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

# Connecting entities to Kubernetes

This article explains how entities in Cortex get associated with Kubernetes resources. For configuration instructions, see [Configuring the integration for Kubernetes](/ingesting-data-into-cortex/integrations/kubernetes). For instructions on using the integration, see [Using the integration for Kubernetes](/ingesting-data-into-cortex/integrations/kubernetes/using-the-integration-for-kubernetes).

## Discovery

By default, Cortex uses the [Cortex tag](/ingesting-data-into-cortex/entities-overview/entities#cortex-tag) as a best guess for the Kubernetes resource. For example, if your Cortex tag is `my-entity`, the corresponding resource in Kubernetes should also be `my-entity`.

If your Kubernetes resources don't cleanly match the Cortex tag, you can override this behavior.

### Methods for mapping Kubernetes resources

There are three ways to map Kubernetes resources to Cortex entities:

| Method | Use case | What you do |
| - | - | - |
| [Annotation-based mapping](/ingesting-data-into-cortex/integrations/kubernetes/connecting-entities-to-kubernetes#annotation-based-mapping) | Entities that own their Kubernetes infrastructure. | Add a `cortex.io/tag` annotation to the Kubernetes resource. This is the default behavior. |
| [Label-based auto-mapping](/ingesting-data-into-cortex/integrations/kubernetes/connecting-entities-to-kubernetes#label-based-auto-mapping) | Shared infrastructure, or entities managed outside your team. | Specify a list of metadata label keys on the Kubernetes settings page in Cortex. |
| [Mapping in the YAML](/ingesting-data-into-cortex/integrations/kubernetes/connecting-entities-to-kubernetes#mapping-resources-in-the-entity-descriptor) | Complex or legacy workloads. | Add the resource to the YAML by hand. |

#### Annotation-based mapping

You can link a Kubernetes deployment to a Cortex entity by adding an annotation to the deployment's metadata. By default, Cortex maps Kubernetes deployments with a `cortex.io/tag` annotation to Cortex entities with the same tag.

Use `cortex.io/tag` as the key, and the value of `x-cortex-tag` in the entity's cortex.yaml as the value.

For example, if the `cortex.yaml` file is:

```yaml theme={null}
openapi: 3.0.1
info:
  title: My Service
  x-cortex-tag: my-service
  x-cortex-type: service
  description: This is my cool service.
```

Then the `deployment.yaml` file should be configured as:

```yaml theme={null}
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-name
  namespace: my-namespace
  annotations:
    cortex.io/tag: my-service
```

Cortex reads the top-level metadata annotations on the Deployment object itself (`metadata.annotations`), not the pod template annotations (`spec.template.metadata.annotations`).

**Customizing annotation mapping**

You can customize annotation mapping in Cortex:

1. From the main sidebar, select **Integrations**.
2. Locate Kubernetes, then click **Settings**.
3. From the **Integration settings** tab, locate the **K8s annotation mapping customization** section.
4. Enter a `jq` mapping in the annotation mapping field.
5. Click **Save mapping**.

If auto-mapping isn't working as expected, confirm that the annotation mapping is at the default absolute path of `.metadata.annotations."cortex.io/tag"`. If it isn't, update the annotation mapping on the Kubernetes settings page to match the exact absolute path of the Cortex tag.

**Example**

Say your `deployment.yaml` includes `my.service` as the `cortex.io/tag`:

```yaml theme={null}
metadata:
  name: my-name
  namespace: my-namespace
  annotations:
    cortex.io/tag: my.service
```

If this deployment should map to a Cortex entity with the tag `my-entity`, enter the following `jq` expression to convert all periods in the deployment annotation tag to dashes:

```
.metadata.annotations."cortex.io/tag" | gsub("\\."; "-")
```

### Label-based auto-mapping

You can override Cortex tag discovery and have Cortex discover Kubernetes resources by their metadata labels instead:

1. From the main sidebar, select **Integrations**.
2. Locate Kubernetes, then click **Settings**.
3. From the **Integration settings** tab, locate the **K8s auto-mapping customization** section.
4. Enter a list of metadata label keys.
5. Click **Save**.

Once the list is saved, Cortex discovers all Kubernetes resources that meet both of the following criteria:

* The resource's spec metadata key contains any of the specified labels.
* The key values match a Cortex entity tag.

**Example**

Say you have two Cortex entities, `example` and `entity`, and the following Kubernetes JSON blob:

```
{
  "name": "Sample Kubernetes resource",
  "metadata": {
    "labels": {
      "app": "example",
      "another": "entity"
    }
  }
}
```

By default, `example` and `entity` have no Kubernetes resource mappings. If the list of metadata labels is set to `["app"]`, then the entity example is associated with "Sample Kubernetes resource." If the list is set to `["app", "another"]`, then both example and entity are associated with the resource.

### Mapping resources in the YAML

Cortex accepts several Kubernetes resource types, which can be on different clusters: Deployments, Argo Rollouts, StatefulSets, and CronJobs.

All of these resource types share the same field definitions:

| Field | Description | Required? |
| - | - | - |
| `identifier` | `namespace/name` as found in Kubernetes. | <Icon icon="check" /> |
| `cluster` | The name of the cluster, set with the `app.clusterName` Helm value when you deploy the agent. If you run more than one agent, each one needs a unique cluster name. For more information, refer to [Installing the Cortex k8s agent in your Kubernetes cluster](/ingesting-data-into-cortex/integrations/kubernetes#installing-the-cortex-k8s-agent-in-your-kubernetes-cluster). | <Icon icon="x" /> |

**Argo Rollouts**

```yaml theme={null}
x-cortex-k8s:
  argorollout:
    - identifier: namespace/name
      cluster: dev
```

**StatefulSets**

```yaml theme={null}
x-cortex-k8s:
  statefulset:
    - identifier: namespace/name
      cluster: dev
```

**CronJobs**

```yaml theme={null}
x-cortex-k8s:
  cronjob:
    - identifier: namespace/name
      cluster: dev
```

### Importing entities from Kubernetes

For instructions on manually importing entities, see [Adding services](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/add-services).


## Related topics

- [Kubernetes](/ingesting-data-into-cortex/integrations/kubernetes.md)
- [Using the integration for Kubernetes](/ingesting-data-into-cortex/integrations/kubernetes/using-the-integration-for-kubernetes.md)
- [Connecting entities to Datadog](/ingesting-data-into-cortex/integrations/datadog/connecting-entities-to-datadog.md)