Kubernetes Integration

Connect Annie to your clusters for deep insights into container orchestration, workloads, and resource usage.

Prerequisites

Kubernetes 1.20+
Helm 3.8+
Anyshift API token (generate one at app.anyshift.io/integrations)

Setup

Add the Anyshift Helm repository

helm repo add anyshift https://helm.anyshift.io
helm repo update

Store your API token in a Kubernetes secret

Recommended for production. Create a secret to hold your API token:

kubectl create secret generic anyshift-secret \
  --namespace anyshift-agent \
  --from-literal api-key="<YOUR_API_TOKEN>"

Install the agent

Install using the secret:

helm install anyshift-agent anyshift/anyshift-k8s-agent \
  --namespace anyshift-agent --create-namespace \
  --set token.secretName="anyshift-secret" \
  --set token.secretKeyName="api-key" \
  --set clusterName="<YOUR_CLUSTER_NAME>"

Replace <YOUR_API_TOKEN> with your token from the integrations page and <YOUR_CLUSTER_NAME> with a meaningful name (e.g. “production-us-east”, “staging-eu”).

For testing, you can pass the token directly with --set token.value="<YOUR_API_TOKEN>" instead of using a secret.

Validate the installation

Check that the agent is running:

kubectl get pods -n anyshift-agent

View agent logs:

kubectl logs -n anyshift-agent -l app.kubernetes.io/name=anyshift-k8s-agent

Live Cluster Queries

Beyond the periodic snapshot, the agent supports live queries from Annie on demand: describing resources, reading pod logs, inspecting events, listing CRDs, and reading Helm release values. No inbound ports are opened on your cluster; the agent only makes outbound connections. Even over live queries, secret values are stripped from responses; only Secret metadata (name, namespace, labels, annotations, type) is ever returned.

Reference

Resource requirements

Agent resource usage depends on cluster size:

Cluster Size	Recommended Memory
Small (<50 nodes)	256Mi - 512Mi
Medium (50-200 nodes)	512Mi - 1Gi
Large (200+ nodes)	1Gi - 2Gi

On warmup, or when many events occur at once, the agent collects cluster state data which temporarily increases memory usage. For large clusters, you may need to set memory limits up to 2GB.

To configure higher memory limits:

resources:
  limits:
    memory: 2Gi
  requests:
    memory: 1Gi

Custom configuration (values.yaml)

Use a values.yaml file for full control over the install. If you use the secret method, create the secret first:

kubectl create secret generic anyshift-secret \
  --namespace anyshift-agent \
  --from-literal api-key="<YOUR_API_TOKEN>"

Create values.yaml:

clusterName: "YOUR_CLUSTER_NAME"  # Example: "staging-eu", "prod-cluster"

token:
  # Option 1: Reference to Kubernetes secret (recommended)
  secretName: "anyshift-secret"
  secretKeyName: "api-key"
  
  # Option 2: Direct value (not recommended for production)
  # value: "your-api-token"

# Common optional configurations
replicaCount: 2

nameOverride: ""
fullnameOverride: ""  
namespaceOverride: ""

image:
  repository: ghcr.io/anyshift-io/anyshift-k8s-agent
  pullPolicy: IfNotPresent

baseURL: "https://api.anyshift.io"

logLevel: info
logFormat: json

port: 8080
metricsPort: 8081

localMode: false

initialSnapshotWait: 30s
batchWindow: 5m
resyncPeriod: 1h
heartbeatInterval: 5m

# Exclude secrets from tracking. When true, the agent's ClusterRole drops
# get/list/watch on v1/secrets entirely.
excludeSecrets: false

# Extra API groups to grant the agent read access to, for in-house or niche
# CRDs not covered by the default ecosystem list.
# Example:
#   extraApiGroups:
#     - acme.com
#     - crossplane.io
extraApiGroups: []

podAnnotations: {}

customLabels: {}

resources:
  requests:
    cpu: 200m
    memory: 256Mi
  limits:
    cpu: 400m
    memory: 512Mi

autoscaling:
  enabled: true
  minReplicas: 2
  maxReplicas: 3
  targetCPUUtilizationPercentage: 50

podDisruptionBudget:
  enabled: true
  minAvailable: 1

initialUploadRetry:
  initialInterval: 2s
  multiplier: 2
  maxInterval: 30s
  maxElapsed: 10m

# HTTP client timeout for upload requests
httpTimeout: 2m  # Increase for large clusters or slow networks

nodeSelector: {}

tolerations: []

affinity: {}

Install with custom values:

helm install anyshift-agent anyshift/anyshift-k8s-agent \
  --namespace anyshift-agent --create-namespace \
  -f values.yaml

Advanced install: cluster name templating and custom labels

Cluster name templating. Use Go template syntax for dynamic cluster names:

# Use custom values in cluster name  
helm install anyshift-agent anyshift/anyshift-k8s-agent \
  --namespace anyshift-agent --create-namespace \
  --set token.value="<YOUR_API_TOKEN>" \
  --set clusterName="{{ .Values.customLabels.environment }}-{{ .Values.customLabels.region }}-cluster" \
  --set customLabels.environment="production" \
  --set customLabels.region="us-east"
# Results in cluster name: "production-us-east-cluster"

Custom labels. Add custom labels to all resources:

helm install anyshift-agent anyshift/anyshift-k8s-agent \
  --namespace anyshift-agent --create-namespace \
  --set token.value="<YOUR_API_TOKEN>" \
  --set clusterName="production" \
  --set customLabels.environment=production \
  --set customLabels.team=platform \
  --set customLabels.cost-center=engineering

Dynamic cluster naming with custom labels (values.yaml).

token:
  value: "your-api-token"

# Use custom labels in cluster naming via Go templates
clusterName: "{{ .Values.customLabels.environment }}-{{ .Values.customLabels.region }}-cluster"

# Custom labels applied to all resources
customLabels:
  environment: production
  region: us-east
  team: platform
  cost-center: engineering
  compliance: sox

# This configuration will:
# - Create cluster name: "production-us-east-cluster"
# - Apply all custom labels to agent resources

Security: secrets handling

The agent tracks Secret metadata only (name, namespace, labels, annotations, type). Secret values are stripped before anything leaves your cluster, in both the periodic snapshot and the live query paths. Metadata is what’s needed to understand topology and relationships.For environments with strict security requirements, you can drop secrets access entirely at the RBAC layer.Option 1: Command line

helm install anyshift-agent anyshift/anyshift-k8s-agent \
  --namespace anyshift-agent --create-namespace \
  --set token.value="<YOUR_API_TOKEN>" \
  --set clusterName="<YOUR_CLUSTER_NAME>" \
  --set excludeSecrets=true

Option 2: values.yaml

excludeSecrets: true

When excludeSecrets=true, the agent’s ClusterRole drops get/list/watch on v1/secrets entirely.

Permissions and RBAC

The agent requires read-only access (get, list, watch). The ClusterRole covers:

All standard Kubernetes resources (core + apps, batch, networking, rbac, policy, autoscaling, storage, discovery, coordination, apiextensions, metrics, gateway, …).
Common add-on ecosystems (Argo CD/Flux, Istio/Linkerd, KEDA, Cert-Manager, Prometheus Operator, Kyverno/Gatekeeper, Crossplane, Tekton, Knative, Velero, Cilium/Calico, Kafka, Elastic, …).
Per-cloud controllers (EKS, GKE, AKS).

The full list is in the chart at templates/clusterRole.yaml.Adding custom CRDs. If you run in-house CRDs or an ecosystem not covered by the default list, extend the RBAC via extraApiGroups:

extraApiGroups:
  - acme.com
  - crossplane.io

These are added to the agent’s ClusterRole with the same read-only verbs, so Annie can describe and list them during live queries.

Upgrade

To upgrade the agent to the latest version:

# Step 1: Update the Helm repository
helm repo update anyshift

# Step 2: Upgrade the agent
helm upgrade anyshift-agent anyshift/anyshift-k8s-agent \
  --namespace anyshift-agent \
  --reset-then-reuse-values

--reset-then-reuse-values keeps the overrides you set at install time while picking up any new defaults shipped by the chart (new fields, updated values). It’s the recommended flag for upgrades that introduce new configuration options.

Uninstall

helm uninstall anyshift-agent --namespace anyshift-agent

Get Started

Product

Interfaces

Workspace

Privacy & Security

Kubernetes Integration

Kubernetes Integration

Prerequisites

Setup

Live Cluster Queries

Reference

​Kubernetes Integration

​Prerequisites

​Setup

​Live Cluster Queries

​Reference

Kubernetes Integration

Prerequisites

Setup

Live Cluster Queries

Reference