Secrets Management

slipp integrates with Ansible Vault for secure secret management. Generate secrets, store them encrypted, and use them in deployments and local development.

Quick Start

1. Generate a secret

   slipp secret
   # Output: 64 hex chars (256-bit)

2. Add to vault

   slipp secrets add vault_db_password myproject

3. Use in templates

   group_vars/all.yml

   database_password: "{{ vault_db_password }}"

4. Encrypt vault

   ansible-vault encrypt inventory/host_vars/myhost/vault.yml

Generating Secrets

Basic secret

slipp secret

Output: 64 hex characters (256-bit entropy)

Options

Length

# 16 bytes (128-bit)
slipp secret --bytes 16

# 64 bytes (512-bit)
slipp secret --bytes 64

Encoding

# Base64 encoded
slipp secret --base64

# ULID format
slipp secret --ulid

JWK

# RSA 2048-bit keypair
slipp secret --jwk

# RSA 4096-bit keypair
slipp secret --jwk --bits 4096

Managing Vaults

List available vaults

slipp secrets list

Shows all registered projects with vault files:

Available vaults:
project      vault                    secrets
myproject    inventory/.../vault.yml  5
auth-service inventory/.../vault.yml  3

List secrets in a vault

slipp secrets list myproject

Secrets in inventory/host_vars/myhost/vault.yml:
  - vault_db_password
  - vault_api_key
  - vault_jwt_secret

Get template string

slipp secrets list myproject vault_db_password
# Output: {{ vault_db_password }}

Adding Secrets

Add random secret

slipp secrets add vault_db_password myproject

Generates a random secret and adds it to the vault.

Add JWK keypair

slipp secrets add vault_signing_key myproject --jwk

Generates an RSA keypair for JWT signing.

Custom entropy

slipp secrets add vault_session_key myproject --bytes 64

Syncing Secrets

Auto-generate secrets for all {{ vault_* }} references:

slipp secrets sync inventory/host_vars/myhost/vars.yml

1. Scans the YAML file for {{ vault_* }} patterns
2. Lists found references
3. Generates random secrets for each
4. Creates vault.yml in the same directory

Caution

After sync, encrypt the vault:

ansible-vault encrypt inventory/host_vars/myhost/vault.yml

Using Secrets

In Ansible templates

Reference vault secrets in your vars files:

group_vars/all.yml

database:
  password: "{{ vault_db_password }}"

api:
  secret_key: "{{ vault_api_key }}"

In run profiles

Load vault secrets as environment variables:

slipp run dev --vault myproject --cmd "npm run dev"

Secrets are transformed and injected:

• vault_db_password becomes DB_PASSWORD
• vault_api_key becomes API_KEY

Multiple vaults

Combine secrets from multiple projects:

slipp run dev --vault myproject --vault shared-secrets

Vault Workflow

Initial setup

1. Create vars file with references

   inventory/host_vars/myhost/vars.yml

   matrix_sliding_sync_shared_secret: "{{ vault_sliding_sync_secret }}"
   matrix_postgres_connection_password: "{{ vault_postgres_password }}"

2. Generate secrets

   slipp secrets sync inventory/host_vars/myhost/vars.yml

3. Encrypt vault

   ansible-vault encrypt inventory/host_vars/myhost/vault.yml

4. Deploy

   slipp deploy
   # Prompts for vault password

Adding new secrets

1. Add to vault

   slipp secrets add vault_new_secret myproject

2. Reference in vars

   new_service_key: "{{ vault_new_secret }}"

3. Redeploy

   slipp deploy

Security Best Practices

Never commit unencrypted vaults

Always encrypt vault files before committing:

ansible-vault encrypt vault.yml

Use .gitignore

Add unencrypted vault files to .gitignore:

# Unencrypted vaults (temporary)
**/vault.yml.unencrypted

Vault password management

Store vault password securely:

• Use a password manager
• Or set ANSIBLE_VAULT_PASSWORD_FILE environment variable

Troubleshooting

Vault password incorrect?

Check you’re using the correct password. Re-encrypt if needed:

ansible-vault rekey vault.yml

Secret not found?

• Verify vault path: slipp secrets list
• Check secret name matches: slipp secrets list myproject
• Ensure vault is encrypted: file vault.yml should show “ASCII text”