Skip to main content

Preseeding Guide

To preseed the Morio config means to load it from an external source — typically a Git repository — rather than keep it within Morio itself. This allows you to deploy Morio with an infrastructure as code approach.

This guide covers the general principle and best practices. For details about all possibilities, refer to the reference documentation on the preseed settings.

Preseeding and reseeding​

Any time you update Morio settings, those settings can be preseeded. But some data — in particular preseeding key data — can only be provided at the initial setup of Morio.

Other changes can be made later, and when we update Morio settings by reloading them from a remote system as defined in the preseed settings, we call this reseeding.

So preseeding is the general principle of keeping your settings outside of Morio, whereas reseeding is the process of reloading Morio and apply the preseeded settings.

Preseeding settings​

How Morio should go and get your data is determined by the preseed settings. Refer to the reference documentation of the preseed settings for all details, but in general this defines a Git repository that Morio should use as the source of truth for its settings.

Morio will load the base settings and then apply any overlays you have defined.

Preseeding key data​

At the initial setup of Morio — and only at the initial setup — you have the option to preseed Morio’s key data.

To do so, you should first export the key data from an existing Morio instance, then add it under preseed.keys.

NOTE

This is an advanced feature to facilitate blue/green deployments or other use cases. You can safely ignore this.

Base settings and overlays​

The base settings file is just that: the base on which we will construct our final settings object.

An overlay then is a file that will mutate the base settings. Typically it is done by adding settings, but an overlay can also overwrite settings.

To understand this process, we will use an example with fictional values.

The base settings file, whether it’s provided as YAML or JSON, will be converted to a JavaScript object that will form the basis of our settings.

Provided YAML base
key1: value1
key2:
  subkey1: subvalue 1
  subkey2:
    subsubkey1: subsubvalue 1
The resulting Javascript object
{
  key1: "value1"
  key2: {
    subkey1: "subvalue 1",
    subkey2: {
      subsubkey1: "subsubvalue 1"
    }
  }
}

Overlay limitations​

Because of the ways overlays use dot-notation to make changes to the settings object, there are two limitations to be aware of:

  • Working with arrays is difficult. You cannot easily add something to an array. This is why in general in Morio we avoid using arrays for settings.
  • You cannot remove settings. While you can overwrite them, and set them to something falsy or null, you cannot remove them, which is why it is best to keep your base settings to the strict minimum.

Example setup using a Git repository​

We recommend placing your Morio settings and overlays for one or more different environments in a single repository, then let Morio clone this repository and reference files from it.

Let’s walk through an example step by step.

Initial setup​

When we initially setup a Morio instance, there is no Vault integration, nor can we use encrypted secrets as there is no key pair yet.

If the git repository you are using does not require authentication, you can use an example like this:

Minimal JSON preseed settings
{
  "git": {
    "repo":
      "url": "https://git.morio.it/iac/morio.git",
      "ref": "main"
    }
  }
  "base": "git:base.yaml@repo"
}

If you save this as preseed.json we can set up Morio with this curl command:

curl -k -H "Content-Type: application/json" -d@preseed.json https://example.morio.it/-/api/preseed

This is sufficient to bootstrap Morio, assuming that base.yaml in the repository holds valid settings.

Example base settings file​

On initial setup, we need to provide Morio with our preseed settings - but once Morio is deployed, they become a part of our regular settings, which means that they can be provided by the base file or by an overlay.

Our base settings holds the minimal settings: our cluster nodes and name.

cluster:
  broker_nodes:
    - broker.morio.it
  name: Just an example

Alternative preseed sources​

In the example above, we cloned a git repository, then loaded files from it for our base settings and overlays.

That is a common scenario that comes warmly recommended, but there are other sources you can use.

Preseed from a URL​

You can preseed both the base settings and one or more overlays from a URL. This is useful for simple scenarios and quick tests.

Refer to the preseed settings reference documentation for all details.

Preseed from the GitHub API​

If your repository is very large, cloning it in its entirety just to load a few files might be overkill. In that case, you can configure Morio to fetch specific files from the GitHub API.

Refer to the preseed settings reference documentation for all details.

Preseed from the GitLab API​

If your repository is very large, cloning it in its entirety just to load a few files might be overkill. In that case, you can configure Morio to fetch specific files from the GitLab API.

Refer to the preseed settings reference documentation for all details.