Morio Settings: preseed

The preseed settings hold information to preseed Morio. It is optional unless you want to use preseeding.

The general principle is that it allows you to instruct Morio to collect information from a variety of sources at initial startup (or when reseeding) and use that information elsewhere.

The various sources currently supported are: a URL, the GitLab or GitHub API, and any git repository that can be cloned over HTTPS.

Whether you are running a standalone node or several broker nodes or flanking nodes, the cluster settings hold this information.

preseed.git

Optional This defines one or more git repositories that Morio should clone locally so their contents can be re-used.

preseed.git.[repo-id]

Mandatory When defining a git repository to clone, you must give it an id. In practice, we utilise the key under the preseed.git settings as the id.

Going forward, we will use repo as the example id.

preseed.git.[repo-id].url

Mandatory The URL to clone the repository over HTTPS.

preseed:
  git:
    repo:
      url: 'https://github.com/certeu/morio-settings.git'

info

Morio does not support cloning over SSH.

preseed.git.[repo-id].ref

Optional The ref to use when cloning the repository. If not specified, the default branch of the repository will be used. When specified, you can use a branch name, a tag, or even a commit reference.

preseed:
  git:
    repo:
      ref: production

preseed.git.[repo-id].user

Optional The username to use for authentication when cloning the repository.

preseed:
  git:
    repo:
      user: bot

info

This will only take effect when token is also set.

preseed.git.[repo-id].token

Optional The access token (password) to use for authentication when cloning the repository.

Using inline credentials

preseed:
  git:
    repo:
      token: 'Use this only for the initial preseeding'

Using a secret reference

preseed:
  git:
    repo:
      token: '{{ GITHUB_TOKEN }}'

Using a vault reference

preseed:
  git:
    repo:
      token:
        vault: 'morio/prod:GITHUB_TOKEN'

info

This will only take effect when user is also set.

preseed:
  git:
    repo:
      user: bot

preseed.base

mandatory This defines how to load the base settings file for Morio. Both JSON or YAML is supported.

A simple URL

The simplest way is to use a string that points to a URL from which to load the base settings:

preseed:
  base: 'https://github.com/certeu/morio-settings/blob/main/production/base-settings.yaml'

Reference to a git repository

If you have defined git repositories under preseed.git you can refer to file in these repositories using this syntax:

git:path/to/file@id

Example:

preseed:
  base: 'git:main/production/base-settings.yaml@repo'

preseed.base.url

optional For more control, you can set the url key to the URL, and add a headers object to set the request headers. This allows you to configure any authentication, as long as it works in a single request (like Basic, or Bearer), rather than requiring a callback (like OIDC).

preseed:
  base:
    url: 'https://github.com/certeu/morio-settings/blob/main/production/base-settings.yaml'
    headers:
      - authorization: 'Bearer my-super-secret-token-here'

preseed.base.github

optional To load data from the GitHub API, you can setup the github key.

preseed.base.github.url

optional The (base) URL of the GitHub API. Defaults to https://api.github.com but can be changed for self-hosted GitHub.

preseed:
  base:
    github:
      url: 'https://api.github.com'

preseed.base.github.owner

mandatory The owner (user or organisation) of the repository.

preseed:
  base:
    github:
      owner: certeu

preseed.base.github.repo

mandatory The repository name

preseed:
  base:
    github:
      repo: morio-settings

preseed.base.github.file_path

mandatory The relative path inside the repository to the file to load as base settings.

preseed:
  base:
    github:
      file_path: settings/production.yaml

preseed.base.github.token

mandatory The GitHub (personal) access token to use for authentication to the GitHub API.

Using inline credentials

preseed:
  base:
    github:
      token: 'Use this only for the initial preseeding'

Using a secret reference

preseed:
  base:
    github:
      token: '{{ GITHUB_TOKEN }}'

Using a vault reference

preseed:
  base:
    github:
      token:
        vault: 'morio/prod:GITHUB_TOKEN'

preseed.base.github.ref

Optional The ref to load the file contents from. If not specified, the default branch of the repository will be used. When specified, you can use a branch name, a tag, or even a commit reference.

preseed:
  base:
    github:
      ref: production

preseed.base.gitlab

optional To load data from the GitLab API, you can setup the gitlab key.

preseed.base.gitlab.url

optional The (base) URL of the GitLab instance. Defaults to https://gitlab.com but can be changed for self-hosted GitLab.

preseed:
  base:
    gitlab:
      url: 'https://gitlab.morio.it'

preseed.base.gitlab.project_id

mandatory The (numeric) project_id of the GitLab project.

preseed:
  base:
    github:
      project_id: 61397500

tip

You can find this under Settings → General on your repository page in the GitLab UI.

preseed.base.gitlab.file_path

mandatory The relative path inside the repository to the file to load as base settings.

preseed:
  base:
    gitlab:
      file_path: settings/production.yaml

preseed.base.gitlab.token

mandatory The GitLab access token to use for authentication to the GitLab API.

Using inline credentials

preseed:
  base:
    gitlab:
      token: 'Use this only for the initial preseeding'

Using a secret reference

preseed:
  base:
    gitlab:
      token: '{{ GITLAB_TOKEN }}'

Using a vault reference

preseed:
  base:
    gitlab:
      token:
        vault: 'morio/prod:GITLAB_TOKEN'

preseed.base.gitlab.ref

Optional The ref to load the file contents from. If not specified, the default branch of the repository will be used. When specified, you can use a branch name, a tag, or even a commit reference.

preseed:
  base:
    gitlab:
      ref: production

preseed.overlays

Optional In addition to preseeding a base settings file (via the preseed.base setting) you can apply one or more overlays to these base settings. This allows you to store your settings in a modular way.

Learn more about preseeding and overlays

For all details about preseeding, refer to the Preseeding Guide.

When preseed.overlays is a string

Simple URL

Use this to load a file from a URL. Only use this if you only have 1 overlay to load.

preseed:
  overlays: 'https://gitlab.com/morio/example-settings/-/blob/main/settings/overlays/idp-ad.yaml?ref_type=heads'

A git file reference

Use this to load a file from a cloned git repository. Only use this if you only have 1 overlay to load.

preseed:
  overlays: 'git:settings/production.yaml@repo'

A git glob pattern

Use this to load files from a cloned git repository that match a given glob pattern.

preseed:
  overlays: 'git:settings/production/overlays/*.yaml@repo'

When preseed.overlays is an array

When preseed.overlays holds an array, you have more options. When an element in the array is a string, it supports all the options listed above.

In addition, for each element you have the following additional options:

GitHub object

Use this to load a file from the GitHub API, just like you can do with the base file.

preseed:
  overlays:
    - github:
        owner: 'certeu'
        repo: 'morio-settings'
        file_path: overlays/example.yaml
        user: '{{ GITHUB_USER }}'
        token: '{{ GITHUB_TOKEN }}'

GitHub reference

If you have used a GitHub API request to load your base settings, you can re-use the same settings for an overlay using this syntax:

file_path@github

Example:

preseed:
  overlays: 'settings/production.yaml@github'

GitLab object

Use this to load a file from the GitLab API, just like you can do with the base file.

preseed:
  overlays:
    - gitlab:
        project_id: 61397500
        file_path: overlays/example.yaml
        user: '{{ GITLAB_USER }}'
        token: '{{ GITLAB_TOKEN }}'

GitLab reference

If you have used a GitLab API request to load your base settings, you can re-use the same settings for an overlay using this syntax:

file_path@gitlab

Example:

preseed:
  overlays: 'settings/production.yaml@gitlab'