Configuration Validation¶

SecretZero provides comprehensive validation to ensure your configuration is correct before generating and syncing secrets. This page covers validation concepts, error messages, and best practices.

Validation Layers¶

SecretZero validates configuration at multiple layers:

Schema Validation - YAML structure and required fields
Type Validation - Data types and value formats
Semantic Validation - Logical consistency and references
Provider Validation - Provider connectivity and authentication
Policy Validation - Compliance with defined policies

Provider identity policy validation¶

provider_identity entries and per-target identity_policies references are checked when the Secretfile is loaded (secretzero validate, API POST /config/validate, and before sync). Invalid rule shapes (for example two matchers on the same rule) or unknown policy names on targets produce clear errors. Live evaluation against your cloud identity happens at sync time (and on the secretzero web dashboard preflight panel).

See Provider identity policies for examples and when to use this feature.

Schema Validation¶

Basic Validation¶

The validate command checks your Secretfile syntax and structure:

Bash

secretzero validate

Successful validation:

Text Only

Validating: Secretfile.yml
✓ Configuration is valid

Configuration Summary:
  Manifest spec version: 1
  Variables: 3
  Providers: 2
  Secrets: 5
  Templates: 1

Failed validation:

Text Only

Validating: Secretfile.yml
✗ Validation failed: secrets.0.name: Field required

Required Fields¶

The minimum valid Secretfile:

YAML

secrets: []

Common Schema Errors¶

Missing Required Secret Fields¶

Error:

Text Only

Validation failed: secrets.0.name: Field required

Fix:

YAML

secrets:
  - name: api_key
    kind: random_password

Missing Secret Name¶

Error:

Text Only

Validation failed: secret definition missing 'name' field

Fix:

YAML

secrets:
  - name: my_secret  # Add name field
    kind: random_password

Invalid Secret Kind¶

Error:

Text Only

Validation failed: unknown secret kind 'random_pass'

Fix:

YAML

secrets:
  - name: my_secret
    kind: random_password  # Use valid kind

Valid kinds:

random_password
random_string
static
script
api
templates.<template_name>

Type Validation¶

Data Type Errors¶

String vs Number¶

Error:

Text Only

Validation failed: expected string, got integer

Fix:

YAML

secrets:
  - name: db_config
    kind: static
    config:
      # Wrong: unquoted number
      port: 5432

      # Right: quoted string
      port: "5432"

Boolean Values¶

Error:

Text Only

Validation failed: expected boolean, got string 'true'

Fix:

YAML

secrets:
  - name: my_password
    kind: random_password
    config:
      # Wrong: quoted boolean
      special: "true"

      # Right: unquoted boolean
      special: true

Format Validation¶

Rotation Period¶

Error:

Text Only

Validation failed: invalid rotation_period format '90days'

Fix:

YAML

secrets:
  - name: my_secret
    # Wrong formats
    rotation_period: "90days"
    rotation_period: "3months"

    # Right formats
    rotation_period: 90d     # 90 days
    rotation_period: 2w      # 2 weeks
    rotation_period: 3m      # 3 months
    rotation_period: 1y      # 1 year

Valid suffixes:

d - days
w - weeks
m - months
y - years

Variable Interpolation¶

Error:

Text Only

Validation failed: invalid variable syntax '{{ var.name }}'

Fix:

YAML

secrets:
  - name: my_secret
    targets:
      - provider: aws
        kind: ssm_parameter
        config:
          # Wrong: spaces inside braces
          name: "{{ var.environment }}"

          # Right: no spaces
          name: "{{var.environment}}"

Semantic Validation¶

Reference Validation¶

Template References¶

Error:

Text Only

Validation failed: template 'database_creds' not found

Fix:

YAML

templates:
  database_creds:  # Define template first
    description: Database credentials
    fields:
      password:
        generator:
          kind: random_password
          config:
            length: 32

secrets:
  - name: db
    kind: templates.database_creds  # Reference defined template

Provider References¶

Error:

Text Only

Validation failed: provider 'aws-prod' not found

Fix:

YAML

providers:
  aws-prod:  # Define provider first
    kind: aws
    auth:
      kind: ambient

secrets:
  - name: my_secret
    targets:
      - provider: aws-prod  # Reference defined provider
        kind: ssm_parameter

Duplicate Names¶

Error:

Text Only

Validation failed: duplicate secret name 'api_key'

Fix:

YAML

secrets:
  # Wrong: duplicate names
  - name: api_key
    kind: random_password

  - name: api_key  # Duplicate!
    kind: static

  # Right: unique names
  - name: api_key_primary
    kind: random_password

  - name: api_key_secondary
    kind: static

Circular Dependencies¶

Error:

Text Only

Validation failed: circular variable reference detected

Fix:

YAML

variables:
  # Wrong: circular reference
  a: "{{var.b}}"
  b: "{{var.a}}"  # Circular!

  # Right: linear dependency
  base: myapp
  name: "{{var.base}}-service"
  full_name: "{{var.name}}-production"

Provider Validation¶

Testing Provider Connectivity¶

Test provider authentication and connectivity:

Bash

secretzero test

Output:

Text Only

Testing Provider Connectivity:

  • aws: ✓ Connected to AWS (us-east-1)
  • vault: ✗ Connection failed: invalid token
  • kubernetes: ✓ Connected to cluster 'production'
  • local: ✓ Local provider (always available)

Some provider tests failed. Check the messages above.

Common Provider Errors¶

AWS Authentication¶

Error:

Text Only

✗ AWS authentication failed: Unable to locate credentials

Solutions:

Configure AWS credentials:

Bash

aws configure

Use environment variables:

Bash

export AWS_ACCESS_KEY_ID=your_key
export AWS_SECRET_ACCESS_KEY=your_secret
export AWS_REGION=us-east-1

Use IAM role (if on EC2/ECS/Lambda):

YAML

providers:
  aws:
    kind: aws
    auth:
      kind: ambient  # Will use IAM role

Vault Connection¶

Error:

Text Only

✗ Vault connection failed: dial tcp: connection refused

Solutions:

Check Vault is running:

Bash

vault status

Set correct URL:

YAML

providers:
  vault:
    kind: vault
    auth:
      kind: token
      config:
        url: http://localhost:8200  # Correct URL
        token: ${VAULT_TOKEN}

Check token:

Bash

export VAULT_TOKEN=$(vault token create -format=json | jq -r .auth.client_token)

Kubernetes Access¶

Error:

Text Only

✗ Kubernetes connection failed: context 'production' not found

Solutions:

List available contexts:

Bash

kubectl config get-contexts

Use correct context:

YAML

providers:
  kubernetes:
    kind: kubernetes
    auth:
      kind: ambient
      config:
        context: correct-context-name

Or use current context:

YAML

providers:
  kubernetes:
    kind: kubernetes
    auth:
      kind: ambient  # Uses current context

Policy Validation¶

Checking Policy Compliance¶

Validate secrets against defined policies:

Bash

secretzero policy

Output:

Text Only

Checking policy compliance...

Warnings:
  ⚠ database_password: No rotation_period defined
    → Add rotation_period to enable automatic rotation

  ⚠ api_token: Rotation period 180d exceeds policy maximum of 90d
    → Reduce rotation_period to 90d or less

Info:
  ℹ service_key: One-time secret cannot be automatically rotated

Summary:
  Errors: 0
  Warnings: 2
  Info: 1

Policy Severity Levels¶

Policies can have different severity levels:

error: Blocks sync operation
warning: Allows sync but warns
info: Informational only

YAML

policies:
  rotation_required:
    kind: rotation
    require_rotation_period: true
    severity: warning  # Won't block sync
    enabled: true

  max_rotation_age:
    kind: rotation
    max_age: 90d
    severity: error  # Will block sync
    enabled: true

Fail on Warnings¶

Treat warnings as errors:

Bash

secretzero policy --fail-on-warning

This will exit with an error code if any warnings are found, useful for CI/CD pipelines.

Validation in CI/CD¶

GitHub Actions¶

YAML

name: Validate Secrets

on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - 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

      - name: Validate Configuration
        run: secretzero validate

      - name: Check Policies
        run: secretzero policy --fail-on-warning

GitLab CI¶

YAML

validate:
  stage: test
  image: python:3.11
  script:
    - pip install secretzero
    - secretzero validate
    - secretzero policy --fail-on-warning
  only:
    - merge_requests
    - main

Pre-commit Hook¶

Bash

# .git/hooks/pre-commit
#!/bin/bash

echo "Validating Secretfile..."
secretzero validate

if [ $? -ne 0 ]; then
  echo "Secretfile validation failed. Commit aborted."
  exit 1
fi

echo "Checking policies..."
secretzero policy --fail-on-warning

if [ $? -ne 0 ]; then
  echo "Policy check failed. Commit aborted."
  exit 1
fi

exit 0

Make it executable:

Bash

chmod +x .git/hooks/pre-commit

Dry Run Validation¶

Preview Changes¶

Test secret generation without making changes:

Bash

secretzero sync --dry-run

Output:

Text Only

DRY RUN: No changes will be made

Synchronizing secrets...

✓ Processed 3 secrets
  • Generated: 2
  • Skipped: 1
  • Stored: 0

Details:

  database_password [random_password]: would generate
    → aws/ssm_parameter: would store

  api_key [static]: skipped (already exists)

  redis_password [random_password]: would generate
    → aws/ssm_parameter: would store
    → kubernetes/kubernetes_secret: would store

This was a dry run. Use 'secretzero sync' to apply changes.

Benefits of Dry Run¶

Preview generation - See what would be generated
Validate targets - Check storage locations
Test configuration - Verify settings work
Safe testing - No actual changes made

Validation Best Practices¶

1. Validate Early and Often¶

Bash

# After every change
secretzero validate

# Before syncing
secretzero validate && secretzero sync --dry-run

2. Automate Validation¶

Add validation to your development workflow:

Bash

# Makefile
.PHONY: validate
validate:
    secretzero validate
    secretzero policy
    secretzero test

.PHONY: sync
sync: validate
    secretzero sync

3. Use Version Control¶

Track validation in commits:

Bash

git add Secretfile.yml
secretzero validate && git commit -m "Update secrets configuration"

4. Document Requirements¶

Add comments to your Secretfile:

YAML

version: '1.0'

# Required environment variables:
# - ENVIRONMENT: deployment environment
# - AWS_REGION: AWS region
# - API_KEY: external service API key

variables:
  environment: ${ENVIRONMENT}
  aws_region: ${AWS_REGION}

5. Test Provider Access¶

Regularly test provider connectivity:

Bash

# In CI/CD pipeline
secretzero test || exit 1

6. Maintain Policy Compliance¶

Keep policies up to date:

YAML

policies:
  # SOC2 compliance
  rotation_required:
    kind: rotation
    require_rotation_period: true
    severity: error
    enabled: true

  max_rotation_age:
    kind: rotation
    max_age: 90d  # Required by policy
    severity: error
    enabled: true

Troubleshooting Validation¶

Get Detailed Error Information¶

For complex validation errors, check:

YAML syntax:

Bash

# Check YAML is valid
python -c "import yaml; yaml.safe_load(open('Secretfile.yml'))"

Variable expansion:

Bash

# Show resolved variables
secretzero validate --verbose

Provider configuration:

Bash

# Test individual provider
secretzero test --provider aws

Common Mistakes¶

Incorrect Indentation¶

YAML

# Wrong
secrets:
- name: my_secret
  kind: random_password
  targets:
  - provider: aws
    kind: ssm_parameter

# Right
secrets:
  - name: my_secret
    kind: random_password
    targets:
      - provider: aws
        kind: ssm_parameter

Missing Quotes¶

YAML

# Wrong
variables:
  account: 123456789012  # Interpreted as number

# Right
variables:
  account: "123456789012"  # String

Trailing Spaces¶

Some YAML parsers reject trailing whitespace. Use a linter:

Bash

yamllint Secretfile.yml

Enable Debug Mode¶

Set environment variable for detailed output:

Bash

export SECRETZERO_DEBUG=1
secretzero validate

Error Reference¶

Common Error Codes¶

Code	Error	Solution
`E001`	Missing required field	Add the required field
`E002`	Invalid field type	Use correct data type
`E003`	Unknown reference	Define referenced entity
`E004`	Duplicate name	Use unique names
`E005`	Invalid format	Fix format/syntax
`E006`	Provider connection failed	Check provider config
`E007`	Policy violation	Fix policy compliance issue
`E008`	Circular dependency	Remove circular references

Getting Help¶

If validation fails and you can't determine why:

Check Troubleshooting Guide
Review Examples for reference
Search GitHub Issues
Ask in Discussions

Next Steps¶

Secretfile Reference

Complete specification of Secretfile.yml

Read Reference →
Variables

Learn about variable interpolation

Variable Guide →
CLI Commands

Use validation commands

CLI Reference →
Troubleshooting

Solve common problems

Troubleshooting →