Skip to main content

Installing mogenius

mogenius allows you to connect with Kubernetes clusters by installing the mogenius operator on a cluster. Once installed, you can start deploying projects and manage Kubernetes workloads through the mogenius platform. To begin the installation process, you'll first need to create a cluster in mogenius.


To successfully complete the next steps, you will need the following:

  • A domain you own, to which you can add a DNS record.
  • A Kubernetes cluster. We recommend a managed Kubernetes service, like EKS (Amazon AWS), AKS (Microsoft Azure) or GKE (Google Cloud Platform), but any cluster with Kubernetes version 1.24 or higher will work. To get started, a local Kubernetes like Docker Desktop, k3s, or minikube is also a great option.
  • A working installation of Helm and kubectl
  • OR optionally the mogenius CLI
  • Kubernetes cluster admin permissions

Resource requirements

The mogenius operator consists of several pods that will be deployed to your Kubernetes cluster. It will require at least 0.5 vCPU and 128 MB RAM.

Add a cluster in mogenius

In your organization open "Clusters" and select "Add cluster." Enter a display name for your cluster and confirm.


This will create a management pane for a Kubernetes cluster in mogenius. It will not create an actual Kubernetes cluster.

Install the operator

mogenius connects to your Kubernetes cluster via an operator that you'll need to deploy on Kubernetes. In the next step you will have two options to do this: using the mogenius CLI, or by using Helm.

mogenius CLI

Install the mogenius CLI, on your terminal perform a mocli login and then run the following command.

Installation via mogenius CLI
mocli cluster connect

You'll be asked to confirm the organization, the cluster that you want to connect, and your current kubecontext before the operator is being deployed.

Helm install

Retrieve the Helm install command from the user interface and run it on a terminal. Make sure that your kubecontext is set to the right Kubernetes cluster. The command will look something like this.

mogenius operator Helm install
helm repo add mogenius
helm repo update
helm install mogenius-operator mogenius/mogenius-k8s-manager -n mogenius --create-namespace --wait \
--set global.cluster_name="DISPLAY_NAME" \
--set global.api_key="API_KEY" \
--set global.namespace="mogenius"

Complete your cluster setup

After executing one of the install commands above, return back to the mogenius user interface and click "I ran the command." The UI will confirm once the operator has established a connection with the mogenius controlplane. To finish your setup you'll now see a list of services that you can install to get your cluster deployment-ready.

The operator scans your cluster and automatically offers a subset of services from the following list, depending on your cluster type and any existing services.

Ingress ControllerInstalls a traefik ingress controller to handle traffic from outside the cluster and more.
Metrics serverMaintained by Kubernetes-SIGs, handles metrics for built-in autoscaling pipelines.
cert-managerInstall the cert-manager to automatically issue Let's Encrypt certificates to your services.
ClusterissuerResponsible for signing certificates.
mogenius-traffic-collectorCollects and exposes detailed traffic data for your mogenius services for better monitoring.
mogenius-pod-stats-collectorCollects and exposes status events of pods for services in mogenius.
Internal container registryA Docker-based container registry inside Kubernetes.
MetalLB loadbalancerA load balancer for local clusters (e.g. Docker Desktop, k3s, minikube, etc.).

Select the services that you want to install on your cluster and confirm. You'll be taken to the settings page of your cluster while the services are installed.


If you're encountering issues with installing the operator, check out common problems in the section Troubleshooting clusters.

Next steps

Congrats, your cluster is now connected with mogenius 🎉
To complete the setup, make sure that hostname and container registry are set up in the cluster settings.