Secrets Management¶

The Windsor CLI provides tools for managing secrets within your projects. This guide covers the setup and usage of the secrets management functionality, including integration with SOPS and 1Password.

Overview¶

The secrets management system in Windsor CLI is designed to securely handle sensitive information such as API keys, passwords, and other confidential data. It supports multiple backends, allowing you to choose the most suitable provider for your needs.

Windsor supports multiple secrets providers simultaneously. Once a provider is configured, you may inject secrets in to your environment by setting these values on your context's environment key in windsor.yaml:

version: v1alpha1
contexts:
  local:
    environment:
      CRITERION_PASSWORD: ${{ op.personal["The Criterion Channel"]["password"] }}
...

Where op represents the onepassword secrets provider, and personal is a reference to the 1Password vault where you have stored your secrets.

Supported Providers¶

SOPS¶

The Windsor CLI integrates with SOPS (Secrets OPerationS). SOPS is a tool that encrypts and decrypts secrets to a file, allowing you to commit sensitive values to a repository securely. If you would like to use SOPS in your project, it is expected that you visit their documentation and configure it correctly with an appropriate sops.yaml file.

To use SOPS with Windsor, run sops contexts/<context-name>/secrets.enc.yaml to encrypt your secrets file. As long as this file exists and is a valid SOPS-encrypted file, these values are available to use in your environment configuration as follows:

version: v1alpha1
contexts:
  local:
    environment:
      CRITERION_PASSWORD: ${{ sops.streaming.criterion.password }}
...

1Password CLI¶

The Windsor CLI integrates with the 1Password CLI. It can import secrets from multiple accounts and vaults. To configure a 1Password vault, add the following to your windsor.yaml:

...
version: v1alpha1
contexts:
  local:
    ...
    secrets:
      onepassword:
        vaults:
          personal:
            url: my.1password.com
            vault: "Personal"
          development:
            url: my-company.1password.com
            vault: "Development"
...

With this configuration in place, you can reference these secrets in your environment configuration as follows:

version: v1alpha1
contexts:
  local:
    environment:
      LOCALSTACK_API_KEY: ${{ op.personal.localstack.api_key }}
      STRIPE_API_KEY: ${{ op.development.stripe.api_key }}

When you have configured 1Password in your environment, you will likely be prompted to authenticate with 1Password. This creates a session, and you will not be prompted again until that session has been expired, lasting typically 30 minutes.

Caching¶

Secrets from remote providers are cached in-memory in your environment to improve performance and reduce unnecessary service calls or re-authentication. If a secret has already been defined in your environment, it will not be retrieved again. If you would like to trigger a refresh of your secrets, you may either:

BashPowerShell

Start a new shell session, or
Set the NO_CACHE environment variable to true:
```
NO_CACHE=true windsor init
```

Start a new PowerShell session, or
Set the NO_CACHE environment variable to true:
```
$env:NO_CACHE = "true"
windsor init
```

Troubleshooting¶

If you are having difficulty with your secrets, you may export your secret to the terminal and inspect it. If there has been an error, it will be included as the value of your environment variable, e.g.:

BashPowerShell

$ env | grep '<ERROR'
MY_SECRET=<ERROR: secret not found>

PS> Get-ChildItem Env: | Where-Object { $_.Value -like '*<ERROR*' }
MY_SECRET=<ERROR: secret not found>

Security Recommendations¶

For more details about Windsor's use of secrets along with our recommendations for securely using secrets in your environment, see the section on Securing Secrets.