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. For instructions on using the integration, see Using the integration for Kubernetes.

Discovery

By default, Cortex uses the 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	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	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	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:

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:

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:

From the main sidebar, select Integrations.
Locate Kubernetes, then click Settings.
From the Integration settings tab, locate the K8s annotation mapping customization section.
Enter a jq mapping in the annotation mapping field.
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:

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:

From the main sidebar, select Integrations.
Locate Kubernetes, then click Settings.
From the Integration settings tab, locate the K8s auto-mapping customization section.
Enter a list of metadata label keys.
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.
`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.

Argo Rollouts

x-cortex-k8s:
  argorollout:
    - identifier: namespace/name
      cluster: dev

StatefulSets

x-cortex-k8s:
  statefulset:
    - identifier: namespace/name
      cluster: dev

CronJobs

x-cortex-k8s:
  cronjob:
    - identifier: namespace/name
      cluster: dev

Importing entities from Kubernetes

For instructions on manually importing entities, see Adding services.

Cortex

Get Started

Connect data

Standardize

Improve

Streamline

Configure

Resources

Connecting entities to Kubernetes

Discovery

Methods for mapping Kubernetes resources

Annotation-based mapping

Label-based auto-mapping

Mapping resources in the YAML

Importing entities from Kubernetes

​Discovery

​Methods for mapping Kubernetes resources

​Annotation-based mapping

​Label-based auto-mapping

​Mapping resources in the YAML

​Importing entities from Kubernetes

Discovery

Methods for mapping Kubernetes resources

Annotation-based mapping

Label-based auto-mapping

Mapping resources in the YAML

Importing entities from Kubernetes