The shape of a joomiz.yaml file

For feature teams. This page shows the parts of a joomiz.yaml file, the rule that every id follows, and the limits on its size. Read it before you read the pages about each part.

The five top-level keys

A file has five keys at the left margin. Each key answers one question.

This outline shows the keys and the keys inside them. The text is not YAML.

version
application
artifacts
tooling
environments
  <environment name>
    targets
    deployments
    managed-resources
    consumed-resources

The start of a real file looks like this:

version: 1

application:
  id: f86f491d-2073-42d1-8166-17ab5d0eb093
  name: quick-start-shop

application holds the identity of your service and nothing else. artifacts, tooling and environments are keys of their own. They are not indented inside application.

The version key

The key version says which shape of the file you wrote. Today the only shape is 1. If you leave the key out, the file is read as version 1. joomiz init writes version: 1 for you.

Any other value is refused. This example is invalid on purpose:

version: 2

You see:

error: the control plane could not validate joomiz.yaml (HTTP 400)
  Unsupported joomiz.yaml version
  version '2' is not a joomiz.yaml version this control plane supports; it supports 1

Declared once and declared for each environment

The file has two kinds of content:

• Declared once for the whole file: the application block, artifacts and tooling. Describe your application and Declare artifacts and tooling explain them.
• Declared for each environment: the environments map. Each key is the name of an environment, for example test or prod. Each value holds the four lists targets, deployments, managed-resources and consumed-resources. Define your environments explains them.

Keys use kebab-case

A key with more than one word uses hyphens. The keys are golden-path, managed-resources, consumed-resources and disk-quota. Do not use camelCase or underscores in these keys. The names that you choose yourself, such as the names of environment variables in env, are free.

A key that Joomiz does not know is an error. For example, this line under application is invalid on purpose:

  team: finance

You see:

error: the control plane found 1 problem in joomiz.yaml (checked by https://joomiz.example.com/validate)
  application: unknown key "team"

The rule for ids

Many parts of the file have an id that you choose. The same rule applies to all of them:

• Use lower case letters, digits and hyphens.
• Do not start or end with a hyphen.
• Do not write two hyphens in a row.
• Write at most 255 characters.

The ids order-service, test-cluster and billing-service-db follow the rule. The ids Order_Service, -test and test--cluster do not.

The rule applies to the name of the application and to the name of each environment. It also applies to the id of each entry in artifacts, tooling and the four lists of an environment.

The rule does not apply to the id of the application, which is a UUID. It does not apply to owner.id, which is the ID of your team. Describe your application explains both.

This line is invalid on purpose, because the id has a capital letter and an underscore:

      - id: Shop_DB

You see:

error: the control plane found 1 problem in joomiz.yaml (checked by https://joomiz.example.com/validate)
  environments:
    test:
      Shop_DB (postgres):
        id: managed resource id must be kebab-case (lower-case letters, digits and single hyphens), but was 'Shop_DB'

An error that says an id "must be kebab-case" always means this rule. For an id in artifacts, the error shows the pattern ^(?!-)(?!.*--)[a-z0-9-]*[a-z0-9]$ instead of these words. It means the same rule.

Where an id must be unique

The same id can appear in two environments. The test environment and the prod environment can each have a managed resource named shop-db. They are two separate resources.

The same id can also appear in two different lists of one environment. A reference names the list too, so managed-resources.shop-db and consumed-resources.shop-db are different things.

joomiz register refuses a duplicate id in artifacts or tooling. Declare artifacts and tooling shows the message.

Limits

A file over a limit is refused. For example, a file with 26 environments gives:

error: the control plane could not validate joomiz.yaml (HTTP 400)
  Invalid application
  The submitted joomiz.yaml is not valid.
  environments: at most 25 environments may be submitted

Next

Describe the identity of your service in Describe your application.