{"id":48969820,"url":"https://github.com/oragazz0/viy","last_synced_at":"2026-04-18T06:38:18.578Z","repository":{"id":348096796,"uuid":"1196490485","full_name":"oragazz0/viy","owner":"oragazz0","description":"CLI-first Kubernetes chaos engineering toolkit in Go — modular, safe, observable. \"Omniscient chaos, unveiled.\"","archived":false,"fork":false,"pushed_at":"2026-04-17T01:45:01.000Z","size":192,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-17T03:34:43.333Z","etag":null,"topics":["chaos-engineering","chaos-toolkit","cli","cloud-native","devops","fault-injection","go","golang","k8s","kubernetes","observability","resilience-testing","sre"],"latest_commit_sha":null,"homepage":"","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/oragazz0.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-30T18:47:58.000Z","updated_at":"2026-04-17T01:44:38.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/oragazz0/viy","commit_stats":null,"previous_names":["oragazz0/viy"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/oragazz0/viy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oragazz0%2Fviy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oragazz0%2Fviy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oragazz0%2Fviy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oragazz0%2Fviy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oragazz0","download_url":"https://codeload.github.com/oragazz0/viy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oragazz0%2Fviy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31959883,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T00:39:45.007Z","status":"online","status_checked_at":"2026-04-18T02:00:07.018Z","response_time":103,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["chaos-engineering","chaos-toolkit","cli","cloud-native","devops","fault-injection","go","golang","k8s","kubernetes","observability","resilience-testing","sre"],"created_at":"2026-04-18T06:38:17.823Z","updated_at":"2026-04-18T06:38:18.568Z","avatar_url":"https://github.com/oragazz0.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 👁️ Viy\n\n```\n══════════════════════════════════════════════════════════════\n  ⬡       ⬡       ⬡\n   ╲      │      ╱\n     ▄████████████▄\n    █░░╱ ▓▒◉▒▓ ╲░░█       V I Y\n     ▀████████████▀\n   ╱      │      ╲        Kubernetes Chaos Engineering Toolkit\n  ⬡       ⬡       ⬡\n══════════════════════════════════════════════════════════════\n```\n\n**Viy** is a Kubernetes Chaos Engineering CLI toolkit written in Go.\n\nInspired by the creature from Slavic folklore whose gaze reveals absolute truth, Viy \"opens its eyes\" on your infrastructure — exposing hidden weaknesses through controlled chaos and omniscient observability.\n\n\u003e *\"I summon the vampires! I summon the werewolves!... I summon Viy!\"*\n\n---\n\n## Key Concepts\n\n| Folklore | Technical Equivalent |\n|----------|---------------------|\n| **Viy's massive eye** | Core orchestration engine |\n| **Servants lifting eyelids** | Chaos modules (*eyes*) |\n| **Revealing gaze** | Full observability during experiments |\n| **Fatal truth** | Failures that must be fixed |\n| **Heavy eyelids** | Safety guards against uncontrolled chaos |\n\nEach chaos module is called an **Eye**. Each Eye reveals a different kind of systemic\nweakness:\n\n| Eye | Chaos Type | What It Reveals |\n|-----|-----------|-----------------|\n| **Disintegration** *(v0.1)* | Pod deletion | Auto-recovery, health checks, single points of failure |\n| **Charm** *(v0.2)* | Network manipulation (`tc netem`) | Timeout gaps, circuit breaker failures, retry logic |\n| **Death** *(v0.2)* | CPU / memory / disk stress | Resource limits, HPA, noisy neighbor tolerance |\n| **Petrification** *(v0.4)* | Container freeze | Deadlocks, dependency timeouts |\n| **Sleep** *(v0.4)* | Latency injection | UX degradation, cache effectiveness |\n| **Wounding** *(v0.4)* | Error injection | Error handling gaps, flaky service tolerance |\n\n---\n\n## Quick Start\n\n### Install\n\n```bash\n# Build from source\ngit clone https://github.com/oragazz0/viy.git\ncd viy\nmake build\n\n# Binary is at ./viy\n./viy version\n```\n\n### Environment Setup\n\nViy needs access to a Kubernetes cluster. It resolves credentials in the following\norder:\n\n1. **`--kubeconfig` flag** — explicit path, highest priority:\n\n   ```bash\n   viy unveil --kubeconfig /path/to/kubeconfig --eye disintegration ...\n   ```\n\n2. **`$KUBECONFIG` / `~/.kube/config`** — when no flag is provided, Viy reads the\n   standard kubeconfig locations (`$KUBECONFIG` env var, then `~/.kube/config`).\n\n3. **In-cluster config** — if no kubeconfig is found, Viy falls back to the service\n   account token mounted at `/var/run/secrets/kubernetes.io/serviceaccount`.\n\n### First Revelation (Dry-Run)\n\nAlways dream before unveiling:\n\n```bash\nviy dream \\\n  --eye disintegration \\\n  --target deployment/nginx \\\n  --namespace staging\n```\n\nOutput:\n\n```\n🔮 Dream Mode: Viy dreams of revelation...\n\nTargets that would be unveiled:\n  • Pod: nginx-abc123 (staging/nginx)\n  • Pod: nginx-def456 (staging/nginx)\n  • Pod: nginx-ghi789 (staging/nginx)\n\nEstimated blast radius: 30% (3/10 pods)\nSafety checks: ✅ All passed\n```\n\n### Unveil for Real\n\n```bash\nviy unveil \\\n  --eye disintegration \\\n  --target deployment/nginx \\\n  --namespace staging \\\n  --duration 2m \\\n  --blast-radius 30% \\\n  --min-healthy 2\n```\n\nOutput:\n\n```\n👁️  Viy awakens from slumber...\n\n🎯 Target Resolution\n   ✅ Found 10 pods in deployment/nginx\n   ✅ Blast radius: 3/10 pods (30%)\n   ✅ Safety checks passed\n\n🔮 Opening Eye of Disintegration\n   ⚡ Unveiling pod nginx-abc123... truth revealed\n   ⚡ Unveiling pod nginx-def456... truth revealed\n   ⚡ Unveiling pod nginx-ghi789... truth revealed\n\n💡 Truths Revealed:\n   🟢 Pod auto-recovery working correctly\n```\n\n### Check Active Experiments\n\n```bash\nviy vision --all\n```\n\n```\nID            EYES               STATUS      TARGET              STARTED\na1b2c3d4e5f6  [disintegration]   revealed    staging/nginx       2m ago\n```\n\n### Stop Everything\n\n```bash\nviy slumber --all\n```\n\n---\n\n## CLI Reference\n\n```\nviy\n├── unveil    Open one eye — single-eye experiment\n├── awaken    Open many eyes — multi-eye experiment from YAML\n├── dream     Dry-run mode (dream without executing)\n├── vision    List active/past experiments\n├── slumber   Stop experiments (close eyes)\n└── version   Show version info\n```\n\n### `viy unveil`\n\n| Flag | Default | Description |\n|------|---------|-------------|\n| `--eye` | *(required)* | Eye to open: `disintegration`, `charm`, or `death` |\n| `--target` | *(required)* | K8s resource, e.g. `deployment/nginx` |\n| `--namespace` | `default` | Kubernetes namespace |\n| `--duration` | `5m` | How long the revelation lasts |\n| `--blast-radius` | `30%` | Max % of targets to affect (1–100) |\n| `--min-healthy` | `1` | Minimum healthy replicas to preserve |\n| `--config` | | Eye config as `key=value,key=value` |\n| `--dream` | `false` | Run in dry-run mode |\n\nSee [docs/configuration/cli-flags.md](docs/configuration/cli-flags.md) for the full\nper-eye `--config` key reference.\n\n### `viy awaken`\n\nOpen multiple eyes simultaneously from a YAML experiment file:\n\n```bash\nviy awaken --file examples/awaken/disintegration-and-charm.yaml\nviy awaken --file experiment.yaml --dream   # dry-run\n```\n\nSee [docs/configuration/experiment-yaml.md](docs/configuration/experiment-yaml.md)\nfor the schema and [docs/cli/commands.md](docs/cli/commands.md#viy-awaken) for\nfailure policies, contention detection, and signal handling.\n\n---\n\n## Safety\n\nViy reveals truths, but responsibly. The heavy eyelids are safety guards:\n\n- **Protected namespaces** — `kube-system`, `kube-public`, and `kube-node-lease` are\n  blocked by default\n- **Blast radius** — limits the percentage of targets affected (default: 30%)\n- **Minimum healthy replicas** — never drops below `--min-healthy` (default: 1)\n- **Dry-run** — always `dream` before you `unveil`\n- **Signal handling** — Ctrl+C gracefully stops experiments\n- **State persistence** — experiments are tracked at `~/.viy/state.json` with atomic writes\n\n---\n\n## Architecture\n\n```\n┌──────────────────────────────────────────────────────────────┐\n│                   CLI Interface (Cobra)                       │\n│  viy unveil | awaken | dream | vision | slumber | version     │\n└─────────────────────┬────────────────────────────────────────┘\n                      │\n┌─────────────────────▼────────────────────────────────────────┐\n│               Core Orchestrator (Viy's Eye)                   │\n│  Run (single-eye)  │  RunMulti (multi-eye, errgroup/waitgroup)│\n│  Target Resolution │ Safety Checks │ Contention │ Lifecycle   │\n└──────┬───────────────────────────────────────┬───────────────┘\n       │                                       │\n┌──────▼─────────────┐                ┌────────▼─────────────┐\n│ Eye + Decoder      │                │  Observability       │\n│ Registries         │                │  • Structured JSON   │\n│ (pkg/eyes +        │                │    logging (zap)     │\n│  pkg/config)       │                └──────────────────────┘\n└──────┬─────────────┘\n       │\n┌──────▼───────────────────────────────────────────────────────┐\n│                   Eyes (Chaos Modules)                        │\n├───────────────────────────────────────────────────────────────┤\n│ Disintegration (pod kill) │ Charm (tc netem) │ Death (stress) │\n└──────┬────────────────────────────────────────────────────────┘\n       │\n┌──────▼───────────────────────────────────────────────────────┐\n│                  Kubernetes API (client-go)                   │\n│          + ephemeral containers (kubectl debug shape)         │\n└───────────────────────────────────────────────────────────────┘\n```\n\n### Package Layout\n\n```\nviy/\n├── cmd/viy/main.go                          Entry point\n├── pkg/\n│   ├── eyes/                                Eye interface + factory registry\n│   │   ├── charm/                           Network chaos (tc netem)\n│   │   └── death/                           Resource exhaustion (stress-ng)\n│   ├── config/                              YAML schema + decoder registry\n│   ├── errors/                              Sentinel errors + suggestions\n│   └── safety/                              Blast radius calculator\n└── internal/\n    ├── cli/                                 Cobra commands\n    ├── orchestrator/                        Run + RunMulti lifecycle\n    ├── eyes/disintegration/                 Pod kill module\n    ├── k8s/                                 Kubernetes client wrapper\n    ├── observability/                       Structured logging\n    └── state/                               Local state persistence\n```\n\nSee [docs/architecture/design.md](docs/architecture/design.md) for the full\ndependency diagram and concurrency model.\n\n---\n\n## Development\n\n```bash\nmake build      # Build binary with version injection\nmake test       # Run tests with -race\nmake lint       # golangci-lint\nmake vuln       # Vulnerability scan\nmake clean      # Remove binary\n```\n\n### Testing\n\n```bash\n# All tests\ngo test -v -race -count=1 ./...\n\n# Specific package\ngo test -v ./internal/eyes/disintegration/...\n```\n\n---\n\n## Roadmap\n\n- [x] **v0.1.0** — Eye of Disintegration, CLI, dry-run, state persistence\n- [x] **v0.2.0** — Eye of Charm (network), Eye of Death (resources), `viy awaken` multi-eye execution, YAML experiments\n- [ ] **v0.3.0** — TUI dashboard (`viy scry`), reports (`viy reveal`), Prometheus metrics\n- [ ] **v0.4.0** — Apocalypse mode, remaining Eyes, OpenTelemetry\n- [ ] **v1.0.0** — Production hardening, Helm chart, docs, release\n\n---\n\n## Documentation\n\n\u003c!-- Full documentation will be hosted at docs.viy.io --\u003e\nFor in-depth guides, configuration reference, architecture details, and runbooks, see the [`docs/`](docs/) folder.\n\n---\n\n## Philosophy\n\nViy is not just a chaos tool — it is a **truth revealer**.\n\nTraditional chaos engineering says *\"break things to see what happens.\"*\nViy says *\"open your eyes to see what was always there.\"*\n\nEvery experiment is a **revelation**. Every failure is a **truth** your infrastructure was hiding.\nThe goal is not destruction — it is **understanding**.\n\n\u003e *\"A curse upon you! With the wings of a bat! With the blood of a serpent! I shall curse you! Curse you!\"*\n\n---\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foragazz0%2Fviy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foragazz0%2Fviy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foragazz0%2Fviy/lists"}