[FAQ]

[chakirou18]

Course

ai-dev-tools-zoomcamp

Question

Why does my Kubernetes deployment work locally with act but fail on GitHub Actions with "could not locate any control plane nodes for cluster named 'agent-relay'"?

Answer

A GitHub-hosted runner starts with a fresh environment and does not contain the local kind cluster that may already exist on your development machine.

This can cause the workflow to fail with:

ERROR: could not locate any control plane nodes for cluster named 'agent-relay'.

Before loading the Docker image into kind or deploying the Kubernetes manifests, make sure the cluster exists.

For example:

if ! kind get clusters | grep -qx "agent-relay"; then
kind create cluster --name agent-relay
fi

After the cluster is created, the workflow can continue with:

1. Loading the Docker image into kind.
2. Applying the Kubernetes manifests.
3. Waiting for the deployment rollout.
4. Verifying the deployed API.

This issue may not appear when testing locally with act if a kind cluster named "agent-relay" already exists on the local machine.

Checklist

• I have searched existing FAQs and this question is not already answered
• The answer provides accurate, helpful information
• I have included any relevant code examples or links

[github-actions]

✅ FAQ NEW proposal created in PR #408

Please review and approve the changes.

[chakirou18]

This error usually means that the GitHub Actions runner does not have the kind cluster that your workflow is trying to use.

A workflow may work locally with act because a kind cluster already exists on your machine. However, GitHub-hosted runners start with a fresh environment for each job, so your local agent-relay cluster is not available there.

You can check the available kind clusters with:

kind get clusters

If agent-relay is missing, create it before trying to load the Docker image or deploy the Kubernetes manifests:

if ! kind get clusters | grep -qx "agent-relay"; then
kind create cluster --name agent-relay
fi

The CI/CD order should then be:

1. Run the tests.
2. Build the Docker image.
3. Install/verify kind and kubectl.
4. Create the kind cluster if it does not exist.
5. Load the Docker image into the cluster.
6. Apply the Kubernetes manifests.
7. Wait for the deployment rollout.
8. Verify the deployed API.

For example:

kind load docker-image <IMAGE_NAME> --name agent-relay
kubectl apply -f k8s/
kubectl rollout status deployment/agent-relay

The important point is that a GitHub-hosted runner is ephemeral. Do not assume that a local kind cluster already exists, even if the same workflow works with act on your machine.