ADR-0021: VSecM Shall Use Environment Variables for Configuration

Status: accepted
Date: 2024-09-02
Tags: configuration, environment-variables

Context and Problem Statement

VSecM (VMware Secrets Manager) needs a flexible and secure way to configure its components across different environments. The challenge is to find a method that is both easy to manage and secure for handling configuration settings, especially those containing sensitive information.

Decision

We have decided to use environment variables as the primary method for configuration in VSecM.

Rationale

Security: Environment variables provide a level of security by keeping sensitive information out of the codebase and configuration files. This reduces the risk of accidentally committing secrets to version control.
Flexibility: Environment variables can be easily set and modified across different environments (development, staging, production) without changing the application code.
Container-friendly: In containerized environments, which are common in modern deployments, environment variables are a standard way to pass configuration to applications.
Simplicity: Using environment variables simplifies the deployment process as there’s no need to manage multiple configuration files for different environments.
Integration: Many CI/CD and cloud platforms provide built-in support for managing environment variables, making it easier to integrate with existing infrastructure.
Runtime configuration: Environment variables allow for runtime configuration changes without requiring application restarts in many cases.

Consequences

Positive

Improved security by keeping sensitive information out of the codebase
Easier management of configurations across different environments
Better compatibility with containerized deployments and cloud platforms
Simplified deployment process

Negative

Potential for environment variable sprawl if not managed carefully
Debugging might be more challenging as configuration is not in a centralized file
Limited structure for complex configurations (compared to configuration files)

Implementation

When implementing this approach:

Use clear and consistent naming conventions for environment variables
Provide documentation on all available configuration options
Use sensible defaults where possible to minimize the number of required variables
Implement validation for required environment variables at application startup
Implement a fallback mechanism to use default values when environment variables are not set

Default Configuration

VSecM codebase will contain sane defaults for all environment variable configurations as much as possible. This approach ensures that:

VSecM will run out of the box even when most (or all) of the environment variables are not defined or configured.
Users can get started quickly without needing to configure every aspect of the system.
The system remains functional with minimal configuration, reducing the chance of misconfigurations or startup failures.

When implementing default configurations:

Choose secure and generally applicable default values.
Document all default values clearly in the codebase and user documentation.
Implement a clear hierarchy: environment variables should override defaults when present.
Log the use of default values at startup to inform users of the active configuration.
Regularly review and update default values to ensure they remain appropriate and secure as the system evolves.

This approach balances ease of use with the flexibility to customize the configuration as needed, making VSecM both user-friendly and adaptable to various deployment scenarios.

ADRs

You can view the ADRs by browsing this following list:

edit this page ✏️