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: .. code-block:: bash 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 HARBOR_USERNAME and HARBOR_PASSWORD - **HARBOR_USERNAME**: Username for authenticating with the MAIA Harbor registry. Only required if ``MAIA_PRIVATE_REGISTRY`` is set. - **HARBOR_PASSWORD**: Password for authenticating with the MAIA Harbor 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 ``HARBOR_USERNAME`` and ``HARBOR_PASSWORD`` (uses public registry) - **JSON_KEY_PATH**: Path to a JSON file containing Harbor credentials in the format: .. code-block:: json { "harbor_username": "username", "harbor_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.) - **.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 - **-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. .. code-block:: ini [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. .. code-block:: ini [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. .. code-block:: ini [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/.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``): .. code-block:: yaml 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): .. code-block:: yaml 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): .. code-block:: yaml device_list: - /dev/sda1 local_storage_size: 500g