Requirements#

Before running the Ansible playbooks, you must configure the installation environment by executing the MAIA_Configure_Installation.sh script. This script comes with the maia-toolkit package and is required to generate the necessary cluster parameters and configuration files for the Ansible deployment.

Running the Configuration Script#

The script can be run with an optional env.json file as an argument:

MAIA_Configure_Installation.sh [path/to/env.json]

If an env.json file is provided, the script will load existing values from it. Otherwise, it will prompt for required values.

Required Values#

The script requires the following environment variables (will prompt if not set):

MAIA_PRIVATE_REGISTRY: The URL of the private MAIA Docker/Helm registry (e.g., https://harbor.example.com). If left empty, the script will set PUBLIC_REGISTRY=1 and skip prompting for REGISTRY_USERNAME and REGISTRY_PASSWORD
REGISTRY_USERNAME: Username for authenticating with a private registry. Only required if MAIA_PRIVATE_REGISTRY is set.
REGISTRY_PASSWORD: Password for authenticating with a private registry. Only required if MAIA_PRIVATE_REGISTRY is set.
CLUSTER_DOMAIN: The public domain or base domain for the MAIA cluster (e.g., maia.example.com).
CLUSTER_NAME: Name to assign to the MAIA Kubernetes cluster (e.g., maia-cluster).
CONFIG_FOLDER: Directory path to store MAIA/cluster configuration files (e.g., /opt/maia/config).
INGRESS_RESOLVER_EMAIL: Email for Let’s Encrypt certificate for ingress (e.g., admin@example.com). It can be left empty if using self-signed certificates.
K8S_DISTRIBUTION: Chosen Kubernetes distribution - must be one of: microk8s, rke2, k3s, k0s.

Optional Values#

PUBLIC_REGISTRY: Set to 1 to skip prompting for REGISTRY_USERNAME and REGISTRY_PASSWORD (uses public registry)
JSON_KEY_PATH: Path to a JSON file containing Harbor credentials in the format:
```
{
  "username": "username",
  "password": "password"
}
```
CIFS Key Generation: The script will prompt to generate a CIFS public-private key pair for CIFS shared storage support

Generated Files#

The script generates all necessary configuration files and stores them in the CONFIG_FOLDER directory:

env.json: Contains all environment variables and cluster parameters (cluster_name, DEPLOY_KUBECONFIG, passwords, secrets, etc.)
<CLUSTER_NAME>.yaml: Cluster configuration YAML file with domain, ingress settings, passwords, and cluster-specific parameters
microk8s-config.yaml: MicroK8s-specific configuration file
maia-registry-credentials.json: Harbor registry credentials in JSON format
MAIA_realm.json: Keycloak realm configuration template
<CLUSTER_NAME>-kubeconfig.yaml: Kubernetes kubeconfig file (generated after cluster installation)
ca.crt: Certificate Authority certificate (generated during installation)
cifs_key and cifs_key.pub: CIFS public-private key pair (if generated)

All files generated by the Ansible scripts, including kubeconfig files, CA certificates, and other cluster-specific files, are stored in the CONFIG_FOLDER. This makes the configuration self-contained and portable.

Note: The CONFIG_FOLDER must be accessible to the Ansible control node and should have appropriate permissions for file creation and modification.

Inventory#

The Ansible inventory file defines the hosts and groups that will be managed during the MAIA installation. The inventory structure is based on the roles that will be applied to different host groups.

Inventory Groups#

control-plane#

The control-plane group contains hosts that will run the Kubernetes control plane (API server, etcd, scheduler, controller manager). For MicroK8s installations, this typically includes the primary node where MicroK8s is installed.

[control-plane]
maia-node-0 ansible_user=root ansible_become=true
maia-node-1 ansible_user=ansible-user ansible_become_password=ansible ansible_become=true ansible_become_method=sudo

Roles applied: microk8s, oidc_microk8s, ca_microk8s, argocd, maia_core_layer

nfs_server#

The nfs_server group contains hosts that will act as NFS servers, providing shared storage for the cluster. Only one host should typically be in this group.

[nfs_server]
maia-node-0 ansible_user=root ansible_become=true

Roles applied: nfs (server tasks), lvm (with NFS storage volume)

Note: Hosts in the nfs_server group will have an additional NFS storage logical volume (maia_0) created by the lvm role, in addition to the local storage volume.

nfs_clients#

The nfs_clients group contains hosts that will mount the NFS share from the NFS server. These hosts need NFS client packages installed and will mount the shared storage.

[nfs_clients]
maia-node-1 ansible_user=ansible-user ansible_become_password=ansible ansible_become=true ansible_become_method=sudo
maia-node-2 ansible_user=ansible-user ansible_become_password=ansible ansible_become=true ansible_become_method=sudo

Roles applied: nfs (client tasks)

Note: The NFS server automatically configures firewall rules to allow access from hosts in the nfs_clients group.

Host Variables for LVM#

The lvm role requires host-specific variables to be defined for each host that will have LVM volumes created. These variables should be defined in host_vars/<hostname>.yml files.

Required Host Variable#

device_list: List of physical volumes (disk devices) to use for creating the volume group. Each device should be a block device path.

Example (host_vars/maia-node-0.yml):

device_list:
  - /dev/sda1
  - /dev/sdc2

Optional Host Variables#

local_storage_size: Size of the local storage logical volume (maia_0_local). Default: 100%FREE
- Can be specified as absolute size: 300g, 500m, 1t
- Or as percentage: 100%FREE, 50%FREE, 50%VG
nfs_storage_size: Size of the NFS storage logical volume (maia_0). Default: 100%FREE
- Only used for hosts in the nfs_server group
- Same format as local_storage_size

Example (host_vars/maia-node-0.yml for NFS server):

device_list:
  - /dev/sda1
  - /dev/sdc2
local_storage_size: 300g
nfs_storage_size: 1.8t

Example (host_vars/maia-node-1.yml for regular node):

device_list:
  - /dev/sda1
local_storage_size: 500g