Secrets Management
Secrets management in Expanso Edge encompasses multiple layers of security, from initial agent registration to runtime pipeline configuration. This guide covers best practices for handling credentials across different deployment environments.
Architecture Overview
Expanso Edge uses secrets at two distinct layers:
1. Bootstrap Secrets
Purpose: Initial agent registration and authentication with Expanso Cloud.
When used: During edge agent startup to establish trust and register the node.
Common approaches:
- Local files with restricted permissions
- Environment variables in systemd services
- Docker/Kubernetes native secret stores
Learn more: Bootstrapping Secrets →
2. Pipeline Credentials
Purpose: Runtime credentials for data sources, destinations, and processors — database passwords, API tokens, message-queue auth, cloud credentials.
When used: When pipelines connect to databases, APIs, message queues, or other authenticated services.
Recommended approach:
- Secret Providers — declare backends and credential references directly in the JobSpec. The edge agent fetches values from HashiCorp Vault, AWS Secrets Manager, AWS Parameter Store, AWS STS, GCP Secret Manager, Azure Key Vault, or local files; caches them; and refreshes them on a schedule. Rotation in the backend flows through to the running pipeline without redeployment.
Alternative approaches (for setups where the edge agent cannot reach the secret store directly):
- Environment-variable interpolation — see Local Secrets
- Sidecar / init-container / CSI-driver injection (Vault Agent, External Secrets Operator, CSI Secret Store Driver) — see External Secret Managers
Security Principles
All secret management approaches should follow these principles:
1. Never Hard-Code Secrets
- Don't commit secrets to version control
- Use
.envfiles locally and add to.gitignore - Reference secrets via environment variables or files
2. Restrict Access
- Use file permissions (e.g.,
chmod 600) for local files - Limit service account permissions in Kubernetes
- Apply least-privilege IAM roles in cloud environments
3. Enable Auditability
- Log secret access (but not values)
- Use centralized secret stores for audit trails
- Track which pipelines use which credentials
4. Rotate Regularly
- Implement automated rotation schedules
- Update secrets without redeploying pipelines
- Monitor for expiring credentials
5. Separate Concerns
- Use different credentials per environment (dev/staging/prod)
- Isolate secrets by pipeline or application
- Don't reuse bootstrap tokens across agents
Secret Types Reference
| Secret Type | Example Use Case | Recommended Storage |
|---|---|---|
| Bootstrap Token | Agent registration | Local file, K8s Secret, Docker Secret |
| Database Password | PostgreSQL connection | Environment variable, Vault |
| API Key | HTTP output authentication | Environment variable, AWS SM |
| TLS Certificate | Mutual TLS connections | Local file, K8s Secret, mounted volume |
| OAuth Token | Third-party API access | Vault with TTL, AWS SM |
| Encryption Key | Data encryption at rest | KMS, Vault Transit |
Choosing an Approach
For Production (Recommended)
→ Secret Providers — declare your secret backend in the JobSpec; the edge agent fetches credentials directly from Vault, AWS, GCP, Azure, or files. Centralized, auditable, with built-in rotation.
For Development/Testing
→ Local Secrets — simple file-based or environment-variable approach.
When the Agent Cannot Reach the Secret Store Directly
→ External Secret Managers — sidecar, init-container, or CSI-driver injection patterns.
Next Steps
- Configuring Pipelines? Start with Secret Providers — the recommended way to supply credentials to pipelines.
- Need backend-specific fields? See Provider Reference for per-provider field tables.
- Getting Started? See Bootstrapping Secrets to register your first edge agent.
- Can't reach the secret store from the agent? Review Local Secrets or External Secret Managers for alternatives.