Write clear documentation on how to test GHA Config with a local KIND cluster

[jeefy]

[Ryder-07]

The documentation need to be in this repo, right??

[Aaravanand00]

Hi sir I'm Aarav Anand 1st yr student I found this issue and here is the solution
how to set up KIND + test GHA config locally.

Documentation: How to Test CNCF Automation GHA Configuration Using a Local KIND Cluster

This document provides a clear, reproducible workflow for testing the CNCF Automation project’s GitHub Actions (GHA) configuration locally using a KIND (Kubernetes-in-Docker) cluster.
The purpose is to enable contributors to validate changes to CI runner images, cluster configuration, and workflow logic before opening a pull request.

1. Introduction

The CNCF Automation repository includes tooling under:

ci/gha-runner-image/
ci/gha-runner-vm/
ci/services/cluster/

These components define how GitHub Action runners are built, provisioned, and executed inside Kubernetes clusters provided to CNCF.
However, the repository currently lacks end-to-end documentation on how to test these configurations locally.

This guide outlines a complete workflow to:

Set up a KIND cluster

Build and load the GHA runner VM image

Deploy runner components

Trigger and validate workflow execution

This documentation aims to simplify onboarding and make local testing accessible for new contributors.

2. Prerequisites

You should have the following installed:

Docker

KIND → https://kind.sigs.k8s.io

kubectl

Go 1.21+

GitHub CLI (optional but recommended)

Verify installation:

docker --version
kind --version
kubectl version --client
go version

3. Create and Prepare a KIND Cluster

Create a new cluster for testing CI components:

kind create cluster --name cncf-ci

Confirm node status:

kubectl get nodes

You should see a single Ready node.

4. Build the GHA Runner VM Image

Navigate to the runner VM directory:

cd ci/gha-runner-vm

Build the Go binary:

go build -o gha-runner main.go

Build the Docker image:

docker build -t cncf/gha-runner:local .

Load the image into the KIND cluster:

kind load docker-image cncf/gha-runner:local --name cncf-ci

KIND runs inside Docker, so images must be explicitly loaded.
Otherwise, Kubernetes will fail to pull local runner images.

5. Deploy Runner Components Into KIND

Move to the cluster deployment directory:

cd ../services/cluster

Apply all required manifests:

kubectl apply -f .

This deploys:

Required namespaces

Service accounts & RBAC

Runner VM workload

Supporting cluster utilities

Check pod status:

kubectl get pods -n gha-system

Wait until all pods reach the Running state.

6. Validate Runner Functionality
   Check runner logs
   kubectl logs -n gha-system

A successful runner should display:

Connected to GitHub…
Listening for workflow jobs…

If this connection is not established, re-check image loading steps.

7. Test the GHA Configuration

There are two ways to verify workflow execution.

Option A — Run a Dry-Run Using GitHub CLI
gh workflow run --dry-run

This validates:

Workflow syntax

Required secrets

Trigger compatibility

Option B — Execute a Real Workflow in the Local Runner

Create a test commit:

git commit -am "test gha config locally"
git push origin test-branch

GitHub will queue a job.
The runner inside your KIND cluster should pick it up automatically.

Watch live logs:

kubectl logs -f -n gha-system

If the runner completes the job successfully, your GHA config is working as expected.

8. Cleaning Up

Delete the local cluster:

kind delete cluster --name cncf-ci

9. Notes & Recommendations

KIND provides a fast, isolated environment ideal for debugging CI runner logic.

Local testing significantly reduces turnaround time when working on gha-runner-image or gha-runner-vm.

Contributors modifying CI workflows should always validate changes locally before creating a PR.

This testing flow also helps detect Kubernetes RBAC issues, container image errors, or workflow misconfigurations early.

10. Conclusion

This documentation provides a complete, reproducible workflow for testing CNCF Automation GitHub Actions configurations using a local KIND cluster.
It aims to reduce contributor friction, improve testing reliability, and ensure that workflow changes are validated before they reach production CI environments.

If additional test cases, troubleshooting tips, or automation scripts are needed, they can be added in future iterations.