DC/OS Secrets

Portworx can integrate with DC/OS Secrets to store your encryption keys/secrets, credentials, and auth tokens. This guide will help you configure Portworx to connect to DC/OS Secrets. DC/OS Secrets can then be used to store Portworx secrets for Volume Encryption and Cloud Credentials.

Secrets is an DC/OS Enterprise only feature
Note: Supported from Portworx Enterprise 1.4 onwards

Configuring DC/OS Secrets with Portworx

Configuring permissions for Secrets

To access secrets, Portworx needs credentials of a user. This user should have permissions to access the secrets under a base secrets path. For instance, you can grant permissions to a user to access secrets under /pwx/secrets base path, using DC/OS enterprise cli:

dcos security org users grant <username> dcos:secrets:default:/pwx/secrets/* full

Enabling Secrets in the Portworx package

During installation or when updating an existing Portworx framework, enable the feature from Secrets section.


The base path is the secrets path under which Portworx will read/write secrets. If not specified, Portworx will look for secrets at the top level.

The dcos username secret and dcos password secret are the paths to secrets, where Portworx will look for credentials of the user to access the secrets. This user should have full access to secrets under the base path.

If you want Portworx framework to access the username and password secrets path, the path should have prefix same as Portworx service name (default service name is portworx). Refer DC/OS docs to know more.

Key generation with DC/OS

The following sections describe the key generation process with Portworx and DC/OS which can be used for encrypting volumes. For more information about encrypted volumes, click here.

Setting cluster wide secret key

Create a secret in DC/OS using the enterprise cli:

dcos security secrets create --value=<secret-value> pwx/secrets/cluster-wide-secret-key

For more details on ways to create Secrets in DC/OS refer DC/OS documentation

A cluster wide secret key is a common key that can be used to encrypt all your volumes. You can set the cluster secret key using the following command:

/opt/pwx/bin/pxctl secrets set-cluster-key \
  --secret pwx/secrets/cluster-wide-secret-key

This command needs to be run just once for the cluster. If you have added the cluster secret through the config.json, the above command will overwrite it. Even on subsequent Portworx restarts, the cluster secret key in config.json will be ignored for the one set through the CLI.

(Optional) Authenticating with DC/OS Secrets using Portworx CLI

If you do not wish to pass the DC/OS credentials through the framework, you can authenticate Portworx with DC/OS Secrets using the Portworx CLI. Run the following command:

/opt/pwx/bin/pxctl secrets dcos login \
  --username <dcos-username> \
  --password <dcos-password> \
  --base-path <optional-base-path>
Important: You need to run this command on all Portworx nodes, so that you could create and mount encrypted volumes on all nodes.

If the cli is used to authenticate with DC/OS Secrets, for every restart of Portworx container it needs to be re-authenticated with DC/OS Secrets by running the dcos login command.

Last edited: Tuesday, May 9, 2023