How the YAML files look

Everything a team owns is a file: integrations, variables, channels, APIs and what runs in which environment. Secret values and the platform’s own records, such as agents, users and API keys, are the only things that never live in Git.

A project folder#

The finance project keeps its files like this:

finance/
  project.yaml
  variables/
    erp-url.yaml                  the default value
  production/
    variables/
      erp-url.yaml                production's own value
    deployments/
      erp-invoice-export.yaml     which version runs in production
  erp-invoice-export/             an integration: a folder of Camel files
    integration.yaml
    routes/
      fetch-invoices.camel.yaml
    beans/
      InvoiceMapper.java
    application.properties
    README.md
  transfers/
    supplier-invoices.yaml        a file transfer, one document

project.yaml gives the project’s name once, so no file below it has to repeat it. An integration is a folder, and every other record is one YAML document. A file can also contain several documents separated by ---.

The four parts of a document#

Every document has the same four parts:

apiVersion: weik.io/v1
kind: variable
metadata: { name: erp-url, project: finance }
spec: { value: https://erp-test.example.internal }

• apiVersion is always weik.io/v1.
• kind is what the document describes: project, environment, variable, deployment, mft, schedule, event-channel, event-source, event-subscription, change-tracking, api, api-version, api-subscription and the others listed in Document kinds.
• metadata gives the name and where the record belongs: its project, and for a value or a deployment of one environment, that environment.
• spec has the fields of the kind. A misspelled field is an error, never ignored.

Values per environment#

A variable without an environment is the default, and one with environment in its metadata overrides it there. One document per environment is deliberate: a document is the unit of permission, so a developer allowed to edit devtest’s values never sees production’s.

apiVersion: weik.io/v1
kind: variable
metadata: { name: erp-url, project: finance, environment: production }
spec: { value: https://erp.example.internal }

Secrets have the same shape, but their values are set with weikio secret set, never written in a file. A deployment document says only which version runs where, and promotion is a change of its version line:

apiVersion: weik.io/v1
kind: deployment
metadata: { name: erp-invoice-export, project: finance, environment: production }
spec: { version: 1.1.0, state: started }

Which project and which environment#

A command finds the project in this order: metadata.project in the document, the --project flag, the nearest project.yaml above the file and the CLI’s context. There is no silent default, and a document and a flag that disagree are an error. Every command that changes something prints the server, project and environment it used first, with where each came from.

Names#

Names use lower-case letters, digits and hyphens, such as erp-invoice-export. Variables and secrets follow Camel’s spelling instead, so {{erp.url}} and {{AWS_ACCESS_KEY}} work as written. An integration or an API is written <project>/<name> in commands, such as finance/erp-invoice-export, or as the bare name when the project comes from the context.

Check files in your editor#

The platform serves a JSON schema for each kind. An editor that runs the YAML language server checks a file against it as you type and marks a misspelled field before weikio apply refuses it. Save the schema of each kind you write into the repository:

$ curl -fsS --create-dirs -o schemas/variable.json -H "Authorization: Bearer $WEIKIO_API_KEY" https://weikio.example.com/api/v1/schemas/variable

Then point a file at it with a comment on its first line:

# yaml-language-server: $schema=../../../schemas/variable.json
apiVersion: weik.io/v1
kind: variable
metadata: { name: erp-url, project: finance, environment: production }
spec: { value: https://erp.example.internal }

weikio validate -f ./finance runs the same checks on the command line before anything is built, so a pipeline can fail early.