Repository navigation
No CLI command applies one Domain: its vhost and certificate come only from migrate, which converges every server #87
Description
Problem
Found while deploying Abecra's staging on 2026-10-19 to a server lent from another fleet. That server's baseline, firewall and services belong to its owner's project, so the Abecra project may run per-component cloudfall deploy on it, never migrate or baseline convergence.
The Domain was declared (abecra.cloudfall.dev, proxy and origin on the lent server), but there was no safe way to apply it:
cloudfall migrateis the only CLI path todomains.yml(sdk/src/cloudfall/migrate.py: stepsdomains-http,dns-verify,domains-tls), and the same plan runsbaselineandserviceson every declared server first- the
converge_domainsMCP tool runsdomains.ymlwithout the baseline, but it is MCP only, renders every declared domain on every server incloudfall_servers, and takes no domain or server argument task domains:deployexists in the repository Taskfile, not in the installed CLI
So the nginx vhost and the Let's Encrypt certificate were written by hand, outside the receipts, and the next domains.yml run from anywhere will overwrite that file with no record of what it replaced.
Proposal
A domains command group matching deploy's shape:
cloudfall domains apply <domain> [--issue-certificate] [--yes]
cloudfall domains observe <domain>
applyrunscloudfall_nginx_sitefor one Domain, limited to itsproxy.server(andorigin.serverwhen it differs); without--yesit shows the plan, likedeploy--issue-certificateruns the HTTP-then-TLS sequencemigrateuses (domains-http, then issuance), refusing when DNS forprimaryNameandaliasesdoes not resolve to the proxy server- It touches no baseline, firewall or service, so it is safe on a server whose baseline another project owns
- A
DeploymentReceiptper run, as today, with the hash of the vhost it replaced if one was there - The same scoping (
domainargument) added to theconverge_domainsMCP tool
Alternatives
migrate --only domains-http,domains-tls: reuses the plan, but a step filter on a resumable plan is easy to get wrong and still reads as "migrate"- A server-level
managedBaseline: falseflag that makesmigrateskip baseline on lent servers: useful too, but a per-domain command is needed regardless (adding a domain to a running fleet should not mean rerunning a migration)
Acceptance
- In a project with two servers,
cloudfall domains apply <d> --yeschanges only the Domain's proxy server, and its Ansible run reports no baseline, firewall or service tasks --issue-certificateon a fresh domain ends with a valid Let's Encrypt certificate,certbot.timerenabled, and a receipt; a second run reports no changes- Without
--yesit exits 0 and changes nothing - An unknown domain id fails with
CONFIG_INVALIDbefore any SSH connection
Activity
shipmill-romamo commentedon Oct 20, 2026
Triage: feature.
Confirmed on main (348ed73):
cloudfall migrate(sdk/src/cloudfall/migrate.py) is the only CLI path todomains.yml, and its plan convergesbaselineandservicesfirst;converge_domainsis MCP only and takes no domain or server. A scopedcloudfall domains apply/observeis a new command group with its own plan, receipts and certificate sequence, so it gets a spec with acceptance criteria first, covering theconverge_domainsscoping too.Writing it alongside #88's spec, since both extend the per-component deploy shape (plan without
--yes, a receipt per run).The spec PR is being written now (
docs/specs/004-domains-apply.md); I'll put its link and the hold line here. Merging it is the approval.shipmill-romamo commentedon Oct 20, 2026
The spec is in #100 (
docs/specs/004-domains-apply.md). Where it departs from the issue, following the code: an unknown domain exitsPRECONDITIONlikedeploy's unknown component, notCONFIG_INVALID;applytouches only the proxy server, since no playbook acts onorigin.server; DNS is checked once before a single role run, and skipped for proxied edges asmigratedoes. The new optional receipt field means an oldercloudfallrejects the newer receipts, which is worth a look in review.On hold: the build waits on #100, the spec
Spec domains apply and observe for #87 (#100)
shipmill-romamo commentedon Oct 27, 2026
The spec merged in #100 on your approval:
docs/specs/004-domains-apply.md. Its build is split into #116 (one Domain indomains.yml, the previous vhost hash), #117 (domains apply, after #116) and #118 (domains observeand the MCP tools, after #117); this issue closes when the last of them does.shipmill-romamo commentedon Oct 27, 2026
Done: spec S-004 (
docs/specs/004-domains-apply.md) isstatus: built, every criterion verified (the live certificate issue and realopenssl/systemctlreads are proven with stand-ins, as its Verification section says), and each build issue has closed:16dcbe1)8ac1c34)cloudfall domains apply <d> [--issue-certificate] [--yes]now applies one Domain's vhost and certificate on its proxy server only,cloudfall domains observe <d>reads its state back, and both are MCP tools. It ships in the next release candidate after v0.8.0rc6.