Secrets#

Starburst Enterprise platform (SEP) manages configuration details in static properties files. This configuration needs to include values such as usernames, passwords, and other strings, that are often required to be kept secret. Only a few selected administrators or the provisioning system have access to the actual value.

Secrets management in SEP allows you to reference values from security managers, files, or environment variables in any configuration property. All configurable SEP components, such as config.properties and catalog properties files, are supported. When loading the properties, SEP replaces the reference with the value from a specific secrets provider.

export DB_PASSWORD=my-super-secret-pwd

To use this variable in the properties file, you reference it with the syntax ${ENV:VARIABLE}. For example, if you want to use the password in a catalog properties file like etc/catalog/db.properties, add the following line:

connection-password=${ENV:DB_PASSWORD}

With this setup in place, the secret is managed by the provisioning system or by the administrators handling the machines. No secret is stored in the SEP configuration files on the filesystem or wherever they are managed.

SEP allows you to use the following configuration providers:

Vault
AWS Secret Manager
Azure Key Vault
Google Cloud Secret Manager
Alibaba Cloud Secret Manager
CyberArk Conjur
Keystore
File
Environment variables

Use a secrets.toml file to configure your secrets provider. By default, this file is located in the /etc directory. Specify a different location using the secretsConfig system property.

If the secretsConfig system property is not set, the environment varibles provider is enabled.

The secrets.toml file establishes the connection to a secrets provider. The file itself does not store your secrets. Instead, the file contains the configuration that SEP uses to retrieve secrets directly from the provider at runtime.

The following example secrets.toml file enables the Vault configuration provider:

secrets-plugins-dir="/usr/lib/starburst-cache-service/secrets-plugins"

[vault]
secrets-provider.name = "vault"
address = "http://vault:8200"
token = "your-token"

Set the secrets-plugins-dir property to the file path for the directory containing secrets provider plugins.

If you are using a standalone cache service deployment, you must copy the starburst-secrets-provider.zip file to your secrets-plugins-dir directory. For more information, see the cache service documentation.

To configure multiple instances of the same secrets provider, use unique section names:

[vault_prod]
secrets-provider.name = "vault"
address = "http://vault-prod:8200"
token = "prod-token"

[vault_dev]
secrets-provider.name = "vault"
address = "http://vault-dev:8200"
token = "dev-token"

Reference a secrets provider instance in your configuration files using the section name:

connection-user = ${vault_prod:secret/db:user}
connection-password = ${vault_dev:secret/db:password}

Vault#

To enable Vault by Hashicorp as your configuration provider, set the following properties in your secrets.toml file:

[vault]
secrets-provider.name = "vault"
address = "http://vault:8200"
token = "your-token"

Reference values from Vault using the syntax ${vault:path:key}, where:

vault is the case-insensitive section name in your secrets.toml file.
path is the secret path.
key is the secret key.

connector.name=postgresql
connection-url=jdbc:postgresql://postgresql:15432/test
connection-user=${vault:secret/postgres:user}
connection-password=${vault:secret/postgres:password}

The following configuration properties are available:

Configuration properties for the Vault configuration provider#
Property	Description
`address`	The address of the Vault server instance. This is a required property.
`auth-method`	The authentication method used to connect to Vault. Supported values are `TOKEN`, `APPROLE`, and `KUBERNETES`. See authentication methods for details. Default is `TOKEN`.
`token`	The Vault authentication token. Required when `auth-method` is `TOKEN`.
`auth.approle.role-id`	The AppRole role ID. Required when `auth-method` is `APPROLE`. See the official documentation for more details.
`auth.approle.secret-id`	Vault AppRole secret ID for authentication. Required when `auth.approle.mode` is `PUSH`.
`auth.approle.mode`	AppRole authentication mode. Supported values: `PUSH`: Authenticates using a `role-id` and `secret-id` provided directly in the configuration. `PULL_SECRET_ID`: Fetches `secret-id` from Vault using a token.
`auth.approle.role-name`	Vault AppRole role name. Used with `PULL_SECRET_ID` mode to generate a `secret-id`.
`auth.approle.token`	Vault token with permission to generate a `secret-id` for the AppRole. Required when `auth.approle.mode` is `PULL_SECRET_ID`.
`auth.approle.path`	The mount path for AppRole authentication. Default is `approle`.
`auth.kubernetes.role`	The Vault Kubernetes auth role name. Alternative to `auth.kubernetes.role.file`. Required when `auth-method` is `KUBERNETES` and `auth.kubernetes.role.file` is not set.
`auth.kubernetes.role.file`	Path to a file containing the Vault Kubernetes auth role name. Alternative to `auth.kubernetes.role`. Required when `auth-method` is `KUBERNETES` and `auth.kubernetes.role` is not set.
`auth.kubernetes.jwt`	The service account JWT token. Alternative to `auth.kubernetes.jwt.file`. Optional. When neither `auth.kubernetes.jwt` nor `auth.kubernetes.jwt.file` are set, `auth.kubernetes.jwt.file` is used and defaults to `/var/run/secrets/kubernetes.io/serviceaccount/token`.
`auth.kubernetes.jwt.file`	Path to a file containing the service account JWT token. Alternative to `auth.kubernetes.jwt`. Optional. Defaults to the token that Kubernetes mounts at `/var/run/secrets/kubernetes.io/serviceaccount/token`.
`auth.kubernetes.path`	The mount path for Kubernetes authentication. Alternative to `auth.kubernetes.path.file`. Default is `kubernetes`.
`auth.kubernetes.path.file`	Path to a file containing the Kubernetes auth mount path. Alternative to `auth.kubernetes.path`.
`namespace`	The global namespace of the Vault server instance.
`engine-version`	The KV Secrets Engine version of the Vault server instance.
`ssl.client-key-pem-path`	The path of a file containing an RSA private key, in unencrypted PEM format with UTF-8 encoding.
`ssl.client-pem-path`	The path of a file containing an X.509 certificate, in unencrypted PEM format with UTF-8 encoding.
`ssl.keystore-path`	A JKS keystore file, containing a client certificate registered with Vault’s TLS Certificate auth backend.
`ssl.keystore-password`	The password to the keystore.
`ssl.truststore-path`	A JKS truststore file, containing the Vault server’s X509 certificate.
`ssl.verify`	A Boolean indicating whether to verify the SSL certificate used by Vault with HTTPS connections.
`open-timeout-seconds`	The timeout value, in seconds, for establishing an HTTP(S) connection to the Vault server instance.
`read-timeout-seconds`	The timeout value, in seconds, for downloading data after establishing an HTTP(S) connection.
`prefix-path-depth`	The depth of the prefix file path.
`max-retries`	The number of retry attempts for API operations after a failure.
`retry-interval`	The wait time, in seconds, between retry attempts for API operations after a failure.

Authentication methods#

The Vault secrets provider supports authentication methods controlled by the auth-method configuration property. View the following sections for details and examples:

Token authentication

Token authentication is the default method. It uses a static Vault token to authenticate:

[vault]
auth-method = "TOKEN"
address = "http://vault:8200"
token = "your-token"

AppRole authentication

AppRole authentication supports two modes: PUSH and PULL_SECRET_ID.

In PUSH mode, role-id and secret-id are both provided directly:

[vault]
secrets-provider.name = "vault"
auth-method = "APPROLE"
address = "http://vault:8200"
auth.approle.mode = "PUSH"
auth.approle.role-id = "your-role-id"
auth.approle.secret-id = "your-secret-id"
auth.approle.path = "approle"

In PULL_SECRET_ID mode, a Vault token is used to fetch the secret-id at execution time:

[vault]
secrets-provider.name = "vault"
auth-method = "APPROLE"
address = "http://vault:8200"
auth.approle.mode = "PULL_SECRET_ID"
auth.approle.role-id = "your-role-id"
auth.approle.role-name = "your-role-name"
auth.approle.token = "your-vault-token"
auth.approle.path = "approle"

Kubernetes authentication

Kubernetes authentication allows pods to authenticate with Vault using their service account JWT token:

[vault]
secrets-provider.name = "vault"
auth-method = "KUBERNETES"
address = "http://vault:8200"
auth.kubernetes.role = "your-role"
auth.kubernetes.jwt = "your-service-account-jwt"
auth.kubernetes.path = "kubernetes"

Alternatively, you can reference file paths for the authentication values:

[vault]
secrets-provider.name = "vault"
auth-method = "KUBERNETES"
address = "http://vault:8200"
auth.kubernetes.role.file = "/path/to/role-file"
auth.kubernetes.jwt.file = "/path/to/jwt-file"
auth.kubernetes.path.file = "/path/to/path-file"

Note

You can mix direct and file-based options, but not both for the same property.

Only auth.kubernetes.role is required. If neither auth.kubernetes.jwt nor auth.kubernetes.jwt.file is set, auth.kubernetes.jwt.file defaults to the service account token that Kubernetes automatically mounts at /var/run/secrets/kubernetes.io/serviceaccount/token. If auth.kubernetes.path is not set, it defaults to the standard Kubernetes auth mount path kubernetes.

AWS Secret Manager#

To enable AWS Secrets Manager as your configuration provider, set the following properties in your secrets.toml file:

[asm]
secrets-provider.name = "asm"
region = "us-east-2"

Reference values from AWS Secrets Manager using the syntax ${asm:path} or ${asm:path:key}. For example:

connector.name=postgresql
connection-url=jdbc:postgresql://postgresql:15432/test
connection-user=test
connection-password=${asm:test:password}

If your secret contains a JSON object, reference a property by using a JSON pointer expression.

The following configuration properties are available:

Configuration properties for the ASM configuration provider#
Property	Description
`aws-access-key`	The AWS access key used for authenticating with AWS Secrets Manager.
`aws-secret-key`	The AWS secret key used for authenticating with AWS Secrets Manager.
`endpoint`	The endpoint URL for your AWS Secrets Manager service.
`region`	The AWS region for your AWS Secrets Manager service.
`iam-role`	The ARN of the IAM role used when connecting to AWS Secrets Manager.
`role-session-name`	The role session name used when connecting to AWS Secrets Manager.
`external-id`	External ID for the IAM role trust policy used when connecting to AWS Secrets Manager.
`sts.endpoint`	The endpoint URL for the AWS Security Token Service (STS) used for authenticating with AWS Secrets Manager.
`sts.region`	The AWS region for the AWS STS service.
`max-connections`	The maximum number of concurrent connections to AWS Secrets Manager.
`http-proxy`	The URL of the HTTP proxy server used for connecting to AWS Secrets Manager.
`http-proxy.secure`	Boolean indicating whether the HTTP proxy uses TLS.

Azure Key Vault#

To enable Azure Key Vault as your configuration provider, set the following properties in your secrets.toml file.

Azure Key Vault supports two authentication methods:

Default authentication - Uses Azure’s default credential chain.
Client secret authentication - Uses explicit client credentials.

The following is an example configuration file using the default authentication method:

[azure-key-vault]
secrets-provider.name = "azure-key-vault"
secrets.azure.key-vault-name = "my-vault"
azure.auth-type = "DEFAULT"

If azure.auth-type is not specified, the default authentication method is used.

The following is an example configuration file using the client secret authentication method:

Note

When using CLIENT_SECRET, you must specify azure.client-id, azure.tenant-id, and azure.client-secret.

[azure-key-vault]
secrets-provider.name = "azure-key-vault"
secrets.azure.key-vault-url = "https://my-vault.vault.azure.net/"
azure.auth-type = "CLIENT_SECRET"
azure.client-id = "your-client-id"
azure.tenant-id = "your-tenant-id"
azure.client-secret = "your-client-secret"

Reference values from Azure Key Vault using the syntax ${azure-key-vault:secret-name}. For example:

connector.name=postgresql
connection-url=jdbc:postgresql://postgresql:15432/test
connection-user=${azure-key-vault:db-username}
connection-password=${azure-key-vault:db-password}

The following configuration properties are available:

Configuration properties for the Azure Key Vault configuration provider#
Property	Description
`secrets.azure.key-vault-name`	The name of your Azure Key Vault instance. Exactly one of `secrets.azure.key-vault-name` or `secrets.azure.key-vault-url` must be specified.
`secrets.azure.key-vault-url`	The full URL of your Azure Key Vault instance. Exactly one of `secrets.azure.key-vault-name` or `secrets.azure.key-vault-url` must be specified.
`azure.auth-type`	The authentication method to use. Valid values are `DEFAULT` (uses Azure’s default credential chain) or `CLIENT_SECRET` (uses explicit client credentials). Defaults to `DEFAULT`.
`azure.client-id`	The Azure AD application (client) ID. Required when `azure.auth-type` is set to `CLIENT_SECRET`.
`azure.tenant-id`	The Azure AD tenant ID. Required when `azure.auth-type` is set to `CLIENT_SECRET`.
`azure.client-secret`	The Azure AD application client secret value. Required when `azure.auth-type` is set to `CLIENT_SECRET`.

Google Cloud Secret Manager#

To enable Google Cloud Secret Manager as your configuration provider, set the following properties in your secrets.toml file:

[gcp-secret-manager]
secrets-provider.name = "gcp-secret-manager"
gcp.credentials-key = "<GCP_CREDENTIALS_KEY>"

Reference values from Google Cloud Secret Manager using the syntax ${gcp-secret-manager:google_project_id:secret_name}. The values are separated by colons, where google_project_id is your Google Cloud project ID and secret_name is the Secret Manager secret name or ID for the database username or password stored in Google Cloud Secret Manager.

connector.name=postgresql
connection-url=jdbc:postgresql://postgresql:15432/test
connection-user=${gcp-secret-manager:<GOOGLE_PROJECT_ID>:<DATABASE_USERNAME>}
connection-password=${gcp-secret-manager:<GOOGLE_PROJECT_ID>:<DATABASE_PASSWORD>}

Alibaba Cloud Secret Manager#

To enable Alibaba Cloud Secret Manager as your configuration provider, set the following properties in your secrets.toml file:

[alibaba-cloud-secret-manager]
secrets-provider.name = "alibaba-cloud-secret-manager"
region = "us-east-1"
access-key-id = "your-access-key-id"
access-key-secret = "your-access-key-secret"

Reference values from Alibaba Cloud Secret Manager using the syntax ${alibaba-cloud-secret-manager:secret-name}. For example:

connector.name=postgresql
connection-url=jdbc:postgresql://postgresql:15432/test
connection-user=${alibaba-cloud-secret-manager:db-username}
connection-password=${alibaba-cloud-secret-manager:db-password}

The following configuration properties are available:

Configuration properties for the Alibaba Cloud Secret Manager configuration provider#
Property	Description
`region`	The Alibaba Cloud region for your Secret Manager service.
`endpoint`	URL for specifying a custom KMS endpoint. Required for private Alibaba Cloud environments.
`access-key-id`	The Alibaba Cloud access key ID used for authentication.
`access-key-secret`	The Alibaba Cloud access key secret used for authentication.

CyberArk Conjur#

To enable CyberArk Conjur as your configuration provider, set the following properties in your secrets.toml file:

[conjur]
secrets-provider.name = "conjur"
conjur.appliance-endpoint = "https://conjur-proxy-nginx"
conjur.account = "sep"
conjur.authentication-login = "user@test"
conjur.api-key = "your-credentials-key"

Configuration properties for the CyberArk Conjur configuration provider#
Property	Description
`conjur.appliance-endpoint`	The endpoint URL for your CyberArk Conjur server instance. It can be an HTTP or HTTPS endpoint.
`conjur.account`	The CyberArk account that contains your secrets.
`conjur.authentication-login`	The username to authenticate to CyberArk.
`conjur.authentication-url`	The URL of the Conjur authentication endpoint. If not specified, the authentication URL defaults to the value of `conjur.appliance-endpoint` with `/authn` appended.
`conjur.api-key`	The API key or password to authenticate to CyberArk.
`conjur.tls.enabled`	Set to `true` to enable TLS.
`conjur.ssl.keystore.path`	The file path to your SSL keystore.
`conjur.ssl.keystore.password`	The password for your SSL keystore.
`conjur.ssl.truststore.path`	The file path to your SSL truststore.
`conjur.ssl.truststore.password`	The password for your SSL truststore.
`conjur.token.authentication.enabled`	Set to `true` to enable token-based authentication.
`conjur.token-file-path`	The file path for your token, if you enable token-based authentication.
`conjur.token.refresh-period`	The duration between token refreshes. This property is optional. Defaults to `1m`.

Keystore#

To enable a Keystore as your configuration provider, set the following properties in your secrets.toml file:

[keystore]
secrets-provider.name = "keystore"
keystore-file-path = "/docker/presto-product-tests/conf/presto/etc/credential.jckes"
keystore-type = "pkcs12"
keystore-password = "password"

File#

To use one or more files as your configuration provider, set the following properties in your secrets.toml file:

secrets-provider.name="file"
allowed-file-variable-dir="/docker/presto-product-tests/conf/presto/etc"

You must specify a directory using the allowed-file-variable-dir property. This ensures that you only allow access to a specific directory on the host.

Note

Your files must be accessible on all nodes.

Reference values from a file using the syntax ${FILE:path}. path must begin with the directory you specify in allowed-file-variable-dir. For example:

connector.name=postgresql
connection-url=jdbc:postgres://pg-instance-hostname:5432
connection-user=${FILE:/<path>/pg_user}
connection-password=${FILE:/<path>/pg_password}

Environment variables#

Environment variables are a widely supported means of setting and retrieving values within services. SEP supports the use of environment variables to manage secrets without needing any external services.

To use environment variables as your configuration provider, set the following properties in your secrets.toml file:

secrets-provider.name="env"

Note

Your environment variables must be accessible on all nodes.

Reference values of environment variables using the syntax ${ENV:name}. For example:

connector.name=postgresql
connection-url=jdbc:postgres://${ENV:PGHOST}:${ENV:PGPORT}
connection-user=${ENV:PGUSER}
connection-password=${ENV:PGPASSWORD}

Note

This provider is enabled by default, if the secretsConfig system property is not set (no secrets.toml file is used). If other providers are configured, it must also be enabled, if any configuration properties include references to environment variables.