k8s-gitops-controller

Lightweight Express API. Reads/writes a deployment config YAML in a GitHub repo and applies nginx to a local kind cluster.

Purpose of this assignment is essentially to boostrap a minor gitOps workflow showcasing knowledge of K8s, API developemnt etc.

This API can be ran locally and in cluster and basically hosts a few endpoints and has read/write access on this repo to deploy nginx deployments although it could deploy anything in a real world scenario would be some actual app with adequate business logic.

Requires GITHUB_TOKEN in .env or in k8s secret when applied to kind cluster

Acceptance criteria

Verify functionality with make test

1. List repos (name, visibility, default branch, URL, …)
2. List branches for owner/repo
3. Read YAML → JSON (name, replicas, annotations, optional content)
4. PUT partial updates to YAML on GitHub; comments and extra keys preserved
5. POST nginx Deployment + Service (optional replicas, default 1)
6. DELETE Deployment + Service by name/namespace
7. POST from-repo → deploy using yaml (repo-branch namespace)
8. Same endpoint; yaml content → ConfigMap mounted at /usr/share/nginx/html

API

Base URL: http://localhost:3000 (override with PORT in env).

Method	Path	Notes
GET	/repos	List repos for the PAT user
GET	/repos/{owner}/{repo}/branches	List branches
GET	/repos/{owner}/{repo}/contents?branch=&path=	Read + parse YAML
PUT	/repos/{owner}/{repo}/contents?branch=&path=	Patch YAML fields, commit to GitHub
POST	/deployments	Create nginx Deployment + Service
DELETE	/deployments	Delete Deployment + Service (+ ConfigMap if any)
POST	/deployments/from-repo	Deploy from repo YAML (repo-branch namespace)

Prereqs

• Node.js 20+
• kind
• podman

Run locally

cp .env.example .env   # put your PAT in GITHUB_TOKEN  https://github.com/settings/tokens
npm install
make cluster           # creates the cluster and writes kind/kubeconfig
make test         # local: starts API with npm, runs test.sh
make destroy # destroy kind cluster 

Run In kind cluster

cp k8s/deploy/secret.example k8s/deploy/secret.yaml # add gitlab secret here or edit live in cluster in git ignore do not commit would be stored in AWS secrets manager or equivalent in actual cluster 
make cluster
make deploy       # podman build, load into kind, apply k8s/deploy/
make cluster-test # port-forward svc/k8s-glab-api:80 → localhost:3000, then test.sh
make undeploy
make destroy # destroy kind cluster 
rm k8s/deploy/secret.yaml

No make run needed in-cluster — the API runs in the pod; cluster-test port-forwards the service.

Repo layout:

• k8s/nginx-deploys/ — sample yaml on GitHub (nginx workloads)
• k8s/deploy/ — manifests for this API in the cluster

export KUBECONFIG=/Users/bwilkinson@alpha-sense.com/Documents/GitHub/k8s-glab-api-task/kind/kubeconfig
k9s