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:

  1. Command flags (--workspace-dir, --log-level, etc.)
  2. Environment variables (COA_*)
  3. config/config.yaml in 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.