init

README.md

@@ -1,3 +1,73 @@
-# k8s-demo
+# Kubernetes Local Cluster Demonstration
 
-Kubernetes demonstration
+Kubernetes demonstration on your local machine
+
+## Prerequisites
+
+1. Make sure to have docker or a OCI compatibile container engine installed
+1. Make sure the docker/oci engine is running
+1. Install `kubectl` for interacting with the kube api:
+    - https://kubernetes.io/docs/tasks/tools/
+1. Install `kind`
+    - mac/brew: `brew install kind`
+    - mac/macports: `sudo port selfupdate && sudo port install kind`
+    - win/choco: `choco install kind`
+    - win/winget: `winget install Kubernetes.kind`
+    - linux: tbd
+1. Have at least 8GB RAM and 20GB disk
+
+## Create cluster
+
+1. `kind create cluster --config cluster-config/config.yaml` (1 control plane, 3 nodes)
+1. Once complete, look at what is running in all namespaces: `kubectl get pods -A`
+
+```
+$ kubectl get pods -A
+NAMESPACE            NAME                                         READY   STATUS    RESTARTS   AGE
+kube-system          coredns-76f75df574-ddznd                     1/1     Running   0          7m16s
+kube-system          coredns-76f75df574-ftv2c                     1/1     Running   0          7m16s
+kube-system          etcd-demo-control-plane                      1/1     Running   0          7m31s
+kube-system          kindnet-jj8bv                                1/1     Running   0          7m16s
+kube-system          kube-apiserver-demo-control-plane            1/1     Running   0          7m31s
+kube-system          kube-controller-manager-demo-control-plane   1/1     Running   0          7m31s
+kube-system          kube-proxy-2wr8l                             1/1     Running   0          7m16s
+kube-system          kube-scheduler-demo-control-plane            1/1     Running   0          7m31s
+local-path-storage   local-path-provisioner-7577fdbbfb-jj2b7      1/1     Running   0          7m16s
+```
+
+You will want to wait for all pods to become ready (showing `1/1` in the `READY` field) and once complete you will have a cluster running on your computer.
+
+## Run services
+
+### Ingress Controller (nginx)
+
+Ingress controllers manage incoming web traffic (usually HTTP/HTTPS)
+
+1. `kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/deploy/static/provider/kind/deploy.yaml`
+
+Wait for it to become available:
+
+```bash
+kubectl wait --namespace ingress-nginx \
+  --for=condition=ready pod \
+  --selector=app.kubernetes.io/component=controller \
+  --timeout=300s
+```
+
+Usually you'll want to next install a load balancer, but for a single node cluster this is not required.
+
+### Observability
+
+tbd - grafana, prometheus, alertmanager, thanos, servicemonitor, podmonitor
+
+### Sublinks in k8s
+
+tbd
+
+## Troubleshooting
+
+tbd
+
+## Cleanup
+
+1. `kind delete cluster`

cluster-config/cluster.yaml

@@ -0,0 +1,17 @@
+kind: Cluster
+apiVersion: kind.x-k8s.io/v1alpha4
+nodes:
+- role: control-plane
+  kubeadmConfigPatches:
+  - |
+    kind: InitConfiguration
+    nodeRegistration:
+      kubeletExtraArgs:
+        node-labels: "ingress-ready=true"
+  extraPortMappings:
+  - containerPort: 80
+    hostPort: 80
+    protocol: TCP
+  - containerPort: 443
+    hostPort: 443
+    protocol: TCP