swift/doc/source/overview_backing_store.rst

Using Swift as Backing Store for Service Data

Background

This section provides guidance to OpenStack Service developers for how to store your users' data in Swift. An example of this is that a user requests that Nova save a snapshot of a VM. Nova passes the request to Glance, Glance writes the image to a Swift container as a set of objects.

Throughout this section, the following terminology and concepts are used:

• User or end-user. This is a person making a request that will result in an OpenStack Service making a request to Swift.
• Project (also known as Tenant). This is the unit of resource ownership. While data such as snapshot images or block volume backups may be stored as a result of an end-user's request, the reality is that these are project data.
• Service. This is a program or system used by end-users. Specifically, it is any program or system that is capable of receiving end-user's tokens and validating the token with the Keystone Service and has a need to store data in Swift. Glance and Cinder are examples of such Services.
• Service User. This is a Keystone user that has been assigned to a Service. This allows the Service to generate and use its own tokens so that it can interact with other Services as itself.
• Service Project. This is a project (tenant) that is associated with a Service. There may be a single project shared by many Services or there may be a project dedicated to each Service. In this document, the main purpose of the Service Project is to allow the system operator to configure specific roles for each Service User.

Alternate Backing Store Schemes

There are three schemes described here:

• Dedicated Service Account (Single Tenant)

  Your Service has a dedicated Service Project (hence a single dedicated Swift account). Data for all users and projects are stored in this account. Your Service must have a user assigned to it (the Service User). When you have data to store on behalf of one of your users, you use the Service User credentials to get a token for the Service Project and request Swift to store the data in the Service Project.

  With this scheme, data for all users is stored in a single account. This is transparent to your users and since the credentials for the Service User are typically not shared with anyone, your users' cannot access their data by making a request directly to Swift. However, since data belonging to all users is stored in one account, it presents a single point of vulnerably to accidental deletion or a leak of the service-user credentials.

• Multi Project (Multi Tenant)

  Data belonging to a project is stored in the Swift account associated with the project. Users make requests to your Service using a token scoped to a project in the normal way. You can then use this same token to store the user data in the project's Swift account.

  The effect is that data is stored in multiple projects (aka tenants). Hence this scheme has been known as the "multi tenant" scheme.

  With this scheme, access is controlled by Keystone. The users must have a role that allows them to perform the request to your Service. In addition, they must have a role that also allows them to store data in the Swift account. By default, the admin or swiftoperator roles are used for this purpose (specific systems may use other role names). If the user does not have the appropriate roles, when your Service attempts to access Swift, the operation will fail.

  Since you are using the user's token to access the data, it follows that the user can use the same token to access Swift directly -- bypassing your Service. When end-users are browsing containers, they will also see your Service's containers and objects -- and may potentially delete the data. Conversely, there is no single account where all data so leakage of credentials will only affect a single project/tenant.

• Service Prefix Account

  Data belonging to a project is stored in a Swift account associated with the project. This is similar to the Multi Project scheme described above. However, the Swift account is different than the account that users access. Specifically, it has a different account prefix. For example, for the project 1234, the user account is named AUTH_1234. Your Service uses a different account, for example, SERVICE_1234.

  To access the SERVICE_1234 account, you must present two tokens: the user's token is put in the X-Auth-Token header. You present your Service's token in the X-Service-Token header. Swift is configured such that only when both tokens are presented will it allow access. Specifically, the user cannot bypass your Service because they only have their own token. Conversely, your Service can only access the data while it has a copy of the user's token --the Service's token by itself will not grant access.

  The data stored in the Service Prefix Account cannot be seen by end-users. So they cannot delete this data -- they can only access the data if they make a request through your Service. The data is also more secure. To make an unauthorized access, someone would need to compromise both an end-user's and your Service User credentials. Even then, this would only expose one project -- not other projects.

The Service Prefix Account scheme combines features of the Dedicated Service Account and Multi Project schemes. It has the private, dedicated, characteristics of the Dedicated Service Account scheme but does not present a single point of attack. Using the Service Prefix Account scheme is a little more involved than the other schemes, so the rest of this document describes it more detail.

Service Prefix Account Overview

The following diagram shows the flow through the system from the end-user, to your Service and then onto Swift:

client
   \
    \   <request>: <path-specific-to-the-service>
     \  x-auth-token: <user-token>
      \
    SERVICE
       \
        \    PUT: /v1/SERVICE_1234/<container>/<object>
         \   x-auth-token: <user-token>
          \  x-service-token: <service-token>
           \
          Swift

The sequence of events and actions are as follows:

• Request arrives at your Service

• The <user-token> is validated by the keystonemiddleware.auth_token middleware. The user's role(s) are used to determine if the user can perform the request. See overview_auth for technical information on the authentication system.

• As part of this request, your Service needs to access Swift (either to write or read a container or object). In this example, you want to perform a PUT on <container>/<object>.

• In the wsgi environment, the auth_token module will have populated the HTTP_X_SERVICE_CATALOG item. This lists the Swift endpoint and account. This is something such as https://<netloc>/v1/AUTH_1234 where AUTH_ is a prefix and 1234 is the project id.

• The AUTH_ prefix is the default value. However, your system may use a different prefix. To determine the actual prefix, search for the first underscore ('_') character in the account name. If there is no underscore character in the account name, this means there is no prefix.

• Your Service should have a configuration parameter that provides the appropriate prefix to use for storing data in Swift. There is more discussion of this below, but for now assume the prefix is SERVICE_.

• Replace the prefix (AUTH_ in above examples) in the path with SERVICE_, so the full URL to access the object becomes https://<netloc>/v1/SERVICE_1234/<container>/<object>.

• Make the request to Swift, using this URL. In the X-Auth-Token header place a copy of the <user-token>. In the X-Service-Token header, place your Service's token. If you use python-swiftclient you can achieve this by:

  • Putting the URL in the preauthurl parameter
  • Putting the <user-token> in preauthtoken parameter
  • Adding the X-Service-Token to the headers parameter

Using the HTTP_X_SERVICE_CATALOG to get Swift Account Name

The auth_token middleware populates the wsgi environment with information when it validates the user's token. The HTTP_X_SERVICE_CATALOG item is a JSON string containing details of the OpenStack endpoints. For Swift, this also contains the project's Swift account name. Here is an example of a catalog entry for Swift:

"serviceCatalog": [
    ...
    {
        ....
        "type": "object-store",
        "endpoints": [
           ...
           {
               ...
               "publicURL": "https://<netloc>/v1/AUTH_1234",
               "region": "<region-name>"
               ...
           }
           ...
     ...
     }
}

To get the End-user's account:

• Look for an entry with type of object-store
• If there are several regions, there will be several endpoints. Use the appropriate region name and select the publicURL item.
• The Swift account name is the final item in the path ("AUTH_1234" in this example).

Getting a Service Token

A Service Token is no different than any other token and is requested from Keystone using user credentials and project in the usual way. The core requirement is that your Service User has the appropriate role. In practice:

• Your Service must have a user assigned to it (the Service User).

• Your Service has a project assigned to it (the Service Project).

• The Service User must have a role on the Service Project. This role is distinct from any of the normal end-user roles.

• The role used must the role configured in the /etc/swift/proxy-server.conf. This is the <prefix>_service_roles option. In this example, the role is the service role:

  [keystoneauth]
  reseller_prefix = AUTH_, SERVICE_
  SERVICE_service_role = service

The service role should only be granted to OpenStack Services. It should not be granted to users.

Single or multiple Service Prefixes?

Most of the examples used in this document used a single prefix. The prefix, SERVICE was used. By using a single prefix, an operator is allowing all OpenStack Services to share the same account for data associated with a given project. For test systems or deployments well protected on private firewalled networks, this is appropriate.

However, if one Service is compromised, that Service can access data created by another Service. To prevent this, multiple Service Prefixes may be used. This also requires that the operator configure multiple service roles. For example, in a system that has Glance and Cinder, the following Swift configuration could be used:

[keystoneauth]
reseller_prefix = AUTH_, IMAGE_, BLOCK_
IMAGE_service_roles = image_service
BLOCK_service_roles = block_service

The Service User for Glance would be granted the image_service role on its Service Project and the Cinder Service user is granted the block_service role on its project. In this scheme, if the Cinder Service was compromised, it would not be able to access any Glance data.

Container Naming

Since a single Service Prefix is possible, container names should be prefixed with a unique string to prevent name clashes. We suggest you use the service type field (as used in the service catalog). For example, The Glance Service would use "image" as a prefix.