All Products
Search

This Product

    Container Service for Kubernetes:Run application pods that use InClusterConfig at the edge without making pod-facing changes

    Document Center

    Container Service for Kubernetes:Run application pods that use InClusterConfig at the edge without making pod-facing changes

    Last Updated:Mar 25, 2026

    ACK Edge lets you deploy application pods at edge nodes and have them access the Kubernetes API server through InClusterConfig — without modifying the pods themselves. This topic explains how edge-hub intercepts and redirects API traffic transparently, and how to enable local caching so pods can restart cleanly when the cloud connection is interrupted.

    How it works

    When you move an application pod from a cloud cluster to an edge node, two problems arise if the pod uses InClusterConfig:

    • Network isolation: InClusterConfig reads KUBERNETES_SERVICE_HOST and KUBERNETES_SERVICE_PORT to locate the Kubernetes API server. At the edge, the pod is on a different network from the API server in the cloud, so the default address is unreachable.

    • Restart failure: If the cloud connection is interrupted and the pod restarts, it cannot contact the API server to retrieve its workload configuration, which blocks the restart.

    edge-hub solves both problems without requiring any changes to the pod.

    When the cloud connection is healthy

    edge-hub intercepts the pod's API server traffic by transparently rewriting the pod's environment variables — changing KUBERNETES_SERVICE_HOST to 169.254.2.1 and KUBERNETES_SERVICE_PORT to 10268 (the local HTTPS endpoint of edge-hub).

    Because edge-hub rewrites those values at the node level, the pod connects to the local edge-hub proxy instead of the remote API server — with no awareness of the redirect.

    edge-hub also caches API responses locally as they are received from the API server, so the cache stays up to date while the connection is healthy.

    When the cloud connection breaks

    If you have enabled the caching feature, edge-hub serves pod requests from its local disk cache. This allows pods to start and retrieve their workload configurations even without a cloud connection.

    If caching is not enabled, pods that restart during a network outage cannot retrieve their workload configurations and will fail to start.

    imageimage

    Prerequisites

    Before you begin, make sure you have:

    • An ACK Edge cluster with edge-hub running on the edge nodes

    • The application pod deployed on an edge node and configured to use InClusterConfig

    Enable the caching feature of edge-hub

    To enable caching for your application pod, add its User-Agent to the cache_agents field in the edge-hub-cfg ConfigMap.

    Note

    Disable caching for pods that issue a high volume of list or watch requests, because cached data is stored on local disk and can consume significant disk space. Restart pods after enabling caching.

    Step 1: Find the pod's User-Agent

    The User-Agent is the component name your pod uses when making requests to the API server. Find it in one of two places:

    From the pod's startup command: The User-Agent matches the binary name in the startup command.

    apiVersion: v1
kind: Pod
metadata:
  name: edge-app-pod
spec:
  containers:
    - name: "edge-app"
      image: "xxx/edge-app-amd64:1.18.8"
      command:
        - /bin/sh
        - -ec
        - |
          # User-Agent is derived from the binary name: edge-app
          /usr/local/bin/edge-app --v=2

    From edge-hub logs: Search for log lines that match the pattern {User-Agent} get/watch {resource}. For example:

    I0820 07:50:18.899015       1 util.go:221] edge-app get services: /api/v1/services/xxx with status code 200, spent 21.035061152ms

    In this example, the User-Agent is edge-app.

    Step 2: Add the User-Agent to the ConfigMap

    Edit the edge-hub-cfg ConfigMap in the kube-system namespace and add the pod's User-Agent to cache_agents. Separate multiple values with commas.

    apiVersion: v1
kind: ConfigMap
metadata:
  name: edge-hub-cfg
  namespace: kube-system
data:
  # Cache API responses for the pod whose User-Agent is "edge-app".
  # Restart the pod after making this change.
  cache_agents: "edge-app"   # Separate multiple components with commas (,).

    After saving the ConfigMap, restart the application pod for the change to take effect.

    Step 3: Verify that caching is active

    On the edge node that hosts the application pod, check whether cache data exists at:

    /etc/kubernetes/cache/{User-Agent}

    What's next