From 448c6414a176831b400ed5a1618fe89a8780968b Mon Sep 17 00:00:00 2001 From: Anthony Young Date: Tue, 14 Feb 2012 12:30:23 -0800 Subject: Update docs to for current keystone-manage usage * Document how to manage users, roles, tenants, services, etc with keystoneclient cli * keystone-manage only does db_sync right now * Fixes bug 931837 * Add docs for import_legacy and export_legacy_catalog Change-Id: I7f55fd607363d0cd4f1646564e430dfb5b12855f --- docs/source/configuration.rst | 322 ++++++++++++++++++------------------ docs/source/configuringservices.rst | 30 ++-- docs/source/man/keystone-manage.rst | 156 +---------------- 3 files changed, 183 insertions(+), 325 deletions(-) diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index 586b66bc..7b975b10 100644 --- a/docs/source/configuration.rst +++ b/docs/source/configuration.rst @@ -94,130 +94,152 @@ primary/public API interface). Both of these run in a single process. Initializing Keystone ===================== -Keystone must be running in order to initialize data within it. This is -because the keystone-manage commands are all used the same REST API that other -OpenStack systems utilize. +keystone-manage is designed to execute commands that cannot be administered +through the normal REST api. At the moment, the following calls are supported: -General keystone-manage options: --------------------------------- +* ``db_sync``: Sync the database. +* ``import_legacy``: Import a legacy (pre-essex) version of the db. +* ``export_legacy_catalog``: Export service catalog from a legacy (pre-essex) db. -* ``--id-only`` : causes ``keystone-manage`` to return only the UUID result - from the API call. -* ``--endpoint`` : allows you to specify the keystone endpoint to communicate - with. The default endpoint is http://localhost:35357/v2.0' +Generally, the following is the first step after a source installation:: -* ``--auth-token`` : provides the authorization token + keystone-manage db_sync -``keystone-manage`` is set up to expect commands in the general form of -``keystone-manage`` ``command`` ``subcommand``, with keyword arguments to -provide additional information to the command. For example, the command -``tenant`` has the subcommand ``create``, which takes the required keyword -``tenant_name``:: +Invoking keystone-manage by itself will give you additional usage information. - keystone-manage tenant create tenant_name=example_tenant +Adding Users, Tenants, and Roles with python-keystoneclient +=========================================================== -Invoking keystone-manage by itself will give you some usage information. +User, tenants, and roles must be administered using admin credentials. +There are two ways to configure python-keystoneclient to use admin +credentials, using the token auth method, or password auth method. -Available keystone-manage commands: +Token Auth Method +----------------- +To use keystone client using token auth, set the following flags -* ``db_sync``: Sync the database. -* ``ec2``: no docs -* ``role``: Role CRUD functions. -* ``service``: Service CRUD functions. -* ``tenant``: Tenant CRUD functions. -* ``token``: Token CRUD functions. -* ``user``: User CRUD functions. +* ``--endpoint SERVIVE_ENDPOINT`` : allows you to specify the keystone endpoint to communicate + with. The default endpoint is http://localhost:35357/v2.0' +* ``--token SERVIVE_TOKEN`` : your administrator service token. + +Password Auth Method +-------------------- + +* ``--username OS_USERNAME`` : allows you to specify the keystone endpoint to communicate + with. For example, http://localhost:35357/v2.0' +* ``--password OS_PASSWORD`` : Your administrator password +* ``--tenant_name OS_TENANT_NAME`` : Name of your tenant +* ``--auth_url OS_AUTH_URL`` : url of your keystone auth server, for example +http://localhost:5000/v2.0' + +Example usage +------------- +``keystone`` is set up to expect commands in the general form of +``keystone`` ``command`` ``argument``, followed by flag-like keyword arguments to +provide additional (often optional) information. For example, the command +``user-list`` and ``tenant-create`` can be invoked as follows:: + + # Using token auth env variables + export SERVICE_ENDPOINT=http://127.0.0.1:5000/v2.0/ + export SERVICE_TOKEN=secrete_token + keystone user-list + keystone tenant-create --name=demo + + # Using token auth flags + keystone --token=secrete --endpoint=http://127.0.0.1:5000/v2.0/ user-list + keystone --token=secrete --endpoint=http://127.0.0.1:5000/v2.0/ tenant-create --name=demo + + # Using user + password + tenant_name env variables + export OS_USERNAME=admin + export OS_PASSWORD=secrete + export OS_TENANT_NAME=admin + keystone user-list + keystone tenant-create --name=demo + + # Using user + password + tenant_name flags + keystone --username=admin --password=secrete --tenant_name=admin user-list + keystone --username=admin --password=secrete --tenant_name=admin tenant-create --name=demo Tenants ------- Tenants are the high level grouping within Keystone that represent groups of users. A tenant is the grouping that owns virtual machines within Nova, or -containers within Swift. A tenant can have zero or more users, Users can be assocaited with more than one tenant, and each tenant - user pairing can have a role associated with it. +containers within Swift. A tenant can have zero or more users, Users can +be associated with more than one tenant, and each tenant - user pairing can +have a role associated with it. -``tenant create`` +``tenant-create`` ^^^^^^^^^^^^^^^^^ keyword arguments -* tenant_name +* name * description (optional, defaults to None) * enabled (optional, defaults to True) example:: - keystone-manage --id-only tenant create tenant_name=admin + keystone tenant-create --name=demo -creates a tenant named "admin". +creates a tenant named "demo". -``tenant delete`` +``tenant-delete`` ^^^^^^^^^^^^^^^^^ -keyword arguments +arguments -* tenant +* tenant_id example:: - keystone-manage tenant delete tenant_id=f2b7b39c860840dfa47d9ee4adffa0b3 + keystone tenant-delete f2b7b39c860840dfa47d9ee4adffa0b3 -``tenant update`` +``tenant-enable`` ^^^^^^^^^^^^^^^^^ -keyword arguments +arguments * tenant_id -* tenant_name (optional, defaults to None) -* description (optional, defaults to None) -* enabled (optional, defaults to True) example:: - keystone-manage tenant update \ - tenant_id=f2b7b39c860840dfa47d9ee4adffa0b3 \ - description="those other guys" \ - name=tog + keystone tenant-enable f2b7b39c860840dfa47d9ee4adffa0b3 -``tenant get`` -^^^^^^^^^^^^^^ +``tenant-disable`` +^^^^^^^^^^^^^^^^^ -keyword arguments +arguments * tenant_id example:: - keystone-manage tenant get \ - tenant_id=523df7c89ce34640996d3d804cbc56f4 + keystone tenant-disable f2b7b39c860840dfa47d9ee4adffa0b3 Users ----- -``user create`` +``user-create`` ^^^^^^^^^^^^^^^ keyword arguments * name -* password +* pass * email -* tenant_id (optional, defaults to None) +* default_tenant (optional, defaults to None) * enabled (optional, defaults to True) example:: - keystone-manage user --id-only create \ - name=admin \ - password=secrete \ - email=admin@example.com - -.. warning:: - Until https://bugs.launchpad.net/keystone/+bug/927873 is resolved, the - keystone-manage cli doesn't allow the setting enabled to be False, making - this command partially broken at the moment. + keystone user-create + --name=admin \ + --pass=secrete \ + --email=admin@example.com -``user delete`` +``user-delete`` ^^^^^^^^^^^^^^^ keyword arguments @@ -226,219 +248,193 @@ keyword arguments example:: - keystone-manage user delete user=f2b7b39c860840dfa47d9ee4adffa0b3 + keystone user-delete f2b7b39c860840dfa47d9ee4adffa0b3 -``user list`` +``user-list`` ^^^^^^^^^^^^^ list users in the system, optionally by a specific tenant (identified by tenant_id) -keyword arguments +arguments * tenant_id (optional, defaults to None) example:: - keystone-manage user list + keystone user-list -``user update_email`` +``user-update-email`` ^^^^^^^^^^^^^^^^^^^^^ -keyword arguments - -* user +arguments +* user_id * email -example:: - keystone-manage user update_email user=03c84b51574841ba9a0d8db7882ac645 email="someone@somewhere.com" +example:: + keystone user-update-email 03c84b51574841ba9a0d8db7882ac645 "someone@somewhere.com" -``user update_enabled`` +``user-enable`` ^^^^^^^^^^^^^^^^^^^^^^^ -keyword arguments +arguments -* user -* enabled (True or False) +* user_id example:: - keystone-manage user update_enabled user=03c84b51574841ba9a0d8db7882ac645 enabled=False - -.. warning:: - Until https://bugs.launchpad.net/keystone/+bug/927873 is resolved, the - keystone-manage cli doesn't allow the setting enabled to False, making - this command broken at the moment. + keystone user-enable 03c84b51574841ba9a0d8db7882ac645 +``user-disable`` +^^^^^^^^^^^^^^^^^^^^^^^ -``user update_password`` -^^^^^^^^^^^^^^^^^^^^^^^^ - -keyword arguments +arguments -* user -* password +* user_id example:: - keystone-manage user update_password user=03c84b51574841ba9a0d8db7882ac645 password=foo + keystone user-disable 03c84b51574841ba9a0d8db7882ac645 -``user update_tenant`` -^^^^^^^^^^^^^^^^^^^^^^ - -keyword arguments -* user -* tenant - -example:: - - keystone-manage user update_tenant user=03c84b51574841ba9a0d8db7882ac645 tenant=b7b8be32c4be4208949f0373c5909e3b - -``user get`` -^^^^^^^^^^^^ +``user-update-password`` +^^^^^^^^^^^^^^^^^^^^^^^^ -keyword arguments +arguments -* user +* user_id +* password example:: - keystone-manage ususer get user=03c84b51574841ba9a0d8db7882ac645 - + keystone user-update-password 03c84b51574841ba9a0d8db7882ac645 foo Roles ----- -``role create`` +``role-create`` ^^^^^^^^^^^^^^^ -keyword arguments +arguments * name exmaple:: - keystone-manage role --id-only create name=Admin + keystone role-create --name=demo -``role delete`` +``role-delete`` ^^^^^^^^^^^^^^^ -keyword arguments +arguments -* role +* role_id exmaple:: - keystone-manage role delete role=19d1d3344873464d819c45f521ff9890 + keystone role-delete 19d1d3344873464d819c45f521ff9890 -``role list`` +``role-list`` ^^^^^^^^^^^^^^^ exmaple:: - keystone-manage role list + keystone role-list -``role get`` +``role-get`` ^^^^^^^^^^^^ -keysword arguments +arguments -* role +* role_id exmaple:: - keystone-manage role get role=19d1d3344873464d819c45f521ff9890 + keystone role-get role=19d1d3344873464d819c45f521ff9890 -``role add_user_role`` +``add-user-role`` ^^^^^^^^^^^^^^^^^^^^^^ -keyword arguments +arguments -* role -* user -* tenant +* role_id +* user_id +* tenant_id example:: - keystone-manage role add_user_role \ - role=3a751f78ef4c412b827540b829e2d7dd \ - user=03c84b51574841ba9a0d8db7882ac645 \ - tenant=20601a7f1d94447daa4dff438cb1c209 + keystone role add-user-role \ + 3a751f78ef4c412b827540b829e2d7dd \ + 03c84b51574841ba9a0d8db7882ac645 \ + 20601a7f1d94447daa4dff438cb1c209 -``role remove_user_role`` +``remove-user-role`` ^^^^^^^^^^^^^^^^^^^^^^^^^ -keyword arguments +arguments -* role -* user -* tenant (optional, defaults to None) - -example:: - - keystone-manage role remove_user_to_tenant \ - role=19d1d3344873464d819c45f521ff9890 \ - user=08741d8ed88242ca88d1f61484a0fe3b \ - tenant=20601a7f1d94447daa4dff438cb1c209 - -``role roles_for_user`` -^^^^^^^^^^^^^^^^^^^^^^^ - -keyword arguments - -* user -* tenant (optional, defaults to None) +* role_id +* user_id +* tenant_id example:: - keystone-manage role roles_for_user user=08741d8ed88242ca88d1f61484a0fe3b + keystone remove-user-role \ + 19d1d3344873464d819c45f521ff9890 \ + 08741d8ed88242ca88d1f61484a0fe3b \ + 20601a7f1d94447daa4dff438cb1c209 Services -------- -``service create`` +``service-create`` ^^^^^^^^^^^^^^^^^^ keyword arguments * name -* service_type +* type * description example:: - keystone-manage service create \ - name=nova \ - service_type=compute \ - description="Nova Compute Service" + keystone service create \ + --name=nova \ + --type=compute \ + --description="Nova Compute Service" -``service list`` +``service-list`` ^^^^^^^^^^^^^^^^ -keyword arguments +arguments + +* service_id example:: - keystone-manage service list + keystone service-list -``service get`` +``service-get`` ^^^^^^^^^^^^^^^ -keyword arguments +arguments + +* service_id example:: - keystone-manage service get id=08741d8ed88242ca88d1f61484a0fe3b + keystone service-get 08741d8ed88242ca88d1f61484a0fe3b -``service delete`` +``service-delete`` ^^^^^^^^^^^^^^^^^^ -keyword arguments +arguments + +* service_id example:: - keystone-manage service delete id=08741d8ed88242ca88d1f61484a0fe3b + keystone service-delete 08741d8ed88242ca88d1f61484a0fe3b diff --git a/docs/source/configuringservices.rst b/docs/source/configuringservices.rst index 3777ce5e..615187ea 100644 --- a/docs/source/configuringservices.rst +++ b/docs/source/configuringservices.rst @@ -80,21 +80,21 @@ for the OpenStack Dashboard to properly function. Here's how we define the services:: - keystone-manage service create name=nova \ - service_type=compute \ - description="Nova Compute Service" - keystone-manage service create name=ec2 \ - service_type=ec2 \ - description="EC2 Compatibility Layer" - keystone-manage service create name=glance \ - service_type=image \ - description="Glance Image Service" - keystone-manage service create name=keystone \ - service_type=identity \ - description="Keystone Identity Service" - keystone-manage service create name=swift \ - service_type=object-store \ - description="Swift Service" + keystone service-create --name=nova \ + --type=compute \ + --description="Nova Compute Service" + keystone service-create --name=ec2 \ + --type=ec2 \ + --description="EC2 Compatibility Layer" + keystone service-create --name=glance \ + --type=image \ + --description="Glance Image Service" + keystone service-create --name=keystone \ + --type=identity \ + --description="Keystone Identity Service" + keystone service-create --name=swift \ + --type=object-store \ + --description="Swift Service" The endpoints for these services are defined in a template, an example of which is in the project as the file ``etc/default_catalog.templates``. diff --git a/docs/source/man/keystone-manage.rst b/docs/source/man/keystone-manage.rst index da5fc941..91f2b9e7 100644 --- a/docs/source/man/keystone-manage.rst +++ b/docs/source/man/keystone-manage.rst @@ -22,162 +22,29 @@ DESCRIPTION =========== keystone-manage is the command line tool that interacts with the keystone -service to initialize and update data within Keystone. Keystone *must* be -opertional for the keystone-manage commands to function correctly. +service to initialize and update data within Keystone. Generally, +keystone-manage is only used for operations that can not be accomplished +with through the keystone REST api, such data import/export and schema +migrations. + USAGE ===== - ``keystone-manage [options] type action [additional args]`` + ``keystone-manage [options] action [additional args]`` General keystone-manage options: -------------------------------- -* ``--id-only`` : causes ``keystone-manage`` to return only the UUID result -from the API call. -* ``--endpoint`` : allows you to specify the keystone endpoint to communicate with. The default endpoint is http://localhost:35357/v2.0' -* ``--auth-token`` : provides the authorization token - -``keystone-manage`` is set up to expect commands in the general form of ``keystone-manage`` ``command`` ``subcommand``, with keyword arguments to provide additional information to the command. For example, the command -``tenant`` has the subcommand ``create``, which takes the required keyword ``tenant_name``:: - - keystone-manage tenant create tenant_name=example_tenant +* ``--help`` : display verbose help output. Invoking keystone-manage by itself will give you some usage information. Available keystone-manage commands: db_sync: Sync the database. - ec2: no docs - role: Role CRUD functions. - service: Service CRUD functions. - tenant: Tenant CRUD functions. - token: Token CRUD functions. - user: User CRUD functions. - -Tenants -------- - -Tenants are the high level grouping within Keystone that represent groups of -users. A tenant is the grouping that owns virtual machines within Nova, or -containers within Swift. A tenant can have zero or more users, Users can be assocaited with more than one tenant, and each tenant - user pairing can have a role associated with it. - -* tenant create - - keyword arguments - * tenant_name - * id (optional) - -example:: - keystone-manage --id-only tenant create tenant_name=admin - -creates a tenant named "admin". - -* tenant delete - - keyword arguments - * tenant_id - -example:: - keystone-manage tenant delete tenant_id=f2b7b39c860840dfa47d9ee4adffa0b3 - -* tenant update - - keyword arguments - * description - * name - * tenant_id - -example:: - keystone-manage tenant update \ - tenant_id=f2b7b39c860840dfa47d9ee4adffa0b3 \ - description="those other guys" \ - name=tog - -Users ------ - -* user create - - keyword arguments - * name - * password - * email - -example:: - keystone-manage user --ks-id-only create \ - name=admin \ - password=secrete \ - email=admin@example.com - -* user delete - - keyword arguments - -* user list - - keyword arguments - -* user update_email - - keyword arguments - -* user update_enabled - - keyword arguments - -* user update_password - - keyword arguments - -* user update_tenant - - keyword arguments - -Roles ------ - -* role create - - keyword arguments - * name - -exmaple:: - keystone-manage role --ks-id-only create name=Admin - -* role add_user_to_tenant - - keyword arguments - * role_id - * user_id - * tenant_id - -example:: - - keystone-manage role add_user_to_tenant \ - role_id=19d1d3344873464d819c45f521ff9890 \ - user_id=08741d8ed88242ca88d1f61484a0fe3b \ - tenant_id=20601a7f1d94447daa4dff438cb1c209 - -* role remove_user_from_tenant - -* role get_user_role_refs - -Services --------- - -* service create - - keyword arguments - * name - * service_type - * description - -example:: - keystone-manage service create \ - name=nova \ - service_type=compute \ - description="Nova Compute Service" + import_legacy: Import a legacy (pre-essex) version of the db. + export_legacy_catalog: Export service catalog from a legacy (pre-essex) db. OPTIONS @@ -212,11 +79,6 @@ Options: syslog (defaults to LOG_USER) --use-syslog Use syslog for logging. --nouse-syslog Use syslog for logging. - --endpoint=ENDPOINT - --auth-token=AUTH_TOKEN - authorization token - --id-only - --noid-only FILES ===== -- cgit