> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Job Configuring Kubeconfig file

> This guide explains how to inject a Kubernetes kubeconfig into a GitLab CI pipeline for kubectl authentication and cluster interaction.

In this guide, you’ll learn how to inject your Kubernetes `kubeconfig` into a GitLab CI pipeline so that `kubectl` can authenticate and interact with your cluster. This setup is essential for automated deployments, health checks, and infrastructure management within your CI/CD workflows.

## Why You Need to Provide a Kubeconfig

When `kubectl` runs without a valid `kubeconfig`, it can only display client information and will fail to contact the API server:

```yaml theme={null}
# .gitlab-ci.yml (without KUBECONFIG)
k8s_dev_deploy:
  stage: dev-deploy
  image: alpine:3.7
  before_script:
    - wget https://storage.googleapis.com/kubernetes-release/release/\
$(wget -q -O - https://storage.googleapis.com/kubernetes-release/stable.txt)/\
bin/linux/amd64/kubectl
    - chmod +x kubectl && mv kubectl /usr/bin/kubectl
  script:
    - kubectl version -o yaml
```

Attempting to run the job yields:

```bash theme={null}
$ kubectl version -o yaml
ClientVersion:
  gitVersion: v1.29.1
...
ERROR: Job failed: exit code 1
```

Without server credentials in a `kubeconfig`, `kubectl` cannot reach your cluster’s API endpoint.

## Local vs. CI: Kubernetes Authentication

### On Your Local Machine

With a valid `~/.kube/config`, you will see both client and server versions:

```bash theme={null}
$ kubectl version -o yaml
```

```yaml theme={null}
clientVersion:
  gitVersion: v1.29.1
serverVersion:
  gitVersion: v1.29.1
```

Your trimmed `kubeconfig` might look like this:

```yaml theme={null}
apiVersion: v1
clusters:
- name: vke-cluster
  cluster:
    server: https://example-cluster:6443
    certificate-authority-data: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0t...
contexts:
- name: vke-cluster
  context:
    cluster: vke-cluster
    user: admin
current-context: vke-cluster
kind: Config
users:
- name: admin
  user:
    client-certificate-data: <omitted>
    client-key-data: <omitted>
```

Verify your context and nodes locally:

```bash theme={null}
kubectl config get-contexts
kubectl get nodes
```

## Storing Kubeconfig in GitLab CI/CD

To securely pass your `kubeconfig` into CI jobs, add it as a **File**-type variable in your project’s CI/CD Settings:

| Key               | Type | Value                             | Environment Scope |
| ----------------- | ---- | --------------------------------- | ----------------- |
| `DEV_KUBE_CONFIG` | File | *Paste entire kubeconfig content* | All (or specific) |

<Frame>
  ![The image shows a GitLab CI/CD settings page where variables are being managed, with options to add a new variable and configure its type and flags.](https://kodekloud.com/kk-media/image/upload/v1752877199/notes-assets/images/GitLab-CICD-Architecting-Deploying-and-Optimizing-Pipelines-Job-Configuring-Kubeconfig-file/gitlab-ci-cd-variables-settings.jpg)
</Frame>

<Callout icon="triangle-alert" color="#FF6B6B">
  Treat your `kubeconfig` as sensitive data. File variables are stored encrypted, but avoid exposing them in job logs or unsecured scopes.
</Callout>

## Updating the CI Job to Use Kubeconfig

Modify your `.gitlab-ci.yml` job to export the `KUBECONFIG` environment variable from the File variable before invoking any `kubectl` commands:

```yaml theme={null}
# .gitlab-ci.yml
k8s_dev_deploy:
  stage: dev-deploy
  image: alpine:3.7
  before_script:
    - wget https://storage.googleapis.com/kubernetes-release/release/\
$(wget -q -O - https://storage.googleapis.com/kubernetes-release/stable.txt)/\
bin/linux/amd64/kubectl
    - chmod +x kubectl && mv kubectl /usr/bin/kubectl
  script:
    - export KUBECONFIG=$DEV_KUBE_CONFIG
    - kubectl version -o yaml
    - kubectl config get-contexts
    - kubectl get nodes
```

Commit your changes and trigger the pipeline. The `k8s_dev_deploy` job should now complete successfully:

<Frame>
  ![The image shows a GitLab CI/CD job interface where a job named "k8s\_dev\_deploy" has successfully passed. The job log details the steps executed, and the interface includes project navigation options on the left.](https://kodekloud.com/kk-media/image/upload/v1752877201/notes-assets/images/GitLab-CICD-Architecting-Deploying-and-Optimizing-Pipelines-Job-Configuring-Kubeconfig-file/gitlab-ci-cd-k8s-dev-deploy.jpg)
</Frame>

## Verifying the CI Job Output

With the kubeconfig in place, your CI job will display both client and server details and list the cluster nodes:

```bash theme={null}
$ kubectl version -o yaml
ClientVersion:
  gitVersion: v1.29.1
ServerVersion:
  gitVersion: v1.29.1

$ kubectl config get-contexts
CURRENT   NAME            CLUSTER         AUTHINFO
*         vke-cluster     vke-cluster     admin

$ kubectl get nodes
NAME                  STATUS   ROLES    AGE   VERSION
gitlab-node-1         Ready    <none>   5h    v1.29.1
gitlab-node-2         Ready    <none>   5h    v1.29.1
```

## Further Reading and References

* [Kubernetes Configuration Best Practices](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/)
* [GitLab CI/CD Variables Documentation](https://docs.gitlab.com/ee/ci/variables/#file-type)
* [Kubectl Cheat Sheet](https://kubernetes.io/docs/reference/kubectl/cheatsheet/)

<CardGroup>
  <Card title="Watch Video" icon="video" cta="Learn more" href="https://learn.kodekloud.com/user/courses/gitlab-ci-cd-architecting-deploying-and-optimizing-pipelines/module/df17ec22-8cda-4af7-af44-10f9f061d4a8/lesson/17485780-3db2-4065-b9dd-16389dd03093" />
</CardGroup>