> For the complete documentation index, see [llms.txt](https://docs.cortex.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cortex.io/ingesting-data-into-cortex/integrations/kubernetes.md).

# Kubernetes

Configuring the integration for Kubernetes

{% hint style="info" %}
Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.
{% endhint %}

## Why use the integration for Kubernetes

Kubernetes (K8s) is a container orchestration system that automates software deployment, scaling, and management. The Cortex Kubernetes agent is a lightweight agent that collects information from your cluster and surfaces it in your Cortex workspace's catalog, Scorecards, and more.

Integrating Kubernetes with Cortex allows you to:

* Discover and import entities directly from Kubernetes clusters, which keeps the catalog in sync with what's actually running in production. See [Connecting entities to Kubernetes](/ingesting-data-into-cortex/integrations/kubernetes/connecting-entities-to-kubernetes.md).
* View Kubernetes data on entity pages, which gives you visibility into your infrastructure and how entities are deployed. See [Viewing Kubernetes data on entity pages](/ingesting-data-into-cortex/integrations/kubernetes/using-the-integration-for-kubernetes.md#view-kubernetes-data-on-entity-pages).
* Create Scorecards to track progress, drive alignment on projects relating to Kubernetes, and enforce Kubernetes best practices. See [Scorecards and CQL](/ingesting-data-into-cortex/integrations/kubernetes/using-the-integration-for-kubernetes.md#scorecards-and-cql).

## Supported Kubernetes entity types

The k8s agent collects the following Kubernetes workload types:

* Deployments
* StatefulSets
* Argo Rollouts
* CronJobs

## Configuring Kubernetes

### Prerequisites

1. Users with the `Configure Integrations` permission can configure Kubernetes in Cortex.
2. Reach out to the [Cortex Customer Engineering team](mailto:help@cortex.io) for the Helm chart used for deployment, and for a username and password.
3. Generate an [API key](/configure/settings/api-keys.md#create-api-key) in Cortex. Ensure the key has the `User` (edit catalog entities) role at a minimum. Alternatively, you can also create the API key programmatically with the [Cortex API](/api/readme/api-keys.md).

### Security considerations

The k8s agent uses a push model, so you don't need to expose your cluster to the public internet. Communication out of the cluster to Cortex happens over HTTPS, and there is no inbound traffic to the agent.

The Helm chart also comes with a predefined ClusterRole that provides the correct role-based access controls (RBACs):

* **Permissions** - `["get", "watch", "list"]`
* **Resources** - `["deployments", "services", "pods", "replicationcontrollers", "statefulsets", "rollouts", "cronjobs"]`
* **API groups** - `["apps", "argoproj.io", "batch"]`

### Installing the Cortex k8s agent in your Kubernetes cluster

To connect Cortex to your Kubernetes instance, install the k8s agent in your cluster. The agent is lightweight and adds negligible impact.

1. Create a Docker image pull secret:<br>

   ```
   kubectl create secret docker-registry cortex-docker-registry-secret \
   --docker-server=ghcr.io \
   --docker-username={provided by Cortex} \
   --docker-password={token provided to you by the Cortex team} \
   --docker-email={email address}
   ```
2. Run the following command, replacing `your API key` with the value of your Cortex API key, to create a secret in your cluster:<br>

   ```
   kubectl create secret generic cortex-key --from-literal api-key=<your API key>
   ```
3. Install the Helm chart provided by Cortex:<br>

   ```
   helm install <a name to assign to the installed helm chart> ./helm-chart
   ```

{% hint style="info" %}
**Running more than one agent?** <br>

Set `app.clusterName` to a unique value for each agent you install. Agents that share a cluster name conflict with each other, which can cause intermittent 409 errors and make Kubernetes data disappear from entity pages.

```
helm install <a name to assign to the installed helm chart> ./helm-chart --set app.clusterName=<a unique name for this cluster>
```

You need a unique `app.clusterName` any time more than one agent reports to the same Cortex account, including when an agent is deployed inside a parent Argo environment or when you run an agent in each of several clusters.

The value you set here is the value Cortex uses for the `cluster` field when you map Kubernetes resources to entities in an entity descriptor. For more information, refer to [Mapping resources in the YAML](/ingesting-data-into-cortex/integrations/kubernetes/connecting-entities-to-kubernetes.md#mapping-resources-in-the-yaml).
{% endhint %}