The Cosmos is all that is or was or ever will be. Our feeblest contemplations of the Cosmos stir us — there is a tingling in the spine, a catch in the voice, a faint sensation, as if a distant memory, of falling from a height. We know we are approaching the greatest of mysteries.
--- ``` ###### Create Dockerfile Next I will create the Dockerfile. This file will define a container that will serve the static web page `index.html` using nginx. The Dockerfile will remove all of the default files that ship with `nginx:alpine` and replace them with the contents of my `site` directory, which contains only `index.html`. **`Dockerfile`** ```Dockerfile FROM nginx:alpine RUN rm -rf /usr/share/nginx/html/* COPY ./site/ /usr/share/nginx/html/ EXPOSE 80 ``` --- ###### Set up credentials for image registry (gitea) One step in the workflow involves pushing the newly-built application Docker image to my registry. To push, I will need to authenticate with the Gitea server. To do this, I will use a GitHub action called `login-action@v3` found in the [GitHub Actions marketplace](https://github.com/marketplace?type=actions). This action requires a few inputs to work: - Registry URL - Username - Password (access token) The registry URL and username inputs are straightforward and I can pass these variables along as strings. The access token will need to be passed as a secret. First I generate an access token in Gitea. I will name this `gitea-package-registry` and give it only the package write permission. {{< image src="images/gitea-access-token-generate.png" caption="Generate registry token" >}} Next I will store this as a secret so that I can securely pass it to the runner. I name the secret `REGISTRY_TOKEN` {{< image src="images/gitea-access-token-secret.png" caption="Store registry token secret" >}} {{< image src="images/registry-token-created.png" caption="Gitea registry token" >}} I can reference this secret in my workflow file `${{ secrets.REGISTRY_TOKEN }}`. --- ###### Store kubeconfig as Gitea secret My workflow file needs access to one more secret: my `kubeconfig.yml`. Storing this as a secret is not as straightforward as the registry access token, since I cannot store a file directly as a secret. I will need encode the file as a base64 string, store *that* string as a secret named `KUBECONFIG_DATA`, and decode the string back into the `kubeconfig.yml` file. First, my k3s container is configured to automatically produce a `kubeconfig.yml` and output it to the specified directory. I have included the relevant configuration from my `docker-compose.yml` file as context. **`docker-compose.yml` snippet** ```yaml environment: - K3S_KUBECONFIG_OUTPUT=/output/kubeconfig.yml volumes: - ./k3s:/output ``` On my host machine, I can locate the generated `kubeconfig.yml` file at `./k3s/kubeconfig.yaml`. Next, I run the following command to base64-encode it and write the result to `kubeconfig.b64`. ```shell base64 -w 0 kubeconfig.yaml > kubeconfig.b64 ``` The contents of `kubeconfig.b64` is a string that will be stored as a secret in Gitea: {{< image src="images/kubeconfig-data.png" caption="Base64 encoded secret" >}} I will reference this secret in my **Gitea Action workflow**, which is defined in yet another yaml file-- this one stored in the same `workflows` directory as the `demo.yml` created in earlier step, during initial stages of setting up the pipeline. ```plaintext 📂proving-ground/ └─📂.gitea/ └─📂workflows/ ├─demo.yml └─deploy.yml ``` --- ###### Action Workflow file - deploy static web page The workflow file defines several steps that will compose the deployment process: - **⬇️Checkout** app repository (`proving-ground`) - **🔐Login** to Gitea package registry - **🐋Build** Docker image from Dockerfile - **🚀Push** new image to package registry - **🛠️Install** `kubectl` - **🔑Decode** `KUBECONFIG_DATA` secret and write local **`kubeconfig.yml`** file; Use this file as `KUBECONFIG` env. - **🚀Test / Deploy** to Kubernetes cluster via API - **🧹Prune** images The `kubectl` CLI utility uses my `kubeconfig.yml` file to authenticate and connect to the Kubernetes cluster in the k3 container. It communicates with the Kubernetes API over HTTP/HTTPS (`https://server:6443`). **deploy.yml** ```yaml name: Deployment on: push: branches: - master workflow_dispatch: jobs: deploy-site: name: 'deploy' env: REGISTRY_USERNAME: nicholas IMAGE_REGISTRY: git.uuard.com IMAGE_NAME: nicholas/proving-ground IMAGE_TAG: latest runs-on: ubuntu-latest steps: - name: ⬇️ Checkout repo uses: actions/checkout@v4 - name: 🔐 Gitea Registry Login uses: docker/login-action@v3 with: registry: ${{ env.IMAGE_REGISTRY }} username: ${{ env.REGISTRY_USERNAME }} password: ${{ secrets.REGISTRY_TOKEN }} - name: 🐋 Build Docker image run: docker build -t $IMAGE_REGISTRY/$IMAGE_NAME:$IMAGE_TAG ./container - name: 🚀 Push Docker image run: docker push $IMAGE_REGISTRY/$IMAGE_NAME:$IMAGE_TAG - name: 🛠️ Setup kubectl uses: azure/setup-kubectl@v4 with: version: 'latest' - name: 🔑 Configure Kubeconfig run: | echo "${{ secrets.KUBECONFIG_DATA }}" | base64 -d > kubeconfig.yml - name: 🧪 Test access env: KUBECONFIG: kubeconfig.yml run: kubectl get nodes - name: 🚀 Deploy to k3s env: KUBECONFIG: kubeconfig.yml run: | kubectl apply -f k8s/deployment.yml kubectl apply -f k8s/service.yml kubectl apply -f k8s/ingress.yml kubectl rollout restart deployment proving-ground kubectl rollout status deployment/proving-ground - name: 🧹 Cleanup images if: always() run: docker image prune -f ``` --- ###### Diagram This diagram shows the relationship between the various containers. ```mermaid graph TD subgraph host[Host] subgraph docker[Docker] subgraph kubernetes[Kubernetes / k3s] subgraph pod[Pod] container["NGINX"] end end gitea-server[Gitea Server] gitea-runner[Gitea Action Runner] gitea-server <--> gitea-runner gitea-runner --Kubernetes API--> kubernetes end end ``` --- ###### Kubernetes deployment manifest My Kubernetes manifest defines a basic static website deployment using the NGINX container image `proving-ground:latest`. The manifest configuration includes three resource types: - **Deployment** (`deployment.yml`) - `kubectl apply -f k8s/deployment.yml` - Runs the NGINX container inside a pod - **Service** (`service.yml`) - `kubectl apply -f k8s/service.yml` - Exposes the pod containing the NGINX app, makes it accessible inside the cluster - **Ingress** (`ingress.yml`) - `kubectl apply -f k8s/ingress.yml` - Configures routing rules to expose NGINX app externally **deployment.yaml** ```yaml apiVersion: apps/v1 kind: Deployment metadata: name: proving-ground labels: app: proving-ground-static-site spec: replicas: 1 selector: matchLabels: app: proving-ground-static-site template: metadata: labels: app: proving-ground-static-site spec: containers: - name: nginx image: git.uuard.com/nicholas/proving-ground:latest ports: - containerPort: 80 ``` **ingress.yml** ```yaml apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: proving-ground-static-site-ingress spec: rules: - host: server http: paths: - path: / pathType: Prefix backend: service: name: proving-ground-static-site-service port: number: 80 ``` **service.yml** ```yaml apiVersion: v1 kind: Service metadata: name: proving-ground-static-site-service spec: selector: app: proving-ground-static-site ports: - protocol: TCP port: 80 targetPort: 80 type: LoadBalancer ``` --- ###### Site repo directory structure This is the complete repository directory structure. ``` 📁proving-ground ├─📁.gitea │ └─📁workflows │ ├─demo.yml │ └─deploy.yml ├─📁container │ ├─Dockerfile │ └─📁site │ └─index.html └─📁k8s ├─deployment.yml ├─ingress.yml └─service.yml ``` --- ###### Test Kubernetes API / kubectl Now I can test the Kubernetes connection by running `kubectl get nodes`. If this step succeeds, I have verified the connection between the runner container and Kubernetes. I can trigger this build by either pushing to `master` or manually triggering the build via Gitea UI. {{< image src="images/k3s-test-success.png" caption="Deployment test success" >}} **✅ It works** --- ###### Deploy Now I deploy the app. I simply push changes to the repository, and voilà, my app is live. {{< image src="images/k3s-deploy-success.png" caption="Deployment success" >}} {{< image src="images/view-site-deployment.png" caption="View deployment in browser" >}} **🎉 It works!** Done.