diff options
Diffstat (limited to 'README.rst')
| -rw-r--r-- | README.rst | 207 |
1 files changed, 23 insertions, 184 deletions
@@ -1,18 +1,29 @@ Python bindings to the OpenStack Identity API (Keystone) ======================================================== -This is a client for the OpenStack Identity API, implemented by Keystone. -There's a Python API (the ``keystoneclient`` module), and a command-line script -(``keystone``). - -Development takes place via the usual OpenStack processes as outlined in the -`developer guide <http://docs.openstack.org/infra/manual/developers.html>`_. The master -repository is in `Git <http://git.openstack.org/cgit/openstack/python-keystoneclient>`_. - -This code is a fork of Rackspace's python-novaclient which is in turn a fork of -`Jacobian's python-cloudservers -<http://github.com/jacobian/python-cloudservers>`_. ``python-keystoneclient`` -is licensed under the Apache License like the rest of OpenStack. +This is a client for the OpenStack Identity API, implemented by the Keystone +team; it contains a Python API (the ``keystoneclient`` module) for +OpenStack's Identity Service. For command line interface support, use +`OpenStackClient`_. + +* `PyPi`_ - package installation +* `Online Documentation`_ +* `Launchpad project`_ - release management +* `Blueprints`_ - feature specifications +* `Bugs`_ - issue tracking +* `Source`_ +* `Specs`_ +* `How to Contribute`_ + +.. _PyPi: https://pypi.python.org/pypi/python-keystoneclient +.. _Online Documentation: http://docs.openstack.org/developer/python-keystoneclient +.. _Launchpad project: https://launchpad.net/python-keystoneclient +.. _Blueprints: https://blueprints.launchpad.net/python-keystoneclient +.. _Bugs: https://bugs.launchpad.net/python-keystoneclient +.. _Source: https://git.openstack.org/cgit/openstack/python-keystoneclient +.. _OpenStackClient: https://pypi.python.org/pypi/python-openstackclient +.. _How to Contribute: http://docs.openstack.org/infra/manual/developers.html +.. _Specs: http://specs.openstack.org/openstack/keystone-specs/ .. contents:: Contents: :local: @@ -28,175 +39,3 @@ By way of a quick-start:: >>> keystone.tenants.list() >>> tenant = keystone.tenants.create(tenant_name="test", description="My new tenant!", enabled=True) >>> tenant.delete() - - -Command-line API ----------------- - -Installing this package gets you a shell command, ``keystone``, that you can -use to interact with OpenStack's Identity API. - -You'll need to provide your OpenStack tenant, username and password. You can do -this with the ``--os-tenant-name``, ``--os-username`` and ``--os-password`` -params, but it's easier to just set them as environment variables:: - - export OS_TENANT_NAME=project - export OS_USERNAME=user - export OS_PASSWORD=pass - -You will also need to define the authentication url with ``--os-auth-url`` and -the version of the API with ``--os-identity-api-version``. Or set them as an -environment variables as well:: - - export OS_AUTH_URL=http://example.com:5000/v2.0 - export OS_IDENTITY_API_VERSION=2.0 - -Alternatively, to bypass username/password authentication, you can provide a -pre-established token. In Keystone, this approach is necessary to bootstrap the -service with an administrative user, tenant & role (to do so, provide the -client with the value of your ``admin_token`` defined in ``keystone.conf`` in -addition to the URL of your admin API deployment, typically on port 35357):: - - export OS_SERVICE_TOKEN=thequickbrownfox-jumpsover-thelazydog - export OS_SERVICE_ENDPOINT=http://example.com:35357/v2.0 - -Since the Identity service can return multiple regions in the service catalog, -you can specify the one you want with ``--os-region-name`` (or ``export -OS_REGION_NAME``):: - - export OS_REGION_NAME=north - -.. WARNING:: - - If a region is not specified and multiple regions are returned by the - Identity service, the client may not access the same region consistently. - -If you need to connect to a server that is TLS-enabled (the auth URL begins -with 'https') and it uses a certificate from a private CA or a self-signed -certificate you will need to specify the path to an appropriate CA certificate -to use to validate the server certificate with ``--os-cacert`` or an -environment variable:: - - export OS_CACERT=/etc/ssl/my-root-cert.pem - -Certificate verification can be turned off using ``--insecure``. This should -be used with caution. - -You'll find complete documentation on the shell by running ``keystone help``:: - - usage: keystone [--version] [--timeout <seconds>] - [--os-username <auth-user-name>] - [--os-password <auth-password>] - [--os-tenant-name <auth-tenant-name>] - [--os-tenant-id <tenant-id>] [--os-auth-url <auth-url>] - [--os-region-name <region-name>] - [--os-identity-api-version <identity-api-version>] - [--os-token <service-token>] - [--os-endpoint <service-endpoint>] - [--os-cacert <ca-certificate>] [--insecure] - [--os-cert <certificate>] [--os-key <key>] [--os-cache] - [--force-new-token] [--stale-duration <seconds>] - <subcommand> ... - - Command-line interface to the OpenStack Identity API. - - Positional arguments: - <subcommand> - catalog - ec2-credentials-create - Create EC2-compatible credentials for user per tenant - ec2-credentials-delete - Delete EC2-compatible credentials - ec2-credentials-get - Display EC2-compatible credentials - ec2-credentials-list - List EC2-compatible credentials for a user - endpoint-create Create a new endpoint associated with a service - endpoint-delete Delete a service endpoint - endpoint-get - endpoint-list List configured service endpoints - password-update Update own password - role-create Create new role - role-delete Delete role - role-get Display role details - role-list List all roles - service-create Add service to Service Catalog - service-delete Delete service from Service Catalog - service-get Display service from Service Catalog - service-list List all services in Service Catalog - tenant-create Create new tenant - tenant-delete Delete tenant - tenant-get Display tenant details - tenant-list List all tenants - tenant-update Update tenant name, description, enabled status - token-get - user-create Create new user - user-delete Delete user - user-get Display user details. - user-list List users - user-password-update - Update user password - user-role-add Add role to user - user-role-list List roles granted to a user - user-role-remove Remove role from user - user-update Update user's name, email, and enabled status - discover Discover Keystone servers, supported API versions and - extensions. - bootstrap Grants a new role to a new user on a new tenant, after - creating each. - bash-completion Prints all of the commands and options to stdout. - help Display help about this program or one of its - subcommands. - - Optional arguments: - --version Shows the client version and exits - --timeout <seconds> Set request timeout (in seconds) - --os-username <auth-user-name> - Name used for authentication with the OpenStack - Identity service. Defaults to env[OS_USERNAME] - --os-password <auth-password> - Password used for authentication with the OpenStack - Identity service. Defaults to env[OS_PASSWORD] - --os-tenant-name <auth-tenant-name> - Tenant to request authorization on. Defaults to - env[OS_TENANT_NAME] - --os-tenant-id <tenant-id> - Tenant to request authorization on. Defaults to - env[OS_TENANT_ID] - --os-auth-url <auth-url> - Specify the Identity endpoint to use for - authentication. Defaults to env[OS_AUTH_URL] - --os-region-name <region-name> - Defaults to env[OS_REGION_NAME] - --os-identity-api-version <identity-api-version> - Defaults to env[OS_IDENTITY_API_VERSION] or 2.0 - --os-token <service-token> - Specify an existing token to use instead of retrieving - one via authentication (e.g. with username & - password). Defaults to env[OS_SERVICE_TOKEN] - --os-endpoint <service-endpoint> - Specify an endpoint to use instead of retrieving one - from the service catalog (via authentication). - Defaults to env[OS_SERVICE_ENDPOINT] - --os-cacert <ca-certificate> - Specify a CA bundle file to use in verifying a TLS - (https) server certificate. Defaults to env[OS_CACERT] - --insecure Explicitly allow keystoneclient to perform "insecure" - TLS (https) requests. The server's certificate will - not be verified against any certificate authorities. - This option should be used with caution. - --os-cert <certificate> - Defaults to env[OS_CERT] - --os-key <key> Defaults to env[OS_KEY] - --os-cache Use the auth token cache. Defaults to env[OS_CACHE] - --force-new-token If the keyring is available and in use, token will - always be stored and fetched from the keyring until - the token has expired. Use this option to request a - new token and replace the existing one in the keyring. - --stale-duration <seconds> - Stale duration (in seconds) used to determine whether - a token has expired when retrieving it from keyring. - This is useful in mitigating process or network - delays. Default is 30 seconds. - - See "keystone help COMMAND" for help on a specific command. |