Skip to main content

​
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

View changelog

​
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

​
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

# Optional: Exclude secrets from tracking for security compliance
# Note: Only metadata is tracked, never actual secret contents
excludeSecrets: false

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

​
Security Configuration

​
Secrets Handling

By default, the agent tracks secrets metadata (name, namespace, labels, annotations) but never accesses actual secret contents. The agent only reads the metadata to understand the relationships and the topology. For environments with strict security requirements, you can disable secrets scanning: 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 secrets are excluded, the Anyshift agent will not be granted the ClusterRole permissions, preventing access to secrets.

​
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 \
  --reuse-values

​
Uninstall

helm uninstall anyshift-agent --namespace anyshift-agent

​
Supported Resources

The Anyshift Kubernetes agent v1 supports a wide range of resources across several API groups to provide a comprehensive view of your cluster. Here is the full list of supported resources:

Core Resources

  • Pods
  • Services
  • Nodes
  • Namespaces
  • ServiceAccounts
  • ConfigMaps
  • Secrets
  • PersistentVolumeClaims (PVCs)
  • PersistentVolumes (PVs)

Apps Resources

  • Deployments
  • ReplicaSets
  • DaemonSets
  • StatefulSets

Networking Resources

  • Ingresses

RBAC Resources

  • Roles
  • ClusterRoles
  • RoleBindings
  • ClusterRoleBindings

Autoscaling & Availability

  • HorizontalPodAutoscalers (HPA)
  • PodDisruptionBudgets (PDB)

Batch Resources

  • Jobs
  • CronJobs

KEDA Autoscaling

  • ScaledObjects
  • ScaledJobs
  • TriggerAuthentications
  • ClusterTriggerAuthentications

Automatically discovered if KEDA is installed

Service Discovery

  • Endpoints
  • EndpointSlices

​
Permissions Overview

The agent requires read-only access to cluster resources. Here are the exact ClusterRole permissions: 
rules:
  - apiGroups: [""]
    resources:
      - pods
      - services
      - nodes
      - persistentvolumeclaims
      - persistentvolumes
      - namespaces
      - configmaps
      {{- if not .Values.excludeSecrets }}
      - secrets
      {{- end }}
    verbs: ["get", "list", "watch"]

  - apiGroups: [""]
    resources:
      - serviceaccounts
    verbs: ["get", "list", "watch"]

  - apiGroups: ["apps"]
    resources:
      - deployments
      - replicasets
      - daemonsets
      - statefulsets
    verbs: ["get", "list", "watch"]

  - apiGroups: ["networking.k8s.io"]
    resources:
      - ingresses
    verbs: ["get", "list", "watch"]

  - apiGroups: ["rbac.authorization.k8s.io"]
    resources:
      - clusterroles
      - clusterrolebindings
      - roles
      - rolebindings
    verbs: ["get", "list", "watch"]

  - apiGroups: ["autoscaling"]
    resources:
      - horizontalpodautoscalers
    verbs: ["get", "list", "watch"]

  - apiGroups: ["policy"]
    resources:
      - poddisruptionbudgets
    verbs: ["get", "list", "watch"]

  - apiGroups: ["batch"]
    resources:
      - cronjobs
      - jobs
    verbs: ["get", "list", "watch"]

  # Service discovery
  - apiGroups: [""]
    resources:
      - endpoints
    verbs: ["get", "list", "watch"]
  
  - apiGroups: ["discovery.k8s.io"]
    resources:
      - endpointslices
    verbs: ["get", "list", "watch"]

  # CRD discovery
  - apiGroups: ["apiextensions.k8s.io"]
    resources:
      - customresourcedefinitions
    verbs: ["get", "list"]

  # KEDA resources (if installed)
  - apiGroups: ["keda.sh"]
    resources:
      - scaledobjects
      - scaledjobs
      - triggerauthentications
      - clustertriggerauthentications
    verbs: ["get", "list", "watch"]
⌘I