Configuration
Workspace layout, settings, suppressions, and report metadata.
CloudOpt keeps snapshots, analysis runs, and reports in a workspace directory. Pass --workspace-dir on each command or export COA_WORKSPACE_DIR once before the session (default: ~/.cloudopt).
Workspace layout
After cloudopt init:
~/.cloudopt/
├── config/
│ ├── config.yaml # main settings
│ ├── suppressions.yaml # optional: hide known findings
│ └── report.yaml # optional: customer/project labels
├── data/
│ ├── cloudopt.db # snapshots, analysis runs, costs, metrics
│ ├── audit.jsonl # append-only audit log (workspace actions)
│ └── backups/ # default location for workspace backup
├── reports/ # generated HTML, JSON, and terraform correlation
└── tmp/ # diagnostics export default path
Settings precedence
Highest priority wins:
- Command flags (
--workspace-dir,--log-level, etc.) - Environment variables (
COA_*) config/config.yamlin the workspace
Environment variables
| Variable | Purpose |
|---|---|
COA_WORKSPACE_DIR |
Workspace root directory |
COA_LOG_LEVEL |
debug, info, warn, or error |
COA_LOG_FORMAT |
text or json |
COA_METADATA_KEY |
Optional AES-256 key material for encrypting small metadata blobs (see metadata_encryption_env) |
config.yaml settings
Fresh workspaces get these keys from cloudopt init:
| Key | Default | Purpose |
|---|---|---|
retention_complete_snapshots |
5 |
Max complete snapshots kept per account after purge/retention |
incomplete_snapshot_ttl_hours |
24 |
Hours before abandoned in-progress snapshots are removed |
metadata_encryption_env |
COA_METADATA_KEY |
Env var name holding encryption key material (optional) |
telemetry_enabled |
false |
Local telemetry flag (diagnostics export reports this; off by default) |
audit_log_path |
(empty) | Override audit log path (default: data/audit.jsonl) |
Example excerpt:
retention_complete_snapshots: 5
incomplete_snapshot_ttl_hours: 24
metadata_encryption_env: "COA_METADATA_KEY"
telemetry_enabled: false
Without COA_METADATA_KEY set, CloudOpt prefixes metadata with plain: for compatibility. Set the env var to turn on AES-256-GCM for eligible fields.
Credentials
AWS: env vars, ~/.aws/credentials, or an instance/container IAM role via the standard SDK chain.
GCP: Application Default Credentials (gcloud auth application-default login, or workload identity in CI). Pass --impersonate-service-account on collect commands for short-lived cross-project access without storing keys.
Do not put secrets in workspace config files or commit them to git.
Suppressing findings
Add accepted findings to config/suppressions.yaml:
suppressions:
- fingerprint: "<finding fingerprint from a previous report>"
reason: "Decommission scheduled for Q3"
expires_at: "2026-12-31T23:59:59Z"
Or suppress by rule and resource:
suppressions:
- rule_id: compute.stopped_instance_storage_cost
resource_id: i-0abc123def456
reason: "Reserved for DR testing"
Expired suppressions drop out automatically. Suppressed findings still show in the report appendix but not in totals.
Report metadata
Optional config/report.yaml sets header labels:
customer_name: Acme Corp
project_name: Production audit
These labels do not affect analysis or findings.
Workspace security and lifecycle
Run after init on shared or multi-user hosts:
cloudopt workspace secure-permissions
Sets directories to 0750 and config/database files to 0600.
Backup and restore before upgrades or schema changes:
cloudopt workspace backup --output "$HOME/.cloudopt/data/backups/pre-upgrade.db"
cloudopt workspace restore --from /absolute/path/to/backup.db
Restore requires an absolute path to the backup file. CloudOpt validates schema compatibility after restore.
Remove account data from the local workspace (does not touch cloud resources):
cloudopt workspace purge-account --account-id <canonical-account-id> --verify
Export without credentials:
cloudopt workspace export-diagnostics # anonymized health summary
cloudopt workspace export-archive # zip of engagement reports
Backup, restore, export, purge, and collection scope each write one JSON line to data/audit.jsonl. No resource payloads.
Collect stops at per-provider caps on resources, API calls, duration, and concurrency. Interrupted collects leave in-progress snapshots until incomplete_snapshot_ttl_hours expires.