# Design: One Session Product PCA

Status: ACCEPTED
Date: 2026-07-31
Owner: cp9

## Decision

Each Dev Full session owns one short-lived AWS ACM Private CA. Premium,
Essential V2, Dedicated, and Starter share that CA. CP9 provisions and wires
the CA without changing upstream service semantics or staging configuration.

The CA is session infrastructure, not an account-level dependency and not a
per-ResourcePool product default.

## Runtime Graph

```mermaid
flowchart LR
  TF["CP9 Terraform substrate"] --> PCA["Session product Root PCA"]
  PCA --> OUT["Typed Terraform output and session context"]
  PCA --> ROOT["Root certificate"]
  ROOT --> S3["Session S3 bucket: ca.pem"]

  OUT --> PREMIUM["Premium DPM environment fallback"]
  OUT --> E2["Essential V2 SharedPool PCA"]
  OUT --> DEDICATED["Dedicated regional and global services"]
  OUT --> STARTER["Starter global and regional services"]

  S3 --> NEXTGEN["Nextgen Global Service CA download"]
  S3 --> DGS["Dedicated Global Service CA download"]

  PREMIUM --> CERTS["Data-plane certificate issuers"]
  E2 --> CERTS
  DEDICATED --> CERTS
  STARTER --> CERTS
```

## Provisioning

[`session_product_pca.tf`](../terraform/aws/cp9-substrate/session_product_pca.tf)
creates one session-scoped `ROOT` authority in
`SHORT_LIVED_CERTIFICATE` mode. Terraform activates it with a seven-day root
certificate. The CA and every taggable supporting resource carry the session
owner, name, TTL, and managed tags through the AWS provider default tags.

The historical Terraform addresses are moved to `session_product` rather than
recreated. This preserves an existing session CA when upgrading from the old
Dedicated-only name.

Terraform exposes the ARN and region through the typed
`session_product_pca` output. CP9 writes that output into the generated session
context; runtime rendering must consume this value instead of deriving an ARN.

## Root Certificate Distribution

[`cluster_certificates_storage.tf`](../terraform/aws/cp9-substrate/cluster_certificates_storage.tf)
creates a private, session-prefixed S3 bucket and declaratively uploads the root
certificate as `ca.pem`.

Global services receive:

- the session bucket;
- `defaultKey: ca.pem`;
- the mapping from the session PCA ARN to `ca.pem`.

No Tilt daemon copies a CA from a data-plane cluster. Reconciliation is owned by
Terraform, so a clean session and an updated session follow the same
declarative path.

## Product-Line Wiring

| Product line | Session PCA contract |
| --- | --- |
| Premium | The CP9 regional DPM `appBoxConfig.pcaConfig` uses the session PCA as its environment-level fallback. A ResourcePool does not need a stored PCA ARN. |
| Essential V2 | CP9 passes `sharedPool.pca.caIdentifier` during bootstrap and records the same ARN on its synthetic local ResourcePool. |
| Dedicated | Regional Server and cluster controllers receive `componentPCAARN`; Dedicated Global Service and Dataflow receive the same `pcaArn`. |
| Starter / Essential V1 | Serverless global/regional services receive the same `pcaArn`; CP9-issued proxy and compact pool certificates use the session authority. |

Every renderer validates that the ARN belongs to the selected runtime account
and region before applying manifests. A missing, cross-account, or
cross-region ARN is a startup failure rather than a fallback to staging.

## Staging Compatibility Boundary

This design must not change existing staging behavior:

- no upstream service creates an AWS PCA;
- no upstream ResourcePool creation path auto-fills `pca_arn`;
- existing staging pools with an empty PCA continue using the staging regional
  DPM environment fallback;
- staging keeps its fixed, environment-owned PCA and certificate bucket;
- CP9 patches only its generated runtime with its session-owned PCA and bucket.

Consequently, CP9 does not require a tidb-management-service change to make
Premium pools explicitly pin a PCA. The existing DPM fallback contract is used
with a different, session-scoped value only inside CP9.

## Lifecycle

`cp9 destroy` first removes the Terraform-owned authority and bucket. The PCA
uses a seven-day permanent-deletion window. Tagged cleanup and purge recognize
ACM PCA authorities as session survivors and provide the fallback cleanup path
if Terraform cannot finish.

The CA is intentionally not rotated during a normal short-lived session. A new
session gets a new trust root.