Complete Working Examples¶

This page provides end-to-end examples for common SecretZero use cases with detailed explanations and step-by-step instructions.

Example 1: Local Development Setup¶

Use Case: Developer workstation with no cloud dependencies

What You'll Learn: - Basic Secretfile structure - Local file generation - Environment variable management - Simple rotation policies

Configuration¶

Create Secretfile.yml:

version: '1.0'

metadata:
  project: local-dev
  description: Local development secrets

providers:
  local:
    kind: local
    config: {}

secrets:
  # Database password for local PostgreSQL
  - name: postgres_password
    kind: random_password
    config:
      length: 20
      special: true
    rotation_period: 90d
    targets:
      - provider: local
        kind: file
        config:
          path: .env
          format: dotenv
          merge: true

  # API key for external service
  - name: api_key
    kind: random_string
    config:
      length: 32
      charset: alphanumeric
    rotation_period: 30d
    targets:
      - provider: local
        kind: file
        config:
          path: .env
          format: dotenv
          merge: true

  # JWT secret (generated once)
  - name: jwt_secret
    kind: random_string
    config:
      length: 64
      charset: base64
    one_time: true
    targets:
      - provider: local
        kind: file
        config:
          path: .env
          format: dotenv
          merge: true

Step-by-Step Usage¶

Install SecretZero:
```
pip install secretzero
```
Validate Configuration:
```
secretzero validate
```
Preview Changes (Dry Run):
```
secretzero sync --dry-run
```
Generate Secrets:
```
secretzero sync
```
View Generated Secrets:
```
cat .env
```

Output:

POSTGRES_PASSWORD=X9k#mP2$vN8qR4&tY7
API_KEY=a8f2d9c4e1b7f3g5h8j9k2l4m6n8p1q3
JWT_SECRET=aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789+/==

Check Rotation Status:
```
secretzero rotation check
```

Use in Your Application:

import os
from dotenv import load_dotenv

load_dotenv()

db_password = os.getenv('POSTGRES_PASSWORD')
api_key = os.getenv('API_KEY')
jwt_secret = os.getenv('JWT_SECRET')

Example 2: AWS Production Deployment¶

Use Case: Production application on AWS with secrets in SSM and Secrets Manager

What You'll Learn: - AWS provider configuration - Multiple target types - Production-grade rotation - Compliance policies

Prerequisites¶

# Install AWS support
pip install secretzero[aws]

# Configure AWS credentials
aws configure

Configuration¶

Create Secretfile.yml:

version: '1.0'

metadata:
  project: production-app
  environment: production
  owner: platform-team
  compliance:
    - soc2
    - iso27001

variables:
  environment: production
  region: us-east-1
  app_name: myapp

providers:
  aws:
    kind: aws
    auth:
      kind: ambient
      region: "{{ var.region }}"

secrets:
  # Database credentials in SSM
  - name: rds_master_password
    kind: random_password
    config:
      length: 32
      special: true
      upper: true
      lower: true
      number: true
    rotation_period: 30d
    targets:
      - provider: aws
        kind: ssm_parameter
        config:
          name: /{{ var.environment }}/{{ var.app_name }}/db/master-password
          type: SecureString
          tier: Standard
          tags:
            Environment: "{{ var.environment }}"
            Application: "{{ var.app_name }}"
            ManagedBy: SecretZero

  # API keys in Secrets Manager (with automatic rotation)
  - name: third_party_api_key
    kind: random_string
    config:
      length: 40
      charset: alphanumeric
    rotation_period: 90d
    targets:
      - provider: aws
        kind: secrets_manager
        config:
          name: "{{ var.app_name }}/third-party-api-key"
          description: "API key for third-party service"
          kms_key_id: alias/aws/secretsmanager
          tags:
            - key: Environment
              value: "{{ var.environment }}"
            - key: Application
              value: "{{ var.app_name }}"

  # Redis password (shared across services)
  - name: redis_password
    kind: random_password
    config:
      length: 24
      special: false  # Redis doesn't handle special chars well
    rotation_period: 60d
    targets:
      # Store in SSM for application access
      - provider: aws
        kind: ssm_parameter
        config:
          name: /{{ var.environment }}/{{ var.app_name }}/redis/password
          type: SecureString
      # Also store in Secrets Manager for Lambda functions
      - provider: aws
        kind: secrets_manager
        config:
          name: "{{ var.app_name }}/redis-password"

policies:
  # Enforce rotation
  rotation_policy:
    kind: rotation
    config:
      require_rotation_period: true
      max_rotation_period: 90d
      warn_before_expiry: 7d
    severity: error

  # SOC2 compliance
  soc2_policy:
    kind: compliance
    config:
      standard: soc2
      require_encryption: true
      require_audit_logging: true
    severity: error

Step-by-Step Deployment¶

Test AWS Connectivity:
```
secretzero test --provider aws
```

Validate Configuration:

secretzero validate
secretzero policy check

Dry Run:
```
secretzero sync --dry-run
```
Deploy Secrets:
```
secretzero sync
```

Verify in AWS:

# Check SSM Parameter
aws ssm get-parameter \
  --name /production/myapp/db/master-password \
  --with-decryption

# Check Secrets Manager
aws secretsmanager get-secret-value \
  --secret-id myapp/third-party-api-key

Use in Application (Python/Boto3):

import boto3

ssm = boto3.client('ssm', region_name='us-east-1')
secrets = boto3.client('secretsmanager', region_name='us-east-1')

# Get from SSM
db_password = ssm.get_parameter(
    Name='/production/myapp/db/master-password',
    WithDecryption=True
)['Parameter']['Value']

# Get from Secrets Manager
api_key = secrets.get_secret_value(
    SecretId='myapp/third-party-api-key'
)['SecretString']

Set Up Rotation Schedule (cron):

# Add to crontab
0 2 * * * cd /opt/secretzero && secretzero rotation execute

Example 3: Kubernetes Integration¶

Use Case: Managing Kubernetes Secrets with SecretZero

What You'll Learn: - Kubernetes provider setup - Native Secret objects - Multiple namespaces - Integration with deployments

Prerequisites¶

# Install Kubernetes support
pip install secretzero[kubernetes]

# Ensure kubectl is configured
kubectl cluster-info

Configuration¶

Create Secretfile.yml:

version: '1.0'

metadata:
  project: k8s-app
  description: Kubernetes secret management

variables:
  namespace: default
  app_name: myapp

providers:
  kubernetes:
    kind: kubernetes
    auth:
      kind: ambient
      config:
        # Uses default kubeconfig
        # context: my-cluster

secrets:
  # Application database password
  - name: postgres_password
    kind: random_password
    config:
      length: 24
      special: true
    rotation_period: 90d
    targets:
      - provider: kubernetes
        kind: kubernetes_secret
        config:
          namespace: "{{ var.namespace }}"
          secret_name: "{{ var.app_name }}-db"
          data_key: password
          secret_type: Opaque
          labels:
            app: "{{ var.app_name }}"
            component: database
          annotations:
            managed-by: secretzero
            rotation-period: 90d

  # Redis credentials
  - name: redis_password
    kind: random_password
    config:
      length: 16
      special: false
    rotation_period: 60d
    targets:
      - provider: kubernetes
        kind: kubernetes_secret
        config:
          namespace: "{{ var.namespace }}"
          secret_name: "{{ var.app_name }}-cache"
          data_key: redis-password
          labels:
            app: "{{ var.app_name }}"
            component: cache

  # API credentials (multiple keys in one Secret)
  - name: api_key
    kind: random_string
    config:
      length: 32
      charset: hex
    targets:
      - provider: kubernetes
        kind: kubernetes_secret
        config:
          namespace: "{{ var.namespace }}"
          secret_name: "{{ var.app_name }}-api"
          data_key: api-key
          labels:
            app: "{{ var.app_name }}"

  - name: api_secret
    kind: random_string
    config:
      length: 64
      charset: base64
    targets:
      - provider: kubernetes
        kind: kubernetes_secret
        config:
          namespace: "{{ var.namespace }}"
          secret_name: "{{ var.app_name }}-api"  # Same Secret
          data_key: api-secret
          labels:
            app: "{{ var.app_name }}"

Step-by-Step Usage¶

Test Kubernetes Access:
```
secretzero test --provider kubernetes
```
Generate Secrets:
```
secretzero sync
```

Verify Secrets Created:

kubectl get secrets -l app=myapp
kubectl describe secret myapp-db
kubectl describe secret myapp-cache
kubectl describe secret myapp-api

Create Deployment Using Secrets:

Create deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
  namespace: default
spec:
  replicas: 3
  selector:
    matchLabels:
      app: myapp
  template:
    metadata:
      labels:
        app: myapp
    spec:
      containers:
      - name: app
        image: myapp:latest
        env:
        # Database credentials
        - name: POSTGRES_PASSWORD
          valueFrom:
            secretKeyRef:
              name: myapp-db
              key: password
        # Redis credentials
        - name: REDIS_PASSWORD
          valueFrom:
            secretKeyRef:
              name: myapp-cache
              key: redis-password
        # API credentials
        - name: API_KEY
          valueFrom:
            secretKeyRef:
              name: myapp-api
              key: api-key
        - name: API_SECRET
          valueFrom:
            secretKeyRef:
              name: myapp-api
              key: api-secret

Deploy Application:
```
kubectl apply -f deployment.yaml
```

Verify Application:

kubectl get pods -l app=myapp
kubectl logs -l app=myapp --tail=50

Rotate Secrets:

# Check rotation status
secretzero rotation check

# Rotate secrets
secretzero rotation execute

# Restart pods to pick up new secrets
kubectl rollout restart deployment/myapp

Example 4: CI/CD Pipeline Integration¶

Use Case: Automating secret management in GitHub Actions

What You'll Learn: - CI/CD integration - Automated rotation - Policy enforcement - Drift detection

GitHub Actions Workflow¶

Create .github/workflows/secrets.yml:

name: Secret Management

on:
  schedule:
    # Check rotation daily at 2 AM
    - cron: '0 2 * * *'
  workflow_dispatch:
  push:
    paths:
      - 'Secretfile.yml'

jobs:
  manage-secrets:
    runs-on: ubuntu-latest
    permissions:
      id-token: write  # For OIDC
      contents: read

    steps:
      - name: Checkout
        uses: actions/checkout@v3

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'

      - name: Install SecretZero
        run: pip install secretzero[all]

      - name: Configure AWS Credentials
        uses: aws-actions/configure-aws-credentials@v2
        with:
          role-to-assume: ${{ secrets.AWS_ROLE_ARN }}
          aws-region: us-east-1

      - name: Validate Configuration
        run: |
          secretzero validate
          secretzero policy check --fail-on-warning

      - name: Check Rotation Status
        id: rotation
        run: |
          secretzero rotation check --json > rotation.json
          cat rotation.json

          # Check if any secrets are overdue
          overdue=$(jq -r '.secrets_overdue | length' rotation.json)
          echo "overdue=$overdue" >> $GITHUB_OUTPUT

      - name: Check for Drift
        run: secretzero drift check

      - name: Execute Rotation
        if: steps.rotation.outputs.overdue > 0
        run: secretzero rotation execute

      - name: Generate Audit Report
        run: |
          secretzero audit report --format json > audit-report.json

      - name: Upload Audit Report
        uses: actions/upload-artifact@v3
        with:
          name: audit-report
          path: audit-report.json

      - name: Notify on Failure
        if: failure()
        uses: slackapi/slack-github-action@v1
        with:
          webhook-url: ${{ secrets.SLACK_WEBHOOK }}
          payload: |
            {
              "text": "SecretZero workflow failed!",
              "blocks": [
                {
                  "type": "section",
                  "text": {
                    "type": "mrkdwn",
                    "text": "❌ Secret management workflow failed in ${{ github.repository }}"
                  }
                }
              ]
            }

Secretfile for CI/CD¶

version: '1.0'

metadata:
  project: cicd-secrets
  description: Secrets managed via CI/CD

providers:
  aws:
    kind: aws
    auth:
      kind: ambient  # Uses GitHub OIDC

secrets:
  - name: prod_db_password
    kind: random_password
    config:
      length: 32
      special: true
    rotation_period: 30d
    targets:
      - provider: aws
        kind: ssm_parameter
        config:
          name: /prod/db/password
          type: SecureString

policies:
  rotation_enforcement:
    kind: rotation
    config:
      require_rotation_period: true
      max_rotation_period: 90d
    severity: error

Usage¶

Initial Setup:

# Commit Secretfile
git add Secretfile.yml
git commit -m "Add Secretfile configuration"
git push

Manual Trigger:
Go to Actions tab in GitHub
Select "Secret Management" workflow
Click "Run workflow"
Monitor Execution:
View workflow logs
Check audit reports in artifacts
Review rotation status
Automatic Rotation:
Workflow runs daily at 2 AM
Checks for overdue secrets
Rotates automatically if needed

Example 5: Multi-Cloud Enterprise Setup¶

Use Case: Large organization using AWS, Azure, and Vault

What You'll Learn: - Multi-provider configuration - Complex secret distribution - Enterprise policies - Centralized management

Configuration¶

Create Secretfile.yml:

version: '1.0'

metadata:
  project: enterprise-secrets
  organization: acme-corp
  compliance:
    - soc2
    - hipaa
    - pci-dss

variables:
  environment: production
  aws_region: us-east-1
  azure_region: eastus
  vault_url: https://vault.example.com

providers:
  aws:
    kind: aws
    auth:
      kind: assume_role
      role_arn: arn:aws:iam::123456789012:role/SecretZeroRole
      region: "{{ var.aws_region }}"

  azure:
    kind: azure
    auth:
      kind: managed_identity
      client_id: 12345678-1234-1234-1234-123456789012

  vault:
    kind: vault
    auth:
      kind: token
      token: "${VAULT_TOKEN}"
      url: "{{ var.vault_url }}"

  local:
    kind: local

secrets:
  # Critical database password - stored everywhere
  - name: master_db_password
    kind: random_password
    config:
      length: 32
      special: true
    rotation_period: 30d
    targets:
      # AWS for EC2 instances
      - provider: aws
        kind: ssm_parameter
        config:
          name: /prod/db/master-password
          type: SecureString
      # Azure for AKS clusters
      - provider: azure
        kind: key_vault
        config:
          vault_url: https://acme-prod-kv.vault.azure.net
          secret_name: master-db-password
      # Vault for on-prem services
      - provider: vault
        kind: kv
        config:
          path: prod/db/master-password
          mount_point: secret
      # Local backup
      - provider: local
        kind: file
        config:
          path: backups/master-password.txt
          format: raw

  # Application secrets per cloud
  - name: aws_api_key
    kind: random_string
    config:
      length: 40
    rotation_period: 90d
    targets:
      - provider: aws
        kind: secrets_manager
        config:
          name: prod/api-key
      - provider: vault
        kind: kv
        config:
          path: aws/api-key

  - name: azure_api_key
    kind: random_string
    config:
      length: 40
    rotation_period: 90d
    targets:
      - provider: azure
        kind: key_vault
        config:
          vault_url: https://acme-prod-kv.vault.azure.net
          secret_name: api-key
      - provider: vault
        kind: kv
        config:
          path: azure/api-key

policies:
  enterprise_rotation:
    kind: rotation
    config:
      require_rotation_period: true
      max_rotation_period: 90d
      warn_before_expiry: 14d
    severity: error

  compliance:
    kind: compliance
    config:
      standards:
        - soc2
        - hipaa
        - pci-dss
      require_encryption: true
      require_audit: true
      require_mfa: true
    severity: error

  access_control:
    kind: access
    config:
      require_approval: true
      allowed_targets:
        - aws_ssm
        - azure_key_vault
        - vault_kv
      deny_local: true  # No local files in production
    severity: error

Deployment¶

Set Up Credentials:

# AWS
aws configure

# Azure
az login

# Vault
export VAULT_TOKEN=your-token
export VAULT_ADDR=https://vault.example.com

Validate Everything:

# Test all providers
secretzero test

# Validate configuration
secretzero validate

# Check policies
secretzero policy check --fail-on-warning

Deploy:

# Dry run first
secretzero sync --dry-run

# Deploy to all clouds
secretzero sync

Verify Across Clouds:

# AWS
aws ssm get-parameter --name /prod/db/master-password

# Azure
az keyvault secret show \
  --vault-name acme-prod-kv \
  --name master-db-password

# Vault
vault kv get secret/prod/db/master-password

Next Steps¶

Explore more examples in the GitHub repository
Learn about API usage
Read the Configuration Guide
Check Best Practices