Kubernetes
Summaryβ
The Kubernetes integration provides deep visibility into the infrastruture of how your services are actually deployed. You can use the Kubernetes integration to:
- Easily one-click import services from multiple k8s clusters into Cortex
- Build scorecard rules to enforce your org's k8s best practices
- View information from k8s in the service homepage, letting you easily access information such as active replicas, currently deployed versions, resource requirements, and more.
Setupβ
In order to connect Cortex to your Kubernetes instance, youβll need to install the Cortex K8s agent in your Kubernetes cluster. You can follow the instructions to do so in Settings β Kubernetes.
Service Registrationβ
Discoveryβ
By default, Cortex will use the service identifier (e.g. my-service
) as the "best guess" for the Kubernetes deployment or rollout. For example, if your service identifier is my-service
, then the corresponding deployment or rollout in Kubernetes should also be my-service
.
If your Kubernetes deployment or rollouts donβt cleanly match the Cortex service identifier, you can override this in the Cortex Service Descriptor.
Annotationβ
Alternatively, you can link your Kubernetes deployment to a Cortex service by adding an annotation to your deployment metadata. Use cortex.io/tag
as the key and use the value of x-cortex-tag
in the Cortex service's cortex.yaml
as the value.
For example, if the cortex.yaml
file contains
openapi: 3.0.0
info:
title: My Service
x-cortex-tag: my-service
description: This is my cool service.
Then the deployment.yaml
file should be configured as
apiVersion: apps/v1
kind: Deployment
metadata:
name: does-not-matter
namespace: does-not-matter-either
annotations:
cortex.io/tag: my-service
Service Descriptorβ
If you need to override the automatic discovery, you can define the following block in your Cortex Service Descriptor.
Cortex accepts a list of K8s resources, which can be on different clusters or of different types.
Each Resource type has the same field definitions.
Field | Description | Required |
---|---|---|
identifier | namespace/name as found in Kubernetes | true |
cluster | The name of the cluster, which is set when deploying the agent | true |
Deploymentsβ
x-cortex-k8s:
deployment:
- identifier: namespace/name
cluster: dev # optional
- identifier: experiment/scratch
cluster: dev
- identifier: default/cortex
cluster: prod
ArgoCD Rolloutβ
x-cortex-k8s:
argorollout:
- identifier: namespace/name
cluster: dev
StatefulSetβ
x-cortex-k8s:
statefulset:
- identifier: namespace/name
cluster: dev
Cortex k8s Agentβ
The k8s integration is powered by a lightweight, custom agent we've developed. The agent is deployed into your cluster, and periodically sends information back to Cortex.
Basicsβ
The k8s agent collects information from your cluster (such as the
current list of deployments
. Using a Cortex API key, it sends this information
back to Cortex, where it's exposed through the dashboard.
The k8s agent is lightweight and adds negligible impact to your cluster. It's essentially a simple cron job that collects and sends information back to your Cortex account.
The agent collects information every five minutes, by default.
Deploymentβ
To deploy the agent, you can use our helm chart which allows for an easy installation. The helm chart is provided to you upon request.
Securityβ
Security of your cluster is extremely important to us (and to you!). The agent's push-model ensures that you do not need to expose your cluster to the public internet.
Additionally, the helm chart comes with a predefined ClusterRole
that provides the correct RBACs, which are:
- Permissions:
["get", "watch", "list"]
- On resources:
["deployments", "services", "pods", "replicationcontrollers"]
Communication out of the cluster to Cortex happens over HTTPS. There is no inbound traffic to the agent.