{"id":47974734,"url":"https://github.com/moranweissman/sharko","last_synced_at":"2026-04-28T09:01:27.588Z","repository":{"id":348608164,"uuid":"1197404859","full_name":"MoranWeissman/sharko","owner":"MoranWeissman","description":"Addon management server for Kubernetes clusters, built on ArgoCD","archived":false,"fork":false,"pushed_at":"2026-04-13T22:25:12.000Z","size":20125,"stargazers_count":1,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-13T23:33:33.858Z","etag":null,"topics":["addons","argocd","gitops","helm","kubernetes","platform-engineering"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MoranWeissman.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"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":"2026-03-31T14:55:46.000Z","updated_at":"2026-04-13T22:25:08.000Z","dependencies_parsed_at":null,"dependency_job_id":"b251fd7c-cdea-4866-8613-06db49421d87","html_url":"https://github.com/MoranWeissman/sharko","commit_stats":null,"previous_names":["moranweissman/sharko"],"tags_count":57,"template":false,"template_full_name":null,"purl":"pkg:github/MoranWeissman/sharko","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MoranWeissman%2Fsharko","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MoranWeissman%2Fsharko/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MoranWeissman%2Fsharko/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MoranWeissman%2Fsharko/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MoranWeissman","download_url":"https://codeload.github.com/MoranWeissman/sharko/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MoranWeissman%2Fsharko/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31776013,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-13T20:17:16.280Z","status":"ssl_error","status_checked_at":"2026-04-13T20:17:08.216Z","response_time":93,"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":["addons","argocd","gitops","helm","kubernetes","platform-engineering"],"created_at":"2026-04-04T10:53:29.364Z","updated_at":"2026-04-28T09:01:27.575Z","avatar_url":"https://github.com/MoranWeissman.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/logo/sharko-mascot.png\" alt=\"Sharko\" width=\"400\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eSharko\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eAddon management for Kubernetes clusters, built on ArgoCD\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/MoranWeissman/sharko/releases\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/MoranWeissman/sharko\" alt=\"Release\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/MoranWeissman/sharko/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/MoranWeissman/sharko\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/go-1.25-blue\" alt=\"Go\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/react-18-61dafb\" alt=\"React\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/typescript-5-3178c6\" alt=\"TypeScript\"\u003e\n\u003c/p\u003e\n\n---\n\nSharko is a server that runs in your Kubernetes cluster, next to ArgoCD, and manages the lifecycle of addons across your fleet. Install it with a single Helm command, and a guided wizard walks you through connecting your Git repo, ArgoCD instance, and optional secrets provider — no config files, no env vars to set by hand.\n\n## Features\n\n- **Wizard-based setup** — first run opens a step-by-step wizard: Git connection, ArgoCD connection, secrets provider, and repo initialization\n- **Fleet dashboard** — cluster health cards with sync status, addon counts, and connection indicators; managed and discovered clusters in separate sections\n- **Curated marketplace (v1.21)** — 45 vetted Helm addons with OpenSSF Scorecard signals, server-side ArtifactHub search, and smart values seeding (heuristic + optional LLM annotation) — every Add still goes through a Git PR\n- **Addon catalog** — version matrix across every cluster, drift detection, and contextual help on all advanced config fields\n- **GitOps-native** — every write operation creates a PR (auto-merge optional); branches cleaned up after merge\n- **Managed vs discovered clusters** — Sharko surfaces all ArgoCD clusters; adopt discovered clusters into full management in one click\n- **Secrets provider** — deliver addon credentials to remote clusters via AWS Secrets Manager or Kubernetes Secrets (no ESO required)\n- **AI assistant** — context-aware troubleshooting panel with resizable panel and error-aware pre-filled prompts; supports OpenAI, Claude, Gemini, Ollama, and any OpenAI-compatible API\n- **API keys** — long-lived tokens for Backstage, Terraform, and CI/CD integrations\n- **Unified API** — CLI, UI, and external integrations all use the same REST API\n- **Upgrade management** — security-aware upgrade recommendation cards (ArtifactHub advisories, security/breaking-change flags, scored best-path), analyze-before-upgrade enforcement, step-by-step progress, batch multi-addon upgrades\n- **ArgoCD diagnostics** — ArgoCD connection state surfaced per cluster; bootstrap app health shown on dashboard and observability view\n- **Auto-refresh** — dashboard, cluster detail, cluster overview, and addon detail pages refresh automatically (30s); addon catalog refreshes every 60s\n\n- **Addon dependency ordering** — declare `dependsOn` in the catalog to enforce deployment order; cycle detection prevents invalid graphs\n- **AI addon summaries** — AI-generated summaries of each addon's purpose and release notes, shown in the addon detail view\n- **Audit log** — every write operation recorded with actor, action, result, and timestamp; queryable via `GET /api/v1/audit`\n- **Multi-cloud provider stubs** — GCP and Azure provider stubs define the interface for community contributions\n- **E2E test framework** — test against a real ArgoCD + Kind cluster (`make e2e-setup \u0026\u0026 make e2e`)\n\n## Demo\n\nNo Kubernetes cluster required — mock backends simulate ArgoCD, Git, and secrets providers.\n\n```bash\ngit clone https://github.com/MoranWeissman/sharko.git\ncd sharko\nmake demo\n```\n\nOpen [http://localhost:8080](http://localhost:8080) and log in with `admin` / `admin` (admin role) or `qa` / `sharko` (viewer role).\n\n## Quick Start (Production)\n\n### 1. Install Sharko\n\n```bash\nhelm install sharko oci://ghcr.io/moranweissman/sharko/sharko \\\n  --namespace sharko --create-namespace\n```\n\nIf using AWS Secrets Manager for cluster credentials, add the IRSA annotation:\n\n```bash\nhelm install sharko oci://ghcr.io/moranweissman/sharko/sharko \\\n  --namespace sharko --create-namespace \\\n  --set serviceAccount.annotations.\"eks\\.amazonaws\\.com/role-arn\"=arn:aws:iam::123456789012:role/sharko-role\n```\n\n### 2. Get the Admin Password\n\n```bash\nkubectl get secret sharko -n sharko \\\n  -o jsonpath='{.data.admin\\.initialPassword}' | base64 -d\n```\n\n### 3. Open the UI\n\n```bash\nkubectl port-forward svc/sharko 8080:80 -n sharko\n```\n\nOpen [http://localhost:8080](http://localhost:8080) and log in with `admin` and the password from step 2.\n\n### 4. Complete the First-Run Wizard\n\nThe wizard appears automatically on first access — no separate configuration step needed.\n\n1. **Welcome** — overview of what Sharko will set up\n2. **Git connection** — enter your repo URL and personal access token\n3. **ArgoCD connection** — Sharko auto-discovers the ArgoCD service in-cluster; add optional secrets provider config\n4. **Initialize repository** — Sharko creates the ApplicationSet, base values, and cluster directory structure in your repo; choose auto-merge or review the PR yourself\n\nAfter the wizard completes, the dashboard loads with clusters pulled from ArgoCD.\n\n## Architecture\n\n```\nDeveloper laptop / CI:\n  sharko CLI ---------\u003e Sharko Server API\n\nBackstage / Port.io / Terraform:\n  plugin / curl ------\u003e Sharko Server API\n\nSharko Server (in-cluster):\n  +-- UI (React dashboard with first-run wizard)\n  +-- API (REST endpoints, JWT + API key auth)\n  +-- Orchestrator (workflow engine, Git-serialized via mutex)\n  +-- ArgoCD client (service-discovery + account token auth)\n  +-- Git client (GitHub, Azure DevOps)\n  +-- Secrets provider (AWS SM, K8s Secrets)\n  +-- Remote client (deliver secrets to remote clusters)\n  +-- AI assistant (multi-provider)\n  +-- Swagger UI (/swagger/index.html)\n```\n\nThe server holds all credentials. The CLI is a thin HTTP client — like `kubectl` to the Kubernetes API. No credentials on developer laptops.\n\n## Tech Stack\n\n| Layer | Technology |\n|-------|------------|\n| Backend | Go 1.25, net/http, Cobra CLI framework |\n| Frontend | React 18, TypeScript, Vite |\n| Styling | Tailwind CSS v4, shadcn/ui components |\n| GitOps | ArgoCD ApplicationSets, Helm charts |\n| API docs | Swagger / OpenAPI (swag) |\n| Secrets | AWS Secrets Manager, Kubernetes Secrets |\n| AI | OpenAI, Claude, Gemini, Ollama, custom OpenAI-compatible |\n\n## CLI Commands\n\n| Command | Description |\n|---------|-------------|\n| `sharko login --server \u003curl\u003e` | Authenticate with the server |\n| `sharko version` | Show CLI + server version |\n| `sharko connect` | Configure the active Git connection |\n| `sharko connect list` | Show current connection |\n| `sharko connect test` | Test current connection |\n| `sharko init` | Initialize the addons repo (async, streams progress) |\n| `sharko validate [path]` | Validate catalog YAML against schema |\n| `sharko add-cluster \u003cname\u003e` | Register a cluster |\n| `sharko add-clusters \u003cn1,n2,...\u003e` | Batch register multiple clusters |\n| `sharko remove-cluster \u003cname\u003e` | Deregister a cluster |\n| `sharko update-cluster \u003cname\u003e` | Update addon assignments |\n| `sharko list-clusters` | List all clusters |\n| `sharko test-cluster \u003cname\u003e` | Test connectivity to a cluster |\n| `sharko adopt-cluster \u003cname\u003e` | Adopt a discovered ArgoCD cluster |\n| `sharko add-addon \u003cname\u003e` | Add addon to catalog |\n| `sharko remove-addon \u003cname\u003e` | Remove addon (dry-run without `--confirm`) |\n| `sharko upgrade-addon \u003cname\u003e` | Upgrade an addon version |\n| `sharko upgrade-addons \u003caddon=ver,...\u003e` | Batch upgrade multiple addons |\n| `sharko list-addons [--show-config]` | List addons |\n| `sharko refresh-secrets [cluster]` | Trigger immediate secrets reconcile |\n| `sharko secret-status` | Show reconciler status per cluster |\n| `sharko token create` | Create an API key |\n| `sharko token list` | List API keys |\n| `sharko token revoke \u003cname\u003e` | Revoke an API key |\n| `sharko status` | Cluster status overview |\n\n## API\n\nSharko exposes a REST API that every consumer uses — the CLI, the UI, and external integrations.\n\n### Read Operations\n\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | `/api/v1/clusters` | List clusters with health stats |\n| GET | `/api/v1/clusters/{name}` | Cluster detail + addon status |\n| GET | `/api/v1/clusters/{name}/comparison` | Git vs ArgoCD comparison, including ArgoCD connection state |\n| GET | `/api/v1/clusters/available` | Discover available clusters from the secrets provider |\n| GET | `/api/v1/addons/catalog` | Addon catalog with deployment stats |\n| GET | `/api/v1/addons/version-matrix` | Version matrix: addon × cluster grid |\n| GET | `/api/v1/fleet/status` | Cluster status overview |\n| GET | `/api/v1/dashboard/stats` | Aggregated stats including bootstrap app health |\n| GET | `/api/v1/upgrade/{addonName}/recommendations` | Smart upgrade recommendations (next patch, next minor, latest stable) |\n| GET | `/api/v1/tokens` | List API keys (admin only) |\n| GET | `/api/v1/addon-secrets` | List addon secret definitions |\n| GET | `/api/v1/clusters/{name}/secrets` | List managed secrets on a cluster |\n| GET | `/api/v1/notifications` | List notifications (upgrades, drift, security advisories) |\n\n### Write Operations\n\n| Method | Path | Description |\n|--------|------|-------------|\n| POST | `/api/v1/clusters` | Register a cluster |\n| POST | `/api/v1/clusters/batch` | Batch register up to 10 clusters |\n| DELETE | `/api/v1/clusters/{name}` | Deregister a cluster |\n| PATCH | `/api/v1/clusters/{name}` | Update addon labels |\n| POST | `/api/v1/clusters/{name}/refresh` | Refresh cluster credentials |\n| POST | `/api/v1/clusters/{name}/secrets/refresh` | Refresh managed secrets on a cluster |\n| POST | `/api/v1/clusters/{name}/test` | Test cluster connectivity |\n| POST | `/api/v1/clusters/{name}/adopt` | Adopt a discovered ArgoCD cluster |\n| POST | `/api/v1/addons` | Add addon to catalog |\n| DELETE | `/api/v1/addons/{name}?confirm=true` | Remove addon (with safety gate) |\n| POST | `/api/v1/addons/{name}/upgrade` | Upgrade an addon |\n| POST | `/api/v1/addons/upgrade-batch` | Upgrade multiple addons in one PR |\n| POST | `/api/v1/addon-secrets` | Define an addon secret template |\n| DELETE | `/api/v1/addon-secrets/{addon}` | Remove an addon secret definition |\n| POST | `/api/v1/tokens` | Create an API key |\n| DELETE | `/api/v1/tokens/{name}` | Revoke an API key |\n| POST | `/api/v1/init` | Initialize addons repo (async — returns `operation_id`) |\n| GET | `/api/v1/operations/{id}` | Get async operation status and log lines |\n| POST | `/api/v1/secrets/reconcile` | Trigger immediate secrets reconcile |\n| GET | `/api/v1/secrets/status` | Reconciler status per cluster |\n\nSee [docs/api-contract.md](docs/api-contract.md) for full request/response shapes.\n\nInteractive API docs at `/swagger/index.html` when the server is running.\n\n## Settings\n\nAfter the wizard, the **Settings** page has six sections:\n\n| Section | What you configure |\n|---------|-------------------|\n| Connection | ArgoCD server URL + token, Git provider + repo + token |\n| Secrets Provider | `aws-sm` or `k8s-secrets`, region or namespace |\n| GitOps | Auto-merge PRs, branch prefix, commit prefix, base branch |\n| Users | Change admin password |\n| API Keys | Create and revoke long-lived tokens for CI/CD |\n| AI | Provider (OpenAI, Claude, Gemini, Ollama, custom), model, API key |\n\n## AI Assistant\n\nBuilt-in assistant accessible from any page. Knows which cluster or addon you are viewing and can answer questions about health, configuration, and version drift.\n\n**Supported providers:** OpenAI, Claude, Gemini, Ollama, or any OpenAI-compatible API.\n\n**Capabilities:** 24 read tools and 5 write tools (admin-only, opt-in):\n- List clusters, addons, and health status\n- Inspect per-cluster addon configuration\n- Query ArgoCD application health, resources, events, and pod logs\n- Compare Helm chart versions and fetch release notes\n- Enable/disable addons, update versions, sync and refresh ArgoCD apps\n\n## Secrets Provider\n\nSharko uses a pluggable provider to fetch cluster kubeconfigs:\n\n| Provider | Description |\n|----------|-------------|\n| `aws-sm` | AWS Secrets Manager (IRSA for auth — no static credentials) |\n| `k8s-secrets` | Kubernetes Secrets (no cloud dependency) |\n\nConfigure in **Settings → Secrets Provider**. Supports structured JSON secrets in AWS SM (individual keys instead of raw kubeconfig YAML) and STS EKS token generation via IRSA.\n\n## Development\n\n### Demo mode\n\n```bash\nmake demo\n# Open http://localhost:8080 — login: admin/admin or qa/sharko\n```\n\n### Hot-reload development\n\n```bash\nmake dev\n# Frontend: http://localhost:5173\n# Backend:  http://localhost:8080 (API only)\n```\n\n### Build and test\n\n```bash\nmake build    # Build Go binary + UI\nmake test     # Run all tests (Go + UI)\nmake lint     # Go vet + UI build check\n```\n\n### Swagger regeneration\n\n```bash\nswag init -g cmd/sharko/serve.go -o docs/swagger --parseDependency --parseInternal\n```\n\n## Documentation\n\n| Document | Description |\n|----------|-------------|\n| [API Contract](docs/api-contract.md) | Full API reference with request/response shapes and error codes |\n| [Architecture](docs/architecture.md) | Server-first architecture, orchestrator pattern, provider interfaces |\n| [User Guide](docs/user-guide.md) | End-to-end guide: install, configure, manage clusters and addons |\n| [Developer Guide](docs/developer-guide.md) | Project structure, coding patterns, testing, adding new features |\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoranweissman%2Fsharko","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmoranweissman%2Fsharko","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoranweissman%2Fsharko/lists"}