Writ

Server config

Every setting and block of the writ serve config, and what writ serve --check refuses.

A team's writ serve reads one config file, written in HCL: settings such as url = "...", and blocks such as env "prod" { ... }. It evaluates nothing, so every value is a literal: no variable, function, or ${...}. It contains no secret: the state keys, the TLS key, and the files of provider_env are paths it points to. A relative path is relative to the config file's directory. Run a control plane shows how to start writ serve with it.

Sample config

// /etc/writ/serve
url           = "https://writ.example.com"
listen        = "0.0.0.0:443"
database      = "postgres://writ@/writ?host=/run/postgresql"
data          = "/var/lib/writ"
provider_uids = "61000-61063"
plan_ttl      = "24h"
session_ttl   = "12h"

tls {
  cert = "/var/lib/writ/tls/fullchain.pem"
  key  = "/var/lib/writ/tls/key.pem"
}

aws {
  region  = "eu-west-1"
  session = "1h"
}

limits {
  requests_per_second  = 10
  requests_per_address = 20
  plans_per_principal  = 4
  plans                = 8
  applies              = 4
  body                 = "16MiB"
  plan_timeout         = "30m"
  apply_start_timeout  = "10m"
  apply_timeout        = "4h"
}

retention {
  audit = "400d"
  plans = "30d"
}

issuer "gitlab" {
  kind     = "gitlab-ci"
  identity = "gitlab"
  url      = "https://gitlab.com"
}

issuer "sso" {
  kind               = "people"
  identity           = "gitlab"
  url                = "https://gitlab.com"
  client_id          = "8f1c0b7e4d2a"
  client_secret_file = "/run/secrets/writ/oidc_client_secret"
  groups             = "userinfo"
}

team "infra_mr" {
  issuer = "gitlab"
  match  = { project_id = ["4242"], pipeline_source = ["merge_request_event"] }
}

team "platform" {
  issuer = "sso"
  match  = { groups = ["acme/platform"] }
}

team "infra_reviewers" {
  issuer = "gitlab"
  match  = { project_id = ["4242"], user_access_level = ["maintainer", "owner"] }
}

team "infra_main" {
  issuer = "gitlab"
  match = {
    project_id        = ["4242"]
    ref_path          = ["refs/heads/main"]
    ref_protected     = ["true"]
    ci_config_ref_uri = ["gitlab.com/acme/infra//.gitlab-ci.yml@refs/heads/main"]
  }
}

grant {
  teams  = ["infra_mr"]
  stacks = ["*"]
  envs   = ["staging", "prod"]
  can    = ["read", "plan"]
  risks  = []
}

grant {
  teams  = ["platform"]
  stacks = ["*"]
  envs   = ["staging", "prod"]
  can    = ["read", "approve"]
  risks  = []
}

grant {
  teams  = ["infra_reviewers"]
  stacks = ["*"]
  envs   = ["prod"]
  can    = ["approve"]
}

grant {
  teams  = ["infra_main"]
  stacks = ["*"]
  envs   = ["staging", "prod"]
  can    = ["read", "apply"]
  risks  = ["create", "update", "replace", "delete"]
}

approval {
  stacks = ["*"]
  envs   = ["prod"]
  risks  = ["create", "update", "replace", "delete", "data-loss"]
  need   = 1
}

approval {
  stacks = ["*"]
  envs   = ["*"]
  risks  = ["delete", "data-loss"]
  need   = 1
}

env "staging" {
  key        = "/var/lib/writ/keys/staging.key"
  plan_role  = "arn:aws:iam::111111111111:role/writ-plan"
  apply_role = "arn:aws:iam::111111111111:role/writ-apply"
}

env "prod" {
  key          = "/var/lib/writ/keys/prod.key"
  plan_role    = "arn:aws:iam::222222222222:role/writ-plan"
  apply_role   = "arn:aws:iam::222222222222:role/writ-apply"
  provider_env = { NOMAD_TOKEN = "/run/secrets/prod/nomad_token" }
}

Settings and blocks

FieldMeaning
urlThe URL of writ serve, and the only audience a token can carry. https://, or http:// on a loopback address behind a proxy that ends TLS.
listenThe address to listen on. Without tls, a loopback address.
tlsA block: cert and key, the certificate chain and key files.
databaseThe Postgres URL of the control database. It can't contain a password: point to a passfile with ?passfile= or set PGPASSFILE.
dataA directory for work files. Default /var/lib/writ.
provider_uidsA range of uids, such as "61000-61063", that no user on the host has, with at least limits.plans uids. Each running plan's providers run as one of them. Required when an environment sets a role or the config has a tofu block.
awsA block: how writ serve reaches STS. region, an optional sts_endpoint for an interface VPC endpoint, and session, how long credentials last, from 15m to 12h, 1h by default. Required when an environment sets a role.
plan_ttlHow long a plan stays live, pending or approved, before it expires. Default 24h.
session_ttlHow long a person's session lasts. There's no refresh. Default 12h.
uiA block. ui { enabled = false } turns the control UI off. It's on when an issuer of kind people exists.
limitsA block: requests a second for each principal, requests a second for each client address, running plans for each principal and in all, running applies, the largest request body after gzip decompression, and how long a plan and an apply can take. The defaults are in the sample above. See Rate limits and Time limits.
trusted_proxiesOptional. A list of CIDRs, such as ["127.0.0.1/32"], of the proxies in front of writ serve. X-Forwarded-For is read only on a request from one of them. See Rate limits.
retentionA block: how long audit rows and spent plans are kept. By default they're kept forever. See Back up and upgrade.
issuer "NAME"A token issuer to trust, one block each: kind (gitlab-ci, github-actions, or people), url, identity, and an optional ca_file for an instance with a private CA. See below.
team "NAME"A rule over token claims, one block each: issuer, and match, an object of claims and the values that match. See Teams and grants.
grantWhat teams can do, one block each, numbered from 1 in the order written.
approvalOptional. How many approvals a plan needs, one block for each rule, by stacks, envs, and risks, with need from 1 to 10. Without one, no plan needs an approval. See Approvals.
env "NAME"An environment, one block each: its state key file, and optionally plan_role, apply_role, s3_endpoints, and provider_env. See below.
forge "NAME"Optional. Where repositories are read from, one block each: kind = "gitlab", url, and read_token_file, a token with read_api.
repoOptional. Pins the list of repositories, one block each, with name, forge, project, path, and prefix. Without one, an admin adds them with writ repo add.
poll_everyHow often each repository's default branch is polled. Default 60s.
tofuOptional. A block: how writ serve runs OpenTofu for stacks of .tf files. See below.
driftOptional. A block: every, how often writ serve runs a drift check of each OpenTofu stack@env it keeps state for, at least 1m. It needs the tofu block and limits.plans of at least 2. Without it, writ serve runs no drift checks.

issuer

  • identity is the lowercase name of the Git host or identity provider that the user ids in the issuer's tokens come from, such as the name of a forge block. Issuers of one Git host share it. See Who a person is.
  • An issuer of kind people is the identity provider people sign in to the control UI with. It also takes client_id, client_secret_file, the file that has the client secret, and groups: "userinfo" reads the groups claim from the userinfo endpoint, and "id_token", the default, from the ID token.

env

  • plan_role: the ARN of the role plans use.
  • apply_role: the ARN of the role applies use.
  • s3_endpoints: a list of the custom endpoint URLs a stack's S3 backend can point to.
  • provider_env: an object of variables for the providers, read from files.

tofu

  • binary: OpenTofu 1.13.9, a path or a name on PATH.
  • plugin_cache: the providers' directory.
  • scratch_dir: where each run gets a directory.
  • git: optional. The git that each run's filesystem view has, a path or a name on PATH. It's found when writ serve starts, which fails if it's missing. Each run's PATH has that git's directory first. Without git, a module source that needs git, such as git::https://... or a github.com/ address, fails, and the plan's error says to set tofu.git.

Both directories must be outside data. The block requires provider_uids, because a stack runs the code of any commit that writ serve plans. So OpenTofu and its providers run as a provider uid, never as writ serve's own user, which can read the state keys, the database, and the tokens. Without the block, a plan of such a stack is refused. writ serve --check checks that the binary is OpenTofu 1.13.9, and that git, when set, has git-remote-http and git-remote-https in its exec path.

Stack names and prefixes

A repository's prefix goes before each stack's directory to make its name on the control plane: with prefix = "payments/", the stack network is payments/network. Grants, approvals, and state use that name. A request can't choose the name.

For every plan and apply, the control plane takes off the stack's name the prefix of the longest-prefixed repository it has that the name starts with. A prefix ends in a slash, so it matches at a slash. Registering a repository is refused when its prefix starts another repository's prefix, or is the start of one, or when one of its stack names starts with another repository's prefix. So one prefix is always the longest. See Rules for adding a repository.

State

State has no field. An OpenTofu stack's state is on the http backend that writ serve serves, in the control database, or in the stack's own S3 bucket, as OpenTofu stacks says. A request that sets a state location is refused.

What writ serve --check refuses

writ serve --check refuses, with its position:

  • An unknown setting or block, a block written as a setting and the reverse, and a block named twice.
  • A reference to an issuer, team, operation, risk class, or environment that doesn't exist.
  • An issuer without identity.
  • An element of trusted_proxies that isn't a CIDR or that sets bits past its prefix length.
  • A drift block without every, with an empty every, an every of zero or under a minute, in a config with no tofu block, or with limits.plans under 2.
  • A tofu block without provider_uids.
  • A stack pattern that isn't one, as Stack patterns says.
  • An approve grant to a team of a CI issuer that matches no claim of the person who ran the job, and an override grant to any team of a CI issuer.

It warns on:

  • A config with an http:// URL and no trusted_proxies.
  • A team that matches a path without its id, and a team that can apply but matches no ref.
  • A provider that acts on the host, such as hashicorp/local.
  • A config without provider_uids.
  • Issuers of two identities whose URLs look like one host.

It prints the approval rules.

A config that sets one of these removed settings is refused, and the setting is named: provider and providers_dir, because a stack runs the providers its .terraform.lock.hcl pins; limits.files; and an environment's secret_env or state. Delete them.

Policy

The policy block lists policy sets. Each is a directory of .rego files on the host, relative to the config file. The config is the only place policy comes from, so no commit can change the policy that checks it. Policy describes the input, the rules Writ reads, and the verdicts.

policy {
  timeout = "10s"
  memory  = "1GiB"

  set "baseline" {
    dir = "policy/baseline"
  }

  set "advice" {
    dir   = "policy/advice"
    level = "advisory"
  }
}
KeyMeaningDefault
timeoutHow long one decision can take, at either point, every set together"10s"
memoryHow much address space the evaluation process can add, at least "64MiB""1GiB"
set "NAME"One policy set. At least one. Its name is lower case letters, digits, -, and _
set.dirThe directory of the set's .rego files, relative to the config file
set.level"mandatory", whose deny refuses, or "advisory", whose deny only warns"mandatory"

A set has every .rego file under its directory, at any depth, except files with names that end in _test.rego. Those contain the set's tests for conftest verify and opa test. A set has at most 1 MiB of Rego.

writ serve reads and compiles every set at start, and doesn't start when one doesn't compile. writ serve --check compiles them and prints a line for each set, and one for the bounds. When a set doesn't compile, --check fails with the file and place:

policy set baseline: iam.rego:6:12: rego_type_error: undefined ref: input.planned_values.root_module.resources[__local0__]

writ serve --dev --config FILE takes the same block.

This page is built from docs/config.md in the repository. It is also served as plain Markdown.

On this page