Difference between revisions of "Keystone"

Revision as of 17:22, 19 April 2012

Keystone is the OpenStack identity service, and is the most foundational Python-based component of OpenStack (that is, ignoring RabbitMQ and any SQL databases you might need). There is a server and client part of Keystone. Typically, Keystone is installed on a server, and the client can be installed anywhere (including the server) and is used to interact with Keystone using the OpenStack Identity API, which uses Web-based protocols as a means of client-server communication. The various components of OpenStack can be configured to connect to Keystone using service users so that they in turn can authenticate and authorize requests.

Definitions

This section describes the various concepts and definitions that are part of Keystone.

Tenants

In Keystone, "tenants" represent logical groups of users to which resources are assigned. Virtual machines (Nova) and containers (Swift) are assigned to tenants, not to users directly. Keystone users can be part of more than one tenant, and can have different types of roles defined for each tenant that they're a part of. Think of tenants as a logical way to organize computing and storage resources without assigning them to user accounts directly. Keystone allows you to create and delete tenants, and also enable and disable them.

Roles

A role is a common security concept, where a user is assigned a certain set of privileges. This set of privileges is called a role, has a name, and can be managed independently of the specific user account(s) that are part of the role. Keystone allows you to create and delete roles, add a user to a role for a specific tenant, remove a user from a role for a specific tenant, and of course list all the roles that have been defined.

Users

Keystone is used to define users. Users are accounts for specific individuals, and typically have a password and email associated with them. Keystone allows you to list, create, delete, enable/disable, update email addresses, and change passwords of Users.

Service Users

A service User is a user account created specifically for a component of OpenStack. Service users are typically added to the services tenant with the Admin role. For example, for Nova, you would create a service User nova. Then you would configure Nova to use this Service User to connect to Keystone so that it can authenticate and authorize requests that it receives. See OpenStack Documentation on Configuring Services for more information.

Services

Keystone allows you to define services, which are logical names for parts of OpenStack that provide internal or external capabilities, for things such as identity services, as well as compute and storage services.

Service Endpoints

These are URLs that define where particular services can be accessed. Various parts of OpenStack will query Keystone for service endpoints that they require. Service endpoints can be created and deleted, and you can "get" a handle (URL) to a service that has been defined. You can also define region-specific service endpoints, so that different regions will be serviced differently.

Service Catalog

Taken as a whole, all the service endpoints defined in Keystone are the service catalog, defining all services available to OpenStack.

Quick Start

In Funtoo Linux, Keystone can be merged by typing:

# emerge sys-auth/keystone

Emerging Keystone will also pull in sys-auth/keystone-client as a runtime dependency. keystone-client (which provides the keystone executable) is now maintained in a separate GitHub repository, and connects to Keystone using the OpenStack identity API. Once setting up /etc/keystone/keystone.conf and starting the Keystone service, you will use the keystone command to define tenants, users, roles, services and service endpoints.

Initial Server Configuration

1. Copy /etc/keystone/keystone.conf.sample to /etc/keystone/keystone.conf.
2. Change the config line connection = to read sqlite:////etc/keystone/keystone.db (four slashes after the colon)
3. /etc/init.d/keystone start

Using SQLite as the database back-end like this is not a great idea for production deployment, but for learning about Keystone it works just fine.

Now, initialize the Keystone database:

# keystone-manage db_sync

Client Connection Test

Now, test connecting to Keystone using the Keystone client. First, export these environment variables so that the client knows how to connect to the server:

# <tt>export SERVICE_ENDPOINT=http://127.0.0.1:35357/v2.0/</tt>
# <tt>export SERVICE_TOKEN=ADMIN</tt>

Now, let's try using the keystone client to connect to the server:

# keystone tenant-list
+----+------+---------+
| id | name | enabled |
+----+------+---------+
+----+------+---------+

If you see this output, then keystone used SERVICE_ENDPOINT and SERVICE_TOKEN environmental variables to connect and successfully query Keystone for tenants.

Authentication

Initial Authentication

Once Keystone is running (which we'll cover below,) you'll need to connect to it using the keystone client, called keystone. Initially, you won't have any users, tenants, roles, or anything else set up, and this creates a chicken-and-egg authentication problem. How do you authenticate with Keystone before you have your own user account?

This problem is solved by using the admin_token = ADMIN setting in /etc/keystone/keystone.conf configuration file. This defines a special administration token that is the literal string 'ADMIN', which can be used like a master password to get full remote control of Keystone so that you can configure it. As long as you know the admin_token, you will be able to administrate Keystone from any system that can connect to the service endpoint that Keystone is using.

Let's see how this works in practice. First, we will want to define these environment variables in our shell:

$ export SERVICE_ENDPOINT=http://127.0.0.1:35357/v2.0/
$ export SERVICE_TOKEN=ADMIN

Now, we can execute queries against our Keystone service:

$ keystone tenant-list
+----+------+---------+
| id | name | enabled |
+----+------+---------+
+----+------+---------+

Above, we defined two handy environment variables that the keystone client will use if defined. The first, SERVICE_ENDPOINT, defines the URL to which the keystone client should try to connect. And SERVICE_TOKEN defines our master token, ADMIN, which will grant us full control of Keystone. Then we ran the keystone tenant-list command, at which point our client used both environment variables to connect to the Keystone service, query for all tenants, and successfully returned an empty list, because we haven't created any tenants yet.

User-Based Authentication

Once you have a user named admin created, here is how you will use keystone to connect to the Keystone service. First, we will want to define these environment variables, and it's a good idea to put these in ~/.bashrc or ~/.bash_profile:

$ export SERVICE_ENDPOINT=http://127.0.0.1:35357/v2.0/
$ export OS_AUTH_URL=http://127.0.0.1:35357/v2.0/

Note that we no longer need to define SERVICE_TOKEN, because we're not using it anymore. Now, here's how we run a Keystone-related query:

$ keystone --os_username='admin' --os_password 'mySekr1t' user-list
+----------------------------------+---------+---------------------+-------+
|                id                | enabled |        email        |  name |
+----------------------------------+---------+---------------------+-------+
| 0c4a78317f234333a9a1116be1c7b022 | True    | drobbins@funtoo.org | admin |
+----------------------------------+---------+---------------------+-------+

If you get tired of specifying the two extra command-line arguments above, you can export the environment variables OS_USERNAME and OS_PASSWORD and Keystone will use them if defined. Note that it is not a good idea to store your plain-text password in any file.

Also note that when calling keystone, specify --os_username and --os_password first, before the command you are calling, such as service-create. Then, after service-create, you would specify any options related to service creation, such as --region.

Service Catalog

The service catalog is an important concept for Keystone and OpenStack, because this is where you knit all of the various parts of your OpenStack deployment into a coherent whole that works together. So we are going to explore service catalog configuration in detail. There are two ways to set up a service catalog. One is to use a plain-text configuration file, and the other is to store your service catalog in a SQL back-end by using keystone service-create commands. The latter is recommended, but we will cover both approaches:

Plain-Text Catalog

In older versions of OpenStack, the service catalog was defined using a plain-text catalog file. This method is still supported by OpenStack, but I think it's a bit confusing and using the SQL method documented in the next section is recommended. However, I am including documentation on the plain-text catalog because it shows up in a lot of OpenStack documentation so it's helpful to be familiar with how it works.

To enable the plain-text catalog, you would add the following settings to /etc/keystone/keystone.conf:

[catalog]
driver = keystone.catalog.backends.templated.TemplatedCatalog
template_file = /etc/keystone/service_catalog

You would then define a plain-text catalog at /etc/keystone/service_catalog. An example service catalog is installed at /usr/share/doc/keystone-9999/etc/default_catalog.templates.bz2

Once this is enabled in your configuration, and keystone is restarted, then the service catalog will be defined in Keystone. At this point, it will not be possible to define any services using the SQL method, via keystone service-create.

SQL-based Catalog

The SQL-based service catalog does not require any additional configuration besides ensuring that a SQL backend is configured for Keystone, which is a typical part of the install process.

To create a service endpoint, you would first define the service, using a command like this:

$ keystone service-create --name=nova --type=compute --description="Nova Compute Service"
+-------------+----------------------------------+
|   Property  |              Value               |
+-------------+----------------------------------+
| description | Nova Compute Service             |
| id          | c3600f9e26be495f9b0ed1328c33a436 |
| name        | nova                             |
| type        | compute                          |
+-------------+----------------------------------+

Now that the service is defined, we can define an endpoint for this service, for region RegionOne:

 $ keystone endpoint-create --region RegionOne --service_id c3600f9e26be495f9b0ed1328c33a436 \
 --publicurl 'http://127.0.0.1:$(compute_port)s/v1.1/$(tenant_id)s' \
 --adminurl 'http://127.0.0.1:$(compute_port)s/v1.1/$(tenant_id)s' \
 --internalurl 'http://127.0.0.1:$(compute_port)s/v1.1/$(tenant_id)s'

Resources

OpenStack Identity Service:

• http://docs.openstack.org/api/openstack-identity-service/2.0/content/
• https://github.com/openstack/identity-api