tempest/doc/source/library/credential_providers.rst

Credential Providers

These library interfaces are used to deal with allocating credentials on demand either dynamically by calling Keystone to allocate new credentials, or from a list of preprovisioned credentials. These 2 modules are implementations of the same abstract credential providers class and can be used interchangeably. However, each implementation has some additional parameters that are used to influence the behavior of the modules. The API reference at the bottom of this doc shows the interface definitions for both modules, however, that may be a bit opaque. You can see some examples of how to leverage this interface below.

Initialization Example

This example is from Tempest itself (from tempest/common/credentials_factory.py just modified slightly) and is how it initializes the credential provider based on config:

from tempest import config
from tempest.lib.common import dynamic_creds
from tempest.lib.common import preprov_creds

CONF = config.CONF

def get_credentials_provider(name, network_resources=None,
                             force_tenant_isolation=False,
                             identity_version=None):
    # If a test requires a new account to work, it can have it via forcing
    # dynamic credentials. A new account will be produced only for that test.
    # In case admin credentials are not available for the account creation,
    # the test should be skipped else it will fail.
    identity_version = identity_version or CONF.identity.auth_version
    if CONF.auth.use_dynamic_credentials or force_tenant_isolation:
        admin_creds = get_configured_admin_credentials(
            fill_in=True, identity_version=identity_version)
        return dynamic_creds.DynamicCredentialProvider(
            name=name,
            network_resources=network_resources,
            identity_version=identity_version,
            admin_creds=admin_creds,
            identity_admin_domain_scope=CONF.identity.admin_domain_scope,
            identity_admin_role=CONF.identity.admin_role,
            extra_roles=CONF.auth.tempest_roles,
            neutron_available=CONF.service_available.neutron,
            project_network_cidr=CONF.network.project_network_cidr,
            project_network_mask_bits=CONF.network.project_network_mask_bits,
            public_network_id=CONF.network.public_network_id,
            create_networks=(CONF.auth.create_isolated_networks and not
                             CONF.network.shared_physical_network),
            resource_prefix='tempest',
            credentials_domain=CONF.auth.default_credentials_domain_name,
            admin_role=CONF.identity.admin_role,
            identity_uri=CONF.identity.uri_v3,
            identity_admin_endpoint_type=CONF.identity.v3_endpoint_type)
    else:
        if CONF.auth.test_accounts_file:
            # Most params are not relevant for pre-created accounts
            return preprov_creds.PreProvisionedCredentialProvider(
                name=name, identity_version=identity_version,
                accounts_lock_dir=lockutils.get_lock_path(CONF),
                test_accounts_file=CONF.auth.test_accounts_file,
                object_storage_operator_role=CONF.object_storage.operator_role,
                object_storage_reseller_admin_role=reseller_admin_role,
                credentials_domain=CONF.auth.default_credentials_domain_name,
                admin_role=CONF.identity.admin_role,
                identity_uri=CONF.identity.uri_v3,
                identity_admin_endpoint_type=CONF.identity.v3_endpoint_type)
        else:
            raise exceptions.InvalidConfiguration(
                'A valid credential provider is needed')

This function just returns an initialized credential provider class based on the config file. The consumer of this function treats the output as the same regardless of whether it's a dynamic or preprovisioned provider object.

Dealing with Credentials

Once you have a credential provider object created the access patterns for allocating and removing credentials are the same across both the dynamic and preprovisioned credentials. These are defined in the abstract CredentialProvider class. At a high level, the credentials provider enables you to get 3 basic types of credentials at once (per object): primary, alt, and admin. You're also able to allocate a credential by role. These credentials are tracked by the provider object and delete must be called manually, otherwise, the created resources will not be deleted (or returned to the pool in the case of preprovisioned creds).

Examples

Continuing from the example above, to allocate credentials by the 3 basic types you can do the following:

provider = get_credentials_provider('my_tests')
primary_creds = provider.get_primary_creds()
alt_creds = provider.get_alt_creds()
admin_creds = provider.get_admin_creds()
# Make sure to delete the credentials when you're finished
provider.clear_creds()

To create and interact with credentials by role you can do the following:

provider = get_credentials_provider('my_tests')
my_role_creds = provider.get_creds_by_role({'roles': ['my_role']})
# provider.clear_creds() will clear all creds including those allocated by
# role
provider.clear_creds()

When multiple roles are specified a set of creds with all the roles assigned will be allocated:

provider = get_credentials_provider('my_tests')
my_role_creds = provider.get_creds_by_role({'roles': ['my_role',
                                                      'my_other_role']})
# provider.clear_creds() will clear all creds including those allocated by
# role
provider.clear_creds()

If you need multiple sets of credentials with the same roles you can also do this by leveraging the force_new kwarg:

provider = get_credentials_provider('my_tests')
my_role_creds = provider.get_creds_by_role({'roles': ['my_role']})
my_role_other_creds = provider.get_creds_by_role({'roles': ['my_role']},
                                                 force_new=True)
# provider.clear_creds() will clear all creds including those allocated by
# role
provider.clear_creds()

API Reference

The dynamic credentials module

tempest.lib.common.dynamic_creds

The pre-provisioned credentials module

tempest.lib.common.preprov_creds