---
name: byoc
version: 1.0.0
description: "Operate an AWS BYOC Region inside Remote Dev full. Use for customer prerequisite boundaries, BYOC config, eager or day-2 activation, readiness, image mirror, role-chain/network diagnosis, resume, and Session closeout."
metadata:
  requires:
    bins: ["cp9"]
  cliHelp: "cp9 cmd byoc.activate; cp9 cmd byoc.status"
---

# AWS BYOC Region

Read [`../get-started/SKILL.md`](../get-started/SKILL.md) for session routing and [`../get-started/references/safety-and-ownership.md`](../get-started/references/safety-and-ownership.md) before mutation.

BYOC is an optional capability inside Remote Dev full. Copy [`../../cp9.dev-full.remote-ec2-k3d.example.yaml`](../../cp9.dev-full.remote-ec2-k3d.example.yaml); its commented `byoc` block is the complete config source of truth.

Customer onboarding remains human-owned. Require the approved [AWS BYOC from-zero guide](https://github.com/tidbcloud/controlplane9/wiki/AWS-BYOC-from-zero) to be complete before enabling the block. CP9 validates but does not create or adopt the customer-owned DNS zones, PCA, quota, CIDR, or AZ mapping.

## Activation

1. Replace every Session, control-plane, host, and customer placeholder in the copied root example. Uncomment the complete `byoc` block only after prerequisites are verified.
2. Run `cp9 setup`, `cp9 doctor`, and `cp9 up dry-run=true`; stop on any config, account, profile, DNS, PCA, quota, CIDR, AZ, source, or host failure.
3. With `byoc.enabled: true`, `cp9 up` resumes Region activation after the Dev full baseline. Otherwise require top-level `cp9 status=ready` and run `bin/cp9 byoc activate config=cp9.yaml`.
4. Run JSON `bin/cp9 byoc status config=cp9.yaml`. Accept only `ready` with account setup, image mirror, role chain, network preflight, regional runtime, and catalog layers ready.

The customer-account profile is local-only and must resolve to the configured customer account. It must differ from the control-plane source/runtime profiles. Never send a local profile name or credential to a remote service.

Activation is resumable. After interruption or SSO expiry, refresh the same profile and rerun the same command with unchanged immutable config and `.cp9` state.

## Diagnosis

Start with JSON BYOC status and its cited activation journal. Preserve the first failing layer:

- account setup: customer identity, stack ownership/reuse, Clinic trust;
- image mirror: source closure, customer ECR, digest evidence;
- role chain: exact cross-account trust and session identity;
- network preflight: CIDR, AZs, DNS/PCA, PrivateLink;
- regional runtime/catalog: rollout and Region registration.

Fix the named layer and resume. Do not replace a customer prerequisite, adopt an unknown fixed-name resource, or edit journal state to skip a gate.

## Closeout

Run `bin/cp9 destroy config=cp9.yaml` from the same Session. It removes session-owned setup stacks, network, roles, runtime, leases, host, and local state while retaining documented customer prerequisites, reused stacks, and shared customer ECR state. Record retained versus removed resources explicitly.

## Completion

A usable BYOC Region ends at `cp9 byoc status=ready`; this skill does not create a customer TiDB. Report Dev full readiness, BYOC layer readiness, any unverified product behavior, and the final Session cleanup receipt separately.

## References

- [`../../cp9.dev-full.remote-ec2-k3d.example.yaml`](../../cp9.dev-full.remote-ec2-k3d.example.yaml)
- [`../get-started/references/dev-full-aws-runtime.md`](../get-started/references/dev-full-aws-runtime.md)