Secrets Management
Relevant source files
The following files were used as context for generating this wiki page:
Secrets Management in Kamal facilitates the secure handling and retrieval of sensitive information such as passwords, tokens, and keys required during deployment. The system supports local environment files via dotenv with advanced features like command interpolation and variable references, as well as integration with various external vault providers through a dedicated adapter architecture.
The core objective is to ensure that secrets are available for the registry, builder, application roles, and accessories while preventing sensitive data from being committed to version control. The management system performs early validation of required secrets to fail fast before expensive operations like image builds or SSH connections occur.
Sources: lib/kamal/secrets.rb, lib/kamal/configuration.rb:108-132
Core Components
Kamal::Secrets Class
The Kamal::Secrets class serves as the primary interface for accessing secrets within the application logic. It manages the loading of secret files from the .kamal/ directory and provides a thread-safe lookup mechanism using a Mutex.
Sources: lib/kamal/secrets.rb:3-12
Configuration Integration
Secrets are integrated into the main Kamal::Configuration lifecycle. During initialization, the configuration object instantiates a Kamal::Secrets instance, which is then used to resolve environment variables for the registry, builder, and individual server roles.
Sources: lib/kamal/configuration.rb:58, 66-73
Validation Logic
A critical feature is the validate_secrets! method, which resolves every secret needed for the deployment upfront. This includes registry credentials, builder secrets, proxy certificates, and accessory environment variables.
Sources: lib/kamal/configuration.rb:108-132
The diagram shows the sequence of secret resolution during the configuration initialization and validation phase.
Sources: lib/kamal/configuration.rb:58-132
Local Secrets Resolution
Kamal looks for local secrets in the .kamal/ directory by default. It supports multiple files to allow for shared and destination-specific configurations.
Secret File Hierarchy
Secrets are merged from multiple files in a specific order, where later files override earlier ones:
.kamal/secrets-common: Shared secrets across all environments..kamal/secrets.<destination>: Secrets specific to a deployment destination (e.g., production, staging)..kamal/secrets: The default secrets file if no destination-specific file is found.
Sources: lib/kamal/secrets.rb:34-40, test/secrets_test.rb:58-69
Interpolation Features
Kamal extends standard dotenv functionality with two key interpolation types:
- Command Interpolation: Values can be generated dynamically using shell commands, e.g.,
SECRET=$(echo ABC). - Variable References: Secrets can reference other variables or system environment variables, e.g.,
SECRET2=${SECRET1}DEF.
Sources: test/secrets_test.rb:21-40, lib/kamal/secrets.rb:4
External Vault Adapters
Kamal provides a CLI-based mechanism to fetch secrets from external providers. This is handled via Kamal::Cli::Secrets and specialized adapter classes.
Supported Adapters
| Provider | Adapter Identifier | Requirements | CLI Dependency |
|---|---|---|---|
| Google Secret Manager | gcp_secret_manager | Account/Email | gcloud |
| AWS Secrets Manager | aws_secrets_manager | AWS Profile (optional) | aws |
| Bitwarden Secrets Manager | bitwarden_secrets_manager | Access Token | bws |
| Enpass (Offline) | enpass | Vault Path | enpass-cli |
| Sources: lib/kamal/secrets/adapters/gcp_secret_manager.rb, lib/kamal/secrets/adapters/aws_secrets_manager.rb, lib/kamal/secrets/adapters/bitwarden_secrets_manager.rb, lib/kamal/secrets/adapters/enpass.rb |
Fetch Flow
When using the kamal secrets fetch command, the system performs the following sequence:
- Dependency Check: Verifies the required provider CLI is installed.
- Authentication: Performs login or validates existing session tokens.
- Retrieval: Fetches requested secrets (or all secrets if supported).
- Extraction: Formats the output as JSON for use in scripts or CLI pipelines.
Sources: lib/kamal/cli/secrets.rb:6-22, lib/kamal/secrets/adapters/base.rb
The sequence diagram illustrates how Kamal interacts with external providers through the adapter layer.
Sources: lib/kamal/cli/secrets.rb:6-22, lib/kamal/secrets/adapters/gcp_secret_manager.rb:34-75
Implementation Details
Thread Safety
Access to the internal secrets hash is protected by a Mutex in the synchronized_fetch method. This prevents race conditions, especially when fetching secrets might trigger interactive user prompts.
Sources: lib/kamal/secrets.rb:43-48
Redaction in Logs
While the configuration object contains secrets, the to_h method and CLI output utilities typically use Kamal::Utils.redacted to ensure that sensitive values do not appear in plain text in logs or console output unless explicitly requested (e.g., via the kamal secrets print command).
Sources: lib/kamal/cli/main.rb:142-145, lib/kamal/cli/secrets.rb:36-40
Error Handling
If a required secret is missing during validation, Kamal raises a Kamal::ConfigurationError detailing which key was not found and which files were searched.
Sources: lib/kamal/secrets.rb:13-20, lib/kamal/configuration.rb:110-132
Summary
Secrets Management in Kamal provides a robust framework for handling sensitive deployment data. By combining local environment file support with a flexible adapter system for cloud vaults, it ensures that developers can manage secrets securely according to their infrastructure requirements. The early validation phase is a key architectural decision that prevents partial deployments due to missing credentials.