Secret Management

Alpha Feature

Secret management is currently an alpha feature. You are seeing an early version of this functionality, which may change significantly in future updates as we continue to improve the experience.

Codesphere provides a Secret Management system integrated with OpenBao, an open-source security vault. This ensures that sensitive data, such as API keys, database credentials, and certificates, are stored with industry-standard encryption and injected into your services only when needed.

Overview

Unlike standard environment variables, secrets are stored in a vault shipped with a Codesphere instance. This provides several advantages:

• Encryption at Rest: All values are encrypted before being persisted.
• Granular Access: Only services explicitly referencing a secret can access its value.
• Automatic Cleanup: Secrets are bound to the lifecycle of the workspace.

info

Currently only admins of a Codesphere installation have direct acces to the vault.

Referencing Secrets

Secrets are managed within the Landscape Config Editor under the CI & Deploy mode. To define a secret, you must use a specific templating syntax regardless of whether you are using the UI or the YAML configuration.

Template Syntax: ${{ vault.secretKeyOfBao }}

UI Configuration

To add a secret to a service using the visual editor:

1. Open the Landscape Config Editor in your workspace.
2. Select the service you wish to configure and open the Edit Service fly-in sheet.
3. Navigate to the Values tab.
4. Add a new entry using the templating syntax:
   • Key: The Environment Variable name the service will use (e.g., SECRET_KEY).
   • Value: The template referencing the vault key (${{ vault.secretFoo }}).

Configuring environment variables using vault templates in the service values tab.

YAML Configuration

For direct configuration, secrets are defined in the env section of your ci.yml profile. Codesphere parses these templates during the sync process and injects the corresponding OpenBao entries into the service environment.

schemaVersion: v0.2
prepare:
  steps: []
test:
  steps: []
run:
  secret-demo:
    steps:
      - command: echo $SECRET_KEY
    plan: 8
    replicas: 1
    network:
      ports:
        - port: 3000
          isPublic: false
      paths: []
    env:
      SECRET_KEY: ${{ vault.secretFoo }}
      PLAIN_ENV: foo

Advanced Environment Templates

Beyond vault secrets, Codesphere supports dynamic templates to reference system-level IDs or existing workspace environment variables. These are particularly useful for making your configuration portable or remapping variables.

Template	Description
${{ workspace.id }}	Resolves to the ID of the Workspace containing the landscape.
${{ team.id }}	Resolves to the ID of the team owning the workspace.
${{ workspace.env['KEY'] }}	Resolves to a global workspace environment variable.

Use Case: Variable Aliasing

The ${{ workspace.env[...] }} template allows you to map global variables to specific service requirements.

For example, if a backend service expects an environment variable named PG_USER, but your database credentials are saved globally as BACKEND_PG_USER to avoid naming collisions with other databases, you can map them like this:

env:
  PG_USER: ${{ workspace.env['BACKEND_PG_USER'] }}

Syncing and Persistence

After defining the secret references, you must sync the Landscape Profile withinin the Execution Manager in the CI & Deploy mode.

The Sync Process

When the selected ci.yml contains new secret references during a landscape synchronization, the user is responsible for providing the actual secret values. The process follows these steps:

1. User Prompt: A modal appears prompting you to provide the secret entries defined in your configuration.
2. Input: You must enter the secret key and its corresponding real value at least once to initialize the entry in the vault.
3. Persistence: Once submitted, these values are persisted in the OpenBao instance.
4. Injection: The sync proceeds, and the landscape accesses the vault keys to inject them into the respective services.

The secret input modal triggered during the landscape sync process.

info

Ahead of any landscape synchronization, you can manually override existing secrets as well.

warning

Landscape synchronizations will fail if a service defined in the CI profile cannot access the secret entry it references. Ensure that all secrets are set up correctly during the first deployment of a Landscape.

Security and Access Control

Codesphere enforces strict isolation for secret access:

• Reference-Based Access: A service can only retrieve a secret if it is explicitly defined in its configuration.
• Landscape Isolation: Secrets are managed at the landscape level, ensuring that different deployment environments remain separated.

Lifecycle and Cleanup

To maintain a clean security posture, Codesphere automatically manages the lifecycle of your secrets. When a Workspace is deleted:

• All associated secret entries in the vault related to that workspace and its services are identified.
• The system performs a permanent cleanup of all related keys.
• No sensitive data remains available after the workspace is removed.