> Index of every page on this site: [llms.txt](https://docs.a-line.cloud/llms.txt)

# Infrastructure as code

> Describe clusters, projects and apps in YAML files kept in Git.

A-Line.cloud reads YAML files from a Git repository and keeps your clusters,
projects and apps in line with them. The tracked branch (usually `main`) is
the source of truth: a change merged there is planned and applied, and a
change made in the dashboard to a field the repository owns is proposed back
to the repository instead of drifting from it.

## Two kinds of link

A repository directory is connected to your organization by a link:

- An **infrastructure link** points at a directory holding `clusters/`,
  `environments/`, `secrets/`, `key-rings/`, `buckets/`, `storages/`,
  `domains/` and `dns/`. Creating one needs an organization admin and a second-factor
  check. An organization has at most ten live infrastructure links.
- A **project link** points at one project directory: `project.yaml`,
  `apps/` and, optionally, `sites/`.

See [GitOps workflow](/iac/gitops) for how the two sync, how dashboard
edits are written back and which changes wait for confirmation.

## Layout

An IaC repository holds one directory per kind of file:

- `clusters/<name>.yaml`: a cluster and its node pools.
- `environments/<name>.yaml`: an environment.
- `secrets/<name>.yaml`: a secret group.
- `key-rings/<name>.yaml`: a key ring and its keys (Preview).
- `buckets/<name>.yaml` and `storages/<name>.yaml`: object storage.
- `domains/<name>.yaml` and `dns/<zone>.yaml`: domain claims and DNS records.
- `projects/<project>/project.yaml`: a project.
- `projects/<project>/apps/<app>.yaml`: an app in that project.
- `projects/<project>/sites/<site>.yaml`: a static site in that project.

The file name (without `.yaml`) is the resource's name. Renaming a file is
read as removing one resource and adding another.

Three single-file formats exist for tools and one-off imports, not for a
linked repository: `a-line.yaml` (a manifest for `alc iac check` and
exports), `infrastructure.yaml` (one cluster) and `a-line-org.yaml` (an
organization bundle, see [import](/iac/import)).

## File kinds

Each file has a kind in the [JSON schema](/iac/reference):

- `ClusterFile`: `clusters/<name>.yaml`.
- `EnvironmentFile`: `environments/<name>.yaml`.
- `SecretGroupFile`: `secrets/<name>.yaml`.
- `KeyRingFile`: `key-rings/<name>.yaml`.
- `BucketFile`: `buckets/<name>.yaml`.
- `StorageFile`: `storages/<name>.yaml`.
- `ProjectFile`: `projects/<project>/project.yaml`.
- `AppFile`: `projects/<project>/apps/<app>.yaml`.
- `SiteFile`: `projects/<project>/sites/<site>.yaml`.
- `Manifest`, `InfrastructureFile` and `OrgBundle`: the single-file formats.

Domain and DNS files (`domains/`, `dns/`) are checked by the sync but have
no schema kind yet.

## The modeline and version

Every file starts with the schema modeline and `version: 1`:

```yaml title="environments/prod.yaml" iac
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
```

The modeline lets editors that use the YAML language server (such as VS
Code with the YAML extension) complete keys and flag mistakes as you type.
`version` names the schema the file is written for. Older supported
versions are upgraded when the file is read, and exports always write the
latest version.

## Next steps

- Follow [your first project](/iac/first-project).
- Read the [GitOps workflow](/iac/gitops).
- Describe [clusters and pools](/iac/clusters), [apps](/iac/apps),
  [networking](/iac/networking), [databases and leases](/iac/databases),
  [environments and secrets](/iac/secrets), [keys](/iac/keys), [volumes, backups and cron
  jobs](/iac/data), [buckets and storages](/iac/buckets) and [domains and
  DNS](/iac/domains).
- Connect resources with [references](/iac/references).
- Bring existing YAML in with [import](/iac/import).
- Copy a [recipe](/iac/recipes).
- Look up every file kind and field in the [reference](/iac/reference).
