Secrets Management

Distr provides a centralized secret management system that allows you to securely store sensitive configuration values and reference them in your deployments using template syntax. The secret values are substituted at deploy time — they never appear in your compose files, Helm values, or deployment logs.

Note

This page covers Distr’s built-in secret store, which works for both Docker and Kubernetes deployments. If you need secrets delivered as files inside containers rather than as environment variables, see Docker Compose Secrets — a Docker-native mechanism that can be used on its own or combined with Distr Secrets.

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 either to a vendor organization or each customer. The scope determines which deployments can use a secret and where you manage it.

Vendor-level secrets

Vendor-level secrets are available to your internal deployments (deployment targets without a customer organization). They are not injected into customer deployments. If a customer deployment needs a credential, create it as a customer-specific secret for that customer.

Use vendor-level secrets for credentials that only your internal infrastructure needs, for example a staging environment token or a third-party API key used in vendor-managed test deployments.

To create or manage vendor-level secrets:

1. In the Vendor Portal sidebar, click Secrets.
2. Create, edit, or delete secrets from this view.

Customer-specific secrets

Customer-specific secrets are only available to deployments for one specific customer. Use these for credentials that belong to a single customer, for example a customer’s own database password or an API key specific to their environment.

Customer-specific secrets are managed from the Customers section, not the Secrets page:

1. In the Vendor Portal sidebar, click Customers.
2. Find the customer and click Manage secrets next to them.
3. Create, edit, or delete secrets from this view.

Customer-specific secrets are only injected into that customer’s deployments. They are not available to other customers and do not appear in the vendor-level secrets list.

Customer Organizations

As a customer, you can only create and view secrets for your own organization. In the Customer Portal, navigate to Secrets to manage them. These secrets are only available to your own 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.