Configuration¶

CredProxy uses YAML-based configuration with support for environment variable substitution and file content injection. This makes it flexible for various deployment scenarios from local development to testing environments.

Authentication Methods¶

Default - AWS SDK default provider chain (EC2 instance profiles, ECS task roles, environment variables, AWS CLI profiles)
IAM Profiles - Use AWS CLI profiles to assume target roles
IAM Keys - Use AWS access keys to assume target roles

Configuration Structure¶

Basic Example¶

server:
  host: localhost
  port: 1338
  debug: false

credentials:
  refresh_buffer_seconds: 300
  retry_delay: 60

services:
  my-app:
    auth_token: "secure-token-here"
    source_credentials:
      region: "us-west-2"
    assumed_role:
      RoleArn: "arn:aws:iam::123456789012:role/MyAppRole"
      RoleSessionName: "my-app-session"
      DurationSeconds: 3600

With Environment Variable Substitution¶

services:
  my-app:
    auth_token: "${fromEnv:APP_AUTH_TOKEN}"
    source_credentials:
      region: "${fromEnv:AWS_DEFAULT_REGION}"
    assumed_role:
      RoleArn: "${fromEnv:APP_ROLE_ARN}"

With File Content Injection¶

Useful for reading secrets from files (Docker secrets, Kubernetes secrets, etc.):

services:
  my-app:
    auth_token: "${fromFile:/run/secrets/app_token}"
    source_credentials:
      region: "us-west-2"
    assumed_role:
      RoleArn: "arn:aws:iam::123456789012:role/MyAppRole"

Dynamic Services¶

CredProxy can monitor directories for service configuration files and dynamically reload them without restarting. The new per-directory format provides flexible file filtering with include/exclude patterns.

New Per-Directory Format (Recommended):

dynamic_services:
  enabled: true
  directories:
    - path: "/credproxy/dynamic"
      include_patterns: [".*\\.yaml$", ".*\\.yml$"]
      exclude_patterns: ["^\\..*", ".*~$", ".*\\.bak$"]
    - path: "/credproxy/dynamic-dev"
      include_patterns: ["^dev-.*\\.yaml$"]
      exclude_patterns: ["^\\..*"]
  reload_interval: 5

Multiple Directories with Different Patterns:

dynamic_services:
  enabled: true
  directories:
    # Production services - only YAML files, no hidden/backup files
    - path: "/credproxy/dynamic"
      include_patterns: [".*\\.yaml$", ".*\\.yml$"]
      exclude_patterns: ["^\\..*", ".*~$", ".*\\.bak$"]

    # Development services - only dev-prefixed files
    - path: "/credproxy/dynamic-dev"
      include_patterns: ["^dev-.*\\.yaml$"]
      exclude_patterns: ["^\\..*"]

    # JSON configurations (if needed)
    - path: "/credproxy/dynamic-json"
      include_patterns: [".*\\.json$"]
      exclude_patterns: ["^\\..*"]

    # Unfiltered directory - include all files
    - path: "/credproxy/dynamic-unfiltered"
      include_patterns: []
      exclude_patterns: []
  reload_interval: 5

Pattern Matching Examples:

".*\\.yaml$" - Include files ending with .yaml
"^dev-.*\\.yaml$" - Include files starting with dev- and ending with .yaml
"^\\..*" - Exclude hidden files (starting with .)
".*/production/.*\\.yaml$" - Include YAML files in production subdirectories
[""] - Empty list means include all (for include_patterns) or exclude none (for exclude_patterns)

Each file in the monitored directories should contain a single service configuration:

# /credproxy/dynamic/service1.yaml
auth_token: "service1-token"
source_credentials:
  region: "us-west-2"
assumed_role:
  RoleArn: "arn:aws:iam::123456789012:role/Service1Role"

Backward Compatibility:

The old format is still supported and automatically converted:

# Old format (still works)
dynamic_services:
  enabled: true
  directory: "/credproxy/dynamic"
  reload_interval: 5