cortexapps-cli 1.39.0__tar.gz → 1.41.0__tar.gz

{cortexapps_cli-1.39.0 → cortexapps_cli-1.41.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cortexapps-cli
-Version: 1.39.0
+Version: 1.41.0
 Summary: Command Line Interface for cortexapps
 License: MIT
 License-File: LICENSE

cortexapps_cli-1.41.0/cortexapps_cli/solutions/kubernetes-agent/README.md

@@ -0,0 +1,137 @@
+---
+name: Kubernetes Agent
+description: Deploy the Cortex Kubernetes agent to a kind cluster in a GitHub Codespace, or to any existing Kubernetes cluster, to demonstrate live workload discovery and k8s integration.
+---
+
+# Kubernetes Agent Solution
+
+Demonstrates the [Cortex Kubernetes agent](https://docs.cortex.io/docs/reference/integrations/kubernetes) integration. Supports two deployment paths:
+
+- **GitHub Codespace** — creates a Codespace with a local [kind](https://kind.sigs.k8s.io) cluster automatically (no cluster setup required)
+- **Existing cluster** — deploys to any Kubernetes cluster already configured in your `kubectl` context
+
+## What this installs
+
+- **Cortex k8s-agent** — connects your cluster to Cortex and syncs workload metadata
+- **Demo workloads** — Deployment, StatefulSet, CronJob, and Argo Rollout, all tagged `demo-kubernetes`
+- **demo-kubernetes** — a Cortex service entity that the workloads annotate to
+
+After setup, visit your entity's K8s tab to see live workload data synced from the cluster.
+
+## Data Model
+
+```
+  GitHub Codespace
+  ┌──────────────────────────────────────────────────────────┐
+  │  kind cluster (cortex-demo)                              │
+  │  ┌────────────────────────────────────────────────────┐  │
+  │  │                                                    │  │
+  │  │  ┌─────────────────┐   ┌──────────────────────┐    │  │
+  │  │  │  Kubernetes API │◀──│  cortex-k8s-agent    │    │  │
+  │  │  │  Server         │   │  (polls every 5 min) │    │  │
+  │  │  └─────────────────┘   └──────────┬───────────┘    │  │
+  │  │                                   │ HTTPS push     │  │
+  │  │  ┌──────────────────────────────┐ │                │  │
+  │  │  │  demo workloads              │ │                │  │
+  │  │  │  Deployment · StatefulSet    │ │                │  │
+  │  │  │  CronJob · Argo Rollout      │ │                │  │
+  │  │  └──────────────────────────────┘ │                │  │
+  │  └────────────────────────────────────────────────────┘  │
+  └──────────────────────────────────┬───────────────────────┘
+                                     ▼
+                           ┌─────────────────┐
+                           │  Cortex         │
+                           │  Platform       │
+                           └─────────────────┘
+```
+
+The agent runs inside the cluster as a Deployment. Every 5 minutes it queries the Kubernetes API for workload resources and pushes the metadata to Cortex over HTTPS. Cortex surfaces the data on each entity's K8s tab.
+
+## Prerequisites
+
+- A Cortex API key (`CORTEX_API_KEY`) — get from Cortex Settings → API Keys
+- A GitHub PAT provided by Cortex Customer Engineering (`GHCR_TOKEN`) — required to pull the k8s-agent image; see [Kubernetes prerequisites](https://docs.cortex.io/ingesting-data-into-cortex/integrations/kubernetes#prerequisites)
+
+**For the GitHub Codespace path only:**
+- The [gh CLI](https://cli.github.com) installed and authenticated (`gh auth login`)
+
+**For the existing cluster path only:**
+- `kubectl`, `helm` installed and configured to reach your cluster
+
+## Quick start
+
+```bash
+cortex solutions install -s kubernetes-agent
+cortex solutions post-install -s kubernetes-agent
+```
+
+The setup script will ask which path you want:
+
+```
+Create a new GitHub Codespace with a kind cluster? (yes = spin up Codespace, no = use an existing configured cluster) [yes]:
+```
+
+### GitHub Codespace path
+
+The script will:
+1. Create a Codespace from the `cortexapps/cli` repository using the `kubernetes-agent` devcontainer
+2. Wait for the Codespace to start and the kind cluster to initialize (~15-20 min on first run)
+3. Deploy the k8s-agent and demo workloads inside the Codespace via `gh codespace ssh`
+
+After setup, the Codespace URL and `gh codespace ssh` command are printed.
+
+### Existing cluster path
+
+Requires `kubectl` pointed at a running cluster. The script deploys the k8s-agent and demo workloads into whatever namespace your current context targets.
+
+## What you should see
+
+After the agent's first sync (~5 min), visit:
+`https://app.getcortexapp.com/admin/resources?tag=demo-kubernetes`
+
+- `demo-deployment` (Deployment)
+- `demo-statefulset` (StatefulSet)
+- `demo-cronjob` (CronJob)
+- `demo-rollout` (Argo Rollout — containers resolved from `demo-deployment`)
+
+## Troubleshooting
+
+**No K8s details showing on the entity page after the first sync**
+
+If you have configured [K8s metadata label customization](https://docs.cortex.io/ingesting-data-into-cortex/integrations/kubernetes#auto-mapping-customization) in your Cortex settings (Settings → Kubernetes → Metadata labels), Cortex uses *only* those labels for resource mapping and ignores the `cortex.io/tag` annotation used by the demo manifests. Either:
+
+- Remove the metadata label customization to use the default annotation-based mapping, or
+- Add a matching label (e.g., `app: demo-kubernetes`) to the demo manifests
+
+## Re-running setup
+
+The setup script is idempotent — re-run `cortex solutions post-install -s kubernetes-agent` to retry any failed step. Completed steps are skipped.
+
+For the Codespace path, the Codespace name is saved locally so re-runs reconnect to the same Codespace rather than creating a new one.
+
+## After Installing
+
+Once you have verified the agent working against the demo cluster, roll it out to your real clusters:
+
+1. **Install the Cortex Kubernetes agent Helm chart into each cluster** for which you want data associated with your Cortex entities. Give each cluster a distinct `clusterName` — this is how Cortex identifies which cluster a workload belongs to:
+
+   ```bash
+   helm upgrade --install cortex-k8s-agent \
+     oci://ghcr.io/cortexapps/k8s-agent/helm/cortex-k8s-agent \
+     --set app.apiKey=<your-cortex-api-key> \
+     --set app.clusterName=<name-as-it-appears-in-cortex> \
+     --set app.baseUrl=https://api.getcortexapp.com
+   ```
+
+2. **Ensure your Kubernetes workloads have the appropriate annotation or label** so Cortex can map them to your catalog entities:
+
+   - **Annotation** (default): add `cortex.io/tag: <entity-tag>` to each workload's metadata
+   - **Label** (if you have configured K8s metadata label customization in Cortex Settings): add the configured label key with the entity tag as the value, e.g. `app: <entity-tag>`
+
+3. **Wait for the first sync** (~5 min) then visit each entity's K8s tab in Cortex to confirm workload data is flowing.
+
+See the [Cortex Kubernetes integration docs](https://docs.cortex.io/ingesting-data-into-cortex/integrations/kubernetes) for full configuration options including namespace filtering, custom resource types, and RBAC setup.
+
+## Temporary limitation
+
+The k8s-agent image is currently private on GHCR, requiring `GHCR_TOKEN`. This requirement will be removed once the image is made public.

cortexapps_cli-1.41.0/cortexapps_cli/solutions/kubernetes-agent/catalog/demo-kubernetes.yaml

@@ -0,0 +1,6 @@
+openapi: 3.0.0
+info:
+  title: Demo Kubernetes
+  description: Demo entity for the Kubernetes agent integration
+  x-cortex-tag: demo-kubernetes
+  x-cortex-type: service

cortexapps_cli-1.41.0/cortexapps_cli/solutions/kubernetes-agent/helm-chart/.helmignore

@@ -0,0 +1,23 @@
+# Patterns to ignore when building packages.
+# This supports shell glob matching, relative path matching, and
+# negation (prefixed with !). Only one pattern per line.
+.DS_Store
+# Common VCS dirs
+.git/
+.gitignore
+.bzr/
+.bzrignore
+.hg/
+.hgignore
+.svn/
+# Common backup files
+*.swp
+*.bak
+*.tmp
+*.orig
+*~
+# Various IDEs
+.project
+.idea/
+*.tmproj
+.vscode/

cortexapps_cli-1.41.0/cortexapps_cli/solutions/kubernetes-agent/helm-chart/Chart.yaml

@@ -0,0 +1,9 @@
+# Bundled copy of the Cortex k8s-agent helm chart for demo purposes.
+# This copy is not kept up-to-date. Once the chart is published to a
+# public helm repo, this bundle will be replaced with a helm repo reference.
+apiVersion: v2
+name: cortex-k8s-agent
+description: A Helm chart for deploying Cortex K8s agent in your cluster
+type: application
+version: 0.1.0
+appVersion: 1.16.0

cortexapps_cli-1.41.0/cortexapps_cli/solutions/kubernetes-agent/helm-chart/README.md

@@ -0,0 +1,28 @@
+# Cortex k8s Helm Chart
+
+## Requirements
+* [Helm](https://helm.sh/docs/intro/install/)
+* A token for our package registry
+
+## Process
+1. Generate a new Cortex API Key on the [API Keys Settings tab](https://app.getcortexapp.com/admin/settings/api-keys) in Cortex.
+	- This will be used for the Cortex Kubernetes agent to communicate and push service information to Cortex backend without exposing your public API Key.
+2. Inside your Kubernetes cluster, run the following command to generate a Kubernetes secret for the Cortex API Key.
+  `kubectl create secret generic cortex-key --from-literal api-key=YOUR_API_KEY`
+3. Run `kubectl create secret docker-registry cortex-docker-registry-secret --docker-server=ghcr.io --docker-username=$GITHUB_USERNAME --docker-password=$GITHUB_PASSWORD --docker-email=<doesn't matter>`
+4. Download the helm chart and inside the repository run the following command to install the agent in your cluster.
+  `helm install YOUR_SELECTED_CHART_NAME .`
+
+## Customization
+The helm chart make installation quick and simple, but if you want to customize any of the installation features for the Cortex agent you can do so by changing the following information in the `values.yaml` of the helm chart.
+### Service Account
+To authenticate the Cortex agent in your cluster and grant it access to service information, the agent needs its own service account. The helm chart by default creates a Service Account `cortex-service-account`, but you can customize the `name` and `namespace` of this Service Account. If you already have a Service Account that you want the Cortex agent to use, set `create: false` under `serviceAccount` and enter the `name` and `namespace` of the Service Account you wish to use.
+### Service
+The service type and port can be customized as well. For security, the agent uses a default `ClusterIP` service type that only allows the service to be accessed from within the cluster.
+### Resources
+By default, no resources are specified. While the Cortex Kubernetes agent is designed to be lightweight and minimize resource utilization, you have the option to add custom CPU limits and requests.
+### Base URL
+The Base URL defaults to that for the hosted version of Cortex. If you are using the on-prem version of Cortex, you should change the `app/baseUrl` value to the correct URL for your on-prem Cortex.
+
+# Usage
+After installation, usage is very simple as no additional steps are required. The next time you go to create a new service in your Service Directory Homepage, you should see all of your Kubernetes services already added, ready for you to use in Cortex. If you do not want to import all of your Kubernetes discovered services, you can simply remove the ones you do not want to add. Removed services will still show up in the Kubernetes tab of Discovered Services if you want to go back and add them later.

cortexapps_cli-1.41.0/cortexapps_cli/solutions/kubernetes-agent/helm-chart/templates/_helpers.tpl

@@ -0,0 +1,73 @@
+{{/*
+Expand the name of the chart.
+*/}}
+{{- define "helm-chart.name" -}}
+{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }}
+{{- end }}
+
+{{/*
+Create a default fully qualified app name.
+We truncate at 63 chars because some Kubernetes name fields are limited to this (by the DNS naming spec).
+If release name contains chart name it will be used as a full name.
+*/}}
+{{- define "helm-chart.fullname" -}}
+{{- if .Values.fullnameOverride }}
+{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}
+{{- else }}
+{{- $name := default .Chart.Name .Values.nameOverride }}
+{{- if contains $name .Release.Name }}
+{{- .Release.Name | trunc 63 | trimSuffix "-" }}
+{{- else }}
+{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }}
+{{- end }}
+{{- end }}
+{{- end }}
+
+{{/*
+Create chart name and version as used by the chart label.
+*/}}
+{{- define "helm-chart.chart" -}}
+{{- printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | trunc 63 | trimSuffix "-" }}
+{{- end }}
+
+{{/*
+Common labels
+*/}}
+{{- define "helm-chart.labels" -}}
+helm.sh/chart: {{ include "helm-chart.chart" . }}
+{{ include "helm-chart.selectorLabels" . }}
+{{- if .Chart.AppVersion }}
+app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
+{{- end }}
+app.kubernetes.io/managed-by: {{ .Release.Service }}
+{{- end }}
+
+{{/*
+Selector labels
+*/}}
+{{- define "helm-chart.selectorLabels" -}}
+app.kubernetes.io/name: {{ include "helm-chart.name" . }}
+app.kubernetes.io/instance: {{ .Release.Name }}
+{{- end }}
+
+{{/*
+Create the name of the service account to use
+*/}}
+{{- define "helm-chart.serviceAccountName" -}}
+{{- if .Values.serviceAccount.create }}
+{{- default (include "helm-chart.fullname" .) .Values.serviceAccount.name }}
+{{- else }}
+{{- default "default" .Values.serviceAccount.name }}
+{{- end }}
+{{- end }}
+
+{{/*
+Create the namespace of the service account to use
+*/}}
+{{- define "helm-chart.serviceAccountNamespace" -}}
+{{- if .Values.serviceAccount.create }}
+{{- default (include "helm-chart.fullname" .) .Values.serviceAccount.namespace }}
+{{- else }}
+{{- default "default" .Values.serviceAccount.namespace }}
+{{- end }}
+{{- end }}

cortexapps_cli-1.41.0/cortexapps_cli/solutions/kubernetes-agent/helm-chart/templates/clusterrole.yaml

@@ -0,0 +1,10 @@
+{{- if .Values.clusterRole.create -}}
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: {{ include "helm-chart.serviceAccountName" . }}
+rules:
+  - apiGroups: ["apps", "argoproj.io", "batch"]
+    resources: ["deployments", "services", "pods", "replicationcontrollers", "statefulsets", "rollouts", "cronjobs"]
+    verbs: ["get", "watch", "list"]
+  {{- end -}}

cortexapps_cli-1.41.0/cortexapps_cli/solutions/kubernetes-agent/helm-chart/templates/clusterrolebinding.yaml

@@ -0,0 +1,14 @@
+{{- if .Values.clusterRoleBinding.create -}}
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  name: {{ include "helm-chart.serviceAccountName" . }}
+subjects:
+  - kind: ServiceAccount
+    name: {{ include "helm-chart.serviceAccountName" . }}
+    namespace: {{ include "helm-chart.serviceAccountNamespace" . }}
+roleRef:
+  kind: ClusterRole
+  name: {{ include "helm-chart.serviceAccountName" . }}
+  apiGroup: rbac.authorization.k8s.io
+  {{- end -}}

cortexapps_cli-1.41.0/cortexapps_cli/solutions/kubernetes-agent/helm-chart/templates/configmap.yaml

@@ -0,0 +1,9 @@
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: {{ template "helm-chart.fullname" . }}-configmap
+data:
+  SPRING_PROFILES_ACTIVE: prod
+  BASE_URL: {{ required "Base URL must be defined." .Values.app.baseUrl }}
+  {{ if .Values.app.clusterName }}CORTEX_CLUSTER: {{ .Values.app.clusterName }}{{ end }}
+  {{ if .Values.app.namespace }}SELECTED_NAMESPACE: {{ .Values.app.namespace }}{{ end }}

cortexapps_cli-1.41.0/cortexapps_cli/solutions/kubernetes-agent/helm-chart/templates/deployment.yaml

@@ -0,0 +1,51 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: {{ include "helm-chart.fullname" . }}
+  labels:
+    {{- include "helm-chart.labels" . | nindent 4 }}
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      {{- include "helm-chart.selectorLabels" . | nindent 6 }}
+  template:
+    metadata:
+      annotations:
+        checksum/config: {{ include (print $.Template.BasePath "/configmap.yaml") . | sha256sum }}
+    {{- with .Values.podAnnotations }}
+        {{- toYaml . | nindent 8 }}
+    {{- end }}
+      labels:
+        {{- include "helm-chart.selectorLabels" . | nindent 8 }}
+    spec:
+      {{- with .Values.image.secrets }}
+      imagePullSecrets:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      serviceAccountName: {{ include "helm-chart.serviceAccountName" . }}
+      containers:
+        - name: {{ .Chart.Name }}
+          image: "{{ required "Image repository must be defined" .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
+          imagePullPolicy: {{ .Values.image.pullPolicy }}
+          ports:
+            - name: http-api
+              containerPort: 80
+              protocol: TCP
+          readinessProbe:
+            initialDelaySeconds: 30
+            periodSeconds: 5
+            httpGet:
+              path: /actuator/health
+              port: 8080
+          resources:
+            {{- toYaml .Values.resources | nindent 12 }}
+          env:
+            - name: CORTEX_API_KEY
+              valueFrom:
+                secretKeyRef:
+                  name: {{ required "A secret containing api-key=CORTEX_API_KEY is required" .Values.app.keySecret }}
+                  key: api-key
+          envFrom:
+            - configMapRef:
+                name: {{ template "helm-chart.fullname" . }}-configmap

cortexapps_cli-1.41.0/cortexapps_cli/solutions/kubernetes-agent/helm-chart/templates/service.yaml

@@ -0,0 +1,15 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: {{ include "helm-chart.fullname" . }}
+  labels:
+    {{- include "helm-chart.labels" . | nindent 4 }}
+spec:
+  type: {{ .Values.service.type }}
+  ports:
+    - port: {{ .Values.service.port }}
+      targetPort: http-api
+      protocol: TCP
+      name: http-{{- include "helm-chart.fullname" . }}
+  selector:
+    {{- include "helm-chart.selectorLabels" . | nindent 4 }}

cortexapps_cli-1.41.0/cortexapps_cli/solutions/kubernetes-agent/helm-chart/templates/serviceaccount.yaml

@@ -0,0 +1,13 @@
+{{- if .Values.serviceAccount.create -}}
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: {{ include "helm-chart.serviceAccountName" . }}
+  namespace: {{ include "helm-chart.serviceAccountNamespace" . }}
+  labels:
+    {{- include "helm-chart.labels" . | nindent 4 }}
+  {{- with .Values.serviceAccount.annotations }}
+  annotations:
+    {{- toYaml . | nindent 4 }}
+  {{- end }}
+{{- end }}

cortexapps_cli-1.41.0/cortexapps_cli/solutions/kubernetes-agent/helm-chart/values.yaml

@@ -0,0 +1,33 @@
+image:
+  repository: ghcr.io/cortexapps/k8s-agent/k8s-agent
+  pullPolicy: IfNotPresent
+  tag: ""
+  secrets:
+    - name: cortex-docker-registry-secret
+
+imagePullSecrets: []
+nameOverride: ""
+fullnameOverride: cortex-k8s-agent
+
+serviceAccount:
+  create: true
+  annotations: {}
+  name: cortex-service-account
+  namespace: default
+
+clusterRole:
+  create: true
+
+clusterRoleBinding:
+  create: true
+
+service:
+  type: ClusterIP
+  port: 80
+
+resources: {}
+
+app:
+  baseUrl: https://api.getcortexapp.com
+  keySecret: cortex-key
+  clusterName: cortex-demo

cortexapps_cli-1.41.0/cortexapps_cli/solutions/kubernetes-agent/manifests/cronjob.yaml

@@ -0,0 +1,22 @@
+apiVersion: batch/v1
+kind: CronJob
+metadata:
+  name: demo-cronjob
+  labels:
+    app: demo-k8s-label
+  annotations:
+    cortex.io/tag: demo-kubernetes
+spec:
+  schedule: "*/10 * * * *"
+  jobTemplate:
+    spec:
+      template:
+        spec:
+          containers:
+          - name: hello
+            image: busybox:latest
+            command:
+            - /bin/sh
+            - -c
+            - echo "$(date '+%Y-%m-%d %H:%M:%S') - Hello from demo-kubernetes cronjob" >> /tmp/hello-world.txt
+          restartPolicy: OnFailure

cortexapps_cli-1.41.0/cortexapps_cli/solutions/kubernetes-agent/manifests/deployment.yaml

@@ -0,0 +1,23 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: demo-deployment
+  labels:
+    app: demo-k8s-label
+  annotations:
+    cortex.io/tag: demo-kubernetes
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: demo-k8s
+  template:
+    metadata:
+      labels:
+        app: demo-k8s
+    spec:
+      containers:
+      - name: hello
+        image: nginx:alpine
+        ports:
+        - containerPort: 80

cortexapps_cli-1.41.0/cortexapps_cli/solutions/kubernetes-agent/manifests/rollout.yaml

@@ -0,0 +1,22 @@
+apiVersion: argoproj.io/v1alpha1
+kind: Rollout
+metadata:
+  name: demo-rollout
+  labels:
+    app: demo-k8s-label
+  annotations:
+    cortex.io/tag: demo-kubernetes
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: demo-k8s-rollout
+  workloadRef:
+    apiVersion: apps/v1
+    kind: Deployment
+    name: demo-deployment
+    scaleDown: onsuccess
+  strategy:
+    canary:
+      steps:
+        - setWeight: 100

cortexapps_cli-1.41.0/cortexapps_cli/solutions/kubernetes-agent/manifests/statefulset.yaml

@@ -0,0 +1,24 @@
+apiVersion: apps/v1
+kind: StatefulSet
+metadata:
+  name: demo-statefulset
+  labels:
+    app: demo-k8s-label
+  annotations:
+    cortex.io/tag: demo-kubernetes
+spec:
+  serviceName: demo-k8s
+  replicas: 1
+  selector:
+    matchLabels:
+      app: demo-k8s-ss
+  template:
+    metadata:
+      labels:
+        app: demo-k8s-ss
+    spec:
+      containers:
+      - name: hello
+        image: nginx:alpine
+        ports:
+        - containerPort: 80