01The endpoint is the system of record
Lifecycle state is derived from what endpoints are observed presenting. The issuance log records what was attempted; only an observation records what is true.
ADR-0121 views, in reading order. Every view ships three ways: an HTML page, an SVG that re-opens in diagrams.net fully editable, and draw.io source.
Twenty-one views in seven acts, for a service that issues, renews, verifies and revokes every X.509 certificate a mid-size B2B SaaS depends on — 24,000 customer custom domains on public trust, 3,800 workload identities on private trust. Read them in order: the argument runs from what sits inside the boundary, through who the system is for and what they get to do, to the structure, the data, the runtime, the operations and finally the assurance. One rule decides the shape of everything after act 2: the issuance log is not the truth, the endpoint is.
The issuance log is not the truth. The endpoint is. A certificate is SERVING because something was observed presenting it, never because an issuance succeeded.
A mid-size B2B SaaS depends on two populations of certificate that behave nothing alike. Twenty-four thousand customer-owned domains are pointed at the platform by tenants who expect a padlock in browsers the platform has no relationship with; three thousand eight hundred internal workloads authenticate each other over mTLS under a certificate authority the platform runs itself. Both populations expire. Expiry is the most preventable failure in production software — a known date, in a machine-readable field, on a certificate the company usually issued to itself — and it still takes down household-name services every year. It does so for a reason that is architectural rather than operational: almost every certificate lifecycle system treats successful issuance as successful renewal. The platform issues, writes the new certificate to a secret store, marks the task complete, and moves on, while the process that actually terminates TLS is still holding the old certificate in memory, having never been told to reload. The issuance log says green. The endpoint says thirty days. Nothing errors, nothing alerts, and the gap between the two is where the outage lives.
A managed identity is the durable object: it carries an owner, a trust domain, a subject and a compromise history, and it outlives every certificate it holds. Entitlement to a certificate is proved differently per trust domain — a one-time CNAME delegation for a customer's public domain, an attested platform credential for a workload — and authorised by policy before any signature is requested. Issuance is the only plane that can cause a signature: an ACME client against two pre-validated public CA accounts on one side, AWS Private CA under CloudHSM custody on the other. Certificates are delivered through a small set of supported adapters, with the reload trigger inside the renewal transaction rather than downstream of it. Then the design turns: an independent verification plane, deployed per region outside the control plane's failure domain, opens a TLS connection to every known endpoint on a fifteen-minute cadence and writes what it actually saw. That write is the only one that moves a certificate into SERVING, and the renewal scheduler reads what is due from observed state rather than from issuance records — so a renewal that did not take effect stays due. Around it sit the consequences: a registry that is a projection rather than a ledger, discovery and CT monitoring as inputs to the same state machine rather than an audit feature, a trust plane gated strictly ahead of issuance, and a revocation path published independently of everything else.
Lifecycle state is derived from what endpoints are observed presenting. The issuance log records what was attempted; only an observation records what is true.
ADR-01They are reached by different mechanisms — one by the issuer, one by the prober — and collapsing them is the defect this architecture exists to prevent.
ADR-02Probers are deployed per region, outside the primary control plane, so an issuance outage does not also blind observation.
ADR-03A certificate the platform did not issue is still the platform's outage, so scanning and CT monitoring write into the same state machine as issuance.
ADR-04Public and private trust share a registry, an escalation ladder and a verify step. They share no protocol, authority, validation mechanism or lifetime, and the design does not pretend otherwise.
ADR-05One third remaining, so the policy survives the industry shortening maximum certificate lifetimes again — which it will.
ADR-09Escalation is measured against remaining validity, not against job status, which is what moves discovery from T-0 to T-30.
ADR-10An outage of this platform never invalidates anything already serving. Issuance queues, traffic continues, and the estate's survival time without the control plane is a published number.
ADR-12A new authority is distributed and confirmed everywhere before a leaf is signed beneath it, and a relying party that cannot report its bundle version blocks the rotation by name.
ADR-13Revoking first turns a compromise notice into a self-inflicted outage. The order inverts only for a key known to be in an attacker's hands, and that inversion has an approver.
ADR-15Keys are generated inside the consuming workload and only a CSR crosses the network, so the platform's databases hold no key material to lose.
ADR-18Identity comes from a platform-attested credential, never a self-asserted subject, and every denial is recorded — a refusal nobody can investigate is not a control.
ADR-20Certificate infrastructure outlives almost everything around it: a root signed today is still signing when the team that made it has gone, and the rules it has to obey are set by a standards body nobody in this organisation sits on. These are the properties that should survive a change of cloud, a change of CA, and another round of the industry shortening certificate lifetimes.
ADR-01 depends on nothing about DynamoDB, AWS, ACME or X.509. It is a statement about which of two sources to believe when they disagree, and it survives replacing every component underneath it. It is also the property a future team would most easily discard — by adding a fast path that marks a renewal complete on issuance — which is why SERVING is a state only the prober can write.
Maximum public certificate lifetimes have fallen from years to months and are still falling. A policy that says "renew 30 days before expiry" quietly becomes a policy of renewing at half of life, then at all of it. A policy that says "one third of lifetime remaining" needs no change at all.
The obligation to revoke and replace inside 24 hours is imposed from outside and has never been relaxed. Designing the bulk path as a rehearsed capability with a measured duration, rather than as an emergency, is the property that stops the next CA incident being an existential one.
Every industry trend — shorter certificates, automated issuance, ubiquitous mTLS — increases issuance volume and decreases the value of revocation infrastructure. Both movements favour this architecture: lifetime becomes the control, and the renewal machinery is exercised continuously rather than discovered during an incident.
As the estate grows, the registry's belief and reality drift further apart, and the cost of being wrong rises. The one component that would be tempting to cut in year one — the prober — is the one that becomes indispensable in year five.
Every number here is a stated assumption from the requirement, chosen to be argued with rather than believed. The right-hand column names the view where the mechanism that meets it is drawn.
| Quality | Target | How it is met | View |
|---|---|---|---|
| Certificates expiring while serving | Zero, Sev-1 with a written review | Expiry clock raised from the probe, not the registry; escalation ladder driven by remaining validity from the first failed attempt. | 18 |
| Private leaf issuance latency | p95 ≤ 120 ms, p99 ≤ 250 ms in-region | Attestation verified locally against a projected token; AWS Private CA called directly by the issuance plane with no control-plane hop on the hot path. | 13 |
| Public certificate, order to installed | p95 ≤ 90 s, p99 ≤ 10 min | Delegation already in place, so the challenge is answered inside the platform's own Route 53 zone; DNS propagation dominates the tail. | 12 |
| New domain to padlock | ≤ 15 min p95, no support interaction | Self-service CNAME delegation, named failure reasons on every validation outcome, issue before cutover. | 04 |
| Expiry detection delay | ≤ 15 min p95 | Regional probers sweep every known endpoint on a 15-minute cadence and compare the observed serial against the registry. | 18 |
| Renewal verified serving | ≤ 10 min p95 after issuance | Reload trigger inside the renewal transaction, followed by a targeted probe rather than the next scheduled sweep. | 13 |
| Revocation propagation | ≤ 5 min p95, ≤ 15 min p99 | CRL and OCSP published through CloudFront on a path independent of issuance; measured by a daily synthetic issue-install-revoke canary. | 18 |
| Bulk re-issuance of public trust | ≤ 18 h, inside a 24 h mandate | Rate-limit-aware bulk order queue across two pre-validated CA accounts; rehearsed twice a year against a representative subset. | 15 |
| Trust bundle distribution | ≤ 4 h p95 to 100% of reporting parties | Signed versioned bundle on its own lifecycle, with per-relying-party version reporting and a rotation gate that blocks below full coverage. | 17 |
| Private issuance availability | ≥ 99.95% monthly | Issuance plane across three AZ; a workload that cannot renew keeps serving until its leaf expires, which is the 8-hour margin. | 16 |
| CRL and OCSP availability | ≥ 99.99% monthly | Read-only, globally cached, published independently so that an issuance outage cannot prevent a revocation from being seen. | 20 |
| Estate survival without the control plane | ≥ 8 h, published as a metric | 24-hour leaf renewed at one third of life; fail static, so an outage stops change and stops nothing else. | 16 |
| Managed coverage of TLS endpoints | ≥ 99.5%, remainder named and dated | Network and DNS scanning plus CT monitoring reconciled against the registry; unmanaged findings carry an owner and a deadline. | 09 |
| Registry-to-reality divergence | ≤ 0.1% at any probe cycle | Divergence detector compares observed serial against registry state on every sweep and raises the gap as its own signal. | 18 |
| Registry recovery | RPO 0, RTO ≤ 30 min | DynamoDB global table; full rebuild from the append-only ledger plus one probe sweep, rehearsed annually. | 10 |
| Issuing intermediate replacement | Live and distributed ≤ 4 h | Two issuing intermediates kept live at all times, both already in every distributed trust bundle. | 17 |
| Root recovery | RTO ≤ 72 h, human in the path by design | Witnessed ceremony from hardware backup under two-person control; the one recovery path deliberately not automated. | 16 |
Four of this architecture's claims are cheap to test and expensive to be wrong about. A prototype that proves these can be built on; one that skips them is a demonstration of calling an ACME client, which is the easy half.
| Risk | If it lands | Response |
|---|---|---|
| The prober cannot reach enough of the estate | If a material fraction of TLS endpoints is unprobeable, the truth rule degrades to belief for exactly the population most likely to be forgotten, and the headline guarantee weakens without any alarm firing. | Measure coverage in the prototype. Unprobeable endpoints become a named architectural gap with an owner — a local agent, an exposed health surface, or an accepted exception — rather than an invisible remainder (ADR-03, ADR-04). |
| Short private leaves overrun the signing budget | A 24-hour leaf at 3,800 workloads is 46,000 issuances a day before churn; a fleet-wide rollout is 37× steady state in ten minutes. Signing throughput is the binding constraint and it is not elastic. | Size against measured AWS Private CA throughput early and treat leaf lifetime as the tuning dial. Lengthening the leaf relaxes the signing budget and lengthens the compromise window in the same move (ADR-08). |
| A relying party that cannot report its bundle version blocks rotation indefinitely | The rotation gate is deliberately strict. A single legacy consumer with no reporting path can stall an authority rotation that has a deadline behind it. | Inventory reporting capability before the first rotation, and treat an unreportable consumer as a migration item with a date. The escape hatch — an explicit, expiring, attributed exception — is a decision with an approver, never a flag (ADR-13). |
| Tenant churn leaves standing authority to issue | A one-time CNAME delegation is the reason renewal is frictionless and also the reason the platform can issue for a customer's domain long after the relationship ends. | Re-prove control on a declared cadence, check delegation health continuously, and retire on a schedule when a domain is repointed — with the contractual position stated rather than assumed (ADR-07). |
| Revocation is soft-fail in the clients that matter | Most browsers do not hard-fail on an unreachable revocation check, so the propagation target can be met while the revocation has no practical effect. | Declare a fail posture per relying-party class and treat an undeclared class as a defect. For workload identity, lean on lifetime rather than revocation, which is why the leaf is 24 hours (ADR-08, ADR-17). |
Twenty decisions make up this architecture. Everything else across the twenty-one views is convention, sizing or consequence. Each record states the forcing question, the context that makes it hard, what was decided, how it is realised on AWS, the options weighed, what the choice buys and costs, the conditions that would flip it, why it should still be right in ten years, and the lesson that transfers beyond this platform.
Status of this document. This is a design, not a report on a running system. The rates, latencies, volumes, retentions and thresholds are the requirement's stated assumptions for a mid-size B2B SaaS — 9,000 tenants, 24,000 customer custom domains, 3,800 internal workloads across six clusters in three regions — invented to be defensible and arguable rather than absent. They are to be replaced by measured telemetry before build, and four of them in particular are the first numbers real data should overturn: the 24-hour private leaf lifetime that sets both the issuance volume and the control-plane survival time, the 15-minute probe cadence that sets the expiry detection delay, the 18-hour bulk re-issuance target inside a 24-hour CA deadline, and the ≥ 99.5% managed-coverage figure, which is the one number that depends entirely on how much of the estate the prober can actually reach.
Which of two disagreeing sources the platform believes, and what follows from choosing the harder one.
ADR-01The endpoint is the system of record, not the issuance log ADR-02ISSUED and SERVING are distinct lifecycle states reached by different mechanisms ADR-03The verification plane does not share a failure domain with the issuance plane ADR-04Discovery is an input to the core state machine, not an audit featureTwo populations of certificate that share an inventory and nothing else, and the authorities beneath them.
ADR-05One control plane spans both trust domains; the issuance mechanics stay separate ADR-06A three-tier hierarchy with an offline root and two live issuing intermediates ADR-07Customer domain control is proved once by CNAME delegation, and re-proved on a cadenceThe failure this service exists to abolish, and the four decisions that actually abolish it.
ADR-08Workload leaves live 24 hours, and lifetime is the revocation mechanism for private trust ADR-09Renewal triggers at a fraction of lifetime remaining, never at a fixed number of days ADR-10A failed renewal is an open incident from the first failed attempt ADR-11The reload trigger is part of the renewal transaction, not a downstream courtesy ADR-12Fail static: an outage of this platform never invalidates what is already servingMoving an authority through an estate without breaking the half that has not heard yet.
ADR-13Trust distribution is gated ahead of issuance, and an unreportable relying party blocks the rotation ADR-14Issuing intermediates drain rather than cut overWhat happens when the deadline is set by someone else.
ADR-15Re-issue precedes revoke, except for a key known to be compromised ADR-16Bulk re-issuance capacity is designed to an external deadline and rehearsed twice a year ADR-17Revocation publication is independent of issuance and held to a higher availability tierWhere keys live, who may ask for a certificate, and what a refusal has to leave behind.
ADR-18Private keys are generated in the consuming workload; the platform accepts only CSRs ADR-19Signing keys live in non-exportable hardware; the root is offline and moved only by witnessed ceremony ADR-20Authorisation is policy over attested identity, and every denial is recordedEvery capability and what it is realised with, the origin of that choice, the alternative that was weighed, and the record that argues it. The requirement stays vendor-neutral throughout; this table is where the architecture commits to Amazon Web Services.
| Capability | Choice | Origin | Credible alternative | Why this one | Record |
|---|---|---|---|---|---|
| Certificate registry | DynamoDB global table, partitioned by managed identity | AWS | Aurora PostgreSQL | The dominant access pattern is a point read or a small range scan per identity at high rate from three regions, with a rebuildable dataset of ~70,000 live rows — a replicated key-value store fits it better than a relational engine that would need cross-region replication built around it. | ADR-01 |
| Issuance ledger | S3 with Object Lock in compliance mode | AWS | QLDB or an append-only table | The requirement is that no operator can edit or delete a record for ten years. Object Lock enforces that at the storage layer rather than through an access policy somebody can later widen. | ADR-01 |
| Private certificate authority | AWS Private CA, two issuing authorities | AWS | step-ca or Vault PKI on EKS | Managed authority lifecycle, native CRL and OCSP publication, and IAM-scoped issuance remove the operational surface that a self-run CA adds. The per-authority monthly charge is the reason authorities are consolidated rather than issued per team. | ADR-06 |
| Root key custody | CloudHSM, module offline between ceremonies | AWS | On-premises HSM appliance | FIPS 140-2 Level 3, non-exportable keys, quorum-controlled. An on-premises appliance is equally defensible and adds a facility and a supply chain the rest of the estate does not have. | ADR-19 |
| Public certificate issuance | ACME client against two public CA accounts | Open source + external | ACM-managed public certificates only | ACM issues and renews well for AWS-terminated endpoints, and does not give the platform a second, independent CA relationship — which is the whole mitigation for a CA outage or distrust event. | ADR-16 |
| Public certificate binding | ACM import, bound to CloudFront and ALB | AWS | Certificate files on the load balancer host | The edge terminates on managed services, so the certificate has to reach them through their own API; import keeps one delivery adapter rather than one per listener type. | ADR-11 |
| Domain validation | Route 53 delegated zone answering DNS-01 | AWS | Running an authoritative DNS server for the challenge zone | The challenge zone is small, highly available and write-heavy in short bursts. A managed authoritative service removes an availability dependency the platform would otherwise own on the customer onboarding path. | ADR-07 |
| Workload attestation | IRSA projected service-account tokens; IMDSv2 for EC2 | AWS + Kubernetes | A bootstrap secret per workload | A platform-attested credential the workload cannot forge is the only basis on which an identity can be issued without a human in the loop. A bootstrap secret is a long-lived credential protecting a short-lived one. | ADR-20 |
| Workload certificate delivery | cert-manager and mesh SDS | Open source | A bespoke node agent | SDS delivers to the proxy without the certificate ever touching disk, and cert-manager is what the clusters already run. A bespoke agent would be a third thing to operate for no gain. | ADR-11 |
| Control plane runtime | EKS across three AZ | AWS | ECS Fargate, or Lambda throughout | The order manager holds long-running work with queue semantics and steady load; the estate already operates EKS. Probing and validation, which are bursty and stateless, go to Lambda instead. | ADR-03 |
| Verification plane | Regional Lambda probers on independent schedules | AWS | A probing service inside the control plane | Independence from the control plane's failure domain is the requirement; per-region Lambda with its own EventBridge schedule is the cheapest way to get it and scales with endpoint count rather than with certificate count. | ADR-03 |
| Lifecycle event spine | EventBridge | AWS | SNS plus SQS fan-out | Consumers — the mesh, the CMDB, deployment pipelines, alerting — subscribe to lifecycle events with content-based filtering rather than polling, and new consumers do not require a change here. | ADR-02 |
| Issuance queue | SQS with per-endpoint ordering and a redrive policy | AWS | Kafka | Bulk re-issuance and fleet-restart bursts need back-pressure and prioritised draining, not a durable ordered log. The prioritisation — renewals near escalation ahead of new issuance — is a consumer-side concern either way. | ADR-16 |
| Policy evaluation | OPA bundles, built from the policy repository | Open source | IAM policy alone | The question "may this identity obtain this subject under this profile" is richer than IAM expresses, and it has to be evaluated identically in CI and at issuance time. | ADR-20 |
| Revocation publication | CRL and OCSP through CloudFront | AWS | Publication from the issuance plane's own endpoints | Relying parties the platform does not control depend on this path, so it is held to a higher availability tier than issuance and must survive an issuance outage entirely. | ADR-17 |
| Certificate Transparency monitoring | CT log polling per managed domain | Open source + external | A commercial CT monitoring product | The signal needed is narrow — any certificate for a managed domain from a CA the platform did not use — and it feeds the same registry as everything else rather than a separate console. | ADR-04 |
| Discovery scanning | Scheduled network and public DNS enumeration | Open source | AWS Config plus service inventories | Config knows about AWS-managed certificates. The certificates that cause outages are the ones nothing knows about, which only a scan of the actual TLS surface finds. | ADR-04 |
When the issuance log and the live endpoint disagree about which certificate is in use, which one is the platform's truth?
Should the lifecycle model collapse "the platform has a certificate" and "the endpoint is using it" into one state?
Can observation run inside the same control plane that performs issuance?
Where do certificates the platform never issued belong — in the registry, or in a separate compliance report?
Are public-trust certificates for customer domains and private-trust workload identities one system or two?
How many tiers should the private hierarchy have, and how many issuing authorities should be live at once?
How does a tenant prove they own a domain, and how often should they have to prove it again?
For workload identity, is revocation infrastructure load-bearing, or is a short lifetime the control?
Should the renewal threshold be expressed in days, or as a proportion of the certificate's lifetime?
When does a failing renewal become somebody's problem — at the first failure, or when expiry is imminent?
Is a renewal complete when the new certificate has been delivered, or when the consuming process is serving it?
What happens to the estate when the certificate service itself is unavailable?
How does the platform know it is safe to start issuing from a new authority?
When retiring an issuing intermediate, do you re-issue everything beneath it or let it empty naturally?
In a bulk revocation event, does the platform revoke first and then replace, or replace first and then revoke?
How fast must the platform be able to replace its entire public-trust population, and how is that claim kept true?
Should revocation be published by the same components that issue, and to what availability target?
Who generates the private key, and does it ever cross the network?
Where do the CA private keys live, and what does it take to use the root?
On what basis is an issuance request authorised, and what happens to the requests that are refused?
The terms this package uses in a specific way, and what each one is doing in the architecture.
| Package | What it is | What it does here | Considered instead |
|---|---|---|---|
| Managed identity | The durable subject a certificate is issued for: trust domain, subject and SANs, owning team, class. | The row that persists across every certificate and every compromise. Ownership, policy and compromise history attach here, not to a certificate that will expire and take the record with it. | Treating the certificate as the primary object, which loses the history every time one expires. |
| SERVING | The lifecycle state a certificate reaches when an observation records an endpoint presenting it. | The architecture's load-bearing state. Only the prober's role can write it, which is what makes the truth rule enforceable rather than aspirational. | Treating ISSUED as healthy, which is the defect this whole design exists to prevent. |
| Observation | A record of what a TLS handshake against a known endpoint actually returned: serial, chain, not_after, time. | The only evidence of reality in the system. The expiry clock and the renewal schedule are both derived from it. | Inferring liveness from a delivery adapter's acknowledgement, which confirms a write and not a load. |
| Divergence | A difference between the certificate the registry considers current and the one an endpoint is observed presenting. | A first-class signal with its own alarm, and the earliest detectable symptom of the issued-but-not-reloaded failure. | Treating the difference as staleness to be reconciled silently, which hides the failure it represents. |
| Trust domain | Public-trust (browsers and clients the platform has no relationship with) or private-trust (an authority the platform runs and every relying party is its own). | The attribute that routes an identity to one issuance plane or the other, while both share the registry and the escalation ladder. | Pretending the two are variants of one issuance mechanism, which produces an abstraction that serves neither. |
| CNAME delegation | A permanent `_acme-challenge` CNAME the tenant creates once, pointing into a platform-controlled DNS zone. | What makes renewal for a customer domain fully automatic forever after a single tenant action. | Per-renewal validation, which is safer and converts a silent system into hundreds of customer actions a day. |
| Trust bundle | A signed, versioned artefact listing the authorities a relying party should trust, distributed on its own lifecycle. | The thing that must arrive everywhere before issuance switches to a new authority. Its version is a reportable property of every relying party. | Shipping roots alongside leaves, which makes the ordering accidental rather than enforced. |
| Rotation gate | A mechanical block on issuing from an authority until every relying party has reported the bundle version containing it. | Converts "distribute trust before you issue" from a runbook step into something that cannot be skipped under pressure. | A checklist, which is exactly what gets abbreviated during the incident that forced the rotation. |
| Fail static | The posture where an outage of this platform stops change and changes nothing already running. | Distinguishes this platform from a fail-closed control: certificates already serving are never invalidated by the certificate service being unavailable. | Fail closed, which would let a control-plane outage take down the estate it exists to protect. |
| Survival time | How long the estate keeps working with the control plane entirely unavailable — the renewal margin on the shortest-lived certificate. | Published as an operational metric, currently 8 hours, so the tolerable outage is a known commitment rather than an incident-time discovery. | Leaving it implicit, which means it is measured for the first time during the outage. |
| Unmanaged certificate | A certificate discovered serving on the estate that the platform did not issue and has no record of. | A first-class registry state with an owner and a deadline, and a standing platform metric — because this population is where expiry outages concentrate. | A quarterly compliance finding, on a slower cadence than the risk it describes. |
| Bulk re-issuance | Replacing the entire public-trust population inside an externally imposed deadline, typically 24 hours. | A designed, measured, twice-yearly-rehearsed capability with a stated duration, rather than an improvisation under a clock nobody here controls. | Assuming it can be done when needed, which is how a CA incident becomes an existential one. |
svg/<view>.svg or drawio/<view>.drawio in draw.io Desktop or at app.diagrams.net to edit. The SVG carries the diagram inside it, so it is both the picture and the source. This folder is self-contained — copy it whole and every link still resolves.