Skip to main content
This article explains how to use the integration for Kubernetes. For configuration instructions, see Configuring the integration for Kubernetes. For instructions on connecting Kubernetes resources to entities, see Connecting entities to Kubernetes.

​
Viewing Kubernetes data on entity pages

Kubernetes deployment data is available in the Kubernetes block on an entity’s details page for entities imported from Kubernetes or linked to a Kubernetes resource. In the entity’s side panel, click Environments to see Kubernetes deployments, clusters, active replicas, and pending deployments, as well as:
  • Replicas - The number of available, ready, and desired replicas.
  • Containers - Resource containers, including requested memory, memory limit, and CPU data. This also includes the full container definition.

​
Creating Scorecard rules and writing CQL queries with the Kubernetes integration

With the Kubernetes integration, you can create Scorecard rules and write Cortex Query Language (CQL) queries based on Kubernetes resources. For an example, see Cortex’s prebuilt Kubernetes Deployment Baseline Scorecard template. See more rule examples in the CQL Explorer in Cortex.
Data about k8s clusters associated with a given entity.Definition - k8s.clusters()ExamplesYou can use the k8s.clusters() expression in the Query Builder to find all clusters that start with “dev”:
Or any cluster named “prod”:
Checks deployment metadata.Definition - k8s.metadata()ExamplesYou can use this expression in a production readiness Scorecard to check ownership:
This rule checks an entity’s metadata labels for the ownership annotation and will pass if “ownership_team” is defined.You can also use this expression in the Query Builder to find all k8s deployments with the label “environment”:
Or you could refine the query further to find k8s deployments with an “environment” label and that are in production:
Checks whether a k8s resource of any type is associated with an entity.Definition - k8s != nullExampleFor a Scorecard focused on automation or development maturity, you can set a rule to make sure a k8s resource is mapped:
The Cortex k8s agent periodically sends the raw spec definitions for all entities. The spec JSON is equivalent to the root spec field of the entity descriptor (deployments, StatefulSet, etc.) and fully conforms to that format.You can find the official documentation for these resource objects in the Kubernetes Workload Docs.You can use this list of JSON specs combined with JQ or Open Policy Agent (OPA) language to write complex assertions such as “all resources must have specific annotations set” or “all containers should have a CPU resource limit defined.”The list of JSON specs can also be filtered to only ones in a specific cluster by specifying the cluster name: k8s.spec("prod").Definition: k8s.spec()ExamplesYou can use this expression to write a wide range of rules. For a best practices Scorecard, you can make sure that resource definitions have set CPU requests:
Or that all resource definitions expose only TCP ports:
Number of replicas available, current, desired, ready, unavailable, or updated.Definition - k8s.replicas()ExampleYou can use this expression in a development maturity Scorecard to make sure an entity has at least two available instances:

​
Viewing Kubernetes integration logs

This feature is available in Cortex cloud.
While viewing an integration’s settings page, select the Error logs tab to view errors from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).
The 'Logs' tab on an integration's settings page shows error information over the past 7 days.
Click into a row to get more information, including time stamp, status code, full error, and request path.

​
Background sync

The Cortex k8s agent is a cron job that runs every five (5) minutes by default.

​
Troubleshooting and FAQ

See frequently asked questions below.
Make sure that the types you expected to see are in the cluster you are attempting to import.
If you’re using Cortex’s k8s agent to import entities into Cortex but don’t see all expected namespaces during the import process, make sure app.namespace is commented out in values.yaml:
If app.namespace is defined the Cortex k8s agent will only be able to discover services from that namespace. This behavior can be confirmed with a backend log similar to:
Once app.namespace is commented out, restart your pods. You will then be able to see all expected namespaces when importing new services.
This usually means two or more Cortex k8s agents are reporting under the same cluster name. Each agent overwrites the other’s data, so Kubernetes information appears and disappears from entity pages, and the agent logs show intermittent 409 errors.Check whether you’re running more than one agent. This is easy to miss when an agent is deployed inside a parent Argo environment, because the parent and child environments can each run one.To fix it, give every agent a unique cluster name. You can set it in values.yaml:
Or pass it at install time:
Restart the pods after you change the value. Keep in mind that changing a cluster name changes the value Cortex expects in the cluster field of any entity descriptor that maps resources from that cluster, so update those descriptors to match.
If your Cortex agent in Kubernetes clusters is blocked due to deprecation of Docker registry after an upgrade, you can make these direct edits using the same credentials:
  1. Access the image from ghcr.io instead of docker.pkg.github.com.
  2. Update the registry secret, setting the server to https://ghcr.io.
If you are unable to make these changes, please reach out to help@cortex.io and request a new Helm chart with this change already reflected.
When running the self-hosted Kubernetes agent successfully, users may see failing ArgoCD rollouts errors while not using this tool.
Cortex logs this exception for verbosity - this error is harmless if not using ArgoCD tool.
Yes. The Cortex Helm chart deploys two Cortex-specific pods from images for the frontend and backend, as well as a data store. You can use these images to run Docker containers on other platforms, such as ECS.
Last modified on September 25, 2026