> ## Documentation Index
> Fetch the complete documentation index at: https://synthetiq.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Generating synthetiq.yaml

> Author the desired-state config that drives provisioning

All provisioning is driven by one file — `_infra/synthetiq.yaml` — committed to your git repository. `generate` and `provision` read it; changing your infrastructure means editing it and re-running the lifecycle.

## Create it with `infra init`

From your infrastructure repository:

```bash theme={null}
synthetiq infra init \
  --domain apps.yourcompany.com \
  --profile <aws-profile>
```

`init` confirms the target AWS account, discovers your VPC, public subnets, and issued [certificates](/docs/platform-docs/deployments/byoi/certificates), and writes the config with concrete ids:

```yaml theme={null}
schema: v1
provider: aws
region: us-east-1
domain: apps.yourcompany.com
network:
  vpc: vpc-0abc123
  public_subnets: [subnet-aaa, subnet-bbb, subnet-ccc]
certs:
  api_cert_arn: arn:aws:acm:us-east-1:111122223333:certificate/aaaa…
  cdn_cert_arn: arn:aws:acm:us-east-1:111122223333:certificate/bbbb…
```

Commit it. `generate` and `provision` find the file from anywhere inside the repo.

## Fields

**Required** — existing infrastructure Synthetiq references, never modifies:

| Field                    | Description                                                                         |
| ------------------------ | ----------------------------------------------------------------------------------- |
| `region`                 | The region Synthetiq provisions into                                                |
| `domain`                 | The base domain apps are served under                                               |
| `network.vpc`            | The VPC Synthetiq lands in (in a fresh sub-account, init discovers the default VPC) |
| `network.public_subnets` | Subnets for the load balancer and NAT — at least 3 Availability Zones               |
| `certs.api_cert_arn`     | Issued ACM ARN covering `*.api.<domain>`, in your region                            |
| `certs.cdn_cert_arn`     | Issued ACM ARN covering `*.<domain>` + apex, in `us-east-1`                         |

**Overrides** — optional block listing existing infrastructure to reuse instead of letting the stack build it:

| Field                            | When present                                                                                                                                                                                                                             |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `overrides.nat`                  | Workload egress routes through this NAT gateway; the stack doesn't create one                                                                                                                                                            |
| `overrides.private_subnet_cidrs` | Synthetiq creates the workload subnets using these three CIDRs instead of auto-allocating (it still creates the NAT). Cannot be combined with `overrides.private_subnets` — see [Networking](/docs/platform-docs/deployments/byoi/networking) |
| `overrides.private_subnets`      | Workloads run in these subnets; the stack creates no networking. Cannot be combined with `overrides.nat` — see [Networking](/docs/platform-docs/deployments/byoi/networking)                                                                  |

Anything not overridden is created and managed inside the Synthetiq stack, and appears as `Add` resources in the diff [`generate`](/docs/platform-docs/deployments/byoi/provisioning) produces — so the effect of an omission is always visible before it's applied.

**Manage** — optional block of account-shared resources Synthetiq provisions by default. Set any to `false` when your account already provides it; provisioning then skips that resource and you own keeping it available. Each defaults to `true`.

| Field                            | When `false`                                                                                                                                                                                   |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `manage.rds_service_linked_role` | Skips creating the account-global `AWSServiceRoleForRDS`. Set this when your account already uses RDS — the role exists once per account, so creating it again fails the stack                 |
| `manage.emf_extraction_policy`   | Skips the account-level metric-extraction policy that suppresses EMF auto-metrics on Synthetiq's app log groups. Set this if you already manage a metric-extraction account policy of your own |

```yaml theme={null}
manage:
  rds_service_linked_role: false   # your account already uses RDS
  emf_extraction_policy: false     # you manage your own metric-extraction policy
```

<Note>
  With `emf_extraction_policy: false`, disable EMF on the `/ecs/synthetiq-app-*` log groups in your own metric-extraction policy — otherwise CloudWatch auto-creates redundant, billable metrics from each app's logs.
</Note>

Unknown keys are rejected at load time, so a typo fails in CI instead of being silently ignored.

## Authoring without AWS access

Run without credentials, `init` enters **offline mode** and asks for the values directly instead of discovering them. `synthetiq infra generate` validates every value against the real account later, wherever credentials exist (CI, or a teammate with a profile).

The file is plain YAML — editing it by hand is equally valid. That's also how you change infrastructure later: edit, commit, and [re-run generate](/docs/platform-docs/deployments/byoi/provisioning) to see the diff before anything is applied.