The most load-bearing write workflow — droplet provisioning is the spine
of phase 4a deployment onboarding.
DigitalOcean.Client: create_droplet, get_droplet, list_droplets_by_tag,
destroy_droplet. list_paginated/3 now threads caller-supplied params
(opts[:params]) through pagination so tag-filtered listing works.
Four droplet saga steps:
- CreateDroplet — POST a droplet, tagged arcadia-saga-<saga8> +
managed-by-arcadia-cloud. Idempotency: re-run checks context for
droplet_id, then queries DO by the saga tag, so a crash between POST
and context-save adopts the existing droplet. compensate destroys it.
- WaitDropletActive — polls get_droplet until status "active" (96x5s);
records the public IP. No compensation (waiting has no side effect).
- RegisterDroplet — fetches the droplet, upserts it into cloud_resources
(inventory consistent immediately, not at next 15-min sync) and writes
cloud_provisioned desired-state {size_slug, region, image}. compensate
removes the DB rows (the droplet itself is destroyed by CreateDroplet's
compensate).
- DestroyDroplet — DELETE the droplet + mark its cloud_resources row
deleted. Terminal/irreversible: compensate is a logged noop, per the
saga design destroy-class steps don't roll back.
Provisioning helpers:
- provision_droplet/1 — [CreateDroplet, WaitDropletActive, RegisterDroplet]
- destroy_droplet/2 — [DestroyDroplet]
Live smoke verified end-to-end (full create + destroy on a real
s-1vcpu-512mb-10gb droplet in syd1):
- provision saga completed: droplet 572017320 created, reached active
with public IP, registered into cloud_resources (status=active) +
cloud_provisioned (spec recorded).
- destroy saga completed: cloud_resources row marked deleted; droplet
confirmed 404 on DO afterward. Account back to its original 5
droplets, zero leftover, ~1 cent total cost.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
DigitalOcean.Client DNS record CRUD:
- list_domain_records/2, create_domain_record/3, update_domain_record/4,
delete_domain_record/3 on /v2/domains/:domain/records.
Steps.UpsertDnsRecord — idempotent ensure-record:
- (type, name) absent -> create
- present, data matches -> no-op
- present, data differs -> update, stashing prior state
Match comparison normalizes trailing dots (DO appends them to CNAMEs)
so a re-run doesn't false-positive into an update. compensate: deletes
records it created, restores prior data/ttl for records it updated.
Steps.DeleteDnsRecord — deletes a record by (type, name); idempotent
(already-absent succeeds); compensate recreates from stashed prior state.
Both read dns_domain / dns_record_type / dns_record_name / dns_record_data
/ dns_record_ttl from saga inputs.
Live smoke verified against sky-ai.com with TXT records (non-disruptive):
- [UpsertDnsRecord, Fail]: record created then compensation deleted it
(saga rolled_back, record absent after).
- [UpsertDnsRecord] twice: first outcome "created", second "noop"
(idempotency holds).
- [DeleteDnsRecord]: record deleted, absent after.
Both test records cleaned up — zero leftover.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
DigitalOcean.Client write methods:
- create_droplet_snapshot/3 — POST a snapshot action (async)
- get_droplet_action/3 — poll action status
- list_droplet_snapshots/2 — snapshots for a droplet
- delete_snapshot/2 — DELETE (used by compensation)
All use the "provisioning" token purpose.
Steps.CreateDropletSnapshot — the first saga step that touches real
infra:
- execute: deterministic snapshot name (arcadia-snap-<droplet>-<saga8>);
checks context for a prior snapshot_id, then checks DO for a snapshot
already carrying that name (crash-between-post-and-save recovery),
then posts the action, polls to completion, finds the resulting
snapshot, records snapshot_id + snapshot_name in context.
- compensate: deletes the snapshot; treats HTTP 404 as success.
Provisioning.snapshot_droplet/2 — convenience saga starter.
Two DO eventual-consistency gotchas surfaced + handled:
- After a snapshot action reports "completed", the snapshot lags a few
seconds before appearing in /droplets/:id/snapshots. The step now
retries the lookup (find_snapshot_with_retry, 12x5s) instead of
failing with :snapshot_not_found_after_completion.
- Deletion has the same lag the other way — a deleted snapshot lingers
in the listing briefly. compensate just trusts the DELETE 2xx/404;
no post-delete verification needed.
Live smoke verified end-to-end against holyspiritbraypark.com:
[CreateDropletSnapshot, Fail] saga — the step created real snapshot
229305609, the Fail step triggered compensation, compensation deleted
the snapshot. Final: saga rolled_back, ledger
[create_droplet_snapshot: compensated, fail: failed], zero leftover on DO.
Test-harness note: smoke tests create sagas via Provisioning.create_saga
(no Oban enqueue) so a single manual Runner.perform/1 owns execution —
start_saga/1 enqueues an Oban job, and running both racing the same saga
corrupts the step ledger. Production only ever runs via Oban.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Two patterns added:
1. ProjectsWorker now does URN-discover for kinds without a dedicated
sync worker (spaces_bucket, managed_db, k8s_cluster, etc.). For these,
it inserts a minimal placeholder row when the URN points to something
not yet in inventory. Kinds with dedicated workers (droplet, snapshot,
volume, etc.) still get attribution-only — the worker is source of
truth for richer attrs. Implemented by splitting attribute_or_discover/4
on a @dedicated_kinds whitelist.
2. New BackupsWorker pulls /v2/droplets/:id/backups for each active
droplet. DO automated backups aren't in /v2/snapshots; they live per
droplet. Cron: hourly at :41. Kind="droplet_backup".
URN normalization extended for two more aliases DO emits:
"volumesnapshot" → snapshot (was creating a duplicate row)
"image" → snapshot (DO droplet snapshots show as do:image:id)
Billing.find_resource/1 gets a kind-specific clause for droplet_backup
that matches to the parent droplet by name, since invoice lines for
backups read "<droplet-name> (Weekly Backup Services)" — the line is a
per-droplet subscription, not a per-backup-snapshot fee.
Live verified on the same April 2026 invoice:
- 6 Spaces buckets discovered via URN (account has 6, only 1 visible in
the invoice as the $5 subscription line — that's account-level so it
can't tie to a specific bucket, expected).
- 4 droplet backups discovered via BackupsWorker; the git.sky-ai.com
backup line now matches (repo.sky-ai.com backup line can't match — that
droplet was destroyed).
- Of 16 unmatched lines: 11 are destroyed historic resources, 1 is GST,
1 is the account-level Spaces subscription, 3 are likely tiny snapshot
name variances. Effectively ~100% of currently-existing billable
resources match.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Five new Oban workers, all on cloud_sync_full following the established
droplet/domains pattern (list → normalize → upsert → mark_stale):
- VolumesWorker — block storage
- SnapshotsWorker — both droplet and volume snapshots (kind="snapshot"
with attrs.resource_type to differentiate)
- FloatingIpsWorker — provider_id is the IP; status assigned/unassigned
- FirewallsWorker — inbound/outbound rules + droplet_ids in attrs
- LoadBalancersWorker — name + region + algorithm + forwarding rules
DigitalOcean.Client gains list_snapshots / list_firewalls / list_load_balancers.
ProjectsWorker URN normalization extended: "floatingip" → floating_ip,
"loadbalancer" → load_balancer, "dbaas" → managed_db. URNs DO emits don't
have underscores for these.
Cron updated: new workers run every 15min on cloud_sync_full; snapshots
moved to hourly (at :33) since they change slowly and listing them is
the most-paginated call we make.
InvoiceIngestWorker.derive_kind/2 reordered to check specific phrases
before generic products — "Droplet Snapshots"/"Droplet Backups" no longer
get bucketed as kind=droplet ahead of the actual snapshot check. Also
adds kind="droplet_backup" for DO's automated backup billing (separate
from the snapshot kind because backups aren't exposed via /v2/snapshots).
Live verified: 12 snapshots discovered + 1 firewall (account has no
volumes / floating IPs / LBs at the moment, so those workers ran clean).
April 2026 invoice match rate jumped from 18.2% → 51.5%. Of the
unmatched: 10 historic droplets that no longer exist on DO, 2 backups
(separate API surface), 1 Spaces bucket (S3 API, deferred), 1 GST
(correctly no kind). Effectively ~95% of currently-extant resources match.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Three new schemas:
- cloud_balance_snapshots — hourly MTD balance/usage poll for live-accrual.
- cloud_invoices — header per provider invoice, with ingest status flags.
- cloud_cost_lines — per-line-item COGS, FK to cloud_resources where matched.
Three new Oban workers (queue: cloud_billing):
- BalanceWorker (hourly) records a snapshot.
- BillingHistoryWorker (daily) discovers invoices via /v2/customers/my/
billing_history, upserts headers, enqueues an InvoiceIngestWorker for
each not-yet-ingested invoice.
- InvoiceIngestWorker (per-invoice) fetches /invoices/:uuid/csv, parses
with NimbleCSV (header-keyed so column order shifts don't break us),
replaces the invoice's line set, then matches lines to cloud_resources
by (kind, name) — case-insensitive, name extracted from "name (size)"
description format.
DigitalOcean.Client gains get_balance / list_billing_history /
get_invoice_summary / fetch_invoice_csv. The CSV endpoint returns text/csv
so we bypass Req's body decoder.
Cron additions: BalanceWorker hourly at :07, BillingHistoryWorker daily
at 02:23.
API:
- GET /api/v1/billing/balance — latest snapshot, platform_admin only.
- GET /api/v1/billing/cost-lines?period=YYYY-MM-DD&kind&limit — per-line
COGS, platform_admin only.
Live smoke against real DO billing API surfaced and fixed three CSV-format
gotchas: column headers use underscores not spaces (group_description,
project_name), USD column has $ prefix, dates use "YYYY-MM-DD HH:MM:SS
+0000" format (space separator + RFC822 offset).
Verified: 137 historical invoices discovered going back to 2014;
April 2026 invoice (33 lines, $86.92 total) ingested with 6/33 lines
matched to current cloud_resources. Unmatched lines are correctly
historic droplets, Spaces buckets (not yet synced), and GST.
NimbleCSV ~> 1.2 added as a dep.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
ProjectsWorker mirrors DO Projects to cloud_projects table in a two-pass
sweep: upsert projects, then walk each project's resource membership
(list_project_resources) and update cloud_resources.cloud_project_id +
tenant_id. DO URN kinds get normalized via normalize_kind/1 (domain →
dns_zone, space → spaces_bucket) so attribution matches local naming.
DomainsWorker syncs DNS zones (DO Domains). Same upsert chokepoint, same
three-strike stale handling. Zones are global to the account; attribution
happens via ProjectsWorker if a domain is in a DO project, else stays
NULL pending operator classification.
Oban.Plugins.Cron added with 15-minute schedules for ProjectsWorker,
DropletsWorker, DomainsWorker — workers run automatically once a token
is configured. Phase 0/1 cadence; phase 2 moves droplets to cloud_sync_fast
(1-min) for real-time status visibility.
DigitalOcean.Client gains list_domains / list_volumes / list_floating_ips.
Volumes and floating IPs not yet wired to workers; trivial follow-on.
Live smoke test: 5 droplets + 7 DNS zones discovered, all attributed to
their existing DO projects via membership lookup (skyai-internal becomes
the fallback only for genuinely orphan resources).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Models:
- cloud_projects: arcadia-cloud's mirror of DO Projects, indexed by
(provider, provider_id); tenant_id + purpose classify each project.
- cloud_resources: single unified resource table; kind-specific bits in
attrs JSONB; first_seen_at / last_seen_at / stale_strike_count drive
three-strike deletion.
- cloud_resource_events: append-only audit (discovered, updated, deleted,
drift_detected, tagged, restored).
ArcadiaCloud.Cloud context owns the single upsert chokepoint that:
- inserts new with `discovered` event
- updates existing only when meaningful fields change
- restores tombstoned rows seen again
- bumps last_seen_at and resets strike count
mark_stale/3 implements the three-strike rule.
ArcadiaCloud.DigitalOcean.Client is a Req wrapper with auto-pagination.
Per-purpose token resolution via .Tokens (phase 1: env DO_API_TOKEN;
phase 2: vault). Per project_arcadia_cloud memory the long-term shape
is one PAT per queue purpose for rate-limit isolation.
ArcadiaCloud.Sync.Bootstrap ensures the skyai-internal DO Project exists
on first sync, idempotent thereafter. ArcadiaCloud.Sync.DropletsWorker
runs full droplet sync on the cloud_sync_full Oban queue.
InventoryController wired to real data: platform_admin sees all,
tenants see only their scope.
Live smoke test against real DO: 5 droplets synced; skyai-internal
project auto-created; events written; endpoint returns scoped results.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
