Kubernetes Integration

Kubernetes integration will allow Annie to connect to your clusters and provide deep insights into your container orchestration, workloads, and resource usage.

Prerequisites

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

View changelog

Resource Requirements

The Anyshift Kubernetes agent resource usage depends on your 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

Installation

Option 1: Quick Installation

Step 1: Add the Anyshift Helm repository

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

Step 2: Install the agent

Option A: Using Kubernetes Secret (Recommended for Production)First, create a Kubernetes secret to store your API token securely:

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

Then install the agent 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>"

Option B: Direct Token Value (For Testing)

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

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

Advanced Installation Examples

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

Option 2: Custom Configuration

Step 1: Create the secret (if using secret method)

If you’re using the secret method for token storage:

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

Step 2: Create a values.yaml file

Create a values.yaml file with your custom configuration:

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: {}

Step 3: Install with custom values

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

Advanced Values File Examples

Dynamic Cluster Naming with Custom Labels

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

Live Cluster Queries

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

Security Configuration

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.

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

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

Permissions Overview

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.

Get Started

Product

Privacy & Security

Kubernetes Integration

Kubernetes Integration

Prerequisites

Resource Requirements

Installation

Step 1: Add the Anyshift Helm repository

Step 2: Install the agent

Advanced Installation Examples

Step 1: Create the secret (if using secret method)

Step 2: Create a values.yaml file

Step 3: Install with custom values

Advanced Values File Examples

Live Cluster Queries

Security Configuration

Secrets Handling

Validate The Installation

Upgrade

Uninstall

Permissions Overview

Adding custom CRDs

Get Started

Product

Privacy & Security

​Kubernetes Integration

​Prerequisites

​Resource Requirements

​Installation

​Step 1: Add the Anyshift Helm repository

​Step 2: Install the agent

​Advanced Installation Examples

​Step 1: Create the secret (if using secret method)

​Step 2: Create a values.yaml file

​Step 3: Install with custom values

​Advanced Values File Examples

​Live Cluster Queries

​Security Configuration

​Secrets Handling

​Validate The Installation

​Upgrade

​Uninstall

​Permissions Overview

​Adding custom CRDs

Kubernetes Integration

Prerequisites

Resource Requirements

Installation

Step 1: Add the Anyshift Helm repository

Step 2: Install the agent

Advanced Installation Examples

Step 1: Create the secret (if using secret method)

Step 2: Create a values.yaml file

Step 3: Install with custom values

Advanced Values File Examples

Live Cluster Queries

Security Configuration

Secrets Handling

Validate The Installation

Upgrade

Uninstall

Permissions Overview

Adding custom CRDs