https://github.com/mogenius/mogenius-operator
mogenius-operator is a Go (>=1.25) service that coordinates cluster resources, patterns, metrics collection, and auxiliary runtime capabilities for the mogenius platform.
https://github.com/mogenius/mogenius-operator
cloud golang helm-charts kubernetes operator
Last synced: about 2 months ago
JSON representation
mogenius-operator is a Go (>=1.25) service that coordinates cluster resources, patterns, metrics collection, and auxiliary runtime capabilities for the mogenius platform.
- Host: GitHub
- URL: https://github.com/mogenius/mogenius-operator
- Owner: mogenius
- License: mit
- Created: 2022-12-20T20:43:37.000Z (over 3 years ago)
- Default Branch: develop
- Last Pushed: 2026-05-11T10:56:56.000Z (about 2 months ago)
- Last Synced: 2026-05-11T11:23:11.999Z (about 2 months ago)
- Topics: cloud, golang, helm-charts, kubernetes, operator
- Language: Go
- Homepage: https://mogenius.com
- Size: 36.9 MB
- Stars: 10
- Watchers: 1
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Codeowners: CODEOWNERS
Awesome Lists containing this project
README
mogenius-operator
Kubernetes cluster manager & runtime control-plane components for the mogenius platform.
---
[](https://artifacthub.io/packages/helm/mogenius/mogenius-operator)
[](go.mod)
[](https://github.com/mogenius/mogenius-operator/releases)
[](LICENSE)
[](https://github.com/mogenius/mogenius-operator/actions)
Go (≥1.25) operator that manages CRDs, Helm deployments, metrics collection, WebSocket communication, and IaC for the mogenius platform.
---
## Architecture
Modular packages under `src/`:
- `cmd/` – CLI entry points (cluster, nodemetrics, system, config).
- `core/` – lifecycle, reconcilers, socket API, node metrics collector.
- `kubernetes/` – resource CRUD, backups, issuers, cronjobs, etc.
- `crds/` – Custom Resource Definitions (Workspace, User, Grant).
- `k8sclient/` – Kubernetes client provider & kubeconfig.
- `valkeyclient/` – Valkey/Redis caching & time-series helpers.
- `websocket/` – WebSocket multiplexing with auto-reconnect.
- `xterm/` – Terminal/shell access over WebSocket.
- `helm/` – Helm SDK integration & chart management.
- `iacmanager/` – Infrastructure-as-Code orchestration.
- `networkmonitor/` – Network traffic collection (eBPF via snoopy, or procdev).
- `containerenumerator/` – Container PID discovery via cgroup inspection.
- `cpumonitor/`, `podstatscollector/`, `rammonitor/` – CPU, pod & RAM telemetry.
- `config/` – Immutable config with validation & change callbacks.
- `logging/` – Structured slog with custom handlers & secret masking.
- `secrets/`, `store/`, `watcher/`, `shutdown/`, `services/`, `utils/`, `assert/`, `version/` – supporting packages.
Generated artifacts: `generated/spec.yaml` (pattern spec) and `generated/client.ts` (TypeScript bindings).
---
## Local Development
Prerequisites: Go 1.25+, [`just`](https://github.com/casey/just), access to a Kubernetes cluster with the `mogenius` namespace.
```sh
# 1. Create .env (see Configuration below)
# 2. Optionally scale down in-cluster deployment to avoid conflicts
just scale-down
# 3. Build & run
just build
just run
# Restore in-cluster deployment afterward
just scale-up
```
Key tasks:
```sh
just build # compile + regenerate spec.yaml & client.ts
just run # run operator locally
just run-node-metrics # run node metrics DaemonSet mode locally
just check # generate + lint + unit tests
just test-unit
just test-integration
just golangci-lint
just generate # run go generate (CRD deepcopy)
just scale-down / scale-up
```
---
## Configuration
Create a `.env` in the repo root:
```sh
MO_API_KEY= # From operator secret (mogenius/mogenius)
MO_CLUSTER_NAME= # Cluster identifier
MO_CLUSTER_MFA_ID= # MFA/instance id
MO_API_SERVER= # Platform API WebSocket URL
MO_EVENT_SERVER= # Platform Event WebSocket URL
MO_VALKEY_ADDR= # Valkey/Redis address
```
Load (bash/zsh):
```sh
if [[ -f .env ]]; then export $(grep -v '^#' .env | xargs); fi
```
### All Environment Variables
| Variable | Default | Description |
|---|---|---|
| `MO_API_KEY` | — | API key to access the mogenius platform (**required**, secret) |
| `MO_CLUSTER_NAME` | — | Name of the Kubernetes cluster (**required**) |
| `MO_CLUSTER_MFA_ID` | — | NanoId of the cluster for MFA purpose (**required**, secret) |
| `MO_API_SERVER` | — | URL of the platform API WebSocket server (**required**) |
| `MO_API_SERVER_CLIENTS` | `1` | Number of parallel WebSocket connections to the API server |
| `MO_EVENT_SERVER` | — | URL of the platform event WebSocket server (**required**) |
| `MO_SKIP_TLS_VERIFICATION` | `false` | Skip TLS verification for API and Event Server |
| `MO_VALKEY_ADDR` | — | Address (`host:port`) of the Valkey/Redis server (**required**) |
| `MO_VALKEY_PASSWORD` | — | Password for the Valkey/Redis server |
| `MO_HTTP_ADDR` | `:1337` | Listen address for the operator HTTP API |
| `MO_OWN_NAMESPACE` | `mogenius` | Namespace the mogenius platform is installed in |
| `OWN_NODE_NAME` | — | Node name the application is running on (set by DaemonSet) |
| `OWN_DEPLOYMENT_NAME` | `mogenius-operator` | Deployment name the application is running in |
| `CLUSTER_DOMAIN` | `cluster.local` | Internal cluster domain |
| `MO_HELM_DATA_PATH` | `/helm-data` | Path to Helm data directory |
| `MO_GIT_USER_NAME` | `mogenius git-user` | Git username for IaC operations |
| `MO_GIT_USER_EMAIL` | `git@mogenius.com` | Git email for IaC operations |
| `MO_AUDIT_LOG_LIMIT` | `1000` | Maximum number of audit log entries to persist |
| `MO_ENABLE_POD_STATS_COLLECTOR` | `true` | Enable collection of pod CPU/memory stats |
| `MO_ENABLE_TRAFFIC_COLLECTOR` | `false` | Enable collection of network traffic stats |
| `MO_SNOOPY_IMPLEMENTATION` | `auto` | Network traffic backend: `auto`, `snoopy` (eBPF), or `procdev` |
| `MO_HOST_PROC_PATH` | `/proc` | Mount path of the host `/proc` filesystem (DaemonSet uses `/hostproc`) |
| `MO_LOG_LEVEL` | `info` | Log level: `mo`, `debug`, `info`, `warn`, or `error` |
| `MO_LOG_FILTER` | — | Comma-separated list of components to enable logs for (empty = all) |
| `MO_ALLOW_COUNTRY_CHECK` | `true` | Allow the operator to determine its location country via IP lookup |
| `MO_PPROF` | `false` | Expose Go pprof profiling endpoints at `/debug/pprof/` (set to `true` for debugging) |
| `KUBERNETES_DEBUG` | `false` | Enable Kubernetes SDK debug output |
List all config options at runtime: `go run -trimpath src/main.go config`
---
## Docker (local image)
```sh
docker build -t localk8smanager \
--build-arg GOOS=linux \
--build-arg GOARCH=arm64 \
--build-arg BUILD_TIMESTAMP="$(date -Iseconds)" \
--build-arg COMMIT_HASH="$(git rev-parse --short HEAD || echo XXX)" \
--build-arg GIT_BRANCH=local-development \
--build-arg VERSION="dev-local" \
-f Dockerfile .
```
To use the local image, patch the deployment to `image: localk8smanager:latest` with `imagePullPolicy: Never`, then restart.
---
## Helm
Install via OCI:
```sh
helm -n mogenius upgrade --install mogenius-platform \
oci://ghcr.io/mogenius/helm-charts/mogenius-operator \
--create-namespace \
--set global.cluster_name="" \
--set global.api_key=""
```
Or via Helm repo:
```sh
helm repo add mo-public https://helm.mogenius.com/public
helm repo update
helm upgrade --install mogenius-platform mo-public/mogenius-operator \
--namespace mogenius --create-namespace \
--set global.cluster_name="" \
--set global.api_key=""
```
Upgrade: `helm repo update && helm upgrade mogenius-platform mo-public/mogenius-operator`
Uninstall: `helm uninstall mogenius-platform`
---
## Runtime Image
The operator uses a minimal `scratch`-based image containing only:
- `mogenius-operator` binary (statically linked, `CGO_ENABLED=0`)
- `mogenius-snoopy` binary (Rust + musl, statically linked)
- `nsenter` from Alpine + musl dynamic linker (required for snoopy network namespace entry)
- CA certificates (for TLS/WSS connections)
There is no shell or OS tooling in the image. Use `kubectl debug` or `hostPID: true` pods for runtime inspection.
---
## Profiling
To profile memory usage, enable pprof temporarily:
```sh
kubectl set env deployment/mogenius-operator -n mogenius MO_PPROF=true
kubectl port-forward -n mogenius deployment/mogenius-operator 1337:1337
# Heap profile:
go tool pprof http://localhost:1337/debug/pprof/heap
# Browser UI:
open http://localhost:1337/debug/pprof/
```
Disable afterward: `kubectl set env deployment/mogenius-operator -n mogenius MO_PPROF-`
---
## Troubleshooting
- Scale down in-cluster deployment before running locally: `just scale-down`.
- Regenerate patterns after structural changes: `just build`.
- Auth issues: verify `.env` secrets match the `mogenius/mogenius` operator secret.
- Stale dependencies: `go clean -modcache && go mod tidy`.