Introduction

When kubectl works in your shell but fails from Ansible, the problem is usually not Kubernetes itself. It is usually execution context: a different user, a missing PATH, a missing KUBECONFIG, or the fact that Ansible is running the command on a remote host that does not have the same local cluster access as your terminal.

First Check Where the Command Runs

Ansible tasks run on the managed host by default, not automatically on your local control machine.

That means this task:

- name: Get pods
  command: kubectl get pods

runs wherever the target host is, not necessarily on the laptop where your working kubeconfig lives.

If kubectl should run locally, delegate the task:

- name: Get pods locally
  command: kubectl get pods
  delegate_to: localhost

This alone resolves many "but it works in my terminal" problems.

Set KUBECONFIG Explicitly

Interactive shells often export KUBECONFIG, but Ansible tasks do not inherit your full interactive environment automatically.

1- name: Get pods with explicit kubeconfig
2  command: kubectl get pods -n default
3  environment:
4    KUBECONFIG: /home/ansible/.kube/config

If the kubeconfig path is wrong or missing for the Ansible execution user, kubectl cannot authenticate even if the binary itself is installed.

Use the Full Binary Path

If PATH is the problem, call kubectl by absolute path:

- name: Run kubectl with explicit path
  command: /usr/local/bin/kubectl get nodes

You can also set PATH through environment, but an explicit binary path is often the fastest diagnostic step.

Check the Effective User

If the play uses become: true, Ansible may run kubectl as a different user than the one you tested manually. That changes:

• home directory
• kubeconfig path
• shell initialization
• filesystem permissions

A command that works for your login user may fail immediately for root or for a service account user with no Kubernetes credentials.

Capture Output and Fail Clearly

Do not let the task fail silently. Register the result and inspect it:

1- name: Check cluster access
2  command: kubectl get ns
3  register: kubectl_result
4  changed_when: false
5
6- debug:
7    var: kubectl_result.stderr

That gives you the actual error message instead of a vague "command failed" impression.

Prefer Kubernetes Modules When Possible

If your playbook is doing Kubernetes operations repeatedly, consider Ansible's Kubernetes modules instead of shelling out to kubectl.

1- name: Ensure namespace exists
2  kubernetes.core.k8s:
3    state: present
4    definition:
5      apiVersion: v1
6      kind: Namespace
7      metadata:
8        name: demo

This is often cleaner and more idempotent than wrapping many raw CLI commands in command tasks.

Common Pitfalls

The most common mistake is forgetting that Ansible runs commands on the target host by default. If your kubeconfig exists only on your workstation, the remote host cannot use it.

Another issue is relying on a login shell setup that Ansible never reads. Aliases, shell profiles, and interactive environment exports often do not exist in task execution.

A third pitfall is using become without noticing that the effective user changed. The new user may not have the same kubeconfig file, credentials, or PATH.

Finally, if you are only using kubectl because it feels familiar, remember that Ansible's Kubernetes modules often give better structured results and cleaner playbooks.

Summary

• 'kubectl failures in Ansible are often environment or execution-location problems.'
• Confirm whether the command should run on the remote host or on localhost.
• Set KUBECONFIG and the binary path explicitly when needed.
• Register output so you can see the real error.
• Prefer kubernetes.core.k8s modules over raw shell commands when the task is a declarative Kubernetes operation.