torloejborg/easykube

1. What this repo is

- Easykube is a Go CLI for creating and managing a local Kubernetes development environment.

- It combines a Kind-based cluster, a Zot pull-through registry, and an addon system that lets users compose stacks of Kubernetes app logic.

2. Primary entrypoint and CLI surface

- main.go and cmd/root.go define the binary and command tree.

- The subcommands in cmd/ are the user-facing operations: boot, start, stop, destroy, add, remove, list, status, config, skaffold, and version.

- This is a classic CLI boundary: command parsing stays at the edge, while orchestration and domain logic live below it.

3. Orchestration layer

- pkg/core is the central coordination layer.

- It models the repository’s domain concepts: addons, stacks, task execution, and dependency resolution.

- This is where the project decides *what* to do with a cluster or addon, without directly embedding tool-specific details.

4. Addon model and dependency graph

- Addons appear to be the core unit of composition.

- pkg/core/dependency_resolver.go, pkg/core/addon.go, and pkg/core/stack.go suggest addons can depend on one another, form stacks, and be executed in dependency order.

- The test_addons/ fixtures include circular, diamond, and broken dependency cases, showing that dependency correctness is an important architectural concern.

5. Scripted addon execution boundary

- pkg/js is the execution/runtime boundary for addon behavior.

- Easykube uses Goja to run JavaScript addon scripts, exposing a curated API such as Helm, Kustomize, Kubernetes operations, environment access, Git checkout, HTTP, skopeo, image preloading, secret creation, deployment waiting, and process execution.

- This means addon authors write behavior in JS, while Go provides the host runtime and safe integration points.

6. External tool abstraction

- pkg/ez is a helper/integration layer around local and cluster-facing tooling.

- It contains wrappers for Kubernetes utilities, container runtime detection, skaffold handling, OS/version detection, and cluster/config helpers.

- Architecturally, this is the “tooling adapter” layer that isolates the rest of the code from direct dependence on binaries like docker, kubectl, helm, kustomize, and skaffold.

7. Bootstrap and cluster lifecycle

- The boot command is the most infrastructure-heavy flow.

- README indicates it creates a Kind cluster named easykube-kind and a companion Zot registry configured as a pull-through cache.

- The cluster lifecycle commands (boot, start, stop, destroy, status) are distinct from addon operations, but both converge on the same underlying environment/config state.

8. Configuration and persistent state

- cmd/config* and pkg/ez/config_utils.go handle generation, editing, and use of configuration.

- The repo intentionally keeps its own config separate from the user’s existing kubeconfig, using a dedicated config directory under ~/.config/easykube and a separate kubeconfig under ~/.kube/easykube.

- This separation is an important boundary for diagrams: Easykube owns its own state and does not directly mutate the user’s primary Kubernetes context.

9. Templates and bundled runtime assets

- pkg/resources/data/ contains the static assets that bootstrap the environment: cluster/config templates, Coredns data, certs, skaffold manifests, and Zot config templates.

- These assets are embedded into the binary and then materialized into files or cluster resources during setup.

- The repo therefore has a “compiled-in defaults” architecture rather than relying entirely on external config files.

10. Certificates and local HTTPS support

- cert/ and pkg/resources/data/cert/ contain a local CA and generated cert material used for secure local access.

- The certificate subsystem supports the local development story, especially because many addons expect HTTPS and registry access.

- In diagrams, this is part of the bootstrap infrastructure, not a standalone application feature.

11. Skaffold and application deployment path

- The skaffold command and the pkg/resources/data/skaffold/ bundle indicate a dedicated path for deploying/managing app workloads using Skaffold alongside Kustomize manifests.

- This is likely the bridge from addon definitions to running application resources in the cluster.

- The presence of pkg/js/ek_skaffold.go and related JS helpers suggests addon scripts can trigger deployment workflows rather than only declaratively defining them.

12. Testing and verification

- Tests are split across helper-layer tests (pkg/ez, pkg/js) and fixture-based addon tests (test_addons/).

- There is also a mock/ package for interface-based mocking, suggesting core orchestration depends on abstractions rather than hard-coded binaries.

- CI includes Go tests and CodeQL, reinforcing that the repo’s correctness depends heavily on dependency resolution, scripting runtime behavior, and tool integration.

13. External dependencies and runtime assumptions

- The runtime assumes the presence of local developer tools: Docker or Podman, Kind via Docker, Kubernetes clients, Helm, Kustomize, and optionally Skaffold.

- External services may be mirrored locally through Zot, and private registries can be configured in the Easykube config.

- Easykube is therefore not a hosted service; it is a local orchestration tool that stitches together local binaries, local cluster state, and addon scripts.

14. High-level data flow

- User command enters cmd/ → command logic calls pkg/core orchestration → pkg/ez resolves local tooling/config/cluster details → pkg/js executes addon scripts → scripts call back into Kubernetes/tool helpers → external binaries and the Kind/Zot/Kubernetes environment perform the actual work.

- The main architectural boundary is between CLI/orchestration code and the external local dev environment it controls.