Configuring Secrets

A secret is a mechanism for transferring sensitive data to a host so that it can be made it available inside a container running on that host. In production environments, creating and populating the secrets location are typically done by an automation tool. Secrets are created in the controller application and then shared with the hosts that need them when the containers are deployed. For example, a tool such as Kubernetes would transfer the secret to a temporary filesystem on the host (so that the secret is never written to disk) and then mount that location in the container.

You use configuration keys to specify information such as the path for the secret; on startup, the software event broker reads the secret and sets the configuration accordingly.

In this section, we 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 container using the secret configurations

The example below creates a container with a UID of 0 (that is, the root user). For a non-zero UID, do the following in addition to the steps listed:

  • Specify the UID for the container by adding the --user parameter to the create command in Step 3.
  • Use the chown command on the Linux host to change the owner of the container's secrets directory to same user that created the container, for example:

    chown --recursive <container uid>:<container gid> /<local-pathname>/secrets

  • Use the chmod 500 command on the Linux host to grant read and execute permission to the secrets directory, and to restrict permission to other users in the group associated with the directory.

    chmod --recursive 500 /<local-pathname>/secrets

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 Container

Create the software event broker container with secret configurations.

The following example is suitable for a test deployment. It shows how to configure a secrets directory using a shell script that runs docker create. The options for podman create are very similar.

For a production deployment, there are use-case dependent factors that impact the settings for creating the container. For more information, see Configuration Keys and Setting Scaling Parameters Using Configuration Keys.

>sudo tee /root/docker-create <<-EOF
#!/bin/bash
sudo docker create \
--network=host \
--uts=host \
--shm-size=1g \
--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 Initializing a Software Event Broker Container.

In the above docker create command:

  • solace-app is the repository name.
  • <version-edition> is the software event broker version. The version-edition is dependent on the 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, otherwise the initial configuration previously configured by the 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 using the Solace CLI:

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