Secrets

Secrets are custom credentials—API keys, passwords, tokens, and other sensitive values—that can be injected into your assets during execution. They complement connections for cases where you need direct access to credentials in your code.

Overview

There are two main approaches to managing secrets in Bruin:

1. Generic Connections: Key-value pairs defined in .bruin.yml and injected as environment variables
2. External Secret Providers: Integration with secret management solutions like Vault, Doppler, or AWS Secrets Manager

Generic Connections

Generic connections are key-value pairs that inject secrets into your assets:

# .bruin.yml
environments:
  default:
    connections:
      generic:
        - name: MY_API_KEY
          value: "sk-abc123..."
        - name: SLACK_WEBHOOK
          value: "https://hooks.slack.com/..."

Access these in your Python and R assets via environment variables:

"""@bruin
name: my_api_asset
secrets:
  - key: MY_API_KEY
@bruin"""

import os

api_key = os.environ["MY_API_KEY"]
# Use the API key...

Injecting Secrets into Assets

To inject secrets into an asset, specify them in the asset definition. Secret mappings are exposed as environment variables for Python and R assets (they are not available in the SQL/Jinja context):

"""@bruin
name: tier1.external_data
secrets:
  - key: MY_API_KEY
  - key: SLACK_WEBHOOK
    inject_as: WEBHOOK_URL
@bruin"""

import os

api_key = os.environ["MY_API_KEY"]
webhook = os.environ["WEBHOOK_URL"]  # Injected with a different name

The inject_as field allows you to rename the environment variable. If a secret key points to a non-generic connection, Bruin injects the connection details as a JSON string.

Pipeline-Level Secrets

You can define default secrets at the pipeline level that apply to all assets:

# pipeline.yml
name: analytics-daily

default:
  secrets:
    - key: MY_API_KEY
      inject_as: API_KEY
    - key: DATABASE_PASSWORD

External Secret Providers

For production environments, Bruin supports external secret management solutions:

Provider	Documentation
HashiCorp Vault	Vault Integration
Doppler	Doppler Integration
AWS Secrets Manager	AWS Secrets Manager
Azure Key Vault	--secrets-backend azure

Using an External Provider

Supported values for --secrets-backend (and BRUIN_SECRETS_BACKEND) are vault, doppler, aws, and azure.

Specify the secrets backend when running:

# Use Doppler
bruin run --secrets-backend doppler

# Use Vault
bruin run --secrets-backend vault

# Use AWS Secrets Manager
bruin run --secrets-backend aws

# Use Azure Key Vault
bruin run --secrets-backend azure

Or set via environment variable:

export BRUIN_SECRETS_BACKEND=doppler
bruin run

Environment Variables in .bruin.yml

Reference system environment variables in your .bruin.yml connection configuration. This example uses literal values for clarity:

environments:
  default:
    connections:
      postgres:
        - name: my_postgres
          username: "bruin_user"
          password: "super_secret"
          host: "db.example.com"

NOTE

You can reference environment variables in connection fields using ${VAR_NAME} placeholders, which are expanded at runtime.

Environment variables are expanded at runtime, allowing you to:

• Keep sensitive values out of configuration files
• Use different values in different deployment environments
• Integrate with CI/CD secret injection

Best Practices

1. Never commit secrets: Ensure .bruin.yml is in .gitignore
2. Use environment variables: Reference ${VAR} syntax instead of hardcoding values
3. Minimize secret scope: Only inject secrets into assets that need them
4. Use external providers in production: Vault, Doppler, or AWS Secrets Manager provide better security and auditing

Related Topics

• Project - Configure your project and environments
• Connections - Built-in platform connections
• .bruin.yml Reference - Complete configuration reference