The policy document

The policy document is the one file a process loads, named by the service document's policy.file. It holds the tables of the policy plus the sections below, held to schemas/config/policy.schema.json, apiVersion: sluis.truvity.github.io/policy/v2.

Section	Holds
exchange.clusters[]	{name, issuer, jwksUri} per federated cluster
exchange.aws	audience, maxAge and accounts[] ({account, name, issuer, jwksUri, orgId, algs})
exchange.github.owners[]	organisations whose CI tokens are verified; none verifies none
exchange.github.ownerIds[]	optional. The numeric ids of those organisations (a token's repository_owner_id). When set, a token must carry one of them as well as an owner above: a login can be renamed, or taken by someone else after the organisation is deleted, and an id cannot. Unset asks nothing of the id
exchange.github.repositoryIds[]	optional. The numeric ids of the repositories whose tokens are verified (repository_id). When set, a token must carry one of them, which narrows an organisation to named repositories whatever they are called. Unset asks nothing of the id
apps.github.apps[]	every GitHub App: {id, purpose, labels, export, org, tier, name} (name: the link App's or a catalogue App's name on GitHub, at most 34) and, for catalogue, the App's declaration (GitHub Apps catalogue)
apps.github.runnerTiers[], apps.github.catalogue[]	deprecated, still read as entries of apps.github.apps, with a warning
apps.slack.catalogue[]	the Slack App catalogue (Slack Apps catalogue)
controllers.github.enabledOrgs[]	organisations the GitHub controller changes; other bound organisations are a dry run
controllers.github.appRefs	{org: App id}: the App an organisation uses (app_ref)
controllers.github.appNames	{org: name}: the name an organisation's App is created with, at most 34; the default is built in
controllers.slack.enabledWorkspaces[]	workspaces the Slack controller changes
backup.runGroups[]	groups of this policy whose holders may start a backup through the issuer; unset lets nobody (backup)

No section holds a secret: every row is a name and a URL.

apiVersion: sluis.truvity.github.io/policy/v2
groups:
  all:sluis:operator: { members: [[email protected]] }
  all:sluis:viewer:   { members: [[email protected]] }
lifetimes: { default: 12h }
github:
  example-org: { members: [all:sluis:viewer] }
exchange:
  clusters:
    - {name: devel, issuer: "https://kubernetes.default.svc", jwksUri: "https://devel.example/openid/v1/jwks"}
  aws:
    audience: sluis-exchange
    accounts:
      - {account: "111122223333", name: apps, issuer: "https://example-id.tokens.sts.global.api.aws"}
  github: {owners: [example-org]}
apps:
  github:
    apps:
      - {purpose: runner, tier: preview}
      - {purpose: runner, tier: stable}
controllers:
  github: {enabledOrgs: [example-org]}

The document checks run wherever it is loaded: the binary, sluisctl policy render and the Pulumi library.

Refused
a catalogue grant naming an undeclared group
an App with no purpose, a second link App, a runner entry without a tier
an appNames entry for an unbound organisation or a name over 34 characters, a link or catalogue name over 34
an appRefs entry for an unbound organisation, an undeclared App or one created under another organisation
a Slack App for an undeclared workspace
an enabled organisation or workspace the policy does not bind
two clusters for one issuer

Rendering

sluisctl policy render <file or directory> [-o <file>] writes one document (sluisctl). The same layers give the same bytes.

Input layer	Form
policy file	version: 1
access document	access: and overlay:, reshaped into tables
policy document fragment	any section

A directory merges in name order. Tables merge by key and a key declared twice is an error naming the file. A list of sections concatenates; a list of names unions.

Target	Where the document goes
any	policy.file in the service document
Kubernetes	policy: in values, or the finished document in documents.policy (chart values)
AWS Lambda	the policy of the configuration layer

The installation document renders both documents at once.