If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/kubernetes-sigs/kind shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 1d ago
• 12 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 53% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live kubernetes-sigs/kind repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/kubernetes-sigs/kind.

What it runs against: a local clone of kubernetes-sigs/kind — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in kubernetes-sigs/kind | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of kubernetes-sigs/kind. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/kubernetes-sigs/kind.git
#   cd kind
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of kubernetes-sigs/kind and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "kubernetes-sigs/kind(\\.git)?\\b" \\
  && ok "origin remote is kubernetes-sigs/kind" \\
  || miss "origin remote is not kubernetes-sigs/kind (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "cmd/kind/main.go" \\
  && ok "cmd/kind/main.go" \\
  || miss "missing critical file: cmd/kind/main.go"
test -f "cmd/kind/app/main.go" \\
  && ok "cmd/kind/app/main.go" \\
  || miss "missing critical file: cmd/kind/app/main.go"
test -f "go.mod" \\
  && ok "go.mod" \\
  || miss "missing critical file: go.mod"
test -f "images/base/Dockerfile" \\
  && ok "images/base/Dockerfile" \\
  || miss "missing critical file: images/base/Dockerfile"
test -f "images/base/files/etc/systemd/system/kubelet.service" \\
  && ok "images/base/files/etc/systemd/system/kubelet.service" \\
  || miss "missing critical file: images/base/files/etc/systemd/system/kubelet.service"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/kubernetes-sigs/kind"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

kind (Kubernetes IN Docker) is a tool for running local Kubernetes clusters inside Docker containers, treating each node as a container. It bootstraps clusters with kubeadm and is primarily designed for testing Kubernetes itself and local CI workflows, though also useful for local development. Core capability: spin up a full multi-node Kubernetes cluster with kind create cluster for rapid iterate-test cycles without VM overhead. Monolithic CLI + library repo: cmd/kind/main.go and cmd/kind/app/main.go are entry points wrapping a collection of Go packages implementing cluster creation, image building, and node management. Images are Docker-based (Dockerfile in .github/workflows and images/ folder). Build and CI orchestration lives in hack/ (hack/build/ for compilation, hack/ci/ for test/release workflows).

Kubernetes developers and maintainers who need to test Kubernetes changes locally, CI/CD pipeline operators running Kubernetes tests in containers, and developers doing local Kubernetes development who want a lightweight alternative to minikube or full VMs.

Actively developed and production-ready: the codebase shows 700KB+ of Go code, comprehensive CI workflows (docker.yaml, e2e.sh, e2e-k8s.sh), established release processes (RELEASE.md, stable binaries on releases page), and v0.31.0 is current. However, the README explicitly notes 'kind is still a work in progress, see the 1.0 roadmap'—indicating intentional API/stability gaps remain before v1.0.

Low-to-moderate risk: dependency surface is tightly curated (go.mod shows only ~10 direct deps, mostly stable CLI/config libraries like Cobra, TOML, YAML), and the project has clear ownership (OWNERS file, SECURITY_CONTACTS). Main risks are tight coupling to Docker/container runtimes (podman/nerdctl support via matrix but Docker-first design) and fast Kubernetes release cycles requiring frequent updates. Single release path through CloudBuild suggests some CI/CD concentration.

Active development with focus on container runtime flexibility: workflows for Docker (docker.yaml), Podman (podman.yml), and nerdctl (nerdctl.yaml) suggest multi-runtime support is being prioritized. CI includes Kubernetes e2e testing (e2e-k8s.sh) and tool-specific e2e runs. Dependabot integration (dependabot.yml) shows continuous dependency updates. No specific milestone visible in provided data but v0.31.0 tag indicates frequent releases.

# Clone and build
git clone https://github.com/kubernetes-sigs/kind.git
cd kind
make build

# Or install directly
go install sigs.k8s.io/kind@latest

# Create a test cluster (requires Docker)
kind create cluster

Daily commands:

# Development build
make build
./bin/kind create cluster

# Run tests
make test

# Build all artifacts (uses docker)
make build-all

# CI e2e tests (requires container runtime)
hack/ci/e2e.sh

• cmd/kind/main.go — Entry point for the kind CLI; all contributors must understand how the command-line interface is bootstrapped
• cmd/kind/app/main.go — Core application logic orchestrating cluster creation, image building, and node management; essential for understanding the main workflows
• go.mod — Declares all external dependencies including Cobra (CLI), YAML libraries, and Kubernetes tooling; critical for dependency management and versioning
• images/base/Dockerfile — Defines the base Docker image for kind nodes, including systemd, kubelet, and containerd setup; fundamental to how kind bootstraps Kubernetes nodes
• images/base/files/etc/systemd/system/kubelet.service — Systemd service configuration for kubelet in kind nodes; essential for understanding node initialization and Kubernetes component management
• Makefile — Primary build and test orchestration; shows how to build kind binaries, run tests, and manage the development workflow
• README.md — High-level project documentation explaining kind's purpose, architecture, and primary use cases; must-read for onboarding

Add a new CLI command

1. Define the command handler in cmd/kind/app/main.go using Cobra's Command structure (cmd/kind/app/main.go)
2. Add flags and configuration using spf13/pflag for command-line arguments (cmd/kind/app/main.go)
3. Implement command logic in a separate package (convention: pkg/cluster, pkg/build, etc.) (cmd/kind/app/main.go)
4. Add unit tests in cmd/kind/app/main_test.go (cmd/kind/app/main_test.go)

Modify node image or system configuration

1. Update Dockerfile if changing base OS layer or package installation (images/base/Dockerfile)
2. Add or modify systemd service files in images/base/files/etc/systemd/system/ (images/base/files/etc/systemd/system/kubelet.service)
3. Update configuration files like containerd.conf or kubelet defaults (images/base/files/etc/containerd/config.toml)
4. Rebuild the base image using images/base/Makefile and tag appropriately (images/base/Makefile)

Add a new dependency or update tooling

1. Add the Go module dependency with go get or edit go.mod directly (go.mod)
2. Run go mod tidy to update go.sum and resolve transitive dependencies (go.sum)
3. If it's a development tool, add it to hack/tools/tools.go (hack/tools/tools.go)
4. Verify the change with make verify and make test (Makefile)

Extend CI/CD workflows

1. Create or modify GitHub Actions workflow in .github/workflows/ (.github/workflows/docker.yaml)
2. Reference shell scripts in hack/ci/ for build and test logic (hack/ci/e2e.sh)
3. Use hack/make-rules/ for test and build rule consistency (hack/make-rules/test.sh)
4. Test the workflow locally before pushing (Makefile)

• Go 1.17+ — Cross-platform CLI binary distribution; minimal runtime overhead for local cluster orchestration
• Docker/Podman/nerdctl — Lightweight container-based nodes; enables testing Kubernetes without full VMs
• kubeadm — Official Kubernetes cluster bootstrapping tool; ensures kind clusters reflect real Kubernetes deployment
• systemd — Service lifecycle management within container nodes; enables proper kubelet and containerd initialization
• Cobra CLI framework — Professional command-line interface with subcommands, flags, and help generation
• containerd — Lightweight container runtime; lower resource overhead than Docker daemon inside nodes

• Container-based nodes instead of VMs

  • Why: Faster startup, lower memory footprint, easier integration with CI/CD systems
  • Consequence: Limited to testing Kubernetes networking within container namespaces; some host-level features unavailable

• Single Go binary for CLI instead of component separation

  • Why: Simplified distribution and installation; all cluster orchestration in one tool
  • Consequence: Tight coupling between CLI, builder, and cluster logic; harder to extend with plugins

• Use kubeadm for node bootstrap instead of custom init

  • Why: Ensures compatibility with upstream Kubernetes; reduces maintenance burden
  • Consequence: Depends on kubeadm stability; slower cluster creation than minimal custom init

• Static base image with all components baked in

  • Why: Faster node startup; no dynamic component installation during cluster creation
  • Consequence: Larger image size; new Kubernetes versions require new base image builds

• Production Kubernetes deployment; not designed for persistent workloads or multi-node geographic distribution
• Network policy testing across multiple Docker networks; networking is simplified for local testing
• Custom scheduler or API server implementations; uses upstream Kubernetes components
• Real-time performance profiling; containerized environment introduces overhead
• Windows node support; Linux-centric design using systemd and Linux containers

1. Tight Docker coupling: kind_experimental_docker_network or Docker socket access required; Podman/nerdctl support exists but Docker is the tested path. 2. kubeadm bootstrapping: cluster configuration mirrors kubeadm constraints (CNI plugins, control plane taints); not all Kubernetes config options are exposed via kind. 3. Go version pinch point: .go-version file specifies exact compiler version; go.mod specifies minimum language version 1.17—build may fail silently with wrong Go release. 4. No in-process cluster API: kind is CLI-only; programmatic cluster control requires shelling out or using the undocumented Go packages directly (no stable Go API). 5. Container image rebuild required for Kubernetes updates: each k8s version requires rebuilding node images; pre-built images live in a separate image registry (kindest/node).

• kubeadm bootstrapping — kind's core mechanism for initializing Kubernetes clusters; understanding kubeadm phases, join tokens, and control plane setup is critical for diagnosing cluster creation failures.
• Container-as-node architecture — kind treats each Kubernetes node as a Docker container rather than a VM; requires understanding how systemd, networking, and volumes are mapped inside containers to work around node-level constraints.
• Docker privileged mode and bind mounts — kind containers run in privileged mode with host Docker socket mounted to enable Docker-in-Docker (DinD); critical for understanding security posture and troubleshooting volume/network issues.
• Cobra CLI framework patterns — kind's CLI is built entirely with Cobra; adding new subcommands or flags requires understanding Cobra's command, flag, and cobra.Command patterns used in main.go.
• CNI (Container Network Interface) plugin abstraction — kind abstracts Kubernetes' CNI layer; understanding that flannel/calico/weave are pluggable and configured via kubeadm is essential for debugging network issues in clusters.
• Image layer caching and reproducible builds — kind uses Docker/Buildx for reproducible node image builds (hack/build/init-buildx.sh); understanding image layers and cache invalidation is key for optimizing build times and ensuring consistent node images across releases.
• systemd in containers (systemd-in-Docker) — kind node images run systemd as PID 1 to manage kubelet, containerd, and other daemons; understanding systemd units and journal logs is essential for debugging node-level failures inside kind containers.

• kubernetes/kubernetes — Official Kubernetes repository; kind is built to test changes against this and integrates its test suites (e2e-k8s.sh).
• kubernetes-sigs/kubeadm — kind bootstraps each node with kubeadm; understanding kubeadm config and phases is essential to troubleshooting kind cluster creation.
• moby/moby — Docker Engine underpins kind's container node runtime; network and volume issues often trace back to Docker daemon behavior.
• kubernetes/minikube — Direct alternative: runs Kubernetes in a VM or container; solves the same 'local cluster' problem but with different trade-offs (minikube is more feature-complete, kind is lighter).
• containerd/containerd — Container runtime used inside kind nodes; debugging node issues may require understanding containerd internals and logging.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for nerdctl and podman container runtimes in CI

The repo has GitHub workflows for docker.yaml, nerdctl.yaml, and podman.yml, but based on the file structure, these workflows likely lack comprehensive integration testing. The nerdctl.yaml and podman.yml workflows exist but probably need expanded test coverage similar to the docker workflow. This is high-value because kind supports multiple container runtimes, and ensuring all three (Docker, Podman, nerdctl) work correctly is critical for the tool's reliability.

• [ ] Review .github/workflows/nerdctl.yaml and .github/workflows/podman.yml to identify missing test cases compared to docker.yaml
• [ ] Add end-to-end test steps in nerdctl.yaml and podman.yml that mirror hack/ci/e2e.sh and hack/ci/e2e-k8s.sh execution
• [ ] Ensure both workflows test cluster creation, node provisioning, and basic Kubernetes operations for their respective runtimes
• [ ] Document the new test coverage in CONTRIBUTING.md

Add unit tests for cmd/kind/app/main.go entry point

The cmd/kind/app/main_test.go file exists but is likely incomplete given the importance of the CLI entry point. Testing the main CLI initialization, argument parsing, and error handling would catch regressions early. The spf13/cobra dependency and pflag are used for CLI, so testing the root command setup and flag validation is critical.

• [ ] Examine cmd/kind/app/main.go to identify untested code paths (command initialization, subcommand routing, error handling)
• [ ] Add test cases in cmd/kind/app/main_test.go for: cobra command setup, invalid flags, missing subcommands, and help output
• [ ] Test integration with spf13/cobra to ensure version flags, help text, and subcommand execution work correctly
• [ ] Add table-driven tests for various flag combinations used in kind create cluster, delete cluster, etc.

Add shellcheck verification to pre-commit and CI for hack scripts

The repo has hack/make-rules/verify/shellcheck.sh which suggests shell linting is possible, but based on the file structure, it may not be integrated into the CI pipeline or pre-commit hooks. With extensive bash scripts in hack/ci/, hack/release/, and hack/build/, ensuring shell script quality prevents runtime failures in critical release and CI processes.

• [ ] Review hack/make-rules/verify/shellcheck.sh to confirm shellcheck rule coverage
• [ ] Add shellcheck verification step to .github/workflows (docker.yaml, nerdctl.yaml, podman.yml) if not already present
• [ ] Create or update .shellcheckrc to define consistent linting rules across all shell scripts in hack/
• [ ] Update Makefile to include shellcheck verification in the default verify target (referenced in hack/make-rules/verify/all.sh)

• Add integration test for nerdctl runtime: The repo has workflows for Docker and Podman but nerdctl.yaml suggests incomplete coverage. A new contributor could expand hack/ci/e2e.sh with nerdctl-specific paths and assertions, or create a new nerdctl-e2e.sh mirroring podman.yml structure.
• Document the Go package API for programmatic cluster creation: cmd/kind/app/main.go wraps Go packages but there's no godoc or examples/ folder showing how to use kind as a library (e.g., cluster.Create(), image.Build()). A junior could extract examples and write inline package documentation.
• Add version constraint validation in Makefile: The .go-version file specifies a precise compiler version but Makefile doesn't validate it before building. A first-time contributor could add a target that checks go version against .go-version and fails early with a helpful message.

The kubernetes-sigs/kind project has a generally solid security posture with active maintenance and established security contacts. However, there are notable concerns: (1) the Go version requirement is outdated (1.17, EOL since Aug 2023), preventing access to security patches, (2) the golang.org/x/sys dependency is significantly behind current versions, and (3) multiple YAML parsing libraries introduce unnecessary attack surface. The project would benefit from updating Go

• Medium · Outdated Go Version Requirement — go.mod (go 1.17 directive). The project specifies go 1.17 as the minimum required version. Go 1.17 reached end-of-life on 2023-08-02. This means the project may not benefit from security patches and bug fixes available in newer Go versions. Current stable versions (1.21+) include important security improvements. Fix: Update the minimum Go version to 1.21 or later to ensure security patches are applied. Update .go-version file accordingly.
• Medium · Outdated Dependency: golang.org/x/sys — go.mod (golang.org/x/sys v0.6.0). The dependency golang.org/x/sys is pinned to v0.6.0, which is outdated. This package is critical for system-level operations and security patches. The current version is significantly behind the latest releases (1.x+). Fix: Update golang.org/x/sys to the latest stable version. Run 'go get -u golang.org/x/sys' and test thoroughly.
• Low · Test-Only Dependencies in Production go.mod — go.mod (test-only transitive deps section). Test-only dependencies (gopkg.in/check.v1, github.com/niemeyer/pretty) are listed as indirect dependencies in the main go.mod file rather than being properly isolated in a tools.go or separate test module. While marked as indirect, this increases the attack surface. Fix: Consider using tools.go in hack/tools directory (which exists) consistently for all development/testing dependencies. Ensure test dependencies are properly isolated.
• Low · Multiple YAML Parsing Libraries — go.mod (go.yaml.in/yaml/v3, sigs.k8s.io/yaml). The project uses multiple YAML parsing libraries: go.yaml.in/yaml/v3 and sigs.k8s.io/yaml. Using multiple YAML parsers increases the attack surface and maintenance burden, as security issues in either library could affect the application. Fix: Evaluate if both YAML libraries are necessary. Consolidate to a single, well-maintained YAML parsing library if possible. Document why both are required if consolidation isn't feasible.
• Low · Missing Security Policy Documentation — Repository root (missing SECURITY.md). While SECURITY_CONTACTS file exists, there is no SECURITY.md file visible in the repository root. This file typically provides vulnerability reporting instructions and security policy details. Fix: Create a SECURITY.md file that follows the GitHub security policy format. Include: how to report vulnerabilities responsibly, expected response times, and supported versions for security updates.
• Low · Shell Scripts Without Visible Security Review — hack/ci/*.sh, hack/build/*.sh, hack/release/*.sh. Multiple bash scripts in hack/ directory (build scripts, CI scripts, release scripts) are present. Shell scripts are prone to injection vulnerabilities if not carefully written. The file structure doesn't indicate security-focused code review processes. Fix: Ensure all shell scripts follow security best practices: use 'set -euo pipefail', avoid eval, properly quote variables, use shellcheck (which appears to be run in verify/shellcheck.sh). Add pre-commit hooks for shell script validation.
• Low · Docker Image Build Configuration Review Needed — images/base/Dockerfile, images/base/cloudbuild.yaml. Docker images are built with various configurations (base/Dockerfile, cloudbuild.yaml). Without visibility into the actual image content, potential issues like running as root, missing security scanning, or including unnecessary tools cannot be verified. Fix: Implement security scanning in the Docker build pipeline using tools like Trivy or Grype. Ensure images run as non-root users where possible. Minimize base image size and unnecessary dependencies.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.