kubernetes

The Problem

Running containerized applications across multiple hosts requires solving scheduling, service discovery, rolling updates, and failure recovery. Kubernetes addresses these by providing a control plane that reconciles desired state (deployments, services) with cluster reality, so operators declare what they want rather than scripting how to get there.

What This Does

This repository is a fork of kubernetes/kubernetes (125k stars upstream) containing the full Kubernetes source tree: cmd/ holds component entry points (kube-apiserver, kube-controller-manager, kubectl), pkg/ holds the core control-plane logic, staging/ contains the versioned client libraries, and vendor/ pins dependencies. The build/ directory provides Dockerfiles for server images and the pause container.

It is a collection of eight self-contained projects, not a single codebase. The substantial ones are the API server (cmd/kube-apiserver), the scheduler (pkg/scheduler), and the kubelet agent (pkg/kubelet), each with deep test coverage (15,078 test files).

How It Is Wired

Execution starts at cmd/kube-apiserver/apiserver.go, which initializes the API machinery in staging/src/k8s.io/apiserver and serves the REST API. The control flow is: API server validates and persists objects to etcd (external dependency), the controller manager in cmd/cloud-controller-manager watches those objects and acts, and the scheduler in pkg/scheduler assigns pods to nodes. The kubelet on each node then executes the pod spec via the container runtime.

The widest blast radius is the API server: it is the single entry point for all cluster state changes, and every component depends on it. The staging/src/k8s.io/api directory defines the versioned object schemas that everything else imports. Changing a field there ripples through all components. The module graph shows a hub-and-spoke pattern centered on staging/, which is intentional: it lets the project publish client libraries independently. The cost is that local changes to staging/ require regeneration and vendoring steps, which adds friction.

How To Use It

Setup: requires a Go environment (.go-version present) or Docker. Build commands from the README:

git clone https://github.com/moses-y/kubernetes
cd kubernetes
make

Or with Docker: make quick-release.

Configuration: no runtime env vars are documented in the repo. Cluster configuration is YAML manifests under cluster/ for deployment scenarios.

Running it: there is no single binary entry point. You build the components (make produces kube-apiserver, kubelet, kubectl under _output/bin/) and run them as separate processes. The Makefile at the root orchestrates the build. For a local cluster, hack/local-up-cluster.sh is the documented path, but its exact flags are not in the file structure provided.

Real-World Use

A production scenario: you define a Deployment manifest specifying 3 replicas of a web service. Submit it via kubectl apply -f deployment.yaml. The API server persists it to etcd, the deployment controller creates a ReplicaSet, the scheduler assigns pods to nodes, and kubelets pull the image and start containers. If a node dies, the controller recreates the pods elsewhere. This is the standard pattern for running stateless services at scale.

Code Health & Issues

Static analysis found 3 issues (0 critical, 1 high, 2 medium):

• High - No build gate for deployable artifacts - build/pause/Dockerfile. The pause container image has no CI workflow validating it builds. Add a workflow that builds the image and validates manifests.
• Medium - No dependency update bot - 38 manifest files, no Dependabot/Renovate configured. Advisories stay unpatched until manual audit. Commit .github/dependabot.yml.
• Medium - Large binary in repo - staging/src/k8s.io/kubectl/testdata/openapi/swagger.json at 5.1MB. Every clone pays for it. Move to Git LFS or object storage.

The repo has tests, CI (Travis), Dockerfiles, a license, a lockfile, and committed secrets flagged for audit. The fork has zero stars, so it is a personal copy of upstream rather than a maintained derivative.

The Bottom Line

This is a faithful snapshot of upstream Kubernetes with no substantive modifications evident. Use it as a reference or starting point for Kubernetes development; do not expect it to be a maintained fork. The codebase is enormous and complex, and the health findings are minor hygiene issues typical of a personal mirror.