Manage Secrets

Distr provides a centralized secret management system that allows you to securely store sensitive configuration values and reference them in your deployments. This enables you to keep secrets out of your deployment configurations while still making them available to your applications at runtime.

In this guide, you’ll learn how to create, manage, and use secrets in your deployment configurations.

What are Secrets?

Secrets are key-value pairs that store sensitive information such as API keys, passwords, database credentials, or any other confidential data that your application needs. Instead of hardcoding these values in environment files or Helm values, you can store them centrally in Distr and reference them using template syntax.

For example, if your application needs a database password, you can create a secret with key DATABASE_PASSWORD and reference it in your deployment configuration:

DATABASE_URL=postgresql://user:{{ .Secrets.DATABASE_PASSWORD }}@host:5432/db

When the deployment is created, the template is automatically replaced with the actual secret value.

Benefits of Using Secrets

• Security: Secrets are stored securely and never exposed in deployment logs or configuration files
• Centralized Management: Update secrets in one place and have them automatically available to all deployments
• Audit Trail: Track who created or updated each secret and when
• Access Control: Secrets are scoped to organizations and customer organizations
• Log Protection: Secret values are automatically redacted from deployment logs

Creating and Managing Secrets

Accessing the Secrets Page

1. Navigate to the Distr web interface
2. Click on Secrets in the sidebar navigation
3. For vendor organizations: You can manage both vendor-level secrets and customer-specific secrets
4. For customer organizations: You can only view and manage secrets for your own organization

Creating a Secret

1. Click the Create Secret button on the Secrets page
2. Enter a Key for your secret (must start with a letter and contain only alphanumeric characters and underscores)
3. Enter the Value for your secret
4. Click Save

Tip

Use descriptive names for your secret keys that clearly indicate their purpose, such as API_KEY_GITHUB or DATABASE_PASSWORD_PROD.

Updating a Secret

1. Find the secret you want to update in the secrets list
2. Click the Edit button next to the secret
3. Enter the new value (the key cannot be changed)
4. Click Save

The updated value will be automatically used in all future deployments. Existing deployments will continue using the old value until they are redeployed.

Deleting a Secret

1. Find the secret you want to delete in the secrets list
2. Click the Delete button
3. Confirm the deletion

Caution

Deleting a secret will cause any deployments that reference it to fail during deployment or validation. Make sure no active deployments are using the secret before deleting it.

Using Secrets in Deployments

Secrets can be referenced in two types of deployment configurations:

Environment Files (.env)

Use secrets in your environment files with Go template syntax:

# Reference a secret directly
API_KEY={{ .Secrets.API_KEY }}

# Use secrets in connection strings
DATABASE_URL=postgresql://user:{{ .Secrets.DB_PASSWORD }}@localhost:5432/mydb

# Combine multiple secrets
AUTH_TOKEN={{ .Secrets.CLIENT_ID }}:{{ .Secrets.CLIENT_SECRET }}

Helm Values (YAML)

For Kubernetes deployments, reference secrets in your Helm values:

database:
  host: db.example.com
  password: {{.Secrets.DB_PASSWORD}}

api:
  credentials:
    username: admin
    password: {{.Secrets.ADMIN_PASSWORD}}

config:
  githubToken: {{.Secrets.GITHUB_TOKEN}}

Template Syntax

Secrets use Go’s text/template syntax for substitution.

Basic Secret Reference

{{ .Secrets.SECRET_KEY_NAME }}

The secret key name must match exactly (case-sensitive) with a secret that exists in your organization.

Conditionals

Use if statements to handle optional secrets:

API_URL={{ if .Secrets.API_URL }}{{ .Secrets.API_URL }}{{ else }}https://api.example.com{{ end }}

In YAML:

api:
  url: {{ if .Secrets.API_URL }}{{ .Secrets.API_URL }}{{ else }}https://api.example.com{{ end }}

Combining Secrets

You can combine multiple secrets in a single value:

CREDENTIALS={{ .Secrets.USERNAME }}:{{ .Secrets.PASSWORD }}

Secret Naming Conventions

Secret keys must follow these rules:

• Must start with a letter (a-z, A-Z)
• Can contain letters, numbers, and underscores
• Cannot start with a number or underscore
• Cannot contain spaces or special characters (except underscore)

Valid examples:

• API_KEY
• database_password
• GitHubToken123
• stripe_api_key_prod

Invalid examples:

• _API_KEY (starts with underscore)
• 123_KEY (starts with number)
• API-KEY (contains hyphen)
• API KEY (contains space)

Secret Scoping

Secrets are scoped by organization:

Vendor Organizations

As a vendor, you can create two types of secrets:

1. Vendor-level secrets: Available to all your deployments and can be used in all customer deployments
2. Customer-specific secrets: Only available to deployments for a specific customer organization

When viewing secrets as a vendor, you can filter by customer organization to see customer-specific secrets.

Customer Organizations

As a customer, you can only create and view secrets for your own organization. These secrets are only available to your deployments.

Security Considerations

Log Redaction

Distr automatically redacts secret values from deployment logs. If a log message contains a secret value, it will be replaced with ******** before being displayed or exported.

This protects your secrets even if they accidentally appear in application logs.

Secret Storage

Caution

Secrets are stored in the Distr database. Ensure your Distr instance uses appropriate database encryption and access controls for your security requirements.

Access Control

• Only users with read_write or admin roles can create, update, or delete secrets
• All users in an organization can view secret keys (but not values)
• Secret values are never returned by the API after creation (only keys and metadata)

Best Practices

1. Rotate secrets regularly: Update secret values periodically and redeploy affected applications
2. Use minimal scope: Create customer-specific secrets when possible rather than vendor-wide secrets
3. Don’t log secrets: Ensure your application code doesn’t intentionally log secret values
4. Use descriptive keys: Make it clear what each secret is for without revealing sensitive information
5. Test in non-production first: Verify secret references work correctly before deploying to production

Error Handling

Missing Secrets

If a deployment configuration references a secret that doesn’t exist, the deployment validation will fail with an error:

template execution error: map has no entry for key "SECRET_NAME"

To fix this, create the missing secret or remove the reference from your configuration.

Template Syntax Errors

If your template syntax is invalid, you’ll receive an error during deployment validation:

template parsing error: unexpected "}" in operand

Check your template syntax for missing braces, quotes, or other syntax issues.

Empty Secret Values

Caution

Secret values cannot be empty. If you need to represent an empty value, consider using a placeholder string or removing the secret reference entirely.