> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anyshift.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Kubernetes Integration

> Integrate Annie with Kubernetes for container orchestration insights.

<iframe width="560" height="315" src="https://www.youtube.com/embed/13rBTrNvA9E" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen />

# 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](https://app.anyshift.io/integrations))

[View changelog](https://helm.anyshift.io/changelog/latest.html)

## Setup

<Steps>
  <Step title="Add the Anyshift Helm repository">
    ```bash theme={null}
    helm repo add anyshift https://helm.anyshift.io
    helm repo update
    ```
  </Step>

  <Step title="Store your API token in a Kubernetes secret">
    Recommended for production. Create a secret to hold your API token:

    ```bash theme={null}
    kubectl create secret generic anyshift-secret \
      --namespace anyshift-agent \
      --from-literal api-key="<YOUR_API_TOKEN>"
    ```
  </Step>

  <Step title="Install the agent">
    Install using the secret:

    ```bash theme={null}
    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](https://app.anyshift.io/integrations) and `<YOUR_CLUSTER_NAME>` with a meaningful name (e.g. "production-us-east", "staging-eu").

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

  <Step title="Validate the installation">
    Check that the agent is running:

    ```bash theme={null}
    kubectl get pods -n anyshift-agent
    ```

    View agent logs:

    ```bash theme={null}
    kubectl logs -n anyshift-agent -l app.kubernetes.io/name=anyshift-k8s-agent
    ```
  </Step>
</Steps>

## 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

<AccordionGroup>
  <Accordion icon="memory" title="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          |

    <Note>
      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.
    </Note>

    To configure higher memory limits:

    ```yaml theme={null}
    resources:
      limits:
        memory: 2Gi
      requests:
        memory: 1Gi
    ```
  </Accordion>

  <Accordion icon="sliders" title="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:

    ```bash theme={null}
    kubectl create secret generic anyshift-secret \
      --namespace anyshift-agent \
      --from-literal api-key="<YOUR_API_TOKEN>"
    ```

    Create `values.yaml`:

    ```yaml theme={null}
    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:

    ```bash theme={null}
    helm install anyshift-agent anyshift/anyshift-k8s-agent \
      --namespace anyshift-agent --create-namespace \
      -f values.yaml
    ```
  </Accordion>

  <Accordion icon="tags" title="Advanced install: cluster name templating and custom labels">
    **Cluster name templating.** Use Go template syntax for dynamic cluster names:

    ```bash theme={null}
    # 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:

    ```bash theme={null}
    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).**

    ```yaml theme={null}
    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
    ```
  </Accordion>

  <Accordion icon="shield-halved" title="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**

    ```bash theme={null}
    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**

    ```yaml theme={null}
    excludeSecrets: true
    ```

    When `excludeSecrets=true`, the agent's `ClusterRole` drops `get/list/watch` on `v1/secrets` entirely.
  </Accordion>

  <Accordion icon="key" title="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`](https://github.com/anyshift-io/anyshift-k8s-agent/blob/main/chart/anyshift-k8s-agent/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`:

    ```yaml theme={null}
    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.
  </Accordion>

  <Accordion icon="arrow-up-right-dots" title="Upgrade">
    To upgrade the agent to the latest version:

    ```bash theme={null}
    # 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
    ```

    <Note>
      `--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.
    </Note>
  </Accordion>

  <Accordion icon="trash" title="Uninstall">
    ```bash theme={null}
    helm uninstall anyshift-agent --namespace anyshift-agent
    ```
  </Accordion>
</AccordionGroup>