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 a more hands-on guide, refer to the gitops
guide. 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
.
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.
- base.yaml
- overlay1.yaml
- overlay2.json
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.
key1: value1
key2:
subkey1: subvalue 1
subkey2:
subsubkey1: subsubvalue 1
{
key1: "value1"
key2: {
subkey1: "subvalue 1",
subkey2: {
subsubkey1: "subsubvalue 1"
}
}
}
An overlay file holds key/value pairs. The key determines the target in dot-notation, and the value holds, well, the value.
key1: different value 1
key2.subkey2.subsubkey2: I am new
key3: So am I
You can read an overlay as a series of mutations:
- Set
key1
todifferent value 1
- Set
key2.subkey2.subsubkey2
toI am new
- Set
key3
toSo am I
Which results in:
{
key1: "different value 1"
key2: {
subkey1: "subvalue 1",
subkey2: {
subsubkey1: "subsubvalue 1"
subsubkey2: "I am new"
}
},
key3: "So am I"
}
Whether you use YAML or JSON does not matter.
{
"key1": "different again",
"key2.whatever": {
"values": {
"can": {
"be any": {
"type": ["of course"]
}
}
}
}
}
Overlays are applied one after the other, so the end result is:
{
key1: "different again"
key2: {
subkey1: "subvalue 1",
subkey2: {
subsubkey1: "subsubvalue 1"
subsubkey2: "I am new"
},
whatever: {
values: {
can: {
"be any": {
type: [ "of course" ]
}
}
}
}
},
key3: "So am I"
}
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.
- Without authentication
- With authentication
If the git repository you are using does not require authentication, you can use an example like this:
{
"git": {
"repo":
"url": "https://git.morio.it/iac/morio.git",
"ref": "main"
}
}
"base": "git:base.yaml@repo"
}
If the git repository you are using does require authentication, you can use an example like this:
{
"git": {
"repo":
"url": "https://git.morio.it/iac/morio.git",
"ref": "main",
"token": "your-short-lived-token-here"
}
}
"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.
- Base settings
- Preseed Overlay
- IDP Overlay
- Secrets overlay
- Overlay using Vault
Our base settings holds the minimal settings: our cluster nodes and name.
cluster:
broker_nodes:
- broker.morio.it
name: Just an example
We’ve placed our preseed settings in an overlay and made some changes:
- The preseed settings are now under the
preseed
key - We’ve added our overlays, for which we used a glob pattern
- We’re now using a secret to hold our
GIT_TOKEN
preseed:
git:
repo:
url: 'https://git.morio.it/iac/morio.git'
ref: main
token: '{{ GIT_TOKEN }}'
base: git:base-settings/my-instance.yaml@repo
overlays: git:overlays/*.yaml
This is another example, it adds an identity provider.
iam.providers.ad:
provider: ldap
about: This is your Active Directory account, the same you use to login to your computer.
server:
url: "ldaps://dc1.tokyo.morio.it
bindDN: "CN=morio-ldap,OU=Users,DC=tokyo,DC=morio,DC=it",
bindCredentials: "{{{ AD_PASSWORD }}}",
searchBase: "OU=Users-EU,DC=tokyo,DC=morio,DC=it",
searchFilter: "(&(objectClass=user)(samaccountname={{username}}))"
username_field: samaccountname
label: Active Directory
rbac:
user:
attribute: samaccountname
regex: .
engineer:
attribute: samaccountname
list:
- mario
- luigi
If you do not have Hashicorp Vault or OpenBao available, you can pre-encrypt your secrets via the Morio API or UI. Then, you can safely commit them to git:
secrets:
GIT_TOKEN: '{ iv: "9989922c677e1d4d0f9a9d1556ac7e7d", ct: "4e3fafac2f4febb1c40b7cced3ddcd21" }'
If you have Hashicorp Vault or OpenBao available, you can defer to it for secrets storage:
secrets:
AD_PASSWORD:
vault: "morio:AD_PASSWORD"
vault:
url: https://vault.morio.it
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.