{"id":33896443,"url":"https://github.com/mogenius/mogenius-operator","last_synced_at":"2026-05-18T12:12:40.292Z","repository":{"id":325310613,"uuid":"580547632","full_name":"mogenius/mogenius-operator","owner":"mogenius","description":"mogenius-operator is a Go (\u003e=1.25) service that coordinates cluster resources, patterns, metrics collection, and auxiliary runtime capabilities for the mogenius platform.","archived":false,"fork":false,"pushed_at":"2026-05-11T10:56:56.000Z","size":38677,"stargazers_count":10,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"develop","last_synced_at":"2026-05-11T11:23:11.999Z","etag":null,"topics":["cloud","golang","helm-charts","kubernetes","operator"],"latest_commit_sha":null,"homepage":"https://mogenius.com","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mogenius.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-12-20T20:43:37.000Z","updated_at":"2026-05-11T09:18:51.000Z","dependencies_parsed_at":"2026-04-01T19:04:16.371Z","dependency_job_id":null,"html_url":"https://github.com/mogenius/mogenius-operator","commit_stats":null,"previous_names":["mogenius/mogenius-operator"],"tags_count":1844,"template":false,"template_full_name":null,"purl":"pkg:github/mogenius/mogenius-operator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mogenius%2Fmogenius-operator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mogenius%2Fmogenius-operator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mogenius%2Fmogenius-operator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mogenius%2Fmogenius-operator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mogenius","download_url":"https://codeload.github.com/mogenius/mogenius-operator/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mogenius%2Fmogenius-operator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32963191,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-12T23:30:32.555Z","status":"ssl_error","status_checked_at":"2026-05-12T23:30:18.191Z","response_time":102,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cloud","golang","helm-charts","kubernetes","operator"],"created_at":"2025-12-11T17:02:55.570Z","updated_at":"2026-05-13T01:07:46.855Z","avatar_url":"https://github.com/mogenius.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://imagedelivery.net/T7YEW5IAgZJ0dY4-LDTpyQ/3ae4fcf0-289c-48d2-3323-d2c5bc932300/detail\" alt=\"mogenius\" width=\"140\"/\u003e\n\u003c/p\u003e\n\u003ch1 align=\"center\"\u003emogenius-operator\u003c/h1\u003e\n\u003cp align=\"center\"\u003eKubernetes cluster manager \u0026 runtime control-plane components for the \u003ca href=\"https://mogenius.com\" target=\"_blank\"\u003emogenius\u003c/a\u003e platform.\u003c/p\u003e\n\n---\n\n[![Artifact Hub](https://img.shields.io/endpoint?url=https://artifacthub.io/badge/repository/mogenius)](https://artifacthub.io/packages/helm/mogenius/mogenius-operator)\n[![Go Version](https://img.shields.io/github/go-mod/go-version/mogenius/mogenius-operator)](go.mod)\n[![Release](https://img.shields.io/github/v/release/mogenius/mogenius-operator)](https://github.com/mogenius/mogenius-operator/releases)\n[![License](https://img.shields.io/github/license/mogenius/mogenius-operator)](LICENSE)\n[![CI](https://img.shields.io/github/actions/workflow/status/mogenius/mogenius-operator/main.yml?label=CI)](https://github.com/mogenius/mogenius-operator/actions)\n\nGo (≥1.25) operator that manages CRDs, Helm deployments, metrics collection, WebSocket communication, and IaC for the mogenius platform.\n\n---\n\n## Architecture\n\nModular packages under `src/`:\n\n- `cmd/` – CLI entry points (cluster, nodemetrics, system, config).\n- `core/` – lifecycle, reconcilers, socket API, node metrics collector.\n- `kubernetes/` – resource CRUD, backups, issuers, cronjobs, etc.\n- `crds/` – Custom Resource Definitions (Workspace, User, Grant).\n- `k8sclient/` – Kubernetes client provider \u0026 kubeconfig.\n- `valkeyclient/` – Valkey/Redis caching \u0026 time-series helpers.\n- `websocket/` – WebSocket multiplexing with auto-reconnect.\n- `xterm/` – Terminal/shell access over WebSocket.\n- `helm/` – Helm SDK integration \u0026 chart management.\n- `iacmanager/` – Infrastructure-as-Code orchestration.\n- `networkmonitor/` – Network traffic collection (eBPF via snoopy, or procdev).\n- `containerenumerator/` – Container PID discovery via cgroup inspection.\n- `cpumonitor/`, `podstatscollector/`, `rammonitor/` – CPU, pod \u0026 RAM telemetry.\n- `config/` – Immutable config with validation \u0026 change callbacks.\n- `logging/` – Structured slog with custom handlers \u0026 secret masking.\n- `secrets/`, `store/`, `watcher/`, `shutdown/`, `services/`, `utils/`, `assert/`, `version/` – supporting packages.\n\nGenerated artifacts: `generated/spec.yaml` (pattern spec) and `generated/client.ts` (TypeScript bindings).\n\n---\n\n## Local Development\n\nPrerequisites: Go 1.25+, [`just`](https://github.com/casey/just), access to a Kubernetes cluster with the `mogenius` namespace.\n\n```sh\n# 1. Create .env (see Configuration below)\n# 2. Optionally scale down in-cluster deployment to avoid conflicts\njust scale-down\n\n# 3. Build \u0026 run\njust build\njust run\n\n# Restore in-cluster deployment afterward\njust scale-up\n```\n\nKey tasks:\n\n```sh\njust build            # compile + regenerate spec.yaml \u0026 client.ts\njust run              # run operator locally\njust run-node-metrics # run node metrics DaemonSet mode locally\njust check            # generate + lint + unit tests\njust test-unit\njust test-integration\njust golangci-lint\njust generate         # run go generate (CRD deepcopy)\njust scale-down / scale-up\n```\n\n---\n\n## Configuration\n\nCreate a `.env` in the repo root:\n\n```sh\nMO_API_KEY=\u003capi-key\u003e       # From operator secret (mogenius/mogenius)\nMO_CLUSTER_NAME=\u003cname\u003e     # Cluster identifier\nMO_CLUSTER_MFA_ID=\u003cid\u003e     # MFA/instance id\nMO_API_SERVER=\u003curl\u003e        # Platform API WebSocket URL\nMO_EVENT_SERVER=\u003curl\u003e      # Platform Event WebSocket URL\nMO_VALKEY_ADDR=\u003chost:port\u003e # Valkey/Redis address\n```\n\nLoad (bash/zsh):\n\n```sh\nif [[ -f .env ]]; then export $(grep -v '^#' .env | xargs); fi\n```\n\n### All Environment Variables\n\n| Variable | Default | Description |\n|---|---|---|\n| `MO_API_KEY` | — | API key to access the mogenius platform (**required**, secret) |\n| `MO_CLUSTER_NAME` | — | Name of the Kubernetes cluster (**required**) |\n| `MO_CLUSTER_MFA_ID` | — | NanoId of the cluster for MFA purpose (**required**, secret) |\n| `MO_API_SERVER` | — | URL of the platform API WebSocket server (**required**) |\n| `MO_API_SERVER_CLIENTS` | `1` | Number of parallel WebSocket connections to the API server |\n| `MO_EVENT_SERVER` | — | URL of the platform event WebSocket server (**required**) |\n| `MO_SKIP_TLS_VERIFICATION` | `false` | Skip TLS verification for API and Event Server |\n| `MO_VALKEY_ADDR` | — | Address (`host:port`) of the Valkey/Redis server (**required**) |\n| `MO_VALKEY_PASSWORD` | — | Password for the Valkey/Redis server |\n| `MO_HTTP_ADDR` | `:1337` | Listen address for the operator HTTP API |\n| `MO_OWN_NAMESPACE` | `mogenius` | Namespace the mogenius platform is installed in |\n| `OWN_NODE_NAME` | — | Node name the application is running on (set by DaemonSet) |\n| `OWN_DEPLOYMENT_NAME` | `mogenius-operator` | Deployment name the application is running in |\n| `CLUSTER_DOMAIN` | `cluster.local` | Internal cluster domain |\n| `MO_HELM_DATA_PATH` | `\u003cworkdir\u003e/helm-data` | Path to Helm data directory |\n| `MO_GIT_USER_NAME` | `mogenius git-user` | Git username for IaC operations |\n| `MO_GIT_USER_EMAIL` | `git@mogenius.com` | Git email for IaC operations |\n| `MO_AUDIT_LOG_LIMIT` | `1000` | Maximum number of audit log entries to persist |\n| `MO_ENABLE_POD_STATS_COLLECTOR` | `true` | Enable collection of pod CPU/memory stats |\n| `MO_ENABLE_TRAFFIC_COLLECTOR` | `false` | Enable collection of network traffic stats |\n| `MO_SNOOPY_IMPLEMENTATION` | `auto` | Network traffic backend: `auto`, `snoopy` (eBPF), or `procdev` |\n| `MO_HOST_PROC_PATH` | `/proc` | Mount path of the host `/proc` filesystem (DaemonSet uses `/hostproc`) |\n| `MO_LOG_LEVEL` | `info` | Log level: `mo`, `debug`, `info`, `warn`, or `error` |\n| `MO_LOG_FILTER` | — | Comma-separated list of components to enable logs for (empty = all) |\n| `MO_ALLOW_COUNTRY_CHECK` | `true` | Allow the operator to determine its location country via IP lookup |\n| `MO_PPROF` | `false` | Expose Go pprof profiling endpoints at `/debug/pprof/` (set to `true` for debugging) |\n| `KUBERNETES_DEBUG` | `false` | Enable Kubernetes SDK debug output |\n\nList all config options at runtime: `go run -trimpath src/main.go config`\n\n---\n\n## Docker (local image)\n\n```sh\ndocker build -t localk8smanager \\\n  --build-arg GOOS=linux \\\n  --build-arg GOARCH=arm64 \\\n  --build-arg BUILD_TIMESTAMP=\"$(date -Iseconds)\" \\\n  --build-arg COMMIT_HASH=\"$(git rev-parse --short HEAD || echo XXX)\" \\\n  --build-arg GIT_BRANCH=local-development \\\n  --build-arg VERSION=\"dev-local\" \\\n  -f Dockerfile .\n```\n\nTo use the local image, patch the deployment to `image: localk8smanager:latest` with `imagePullPolicy: Never`, then restart.\n\n---\n\n## Helm\n\nInstall via OCI:\n\n```sh\nhelm -n mogenius upgrade --install mogenius-platform \\\n  oci://ghcr.io/mogenius/helm-charts/mogenius-operator \\\n  --create-namespace \\\n  --set global.cluster_name=\"\u003ccluster\u003e\" \\\n  --set global.api_key=\"\u003capi-key\u003e\"\n```\n\nOr via Helm repo:\n\n```sh\nhelm repo add mo-public https://helm.mogenius.com/public\nhelm repo update\nhelm upgrade --install mogenius-platform mo-public/mogenius-operator \\\n  --namespace mogenius --create-namespace \\\n  --set global.cluster_name=\"\u003ccluster\u003e\" \\\n  --set global.api_key=\"\u003capi-key\u003e\"\n```\n\nUpgrade: `helm repo update \u0026\u0026 helm upgrade mogenius-platform mo-public/mogenius-operator`\n\nUninstall: `helm uninstall mogenius-platform`\n\n---\n\n## Runtime Image\n\nThe operator uses a minimal `scratch`-based image containing only:\n\n- `mogenius-operator` binary (statically linked, `CGO_ENABLED=0`)\n- `mogenius-snoopy` binary (Rust + musl, statically linked)\n- `nsenter` from Alpine + musl dynamic linker (required for snoopy network namespace entry)\n- CA certificates (for TLS/WSS connections)\n\nThere is no shell or OS tooling in the image. Use `kubectl debug` or `hostPID: true` pods for runtime inspection.\n\n---\n\n## Profiling\n\nTo profile memory usage, enable pprof temporarily:\n\n```sh\nkubectl set env deployment/mogenius-operator -n mogenius MO_PPROF=true\nkubectl port-forward -n mogenius deployment/mogenius-operator 1337:1337\n\n# Heap profile:\ngo tool pprof http://localhost:1337/debug/pprof/heap\n\n# Browser UI:\nopen http://localhost:1337/debug/pprof/\n```\n\nDisable afterward: `kubectl set env deployment/mogenius-operator -n mogenius MO_PPROF-`\n\n---\n\n## Troubleshooting\n\n- Scale down in-cluster deployment before running locally: `just scale-down`.\n- Regenerate patterns after structural changes: `just build`.\n- Auth issues: verify `.env` secrets match the `mogenius/mogenius` operator secret.\n- Stale dependencies: `go clean -modcache \u0026\u0026 go mod tidy`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmogenius%2Fmogenius-operator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmogenius%2Fmogenius-operator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmogenius%2Fmogenius-operator/lists"}