Chapter 3. Installing Barbican

Barbican is not enabled by default in Red Hat OpenStack Platform. This procedure describes how you can deploy barbican in an existing OpenStack deployment. Barbican runs as a containerized service, so this procedure also describes how to prepare and upload the new container images:

Note

This procedure configures barbican to use the simple_crypto backend. Additional backends are available, such as PKCS11 and DogTag, however they are not supported in this release.

  1. On the undercloud node, create an environment file for barbican. This will instruct director to install barbican (when its included in openstack overcloud deploy […​]) 

    $ cat /home/stack/configure-barbican.yaml
	parameter_defaults:
	  BarbicanSimpleCryptoGlobalDefault: true
    • BarbicanSimpleCryptoGlobalDefault - Sets this plugin as the global default plugin.

    • Further options are also configurable:

      • BarbicanPassword - Sets a password for the barbican service account.
      • BarbicanWorkers - Sets the number of workers for barbican::wsgi::apache. Uses '%{::processorcount}' by default.
      • BarbicanDebug - Enables debugging.
      • BarbicanPolicies - Defines policies to configure for barbican. Uses a hash value, for example: { barbican-context_is_admin: { key: context_is_admin, value: 'role:admin' } }. This entry is then added to /etc/barbican/policy.json. Policies are described in detail in a later section.
      • BarbicanSimpleCryptoKek - The Key Encryption Key (KEK) is generated by director, if none is specified.

  2. This step prepares new container images for barbican. You will need to include the configure-barbican.yaml and all the relevant template files. Change the following example to suit your deployment: 

    $ openstack overcloud container image prepare \
	--namespace example.lab.local:5000/rhosp15-rhel8 \
	--tag latest \
	--push-destination 192.168.100.1:8787 \
	--output-images-file ~/container-images-with-barbican.yaml \
	-e /home/stack/virt/config_lvm.yaml \
	-e /usr/share/openstack-tripleo-heat-templates/environments/network-isolation.yaml \
	-e /home/stack/virt/network/network-environment.yaml \
	-e /home/stack/virt/hostnames.yml \
	-e /home/stack/virt/nodes_data.yaml \
	-e /home/stack/virt/extra_templates.yaml \
	-e /home/stack/virt/docker-images.yaml \
	-e /usr/share/openstack-tripleo-heat-templates/environments/services/barbican.yaml \
	-e /usr/share/openstack-tripleo-heat-templates/environments/barbican-backend-simple-crypto.yaml \
	-e /home/stack/configure-barbican.yaml

  3. Upload the new container images to the undercloud registry: 

    $ openstack overcloud container image upload --debug --config-file container-images-with-barbican.yaml

  4. Prepare the new environment file: 

    $ openstack overcloud container image prepare \
  --tag latest \
  --namespace 192.168.100.1:8787/rhosp15-rhel8 \
  --output-env-file ~/container-parameters-with-barbican.yaml \
  -e /home/stack/virt/config_lvm.yaml \
  -e /usr/share/openstack-tripleo-heat-templates/environments/network-isolation.yaml \
  -e /home/stack/virt/network/network-environment.yaml \
  -e /home/stack/virt/hostnames.yml \
  -e /home/stack/virt/nodes_data.yaml \
  -e /home/stack/virt/extra_templates.yaml \
  -e /home/stack/virt/docker-images.yaml \
  -e /usr/share/openstack-tripleo-heat-templates/environments/services/barbican.yaml \
  -e /usr/share/openstack-tripleo-heat-templates/environments/barbican-backend-simple-crypto.yaml \
  -e /home/stack/configure-barbican.yaml

  5. To apply these changes to your deployment: update the overcloud and specify all the heat template files that you used in your previous openstack overcloud deploy […​]. For example: 

    $ openstack overcloud deploy \
    --timeout 100 \
    --templates /usr/share/openstack-tripleo-heat-templates \
    --stack overcloud \
    --libvirt-type kvm \
    --ntp-server clock.redhat.com \
    -e /home/stack/virt/config_lvm.yaml \
    -e /usr/share/openstack-tripleo-heat-templates/environments/network-isolation.yaml \
    -e /home/stack/virt/network/network-environment.yaml \
    -e /home/stack/virt/hostnames.yml \
    -e /home/stack/virt/nodes_data.yaml \
    -e /home/stack/virt/extra_templates.yaml \
    -e /home/stack/container-parameters-with-barbican.yaml \
    -e /usr/share/openstack-tripleo-heat-templates/environments/services/barbican.yaml \
    -e /usr/share/openstack-tripleo-heat-templates/environments/barbican-backend-simple-crypto.yaml \
    -e /home/stack/configure-barbican.yaml \
    --log-file overcloud_deployment_38.log

3.1. Add users to the creator role on Overcloud

Users must be members of the creator role in order to create and edit barbican secrets. For example, they require this role to create encrypted volumes that store their secret in barbican.

  1. Create a new role called creator: 

    $ openstack role create creator
+-----------+----------------------------------+
| Field     | Value                            |
+-----------+----------------------------------+
| domain_id | None                             |
| id        | 4e9c560c6f104608948450fbf316f9d7 |
| name      | creator                          |
+-----------+----------------------------------+

  2. Retrieve the id of the creator role: 

    openstack role show creator
+-----------+----------------------------------+
| Field     | Value                            |
+-----------+----------------------------------+
| domain_id | None                             |
| id        | 4e9c560c6f104608948450fbf316f9d7 |
| name      | creator                          |
+-----------+----------------------------------+

  3. Assign a user to the creator role and specify the relevant project. In this example, a user named user1 in the project_a project is added to the creator role: 

    openstack role add --user user1 --project project_a 4e9c560c6f104608948450fbf316f9d7

3.1.1. Test barbican functionality

This section describes how to test that barbican is working correctly.

  1. Create a test secret. For example: 

    $ openstack secret store --name testSecret --payload 'TestPayload'
+---------------+------------------------------------------------------------------------------------+
| Field         | Value                                                                              |
+---------------+------------------------------------------------------------------------------------+
| Secret href   | https://192.168.123.163/key-manager/v1/secrets/4cc5ffe0-eea2-449d-9e64-b664d574be53 |
| Name          | testSecret                                                                         |
| Created       | None                                                                               |
| Status        | None                                                                               |
| Content types | None                                                                               |
| Algorithm     | aes                                                                                |
| Bit length    | 256                                                                                |
| Secret type   | opaque                                                                             |
| Mode          | cbc                                                                                |
| Expiration    | None                                                                               |
+---------------+------------------------------------------------------------------------------------+

  2. Retrieve the payload for the secret you just created: 

    openstack secret get https://192.168.123.163/key-manager/v1/secrets/4cc5ffe0-eea2-449d-9e64-b664d574be53 --payload
+---------+-------------+
| Field   | Value       |
+---------+-------------+
| Payload | TestPayload |
+---------+-------------+

3.2. Understanding policies

Barbican uses policies to determine which users are allowed to perform actions against the secrets, such as adding or deleting keys. To implement these controls, keystone project roles (such as creator you created earlier) are mapped to barbican internal permissions. As a result, users assigned to those project roles receive the corresponding barbican permissions.

3.2.1. Viewing the default policy

The default policy is defined in code and typically does not require any amendments. You can view the default policy by generating it from the barbican source code:

  1. Perform the following steps on a non-production system, because additional components may be downloaded and installed. This example switches to the queens branch, so you must adapt this if using a different version. 

    git clone https://github.com/openstack/barbican
cd /home/stack/barbican
git checkout origin/stable/queens
tox -e genpolicy

    This generates a policy file within a subdirectory that contains the default settings: etc/barbican/policy.yaml.sample. Note that this path refers to a subdirectory within the repository, not your system’s /etc directory. The contents of this file are explained in the following step.

  2. The policy.yaml.sample file you generated describes the policies used by barbican. The policy is implemented by four different roles that define how a user interacts with secrets and secret metadata. A user receives these permissions by being assigned to a particular role:

    • admin - Can delete, create/edit, and read secrets.
    • creator - Can create/edit, and read secrets. Can not delete secrets.
    • observer - Can only read data.

    • audit - Can only read metadata. Can not read secrets.

      For example, the following entries list the admin, observer, and creator keystone roles for each project. On the right, notice that they are assigned the role:admin, role:observer, and role:creator permissions: 

      #
#"admin": "role:admin"

#
#"observer": "role:observer"

#
#"creator": "role:creator"

      These roles can also be grouped together by barbican. For example, rules that specify admin_or_creator can apply to members of either rule:admin or rule:creator.

  3. Further down in the file, there are secret:put and secret:delete actions. To their right, notice which roles have permissions to execute these actions. In the following example, secret:delete means that only admin and creator role members can delete secret entries. In addition, the rule states that users in the admin or creator role for that project can delete a secret in that project. The project match is defined by the secret_project_match rule, which is also defined in the policy. 

    secret:delete": "rule:admin_or_creator and rule:secret_project_match"