# Agents
Source: https://docs.mogenius.com/ai/agents
Configure AI agents that monitor your Kubernetes workloads, generate troubleshooting reports, and propose fixes for your approval.
Agents are configurable AI workers that run against your cluster. Each agent has its own instruction, scope, triggers, and tools, and files its findings as **reports** with actionable proposals that you review and approve.
mogenius ships a set of **curated default agents** for common use cases — such as workload troubleshooting — and you can adapt them or create your own.
Agents require a connected AI model. If you haven't configured one yet, see [AI Models & Setup](/ai/setup).
## Where to find agents
Open the **Agents** section at either level:
* **Cluster** — agents and reports across every namespace the operator manages.
* **Workspace** — the same view, scoped to that workspace's namespaces.
The landing page has two views, switched with the toggle at the top:
* **Reports** — the inbox of findings your agents have produced, with **Open** and **All** tabs.
* **Agents** — one box per configured agent, with its trigger summary, open‑proposal count, and last run.
## Managing agents
From the **Agents** view, each agent box offers:
* **Run now** — Trigger the agent immediately, independent of its schedule or event triggers.
* **Enable / disable** — Turn the agent's automatic triggers on or off without deleting it.
* **Configure** — Open the full configuration page.
* Selecting the box opens the **agent detail** page with its run history.
To create a new agent, choose **New agent** and fill in the configuration below. To remove one, open its configuration page and use **Delete agent** in the danger zone at the bottom — this is only available for existing agents and asks for confirmation before deleting.
## Configuring an agent
The configuration page is organized into sections. A live preview shows the resulting `Agent` resource (`mogenius.com/v1alpha1`) as YAML.
### Identity
* **Display name** — The human‑readable name shown in the UI.
* **Resource name** — The technical name (lowercase letters, digits, and dashes). Generated from the display name and fixed once the agent exists.
* **Description** — A one‑line summary of what the agent looks after.
* **Icon** — An icon for the agent box.
* **Instruction** — Free‑text guidance appended to the base system prompt on every run. This is where you describe what the agent should focus on.
* **Enabled** — Whether the agent's automatic triggers are active.
### Model
* **Use cluster default** — The agent uses the model marked as the cluster default.
* **Specific model** — Turn the default off to pick a particular model for this agent. Models are managed in [AI Models & Setup](/ai/setup).
### Scope
Scope defines what the agent may access. Choose one of:
* **Namespaces** — Select specific namespaces, or enable **All namespaces (`*`)**.
* **Workspace** — Reference a workspace; all of its namespaces are in scope.
### Triggers
Triggers decide when the agent runs. You can combine them, and you can always run an agent manually.
* **Cron** — Periodic runs on a schedule. Presets cover hourly, daily, weekly, and monthly, or you can enter a custom 5‑field cron expression.
* **On change** — Runs when resources in scope change. Configure which **kinds** wake the agent (e.g. `Pod`, `Deployment` — leave empty for all watched types), which **change types** apply (`created`, `updated`, `deleted`), and a **minimum interval** (cooldown) to debounce noisy resources.
* **Manual** — Every agent can be triggered on demand with **Run now** in the UI, or from the CLI with `mocli agent run `.
### Tools
Tools determine what the agent can do. See [Tools & Custom MCP Servers](/ai/tools) for details.
* **Built‑in — Kubernetes** — Read and manage Kubernetes resources in scope.
* **Built‑in — Helm** — Install, upgrade, and inspect Helm releases in scope.
* **Custom MCP servers** — Reference one or more [custom MCP servers](/ai/tools#custom-mcp-servers) to give the agent access to their tools.
### Budgets
Budgets override the model defaults for this agent:
* **Max tool calls per run** — Caps how many tool calls a single run may make.
* **Token budget per run** — Caps tokens per run (`0` = unlimited).
## Reports and proposals
When an agent runs, it produces **reports** collected in the Reports inbox. The inbox has two tabs:
* **Open** — Reports that still need attention (pending, in progress, proposed, or executing).
* **All** — Every report, including resolved and dismissed ones.
Reports carry a status that reflects their progress:
* **Pending** — Queued for processing.
* **In progress** — The agent is analyzing.
* **Proposal** — The agent has a proposed change awaiting your decision.
* **Executing / Executed** — An approved proposal is being applied, or has been applied.
* **Solved** — The proposed solution was accepted and the issue resolved.
* **Ignored / Rejected** — Dismissed by a user; hidden from dashboards and resource views.
* **Failed** — The report or its execution could not complete.
### Approving proposals
When an agent is confident in a fix, it attaches a **proposal** — a create, update, or delete operation on a resource. You can:
* **Show diff** — Review a visual diff between the current manifest and the agent's proposed version.
* **Approve** — Apply the proposal. mogenius executes the change and marks the report solved. Destructive operations (such as deleting a resource) ask for explicit confirmation first.
* **Reject / Ignore** — Dismiss the proposal without applying it.
* **Solve** — Mark the report as resolved manually.
* **Replay** — Re‑queue the report for a fresh analysis.
### Agent runs and the reasoning timeline
The **agent detail** page groups findings into **runs**. Each run shows how it was triggered (event, cron, or manual), its duration, and token usage. Open a run to see the agent's step‑by‑step **reasoning timeline** — the think → act → observe loop, including the tools it called and the findings it produced — updated live while the run is in progress.
## Reports on a resource
When you view a specific Kubernetes resource, a banner appears if an agent has detected an issue with it. The resource's report view is filtered to that resource, so you can review and act on findings in context.
# Chat with AI
Source: https://docs.mogenius.com/ai/chat
Use the interactive AI chat to ask questions, investigate issues, and manage your Kubernetes cluster through natural language.
The AI chat lets you interact with the mogenius AI directly through a conversational interface. You can ask questions, investigate issues, and give instructions — the assistant has access to your cluster and uses its tools to find answers and take action, reasoning step by step in a think → act → observe loop.
Chat requires a connected AI model. If you haven't configured one yet, see [AI Models & Setup](/ai/setup).
## Opening the chat
Open the chat from the **chat button** in the platform header — it appears in a sidebar next to your current view. You can also open it as a **separate window** to keep the conversation visible while you work elsewhere.
The chat is available at both the **Cluster** and **Workspace** level, and automatically scopes its responses to the context you're working in.
## What you can do
The assistant understands natural language and can use its tools to interact with your cluster on your behalf. Common uses include:
* Investigating issues such as misconfigured resources, unreachable applications, or networking problems.
* Querying cluster resources like Pods, Deployments, Services, and ConfigMaps.
* Getting guidance on resource optimization, node allocation, and resource limits.
* Reviewing and drafting Kubernetes manifests or Helm values.
* Troubleshooting interactively by feeding the assistant additional context.
## Chat modes
A mode selector tailors how the assistant responds:
* **Ask** — Answer questions and explain, without proposing changes.
* **Code** — Focus on writing and editing manifests, values, and configuration.
* **Plan** — Break a task down into a step‑by‑step plan before acting.
You can **clear the conversation** at any time to start fresh.
## Choosing a model
A model picker lets you switch between the models marked as **chat enabled** in [AI Models & Setup](/ai/setup). The cluster default is preselected. Switching models starts a fresh connection for the next message.
## Tools and reasoning
The chat uses the same tools as agents. As the assistant works, it shows which tools it is calling so you can follow its reasoning:
* **Kubernetes** — Query resources, read logs, describe Pods, inspect events, and retrieve manifests in real time.
* **Helm** — List releases, inspect chart values, and review release history.
* **Custom tools** — Any [custom MCP servers](/ai/tools#custom-mcp-servers) and integrations connected to your cluster.
See [Tools & Custom MCP Servers](/ai/tools) for the full picture.
## Streaming and cancelling
Responses stream in as they are generated, with an indicator while the assistant is thinking. If a response is heading in the wrong direction, use **Cancel** to stop it immediately and refine your prompt.
Each message offers quick actions — copy, retry, and edit & resend — plus feedback controls, and code blocks have their own copy button.
## Permissions
The assistant operates under the same permissions as the logged‑in user. If your role grants **View** access to specific namespaces, the chat can only query resources in those namespaces. It never exposes data beyond what you are authorized to see.
## Token usage
Chat conversations count toward the token limits of the model in use. A usage indicator shows how much of the budget has been consumed. Once a limit is reached, further messages are queued until it resets. See [token and budget limits](/ai/setup#token-and-budget-limits).
## Session persistence
Chat sessions are preserved across page reloads and browser refreshes, scoped to your user and the current organization, cluster, and workspace. You can close the chat, navigate elsewhere, and return to an ongoing conversation without losing context.
# mogenius MCP Server
Source: https://docs.mogenius.com/ai/mcp-server
Connect external AI tools and IDEs to your mogenius cluster through the mogenius Model Context Protocol (MCP) server.
mogenius exposes its own **Model Context Protocol (MCP) server**, so external AI‑powered tools — such as IDE assistants, Claude Desktop, or custom automations — can interact with your Kubernetes cluster through the same AI infrastructure that powers [Agents](/ai/agents) and [Chat](/ai/chat).
This is the **outbound** direction: external clients connect **to** mogenius. To connect external tools **to your agents** (for example a GitHub or GitLab MCP server), see [Tools & Custom MCP Servers](/ai/tools#custom-mcp-servers) instead.
## Authentication & permissions
Access to the mogenius MCP server requires a valid **API key** generated in the platform. Each API key is tied to a specific user and inherits that user's workspace permissions.
This means:
* The MCP client can only access namespaces and resources the API key owner is permitted to view or manage.
* You can create separate API keys per workspace, each scoped to that workspace's resources and permissions.
* API keys can be revoked at any time from the platform settings.
You can create an API key from the settings of a **Cluster** or **Workspace**.
## Connecting a client
Add the mogenius MCP server to your client's configuration. The exact steps depend on the tool, but typically you edit a local config file that lists the client's MCP servers. Replace the endpoint and API key to match your setup.
### Claude Desktop
For remote MCP servers, Claude uses Connectors. mogenius is not yet available as a Connector, but you can configure it as a local MCP server. Adapt the following and add it to your `claude_desktop_config.json`:
```json theme={null}
"mcpServers": {
"mogenius": {
"command": "PATH-TO-YOUR-NODE-INSTALLATION/.nvm/versions/node/v23.3.0/bin/npx",
"args": [
"-y",
"mcp-remote",
"https://platform-api.mogenius.com/mcp",
"--header",
"Authorization: bearer YOUR-MOGENIUS-API-KEY"
],
"env": {
"PATH": "PATH-TO-YOUR-NODE-INSTALLATION/.nvm/versions/node/v23.3.0/bin:/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin"
}
}
}
```
### Cursor
In the Cursor Desktop app, open **Settings** and go to **Tools & MCP**. Add a new MCP server — Cursor opens your `mcp.json`, where you can add the mogenius server:
```json theme={null}
{
"mcpServers": {
"mogenius": {
"type": "streamable-http",
"url": "https://platform-api.mogenius.com/mcp",
"headers": {
"Authorization" : "bearer YOUR-MOGENIUS-API-KEY"
}
}
}
}
```
## Tools & capabilities
The mogenius MCP server exposes the same tools available to agents and chat, so external clients can perform cluster operations through natural language or structured requests.
### Kubernetes
* List and describe Pods, Deployments, Services, ConfigMaps, and other resources.
* Read Pod logs and events for troubleshooting.
* Retrieve resource manifests and status information.
* Inspect namespace‑level overviews.
* Create and modify resources and workloads.
### Helm
* List installed Helm releases across namespaces.
* Inspect chart values and release configuration.
* Review release history and rollback information.
* Deploy Helm charts.
## Auditing MCP activity
Requests made through the mogenius MCP server are recorded in the cluster [audit log](/cluster-management/audit-log) and tagged as MCP requests, so you can trace which actions were taken by external clients.
# AI on mogenius
Source: https://docs.mogenius.com/ai/overview
Configurable AI agents, an interactive chat, and connectable models and tools — the AI capabilities built into your mogenius cluster.
mogenius brings AI directly into your Kubernetes operations. Instead of a single fixed assistant, you get a **toolbox of configurable agents**, an interactive **chat**, and a shared foundation of **models** and **tools** that both build on.
Everything runs against your own cluster through the mogenius operator and respects your existing roles and permissions.
## The building blocks
* **Agents** — Configurable AI workers that watch your cluster and produce troubleshooting reports and actionable proposals. You can run the curated defaults, adapt them, or create your own. See [Agents](/ai/agents).
* **Chat** — An interactive assistant for asking questions, investigating issues, and drafting manifests through natural language. See [Chat](/ai/chat).
* **AI Models** — One or more language models (OpenAI, Anthropic, or any OpenAI‑compatible / Ollama endpoint) that power agents and chat. See [AI Models & Setup](/ai/setup).
* **Tools** — Built‑in Kubernetes and Helm access, plus custom [MCP](https://modelcontextprotocol.io) servers you connect as additional agent tools. See [Tools & Custom MCP Servers](/ai/tools).
All AI features require at least one connected AI model. If you haven't set one up yet, start with [AI Models & Setup](/ai/setup).
## Agents vs. Chat
Both use the same models and tools, but serve different jobs:
* **Agents** run **autonomously** — on a schedule, on cluster events, or on demand — and file their findings as **reports** you review and approve. Use them for continuous monitoring and remediation.
* **Chat** is **interactive** — you drive the conversation in real time. Use it for ad‑hoc investigation, questions, and quick edits.
## Where to find it
The AI features live under the **Agents** section in the platform:
* **Cluster level** — cluster‑wide agents and reports across every namespace the operator manages.
* **Workspace level** — the same view, scoped to the namespaces belonging to that workspace.
Models, tools, and custom MCP servers are managed centrally under **Cluster Settings → AI** and shared across the whole cluster.
## Get started
Add at least one AI model and mark a default. See [AI Models & Setup](/ai/setup).
Use a curated default agent or configure your own scope, triggers, and tools. See [Agents](/ai/agents).
Approve, reject, or apply the proposals your agents generate. See [Reports & proposals](/ai/agents#reports-and-proposals).
Open the chat for interactive investigation. See [Chat](/ai/chat).
# AI Models & Setup
Source: https://docs.mogenius.com/ai/setup
Connect one or more AI models, set a default, and configure token and budget limits for mogenius AI features.
All AI features in mogenius — [Agents](/ai/agents) and [Chat](/ai/chat) — run on the AI models you connect to your cluster. You can register **several models** and choose which one is the default and which are available in chat.
Models are managed centrally under **Cluster Settings → AI** and shared across the whole cluster.
## Connecting an AI model
Open **Cluster Settings → AI** and add a model. Each model has the following fields:
* **SDK** — The provider: **OpenAI**, **Anthropic**, or **Ollama**. Choose OpenAI for any OpenAI‑compatible endpoint.
* **Model** — The model identifier. Pick from the list the provider returns; if none appear, check the endpoint and authentication.
* **API URL** — The endpoint URL. Required for Ollama and for OpenAI‑compatible providers; the standard OpenAI and Anthropic endpoints are used by default otherwise. Any [OpenAI‑compatible API endpoint](https://bentoml.com/llm/llm-inference-basics/openai-compatible-api) works.
* **API Key** — Authentication for the endpoint. Enter a key as plain text and mogenius stores it as a managed Kubernetes secret, or reference an existing secret. Ollama endpoints that require no authentication can be left without a key.
After saving, mogenius validates the connection and the model becomes available to your cluster.
You can add multiple models — for example a fast model for chat and a more capable model for agents. Each is stored as its own resource and can be edited, tested, or removed independently.
## Default and chat‑enabled models
* **Default** — Mark one model as the cluster default. Agents that don't specify their own model, and new chat sessions, use it automatically.
* **Chat enabled** — Toggle whether a model appears in the chat model picker. This lets you keep some models for agents only.
## Token and budget limits
Limits are configured **per model**, so each model carries its own budget:
* **Daily token limit** — The maximum tokens the model may consume per day across agents and chat (`0` = unlimited). Once reached, further work is queued until the limit resets.
* **Token budget per run** — A per‑run cap on tokens (`0` = unlimited). Agents can override this in their own [budget settings](/ai/agents#budgets).
* **Max tool calls per run** — A per‑run cap on how many tool calls the model may make. Agents can override this too.
Each model shows its current usage, and you can **reset the usage** counter manually at any time.
## Testing and maintenance
The model list provides administrative controls per model:
* **Test** — Runs a connectivity probe against the endpoint and reports whether the model is reachable and correctly authenticated. A readiness badge reflects the current state.
* **Reset usage** — Resets the recorded token usage for that model to zero.
## Next steps
* Configure what your agents do in [Agents](/ai/agents).
* Give agents extra capabilities in [Tools & Custom MCP Servers](/ai/tools).
* Start an interactive session in [Chat](/ai/chat).
# Tools & Custom MCP Servers
Source: https://docs.mogenius.com/ai/tools
Give agents and chat access to your cluster with built-in tools, and extend them with custom MCP servers and integrations.
Tools are what let mogenius AI *do* things rather than just answer. Both [agents](/ai/agents) and [chat](/ai/chat) draw on the same set of tools: built‑in Kubernetes and Helm access, plus any custom [MCP](https://modelcontextprotocol.io) servers and integrations you connect.
## Built‑in tools
These tools are always available once an AI model is configured. Agents enable them per agent; chat uses them automatically.
* **Kubernetes** — Query and inspect resources (Pods, Deployments, Services, ConfigMaps, events), read logs, describe resources, and retrieve manifests. With write access in scope, agents can also create and modify resources.
* **Helm** — List releases, inspect chart values, review release history, and install or upgrade releases in scope.
During an agent run or chat conversation, tool usage is shown so you can see which tools are being used to reach an answer.
## Custom MCP servers
The [Model Context Protocol (MCP)](https://modelcontextprotocol.io) is an open standard for connecting AI models to external tools. mogenius lets you register **custom MCP servers** and expose their tools to your agents — for example a GitHub, GitLab, or Atlassian server, or your own internal tooling.
Custom MCP servers are managed centrally under **Cluster Settings → AI**, alongside your models. Define a server once and reference it from any number of agents.
### Adding an MCP server
Each MCP server has the following configuration:
* **Display name & description** — A name for the server and a short note on what its tools are for. The description helps the agent decide when to use it.
* **Transport** — How mogenius connects to the server: **Streamable HTTP** (recommended) or **SSE**. Local `stdio` servers are not supported.
* **URL** — The server endpoint. Required.
* **Authentication** — One of **None**, **Bearer token**, or **API key**. For bearer/API‑key auth, enter the token (stored as a managed secret) or reference an existing secret; the API‑key header defaults to `X-Api-Key` and can be customized.
* **Allowed tools** — An optional allowlist restricting which of the server's tools agents may use. Leave empty to expose all discovered tools.
* **Headers** — Optional additional request headers.
Once connected, mogenius discovers the server's tools and shows a readiness state, the number of available tools, and when it last connected.
### Assigning MCP servers to an agent
In an agent's [Tools configuration](/ai/agents#tools), select the MCP servers it may use. The agent then has access to the tools those servers expose (filtered by each server's allowlist). The agent detail page shows the connected tools as tags.
## GitHub & memory repository
mogenius also supports connecting a **GitHub** account and a **memory repository** as chat integrations, configured under **Cluster Settings → AI**:
* **GitHub** — Provide a personal access token so the assistant can look up source code, configuration, and CI/CD pipelines in your linked repositories and cross‑reference them with cluster state.
* **Memory repository** — A GitHub repository the assistant uses to read and write long‑term context, so it can recall recurring issues, environment‑specific quirks, and team conventions over time. You can use an [agents.md](https://agents.md/) file to provide organization‑specific guidance.
For connecting external clients such as Cursor or Claude Desktop **to** mogenius — rather than connecting tools **to** your agents — see the [mogenius MCP Server](/ai/mcp-server).
# Clusters & contexts
Source: https://docs.mogenius.com/cli/clusters-and-contexts
List every reachable cluster and target a mogenius platform cluster or a local kubeconfig context
`mocli` reaches a cluster either through the mogenius platform or straight through your kubeconfig. A **context** stores which cluster you are pointed at (plus a default namespace) so that resource commands run without re-selecting it every time.
## List every reachable cluster
`get-contexts` shows the mogenius clusters of every organization you belong to **and** the contexts in your kubeconfig, in one table. The active one is marked with `*`.
```bash theme={null}
# Both sources side by side
mocli config get-contexts
# kubeconfig contexts only
mocli config get-contexts --direct
```
mogenius clusters are only listed when you are already logged in — `get-contexts` never opens a browser. A kubeconfig is read regardless of login.
## Set your context
```bash theme={null}
# Interactive setup — pick a platform cluster (org + cluster + default namespace)
mocli config use-context
# Non-interactive platform cluster
mocli config use-context --org acme --cluster prod -n acme-staging
# Pin a kubeconfig context (direct access)
mocli config use-context --context kind-dev
# Use a specific kubeconfig file
mocli config use-context --kubeconfig ~/clusters/dev.yaml --context dev
# Show what you are currently pointed at
mocli config current-context
# List available organizations and clusters (platform)
mocli config list
```
The context is stored locally and used by all resource commands. You can override it per command with the flags below.
## Connection flags
These flags work on any command and select the connection for that invocation:
| Flag | Meaning |
| - | - |
| `--kubeconfig ` | Path to a kubeconfig file (implies direct access) |
| `--context ` | kubeconfig context to use (implies direct access) |
| `--direct` | Use the kubeconfig's current-context |
| `--platform` | Force the mogenius connection even if a direct one is saved |
| `--org`, `--cluster`, `-n` | Override the platform organization, cluster, and namespace |
## kubeconfig resolution
Direct access follows standard kubeconfig resolution: `$KUBECONFIG` first, then `~/.kube/config`, including multi-file merging. `exec` credential plugins work out of the box — for example `aws eks get-token` or `gke-gcloud-auth-plugin` — so cloud clusters authenticate exactly as they do with `kubectl`.
`mocli cluster connect` (registering a cluster with the platform and installing the operator) is a platform action and has no meaning on a direct kubeconfig connection. See [Installing the mogenius operator](/cluster-management/installing-the-mogenius-operator).
# CLI commands
Source: https://docs.mogenius.com/cli/commands
kubectl-style verbs for scripting and automation with mocli
In addition to the [Terminal UI](/cli/terminal-ui), `mocli` provides kubectl-style CLI commands for scripting and automation. They run against your active [context](/cli/clusters-and-contexts) and accept the same connection flags (`--org/--cluster/-n`, `--context`, `--kubeconfig`, `--direct`, `--platform`).
## Listing and getting resources
```bash theme={null}
# List all pods in a namespace
mocli get pods -n acme-staging
# Get a specific resource
mocli get deployment my-app -n acme-staging
# Output as YAML or JSON
mocli get configmap my-config -n acme-staging -o yaml
mocli get secret db-credentials -n acme-staging -o json
# Wide output with additional columns
mocli get pods -n acme-staging -o wide
# List cluster-scoped resources
mocli get crd
mocli get namespaces
```
`mocli list` is an alias for `mocli get` when listing all resources of a kind:
```bash theme={null}
mocli list pods -n acme-staging
mocli list cronjobs -n acme-staging
```
## Describing resources
Show a detailed, human-readable view of a resource — its spec, status, and recent events:
```bash theme={null}
mocli describe pod my-pod-abc123 -n acme-staging
mocli describe deployment my-app -n acme-staging
```
## Creating resources
Create resources from manifest files or directly via CLI:
```bash theme={null}
# Create from a YAML manifest (supports multi-document files)
mocli create -f manifest.yaml -n acme-staging
# Create a namespace
mocli create namespace acme-staging
# Create a Job with a container image
mocli create job db-migration --image=postgres:15 -n acme-staging
# Create a Job with a custom command
mocli create job db-migration --image=postgres:15 -n acme-staging -- pg_dump -h db
# Create a Job from a CronJob template (trigger a one-off run)
mocli create job --from=cronjob/nightly-backup -n acme-staging
```
## Applying resources
Apply a manifest with create-or-update semantics — resources that don't exist yet are created, and resources that already exist are updated in place. Applying the same manifest twice is safe (idempotent):
```bash theme={null}
mocli apply -f deployment.yaml -n acme-staging
mocli apply -f manifests.yaml -n acme-staging
```
Unlike `mocli create`, which fails when a resource already exists, `mocli apply` reconciles the cluster to match your manifest — making it the safer choice for repeatable deployments and CI/CD pipelines.
## Editing resources
Open a resource in your editor and apply the changes on save (uses `$KUBE_EDITOR` or `$EDITOR`):
```bash theme={null}
mocli edit deployment my-app -n acme-staging
mocli edit configmap my-config -n acme-staging
```
## Scaling and restarting workloads
```bash theme={null}
# Scale a deployment
mocli scale deployment my-app --replicas=3 -n acme-staging
# Roll out a fresh set of pods (restart)
mocli rollout restart deployment my-app -n acme-staging
```
## Resource usage
Show CPU and memory usage for pods and nodes:
```bash theme={null}
mocli top pod -n acme-staging
mocli top node
```
On a direct kubeconfig connection, `top` and pod CPU/RAM columns require a [metrics-server](https://github.com/kubernetes-sigs/metrics-server) on the cluster.
## Deleting resources
```bash theme={null}
# Delete a specific resource (prompts for confirmation)
mocli delete pod my-pod-abc123 -n acme-staging
mocli delete job db-migration -n acme-staging
# Skip confirmation prompt
mocli delete pod my-pod-abc123 -n acme-staging -y
# Delete resources defined in a manifest
mocli delete -f manifest.yaml
```
## Shell access
Open an interactive shell in a running container:
```bash theme={null}
# Shell into a pod (uses first container if multiple)
mocli shell my-pod -n acme-staging
# Specify a container
mocli shell my-pod -c app -n acme-staging
```
`mocli exec` is an alias for `mocli shell`.
## Viewing logs
Stream or fetch logs from pods and jobs:
```bash theme={null}
# View logs from a pod
mocli logs my-pod -n acme-staging
# View logs from a specific container (multi-container pods)
mocli logs my-pod -c app -n acme-staging
# Stream logs in real-time
mocli logs my-pod -f -n acme-staging
# View logs from a Job (automatically finds the pod)
mocli logs job/db-migration -n acme-staging
```
## Waiting for conditions
Wait for a resource to reach a specific condition — useful in CI/CD pipelines:
```bash theme={null}
# Wait for a Job to complete
mocli wait job/db-migration --for=condition=complete -n acme-staging
# With a timeout
mocli wait job/db-migration --for=condition=complete --timeout=10m -n acme-staging
# Wait for a Pod to be ready
mocli wait pod/my-pod --for=condition=ready -n acme-staging
# Wait for a resource to be deleted
mocli wait pod/my-pod --for=delete -n acme-staging
```
**Supported conditions:**
* `condition=complete` — Job completed successfully
* `condition=failed` — Job failed
* `condition=ready` — Pod is ready
* `delete` — Resource has been deleted
## Shell autocompletion
`mocli` can complete commands, flags, and even live resource names, namespaces, and kinds directly in your shell.
The quickest way is to let `mocli` detect your shell and set everything up automatically:
```bash theme={null}
mocli completion install
```
This adds a source line to your shell's config file (`~/.zshrc`, `~/.bashrc`) or writes a completion file for fish (`~/.config/fish/completions/`). The command is idempotent — running it twice does nothing. Restart your shell or re-source the config file to activate it.
To set it up manually, generate the completion script for your shell:
```bash theme={null}
mocli completion zsh
mocli completion bash
mocli completion fish
mocli completion powershell
```
Autocompletion is dynamic: when you tab-complete a resource name, namespace, or kind, `mocli` queries your active context live — so you get the real names from your cluster, not just static command names.
## Version
```bash theme={null}
mocli version
```
# Installation
Source: https://docs.mogenius.com/cli/installation
Install mocli, sign in for platform features, and configure self-hosted or API-key access
## Install
### Mac, Linux
Use [homebrew](https://brew.sh) to install `mocli`:
```bash theme={null}
brew tap mogenius/mocli
brew install mocli
```
On Linux with a headless machine, `mocli login` requires a browser for the initial login. After the first login, your session persists locally.
### Windows
```bash theme={null}
scoop bucket add mocli https://github.com/mogenius/homebrew-mocli
scoop install mocli
```
## Login (optional)
Signing in to mogenius is **optional** — you only need it for the platform features (organizations, workspaces, operator-connected clusters, tunnels). Working against a local kubeconfig needs no login.
To use platform features, authenticate once. Your browser opens automatically to complete the login:
```bash theme={null}
mocli login
```
Your session is stored locally, so you only need to log in once per machine.
```bash theme={null}
# Log out again
mocli logout
```
## Self-hosted instances
By default, `mocli` connects to the mogenius cloud at `app.mogenius.com`. If you run a self-hosted mogenius platform, point `mocli` at your own instance by editing its configuration file.
The config file lives at:
| OS | Path |
| - | - |
| Mac, Linux | `~/.mocli/config.yaml` |
| Windows | `%USERPROFILE%\.mocli\config.yaml` |
Replace the endpoints in the `services` block with the URLs of your self-hosted deployment:
```yaml theme={null}
services:
api: "https://platform-api.mogenius.example.com/"
user: "https://platform-user.mogenius.example.com/"
platform: "https://app.mogenius.example.com/"
ws: "wss://k8s-cmd-stream.mogenius.example.com"
socket: "https://platform-ws.mogenius.example.com"
```
All five endpoints refer to the same self-hosted instance. Ask your platform administrator for the exact hostnames if you are unsure — they follow the DNS scheme configured during installation.
`mocli` must be able to reach these endpoints over the network from the machine it runs on. In restricted environments where the platform is only reachable from inside a managed desktop or jump host (for example via a VDI or bastion), run `mocli` there rather than on your local machine.
## API-key authentication
For automated pipelines — or locked-down environments where the browser callback used by `mocli login` is blocked — authenticate with an API key instead. It needs no local callback server:
```bash theme={null}
# API-key login
mocli login --api-key mo_pat:
# Or via environment variable
export MOGENIUS_API_KEY=mo_pat:
mocli login --api-key
```
Create the API key in your mogenius profile settings. The key is a single opaque token starting with `mo_pat:`. When `MOGENIUS_API_KEY` is set, `mocli` automatically uses API-key authentication.
**CI/CD integration:** set the `MOGENIUS_API_KEY` environment variable in your pipeline and `mocli` picks it up automatically — no interactive step required.
# Overview
Source: https://docs.mogenius.com/cli/overview
Manage Kubernetes clusters, resources, and workloads from your terminal with mocli — through the mogenius platform or straight through your kubeconfig
`mocli` is the mogenius command-line tool. It ships an interactive Terminal UI (k9s-style navigation) and kubectl-style commands for scripting — browse resources, stream logs, open shells, and set up port-forwards, all from your terminal.
## Two ways to connect
`mocli` reaches a cluster in one of two ways, and lists both side by side:
* **mogenius platform** — clusters connected to your mogenius organization through the operator. Authentication is handled by the platform, so you get secure access to any connected cluster from anywhere without a local kubeconfig.
* **Local kubeconfig (direct access)** — point `mocli` at a kubeconfig context and go. No operator, no `mocli login` required. Standard kubeconfig resolution applies, including `exec` credential plugins like `aws eks get-token`.
You choose the connection when you set your context or with connection flags — see [Clusters & contexts](/cli/clusters-and-contexts).
## What works where
Features a plain kubeconfig connection cannot provide are hidden rather than failing when you reach for them.
| Capability | mogenius | kubeconfig |
| - | :-: | :-: |
| Browse, describe, edit and delete resources | ✅ | ✅ |
| Logs, shell, port-forward | ✅ | ✅ |
| Organizations and workspaces | ✅ | — |
| Public tunnel URLs | ✅ | local only |
| RBAC-enforced access without handing out a kubeconfig | ✅ | — |
| `mocli ssh-proxy` / `setup-ssh` | ✅ | — |
| Operator install and upgrade (`mocli cluster connect`) | ✅ | — |
| Pod CPU/RAM columns | ✅ | needs metrics-server |
| Server-side search and sorting | ✅ | done locally |
## Get started
Install `mocli`, sign in (optional), and configure self-hosted or API-key access.
List every reachable cluster and pick a platform cluster or a kubeconfig context.
Launch `mocli tui` for a full-screen, k9s-style view of your cluster.
kubectl-style verbs for scripting and automation.
# Port forwarding
Source: https://docs.mogenius.com/cli/port-forwarding
Create secure TCP tunnels to Kubernetes workloads from the terminal with mocli
Use the CLI to create TCP tunnels to Kubernetes workloads:
```bash theme={null}
mocli port-forward -n -k -w -p :
```
Supported resource kinds: `Pod`, `Service`, `Deployment`, `StatefulSet`, `DaemonSet`
## Examples
```bash theme={null}
# Forward to a Service
mocli port-forward -n production -k Service -w postgres -p 5432:5432
# Forward to a Deployment
mocli port-forward -n staging -k Deployment -w api-server -p 8080:8080
# Forward to a specific Pod
mocli port-forward -n default -k Pod -w my-pod-abc123 -p 3000:3000
```
## Flags
| Flag | Description |
| - | - |
| `-n, --namespace` | Kubernetes namespace (required) |
| `-k, --kind` | Resource kind (required) |
| `-w, --name` | Workload name (required) |
| `-p, --port` | Port mapping `LOCAL:REMOTE` (required) |
The tunnel remains active while the CLI process runs. Press `Ctrl+C` to terminate.
On a mogenius platform connection, port-forwards are tunnelled through the platform with full RBAC enforcement and can be exposed as public tunnel URLs. On a direct kubeconfig connection, forwards are local only. See [Tunnels](/workspaces/tunnels).
# Terminal UI
Source: https://docs.mogenius.com/cli/terminal-ui
Browse and manage your resources in a full-screen, k9s-style interface with mocli tui
Launch the interactive Terminal UI to browse and manage your resources:
```bash theme={null}
mocli tui
```
The TUI provides a visual interface for navigating your clusters and Kubernetes resources. It works against both a mogenius platform cluster and a local kubeconfig context — on a platform connection you additionally navigate through organizations and clusters. All keybindings are displayed at the bottom of each screen.
## Navigation
The TUI follows a hierarchical navigation pattern. On a platform connection this starts at the organization; a direct kubeconfig connection has no org/cluster hierarchy above the cluster.
**Organization → Cluster → Namespace → Resources**
| Key | Action |
| - | - |
| Arrow keys | Move up/down |
| `Enter` | Select / drill down |
| `Esc` | Go back |
| `q` | Quit |
| `/` | Filter list |
| `:` | Command mode (switch resource types, including CRDs) |
## Browsing resources
Once you select a namespace, you'll see a list of Pods by default. Use command mode (`:`) to switch between resource types:
* `:pods` or `:po` — Pods
* `:deployments` or `:deploy` — Deployments
* `:services` or `:svc` — Services
* `:statefulsets` or `:sts` — StatefulSets
* `:daemonsets` or `:ds` — DaemonSets
* `:jobs` — Jobs
* `:cronjobs` or `:cj` — CronJobs
* `:configmaps` or `:cm` — ConfigMaps
* `:secrets` — Secrets
* `:ingresses` or `:ing` — Ingresses
The TUI also supports custom resources (CRDs) — type the resource name in command mode to browse any resource type available in your cluster.
## Viewing logs
Select a Pod and press `Enter` to view its logs in real-time. If the Pod has multiple containers, you'll be prompted to select one.
| Key | Action |
| - | - |
| `PgUp` / `PgDn` | Scroll through logs |
| `s` | Toggle autoscroll |
| `w` | Toggle word wrap |
| `Esc` | Return to resource list |
## Port forwarding
From the logs view or resource list, press `t` to create a port-forward tunnel to the selected Pod. Enter the port mapping (e.g., `8080:80`) and the tunnel will be established.
Active tunnels persist while the TUI is running. Press `Esc` from the port-forward view to return to browsing while keeping tunnels open. See [Port forwarding](/cli/port-forwarding) for the scriptable CLI equivalent.
## Shell access
Select a Pod and press `x` to open an interactive shell session in the container. If the Pod has multiple containers, you'll be prompted to select one.
On a platform connection the shell session is tunnelled through the mogenius platform — no local kubeconfig or direct cluster access required.
# Active cluster sync
Source: https://docs.mogenius.com/cluster-management/active-cluster-sync
Use Active Cluster Sync to synchronize Kubernetes workloads with Git.
This feature is currently in closed beta. [Contact us](mailto:support@mogenius.com) if you're interested in Active Cluster Sync.
With Active Cluster Sync, you can use the mogenius operator to synchronize a Kubernetes cluster with a Git repository. Once activated, all Kubernetes workloads will be stored and updated in the repository as YAML files. The sync strategy setting allows you to synchronize workloads across multiple Kubernetes clusters. This feature is highly useful for several scenarios:
* **Backup and Failover:** Create a hot backup of a Kubernetes cluster that always mirrors the exact state of your production cluster. If there is an incident with your primary cluster, you can fail over to the backup to minimize downtime.
* **Kubernetes Migration:** When you need to migrate a Kubernetes cluster from one provider or data center to another, you can quickly create a clone of your current cluster. This allows you to test all workloads in the new environment before fully transitioning your workflows to the new infrastructure.
* **Bridging Location Limitations:** If regulations or data privacy laws require your organization to serve customers from specific locations where your current cloud provider does not have a data center, managing multiple providers can be costly and prone to errors. Active Cluster Sync provides a solution by maintaining a streamlined workflow for deploying and updating applications on your main infrastructure, while serving edge locations with replicas of your main setup.
## Configuration
In your organization, navigate to the settings of your cluster and scroll down to the "Active Cluster Sync" section. Fill in the form fields as follows:
* **Git repository URL**: Enter the URL of the repository to be used for synchronization (e.g., [https://github.com/yourorganization/syncrepo.git](https://github.com/yourorganization/syncrepo.git)).
* **Git branch**: Specify the branch that should be targeted for the sync.
* **PAT**: Enter a Personal Access Token that has access to the defined repository. The token must have permissions to add and change the contents of the repository.
* **Sync strategy**: More details below.
* **Ignored namespaces**: List the namespaces that won’t be synchronized by the operator.
## Sync strategy
The sync strategy setting determines the synchronization behavior of the operator on your Kubernetes cluster:
* **None**: This is the default setting where no synchronization is enabled. Use this setting if you have previously applied a sync strategy and wish to stop the synchronization.
* **Push**: This strategy pushes all workloads to the repository and updates them if changes on the cluster are detected. Manual changes to the YAML files stored in the repository will be overwritten. For the initial synchronization, an empty repository is required; otherwise, the initial sync will be canceled.
* **Pull**: This strategy pulls workloads from the repository and applies them to your Kubernetes cluster. Any changes on the cluster that differ from the YAML files stored in Git will be overwritten.
* **Push & Pull**: This setting combines both strategies, enabling bi-directional synchronization. Changes on Kubernetes will be pushed to the repository, and changes in Git will be pulled to the cluster. This excludes changes applied by the sync workflow itself to avoid infinite loops.
The operator will monitor changes and apply the configured sync strategy every 10 seconds. All sync activities are logged by the operator's pod. To view the log, navigate to Workloads > Pods in your cluster and open the pod named mogenius-k8s-manager.
# Audit log
Source: https://docs.mogenius.com/cluster-management/audit-log
The audit log provides a streamlined history of all changes made through the mogenius platform on your cluster. It serves as a crucial tool for identifying the root cause of failures and is an essential component for maintaining compliance in regulated environments through fully audited workflows.
## How Does It Work?
The audit log captures all changes performed via the mogenius platform. Whenever a user creates, updates, or deletes a resource on your cluster using mogenius, a corresponding entry is generated in the audit log.
## Logged Information
Each audit log entry includes the following details (when applicable):
* Type: The type of operation and resource, e.g., create/workload
* Age: Timestamp for when the action occurred
* Kind, Namespace, and Workspace: Details of the modified resource
* User: The mogenius user who triggered the action
* Diff: Shows a visual difference between the resource state before and after the change
* Status: Indicates the result of the operation (e.g., success or error)
You can click on each log item to view the full API payload, along with the diff and any errors that occurred during the operation.
The audit log only tracks actions performed through the mogenius platform. Changes made directly on the cluster (e.g., using kubectl) are not logged.
To ensure a fully auditable workflow, we recommend limiting direct access to your cluster and enabling user interactions exclusively through mogenius.
# Cluster settings
Source: https://docs.mogenius.com/cluster-management/cluster-settings
Prepare a cluster in mogenius to connect with your own Kubernetes cluster.
On the "Settings" tab in a cluster, you can manage metadata, baseline components, default hostnames for ingresses, and more.
## General Cluster Information
Modify metadata information of your cluster for displaying purposes in your cluster overview.
## Loadbalancer
If you're using an ingress controller, you can use this setting to define a default hostname that will be used when you expose a port on a deployment.
Fill in the form fields to set up a default domain for your cluster:
* Loadbalancer IPs: If an IngressController is running on your cluster, the external loadbalancer IP address of your cluster will usually be filled out automatically. If the IP is not set automatically, you can enter it manually.
* Loadbalancer Host: Enter a hostname for your cluster. Each service on the cluster will be created under a subdomain of this hostname by default. Later, you can set individual domains in the settings of each service.
### Connecting your domain
In your DNS settings, create two records of type A:
| Type | Name (example) | Target |
| - | - | - |
| A | yourdomain.com | LOADBALANCER\_IP |
| A | \*.yourdomain.com | LOADBALANCER\_IP |
## Platform config
Under **Settings → Platform config** you can view and edit your cluster's [Platform Config](/cluster-management/platform-config) — the declarative tool stack (GitOps, ingress, certificates, monitoring, secrets, and more) that the operator keeps in sync. Every change you save is written back to the connected Git repository, and the GitOps engine applies it to the cluster.
## Blueprints
To create applications and services on your cluster from pre-configured Helm charts, use [Blueprints](/deploying-applications/blueprints). Blueprints provide sensible defaults that you can review and customize before deploying, and support optional GitOps integration.
Platform Config and Blueprints cover two distinct roles: the **Platform Config** manages the cluster's shared platform tool stack (the admin's job), while **Blueprints** create applications on top of it (what the user does).
If you previously installed services through Cluster Services, they continue to work as standard Helm releases. No migration is needed. For new installations, use Blueprints instead.
## Reset cluster MFA-ID
Use this option to reset the connection with your Kubernetes cluster. This is necessary if you're re-installing the operator on a Kubernetes cluster, as each connection between the mogenius platform and an operator is kept unique.
## Deleting a cluster
Deleting a cluster will remove it from your organization together with all workspaces that were created on that cluster. The resources on Kubernetes aren't affected by this. Since workspaces are a CRD, they will reappear in your organization after reconnecting your cluster.
# GitOps with Argo CD
Source: https://docs.mogenius.com/cluster-management/gitops/argocd
This page covers mogenius' **Argo CD**–based GitOps workflow. For the GitOps concept and help choosing between the two engines, see the [GitOps overview](/cluster-management/gitops/overview).
The Argo CD path in mogenius is **UI-first**: you deploy through the mogenius UI, mogenius generates the Kubernetes manifests and commits them to your Git repository, and Argo CD syncs them to your cluster. mogenius installs and manages Argo CD (and Sealed Secrets) for you.
**Here's how you can use that in your teams:**
* Deploy containers to Kubernetes using the mogenius UI, without requiring deep Kubernetes knowledge. Then, add them to GitOps for deploying them to production-grade deployments.
* Configure your applications once and then deploy them to additional environments for a staged development workflow. See [Multi-Environment Deployments](/deploying-applications/multi-environment-deployments) for a practical guide.
* Backup all your manifests to recover your cluster state in case of an incident.
## How the Argo CD workflow works
The Argo CD workflow in mogenius follows a UI-first approach. You don't need to write Kubernetes manifests manually — mogenius generates them for you.
Here's the end-to-end flow:
1. **Deploy via the UI**: Use the mogenius UI to deploy applications through [container images](/deploying-applications/container-images), [pipeline starters](/deploying-applications/pipeline-starters), [Helm charts](/deploying-applications/helm-charts), or [Kubernetes manifests](/deploying-applications/kubernetes-manifests).
2. **Enable GitOps** on your cluster (see setup below).
3. **Create a GitOps application** that includes your deployments.
4. **Manifests are auto-generated**: mogenius automatically creates the Kubernetes manifests (`application.yaml`) for all selected resources and commits them to your Git repository. You do not need to write these manifests yourself.
5. **Changes sync through Git**: When you modify configurations in the mogenius UI (environment variables, health checks, scaling, etc.), the changes are committed to Git. ArgoCD then syncs the updated manifests to your cluster.
This means you get the speed and simplicity of UI-based deployments combined with the reliability and auditability of Git-based infrastructure management.
## GitOps setup
You can configure GitOps for each cluster. Navigate to **Clusters** in your organization and open the tab **GitOps**. Click the button to enable GitOps and open the configuration page.
mogenius comes with a pre-configured stack for enabling GitOps consisting of two main applications:
1. ArgoCD: mogenius relies on the open-source project [ArgoCD](https://github.com/argoproj/argo-cd) as the GitOps engine.
2. Sealed Secrets: To securely synchronize secrets with Git, mogenius uses [Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) to encrypt secrets when transferring them to Git.
The setup form uses defaults that should work out of the box. You can overwrite them to customize the installation.
Already have ArgoCD and/or Sealed Secrets installed on your cluster? If possible, mogenius detects existing installations and updates the settings in the setup form. Check the default values and adjust them if they don't match your installation.
Your applications on a cluster will be synced with a Git repository. mogenius supports both GitHub and GitLab as providers.
To set up a GitHub repository, go to github.com and perform the following steps:
* Create a new repository and make sure it has a branch.
* Create a Personal Access Token. It requires at least `read/write` permissions on `Contents`. This way mogenius can commit changes on applications to the repository. If you want to use pull requests instead, make sure that the access token has `read/write` permissions for `Pull Requests` as well. Make sure to copy the PAT to a safe location.
**Branch protection and direct commits:** If you enable branch protection rules on your repository (e.g., requiring pull request reviews), direct commits from the mogenius UI will fail with an error. In this case, you must use the pull request workflow instead. The mogenius UI provides buttons to create pull requests when saving changes to GitOps-managed resources.
To set up a GitLab repository, go to gitlab.com (or your self-hosted GitLab instance) and perform the following steps:
* Create a new repository (project) and make sure it has a branch.
* Create a Personal Access Token. Navigate to **User Settings** → **Access Tokens** and create a new token.
GitLab's fine-grained personal access tokens are currently in Beta. For reliable integration, use a **Personal Access Token (classic)** instead.
The token requires the following scopes:
* `read_user` — Read access to your user profile
* `read_repository` — Read access to the repository
* `write_repository` — Write access to the repository
* `read_api` — Read access to the API
* `api` — Full API access (required for write operations)
Make sure to copy the token to a safe location before leaving the page.
**Branch protection and direct commits:** If you enable branch protection rules on your repository (e.g., requiring merge request approvals), direct commits from the mogenius UI will fail with an error. In this case, you must use the pull request workflow instead. The mogenius UI provides buttons to create merge requests when saving changes to GitOps-managed resources.
You can use the same repository for multiple clusters. Your applications will be managed using the following structure for folders and files:\
`your-repository/mogenius/CLUSTER/APPLICATION/application.yaml`
Now, in your GitOps settings in mogenius, click **Connect repository** and follow the steps:
* Enter a name for the repository.
* Enter the Personal Access Token.
* Your username and a dropdown to select your repository will load. In the dropdown, search for your GitOps repository and select it.
* Set the commit behavior: By default, mogenius will commit changes directly on the branch of your application. Activate the toggle to create pull requests instead.
* Save your settings to connect the repository.
You can proceed with creating applications.
## Applications
Your workloads and resources in Kubernetes are tracked in GitOps as applications. Each application consists of one or more resources.
Typical examples for how applications can be defined:
* A deployment for your container, plus Ingress, Service, and Secrets that are used by the deployment.
* A platform deployment consisting of several microservices.
You can create applications in your cluster settings as an admin, or within Workspaces. In your cluster, scroll to the bottom of your **GitOps** page. In a Workspace, navigate to the page **GitOps applications**. Click the button **Create application** to configure a new application.
Here's how it works:
* Enter a name for your application. This is how it will be displayed in mogenius and it will be added as a folder to your Git repository.
* From the list of namespaces on your cluster, select the resources that you want to include in your application. You can select one namespace per application. Inside a namespace you can select all resources, or a selected list of resources.
* Confirm to create your application.
Your application is now added to the list, and mogenius automatically generates the Kubernetes manifests for all selected resources and stores them as `application.yaml` in your Git repository. It can take a few minutes until ArgoCD has synchronized it, and you'll see a loading animation in the meantime. Once it is synced, you'll see the status of your application and all included resources.
## Working with GitOps in mogenius
When workloads or resources in your Workspaces are part of an application (i.e. managed via GitOps), a status object `Application` will be shown. This indicates the sync status of the directory and the application. If an error occurs, you can hover over the status to view the error message.
### Updating workloads
You can continue using the mogenius UI to change configurations such as environment variables, resource limits, health checks, or YAML manifests on any resource. When saving changes, mogenius detects that GitOps is enabled for the resource and will update the corresponding `application.yaml` in Git. This follows the commit behavior defined in your cluster settings (direct commit or pull request). Changes are not applied directly to the cluster but will be synced by ArgoCD within a few minutes. You can monitor this sync using the Application status.
### GitOps log
You can track the history and changes of your `application.yaml` using the **GitOps log**. It is available on any resource managed by a GitOps application and shows commits and pull requests.
## ApplicationSets
ApplicationSets allow you to deploy applications from an external Git repository directly to your cluster using ArgoCD. Unlike standard Applications (which track mogenius-managed resources), ApplicationSets sync manifests that already exist in a Git repository — ideal for teams with existing Kubernetes configurations, Helm charts, or Kustomize overlays.
**When to use ApplicationSets:**
* You have existing Kubernetes manifests, Helm charts, or Kustomize overlays in Git
* You want to deploy the same application to multiple environments from a single source
* You're integrating mogenius with an existing GitOps workflow
### Creating an ApplicationSet
Navigate to **Clusters → \[Your Cluster] → GitOps** and click **Create ApplicationSet**.
* **ApplicationSet name**: A unique name for this ApplicationSet
* **Repository**: Select a connected Git repository containing your manifests
* **Branch**: The branch to sync from
* **Path**: The directory containing your manifests (e.g., `apps/my-service/overlays/prod`)
Choose how ArgoCD should interpret the contents of the path:
| Source Type | Use When | Path Must Contain |
| - | - | - |
| **Directory** | Plain Kubernetes YAML manifests | `.yaml` or `.json` files |
| **Helm** | Helm chart | `Chart.yaml` |
| **Kustomize** | Kustomize overlay | `kustomization.yaml` |
Depending on your source type, additional options are available:
**For Helm sources:**
* **Values Files**: Paths to values files (one per line, relative to chart directory). Files are applied in order — later files override earlier ones.
**For Kustomize sources:** See [Kustomize configuration](#kustomize-configuration) below.
Specify where ArgoCD should deploy resources if the manifests don't include a namespace. Leave empty to use the ArgoCD default namespace.
Once created, the ApplicationSet appears in your GitOps overview. ArgoCD will sync the manifests from Git and deploy them to your cluster. The sync status shows whether the cluster state matches the Git repository.
### Kustomize configuration
When using Kustomize as the source type, you can configure additional transformations that ArgoCD applies during deployment:
| Option | Description | Example |
| - | - | - |
| **Kustomize Namespace** | Override the namespace in all manifests | `production` |
| **Name Prefix** | Prepend a string to all resource names | `prod-` |
| **Name Suffix** | Append a string to all resource names | `-v2` |
| **Image Overrides** | Replace container images (one per line) | `nginx=my-registry/nginx:1.21` |
| **Common Labels** | Add labels to all resources (key=value per line) | `env=production` |
| **Common Annotations** | Add annotations to all resources | `owner=platform-team` |
If both **Target Namespace** and **Kustomize Namespace** are set but differ, Kustomize Namespace takes precedence and overrides the namespace in your manifests before deployment.
**Example: Deploying to production with Kustomize**
For a production deployment with environment-specific settings:
* **Path**: `apps/my-service/overlays/prod`
* **Kustomize Namespace**: `production`
* **Name Prefix**: `prod-`
* **Image Overrides**: `my-app=ghcr.io/myorg/my-app:v2.1.0`
* **Common Labels**: `app.kubernetes.io/env=production`
### Managing ApplicationSets
ApplicationSets are listed alongside standard Applications in the GitOps overview. You can:
* View the sync status and included resources
* Delete an ApplicationSet (this removes the ArgoCD ApplicationSet but does not delete deployed resources by default)
To update an ApplicationSet's configuration, delete it and create a new one with the updated settings.
## Argo CD Projects
Argo CD Projects provide a way to organize applications and control access to cluster resources. When connecting a Git repository, you can assign it to a specific Argo CD Project.
By default, mogenius creates a `mogenius` project for your applications. If you have existing Argo CD Projects on your cluster, you can select them when configuring a repository:
1. Navigate to **Clusters → \[Your Cluster] → GitOps**
2. When adding or editing a repository connection, use the **ArgoCD Project** dropdown to select the target project
Projects are useful for:
* Separating applications by team or environment
* Applying different sync policies or access controls
* Integrating with existing Argo CD setups that use project-based organization
## CI/CD integration with GitHub Actions
For teams that want to combine CI/CD builds with GitOps-based deployment, mogenius provides GitHub Actions workflow templates in the [mogenius build-workflows repository](https://github.com/mogenius/build-workflows). These templates automate the process of building your container image and triggering the mogenius operator to update the deployment, which is then tracked and synced by GitOps.
You can use these templates in two ways:
* **Through Pipeline Starters**: The easiest approach — mogenius sets up the GitHub Actions workflow for you directly from the UI. See [Pipeline Starters](/deploying-applications/pipeline-starters) for details.
* **Custom integration**: Use the workflow templates directly in your own CI/CD pipelines for more control over the build and deployment process.
## Working with Sealed Secrets
When GitOps is enabled, secrets cannot be stored in Git as plain text — they would be exposed to anyone with repository access. mogenius uses [Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) to solve this: secrets are encrypted before being committed to Git, and only the Sealed Secrets controller running on your cluster can decrypt them.
### How secrets flow through GitOps
When you create a Secret through the mogenius UI with GitOps enabled:
1. **You create a Secret** using the [Secrets & Configs](/deploying-applications/deployment-configuration#secrets-and-configmaps) page in your workspace
2. **mogenius encrypts it** using the Sealed Secrets controller's public certificate
3. **A SealedSecret is committed** to your Git repository (encrypted, safe to store in Git)
4. **ArgoCD syncs** the SealedSecret to your cluster
5. **The controller decrypts it** and creates a regular Kubernetes Secret that your pods can use
This happens automatically — you work with secrets normally in the UI, and mogenius handles the sealing and Git commits.
### Creating secrets
To create a secret that will be managed through GitOps:
1. Navigate to your workspace and open the **Secrets & Configs** page
2. Click **Create Secret** and enter your key-value pairs
3. Save the secret — mogenius creates the Secret in your cluster
4. Add the secret to a GitOps application to include it in Git sync
Once the secret is part of a GitOps application, mogenius automatically seals it and commits the SealedSecret to your repository. The encrypted secret in Git is safe to store — only the Sealed Secrets controller on your cluster can decrypt it.
### Viewing secrets
**In the mogenius UI:**
The Secrets & Configs page shows all secrets in your workspace. You can view the keys (but not values) and see which deployments reference each secret.
**Using mocli:**
Use the [mogenius CLI](/cli/overview) to view secrets from your terminal:
```bash theme={null}
# List secrets in a namespace
mocli get secrets -n
# View a secret's data (base64 encoded)
mocli get secret -n -o yaml
```
You can also browse secrets interactively in the mocli TUI — launch `mocli`, navigate to your namespace, and type `:secrets` to switch to the secrets view.
**What's in Git:**
The SealedSecret in your repository contains encrypted data that is not human-readable. This is expected — it ensures secrets are safe even if your repository is compromised.
# GitOps with Flux
Source: https://docs.mogenius.com/cluster-management/gitops/flux
mogenius integrates with [Flux](https://fluxcd.io), the CNCF GitOps engine. When Flux is installed on a cluster, mogenius **detects it automatically** and gives you a single place to operate it: monitor all Flux resources and their sync health, reconcile, suspend and resume them, and **edit the source manifests directly in Git** — with AI assistance for diagnosing and fixing broken resources.
Unlike the [Argo CD path](/cluster-management/gitops/argocd), the Flux integration is **Git-first**: your desired state already lives in Git and is reconciled by Flux. mogenius does not generate manifests for you — it manages and edits the manifests you already have.
## Prerequisites and detection
Flux must already be running on the cluster. You can install it yourself (for example with the Flux CLI) or via the [flux-operator](/deploying-applications/blueprints) blueprint. Once Flux is present, mogenius detects it and shows the Flux integration on the cluster's **GitOps** page (**Clusters → \[Your Cluster] → GitOps**).
Monitoring and reconcile actions work immediately, with no additional setup. Editing manifests in Git is opt-in and requires [Git write access](#editing-manifests-in-git).
**Mogenius-managed Flux install (private beta).** A managed installation path — where mogenius installs and configures Flux and your Git repositories for you via the platform configuration (`PlatformConfig`) — is available in **private beta**. Contact mogenius to have it enabled for your account. Without it, use your own Flux installation as described above; all features on this page work the same either way.
## Managing Flux resources
The GitOps page lists all your Flux resources — Kustomizations, HelmReleases, Sources (GitRepository, OCIRepository, HelmRepository, Bucket), and, when present, Image Automation, ResourceSets, and Receivers. You can search and filter by ready state, see each resource's sync health and current revision, and spot resources that are failing or **behind** their source.
Opening a resource shows its status, source, dependencies, applied inventory, revision history, conditions, and events, so you can understand why a resource is out of sync without leaving mogenius.
For each resource you can trigger the standard Flux operations:
* **Reconcile** — request an immediate reconciliation.
* **Reconcile with source** — refresh the source first, then reconcile the workload.
* **Force** — force a reconciliation (HelmRelease only).
* **Suspend** / **Resume** — pause or resume reconciliation.
These actions require the appropriate permissions (see [Permissions](#permissions)).
## Editing manifests in Git
Because Flux reconciles from Git, mogenius lets you edit the **source manifest** that backs a resource and commit the change back to your repository — directly from the resource's manifest view. mogenius locates the file in the repo, so you don't have to. Editing is opt-in and disabled until Git write access is configured for the repository.
### Enable Git write access
On the cluster **GitOps** page, open **Git write access** and enable editing for a repository. Paste a **personal access token** with write permission (and a username if required). Supported providers are **GitHub**, **GitLab**, and **Gitea**.
mogenius validates the token against the provider before storing it. The token is stored as a Secret in the cluster's `mogenius` namespace — mogenius never stores your token itself. Removing the credential turns editing off again. Enabling write access requires the **cluster change** permission.
Set how changes reach the repository, per repository:
* **Pull Request** (default) — mogenius opens a branch and a pull request. Nothing is reconciled until the PR is merged. Use this when the tracked branch is protected.
* **Direct commit** — mogenius commits straight to the tracked branch. Commits to a protected branch are rejected.
If the write mode is declared in your platform configuration (`PlatformConfig`), that value takes precedence over the UI choice. mogenius never edits your `PlatformConfig` for you — a snippet is shown that you can commit to your own GitOps repository to declare the settings in Git.
### Edit and commit
Open a resource's manifest, switch to the **Git** view, edit the YAML (or use **Fix with AI**), add a commit message, and commit. In Pull Request mode a PR is opened and linked; in direct-commit mode you can optionally reconcile right after the commit. Concurrent edits are protected — a save that is based on a stale version is rejected rather than overwriting someone else's change.
### When editing is blocked
If a file can't be edited, mogenius explains why. Common reasons: no write credential, write disabled, an unsupported Git host, the file couldn't be located or matched unambiguously, a SOPS-encrypted manifest, or a Kustomization that renders overlays rather than mapping to a single file.
## AI-assisted fixes
Broken Flux resources can be fixed with AI. **Fix with AI** proposes a corrected manifest as a reviewable diff — nothing is committed without you. The **Flux Doctor** agent watches your Flux resources and explains failed reconciliations. Both require a chat-enabled AI model on the cluster; see [Agents](/ai/agents) for details and setup.
## Permissions
* Enabling Git write access and performing runtime actions require the **cluster change** permission.
* **Workspace-scoped users** can act on a Flux resource only if it is **assigned to their workspace** — otherwise it is read-only. This rule is enforced in the UI and on the server.
# GitOps
Source: https://docs.mogenius.com/cluster-management/gitops/overview
GitOps (short for Git Operations) describes a declarative way of managing applications in cloud-native environments using the Git workflow. Application configurations are stored and updated via Git repositories, and a GitOps engine running on the cluster tracks those repositories and keeps the cluster in sync with them.
mogenius comes with a native GitOps integration that lets you implement GitOps in your teams, or integrate the mogenius platform with your existing GitOps stack. You can deploy workloads and resources to Kubernetes through the UI with mogenius Workspaces (see [Deploying Applications](/deploying-applications/overview)) and add GitOps as a layer of stability and control.
**Here's how you can use that in your teams:**
* Deploy containers to Kubernetes using the mogenius UI, without requiring deep Kubernetes knowledge. Then, add them to GitOps for production-grade deployments.
* Configure your applications once and then deploy them to additional environments for a staged development workflow. See [Multi-Environment Deployments](/deploying-applications/multi-environment-deployments) for a practical guide.
* Back up all your manifests to recover your cluster state in case of an incident.
## Two GitOps engines
mogenius supports two GitOps engines. A cluster runs **one** engine, and mogenius detects which one is installed and shows it on the cluster's **GitOps** page.
UI-first. mogenius installs and manages Argo CD (plus Sealed Secrets), **generates** your Kubernetes manifests, and commits them to Git. You start in the mogenius UI.
Git-first, bring-your-own. Flux already runs on the cluster; mogenius **detects**, observes, and manages it, and lets you **edit the existing source manifests** from the UI. You start in Git.
The two engines follow different workflows:
* **Argo CD path** — UI-first. You deploy through the mogenius UI; mogenius generates manifests and commits them for you (Applications and ApplicationSets), and Argo CD syncs them to the cluster. mogenius installs and manages Argo CD and Sealed Secrets.
* **Flux path** — Git-first. Flux is already installed on the cluster (self-installed or via the flux-operator). mogenius detects it, shows the status and all Flux resources, lets you reconcile, suspend, and resume them, and lets you edit the source manifests in Git — with AI assistance.
## How to choose
* Choose **Argo CD** if you want mogenius to drive deployments from the UI and generate the manifests for you — ideal for teams that want GitOps without writing Kubernetes YAML by hand.
* Choose **Flux** if you already run Flux (or standardize on it) and want mogenius to observe, manage, and help you edit your existing Flux setup from a single UI.
Both engines give you the auditability and reliability of Git-based infrastructure management. Pick the one that matches how your team already works, then follow the matching guide:
* [GitOps with Argo CD](/cluster-management/gitops/argocd)
* [GitOps with Flux](/cluster-management/gitops/flux)
# Installing the mogenius operator
Source: https://docs.mogenius.com/cluster-management/installing-the-mogenius-operator
Connect your own Kubernetes cluster by installing the mogenius operator on the cluster.
mogenius allows you to connect with Kubernetes clusters by installing the mogenius operator on a cluster. Once installed, you can start creating workspaces and manage Kubernetes workloads through the mogenius platform. To begin the installation process, you'll first need to add a cluster in mogenius.
## Prerequisites
To successfully complete the next steps, you will need the following:
* 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](/cli/installation)
* Kubernetes cluster admin permissions
## Resource requirements
The mogenius operator is deployed to your Kubernetes cluster using Helm. 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.
## Set up your platform tool stack (optional)
During onboarding you can optionally set up a [Platform Config](/cluster-management/platform-config) — a declarative tool stack (GitOps, ingress, certificates, monitoring, secrets, and more) that the operator installs and keeps in sync for you:
1. Connect a Git repository for the Platform Config.
2. Configure the components you want. If the repository has no Platform Config yet, mogenius loads a default for you to adjust; if one already exists, it is loaded so you can edit it.
3. Save. mogenius commits the `platformconfig.yaml` to the repository (directly or as a pull request).
Once the operator is installed (next step), it installs the GitOps engine, which syncs the Platform Config to the cluster; the operator then reconciles it and creates the configured components.
This step is optional. You can also connect a cluster with just the operator and add a Platform Config later. See [Platform Config](/cluster-management/platform-config) for the full component catalog and how to manage it.
## 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 Helm, or the mogenius CLI.
### 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.
```jsx title="mogenius operator Helm install" theme={null}
helm repo add mogenius https://helm.mogenius.com/public
helm repo update mogenius
helm upgrade --install mogenius-operator mogenius/mogenius-operator -n mogenius --create-namespace --wait \
--set global.cluster_name="NAME" \
--set global.api_key="API_KEY"
```
### mogenius CLI
Install the mogenius CLI, on your terminal perform a `mocli login` and then run the following command.
```jsx" title="Installation via mogenius CLI" theme={null}
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.
## Metrics server
Once the operator is installed, it will check if a [metrics server](https://github.com/kubernetes-sigs/metrics-server) is present on the cluster. If not, it will be automatically installed.
**That's it - your cluster is connected and you can now create workspaces!**
## Troubleshooting
If you're encountering issues with installing the operator, check out common problems in the section [Troubleshooting clusters](./troubleshooting-clusters.md).
## Helm chart values
The Helm chart for the mogenius operator supports a range of values that you can optionally adjust during the installation. Add them to the [Helm install command](https://docs.mogenius.com/documentation/cluster-management/installing-mogenius#helm-install) with `--set` .
View the latest values on [Artifact Hub](https://artifacthub.io/packages/helm/mogenius/mogenius-k8s-manager#values).
# Kubernetes workloads
Source: https://docs.mogenius.com/cluster-management/kubernetes-workloads
Manage your Kubernetes cluster with workloads and logs. An alternative to k9s and Lens, right from your mogenius platform.
Once the mogenius operator is [installed](./installing-the-mogenius-operator) on Kubernetes you'll be able to access a workload manager through the platform. This allows you to view each Kubernetes resource, use the `Describe` command, edit YAML, view logs, and open a shell for containers that support this feature.
To access the workload manager, open a cluster in mogenius and navigate to the tab "Workloads".
# Managed clusters
Source: https://docs.mogenius.com/cluster-management/managed-clusters
Besides the options of connecting mogenius with your own Kubernetes clusters, we offer managed cluster for maximum simplicity and less overhead. These clusters are available on a range of cloud providers and they are fully managed up to the point that you can create projects and deploy services right away from mogenius.
Here's some use cases where a managed cluster might be a good idea:
* You don't have a cloud account yet and want a simple but scalable cloud environment
* For isolated projects, prototyping, or MVPs, where you need to move fast without deep infrastructure requirements
* For testing mogenius in your team before rolling it out on your own infrastructure
## Cloud providers
We currently offer shared or dedicated clusters on these cloud providers:
* [Google Cloud Platform](https://cloud.google.com/)
* [Microsoft Azure](https://azure.microsoft.com)
* [StackIT](https://stackit.de/)
* [Plusserver](http://plusserver.com/)
* [Hetzner](https://hetzner.com)
## Pricing
We're working with fixed resources that will be added to your monthly subscription. The price for CPU, RAM and storage depends on the cloud provider and individual requirements that you might have. Service level agreements, and support times will be offered according to your requirements.
[Contact us](mailto:sales@mogenius.com) if you're interested in learning more about managed clusters. We're happy to create a proposal for you.
# Platform Config
Source: https://docs.mogenius.com/cluster-management/platform-config
Define and manage a cluster's platform tool stack declaratively through GitOps.
The Platform Config is a declarative definition of your cluster's platform tool stack — the baseline components that every workload on the cluster relies on, such as GitOps, ingress, certificates, monitoring, and secrets. It lives in a Git repository as a single `PlatformConfig` resource, and mogenius keeps the cluster in sync with it through GitOps. Instead of installing and wiring these components by hand, you describe the tool stack you want and the operator reconciles the cluster to match.
## Components
The Platform Config bundles the platform components you can enable and configure:
* **GitOps engine** — keeps the cluster in sync with Git. Choose **Argo CD** (`gitOps.argocd`) or **Flux** (`gitOps.fluxcd`) — a cluster runs one engine — and configure the `repositories` it watches. See [GitOps](/cluster-management/gitops/overview) for how the two engines differ.
* **kube-prometheus-stack** — metrics and dashboards with Prometheus, Grafana, and Alertmanager. Adjust individual charts through patches.
* **Alloy** — collects logs and metrics from the cluster.
* **Loki** — persistent log storage. Optional, disabled by default; enable it when you want logs retained on the cluster.
* **Renovate operator** — automated dependency updates for your platform components.
* **Traefik** — the ingress controller. Set service annotations, for example load-balancer provider annotations.
* **external-dns** — automated DNS record management. Choose the provider (for example Cloudflare), reference the API-token secret, and set the domains it manages via `domainFilters`.
* **cert-manager** — TLS certificates via Let's Encrypt. Define your `clusterIssuers` and `issuers`.
* **external-secrets** — pulls secrets from an external vault. Configure the `vaults` to connect (for example 1Password).
## Managing the Platform Config
You edit the Platform Config in the mogenius UI under **Cluster → Settings → Platform config**. Every change you save is written back to the Git repository, and the GitOps engine applies it to the cluster — so Git always reflects the current state of your platform.
## Example
A `PlatformConfig` is a Kubernetes resource. Here is a shortened example with a few components enabled:
```yaml theme={null}
apiVersion: mogenius.com/v1alpha1
kind: PlatformConfig
metadata:
name: platform
spec:
platformVersion: main
gitOps:
argocd: # or: fluxcd (a cluster runs one engine)
enabled: true
repositories: []
kubePrometheusStack:
enabled: true
patches:
- name: grafana
traefik:
enabled: true
certManager:
enabled: true
clusterIssuers:
- name: letsencrypt-prod
email: ops@example.com
solvers:
- http01:
ingress:
class: traefik
```
## Platform Config vs. Blueprints
Platform Config and [Blueprints](/deploying-applications/blueprints) serve two distinct roles:
* **Platform Config** manages the **platform** — the shared tool stack of a cluster. This is the admin's job.
* **Blueprints** create **applications** on top of that platform. This is what the user does.
# Self hosted
Source: https://docs.mogenius.com/cluster-management/self-hosted
The mogenius platform is available as a SaaS option on [app.mogenius.com](https://app.mogenius.com). If you prefer the self-hosted version of mogenius, you can install it with our Helm chart. This way you can run mogenius on your own clusters and even in air-gapped environments.
## Prerequisites
* A Kubernetes cluster with at least 1 CPU and 1 GB of memory available.
* Credentials for pulling the mogenius images from the container registry (see below).
* The traefik ingress controller.
* A working local installation of [Helm](https://helm.sh/).
* A MySQL server (optional).
Running the platform as a self-hosted version requires a subscription. Contact our sales team for more information.
## Quickstart
For a quick installation of the mogenius platform with defaults where possible, follow these steps.
### Create a Namespace
On the cluster where you're installing the mogenius platform, create a new namespace `mogenius-platform`. All following commands target this namespace.
```bash theme={null}
kubectl create namespace mogenius-platform
```
### Create Secrets
The platform services require a few secrets containing critical credentials that aren't created by the Helm chart. The following secrets are required for the minimum configuration. Additional secrets can be used when working with more sophisticated Helm chart configurations.
The commands below create each secret directly with `kubectl`. They generate secure random values on the fly using `openssl`, so you can run them as-is and only replace the placeholders that are marked with `<...>`.
The encryption key `MO_CORE_NEST__SSH_SYM_ENC_KEY` must be **identical** in the `mo-platform-shared` and `mo-platform-user-secret` secrets. The commands below generate it once into a shell variable and reuse it, so run them in the same terminal session.
**1. Container Registry**
After obtaining a subscription for the self-hosted version, you will have received credentials for the container registry where the platform images are stored. Store them as a `mo-registry-credentials` secret of type `kubernetes.io/dockerconfigjson`. Replace the placeholders with the values from your subscription.
```bash theme={null}
kubectl create secret docker-registry mo-registry-credentials \
--namespace mogenius-platform \
--docker-server= \
--docker-username= \
--docker-password=
```
**2. Valkey (Redis-compatible)**
Holds the password shared by all Valkey instances. The command generates a secure random value.
```bash theme={null}
kubectl create secret generic mo-redis-secret \
--namespace mogenius-platform \
--from-literal=REDIS_SECRET="$(openssl rand -base64 32)"
```
**3. Encryption Key**
Generate the symmetric encryption key once and keep it in a shell variable so it can be reused for the admin user secret in step 5.
```bash theme={null}
export MO_ENC_KEY="$(openssl rand -base64 32)"
kubectl create secret generic mo-platform-shared \
--namespace mogenius-platform \
--from-literal=MO_CORE_NEST__SSH_SYM_ENC_KEY="$MO_ENC_KEY"
```
**4. MySQL**
Holds the application and root passwords for the MySQL database. The command generates secure random values.
Avoid single quotes (`'`) and backslashes (`\`) in MySQL passwords — they break the MySQL container's init and cause *Access denied*. Use **alphanumeric passwords** (`A–Z`, `a–z`, `0–9`). The command below already generates compliant values.
```bash theme={null}
kubectl create secret generic mo-mysql-secret \
--namespace mogenius-platform \
--from-literal=MYSQL_PASSWORD="$(LC_ALL=C tr -dc 'A-Za-z0-9' " \
--from-literal=MO_USER_NEST__SYSTEM_ADMIN_PASSWORD="" \
--from-literal=MO_CORE_NEST__SSH_SYM_ENC_KEY="$MO_ENC_KEY" \
--from-literal=MO_USER_NEST__JWT_PRIVATE="$(openssl base64 -A -in ec512-key-pair.pem)" \
--from-literal=MO_USER_NEST__JWT_PUBLIC="$(openssl base64 -A -in public.pem)" \
--from-literal=MO_USER_NEST__SESSION_SECRET="$(openssl rand -base64 32)"
```
The keys stored in this secret are:
`MO_USER_NEST__SYSTEM_ADMIN_EMAIL` — the email address to log in with your admin user.
`MO_USER_NEST__SYSTEM_ADMIN_PASSWORD` — the password for your admin user.
`MO_CORE_NEST__SSH_SYM_ENC_KEY` — the same encryption key set in the `mo-platform-shared` secret.
`MO_USER_NEST__JWT_PRIVATE` — the base64-encoded private key for signing JWTs.
`MO_USER_NEST__JWT_PUBLIC` — the base64-encoded public key for verifying JWTs.
`MO_USER_NEST__SESSION_SECRET` — a secure random secret for session handling.
### Prepare your values.yaml
The Helm chart supports wide range of values that you can use to configure your installation of the mogenius platform. Skip to [values](/cluster-management/self-hosted#values) for a full reference of the chart.
Below is an example `values.yaml` for a minimal setup to install the mogenius platform in a development environment. Make sure to review the configuration and ensure that it matches your infrastructure.
```yaml values.yaml quickstart example theme={null}
ingress:
annotations:
cert-manager.io/cluster-issuer: letsencrypt-cluster-issuer
traefik.ingress.kubernetes.io/forward-headers: "true"
traefik.ingress.kubernetes.io/router.middlewares: mogenius-platform-cors-middleware@kubernetescrd
traefik.ingress.kubernetes.io/secure-headers: "true"
api_service_url: platform-api.YOURDOMAIN.com
hostname: mogenius.YOURDOMAIN.com
k8s_cmd_stream_url: k8s-cmd-stream.YOURDOMAIN.com
k8s_dispatcher_url: k8s-dispatcher.YOURDOMAIN.com
k8s_logs_url: k8s-logs.YOURDOMAIN.com
k8s_websocket_url: k8s-ws.YOURDOMAIN.com
rootDomain: YOURDOMAIN.com
socket_service_url: platform-ws.YOURDOMAIN.com
tls:
- hosts:
- mogenius.YOURDOMAIN.com
- platform-api.YOURDOMAIN.com
- platform-user.YOURDOMAIN.com
- platform-ws.YOURDOMAIN.com
- k8s-ws.YOURDOMAIN.com
- k8s-logs.YOURDOMAIN.com
- k8s-cmd-stream.YOURDOMAIN.com
- k8s-dispatcher.YOURDOMAIN.com
secretName: mo-platform-tls
traefik:
apiVersion: traefik.io/v1alpha1
user_service_url: platform-user.YOURDOMAIN.com
mo_platform:
metrics:
enabled: true
resources:
requests:
cpu: 10m
memory: 50Mi
mo_platform_api:
enableAutoRefreshToken: true
refreshTokenTask: true
mo_platform_user:
openid:
enabled: false
mogenius:
imagePullSecrets:
- mo-registry-credentials
mysql:
enabled: true
ssl: false
storage:
accessMode: ReadWriteOnce
className: local-path
```
This chart configuration deploys the MySQL Docker image as part of the platform deployment. This setup is not recommended for running the mogenius platform in production scenarios. We recommend configuring the `mysql` values with connection to a high-availability MySQL for use in a production environment.
### Deploy the Helm chart
Run the following command on your cluster to install the Helm chart with your values.yaml.
```bash theme={null}
helm repo add mogenius https://helm.mogenius.com/private
helm install mogenius-platform mogenius/mo-infrastructure -n mogenius-platform -f values.yaml
```
### Access the mogenius web interface
Check the status of the installation and make sure all Pods are starting properly.
```bash theme={null}
kubectl get pods -n mogenius-platform
```
When all Pods are `Running`, access the mogenius platform with the hostname you specified in your Ingress (e.g. mogenius.yourdomain.com). You can log in with the credentials of your admin user.
### Next steps
Now that mogenius is up and running you can prepare the platform for your team. Check out the following resources as next steps:
* [Quickstart guide](../overview/quickstart) for connecting your first cluster and getting started with Workspaces.
* [Enable Single Sign-On](./single-sign-on) to enable your team joining the mogenius platform.
* [Configure GitOps](/cluster-management/gitops/argocd) for enabling Git-based workflows in mogenius using Argo CD.
### Support
Need help setting up the mogenius platform? Contact us via [support@mogenius.com](mailto:support@mogenius.com).
## Values
### Global Settings
| Key | Type | Default | Description |
| - | - | - | - |
| stage | string | `"production"` | Current environment, one of \[dev, production] |
| revisionHistoryLimit | int | `1` | Global revisionHistoryLimit for all resources |
| progressDeadlineSeconds | int | `600` | Deployment progress deadline |
| secrets | object | `{}` | secrets.``.``.`` |
| dockersecrets | object | `{}` | Docker registry secrets |
| mogenius.imagePullSecrets | list | `[]` | List of image pull secrets for mogenius images |
| global.imagePullSecrets | list | `[]` | List of image pull secrets for all images |
| global.serviceMonitor.fallbackScrapeProtocol | string | `"PrometheusText0.0.4"` | Fallback scrape protocol for service monitors |
| global.podLabels | object | `{}` | Global pod labels applied to all pods |
### Ingress
| Key | Type | Default | Description |
| - | - | - | - |
| ingress.rootDomain | string | `nil` | Root domain that the platform will be hosted on, e.g. example.com |
| ingress.ingressClassName | string | `"traefik"` | Ingress class name |
| ingress.annotations | object | See below | Annotations to be placed on the ingress |
| ingress.tls | list | `[]` | Secret reference for TLS |
| ingress.hostname | string | `nil` | Platform hostname e.g. app.example.com |
| ingress.api\_service\_url | string | `nil` | API hostname e.g. api-app.example.com |
| ingress.user\_service\_url | string | `nil` | User service hostname e.g. user-app.example.com |
| ingress.socket\_service\_url | string | `nil` | WebSocket hostname e.g. ws-app.example.com |
| ingress.k8s\_websocket\_url | string | `nil` | Kubernetes WebSocket hostname e.g. k8s-ws.example.com |
| ingress.k8s\_logs\_url | string | `nil` | Kubernetes log hostname e.g. k8s-logs.example.com |
| ingress.k8s\_cmd\_stream\_url | string | `nil` | Kubernetes cmd stream hostname e.g. k8s-cmd-stream.example.com |
| ingress.k8s\_dispatcher\_url | string | `nil` | Kubernetes dispatcher hostname e.g. k8s-dispatcher.example.com |
| ingress.traefik.apiVersion | string | `"traefik.containo.us/v1alpha1"` | The apiVersion that shall be used for traefik resources |
Default ingress annotations:
```yaml theme={null}
traefik.ingress.kubernetes.io/router.middlewares: mogenius-cors-middleware@kubernetescrd
traefik.ingress.kubernetes.io/forward-headers: "true"
traefik.ingress.kubernetes.io/secure-headers: "true"
```
### Feature Toggles
| Key | Type | Default | Description |
| - | - | - | - |
| features.sso.enabled | bool | `true` | Enable SSO feature with ingress for SSO wildcard domain |
| features.sso.ingress.tls | list | `[]` | TLS configuration for SSO ingress |
| features.sso.ingress.annotations | object | `{}` | Annotations for SSO ingress |
| features.portForwarding.enabled | bool | `true` | Enable port forwarding feature |
| features.portForwarding.hostname | string | `"tunnel.mogenius.com"` | Hostname for port forwarding |
| features.portForwarding.ingress.tls | list | `[]` | TLS configuration for port forwarding ingress |
| features.portForwarding.ingress.annotations | object | `{}` | Annotations for port forwarding ingress |
### Platform Services
#### mo\_platform (Frontend)
| Key | Type | Default | Description |
| - | - | - | - |
| mo\_platform.enabled | bool | `true` | Enable frontend service |
| mo\_platform.replicas | int | `1` | Number of replicas |
| mo\_platform.image.registry | string | `"ghcr.io"` | Image registry |
| mo\_platform.image.repository | string | `"mogenius/mo-frontend"` | Image repository |
| mo\_platform.image.tag | string | `"v2.8.3"` | Image tag |
| mo\_platform.imagePullPolicy | string | `"IfNotPresent"` | Image pull policy |
| mo\_platform.port | int | `8080` | Service port |
| mo\_platform.resources | object | `{}` | Resource requests/limits |
| mo\_platform.tolerations | object | `{}` | Pod tolerations |
| mo\_platform.metrics.enabled | bool | `false` | Enable Prometheus metrics exporter for nginx |
| mo\_platform.metrics.port | int | `9113` | Metrics port |
| mo\_platform.metrics.serviceMonitor.enabled | bool | `false` | Enable ServiceMonitor |
#### mo\_platform\_api (API Service)
| Key | Type | Default | Description |
| - | - | - | - |
| mo\_platform\_api.enabled | bool | `true` | Enable API service |
| mo\_platform\_api.replicas | int | `1` | Number of replicas |
| mo\_platform\_api.image.registry | string | `"ghcr.io"` | Image registry |
| mo\_platform\_api.image.repository | string | `"mogenius/mo-platform-api-service"` | Image repository |
| mo\_platform\_api.image.tag | string | `"v4.4.6"` | Image tag |
| mo\_platform\_api.imagePullPolicy | string | `"IfNotPresent"` | Image pull policy |
| mo\_platform\_api.port | int | `1337` | HTTP port |
| mo\_platform\_api.port\_tcp | int | `7000` | TCP port |
| mo\_platform\_api.ws\_port | int | `7001` | WebSocket port |
| mo\_platform\_api.ws\_log\_port | int | `7002` | WebSocket log port |
| mo\_platform\_api.ws\_cmd\_stream\_port | int | `7003` | WebSocket cmd stream port |
| mo\_platform\_api.refreshTokenTask | bool | `false` | If set to true will refresh the tokens in the database |
| mo\_platform\_api.enableAutoRefreshToken | bool | `false` | Enable automatic token refresh |
| mo\_platform\_api.resources | object | `{}` | Resource requests/limits |
| mo\_platform\_api.tolerations | object | `{}` | Pod tolerations |
| mo\_platform\_api.probes.enabled | bool | `true` | Enable health probes |
| mo\_platform\_api.probes.port | int | `1337` | Probe port |
| mo\_platform\_api.probes.livenessProbe.path | string | `"/core/status"` | Liveness probe path |
| mo\_platform\_api.probes.readinessProbe.path | string | `"/core/status"` | Readiness probe path |
| mo\_platform\_api.probes.startupProbe.path | string | `"/core/status"` | Startup probe path |
| mo\_platform\_api.sshSymEncKey.secretName | string | `"mo-platform-shared"` | Secret name for SSH symmetric encryption key |
| mo\_platform\_api.sshSymEncKey.secretKey | string | `"MO_CORE_NEST__SSH_SYM_ENC_KEY"` | Secret key for SSH symmetric encryption key |
| mo\_platform\_api.initContainer.image.registry | string | `"docker.io"` | Init container image registry |
| mo\_platform\_api.initContainer.image.repository | string | `"alpine/curl"` | Init container image repository |
| mo\_platform\_api.initContainer.image.tag | string | `"8.20.0"` | Init container image tag |
#### mo\_platform\_user (User Service)
| Key | Type | Default | Description |
| - | - | - | - |
| mo\_platform\_user.enabled | bool | `true` | Enable user service |
| mo\_platform\_user.replicas | int | `1` | Number of replicas |
| mo\_platform\_user.image.registry | string | `"ghcr.io"` | Image registry |
| mo\_platform\_user.image.repository | string | `"mogenius/mo-platform-user"` | Image repository |
| mo\_platform\_user.image.tag | string | `"v2.0.17"` | Image tag |
| mo\_platform\_user.imagePullPolicy | string | `"IfNotPresent"` | Image pull policy |
| mo\_platform\_user.port | int | `1337` | HTTP port |
| mo\_platform\_user.port\_ws | int | `7000` | WebSocket port |
| mo\_platform\_user.resources | object | `{}` | Resource requests/limits |
| mo\_platform\_user.tolerations | object | `{}` | Pod tolerations |
| mo\_platform\_user.probes.enabled | bool | `true` | Enable health probes |
| mo\_platform\_user.sshSymEncKey.secretName | string | `"mo-platform-shared"` | Secret name for SSH symmetric encryption key |
| mo\_platform\_user.sshSymEncKey.secretKey | string | `"MO_CORE_NEST__SSH_SYM_ENC_KEY"` | Secret key for SSH symmetric encryption key |
**OpenID Configuration:**
| Key | Type | Default | Description |
| - | - | - | - |
| mo\_platform\_user.openid.enabled | bool | `true` | Enable OpenID |
| mo\_platform\_user.openid.issuer | string | `"https://login-dev.mogenius.com"` | OpenID issuer URL |
| mo\_platform\_user.openid.accessTokenLifetime | string | `"600"` | Access token lifetime in seconds |
| mo\_platform\_user.openid.refreshTokenLifetime | string | `"7776000"` | Refresh token lifetime in seconds |
| mo\_platform\_user.openid.adminAccessTokenLifetime | string | `"28800"` | Admin access token lifetime in seconds |
| mo\_platform\_user.openid.provider.github.enabled | bool | `false` | Enable GitHub OAuth |
| mo\_platform\_user.openid.provider.gitlab.enabled | bool | `false` | Enable GitLab OAuth |
| mo\_platform\_user.openid.provider.google.enabled | bool | `false` | Enable Google OAuth |
| mo\_platform\_user.openid.provider.linkedin.enabled | bool | `false` | Enable LinkedIn OAuth |
| mo\_platform\_user.openid.provider.microsoft.enabled | bool | `false` | Enable Microsoft OAuth |
#### mo\_platform\_websocket (WebSocket Service)
| Key | Type | Default | Description |
| - | - | - | - |
| mo\_platform\_websocket.enabled | bool | `true` | Enable WebSocket service |
| mo\_platform\_websocket.replicas | int | `1` | Number of replicas |
| mo\_platform\_websocket.image.registry | string | `"ghcr.io"` | Image registry |
| mo\_platform\_websocket.image.repository | string | `"mogenius/mo-platform-websocket"` | Image repository |
| mo\_platform\_websocket.image.tag | string | `"v2.0.7"` | Image tag |
| mo\_platform\_websocket.imagePullPolicy | string | `"IfNotPresent"` | Image pull policy |
| mo\_platform\_websocket.port | int | `1337` | HTTP port |
| mo\_platform\_websocket.port\_ws | int | `7000` | WebSocket port |
| mo\_platform\_websocket.resources | object | `{}` | Resource requests/limits |
| mo\_platform\_websocket.tolerations | object | `{}` | Pod tolerations |
| mo\_platform\_websocket.sshSymEncKey.secretName | string | `"mo-platform-shared"` | Secret name for SSH symmetric encryption key |
| mo\_platform\_websocket.sshSymEncKey.secretKey | string | `"MO_CORE_NEST__SSH_SYM_ENC_KEY"` | Secret key for SSH symmetric encryption key |
#### mo\_platform\_notification (Notification Service)
| Key | Type | Default | Description |
| - | - | - | - |
| mo\_platform\_notification.enabled | bool | `true` | Enable notification service |
| mo\_platform\_notification.replicas | int | `1` | Number of replicas |
| mo\_platform\_notification.image.registry | string | `"ghcr.io"` | Image registry |
| mo\_platform\_notification.image.repository | string | `"mogenius/mo-platform-notification"` | Image repository |
| mo\_platform\_notification.image.tag | string | `"v2.0.7"` | Image tag |
| mo\_platform\_notification.imagePullPolicy | string | `"IfNotPresent"` | Image pull policy |
| mo\_platform\_notification.port | int | `7000` | Service port |
| mo\_platform\_notification.email.fromName | string | `"Mogenius Team"` | Email sender name |
| mo\_platform\_notification.email.fromAddress | string | `"no-reply@mogenius.com"` | Email sender address |
| mo\_platform\_notification.resources | object | `{}` | Resource requests/limits |
| mo\_platform\_notification.tolerations | object | `{}` | Pod tolerations |
| mo\_platform\_notification.sshSymEncKey.secretName | string | `"mo-platform-shared"` | Secret name for SSH symmetric encryption key |
| mo\_platform\_notification.sshSymEncKey.secretKey | string | `"MO_CORE_NEST__SSH_SYM_ENC_KEY"` | Secret key for SSH symmetric encryption key |
#### mo\_platform\_queue (Queue Service)
| Key | Type | Default | Description |
| - | - | - | - |
| mo\_platform\_queue.enabled | bool | `true` | Enable queue service |
| mo\_platform\_queue.replicas | int | `1` | Number of replicas |
| mo\_platform\_queue.image.registry | string | `"ghcr.io"` | Image registry |
| mo\_platform\_queue.image.repository | string | `"mogenius/mo-platform-queue"` | Image repository |
| mo\_platform\_queue.image.tag | string | `"v3.0.4"` | Image tag |
| mo\_platform\_queue.imagePullPolicy | string | `"IfNotPresent"` | Image pull policy |
| mo\_platform\_queue.resources | object | `{}` | Resource requests/limits |
| mo\_platform\_queue.tolerations | object | `{}` | Pod tolerations |
| mo\_platform\_queue.sshSymEncKey.secretName | string | `"mo-platform-shared"` | Secret name for SSH symmetric encryption key |
| mo\_platform\_queue.sshSymEncKey.secretKey | string | `"MO_CORE_NEST__SSH_SYM_ENC_KEY"` | Secret key for SSH symmetric encryption key |
#### mo\_platform\_message\_dispatcher (Message Dispatcher)
| Key | Type | Default | Description |
| - | - | - | - |
| mo\_platform\_message\_dispatcher.enabled | bool | `true` | Enable message dispatcher |
| mo\_platform\_message\_dispatcher.replicas | int | `1` | Number of replicas |
| mo\_platform\_message\_dispatcher.image.registry | string | `"ghcr.io"` | Image registry |
| mo\_platform\_message\_dispatcher.image.repository | string | `"mogenius/mo-platform-message-dispatcher"` | Image repository |
| mo\_platform\_message\_dispatcher.image.tag | string | `"v1.1.4"` | Image tag |
| mo\_platform\_message\_dispatcher.imagePullPolicy | string | `"IfNotPresent"` | Image pull policy |
| mo\_platform\_message\_dispatcher.listen\_host | string | `"0.0.0.0"` | Listen host |
| mo\_platform\_message\_dispatcher.port | int | `7060` | Service port |
| mo\_platform\_message\_dispatcher.resources | object | `{}` | Resource requests/limits |
| mo\_platform\_message\_dispatcher.tolerations | object | `{}` | Pod tolerations |
### Valkey (Redis-compatible Cache)
The platform uses [Valkey](https://valkey.io/), an open-source Redis-compatible in-memory data store, for caching and message queuing. The chart deploys multiple Valkey instances for different purposes.
#### mo\_platform\_api\_valkey
| Key | Type | Default | Description |
| - | - | - | - |
| mo\_platform\_api\_valkey.enabled | bool | `true` | Enable Valkey for API service |
| mo\_platform\_api\_valkey.image.registry | string | `"docker.io"` | Image registry |
| mo\_platform\_api\_valkey.image.repository | string | `"valkey/valkey"` | Image repository |
| mo\_platform\_api\_valkey.image.tag | string | `"9.1.0"` | Image tag |
| mo\_platform\_api\_valkey.imagePullPolicy | string | `"IfNotPresent"` | Image pull policy |
| mo\_platform\_api\_valkey.port | int | `6379` | Service port |
| mo\_platform\_api\_valkey.host | string | `"mo-platform-api-valkey"` | Service hostname |
| mo\_platform\_api\_valkey.password.secretName | string | `"mo-redis-secret"` | Secret name for password |
| mo\_platform\_api\_valkey.password.secretKey | string | `"REDIS_SECRET"` | Secret key for password |
| mo\_platform\_api\_valkey.resources | object | `{}` | Resource requests/limits |
| mo\_platform\_api\_valkey.metrics.enabled | bool | `false` | Enable Prometheus metrics exporter |
| mo\_platform\_api\_valkey.metrics.port | int | `9121` | Metrics port |
| mo\_platform\_api\_valkey.metrics.serviceMonitor.enabled | bool | `false` | Enable ServiceMonitor |
#### mo\_valkey\_shared
Shared Valkey instance used for queue processing and cross-service communication.
| Key | Type | Default | Description |
| - | - | - | - |
| mo\_valkey\_shared.enabled | bool | `true` | Enable shared Valkey |
| mo\_valkey\_shared.tls | bool | `false` | Enable TLS |
| mo\_valkey\_shared.queue\_db | int | `7` | Database number for queue |
| mo\_valkey\_shared.image.registry | string | `"docker.io"` | Image registry |
| mo\_valkey\_shared.image.repository | string | `"valkey/valkey"` | Image repository |
| mo\_valkey\_shared.image.tag | string | `"9.1.0"` | Image tag |
| mo\_valkey\_shared.imagePullPolicy | string | `"IfNotPresent"` | Image pull policy |
| mo\_valkey\_shared.port | int | `6379` | Service port |
| mo\_valkey\_shared.host | string | `"mo-valkey-shared"` | Service hostname |
| mo\_valkey\_shared.password.secretName | string | `"mo-redis-secret"` | Secret name for password |
| mo\_valkey\_shared.password.secretKey | string | `"REDIS_SECRET"` | Secret key for password |
| mo\_valkey\_shared.resources | object | `{}` | Resource requests/limits |
| mo\_valkey\_shared.strategy | string | `"RollingUpdate"` | Update strategy |
| mo\_valkey\_shared.metrics.enabled | bool | `false` | Enable Prometheus metrics exporter |
| mo\_valkey\_shared.metrics.serviceMonitor.enabled | bool | `false` | Enable ServiceMonitor |
#### mo\_websocket\_valkey
| Key | Type | Default | Description |
| - | - | - | - |
| mo\_websocket\_valkey.enabled | bool | `true` | Enable Valkey for WebSocket service |
| mo\_websocket\_valkey.image.registry | string | `"docker.io"` | Image registry |
| mo\_websocket\_valkey.image.repository | string | `"valkey/valkey"` | Image repository |
| mo\_websocket\_valkey.image.tag | string | `"9.1.0"` | Image tag |
| mo\_websocket\_valkey.port | int | `6379` | Service port |
| mo\_websocket\_valkey.host | string | `"mo-websocket-valkey"` | Service hostname |
| mo\_websocket\_valkey.password.secretName | string | `"mo-redis-secret"` | Secret name for password |
| mo\_websocket\_valkey.password.secretKey | string | `"REDIS_SECRET"` | Secret key for password |
| mo\_websocket\_valkey.resources | object | `{}` | Resource requests/limits |
| mo\_websocket\_valkey.metrics.enabled | bool | `false` | Enable Prometheus metrics exporter |
#### mo\_user\_valkey
| Key | Type | Default | Description |
| - | - | - | - |
| mo\_user\_valkey.enabled | bool | `true` | Enable Valkey for user service |
| mo\_user\_valkey.image.registry | string | `"docker.io"` | Image registry |
| mo\_user\_valkey.image.repository | string | `"valkey/valkey"` | Image repository |
| mo\_user\_valkey.image.tag | string | `"9.1.0"` | Image tag |
| mo\_user\_valkey.port | int | `6379` | Service port |
| mo\_user\_valkey.host | string | `"mo-user-valkey"` | Service hostname |
| mo\_user\_valkey.password.secretName | string | `"mo-redis-secret"` | Secret name for password |
| mo\_user\_valkey.password.secretKey | string | `"REDIS_SECRET"` | Secret key for password |
| mo\_user\_valkey.resources | object | `{}` | Resource requests/limits |
| mo\_user\_valkey.metrics.enabled | bool | `false` | Enable Prometheus metrics exporter |
#### mo\_message\_dispatcher\_valkey
| Key | Type | Default | Description |
| - | - | - | - |
| mo\_message\_dispatcher\_valkey.enabled | bool | `true` | Enable Valkey for message dispatcher |
| mo\_message\_dispatcher\_valkey.image.registry | string | `"docker.io"` | Image registry |
| mo\_message\_dispatcher\_valkey.image.repository | string | `"valkey/valkey"` | Image repository |
| mo\_message\_dispatcher\_valkey.image.tag | string | `"9.1.0"` | Image tag |
| mo\_message\_dispatcher\_valkey.port | int | `6379` | Service port |
| mo\_message\_dispatcher\_valkey.host | string | `"mo-message-dispatcher-valkey"` | Service hostname |
| mo\_message\_dispatcher\_valkey.tls | bool | `false` | Enable TLS |
| mo\_message\_dispatcher\_valkey.password.secretName | string | `"mo-redis-secret"` | Secret name for password |
| mo\_message\_dispatcher\_valkey.password.secretKey | string | `"REDIS_SECRET"` | Secret key for password |
| mo\_message\_dispatcher\_valkey.resources | object | `{}` | Resource requests/limits |
| mo\_message\_dispatcher\_valkey.metrics.enabled | bool | `false` | Enable Prometheus metrics exporter |
### MySQL
| Key | Type | Default | Description |
| - | - | - | - |
| mysql.enabled | bool | `false` | Enable MySQL deployment (use external MySQL for production) |
| mysql.replicas | int | `1` | Number of replicas |
| mysql.image.registry | string | `"docker.io"` | Image registry |
| mysql.image.repository | string | `"mysql"` | Image repository |
| mysql.image.tag | string | `"8.4.10"` | Image tag |
| mysql.imagePullPolicy | string | `"IfNotPresent"` | Image pull policy |
| mysql.port | int | `3306` | Service port |
| mysql.host | string | `"mysql"` | Service hostname |
| mysql.database | string | `"platform"` | Database name |
| mysql.user | string | `"platform_user"` | Database user |
| mysql.password.secretName | string | `"mo-mysql-secret"` | Secret name for password |
| mysql.password.secretKey | string | `"MYSQL_PASSWORD"` | Secret key for password |
| mysql.root\_password.secretName | string | `"mo-mysql-secret"` | Secret name for root password |
| mysql.root\_password.secretKey | string | `"MYSQL_ROOT_PASSWORD"` | Secret key for root password |
| mysql.ssl | bool | `false` | Enable SSL |
| mysql.sslRejectUnauthorized | bool | `true` | Reject unauthorized SSL connections |
| mysql.allow\_empty\_root\_password | int | `0` | Allow empty root password (0 = no) |
| mysql.subpath | string | `"{{ tpl .Release.Namespace }}-mysql-storage"` | Storage subpath |
| mysql.mountpoint | string | `"/var/lib/mysql"` | Data mount point |
| mysql.storage.capacity | string | `"50Gi"` | Storage capacity |
| mysql.resources | object | `{}` | Resource requests/limits |
| mysql.tolerations | object | `{}` | Pod tolerations |
### Storage
| Key | Type | Default | Description |
| - | - | - | - |
| storage.className | string | `"default"` | Storage class name |
| storage.accessMode | string | `"ReadWriteMany"` | Access mode |
# Single Sign-On
Source: https://docs.mogenius.com/cluster-management/single-sign-on
Configure SSO for your mogenius organization using Microsoft Entra, GitHub, or any OpenID Connect provider — including group-based workspace access.
# Single Sign-On
mogenius supports Single Sign-On (SSO) through OpenID Connect (OIDC), allowing team members to authenticate using their existing identity provider accounts. Once configured, your organization receives a unique login page that you share with your team.
## Supported Providers
* **Microsoft Entra ID** (formerly Azure Active Directory)
* **GitHub**
* **OpenID Connect** — any standards-compliant OIDC provider (GitLab, Okta, Keycloak, Auth0, and others)
## How the connection works
You configure SSO under **Organization settings → Single sign-on**. When you select a provider, the form shows a **Redirect URI** for your organization — copy it and register it in your identity-provider app. The provider validates this value exactly, so it must match including the trailing slash:
```
https:///source/oauth/callback/org-/
```
After you enter the provider credentials and click **Connect**, mogenius displays a **Login URL** for your organization. Share this URL with your team — users who sign in via this link are added to your organization automatically.
## Microsoft Entra ID
All steps happen in the **Microsoft Entra admin center** of your own tenant. First decide how mogenius should learn about your users' groups — the steps differ:
| Mode | What mogenius gets | Requires |
| - | - | - |
| **Microsoft Graph** (default) | Group **names** and Entra app roles → organization roles and workspace access | Delegated `GroupMember.Read.All` with **admin consent** |
| **Token claims** | Group **object IDs** from the sign-in token → workspace access via GroupGrant rules | Only the groups claim on the app registration — **no Graph permission, no admin consent** |
### Step 1: Register the application (both modes)
1. **App registrations → New registration.** Any name; supported account types: *Accounts in this organizational directory only*.
2. **Authentication → Add a platform → Web.** Set the Redirect URI to the value shown in the mogenius SSO form. The trailing slash is required.
3. **Certificates & secrets → New client secret.** Copy the secret **Value** immediately — it is shown only once.
4. **Overview.** Note the *Application (client) ID* and the *Directory (tenant) ID*.
### Step 2a: Group memberships via Microsoft Graph
1. **API permissions → Add a permission → Microsoft Graph → Delegated →** `GroupMember.Read.All`.
2. **Grant admin consent for ``.** The row must show *Granted*. Adding the permission alone is not enough — users would see "Approval required" at sign-in.
3. **App roles → Create app role.** Allowed member types *Users/Groups*; values `admin`, `editor`, `viewer` (further values are passed on as workspace roles).
4. **Enterprise applications → `` → Users and groups → Add user/group.** Assign each group an app role. Only assigned groups are synced.
5. Organization roles: groups named `mogenius-admin`, `mogenius-editor`, or `mogenius-viewer` set the organization role; their app role is ignored.
Assigning groups to enterprise applications requires Entra ID P1. The app reads its own role assignments by itself, so no application permission is needed.
### Step 2b: Group memberships via token claims
1. **Token configuration → Add groups claim.** Select **Security groups**; keep **Group ID** for the ID token. (Manifest equivalent: `"groupMembershipClaims": "SecurityGroup"`.)
2. **Token configuration → Add optional claim → ID:** `email`, `given_name`, `family_name` (recommended for complete profiles).
3. **API permissions:** the default `User.Read` is enough — no admin consent.
4. **Groups → `` → Overview → Object ID.** Note the object ID of every group that should grant workspace access.
5. In the cluster, create a GroupGrant per group (see [Group-based workspace access](#group-based-workspace-access)).
Organization roles are not derived from Entra in this mode — reserved group names don't match object IDs. Manage them in mogenius. If a user belongs to more than \~200 groups, Entra omits the groups claim; choose *Groups assigned to the application* and assign the relevant groups under **Enterprise applications → Users and groups** (Entra ID P1).
### Step 3: Connect in mogenius
1. **Organization settings → Single sign-on → Microsoft Entra.** Choose *Group memberships* (**Microsoft Graph** or **Token claims**), enter the **Client ID**, **Client Secret**, and **Tenant ID**, then click **Connect**.
2. Members sign in through the organization's Login URL. Group changes take effect at the next sign-in.
### Both modes
* Users must be **members** of a group — owners do not count.
* The Redirect URI needs the trailing slash.
## GitHub
1. In GitHub, go to **Settings → Developer settings → OAuth Apps → New OAuth App** (in your personal account or an organization).
2. Fill in the details:
* **Application name**: A recognizable name (e.g., "mogenius SSO")
* **Authorization callback URL**: Paste the Redirect URI from the mogenius SSO form
3. Register the app, then generate a **client secret**.
4. Back in mogenius, select **GitHub**, enter the **Client ID** and **Client Secret**, and click **Connect**.
## OpenID Connect
Use the generic OpenID Connect provider for any standards-compliant OIDC identity provider — for example GitLab (including self-hosted instances), Okta, Keycloak, or Auth0.
1. In your provider, create an OIDC/OAuth application:
* **Redirect URI**: Paste the Redirect URI from the mogenius SSO form
* **Scopes**: `openid`, `email`, `profile`
* Where applicable, mark the application as **confidential**.
2. Note the **Client ID**, **Client Secret**, and the provider's **Issuer URL** — the base URL where its discovery document lives at `/.well-known/openid-configuration` (for example `https://gitlab.com` for GitLab.com, or your self-hosted base URL).
3. Back in mogenius, select **OpenID Connect**, enter the **Client ID**, **Client Secret**, and **Issuer URL**, then click **Connect**.
For self-hosted providers, make sure the instance is reachable on a public HTTPS hostname. mogenius needs the discovery URL to be publicly accessible.
## Group-based workspace access
With a GroupGrant, an identity-provider group maps to access on a workspace (or cluster) with a specific role. In the token-claims flow you reference the group by its object ID; with name-based groups you reference the group name.
```yaml theme={null}
apiVersion: mogenius.com/v1alpha1
kind: GroupGrant
metadata:
name:
namespace: mogenius
spec:
claimValue:
targetType: workspace # or: cluster
targetName:
role: editor # optional: viewer (default) | editor | admin
```
`role` is optional. A GroupGrant saved without a role defaults to **viewer** (applied for kubectl/GitOps as well as the UI/CLI), so a forgotten role never grants more than read access.
Members who receive access through a GroupGrant appear in the workspace member list marked as **SSO group**. Their role is managed in the identity provider / GroupGrant, not per user in mogenius.
## Troubleshooting
**Redirect URI mismatch error**
Ensure the Redirect URI in your identity provider exactly matches the one shown in mogenius, including the protocol (`https://`) and the trailing slash.
**Discovery failures (self-hosted OpenID Connect)**
Verify that your provider is reachable from the internet and that `/.well-known/openid-configuration` returns a valid JSON document. Instances behind a VPN or on a private IP cannot be used.
**Missing email in user profile**
Ensure the `email` scope (or, for Entra, the `email` optional claim) is included, and that users have a verified email address in their identity provider.
# Troubleshooting clusters
Source: https://docs.mogenius.com/cluster-management/troubleshooting-clusters
Here's a list of common issues with clusters on mogenius and how to fix them.
Here's a list of common issues that can occur when connecting clusters with mogenius. If your problem is not on the page, please contact [support](mailto:support@mogenius.com).
## Installation failed: clusterroles.rbac.authorization.k8s.io
If installing the mogenius operator fails with an error message related to cluster roles and permissions, it is likely that your current user doesn't have sufficient permissions to perform the installation. Per default, the installation requires the clusterAdmin role.
If you can't get access to this role by company policies please contact our [support](mailto:support@mogenius.com). Depending on your infrastructure setup the operator can be customized with less permissions required.
## No connection to mogenius
The installation of the operator was completed, and the pod `mogenius-k8s-manager` is running on your cluster. However, the cluster status in mogenius is either disconnected or pending. To troubleshoot, please check the logs of the pod in Kubernetes. Here are some scenarios that might be occurring and suggestions on how to address them:
* **Unauthorized Errors:** If the pod log is showing repeating unauthorized errors and no connection can be established, it could be due to the cluster having been connected to mogenius before, and the platform API is rightfully rejecting the unknown connection. In this case, try using the Reset MFA-ID option in your cluster settings. If this option isn’t available, consider deleting the cluster in mogenius, uninstalling the operator, and restarting the installation workflow.
* **Operator Connection Issues:** If the operator cannot send traffic outside of the cluster, this could indicate a problem with the cluster’s internet connection. Check your network settings and ensure that there are no restrictions preventing outbound connections.
# Custom Resource Forms
Source: https://docs.mogenius.com/cluster-management/ui-configs
Give any custom resource a form-based create and edit experience in mogenius instead of raw YAML, using UI Configs.
By default, custom resources (CRDs) on your cluster are created and edited as raw YAML. A **UI Config** replaces that raw editor with a structured form: labelled inputs, grouped sections, dropdowns, toggles, and validation. You define the form once for a resource type, and from then on everyone who opens a resource of that type gets the same guided experience.
If no UI Config exists for a resource type, mogenius falls back to the plain YAML editor — so adding a UI Config is always additive and never blocks the raw workflow.
UI Configs currently apply to **custom resources (CRDs)** only. Built-in Kubernetes kinds keep their existing editors.
## How it works
A UI Config is a cluster-scoped resource that binds a **form layout** to a **target resource type** (its API version and kind). Only one UI Config exists per resource type.
When you create a new form, mogenius reads the target CRD's OpenAPI schema and auto-generates a starting layout with all available fields. You then curate that layout — keep the fields that matter, relabel them, group them into sections, and set defaults or validation. A live preview shows the resulting form as you edit.
## Creating a UI form
UI Configs are managed by cluster administrators.
1. Open your **Cluster** and go to **Settings → UI Configs**.
2. Select **New UI Form**.
3. Pick the target resource type from the list of custom resources. Types that already have a UI Config are shown but cannot be selected again.
4. The form editor opens with a schema auto-generated from the resource's OpenAPI definition.
## Building the form
The editor has two panels: the **builder** on the left and a **live preview** on the right that updates as you make changes.
### Sections
Fields are grouped into ordered **sections** that render as blocks in the final form. By convention the first section holds the resource's metadata (name, namespace); the following sections map to the top-level spec. Nested objects in the spec are expressed as child sections rather than fields, keeping every field a simple input.
### Fields
Each field maps to one property in the resource manifest. A field has:
* **Key** — the dot-notation path into the resource YAML, e.g. `spec.replicas` or `spec.template.spec.containers[].image`. This is where the entered value is written.
* **Label** — the name shown next to the input.
* **Description** — hint text shown below the input to explain the expected value.
* **Type** — the input widget (see below).
* **Required** — blocks form submission when left empty.
* **Default** — pre-filled into a blank create form.
* **Enum** — restricts the input to a fixed set of allowed values, rendered as a dropdown.
### Field types
* **string** — free-text input.
* **integer** / **number** — numeric input.
* **boolean** — a toggle switch.
* **array** — a list of scalar values with add/remove.
* **map** — a set of key/value pairs.
Set an **Enum** on a field to turn it into a dropdown restricted to the allowed values.
### Curating the layout
Starting from the auto-generated fields you can toggle fields on or off, rename them, reorder them, and move them between sections by drag and drop. Once you save your own edits, the UI Config is marked as **customized** to distinguish it from an untouched auto-generated schema.
## Saving
Use **Save** in the editor header to store the UI Config. It takes effect immediately for every resource of the target type across the cluster.
## How users experience it
Once a UI Config exists for a resource type, users opening a resource of that type see a **Details** tab that renders the form — on both the resource detail page and the resource drawer. They can fill in and edit values through the form controls instead of editing YAML, with required fields validated inline. If no UI Config exists, the **YAML** tab is shown instead.
## Managing UI forms
From **Settings → UI Configs** you can, per resource type:
* **Edit** — reopen the form editor to adjust the layout.
* **View YAML** — inspect the underlying UI Config manifest.
* **Delete** — remove the form. Resources of that type fall back to the plain YAML editor.
# Update and uninstall
Source: https://docs.mogenius.com/cluster-management/update-and-uninstall
Manage the mogenius operator, run updates and delete it from your cluster.
You can manage the installation of your mogenius operator directly from the management pane in mogenius. In the "Settings" and "Connect" sections, you will find several options to update your operator and to upgrade and uninstall the Helm repository.
## Updating the mogenius operator
New versions of the operator are released frequently to deliver additional features and improvements alongside the development of the mogenius platform. Updates to the operator must be installed manually. To do so, open the "Settings" tab in your cluster and scroll down to the update section.
In this area, you can track the following versions:
* Your version: The current version of your operator on the cluster
* Current version: The most recent version available
By clicking the "Update k8s manager" button, your operator will be updated to the current version.
Updating your operator does not affect the services running on your cluster. However, the operator will restart, resulting in a short connection interruption in which events between the mogenius platform and the cluster may get lost.
## Helm uninstall
To remove the mogenius operator from your cluster, use `Helm uninstall`. Head to the "Connect" tab, and in the code section, switch to "Uninstall." Once executed on your Kubernetes cluster, the operator and all accompanying platform services (e.g., cert manager, ingress controller, etc.) will be removed.
The uninstall command looks like this:
```jsx title="mogenius operator Helm uninstall" theme={null}
helm uninstall mogenius -n mogenius
```
Namespaces and services created through projects in the mogenius platform won't be affected by the uninstall. To remove them, you must delete them through the mogenius platform (an active connection to the operator is required).
# Blueprints
Source: https://docs.mogenius.com/deploying-applications/blueprints
Deploy pre-configured Helm charts to your cluster using the Blueprints library, with optional GitOps integration and full customization.
Blueprints provide a library of pre-configured Helm charts that you can deploy to your cluster with sensible defaults. They replace the previous Cluster Services approach and give you full control over the configuration of each component before deployment.
Once a Blueprint is deployed, it becomes a standard Helm release and is managed through the existing [Helm Charts](/deploying-applications/helm-charts) interface — Blueprints are an entry point for installation, not a separate management layer.
## How Blueprints work
Each Blueprint is defined in a Blueprint Repository — a Git repository that contains Helm chart references, default values, and metadata. mogenius provides a default repository with commonly used infrastructure components. You can replace it with your own repository to define a custom standard stack for your organization.
A Blueprint includes the following metadata:
* **Display name and description** of the component
* **Category and tags** for filtering (e.g. security, networking, monitoring)
* **Helm chart reference** pointing to the upstream chart
* **Default values** that are pre-configured for a production-ready setup
## Default Blueprints
mogenius ships with Blueprints for the following infrastructure components:
| Blueprint | Category | Description |
| - | - | - |
| cert-manager | Security | Automated TLS certificate management — integrates with Let's Encrypt and private CAs. |
| Traefik | Networking | Cloud-native reverse proxy and ingress controller with automatic HTTPS. |
| MetalLB | Networking | Bare-metal load-balancer — assigns external IPs on clusters without cloud load-balancers. |
| Cilium | Networking | eBPF-based CNI providing networking, observability and security. |
| Alertmanager | Monitoring | Routes alerts from Prometheus to receivers like email, Slack, or PagerDuty. |
| Kube Prometheus Stack | Monitoring | Full monitoring stack — Prometheus, Grafana, Alertmanager and kube-state-metrics. |
| Argo CD | GitOps | Declarative GitOps continuous delivery — syncs your cluster state from Git. |
| Flux Operator | GitOps | Manages Flux CD instances declaratively using a FluxInstance CRD. Once installed, manage it from [GitOps with Flux](/cluster-management/gitops/flux). |
| Metrics Server | Operations | Resource usage aggregator — required for `kubectl top` and Horizontal Pod Autoscaler. |
| Calico (Tigera Operator) | Networking | CNI plugin with fine-grained network policies. |
| External Secrets Operator | Security | Syncs secrets from AWS Secrets Manager, GCP Secret Manager, Vault, and others into Kubernetes. |
| Harbor | Registry | Container and artifact registry with vulnerability scanning, RBAC and replication. |
| Kyverno | Security | Kubernetes-native policy engine — validates, mutates and generates resources. |
| NFS Subdir External Provisioner | Storage | Automatic NFS-based PersistentVolume provisioner for PVC claims. |
| Renovate | Operations | Automated dependency updates — keeps Helm charts, container images and packages current. |
## Installing a Blueprint
To deploy a Blueprint, navigate to the **Helm Charts** tab in your cluster and click **Install Chart**. In the installation dialog, you can choose between installing a chart from a Helm repository or selecting a Blueprint.
Browse the available Blueprints in the library. Each entry shows the name, description, and category. Select the Blueprint you want to install.
The Blueprint's default Helm values are pre-filled in the YAML editor. Review them and adjust any settings to match your requirements before proceeding. The defaults are designed to work out of the box for most setups.
Set the release name and target namespace. If the namespace does not exist yet, use the **Create New Namespace** button — the namespace will be created automatically before the chart is installed.
If your cluster has [GitOps](/cluster-management/gitops/argocd) enabled, you can activate the GitOps toggle to deploy the Blueprint through Argo CD instead of a direct Helm install. This stores the configuration in your Git repository, making it versioned and auditable.
Confirm your settings to start the installation. A real-time log view shows the deployment progress. Once the installation completes, the release appears in your Helm Charts overview with its current status.
If errors occur during installation, the log output provides details. Check the error message and adjust the Helm values or namespace configuration as needed.
After deployment, the Blueprint is a regular Helm release. You can view its status, resources, and values on the [Helm Charts](/deploying-applications/helm-charts) page and manage it like any other release.
You can also deploy Blueprints programmatically — see [Deploy a Blueprint](/workspaces/mogenius-API#deploy-a-blueprint) in the API reference.
## GitOps integration
When GitOps is enabled on your cluster, Blueprints can be deployed through the GitOps workflow. Activating the GitOps toggle during installation creates an Argo CD Application in your connected Git repository instead of installing the chart directly.
This means the Blueprint configuration is stored in Git, versioned alongside your other cluster resources, and synced by Argo CD. For more details on the GitOps setup, see [GitOps](/cluster-management/gitops/argocd).
If GitOps is not configured on your cluster, Blueprints are deployed as direct Helm releases — no additional setup is required.
## Using a custom Blueprint repository
By default, mogenius uses the [mogenius/helm-chart-blueprints](https://github.com/mogenius/helm-chart-blueprints) repository. You can replace it with your own repository in the **Organization Settings** to define a custom set of Blueprints for your teams.
To create a custom Blueprint repository, we recommend forking the default mogenius repository and modifying it to fit your needs. The repository structure is straightforward:
* The `/charts` directory contains individual Blueprint definitions, each referencing a Helm chart with default values.
* The `index.yaml` at the root defines which Blueprints are shown in the mogenius UI, including display names, descriptions, categories, and icons.
Once your custom repository is configured, the Blueprint library in mogenius will show your Blueprints instead of the defaults.
To keep your Blueprint repository up to date with the latest Helm chart versions, we recommend using [mogenius/renovate-operator](https://github.com/mogenius/renovate-operator). It automatically monitors chart dependencies and creates updates.
# Container images
Source: https://docs.mogenius.com/deploying-applications/container-images
You can deploy container images with mogenius from any public or private container registry. To get started, click **Add Resource** on your workspace dashboard and select **Container image**.
## Creating a deployment
On the following page, enter the settings for the container image you want to deploy:
* **Name**: The name of the deployment. This can't be changed later.
* **Kind**: By default this is set to Deployment. You can change it to [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) or [StatefulSet](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/).
* **Namespace**: The namespace where your workload should run.
* **Container image**: The URL of your container image and tag. By default, this field accepts images from Docker Hub (e.g. `nginx:latest`), but you can enter container image URLs from any registry. Note that if your image is private, you'll need to define an image pull secret below.
* **Container Settings**: Define image commands and arguments that your container should execute when started.
* **Image Pull Secret**: If your image is private, authentication is done through credentials stored in an image pull secret on your Kubernetes cluster. You can either select an existing one, or create a new secret by entering a secret name, registry URL, user, and access token.
* **YAML manifest**: At the end, you can preview and modify the manifest that will be deployed to the cluster. You can adjust resource limits, environment variables, and other settings directly in the YAML before deploying.
Click **Create** and the mogenius operator will deploy the container image to your cluster.
## After deployment
Once your deployment is created, it appears on your workspace dashboard and you can manage it from there:
* **Monitor** your application's status, resource consumption, logs, and events on the deployment detail page. See [Monitoring and Logs](/workspaces/service-status-and-errors) for details.
* **Configure** environment variables, secrets, health checks, scaling, update strategies, and resource limits in the deployment settings. See [Deployment Configuration](/deploying-applications/deployment-configuration) for a full guide.
* **View dependencies** using the topology view on the detail page, which shows related resources like Services, Ingress, ConfigMaps, and Secrets.
## Programmatic deployment options
Deploying through the UI is the quickest way to get started. For automated and production workflows, mogenius offers several programmatic options:
* **Pipeline Starters (CI/CD)**: Automatically build and deploy from a Git repository using GitHub Actions. See [Pipeline Starters](/deploying-applications/pipeline-starters).
* **GitOps**: Enable declarative, Git-based deployment management with ArgoCD. Manifests are auto-generated from the UI and synced through Git. See [GitOps](/cluster-management/gitops/argocd).
* **API**: Update container images programmatically from custom CI pipelines using the [set-image API](/workspaces/mogenius-API).
* **GitHub Actions templates**: Use pre-built workflow templates from the [mogenius build-workflows repository](https://github.com/mogenius/build-workflows) for custom CI/CD integrations.
# Deployment Configuration
Source: https://docs.mogenius.com/deploying-applications/deployment-configuration
Configure environment variables, secrets, ports and domains, scaling, health checks, update strategies, and resource limits for your deployments in mogenius.
After deploying an application with [container images](/deploying-applications/container-images), [pipeline starters](/deploying-applications/pipeline-starters), or [Kubernetes manifests](/deploying-applications/kubernetes-manifests), you can configure all deployment settings through the mogenius UI. Open any deployment in your workspace to access the detail page, where you'll find settings for environment variables, health checks, scaling, and more. You can use the simplified UI forms or switch to the YAML editor for full control over your manifests.
If [GitOps](/cluster-management/gitops/argocd) is enabled, any configuration change you make through the UI is automatically committed to your Git repository and synced by ArgoCD.
## Environment variables
Environment variables allow you to pass configuration values to your containers at runtime. In mogenius, you manage them directly from the deployment settings.
To configure environment variables:
1. Open the detail page of your deployment in the workspace.
2. Navigate to the **Settings** section.
3. Add environment variables as key-value pairs using the form.
4. To edit multiple variables at once, switch to the **YAML editor** for bulk editing.
5. Save your changes to apply them to the deployment.
### Referencing secrets
Instead of storing sensitive values directly as environment variables, you can reference Kubernetes Secrets. This keeps credentials, API keys, and other sensitive data separate from your deployment configuration. In the environment variables form, you can set a variable to reference a value from a Secret using the `valueFrom` pattern, which maps to a specific key in a Kubernetes Secret object.
### ConfigMaps as environment variables
Similarly, you can reference values from ConfigMaps to inject shared configuration data into your containers. This is useful for non-sensitive configuration that is shared across multiple deployments.
## Secrets and ConfigMaps
mogenius provides a dedicated **Secrets & Configs** page in each workspace for managing Kubernetes Secrets and ConfigMaps without requiring YAML.
On this page you can:
* **Create new Secrets** with an intuitive form — enter key-value pairs and mogenius handles encoding and resource creation.
* **Create ConfigMaps** for non-sensitive configuration data shared across deployments.
* **Edit existing Secrets and ConfigMaps** directly through the UI.
* **Navigate** between Secrets, ConfigMaps, and the deployments that reference them.
### Image pull secrets
When deploying from a private container registry, you need an image pull secret to authenticate. You can create image pull secrets during the initial deployment (see [Container Images](/deploying-applications/container-images)), or manage them afterwards in the **Source** settings of your deployment. From there, you can select an existing secret on the cluster or create a new one by providing your registry URL, username, and access token.
## Resource limits and requests
Resource limits and requests control how much CPU and memory your containers can use. Setting these correctly ensures stable performance and efficient cluster utilization.
In the deployment settings, configure:
* **CPU request**: The minimum CPU resources guaranteed for your container.
* **CPU limit**: The maximum CPU resources the container can consume.
* **Memory request**: The minimum memory guaranteed for your container.
* **Memory limit**: The maximum memory the container can use before being terminated.
Setting appropriate resource requests is important for Kubernetes scheduling. If requests are too high, pods may not be scheduled. If too low, pods may be evicted under resource pressure.
## Health checks and probes
Health checks ensure that your application is running correctly and ready to serve traffic. Kubernetes uses three types of probes that you can configure in the deployment settings.
### Probe types
* **Liveness probe**: Checks if your container is still running. If the liveness probe fails, Kubernetes restarts the container. Use this to recover from deadlocks or unresponsive states.
* **Readiness probe**: Checks if your container is ready to accept traffic. If the readiness probe fails, Kubernetes removes the pod from service endpoints until it passes again. Use this to avoid sending traffic to pods that are still initializing or temporarily unable to serve requests.
* **Startup probe**: Delays liveness and readiness checks until the startup probe succeeds. Use this for slow-starting containers that need extra time to initialize before health checks begin.
### Configuring probes
To set up health checks:
1. Open the deployment settings.
2. Navigate to the health checks section.
3. Select the check method:
* **HTTP**: Sends an HTTP GET request to a specified path and port. The check passes if the response status is between 200 and 399.
* **TCP**: Attempts a TCP connection to a specified port. The check passes if the connection is established.
* **Exec**: Runs a command inside the container. The check passes if the command exits with status code 0.
4. Configure the probe parameters:
* **Initial delay (seconds)**: Time to wait after the container starts before running the first check.
* **Period (seconds)**: How often to run the check.
* **Timeout (seconds)**: How long to wait for a response before the check is considered failed.
* **Success threshold**: Number of consecutive successes required to mark the probe as passing.
* **Failure threshold**: Number of consecutive failures required to take action (restart or remove from service).
Start with a readiness probe as the minimum configuration. This prevents traffic from being routed to pods that aren't ready, which is the most common cause of errors during deployments and restarts.
## Horizontal scaling
mogenius supports both manual replica scaling and automatic horizontal pod autoscaling (HPA) through the deployment settings.
### Manual scaling
Set the **replica count** to define how many instances of your pod should run simultaneously. You can adjust this in the deployment settings, or use the [Resource Manager](/workspaces/resources) to quickly scale a deployment up or down.
### Horizontal Pod Autoscaler (HPA)
For automatic scaling based on resource utilization, configure the HPA in the deployment settings:
* **Minimum replicas**: The lowest number of pods to maintain, even under low load.
* **Maximum replicas**: The upper limit of pods that the autoscaler can create.
* **Scaling triggers**: Define the target utilization thresholds that trigger scaling. Common triggers include:
* **CPU utilization**: Scale when average CPU usage across pods exceeds a target percentage.
* **Memory utilization**: Scale when average memory usage exceeds a target percentage.
When the observed resource usage exceeds the target, Kubernetes automatically adds pods up to the maximum. When usage drops, it scales back down to the minimum.
Scaling settings are also manageable through [GitOps](/cluster-management/gitops/argocd), which allows you to maintain consistent scaling configurations across environments.
## Update strategy
The update strategy defines how Kubernetes replaces existing pods with new ones during a deployment update (e.g., when you change the container image or configuration).
### Rolling update
This is the default strategy. Kubernetes gradually replaces old pods with new ones, ensuring that your application remains available throughout the process.
Configure the rolling update behavior in deployment settings:
* **maxSurge**: The maximum number of pods that can be created above the desired replica count during an update. For example, if you have 3 replicas and maxSurge is 1, Kubernetes may run up to 4 pods during the update.
* **maxUnavailable**: The maximum number of pods that can be unavailable during the update. For example, if set to 1, at least 2 out of 3 replicas remain available at all times.
### Recreate
With the Recreate strategy, all existing pods are terminated before new ones are created. This causes downtime but is useful when your application cannot run multiple versions simultaneously (e.g., due to database migrations or shared file locks).
Pair rolling updates with [health checks](#health-checks-and-probes) to ensure that new pods are verified as healthy before old pods are terminated. This prevents broken deployments from taking down your application.
## Ports and domains
The Ports & Domains section configures how your application is exposed internally within the cluster and externally to the internet. This controls the Kubernetes Service and Ingress resources for your deployment.
### Configuring ports
Each port entry defines how traffic reaches your container:
* **Type**: The protocol for the port — either `TCP` (default) or `UDP`.
* **Container port**: The port your application listens on inside the container. You can select from ports defined in your container spec or enter a custom value.
* **Service port**: The port exposed by the Kubernetes Service. Other workloads in the cluster can reach your application at `:`.
Click **Add Port** to define additional ports if your application listens on multiple ports.
### Exposing ports externally
To make a port accessible from outside the cluster, enable the **Expose port** toggle. This creates an Ingress rule that routes external traffic to your service.
When a port is exposed, you can configure one or more domains:
* **Domain**: The hostname for accessing your application (e.g., `api.example.com`). When adding a domain, mogenius pre-fills it with your cluster's load balancer hostname. You can use this default or replace it with your own custom domain.
* **SSL/TLS**: Enable HTTPS for the domain. By default, mogenius uses cert-manager to automatically issue a Let's Encrypt certificate.
To use a custom domain, create a DNS CNAME record pointing your domain to your cluster's load balancer hostname.
### Custom TLS certificates
If you need to use your own TLS certificate instead of Let's Encrypt (for example, for wildcard certificates or internal CAs), expand the **Advanced** settings under SSL/TLS:
1. Enable **Custom Secret**.
2. Select an existing `kubernetes.io/tls` Secret from the dropdown. This secret must contain your certificate and private key.
When Custom Secret is disabled, cert-manager automatically provisions and renews certificates from Let's Encrypt.
## Volume mounts
Volume mount settings allow you to attach persistent storage and configuration files to your containers. You can configure volumes and their mount paths directly in the deployment settings.
For persistent storage solutions, see [Storage](/workspaces/storage).
## Using the YAML editor
Every setting described above can also be configured through the YAML editor. On the detail page of any controller (Deployment, StatefulSet, DaemonSet), use the **UI/YAML toggle** to switch between the simplified form view and the full YAML manifest editor. The YAML view provides direct access to the Kubernetes manifest, and includes a topology of all dependent resources for navigation through the complete configuration.
# Helm charts
Source: https://docs.mogenius.com/deploying-applications/helm-charts
mogenius includes a Helm chart manager that simplifies managing Helm repositories and releases on your cluster. With this feature, you can monitor installed charts on your cluster and easily install new ones.
Helm charts are currently available on the **Clusters** page. We’re working on enabling Helm charts within projects.
## Accessing the Helm Charts UI
To use the Helm charts manager, go to the **Clusters** page within your organization. If you don’t have a Kubernetes cluster connected yet, refer to our [quickstart guide](../overview/quickstart.md). Once inside the cluster, navigate to the **Helm Charts** tab.
This page displays:
* All installed Helm repositories on the cluster.
* A list of Helm releases, including their status, versions, namespace, and age.
By opening a release, you can view:
* Detailed information about the Kubernetes resources managed by the Helm chart.
* Configuration files, such as `values.yaml`, which define the chart's setup.
## Adding a Helm Repository
To add a new Helm repository, use the **Add Repository** button at the top of the page. Fill out the following fields in the menu that appears:
* **Name**: Internal name to display the chart.
* **Repository URL**: The URL of the Helm repository you want to install.
* **User Name and Password Credentials (optional)**: Provide credentials if the repository requires authentication.
* **Skip TLS**: Enable this option to skip TLS during authentication (optional).
Once the repository is installed, its charts will be available for installation. When adding a repository, the latest versions of its charts are automatically retrieved. If charts in a repository are updated later, use the **Update All** button to fetch the latest versions.
## Installing from Blueprints
When installing a chart, you can also choose from the [Blueprints](/deploying-applications/blueprints) library. Blueprints are pre-configured charts for common infrastructure services (ingress controllers, monitoring, TLS, etc.) with sensible defaults. Select a Blueprint instead of a repository chart, customize the values if needed, and deploy — the result is a standard Helm release managed here.
## Installing a Helm Chart
To install a new Helm chart, click the **Install Chart** button. Here's how to proceed:
1. **Select the Chart**: Choose the chart you want to install from the list or search for it by name.
2. **Configure the Release**: Fill out the following settings:
* **Version**: Select the desired chart version from the list of available versions in the repository.
* **Release Name**: Specify an internal name for the Helm release.
* **Namespace**: Select the namespace where the chart will be installed. All resources from the chart will be deployed into this namespace.
* We recommend creating a new namespace for your chart to prevent conflicts with other applications on the cluster. Use the **Create New Namespace** button to quickly create one.
* **Chart Values Reference**: Review the default chart values. Most charts should install successfully with default values for testing purposes. You can refine the configuration later with custom values.
* **User-Defined Values**: To modify default chart configurations or fill out template values, use the YAML editor. Copy sections from the chart values reference and overwrite them with your configurations. A custom `values.yaml` file will then be applied during chart installation.
3. **Confirm Settings**: Once your configurations are complete, confirm your settings to start the installation. You can monitor the installation process through the logs.
After installation, the release will appear in the list, and its status should change to `Deployed`. If errors occur, check the logs and adjust the release configuration as needed.
## Installing from OCI Registries
In addition to traditional Helm repositories, mogenius supports installing charts from OCI-compliant registries such as GitHub Container Registry (ghcr.io), Amazon ECR, Google Artifact Registry, or Docker Hub.
To install an OCI chart:
1. Click **Install OCI Chart** on the Helm Charts page.
2. Enter the **OCI Chart URL** in the format `oci://registry/repository/chart` (e.g., `oci://ghcr.io/myorg/my-chart`).
3. Optionally provide **registry credentials** if the chart requires authentication.
4. Select the **version**, **release name**, and **namespace** as with standard chart installations.
5. Configure custom values if needed and confirm to install.
OCI registries are increasingly common for distributing Helm charts. If your organization uses GitHub Packages, ECR, or a similar registry for container images, you can likely store Helm charts there as well.
## Upgrading a Helm Release
To upgrade an existing release to a new chart version or apply updated values:
1. Open the release details by clicking on a release in the list.
2. Click **Upgrade** to open the upgrade dialog.
3. Select the new **chart version** from the available versions.
4. Review and modify the **values** as needed. The current values are pre-filled for reference.
5. Confirm to start the upgrade.
The upgrade process creates a new revision of the release. You can monitor progress in the logs. If the upgrade succeeds, the release status updates to `Deployed` with the new version.
Upgrading a release preserves its revision history, allowing you to roll back if needed.
## Rolling Back a Release
If an upgrade introduces issues, you can roll back to a previous revision:
1. Open the release details by clicking on a release in the list.
2. Click **Rollback** to open the rollback dialog.
3. Select the **revision** you want to restore from the list of previous revisions. Each revision shows the chart version and description.
4. Confirm to roll back.
The rollback creates a new revision that restores the previous configuration. This is a safe operation — the previous revisions remain available in case you need to roll back again or roll forward.
Before rolling back, review the revision details to understand what configuration was active at that point. This helps ensure you're restoring to the correct state.
## Linking Releases to Workspaces
Helm releases installed at the cluster level can be linked to a Workspace for easier monitoring and access control. When a release is linked to a Workspace:
* Workspace members can view the release status and resources
* The release appears in the Workspace's resource list
* Access is governed by Workspace roles
To link a release to a Workspace:
1. Open the release details.
2. Click **Link to Workspace**.
3. Select the target Workspace from the list.
4. Confirm to create the link.
This is useful when a platform team installs shared infrastructure (databases, message queues, etc.) that application teams need to monitor but not manage directly.
## Uninstalling a Release
To remove a Helm release from your cluster:
1. Open the release details by clicking on a release in the list.
2. Click **Uninstall** (or use the actions menu).
3. Confirm the uninstallation.
Uninstalling a release deletes all Kubernetes resources managed by that release. This action cannot be undone. Make sure to back up any important data before uninstalling.
The uninstallation process removes the release and its resources from the cluster. Once complete, the release will no longer appear in the list.
# Kubernetes manifests
Source: https://docs.mogenius.com/deploying-applications/kubernetes-manifests
You can deploy any Kubernetes manifest from within a workspace based on default resource templates. This way you can avoid creating local YAML files, applying them via kubectl, and instead use the mogenius interface to deploy manifests quickly.
To deploy a manifest, follow these simple steps:
1. Create a workspace.
2. Add an existing namespace to your workspace, or create a new one.
3. Select the kind of Kubernetes resource (deployment, pod, configmap, etc.).
4. Define the namespace where your resource should be created.
5. A YAML template will be shown. Configure the necessary values and then click **Create**.
# Multi-Environment Deployments
Source: https://docs.mogenius.com/deploying-applications/multi-environment-deployments
Set up a multi-environment deployment strategy with dev, staging, and production using mogenius UI and GitOps.
A common pattern for production-ready applications is maintaining separate environments for development, staging, and production. mogenius supports this through a combination of UI-based deployments for rapid iteration and GitOps for stable, version-controlled environments.
**The recommended approach:**
* **Development**: Deploy and iterate quickly using the mogenius UI.
* **Staging and Production**: Enable GitOps to manage deployments declaratively through Git, with pull request-based reviews for production changes.
## Setting up a development environment
Create a workspace for your development environment. Assign it to the cluster and namespace where your dev workloads should run. See [Creating Workspaces](/workspaces/creating-workspaces).
Use any of the deployment methods to get your application running:
* [Container images](/deploying-applications/container-images) for deploying from a registry.
* [Pipeline starters](/deploying-applications/pipeline-starters) for CI/CD from a Git repository.
* [Helm charts](/deploying-applications/helm-charts) for chart-based deployments.
Set up environment-specific configuration for your dev environment: environment variables, resource limits, health checks, and scaling. See [Deployment Configuration](/deploying-applications/deployment-configuration).
Use the built-in [monitoring and logs](/workspaces/service-status-and-errors) to debug and iterate on your application. The mogenius UI allows you to make changes and see results quickly without needing to manage YAML files or kubectl commands.
## Enabling GitOps for environment promotion
Once your application is working in development, enable GitOps to version-control your configurations and promote them to other environments.
Navigate to your cluster settings and enable GitOps. This installs ArgoCD and Sealed Secrets on your cluster and connects a GitHub repository. See [GitOps setup](/cluster-management/gitops/argocd).
Add your development deployments to a GitOps application. mogenius automatically generates the Kubernetes manifests and commits them to your Git repository. You now have a versioned, declarative representation of your application.
All configuration changes you make through the mogenius UI are automatically committed to Git. This gives you a full history of changes and enables Git-based workflows for promoting configurations to other environments.
## Creating staging and production environments
With your application manifests in Git, you can set up additional environments using GitOps.
### Staging environment
Create a separate workspace with its own namespace for staging. Use GitOps to deploy from the same Git repository, ensuring consistency between development and staging. Adjust environment-specific settings (environment variables, resource limits, replica counts) as needed for the staging context.
### Production environment
For production, use GitOps with **pull request-based commit behavior**. This ensures that every change to your production configuration goes through a review process before being applied.
To enable this:
1. In your cluster's GitOps settings, activate the toggle for creating pull requests instead of direct commits.
2. When changes are made, mogenius creates a pull request in your Git repository.
3. Team members review and approve the pull request.
4. Once merged, ArgoCD syncs the changes to the production cluster.
Using pull request-based commits for production environments enforces code review on all infrastructure changes, providing an audit trail and preventing accidental configuration changes.
## Alternative: ApplicationSets for existing Git configurations
If your team already maintains Kubernetes manifests, Helm charts, or Kustomize overlays in Git, you can use **ApplicationSets** instead of the workspace-based approach described above. ApplicationSets deploy directly from your existing Git repository structure.
This approach is useful when:
* You have an established GitOps workflow with manifests already in Git
* You use Kustomize overlays for environment-specific configurations (e.g., `overlays/dev`, `overlays/staging`, `overlays/prod`)
* You want to manage environment differences through Git rather than the mogenius UI
To set this up:
1. Enable GitOps on your cluster and connect your manifest repository
2. Create an ApplicationSet for each environment, pointing to the appropriate overlay or values file
3. Use Kustomize configuration options (namespace overrides, name prefixes, image overrides) to differentiate environments
For example, with a Kustomize-based repository:
* **Dev ApplicationSet**: Path `apps/my-service/overlays/dev`, Kustomize Namespace `development`
* **Prod ApplicationSet**: Path `apps/my-service/overlays/prod`, Kustomize Namespace `production`, Name Prefix `prod-`
See [ApplicationSets](/cluster-management/gitops/argocd#applicationsets) for detailed configuration options.
## Managing environment-specific configurations
When running multiple environments, keep these practices in mind:
* **Use separate namespaces** for each environment to isolate resources and prevent conflicts.
* **Environment variables**: Set different values per environment (e.g., database URLs, API endpoints, feature flags) in each workspace's [deployment settings](/deploying-applications/deployment-configuration).
* **Resource limits and scaling**: Development environments typically need fewer resources and replicas than production. Configure appropriate [resource limits and scaling](/deploying-applications/deployment-configuration#horizontal-scaling) per environment.
* **Secrets**: Manage environment-specific secrets through the Secrets & Configs page in each workspace. When GitOps is enabled, secrets are encrypted with [Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) before being committed to Git.
* **Workspaces as team boundaries**: Use [workspace roles](/workspaces/members-and-roles) to control who can make changes in each environment. For example, give developers editor access to dev but only viewer access to production.
# Overview
Source: https://docs.mogenius.com/deploying-applications/overview
The mogenius platform offers several ways of deploying containerized applications to a Kubernetes cluster. Currently we support deploying services from git repositories, container registries and templates. We're extending these options soon by features like Docker compose, Helm charts, Terraform modules and more.
You will find details about creating each service type on the pages below.
# Pipeline starters
Source: https://docs.mogenius.com/deploying-applications/pipeline-starters
If you're starting from a repository with just a Dockerfile, mogenius has a pipeline starter for GitHub actions that seamlessly deploys your application to Kubernetes. This is the worklow that the pipeline starter creates:
1. The container image is built based on the Dockerfile in your repository.
2. The image is pushed to your container registry.
3. The mogenius operator is receives an API call to trigger the deployment.
4. A deployment is created on Kubernetes.
5. The new image from your GitHub actions workflow is set.
6. Which each commit to your repository, the workflow is automatically triggered again.
To deploy a container with the pipeline starter, go to your workspace dashboard.\
Click **Add resource** and select **Pipeline starter** from the list.
### Connect your GitHub account
First, you'll be asked to set up the GitHub integration for the pipeline starter. After logging in with GitHub, select the GitHub organization, user, and repository permissions that you want to use. This will create an application in your GitHub account that manages the mogenius integration.
### General settings
After the integration is set up you'll define basic settings for the application you want to deploy:
* Name: The name of the deployment. This can't be changed later.
* Kind: By default this is set to deployment. You can change it to [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) or [StatefulSet](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/).
* Namespace: The namespace where your workload should run.
* Git repository: The repository of your application. The pipeline starter will be pushed to this repository.
* Branch: The branch that should be used for the pipeline.
* Dockerfile path: The location and name of your Dockerfile in the repository. By default this is set to root.
* Docker context: The context that should be used during `Docker build`.
### API Key
At the end of the workflow, the pipeline starter will trigger the mogenius operator to deploy the new image. This requires a [workspace API key](../workspaces/mogenius-API). If you stored an existing API key in a vault that you want to use, you can copy and paste it. If you want to use a new API key, create it with the button below the form field.
### Container registry credentials
You'll need to provide credentials to access the container registry when pushing the image and pulling it from Kubernetes later. If an [ImagePullSecret](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/) exists on your cluster, you can select it from the dropdown menu to use the credentials that were stored there.
Next, enter the credentials to authenticate with your container registry. Enter user, registry URLs, and access token in the respective form fields. The access token requires read and write access to your registry in order to push and pull images.
If you're creating a new ImagePullSecret, enter a name for the secret. You'll see a preview of the `dockerconfigjson` below. This will be base64 encoded and used in the ImagePullSecret. You can also modify the content of the dockerconfigjson in the preview manually.
### Deploy the pipeline starter
Click **Create** to deploy the pipeline starter. This will push the pipeline starter to your repository and trigger the new worklow to build your image. The deployment will happen automatically and you should see your Pod restarting soon, pulling the new image. Please note, that while the initial workflow is running, it is normal that you Pod isn't starting. As soon as the image is ready, Kubernetes will pull it automatically.
With the Git integration, you can follow the progress of the GitHub actions workflow in mogenius.
### GitHub Actions templates
The pipeline starter is based on GitHub Actions workflow templates maintained by mogenius. You can find these templates in the [mogenius build-workflows repository](https://github.com/mogenius/build-workflows). The templates can also be used independently in your own CI/CD pipelines for custom integrations with the mogenius operator.
For production deployments, consider enabling [GitOps](/cluster-management/gitops/overview) to layer declarative Git-based management on top of your CI/CD pipeline. This gives you version-controlled infrastructure with full audit history.
# Introduction
Source: https://docs.mogenius.com/introduction
Welcome to the mogenius documentation hub, your comprehensive resource for setting up and utilizing mogenius as your Kubernetes Manager.
## What is mogenius?
![Hero Keep Efficiency Pn]()
mogenius empowers you to monitor and manage Kubernetes applications easily. With Workspaces, teams get access to the resources they need in a safe way. They beautifully structure your Kubernetes clusters, simplify troubleshooting, and come with built-in pipeline tools to easily deploy any container to Kubernetes. To learn more about mogenius, please visit our [website](https://mogenius.com).
[**Read our quickstart guide to set up mogenius and get started.**](/overview/quickstart)
[**Or dive into how mogenius works for a comprehensive overview.**](/overview/how-mogenius-works)
## The mogenius documentation
This documentation hub serves as a resource for getting started, utilizing the platform's features, and exploring tutorials covering entire workflows.
## mogenius for DevOps and Developers
With mogenius, developers can work easily and safely with Kubernetes, without constant DevOps support. The platform provides developers with workspaces that abstract complexity, implement RBAC and guardrails, and automate deployments. mogenius therefore helps DevOps to reduce support overhead, ensure safe Kubernetes operations, and improve developer adoption.
**Cloud-agnostic operator**\
mogenius seamlessly integrates with Kubernetes clusters on any infrastructure, including cloud providers, on-premise, or local environments. The implementation is simple by installing the mogenius operator on Kubernetes using Helm. [Read more](./cluster-management/installing-the-mogenius-operator)
**Monitoring and logging**\
mogenius offers aggregated monitoring of all service and resource metrics, traffic analytics, and consolidated build, deployment, and application runtime logs. Developers can independently navigate the resources they need to troubleshoot applications with real-time pod logs, Kubernetes events, resource topologies, and metrics.
**Automated pipelines on Kubernetes clusters**\
With mogenius, deploying applications on any Kubernetes cluster takes just minutes. Developers can easily connect their repositories (e.g., GitHub, GitLab, or container registries), and mogenius' pipeline starters will take care of the rest. If you prefer using your own pipeline instead, you can easily integrate it.
**Invite team members and assign roles**\
Invite team members to collaborate on projects or organizations, granting them specific access rights such as viewing, editing, or admin roles. Control user permissions to ensure efficient collaboration.
**Harness Kubernetes for your developers**\
mogenius acts as a lightweight yet powerful tool, simplifying Kubernetes usage for teams. Onboarding is quick, enabling everyone on your team to leverage the full potential of Kubernetes without the need for lenghty training or manual governance. Experience minimal overhead while retaining complete control over your clusters.
## How to contribute
The mogenius documentation is open-source and based on Docusaurus. You can contribute by editing or creating content within the documentation. Simply create a pull request on [**GitHub**](https://github.com/mogenius/docs) with your suggested changes. We appreciate your contributions!
# Basic concepts
Source: https://docs.mogenius.com/overview/basic-concepts
The mogenius platform comprises multiple organizational levels tailored to various workflows and use cases for DevOps, developers, and teams.
## Organizations
Organizations are the highest level in the mogenius platform. Each organization has its own member list, billing, and settings. Clusters, workspaces, and other resources can be shared within an organization but not across different organizations. Organizations are useful for representing isolated groups of people. You can create multiple organizations to accommodate large, independent departments, subsidiaries, or clients who should not have access to each other's resources.
## Clusters
Clusters in mogenius serve as control planes for Kubernetes clusters. They provide various settings to manage the Helm installation of mogenius on Kubernetes, define policies and controls for workspaces, and monitor resources on the cluster. A cluster's platform tool stack — GitOps, ingress, certificates, monitoring, secrets, and more — is defined declaratively through its [Platform Config](/cluster-management/platform-config).
## Workspaces
Workspaces are an extension to Kubernetes that allow you to group resources for a dedicated set of users, based on namespaces, Helm releases, or labels. Each workspace comes with a comprehensive dashboard for monitoring services and to navigate resources on the cluster in an abstracted and safe way for the team. You can create multiple workspaces to manage access and permissions granularly. Workspaces also come with built-in deployment tools, to either connect your existing build pipelines, or to create pipeline starters like GitHub Actions templates.
mogenius introduces a Custom Resource Definition (CRD) for workspaces on Kubernetes. This allows you to create and update workspaces in your mogenius account as Kubernetes resources. This can be useful for automating the creation of workspaces, or for integrating it with third-party tooling.
Here's an example of a YAML that defines a workspace with two namespaces and a Helm release:
```
apiVersion: mogenius.com/v1alpha1
kind: Workspace
metadata:
creationTimestamp: '2025-03-27T21:06:24Z'
generation: 2
name: exampleworkspace
namespace: mogenius
resourceVersion: '4362774'
uid: b400fefe-7678-4548-bd21-14c8e1781b73
spec:
resources:
- id: gitea
type: namespace
- id: opensearch
type: namespace
- id: discourse
namespace: discourse
type: helm
status: {}
```
Read more about creating workspaces [here](../workspaces/creating-workspaces).
# Help and feedback
Source: https://docs.mogenius.com/overview/help-and-feedback
## Support
If you encounter any problems or need quick help, you can always contact us directly.\
❗️ [**Support**](mailto:support@mogenius.com)
## Feedback
You can see what we're building next, submit your feedback, and vote on ideas on our public roadmap.\
💡 [**Roadmap**](https://feedback.mogenius.com/)
## FAQ
mogenius is an internal developer platform that makes running and managing containerized applications on Kubernetes simple and efficient. It is designed to help DevOps reduce support overhead from development teams and to help them focus on core infrastructure tasks. For developers, mogenius enables them to work independantly and to focus on shipping great code.
All you need is a Kubernetes cluster where you can install the mogenius operator. Check out the [quickstart](https://docs.mogenius.com/overview/quickstart">quickstart\,) for detailed first steps. If you want to use mogenius but you don't want to run your own Kubernetes cluster, refer to [managed clusters](https://docs.mogenius.com/cluster-management/managed-clusters).
mogenius works with simple and fixed monthly subscriptions. The pricing depens on the number of clusters and projects, and additional services that you might require. Check out the [available plans](https://mogenius.com/pricing).
Everything that you configure on mogenius can be exported as YAML if you decide to leave mogenius. We want to avoid vendor lock-in and if you feel that mogenius is not adding value anymore you won't be forced to stay.
# How mogenius works
Source: https://docs.mogenius.com/overview/how-mogenius-works
mogenius acts as a layer on top of Kubernetes, integrating seamlessly with your infrastructure and existing development tools. The platform serves teams in three core functions:
* Creating self-service workspaces for developers.
* A single pane of glass to navigate Kubernetes from beginner to expert in a safe way.
* Automating deployments and workload configuration with built-in pipelines and integrations.
## The mogenius operator
mogenius connects to Kubernetes clusters through our operator, which is installed on the cluster using `helm`. It establishes an outbound TCP connection to the mogenius platform. Once connected, the operator populates your workspaces with metrics, status events, logs, and resource updates. It is also capable of deploying applications with built-in pipelines, or by integrating existing pipelines.
## The mogenius platform
The mogenius platform orchestrates multiple clusters and enables you to manage Kubernetes resources, workloads, and deployments through its user interface (UI) and API. Serving as a management layer, the platform facilitates the creation of workspaces for development teams within your organization. It streamlines the entire workflow for creating, managing, scaling, and monitoring container applications on Kubernetes in an automated and developer-friendly manner.
## What makes this powerful?
mogenius is a Kubernetes Manager that can be set up within minutes. Its intuitive developer experience empowers teams to leverage Kubernetes at scale without the need for extensive training, onboarding, or excessive overhead. By abstracting complexity, mogenius follows an operator approach, enabling you to run it on any Kubernetes cluster, including on-premises environments. This flexibility allows the platform to seamlessly adapt to sophisticated infrastructures while avoiding vendor lock-in.
# Plans pricing
Source: https://docs.mogenius.com/overview/plans-pricing
mogenius plans are simple and fixed subscriptions that consist of three major components:
* The number of clusters you are managing.
* The number of users in your organization.
* Support levels, SLAs, or any other additional services.
mogenius does not interfere with your cloud account, so you are charged for resource costs separately by your cloud provider. An exception applies to managed clusters by mogenius, where cloud resources are included in your subscription. Read more about [managed clusters](./../cluster-management/managed-clusters.md).
Compare plans in detail on our [pricing page](https://mogenius.com/pricing) and contact us for an individual quote.
# Quickstart
Source: https://docs.mogenius.com/overview/quickstart
Getting started with mogenius is easy. Here's a walkthrough of the most important steps for connecting your cluster and creating a workspace.
## 1. Sign up
First, [sign up](https://app.mogenius.com/user/registration) for a mogenius account. You can use a social login (GitHub, Gitlab, Google, Microsoft), or your email address.
## 2. Create an organization
Create an organization, which represents the highest level in the mogenius account hierarchy. This allows you to have multiple organizations, each fully isolated with its own access management and list of clusters.
## 3. Connect a Kubernetes cluster
Now, let's move on to the exciting part: connecting to a Kubernetes cluster. Once you have connected your cluster, you will be able to create workspaces for monitoring and navigating your applications, as well as deploying containers to your cluster with the built-in pipeline tools.
### Prerequisites
To successfully complete the next steps, you will need the following:
* 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 minikube, Docker Desktop, or k3s, is also a great option.
* A working installation of `Helm` and `kubectl`
* OR optionally the [mogenius CLI](/cli/installation)
* Kubernetes cluster admin permissions
If you want to explore mogenius before connecting it with your cluster, check out the demo organization in your account. If you don't want to run mogenius with your own Kubernetes cluster, check out our section [Managed clusters](./../cluster-management/managed-clusters.md).
After creating your organization, add a new cluster. Enter a name (this will only be used to display the cluster in mogenius) and proceed to install the operator.
## 4. Install mogenius on the cluster
Before you continue, make sure that you have a running Kubernetes cluster where you have admin access. Next, you will install the mogenius operator on the cluster using `Helm` or [mocli](/cli/overview) to connect your cluster with the mogenius platform.
Copy the `Helm` or `mocli` command. Open a terminal and make sure that your kubecontext is set to the cluster that you want to connect with mogenius. Paste and execute the install command, return to mogenius, and click "I ran the command." The UI will confirm once the operator has established a connection with the mogenius controlplane.
Having trouble connecting the operator? Check out the [troubleshooting section.](../cluster-management/troubleshooting-clusters.md)
Once connected, the operator will check if a [metrics server](https://github.com/kubernetes-sigs/metrics-server) is present on the cluster. If not, it will be installed automatically.
**Done - your cluster is ready! 🥳 You can now create your first workspace.**
## 8. Create a workspace
Head to the Workspaces section in your organization and click **Create workspace**. Select your cluster from the list, and enter a name for your workspace.
Next, select the resources that you want to manage in your workspace. You can select them based on namespaces, or Helm releases from the cluster.
Finally, invite team members and define their roles and permissions. They'll receive an invitation email right afterwards.
## 9. Congratulations - your workspace is ready 🎉
What's next?\
Your dashboard is ready to start monitoring your applications in real-time. Check the status of your resources, monitor events, and browse through logs, metrics, or the resource topology for troubleshooting issues. Want to deploy a new application? Use the built-in pipeline tools to connect a registry, deploy a pipeline starter, or start from scratch with a YAML manifest.
If you need help, please take a look at our Help & Feedback page. You can contact us directly if you run into any problems.
# Creating workspaces
Source: https://docs.mogenius.com/workspaces/creating-workspaces
A workspace allows you to group a set of resources from Kubernetes based on namespaces, Helm releases, or labels. With integrated RBAC, monitoring, workload management, and pipeline integrations, workspaces provide self-service capabilities to any team.
## Adding a new workspace
Once a cluster is connected, you can add a new workspace. In your organization, navigate to **Workspaces** and add a new workspace. There's two steps you need to complete:
1. If you have a cluster with existing workloads, you can import these into a workspace. Select the namespaces, Helm releases, or labels, that you want to include in your workspace. They act as filters, so changes to resources inside these filters will be applied to your workspace automatically. You can also skip this step and start with a blank workspace. You can use the built-in tools to create namespaces, deploy Kubernetes manifests, or containers from a registry.
2. Add users, or select them from your organization. You can define their permissions based on pre-defined groups ([Read more about RBAC](/workspaces/members-and-roles)).
That's it, your workspace dashboard will be ready immediately. The members you invited will receive an email to join the workspace. You can now start monitoring resources on the cluster, troubleshoot issues, or use built-in [pipeline tools](/deploying-applications/overview) to create new deployments.
## Configuring workspaces and users as CRDs
Since workspaces are stored as Custom Resource Definitions (CRD) on your cluster, you can also define them via YAML manifests. This allows you to automate provisioning workspaces und users from pipelines, or during onboarding workflows of team members.
The following CRDs are used for this workflow with APIVersion `mogenius.com/v1alpha1`:
* Workspace
* User
* Grant
### Workspace
`Workspace` is defined like this.
```
apiVersion: mogenius.com/v1alpha1
kind: Workspace
metadata:
creationTimestamp: '2025-03-27T21:06:24Z'
generation: 2
name: exampleworkspace
namespace: mogenius
resourceVersion: '4362774'
uid: b400fefe-7678-4548-bd21-14c8e1781b73
spec:
resources:
- id: gitea # Identifies the namespace that should be added to the workspace
type: namespace
- id: discourse
namespace: discourse
type: helm # Add type: helm if you want to add resources only from a specific Helm release
status: {}
```
### User
Workspace users are managed on the cluster with the CRD `User`.
```
apiVersion: mogenius.com/v1alpha1
kind: User
metadata:
creationTimestamp: '2025-02-10T08:42:11Z'
generation: 1
name: user-12d19670-2b9d-5320-ae2e-cb728fc4f70b
namespace: mogenius
resourceVersion: '1296441'
uid: a30ea67d-d3a8-4be6-8c5d-b8ab45ef57cc
spec:
email: email@example.com # An invitation email will be sent to the user to set up login credentials
firstName: Linus
lastName: Torvalds
status: {}
```
### Grant
With a `Grant` you assign users to workspaces and define their permission within the workspace.
```
apiVersion: mogenius.com/v1alpha1
kind: Grant
metadata:
creationTimestamp: '2025-02-25T13:28:47Z'
generation: 1
name: grant-0e98deb9-5872-4e3d-8417-19031aa1950e
namespace: mogenius
resourceVersion: '2929550'
uid: 223c3854-6b5f-4583-89c1-76b4278df4c0
spec:
grantee: user-12d19670-2b9d-5320-ae2e-cb728fc4f70b # Retrieve this from the name of the User CRD
role: viewer # Can be viewer, editor, or admin
targetName: teamspace # The ID of the workspace where the user will be added
targetType: workspace
status: {}
```
# Integrations
Source: https://docs.mogenius.com/workspaces/integrations
You can enrich the capabilities of your workspace with integrations that connect your Kubernetes resources with data from external tools. This way, mogenius provides a streamlined interface for monitoring and troubleshooting Kubernetes applications.
## GitHub
Use the GitHub integration to add logs and status information from GitHub actions to your Kubernetes deployments. This will populate the **Build log** on your application's detail page as well as adding a **Build status**.
Here's how to set up the integration:
1. Go to the **Integrations** tab in your workspace settings.
2. Click **Connect** to authorize GitHub with your workspace.
3. On the following screens you can sign in with your GitHub account, set the GitHub organization and the integration's permission.
4. Once your integration is set up, go to the **General settings** of your workload. Set the repository that you want to connect with your application. If it has a GitHub actions workflow, the status and logs of your workflows are now available in the mogenius UI.
## Prometheus
mogenius natively integrates with Prometheus, allowing you to monitor custom application metrics directly within the mogenius platform.
How to set it up:
1. Make sure Prometheus is running on your cluster—you can install it via a Helm chart, e.g., from the [Bitnami Helm repository](https://charts.bitnami.com/) (see [this guide](../deploying-applications/helm-charts) for help).
2. Once Prometheus is running on your cluster, mogenius will detect it automatically.
3. Open your deployment in mogenius, go to the **Metrics** tab, and click **Add Prometheus Metrics**.
4. Select a PromQL query from the dropdown, enter a display name, and click **Create**.
5. A chart will appear on your metrics page, visualizing the selected Prometheus data.
### Additional Info
* mogenius applies default [step values](https://prometheus.io/docs/prometheus/latest/querying/basics/) for chart resolution based on your selected time range.
* You can manually adjust the step value to control the resolution of the displayed data.
All metric chart configurations are **persisted on your cluster**, meaning they are shared across all users within your workspace who access the same deployment.
## ArgoCD
With the ArgoCD integration you can monitor your GitOps workflow right within mogenius. Once enabled, several components will be added to your Workspaces:
* Application status: Shows sync status and errors from ArgoCD for a selected resource.
* Application overview: On the page **GitOps applications** get a list of applications, see included resources, and monitor the sync status.
* GitOps log: On resources managed by ArgoCD you'll get a log with a history of commits and pull requests on the ArgoCD application.
Check our [GitOps documentation](/cluster-management/gitops/overview) for more information and setup instructions.
## Gitlab
Coming soon 🚧
# Members and roles
Source: https://docs.mogenius.com/workspaces/members-and-roles
There's two levels of access management in mogenius: Organization and workspace level. On each level there's a simple set of pre-configured roles that you can use to control permissions within your teams.
## Organization
People joining your organization can have either admin, editor, or viewer role. You can invite members to join your organization from the Members page in your organization.
| Permissions | Admin | Editor | Viewer |
| - | - | - | - |
| Organization | Create, Edit, Delete | View | View |
| Clusters | Add, Edit, Delete | - | - |
| Workspaces | View all workspaces | View by invite | View by invite |
| Templates | Create, Edit, Delete | Create, Edit, Delete | View |
| Members | Add, Edit, Delete | View | View |
| Settings | Edit | View | View |
## Workspace
In a workspace you can invite users to provide them with access to Kubernetes resources. Workspaces rely on Kubernetes RBAC which means that the users and groups you define in the mogenius platform are created and updated on the Kubernetes cluster. You can invite and manage members on the **Team** tab in your workspace settings. There's three pre-defined groups that you can use.
| Permissions | Admin | Editor | Viewer |
| - | - | - | - |
| Workspace | Edit, Delete | View | View |
| Resources | Create, Edit, Delete | Create, Edit, Delete | View |
| Start/stop/restart workloads | ✅ | ✅ | - |
| Pipeline tools | ✅ | ✅ | - |
| Shell | ✅ | ✅ | - |
| Volumes | Create, Edit, Delete | Create, Edit, Delete | View |
| Integrations | Create, Edit, Delete | Create, Edit, Delete | View |
| Team members | Add, Edit, Delete | Add, Edit, Delete | View |
## Access via identity-provider groups
Besides inviting members individually, you can grant workspace access through identity-provider groups. Using a [GroupGrant](/cluster-management/single-sign-on#group-based-workspace-access), an SSO group is mapped to a workspace with a role (viewer, editor, or admin).
Members who receive access this way appear in the member list marked as **SSO group**. Their role is managed in the identity provider / GroupGrant, not per user in mogenius. See [Single Sign-On](/cluster-management/single-sign-on) for setup.
# Mogenius API
Source: https://docs.mogenius.com/workspaces/mogenius-API
The mogenius REST API allows you to manage your mogenius workspaces and resources in scripts, automations, and third party tools.
## Creating an API key
To authenticate with the mogenius API, first create an API key. You can do this on cluster level, or workspace level. Go to the section **API key** in the respective settings and add a new key by filling out the form:
* Set a name to identify the API key later.
* Define the expiration date.
* Set the scope based on the [pre-defined groups](./members-and-roles.md).
## Set Image
You can use the API to perform a `set image` for your deployments via the mogenius operator.
```
curl --location 'https://platform-api.mogenius.com/workspace/workload/set-image' \
--header 'Authorization: bearer YOUR_WORKSPACE_API_KEY' \
--data '{
"kind": "Deployment",
"namespace": "YOUR_NAMESPACE",
"resourceName": "DEPLOYMENT_NAME",
"containerName": "CONTAINER_NAME",
"image": "CONTAINER_IMAGE"
}'
```
## Helm Upgrade
You can use the API to perform a `Helm upgrade` on a Helm release via the mogenius operator. For this to work, the Helm repository must be installed on the cluster first. The variable `REPO_NAME` in the request below refers to this Helm repository.
The Helm upgrade can be performed with an API key on workspace level, or cluster level.
```Workspace Workspace theme={null}
curl --location --request PATCH 'https://platform-api.mogenius.com/workspace/helm/release/upgrade' \
--header 'Authorization: bearer YOUR_WORKSPACE_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"namespace": "YOUR_NAMESPACE",
"chart": "CHART_NAME", // REPO_NAME/CHART_NAME
"release": "RELEASE_NAME",
"version": "UPGRADE_TO_VERSION",
"values": {
"key1":"value1" // can also be a yaml string
},
"dryRun": false
}'
```
```Cluster Cluster theme={null}
curl --location --request PATCH 'https://platform-api.mogenius.com/helm/admin/YOUR_CLUSTER_ID/release/upgrade' \
--header 'Authorization: bearer YOUR_CLUSTER_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"namespace": "YOUR_NAMESPACE",
"chart": "CHART_NAME", // REPO_NAME/CHART_NAME
"release": "RELEASE_NAME",
"version": "UPGRADE_TO_VERSION",
"values": {
"key1":"value1" // can also be a yaml string
},
"dryRun": false
}'
```
## Deploy a Blueprint
[Blueprints](/deploying-applications/blueprints) are pre-configured Helm charts. Deploying one via the API is a two-step flow:
1. Read the blueprint to get its chart coordinates and default values.
2. Install that chart with the Helm install endpoint.
The target cluster is selected with the `cluster-id` header. Use a cluster-level API key (or a workspace-level key with editor permissions); installing requires editor/admin rights on the cluster.
### 1. List blueprints
```
// HEADER
Authorization: Bearer YOUR_CLUSTER_API_KEY
cluster-id: YOUR_CLUSTER_ID
GET https://platform-api.mogenius.com/helm/blueprints
```
Returns the catalog with each blueprint's `id`, `displayName`, `description`, `category`, and `tags`.
### 2. Get a blueprint's details
```
// HEADER
Authorization: Bearer YOUR_CLUSTER_API_KEY
cluster-id: YOUR_CLUSTER_ID
GET https://platform-api.mogenius.com/helm/blueprints/BLUEPRINT_ID
```
The response includes the blueprint's Helm `repository` and `chart` (name and version) plus its default install target (`namespace`, `release`) and default `values`. Use these to build the install request.
### 3. Install the chart
Install the blueprint's chart as a standard Helm release. For repository-based charts, the Helm repository must be added to the cluster first (the `chart` value has the form `REPO_NAME/CHART_NAME`).
```
// HEADER
Authorization: Bearer YOUR_CLUSTER_API_KEY
cluster-id: YOUR_CLUSTER_ID
Content-Type: application/json
POST https://platform-api.mogenius.com/helm/chart/install
```
```curl expandable theme={null}
// BODY
{
"namespace": "YOUR_NAMESPACE",
"chart": "REPO_NAME/CHART_NAME", // from the blueprint's chart
"release": "RELEASE_NAME",
"version": "CHART_VERSION",
"values": "key1: value1", // YAML string with your value overrides
"dryRun": false
}
```
For charts hosted in an OCI registry, use the OCI install endpoint instead:
```
// HEADER
Authorization: Bearer YOUR_CLUSTER_API_KEY
cluster-id: YOUR_CLUSTER_ID
Content-Type: application/json
POST https://platform-api.mogenius.com/helm/chart/oci/install
```
```curl expandable theme={null}
// BODY
{
"ociChartUrl": "oci://REGISTRY/CHART",
"namespace": "YOUR_NAMESPACE",
"release": "RELEASE_NAME",
"version": "CHART_VERSION", // optional
"values": "key1: value1", // optional YAML string
"dryRun": false
}
```
Once installed, the blueprint becomes a standard Helm release that you can manage through the [Helm upgrade](#helm-upgrade) endpoint or the [Helm Charts](/deploying-applications/helm-charts) interface.
## Manage Ports & Hostnames
You can `get`, `add`, and `delete` ports and hostnames from deployments, just like from the UI. mogenius will automatically create or update the corresponding service and ingress resources.
Here's example requests with configuration options on each parameter. Make sure to remove the comments when copying the example.
### GET Ports & Domains
Returns a JSON with all Service and Ingress configurations related to a Controller.
```
// HEADER
Authorization: Bearer [your token]
GET https://platform-api.mogenius.com/resource/workload/ports-domains?kind=Deployment&plural=deployments&apiVersion=apps/v1&namespaced=true&resourceName=my-container&namespace=my-namespace
```
### PATCH Ports & Domains
Adds or deletes Service and Ingress configurations.
```
// HEADER
Authorization: Bearer [your token]
PATCH https://platform-api.mogenius.com/resource/workload/ports-domains
```
```curl expandable theme={null}
// BODY
{
"kind": "Deployment",
"plural": "deployments",
"apiVersion": "apps/v1",
"namespaced": true,
"resourceName": "my-deployment", // deployment name
"namespace": "my-namespace",
"service": { // service
// "resourceName": "test-service", // optional
"ports": [
{
"action": "add", // optional -> add or delete
"protocol": "TCP", // TCP/UDP
"targetPort": 8080,
"port": 8080,
"ingress": { // ingress
// "resourceName": "test-ingress", // optional
"domains": [
{
"action": "add", // optional -> add or delete
"tls": true, // true or false
"domain": "yourdomain.com",
"tlsSecret": "" // optional, specify secret name if a custom TLS secret should be used
}
]
}
}
]
}
}
```
# Resources
Source: https://docs.mogenius.com/workspaces/resources
On the **Resources** page, you can explore all active Kubernetes resources across your current workspace. The **Resource Manager** offers a powerful interface to help you quickly identify, monitor, and interact with these resources.
**Key capabilities include:**
* **Search and Filtering**: Narrow down resources using filters by resource kind (e.g., Pods, Deployments, Services, Secrets), status, namespace, or labels. This allows for efficient troubleshooting and resource management in large-scale environments.
* **Resource Actions**: Perform operational tasks such as restarting Pods, scaling Deployments, or deleting individual resources — all from the web UI, without requiring kubectl or terminal access.
* **YAML Access and Editing**: View live YAML manifests for each resource with syntax highlighting and the option to copy, inspect, or modify definitions. This supports advanced debugging and infrastructure as code practices.
* **Form-based Editing**: For custom resources that have a [Custom Resource Form](/cluster-management/ui-configs) configured, a **Details** tab renders a structured form with labelled inputs and validation instead of raw YAML.
* **Topology View**: Visualize dependencies and relationships between resources with the interactive **Topology Graph**. Understand how Deployments relate to Services, Ingress, ConfigMaps, and other components at a glance — especially useful for debugging microservices and validating Helm chart deployments.
* **Event Streams**: For supported resource types like Pods and Deployments, view real-time Kubernetes events and logs directly within the panel. This helps developers and SREs to investigate incidents without accessing the underlying cluster.
* **RBAC-Aware Access**: Actions and visibility are scoped by **Workspace RBAC**, ensuring developers, platform engineers, and operations teams only see and interact with resources they’re authorized to manage.
* **Tunnels**: For Services, create secure TCP tunnels to access internal services from your local machine without direct cluster access. See [Tunnels](/workspaces/tunnels) for details.
# Service status and errors
Source: https://docs.mogenius.com/workspaces/service-status-and-errors
Within your workspace there are several levels of monitoring that you can rely on. Data from the cluster is polled in real-time to ensure fast troubleshooting and a smooth experience.
Monitoring and logging are built-in features of the mogenius platform. No additional setup is required to access status, metrics, logs, and events for your deployments.
## Status
The status module provides a real-time view into cluster resources. You'll find it on the **workspace dashboard** and on each **deployment detail page**.
If available, the status module automatically shows related status information from dependent resources. For example, a Deployment also displays the status of its ReplicaSets and Pods, providing all relevant information in one place. Hover over the status module to view recent Kubernetes events.
Common statuses you may encounter:
| Status | Description |
| - | - |
| **Running** | All pods are running and healthy. |
| **Pending** | Pods are waiting to be scheduled, often due to insufficient resources or pending image pulls. |
| **CrashLoopBackOff** | A container is repeatedly crashing and Kubernetes is waiting before restarting it. Check the logs for error details. |
| **ImagePullBackOff** | Kubernetes cannot pull the container image. Verify the image URL and image pull secret. |
| **Error** | A general error state. Hover over the status or check events for details. |
Use the [topology view](/workspaces/resources) on the detail page to understand dependencies between resources (Deployments, Services, Ingress, ConfigMaps) and trace issues across related components.
## Metrics
mogenius collects metrics using its operator and the Kubernetes metrics server. Data for **CPU**, **RAM**, and **traffic** usage is presented in charts on the workspace dashboard and on each deployment detail page.
On the workspace dashboard, charts show aggregated resource consumption across all deployments. You can filter by time range to identify trends and spikes. Hover over the charts to see a **per-pod breakdown** showing each pod's individual share of resource consumption.
On the deployment detail page, metrics are scoped to that specific application, allowing you to monitor resource usage at the application level.
### Prometheus integration
For custom application metrics, mogenius integrates natively with Prometheus. Once Prometheus is running on your cluster, you can add custom PromQL queries to visualize application-specific metrics directly on the deployment detail page. See [Integrations](/workspaces/integrations) for setup details.
## Logs
Logs are streamed in real-time from pods and jobs and are available on each deployment detail page.
To access logs:
1. Open the detail page of your deployment in the workspace.
2. Navigate to the **Logs** section.
3. Use the search and filter tools to find specific log entries.
If a pod restarted, the **previous log** is automatically inserted above the current log, so you can review what happened before the restart without needing to switch between log sources.
Logs are streamed live, so you can monitor application output as it happens — useful for debugging startup issues, tracking request flows, or watching for errors in real time.
## Events
On the detail page of a deployment, events are collected from multiple related resources into a single timeline. This aggregated view includes events from the Deployment, its ReplicaSets, and individual Pods, so you don't need to inspect each resource separately.
Common events you'll see include:
* **Scheduling**: Pod assigned to a node.
* **Image pulls**: Container image being pulled from the registry.
* **Scaling**: Replica count changes (manual or via autoscaler).
* **Health check failures**: Liveness or readiness probe failures that trigger restarts or endpoint removal.
* **Resource warnings**: Events related to resource limits, OOM kills, or evictions.
## Build logs
If you have the [GitHub integration](/workspaces/integrations) enabled, your deployment detail page also shows **build status** and **build logs** from GitHub Actions workflows. This lets you track CI/CD pipeline progress alongside your deployment status without leaving mogenius.
## Integrations
You can extend monitoring capabilities with integrations that connect your Kubernetes resources with data from external tools. Read more about available [integrations](/workspaces/integrations), including GitHub, Prometheus, and ArgoCD.
# Storage
Source: https://docs.mogenius.com/workspaces/storage
mogenius has a built-in storage solution based on NFS storage. This allows you to persist applications and to store assets and data from your applications. The solution is designed to achieve persistency for your services without the overhead of managing a storage solution. This setup is not recommended for heavy workloads, or large production setups. In this case we recommend to implement your own storage solution depending on your requirements.
To use mogenius NFS just open the **Storage** section in your workspace and create a volume. This will deploy an NFS server on your Kubernetes cluster. The NFS supports ReadWriteMany which allows you to access a volume from each pod in the namespace.
Now that you've created a volume you can start using storage with your applications. In your application settings go to **Volume mounts** and add a new volume. Define or create a folder inside your volume and enter the path in your container that should be mounted.
In your storage browser you can then see and manage all the application data that was stored.
# Tunnels
Source: https://docs.mogenius.com/workspaces/tunnels
Access Kubernetes Services securely through TCP tunnels without direct cluster access
Tunnels allow you to establish secure TCP connections to Kubernetes Services running in your clusters — without requiring direct cluster access or a local kubeconfig. All connections are routed through the mogenius platform with full RBAC enforcement and audit logging.
## Use Cases
* **Internal tools**: Securely access admin panels, monitoring dashboards, or management interfaces without exposing them publicly
* **Database access**: Connect your local database client to a PostgreSQL, MySQL, or Redis service running in Kubernetes
* **Internal APIs**: Test internal microservices from your development machine
* **Debugging**: Access services that aren't exposed via Ingress for troubleshooting
* **Development**: Connect local tools to staging or production services securely
## How It Works
When you create a Tunnel, mogenius establishes a secure WebSocket connection between your browser (or CLI) and the target service in your cluster:
```
Your Machine → mogenius Platform → Operator → Kubernetes Service
```
The connection is authenticated through your mogenius account and authorized based on your workspace and cluster permissions. Each tunnel session receives a unique URL that you can use to access the service.
## Creating Tunnels via UI
### From the Tunnel Overview
The Tunnel overview page provides a central place to create and manage all your tunnels:
1. Navigate to **Tunnels** in the sidebar (cluster or workspace level)
2. Click **Create Tunnel**
3. Select the target service from the dropdown
4. Choose a session duration:
* **30 minutes** (default)
* **4 hours**
* **24 hours**
* **Unlimited**
5. Click **Create** to start the tunnel
The tunnel URL follows the pattern `[session-id].platform-api.mogenius.com` and provides direct access to your service.
### From the Resource Browser
You can also create tunnels directly from the Resource Browser:
1. Navigate to **Resources** in your workspace
2. Filter by **Kind: Service** to see available services
3. Click the **Tunnel** button on the service you want to access
4. A new tunnel session opens with a unique URL
### Managing Active Tunnels
The Tunnel overview displays all active tunnel sessions with:
* **Service name** and namespace
* **Tunnel URL** for accessing the service
* **Session duration** and time remaining
* **Status** indicator
Use the context menu on each tunnel to:
* **Open in new tab** — Launch the tunnel URL in a new browser tab
* **Copy URL** — Copy the tunnel URL to your clipboard
* **Delete** — Terminate the tunnel session
Tunnels are automatically closed after the configured session duration expires or after 30 minutes of inactivity.
## Creating Tunnels via CLI
The mogenius CLI (`mocli`) provides a `port-forward` command for creating tunnels directly from your terminal. This is ideal for connecting local tools and scripts to Kubernetes services.
### Prerequisites
* [Install mocli](/cli/installation) and log in with `mocli login`
* Ensure you have at least **Editor** permissions for the target workspace
### Terminal UI
The CLI includes an interactive terminal UI for creating tunnels. Launch it by running:
```bash theme={null}
mocli
```
To create a tunnel from the Terminal UI:
1. Navigate to the target **Pod**, **Deployment**, or **Service**
2. Press **p** to open the port-forward configuration
3. Configure the local and remote port mapping
4. The tunnel starts and remains active while the TUI is running
### Basic Usage
```bash theme={null}
mocli port-forward --namespace --service --port :
```
**Parameters:**
* `--namespace` — Kubernetes namespace where the service runs
* `--service` — Name of the Kubernetes Service to tunnel to
* `--port` — Port mapping in `local:remote` format (e.g., `8080:80`)
### Examples
**Connect to a PostgreSQL database:**
```bash theme={null}
mocli port-forward --namespace production --service postgres --port 5432:5432
```
Then connect with your database client to `localhost:5432`.
**Access an internal API:**
```bash theme={null}
mocli port-forward --namespace staging --service api-server --port 8080:8080
```
The API is now available at `http://localhost:8080`.
**Tunnel to a specific Deployment:**
```bash theme={null}
mocli port-forward --namespace staging --deployment worker --port 3000:3000
```
**Tunnel to a specific Pod:**
```bash theme={null}
mocli port-forward --namespace default --pod my-pod-abc123 --port 9090:9090
```
### Supported Target Types
The CLI supports tunneling to different Kubernetes resource types:
| Flag | Target Type | Description |
| - | - | - |
| `--service` | Service | Routes to any healthy pod backing the service |
| `--deployment` | Deployment | Routes to a pod from the deployment's replica set |
| `--pod` | Pod | Routes directly to a specific pod |
### Session Behavior
* The tunnel remains active as long as the CLI process is running
* Press `Ctrl+C` to terminate the tunnel
* The CLI maintains a keepalive ping to prevent timeouts
* If the connection drops, the CLI will attempt to reconnect automatically
## Permissions
Creating tunnels requires **Editor** or higher permissions in the workspace:
| Role | Can Create Tunnels | Can View Active Tunnels |
| - | - | - |
| Viewer | No | No |
| Editor | Yes | Yes |
| Admin | Yes | Yes (all tunnels) |
Tunnels provide direct TCP access to services in your cluster. Ensure you only create tunnels to services you're authorized to access, and avoid sharing tunnel URLs with unauthorized users.
## Troubleshooting
### Tunnel fails to connect
* Verify the target service exists and has healthy endpoints
* Check that you have sufficient permissions for the namespace
* Ensure the mogenius operator is running in the cluster
### Connection drops frequently
* Check your network connection stability
* For CLI tunnels, ensure the terminal session remains active
* Consider using a longer session duration for UI tunnels
### Port already in use (CLI)
If the local port is already in use, the CLI will display an error. Either:
* Stop the process using the port, or
* Choose a different local port (e.g., `--port 5433:5432`)
# Workspace Dashboard
Source: https://docs.mogenius.com/workspaces/workspace-dashboard
The workspace overview page — what it shows, and how administrators tailor it per workspace with custom dashboards.
![Workspace Dashboard Docu Pn]()
The workspace dashboard provides a streamlined overview of your workspace resources and any important events that apply to your applications on Kubernetes. In short, here's what you can do on the dashboard:
* Monitor resource consumption and filter by time ranges.
* See team activity on the workspace.
* Identify issues and events from Kubernetes workloads.
From here, you can dive into the [resources](/workspaces/resources) of your workspace for further troubleshooting.
## Customizing workspace dashboards
The layout of the workspace dashboard is not fixed. Cluster administrators can define **custom dashboards** that control which sections appear and add tailored resource tables — so each team can get a landing view that fits how they work. A single dashboard can be shared across multiple workspaces.
Workspaces that aren't assigned a custom dashboard use the built-in **default dashboard**, which shows all standard sections.
### Configuring a dashboard
Custom dashboards are managed by cluster administrators.
1. Open your **Cluster** and go to **Settings → Workspace Dashboards**.
2. Edit the default dashboard, or create a new named dashboard.
3. Toggle the built-in sections and add resource tables (see below).
4. Assign the dashboard to one or more workspaces. A live preview shows the resulting layout as you edit.
### Built-in sections
Each of these standard sections can be turned on or off:
* **Dashboard header** — the workspace summary at the top of the page.
* **Capacities** — the resource-consumption tile.
* **Agents** — the banner surfacing AI agent findings and proposals for the workspace.
* **Members** — the workspace members tile.
* **Resource overview** — the standard overview of workspace resources.
### Resource tables
Below the built-in sections you can add any number of **resource tables**. Each table has a heading and lists the Kubernetes resource kinds you choose (for example Deployments, StatefulSets, or a specific custom resource). Tables render in the order you arrange them, letting you put the resources a team cares about front and center.
### Assigning dashboards to workspaces
A workspace can be assigned to at most one dashboard. Assigning a workspace to a custom dashboard immediately changes what its members see on the Dashboard tab. Removing the assignment — or deleting the dashboard — reverts the workspace to the default dashboard.
### Permissions
Any workspace member with view access sees the dashboard that applies to their workspace. Creating and editing dashboards requires cluster administrator permissions.