> ## 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.

# Using the integration for Kubernetes

This article explains how to use the integration for Kubernetes. For configuration instructions, see [Configuring the integration for Kubernetes](/ingesting-data-into-cortex/integrations/kubernetes). For instructions on connecting Kubernetes resources to entities, see [Connecting entities to Kubernetes](/ingesting-data-into-cortex/integrations/kubernetes/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](/ingesting-data-into-cortex/entities-overview/entities/details) 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](/guides/migrations-and-modernization/accelerate-migration-to-k8s#create-a-kubernetes-scorecard) template.

See more rule examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer) in Cortex.

<AccordionGroup>
  <Accordion title="Cluster information">
    Data about k8s clusters associated with a given entity.

    **Definition** - `k8s.clusters()`

    **Examples**

    You can use the `k8s.clusters()` expression in the Query Builder to find all clusters that start with "dev":

    ```
    k8s.clusters.all((cluster) => cluster.name.matches("""dev-.*"""))
    ```

    Or any cluster named "prod":

    ```
    k8s.clusters.any((cluster) => cluster.name.matches("prod"))
    ```
  </Accordion>

  <Accordion title="Deployment labels">
    Checks deployment metadata.

    **Definition** - `k8s.metadata()`

    **Examples**

    You can use this expression in a production readiness Scorecard to check ownership:

    ```
    k8s.metadata().labels.any((label) => label.get("ownership") == "ownership_team")
    ```

    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":

    ```
    k8s.metadata().labels.all((label) => label.containsKey("environment")) == true
    ```

    Or you could refine the query further to find k8s deployments with an "environment" label and that are in production:

    ```
    k8s.metadata().labels.all((label) => label.get("environment")?.matches("prod")") == true
    ```
  </Accordion>

  <Accordion title="K8s resource is set for entity">
    Checks whether a k8s resource of any type is associated with an entity.

    **Definition** - `k8s != null`

    **Example**

    For a Scorecard focused on automation or development maturity, you can set a rule to make sure a k8s resource is mapped:

    ```
    k8s != null
    ```
  </Accordion>

  <Accordion title="Kubernetes spec YAML">
    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](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/).

    You can use this list of JSON specs combined with JQ or [Open Policy Agent (OPA) language](https://www.openpolicyagent.org/docs/v0.52.0/) 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()`

    **Examples**

    You 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:

    ```
    jq(k8s.spec(), ".[].template.spec.containers[].resources.requests.cpu") != null
    ```

    Or that all resource definitions expose only TCP ports:

    ```
    jq(k8s.spec(), ".[].template.spec.containers[].ports[].protocol") == "TCP"
    ```
  </Accordion>

  <Accordion title="Replica information">
    Number of replicas available, current, desired, ready, unavailable, or updated.

    **Definition** - `k8s.replicas()`

    **Example**

    You can use this expression in a development maturity Scorecard to make sure an entity has at least two available instances:

    ```
    k8s.replicas().numAvailable >= 2
    ```
  </Accordion>
</AccordionGroup>

## Viewing Kubernetes integration logs

<Info>
  This feature is available in Cortex cloud.
</Info>

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).

<Frame>
  <img src="https://mintcdn.com/cortex-290c0c42/ovmDVVMNC2L6Yw7I/images/integration-error-logs.png?fit=max&auto=format&n=ovmDVVMNC2L6Yw7I&q=85&s=dffdc901a9ce0232aedd090bb3a4531c" alt="The 'Logs' tab on an integration's settings page shows error information over the past 7 days." title="Integration Error Logs" className="mr-auto" width="1532" height="203" data-path="images/integration-error-logs.png" />
</Frame>

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.

<AccordionGroup>
  <Accordion title="When I try to import entities, I don't see all the supported workload types (deployments, ArgoCD rollout, StatefulSet, CronJob)">
    Make sure that the types you expected to see are in the cluster you are attempting to import.
  </Accordion>

  <Accordion title="Namespaces are missing from Kubernetes discovery">
    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`:

    ```
    app:
      # baseURL: 
      baseURL:
      keySecret:
      # namespace: exampleNamespace
    ```

    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:

    ```
    INFO 1 --- [ scheduling-1] k8sagent : Looking for stateful sets in namespace 
    ```

    Once `app.namespace` is commented out, restart your pods. You will then be able to see all expected namespaces when importing new services.
  </Accordion>

  <Accordion title="Kubernetes data disappears from entity pages, or the agent logs 409 errors">
    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`:

    ```
    app:
      # baseURL: 
      baseURL:
      keySecret:
      clusterName: my-cluster-name
    ```

    Or pass it at install time:

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

    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.
  </Accordion>

  <Accordion title="The agent is blocked after an upgrade because of the deprecated Docker registry">
    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`.

       ```
       image: ghcr.io/cortexapps/k8s-agent...
       ```
    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](mailto:help@cortex.io) and request a new Helm chart with this change already reflected.
  </Accordion>

  <Accordion title="The agent logs failing Argo Rollouts errors, but I don't use Argo Rollouts">
    When running the self-hosted Kubernetes agent successfully, users may see failing ArgoCD rollouts errors while not using this tool.

    ```
    Error polling argocd rollouts from Kubernetes API

    io.kubernets.client.openapi.ApiException:
    [...]
      at com.brainera.k8sSDKClient.getArgoRollouts(k8sClient.kt:101) ~[app:/na]
    ```

    Cortex logs this exception for verbosity - this error is harmless if not using ArgoCD tool.
  </Accordion>

  <Accordion title="Can I deploy on prem if I don’t use Kubernetes?">
    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.
  </Accordion>
</AccordionGroup>


## Related topics

- [Connecting entities to Kubernetes](/ingesting-data-into-cortex/integrations/kubernetes/connecting-entities-to-kubernetes.md)
- [Kubernetes](/ingesting-data-into-cortex/integrations/kubernetes.md)
- [Syntasso Kratix Enterprise (SKE)](/ingesting-data-into-cortex/integrations/syntasso.md)