Jenkins Kubernetes Plugin Pod Template Failure - Fix Agent Pods

The Kubernetes plugin tried to schedule an agent pod and it never became a usable agent. The pod is stuck Pending (no resources/node), failed to pull its image, hit an RBAC/quota error, or started but never connected back to the controller.

What this error means

A build waits for a Kubernetes agent that never starts. The pod shows Pending, ImagePullBackOff, or CrashLoopBackOff, or the plugin logs that the pod was deleted before the agent connected. The job sits queued or fails after the provisioning timeout.

Jenkins console / kubectl

Created Pod: jenkins-agent-9k2lp
Pod 'jenkins-agent-9k2lp' is now Pending: Insufficient cpu
# or
Back-off pulling image "registry.example.com/jnlp-agent:bad-tag" (ImagePullBackOff)

Common causes

Pod cannot be scheduled

Insufficient CPU/memory, a missing node selector/toleration, or a namespace quota leaves the pod Pending, so no agent ever comes up.

Image pull or container start failure

A wrong image, missing imagePullSecret, or a crashing container (ImagePullBackOff/CrashLoopBackOff) prevents the agent container from running.

RBAC or pod template misconfiguration

The Jenkins service account lacks permission to create/delete pods, or the pod template/JNLP container is misconfigured so the agent never connects back.

How to fix it

Fix the pod template and resources

Pin a reachable image, set sane requests/limits, and ensure the JNLP container can reach the controller.

Jenkinsfile

podTemplate(yaml: '''
apiVersion: v1
kind: Pod
spec:
  containers:
  - name: jnlp
    image: jenkins/inbound-agent:latest
    resources:
      requests: { cpu: "500m", memory: "1Gi" }
      limits:   { cpu: "1",    memory: "2Gi" }
''') {
  node(POD_LABEL) { sh 'make build' }
}

Diagnose with kubectl and fix RBAC

Run kubectl describe pod <name> to see why it is Pending/failing (resources, image, scheduling).
Add the missing imagePullSecret, node selector/toleration, or raise the namespace quota.
Grant the Jenkins service account RBAC to create/delete/watch pods in the agent namespace.

How to prevent it

Pin agent images to reachable tags with the right imagePullSecret.
Set realistic resource requests/limits so pods schedule reliably.
Give the Jenkins service account least-privilege pod RBAC in the agent namespace.