Secrets
Overview
Secrets are used to store strongly-encrypted information. All secrets can be injected into containers through the use of environment variables.
In addition to optionally being injected into containers as environment variables, secrets are also used for:
- Image registry (Docker, ECR, and GCP) pull secrets, enabling workloads in a GVC to pull images from private repositories.
- Enabling Control Plane to manage policies in Azure, using the Azure SDK and Azure Connector secret type.
A workload identity MUST be granted the reveal permission on a secret to have its value injected at runtime.
Secret Types
- Amazon Web Services (AWS)
- Azure SDK
- Azure Connector
- Docker
- Dictionary
- ECR
- Google Cloud Platform (GCP)
- Keypair
- Opaque
- NATS Account
- TLS
- Username & Password
Amazon Web Services (AWS)
The AWS secret type enables a workload to consume services from AWS. It is used in cases where an identity isn’t used.
For example, when an Org does not wish to create a cloud account, or to create cloud access policy as part of an identity definition.
The recommended approach to consuming services from AWS is not to use a AWS secret, but rather to:
- Create a cloud account.
- Create an identity.
- Defining a cloud access policy for the AWS account as part of the identity.
In cases where an Org wishes to not leverage the identity feature, in order to use an AWS secret, simply read the secret from the environment variable and convey its set of values to AWS using any AWS API you wish.
The AWS secret schema consists of:
- Secret Key
- Access Key
- Role ARN (Optional)
- External ID (Optional)
For an existing AWS user, these values are obtained from the AWS IAM Dashboard.
Refer to these instruction to create a new AWS IAM user in your AWS account.
Azure SDK
-
Used to store Azure SDK credentials.
-
When creating a Cloud Account using the Azure SDK, a JSON file is generated containing the credentials. This file is uploaded and automatically stored as an Azure-SDK secret.
-
Sample Azure-SDK secret content:
JSON{ "subscriptionId": "2cd2674e-4f89-4a1f-b420-7a1361b46ef7", "tenantId": "292f5674-78b0-488b-9ff8-6d30d77f38d9", "clientId": "649746ce-d862-49d5-a5eb-7d5aad90f54e", "clientSecret": "CONFIDENTIAL" }
-
If the client secret has been compromised or needs to be updated, the content of the secret can be updated using the console or CLI and will be used by the associated Cloud Accounts.
Azure Connector
- Used to store Azure Function App credentials.
- When creating a Cloud Account using the Azure Connector, the
deployment URL
andcode
will be saved. - These values can be updated using the console or the CLI.
Docker
The Docker secret type is used when a container pulls an image from a private Docker compatible repository, such as a Org’s private repository at Control Plane, Docker Hub, or Azure Container Registry.
An authorized user then assigns a secret of this type to a GVC Pull Secret.
Workloads in the GVC can then pull their image using the secret.
The contents of a Docker secret follows this syntax:
{
"auths": {
"REPOSITORY_URL": {
"username": "USERNAME",
"password": "PASSWORD"
}
}
}
Control Plane
To create a Docker secret targeting a private repository hosted at Control Plane, a Service Account at the source Org, bound with the pull permission is required.
Example:
{
"auths": {
"ORG_NAME.registry.cpln.io": {
"username": "<token>",
"password": "SERVICE_ACCOUNT_KEY"
}
}
}
The username
is the literal string <token>
.
Docker Hub
To create a Docker secret targeting Docker Hub, a Docker username and password (which has permissions to pull the images) are required.
There are two ways to create the secret content:
-
Username & Password
KeysExample:
JSON{ "auths": { "https://index.docker.io/v1/": { "username": "USERNAME", "password": "PASSWORD" } } }
-
auth
Key- When using a password, the value of the
auth
key is the base64 encoded result of the stringUSERNAME:PASSWORD
.
Example:
JSON{ "auths": { "https://index.docker.io/v1/": { "auth": "BASE_64_ENCODING(USERNAME:PASSWORD)" } } }
- When using a Docker Access Token, the value of the
auth
key is the base64 encoded result of the stringUSERNAME:DOCKER_ACCESS_TOKEN
.
Example:
JSON{ "auths": { "https://index.docker.io/v1/": { "auth": "BASE_64_ENCODING(USERNAME:DOCKER_ACCESS_TOKEN)" } } }
- When using a password, the value of the
When performing the base64 encoding, remember to include the colon ( : ) when concatenating the username and password/token.
The base64
utility can be used to easily encode the string.
Example: echo -n USERNAME:PASSWORD | base64
Azure Container Registry
To create a Docker secret targeting the Azure Container Registry, the following properties are required:
- Repository URL
- Service Principal ID
- Password
An Azure Service Principal
is recommended as the identity used to pull images.
Refer to this article to create an Azure Service Principal that only has the pull permission.
- The format of the repository URI is:
REGISTRY_NAME.azurecr.io
and can be obtained from theAzure Container Registry
section of the Azure Portal. - The USERNAME is the ID GUID of the Service Principal (e.g., ed0a30b4-5cd0-44af-864a-cf825b0ceeb6).
- The PASSWORD is generated when creating the Service Principal. By default, the password expires after 1 year.
To increase the expiration length of the password, use the --years
flag when running the az ad sp create-for-rbac
command during the creation of a Service Principal.
Example:
{
"auths": {
"REGISTRY_NAME.azurecr.io": {
"username": "APP_ID",
"password": "PASSWORD"
}
}
}
GitHub Container Registry
To create a Docker secret targeting GitHub, a GitHub personal access token (which has the read:packages
scope) is required.
Example:
{
"auths": {
"ghcr.io": {
"username": "controlplane",
"password": "PERSONAL_ACCESS_TOKEN"
}
}
}
Dictionary
- Used to securely store key/value pairs that can be used by a workload’s environment variables.
- Multiple key/value pairs can be added to a single dictionary secret.
ECR
The Elastic Container Registry (ECR) secret type is used when a workload pulls a container image from a private AWS ECR repository.
This secret type is used when configuring a GVC’s Pull Secret. Workloads that are connected to that GVC will have access to the secret when pulling the image.
The ECR secret consists of:
- AWS Secret Key
- AWS Access Key
- AWS Role ARN (Optional)
- ECR Repository URIs (e.g., AWS_ACCOUNT_ID.dkr.ecr.REGION.amazonaws.com/REPO_NAME)
- External ID (Optional)
To obtain the keys required to create an ECR secret, from the AWS IAM Dashboard:
- Add a new IAM User with programmatic access.
- Create an Access Token for the new user and take note/download the secret and access key.
- Create a new IAM Policy for the
Elastic Container Registry
service with theRead
action on the specific repositories. - Attach the new IAM Policy to the new IAM User.
- Optionally, impersonate the IAM user with its credentials and try to pull an image locally as described here.
- Create the ECR secret using either the UI Console or CLI.
Amazon ECR Helper Links
Google Cloud Platform (GCP)
- Similar to a Docker and ECR secret, a GCP secret is used when a workload pulls a container image from a private
Google Container Registry
. - This secret type is used when configuring a GVC Pull Secret. Workloads that are connected to that GVC will have access to the secret when pulling the image.
- Using the UI, the secret JSON text can be in a file that is uploaded or pasted into the textbox.
- Below is a sample of a GCP secret. The values can be obtained from your GCP account.
{
"type": "service_account",
"project_id": "PROJECT_ID",
"private_key_id": "PRIVATE_KEY_ID",
"private_key": "PRIVATE_KEY_CERTIFICATE",
"client_email": "CLIENT_EMAIL",
"client_id": "CLIENT_ID",
"auth_uri": "https://accounts.google.com/o/oauth2/auth",
"token_uri": "https://oauth2.googleapis.com/token",
"auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
"client_x509_cert_url": "X509_CERTIFICATE_URL"
}
Keypair
- Used to securely store a keypair that can be used by a workload’s environment variables.
- A keypair secret consists of:
- Secret key
- Public key
- Passphrase (required if the secret key is encrypted)
- Using the UI, the secret and public key text can be in a file that is uploaded or pasted into the textbox.
- The keys will be validated and the secret will only be created or updated if they are valid PEM-encoded certificates.
Opaque
Opaque secrets are used to securely store any text.
When creating or updating an opaque secret, an option is available to perform a base64 decode at runtime.
To access the stored text, an environment variables’ value must be set to one of the following:
-
cpln://secret/SECRET_NAME.payload
- If the option to perform a base64 decode at runtime is enabled, the decoded value will be returned.
-
cpln://secret/SECRET_NAME
(without the .payload)- If the option to perform a base64 decode at runtime is enabled, the
encoding
property will be set tobase64
. It is the responsibility of the user to perform the base64 decode.
Example values returned:
base64: "{\"payload\":\"VGhpcyBpcyBhbiBvcGFxdWUgaW4gYmFzZTY0\",\"encoding\":\"base64\"}"
plain text: "{\"payload\":\"The is an opaque secret in plain text\",\"encoding\":\"plain\"}"
- If the option to perform a base64 decode at runtime is enabled, the
NATS Account
- Used to store NATS Account credentials.
- When creating a Cloud Account using the Azure Connector, the
deployment URL
andcode
will be saved. - These values can be updated using the console or the CLI.
- A NATS Account secret consists of:
- Account ID
- Private Key
- These properties will be validated and the secret will only be created or updated if they are valid.
TLS
- Used to securely store a Transport Layer Security (TLS) secret that can be used by a workload’s environment variables.
- A TLS secret consists of a:
- Key
- Certificate
- Chain Certificate (optional if the certificate is self-signed or not part of the installed root certificates)
- Using the UI, the secret can be in a file that is uploaded or pasted into the textbox.
- The certificates will be validated and the secret will only be created or updated if they are valid PEM-encoded certificates
Username & Password
- Used to securely store a username and password secret that can be used by a workload’s environment variables.
- The secret consists of:
- Username
- Password
- Encoding (Base64 / Plain Text)
- The secret will only be created or updated if the username and password are valid strings.
Permissions
The permissions below are used to define policies together with one or more of the four principal types:
Permission | Description | Implies |
---|---|---|
create | Create new secrets | |
delete | Delete secrets | |
edit | Modify existing secrets | view, reveal |
manage | Full access | create, delete, edit, manage, reveal, use, view |
reveal | Reveal the plaintext of the secret | view |
use | Refer to this secret from other entities (gvcs, cloudaccounts, etc) | view |
view | Read-only access excluding plaintext |
Reveal Permission
The plaintext of a secret can be viewed only if you or an identity has the reveal
permission.
For example, when using a secret as the value of an environment variable for a container, the identity assigned to the workload must have the reveal
permission set on the assigned secret using a policy.
When configuring the environment variable, the value of the variable will be in the following format: cpln://secret/SECRET_NAME
. The image running within the container will be able to access the plaintext of the secret by referring to the name of the configured environment variable.
Use Permission
A secret is used with a:
- GVC’s pull secret
- Container’s environment variables
- Policy’s binding
To allow a non-administrator user the ability to use a secret with one of the above objects, the user must be granted the use
permission.
For example, if the image assigned to a container belongs to a private Docker registry, a pull secret for that registry must be added to the associated GVC. The user that is configuring this application must have the use
permission set on the secret (using a policy) to be able to add it as a pull secret.
Updating Secrets
If a secret value is updated, any workload referencing that secret will need to be redeployed.
Access Report
Displays the permissions granted to principals for the secret.
CLI
To view the CLI documentation for secrets, click here.