From 420c638d6325d1ccf50eb5fe430c5d255dcbfb94 Mon Sep 17 00:00:00 2001 From: Craig Vyvial Date: Tue, 16 Feb 2016 22:25:24 -0600 Subject: Update readme file to be valid rst and update content Change-Id: Ia407c1a1b885aa8632b54787da8d125a6dd582c0 --- README.rst | 386 ++++++++++++++++++++++++++++++++++++------------------------- 1 file changed, 228 insertions(+), 158 deletions(-) (limited to 'README.rst') diff --git a/README.rst b/README.rst index ca0d328..36a1dda 100644 --- a/README.rst +++ b/README.rst @@ -1,5 +1,5 @@ Python bindings to the OpenStack Trove API -=========================================== +========================================== .. image:: https://img.shields.io/pypi/v/python-troveclient.svg :target: https://pypi.python.org/pypi/python-troveclient/ @@ -18,22 +18,28 @@ command-line tool. You may also want to look at the `OpenStack API documentation`_. .. _OpenStack CLI Guide: http://docs.openstack.org/user-guide/cli.html -.. _OpenStack API documentation: http://docs.openstack.org/api/ +.. _OpenStack API documentation: http://docs.openstack.org/api/quick-start/content/ -The project is hosted on `Launchpad`_, where bugs can be filed. The code is -hosted on `Github`_. Patches must be submitted using `Gerrit`_, *not* Github -pull requests. - -.. _Github: https://github.com/openstack/python-troveclient -.. _Releases: https://github.com/openstack/python-troveclient/releases -.. _Launchpad: https://launchpad.net/python-troveclient -.. _Gerrit: http://docs.openstack.org/infra/manual/developers.html#development-workflow - -This code a fork of `Jacobian's python-cloudservers`__ If you need API support -for the Rackspace API solely or the BSD license, you should use that repository. python-troveclient is licensed under the Apache License like the rest of OpenStack. -__ http://github.com/jacobian/python-cloudservers +* License: Apache License, Version 2.0 +* `PyPi`_ - package installation +* `Online Documentation`_ +* `Blueprints`_ - feature specifications +* `Bugs`_ - issue tracking +* `Git Source`_ +* `Github`_ +* `Specs`_ +* `How to Contribute`_ + +.. _PyPi: https://pypi.python.org/pypi/python-troveclient +.. _Online Documentation: http://docs.openstack.org/developer/python-troveclient +.. _Blueprints: https://blueprints.launchpad.net/python-troveclient +.. _Bugs: https://bugs.launchpad.net/python-troveclient +.. _Git Source: https://git.openstack.org/cgit/openstack/python-troveclient +.. _Github: https://github.com/openstack/python-troveclient +.. _How to Contribute: http://docs.openstack.org/infra/manual/developers.html +.. _Specs: http://specs.openstack.org/openstack/trove-specs/ .. contents:: Contents: :local: @@ -42,7 +48,7 @@ Command-line API ---------------- Installing this package gets you a shell command, ``trove``, that you -can use to interact with any Rackspace compatible API (including OpenStack). +can use to interact with any OpenStack cloud. You'll need to provide your OpenStack username and password. You can do this with the ``--os-username``, ``--os-password`` and ``--os-tenant-name`` @@ -52,11 +58,17 @@ params, but it's easier to just set them as environment variables:: export OS_PASSWORD=yadayada export OS_TENANT_NAME=myproject -You will also need to define the authentication url with ``--os-auth-url`` -and the version of the API with ``--version``. Or set them as an environment -variables as well:: +You will also need to define the authentication url with ``--os-auth-url`` and +the version of the API with ``--os-database-api-version`` (default is version +1.0). Or set them as an environment variables as well:: export OS_AUTH_URL=http://example.com:5000/v2.0/ + export OS_AUTH_URL=1.0 + +If you are using Keystone, you need to set the OS_AUTH_URL to the keystone +endpoint:: + + export OS_AUTH_URL=http://example.com:5000/v2.0/ Since Keystone can return multiple regions in the Service Catalog, you can specify the one you want with ``--os-region-name`` (or @@ -66,161 +78,219 @@ Argument ``--profile`` is available only when the osprofiler lib is installed. You'll find complete documentation on the shell by running ``trove help``:: - usage: trove [--version] [--debug] [--os-username ] - [--os-password ] - [--os-tenant-name ] - [--os-tenant-id ] [--os-auth-url ] - [--os-region-name ] [--service-type ] - [--service-name ] [--bypass-url ] - [--database-service-name ] - [--endpoint-type ] - [--os-database-api-version ] - [--os-cacert ] [--retries ] [--json] - ... + + usage: trove [--version] [--debug] [--os-auth-system ] + [--service-type ] [--service-name ] + [--bypass-url ] + [--database-service-name ] + [--endpoint-type ] + [--os-database-api-version ] + [--retries ] [--json] [--profile HMAC_KEY] [--insecure] + [--os-cacert ] [--os-cert ] + [--os-key ] [--timeout ] + [--os-auth-url OS_AUTH_URL] [--os-domain-id OS_DOMAIN_ID] + [--os-domain-name OS_DOMAIN_NAME] [--os-project-id OS_PROJECT_ID] + [--os-project-name OS_PROJECT_NAME] + [--os-project-domain-id OS_PROJECT_DOMAIN_ID] + [--os-project-domain-name OS_PROJECT_DOMAIN_NAME] + [--os-trust-id OS_TRUST_ID] [--os-user-id OS_USER_ID] + [--os-username OS_USERNAME] + [--os-user-domain-id OS_USER_DOMAIN_ID] + [--os-user-domain-name OS_USER_DOMAIN_NAME] + [--os-password OS_PASSWORD] [--os-tenant-name ] + [--os-tenant-id ] [--os-auth-token OS_AUTH_TOKEN] + [--os-region-name ] + ... Command-line interface to the OpenStack Trove API. Positional arguments: - - backup-copy Creates a backup from another backup. - backup-create Creates a backup of an instance. - backup-delete Deletes a backup. - backup-list Lists available backups. - backup-list-instance Lists available backups for an instance. - backup-show Shows details of a backup. - cluster-create Creates a new cluster. - cluster-delete Deletes a cluster. - cluster-instances Lists all instances of a cluster. - cluster-list Lists all the clusters. - cluster-show Shows details of a cluster. - configuration-attach Attaches a configuration group to an - instance. - configuration-create Creates a configuration group. - configuration-default Shows the default configuration of an - instance. - configuration-delete Deletes a configuration group. - configuration-detach Detaches a configuration group from an - instance. - configuration-instances Lists all instances associated with a - configuration group. - configuration-list Lists all configuration groups. - configuration-parameter-list Lists available parameters for a - configuration group. - configuration-parameter-show Shows details of a configuration parameter. - configuration-patch Patches a configuration group. - configuration-show Shows details of a configuration group. - configuration-update Updates a configuration group. - create Creates a new instance. - database-create Creates a database on an instance. - database-delete Deletes a database from an instance. - database-list Lists available databases on an instance. - datastore-list Lists available datastores. - datastore-show Shows details of a datastore. - datastore-version-list Lists available versions for a datastore. - datastore-version-show Shows details of a datastore version. - delete Deletes an instance. - detach-replica Detaches a replica instance from its - replication source. - flavor-list Lists available flavors. - flavor-show Shows details of a flavor. - limit-list Lists the limits for a tenant. - list Lists all the instances. - metadata-create Creates metadata in the database for - instance . - metadata-delete Deletes metadata for instance . - metadata-edit Replaces metadata value with a new one, this - is non-destructive. - metadata-list Shows all metadata for instance . - metadata-show Shows metadata entry for key and - instance . - metadata-update Updates metadata, this is destructive. - resize-flavor [DEPRECATED] Please use resize-instance - instead. - resize-instance Resizes an instance with a new flavor. - resize-volume Resizes the volume size of an instance. - restart Restarts an instance. - root-enable Enables root for an instance and resets if - already exists. - root-show Gets status if root was ever enabled for an - instance. - secgroup-add-rule Creates a security group rule. - secgroup-delete-rule Deletes a security group rule. - secgroup-list Lists all security groups. - secgroup-list-rules Lists all rules for a security group. - secgroup-show Shows details of a security group. - show Shows details of an instance. - update Updates an instance: Edits name, - configuration, or replica source. - user-create Creates a user on an instance. - user-delete Deletes a user from an instance. - user-grant-access Grants access to a database(s) for a user. - user-list Lists the users for an instance. - user-revoke-access Revokes access to a database for a user. - user-show Shows details of a user of an instance. - user-show-access Shows access details of a user of an - instance. - user-update-attributes Updates a user's attributes on an instance. - bash-completion Prints arguments for bash_completion. - help Displays help about this program or one of - its subcommands. + + backup-copy Creates a backup from another backup. + backup-create Creates a backup of an instance. + backup-delete Deletes a backup. + backup-list Lists available backups. + backup-list-instance Lists available backups for an instance. + backup-show Shows details of a backup. + cluster-create Creates a new cluster. + cluster-delete Deletes a cluster. + cluster-grow Adds more instances to a cluster. + cluster-instances Lists all instances of a cluster. + cluster-list Lists all the clusters. + cluster-show Shows details of a cluster. + cluster-shrink Drops instances from a cluster. + configuration-attach Attaches a configuration group to an + instance. + configuration-create Creates a configuration group. + configuration-default Shows the default configuration of an + instance. + configuration-delete Deletes a configuration group. + configuration-detach Detaches a configuration group from an + instance. + configuration-instances Lists all instances associated with a + configuration group. + configuration-list Lists all configuration groups. + configuration-parameter-list Lists available parameters for a + configuration group. + configuration-parameter-show Shows details of a configuration parameter. + configuration-patch Patches a configuration group. + configuration-show Shows details of a configuration group. + configuration-update Updates a configuration group. + create Creates a new instance. + database-create Creates a database on an instance. + database-delete Deletes a database from an instance. + database-list Lists available databases on an instance. + datastore-list Lists available datastores. + datastore-show Shows details of a datastore. + datastore-version-list Lists available versions for a datastore. + datastore-version-show Shows details of a datastore version. + delete Deletes an instance. + detach-replica Detaches a replica instance from its + replication source. + eject-replica-source Ejects a replica source from its set. + flavor-list Lists available flavors. + flavor-show Shows details of a flavor. + limit-list Lists the limits for a tenant. + list Lists all the instances. + log-disable Instructs Trove guest to stop collecting log + details. + log-discard Instructs Trove guest to discard the + container of the published log. + log-enable Instructs Trove guest to start collecting + log details. + log-list Lists the log files available for instance. + log-publish Instructs Trove guest to publish latest log + entries on instance. + log-save Save log file for instance. + log-show Instructs Trove guest to show details of + log. + log-tail Display log entries for instance. + metadata-create Creates metadata in the database for + instance . + metadata-delete Deletes metadata for instance . + metadata-edit Replaces metadata value with a new one, this + is non-destructive. + metadata-list Shows all metadata for instance . + metadata-show Shows metadata entry for key and + instance . + metadata-update Updates metadata, this is destructive. + promote-to-replica-source Promotes a replica to be the new replica + source of its set. + resize-instance Resizes an instance with a new flavor. + resize-volume Resizes the volume size of an instance. + restart Restarts an instance. + root-disable Disables root for an instance. + root-enable Enables root for an instance and resets if + already exists. + root-show Gets status if root was ever enabled for an + instance or cluster. + secgroup-add-rule Creates a security group rule. + secgroup-delete-rule Deletes a security group rule. + secgroup-list Lists all security groups. + secgroup-list-rules Lists all rules for a security group. + secgroup-show Shows details of a security group. + show Shows details of an instance. + update Updates an instance: Edits name, + configuration, or replica source. + user-create Creates a user on an instance. + user-delete Deletes a user from an instance. + user-grant-access Grants access to a database(s) for a user. + user-list Lists the users for an instance. + user-revoke-access Revokes access to a database for a user. + user-show Shows details of a user of an instance. + user-show-access Shows access details of a user of an + instance. + user-update-attributes Updates a user's attributes on an instance. + bash-completion Prints arguments for bash_completion. + help Displays help about this program or one of + its subcommands. Optional arguments: - --version Show program's version number and exit. - --debug Print debugging output. - --os-username Defaults to env[OS_USERNAME]. - --os-password Defaults to env[OS_PASSWORD]. - --os-tenant-name - Defaults to env[OS_TENANT_NAME]. - --os-tenant-id - Defaults to env[OS_TENANT_ID]. - --os-auth-url Defaults to env[OS_AUTH_URL]. - --os-region-name Defaults to env[OS_REGION_NAME]. - --service-type Defaults to database for most actions. - --service-name Defaults to env[TROVE_SERVICE_NAME]. - --bypass-url Defaults to env[TROVE_BYPASS_URL]. - --database-service-name - Defaults to - env[TROVE_DATABASE_SERVICE_NAME]. - --endpoint-type - Defaults to env[TROVE_ENDPOINT_TYPE] or - publicURL. - --os-database-api-version - Accepts 1, defaults to - env[OS_DATABASE_API_VERSION]. - --os-cacert Specify a CA bundle file to use in verifying - a TLS (https) server certificate. Defaults - to env[OS_CACERT]. - --retries Number of retries. - --json, --os-json-output Output JSON instead of prettyprint. Defaults - to env[OS_JSON_OUTPUT]. - --profile HMAC_KEY HMAC key to use for encrypting context data - for performance profiling of operation. This - key should be the value of HMAC key - configured in osprofiler middleware in - Trove, it is specified in paste configure - file at /etc/trove/api-paste.ini. Without - key the profiling will not be triggered even - if osprofiler is enabled on server side. - Defaults to env[OS_PROFILE_HMACKEY]. + --version Show program's version number and exit. + --debug Print debugging output. + --os-auth-system Defaults to env[OS_AUTH_SYSTEM]. + --service-type Defaults to database for most actions. + --service-name Defaults to env[TROVE_SERVICE_NAME]. + --bypass-url Defaults to env[TROVE_BYPASS_URL]. + --database-service-name + Defaults to + env[TROVE_DATABASE_SERVICE_NAME]. + --endpoint-type + Defaults to env[TROVE_ENDPOINT_TYPE] or + publicURL. + --os-database-api-version + Accepts 1, defaults to + env[OS_DATABASE_API_VERSION]. + --retries Number of retries. + --json, --os-json-output Output JSON instead of prettyprint. Defaults + to env[OS_JSON_OUTPUT]. + --profile HMAC_KEY HMAC key used to encrypt context data when + profiling the performance of an operation. + This key should be set to one of the HMAC + keys configured in Trove (they are found in + api-paste.ini, typically in /etc/trove). + Without the key, profiling will not be + triggered even if it is enabled on the + server side. Defaults to + env[OS_PROFILE_HMACKEY]. + --insecure Explicitly allow client 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-cacert Specify a CA bundle file to use in verifying + a TLS (https) server certificate. Defaults + to env[OS_CACERT]. + --os-cert Defaults to env[OS_CERT]. + --os-key Defaults to env[OS_KEY]. + --timeout Set request timeout (in seconds). + --os-auth-url OS_AUTH_URL Authentication URL + --os-domain-id OS_DOMAIN_ID Domain ID to scope to + --os-domain-name OS_DOMAIN_NAME + Domain name to scope to + --os-project-id OS_PROJECT_ID Project ID to scope to + --os-project-name OS_PROJECT_NAME + Project name to scope to + --os-project-domain-id OS_PROJECT_DOMAIN_ID + Domain ID containing project + --os-project-domain-name OS_PROJECT_DOMAIN_NAME + Domain name containing project + --os-trust-id OS_TRUST_ID Trust ID + --os-user-id OS_USER_ID User ID + --os-username OS_USERNAME, --os-user_name OS_USERNAME + Username + --os-user-domain-id OS_USER_DOMAIN_ID + User's domain id + --os-user-domain-name OS_USER_DOMAIN_NAME + User's domain name + --os-password OS_PASSWORD User's password + --os-tenant-name + Tenant to request authorization on. Defaults + to env[OS_TENANT_NAME]. + --os-tenant-id Tenant to request authorization on. Defaults + to env[OS_TENANT_ID]. + --os-auth-token OS_AUTH_TOKEN Defaults to env[OS_AUTH_TOKEN] + --os-region-name Specify the region to use. Defaults to + env[OS_REGION_NAME]. + + See "trove help COMMAND" for help on a specific command. + Python API ---------- -There's also a complete Python API, but it has not yet been documented. +There's also a complete Python API. Quick-start using keystone:: # use v2.0 auth with http://example.com:5000/v2.0/ >>> from troveclient.v1 import client - >>> nt = client.Client(USERNAME, - PASSWORD, - project_id=TENANT_NAME, - auth_url=AUTH_URL) + >>> nt = client.Client(USERNAME, PASSWORD, TENANT_NAME, AUTH_URL) + >>> nt.datastores.list() + [...] + >>> nt.flavors.list() + [...] >>> nt.instances.list() [...] - -* License: Apache License, Version 2.0 -* Documentation: http://docs.openstack.org/developer/python-troveclient -* Source: http://git.openstack.org/cgit/openstack/python-troveclient -* Bugs: http://bugs.launchpad.net/python-troveclient +* Documentation: http://docs.openstack.org/developer/python-troveclient/ -- cgit v1.2.1