Secrets Configuration

A secret is a mechanism used by automated deployment tools to store and transfer sensitive data to a host and make it available inside a container running on that host. Secrets are created in the controller application and then shared with the hosts that need them when the containers are deployed.

For Solace PubSub+ software event brokers, a secrets directory is created in the host environment, which is then mounted as a volume in the container consuming the secret. When the container is started for the first time, configuration keys indicate where to look for the secret, and the initial configuration of the software event broker instance is set accordingly.

In this section, we will show you how to:

  • create a secrets directory and place a server certificate and the file containing the username password in it
  • create a software event broker Docker container using the secret configurations

Assumptions

  • You know how to set up a software event broker Docker container. For more information, see Docker Images.
  • The example we show below uses a software event broker Docker container with a UID of 0, that is, the root user. For a non-zero UID, refer to Secrets Configuration for a Non-zero UID.

Configuring Secrets

To configure secrets for use with a software event broker Docker container, do the following:

Step 1: Create a Secrets Directory

Step 2: Place Files in the Secrets Directory

Step 3: Create the Software Event Broker Docker Container

Step 4: Verify Using Solace CLI

Step 1: Create a Secrets Directory

Create a secrets directory in the host.

For example:

$ mkdir -p <local-pathname>/secrets

Where:

<local-pathname> is the path where the secrets directory will be located in the host.

Step 2: Place Files in the Secrets Directory

Place the server certificate and file containing the username password in the secrets directory.

For example:

$scp <username>@<host>:<remote-pathname>/<certificate-file> <local-pathname>/secrets/
$scp <username>@<host>:<remote-pathname>/<password-file> <local-pathname>/secrets/

Where:

<username> is the username, if a username is required, to access the remote certificate file.

<host> is the address of the server where the remote certificate file is stored.

<remote-pathname> is the path to the location of the secrets directory from the server root directory.

<certificate-file> is the filename to use for the server certificate on the event broker.

<password-file> is the file containing the plain-text password for the software event broker username.

Step 3: Create the Software Event Broker Docker Container

Create the software event broker Docker container with secret configurations.

The following example shows how to configure software event broker secrets using the docker-create shell script and is suitable for a test deployment. For a production deployment, there are use-case dependent factors that will impact the option and configuration key settings in the docker create command. For more information, see Docker Create Options Configuration.

>sudo tee /root/docker-create <<-EOF
#!/bin/bash
sudo docker create \
--network=host \
--uts=host \
--shm-size=2g \
--ulimit core=-1 \
--ulimit memlock=-1 \
--ulimit nofile=2448:42192 \
--env 'username_admin_globalaccesslevel=admin' \
--env 'username_admin_passwordfilepath=<password-file>' \
--env 'tls_servercertificate_filepath=<certificate-file>' \
--volume /<local-pathname>/secrets:/run/secrets \
--name=solace solace-app:<version-edition> \
EOF

In this example:

  • The --volume /<local-pathname>/secrets:/run/secrets option mounts the secrets directory to the specified location inside the container.
  • The admin Solace CLI user and the path to the secrets directory containing the username password file are defined at container creation through username_admin_globalaccesslevel and username_admin_passwordfilepath=<password-file> configuration keys.
  • The tls_servercertificate_filepath configuration key defines the path to the secrets directory where the server certificate is placed. If the TLS server certificate contained in the file is encrypted, then the path to the file containing the passphrase must be provided through the tls_servercertificate_passphrasefilepath configuration key. For more information, see Configuration Key Usage.

In the above docker create command:

solace-app is the repository name.

<version-edition> is the software event broker Docker Container version. The version-edition is dependent on the VM Docker package you have obtained. You can use the docker images command to check the version-edition.

:   When reloading a container to the default configuration, the secrets and keys must be present when the reload happens, or else, the initial configuration previously configured by secret will not be present in the new initial configuration.

Step 4: Verify Using Solace CLI

Once your container is up and running, verify the software event broker secrets configuration in the Solace CLI:

solace> show ssl server-certificate 
Filename:                    servercert.pem
Configured at:               Oct 11 2017 1933:42 UTC