tencent cloud

Tencent Kubernetes Engine

DokumentasiTencent Kubernetes EngineApplication ConfigurationComponent and Application Management Add-On Managementagent-network Component Description

agent-network Component Description

Unduh
Mode fokus
Ukuran font
Terakhir diperbarui: 2026-10-23 16:19:17
Diterjemahkan oleh AI

Component Introduction

In AI Agent scenarios, workloads typically need to access code repositories, COS, Tencent Cloud VectorDB, internal APIs, or other Agent services. Compared with regular applications, Agents can autonomously generate code, initiate network requests, and use business credentials. Without unified network governance, risks may arise, such as accessing production databases, bypassing controlled entry points, exposing credentials directly to Pods, call identity spoofing, and missing audits.
Traditional Kubernetes networking focuses on connectivity by default. It typically does not converge Agent Pod TCP traffic and UDP/53 DNS traffic to a unified policy enforcement point, nor can it perform credential injection and access auditing without modifying business Pods. Other protocols fall outside the scope of current HTTP policy governance. The Sidecar approach provides some proxy capabilities, but it requires injecting an additional container into each workload, which leads to high integration and Ops costs. Moreover, bypassing controls depends on the network configuration within the Pod.
agent-network is a cloud-native network data plane component that caters to AI Agent workloads and is delivered as a TKE Addon. It installs the Agent CNI on explicitly authorized Canary Worker nodes. Currently, nodes rather than Pod Labels serve as the access boundary. Non-hostNetwork Pods that are subsequently created on Canary nodes and use the primary CNI will enter the Agent CNI path and obtain a Fake IP address. The host iptables forcibly converges DNS and TCP traffic to the node-local ZeroProxy, which enforces access policies, performs credential injection, verifies call identities, intercepts direct bypasses, and provides unified auditing.
Core objectives:
Deny by default.
All traffic must pass through the proxy.
Credentials are not injected into Agent Pods.
Access processes are auditable.
Node changes can be rolled out in a phased manner.
Data plane failures can be rolled back.
Characteristic
Description
Real CNI access
Agent CNI configures veth, the agentcni0 bridge, Fake IP address, default routes, and node-side iptables rules for subsequently created Pods that use the primary CNI on Canary nodes.
Forced traffic convergence
UDP/53 traffic is redirected to the node DNS Proxy. TCP traffic is redirected to ZeroProxy, except for traffic that matches the Service CIDR and is marked for bypass.
Default deny
Egress, Ingress, and Direct Bypass support default deny. Sensitive Metadata/CGNAT addresses have built-in deny protection.
Credential isolation
Business Agent Pods do not mount credentials. Credentials are stored in Kubernetes Secrets and are read and injected by ZeroProxy during forwarding.
Dynamic policy
AgentNetworkPolicy supports policy declarations. Controller updates ConfigMap and triggers ZeroProxy hot reload.
Service compatibility
Service CIDR traffic is handed back to kube-proxy and the primary CNI using fwmark, avoiding impact on Kubernetes ClusterIP Service.
Canary release and rollback
Only nodes with the Canary tag will have CNI installed. Node-level rollback and host residue check are provided.

Integration with Kubernetes

agent-network leverages Kubernetes capabilities for scheduling, DaemonSets, Deployments, CRDs, ConfigMaps, and Secrets:
agent-cni-installer runs as a privileged DaemonSet and is scheduled only on Canary nodes. It installs the CNI binary, CNI configuration, bridge, sysctl settings, and iptables rules.
zeroproxy runs as a hostNetwork DaemonSet and provides a local proxy on each Canary node.
credential-upstreams provides protected upstreams for testing purposes to verify complete functionality. In production, replace them with real upstreams.
agent-network-controller runs as a Deployment, watches AgentNetworkPolicy and AgentNetworkClass, and coordinates policies and basic CNI configurations.
AgentNetworkPolicy, ConfigMap, and Secret carry policies, upstream addresses, and credential references.
TKE Addon uses Charts to uniformly create component resources, pull images, and deliver default parameters.
The complete traffic path is as follows:
Agent Pod eth0(Fake IP)
  → Default route
  → agentcni0 bridge
  → Host iptables PREROUTING
      ├── UDP/53 → REDIRECT to ZeroProxy DNS :18053
      ├── Service CIDR → Returned to kube-proxy/primary CNI after fwmark
      └── TCP → REDIRECT to ZeroProxy :18080
  → Policy matching, identity verification, credential injection, and auditing
  → Target service
After TKE packages agent-network as an Addon, users can install it through the console or the InstallAddon API. However, because the component modifies the CNI, bridge, and iptables on target nodes, you must still follow the canary process of "single-node Canary → dual-node Canary → rollback residual check."

Core Concepts

Concept
Description
Agent workload
Newly created Pods that are scheduled to Canary nodes with Agent CNI enabled and require network governance. Dedicated Canary nodes are currently used as the isolation boundary instead of Pod Label selectors.
Canary node
Worker nodes with the tke-agent-network.io/agent-cni-canary=true label that are explicitly authorized to install Agent CNI.
Agent CNI
A real CNI plugin responsible for Fake IP address, Pod network namespaces, veth, the agentcni0 bridge, routes, state files, and iptables rules.
Fake IP
A dedicated address assigned by Agent CNI to Agent Pods. It is not equivalent to the primary CNI Pod IP address and is used for traffic convergence and source identity mapping.
ZeroProxy
A node-local policy proxy that listens on :18080 and is responsible for Egress, Ingress, credential injection, Direct Bypass, auditing, and metrics.
DNS Proxy
A UDP DNS proxy of ZeroProxy that listens on :18053 by default and receives DNS requests from Fake-IP Pods.
Service CIDR
Address range of cluster Kubernetes Services. It must be provided during installation to prevent ClusterIP Service traffic from entering the HTTP policy proxy.
AgentNetworkPolicy
A Namespaced CRD that declares Egress Allow/Credential/Deny, Ingress, and Direct Bypass policies.
AgentNetworkClass
A Cluster-scoped CRD that declares node-level network parameters such as Fake IP CIDR, Service CIDR, and proxy ports. Some API fields are currently only delivered for recording and do not trigger data plane mode switching.
CNI State
Pod network/identity state persisted by Agent CNI. ZeroProxy can use this state to map Fake IPs back to Pod identities.
Direct Bypass
Behavior in which an Agent Pod directly accesses a destination address within the Agent Fake-IP CIDR and attempts to bypass the controlled ingress. This behavior is denied by default. Other TCP outbound requests are still processed by Egress policies.

Strengths

Comparison with Standard Kubernetes Pod Networking

Dimension
Standard Pod Network
agent-network
Egress Access
Applications can directly access reachable network targets.
ZeroProxy uniformly enforces Allow, Credential, and Deny.
Credential Management
Secrets are often injected into business Pods.
Credentials are mounted only to ZeroProxy and injected during rule-based forwarding.
DNS
Uses the primary CNI/cluster default DNS path.
DNS of Fake-IP Pods is centrally processed by the node-local DNS Proxy.
Inter-Agent Calls
Relies on the service to perform authentication.
Supports Caller/Target rules and Fake-IP source identity verification.
Bypass Control
A Pod may attempt to directly connect to the target.
Node iptables enforces traffic convergence, and Direct Bypass is denied by default.
Audit
Logs are scattered across business systems.
ZeroProxy centrally outputs policy hits and access audit logs.
Node Changes
No CNI changes.
CNI changes require Canary and verifiable rollback.

Comparison with Sidecar Proxies

Dimension
Sidecar Proxy
agent-network
Access Mode
Inject a proxy container into each Pod.
Node-level Agent CNI + ZeroProxy
Service Modification
May require modification of Deployment/Pod templates.
Agent applications do not need to be aware of the local proxy address.
Resource consumption
One proxy resource per Pod
One ZeroProxy per Canary node
Traffic Interception
Mostly relies on in-Pod redirection and injection logic.
Forcibly taken over by CNI and node iptables in the network path.
Credential Location
May exist in both the business Pod and the Sidecar.
Credentials are retained only in the Secret mounted by ZeroProxy.
Risk Scope
Mainly affects a single workload.
Involving node CNI, operations must strictly follow the canary and rollback process.

Typical Use Cases

Coding Agent Access to Code Repositories

Coding Agents need access to public dependencies or private code repositories, but they should not hold long-term tokens. You can allow access to public repositories and configure Credential rules for private repositories, with ZeroProxy injecting the Authorization request header.
apiVersion: agent.tke.cloud.tencent.com/v1alpha1
kind: AgentNetworkPolicy
metadata:
  name: coding-agent-network
  namespace: tke-agent-network-real
spec:
  podSelector: {}
  priority: 100
  egress:
    allow:
      - name: public-git
        host: git.example.com
        protocol: tcp
        port: 443
    credential:
      - name: private-git
        host: git.internal.example.com
        header: Authorization
        valueFrom:
          name: zeroproxy-credentials
          key: REPO_TOKEN
    deny:
      - name: production-db
        host: prod-db.internal
  directBypass:
    defaultAction: deny
Note:
By default, the Controller listens only on the namespace where the Addon resides (default: tke-agent-network-real). Business Pods can be in other namespaces, but AgentNetworkPolicy must be created in the namespace that the Controller listens on.

RAG Agent Access to Tencent Cloud VectorDB

You can configure it to allow RAG Agents to access COS and the specified Tencent Cloud VectorDB. Access to the vector database is authenticated by ZeroProxy, which injects a search Token. Access to other databases or highly sensitive data services is denied by default.

Multi-Agent Invocation Governance

When multiple Agents call each other, you can define Ingress rules based on Caller and Target. For Fake-IP Pods managed by the Agent CNI, ZeroProxy verifies the caller identity claim in X-Agent-Caller against the source Pod identity and matches target rules based on X-Agent-Target, reducing the risk of bypassing authorization by merely forging request headers.
spec:
  podSelector: {}
  ingress:
    allow:
      - caller: "sa:agent-workloads:planner"
        target: "agent-server"
    deny:
      - caller: "sa:agent-workloads:untrusted-agent"
        target: "agent-server"

Preventing Access to Sensitive Addresses

ZeroProxy denies the following sensitive address ranges by default. This built-in denial takes precedence even if a business policy explicitly allows them:
169.254.169.254/32
100.64.0.0/10

Product Status and Support Scope

Item
Description
Current Version
Addon / Chart 0.3.0
Release Form
TKE Addon / Helm Chart
Release status
In the grayscale release phase; the actual installable regions and versions are subject to what is displayed in the TKE Addon console.
Supported cluster type
TKE managed cluster (MANAGED_CLUSTER)
Kubernetes Version
Declared by Chart: greater than or equal to 1.20.0-0
Node OS
Linux
Node Architecture
The current Chart targets amd64 nodes.
Primary CNI Compatibility
Verified in real clusters in TKE ENI / Multus environments. The actual Service CIDR must be provided during installation.
Policy Protocol
HTTP; TLS SNI passthrough is disabled by default. It is not recommended to enable it when trusted DNS or identity verification is not configured.
Billed or not
The component is not billed separately, but it consumes CPU, memory, network, and log storage resources on the target node.

Use Limits

Before deployment, confirm the following limits:
1. Only Linux nodes are supported. The original destination restoration for Direct Bypass relies on the Linux SO_ORIGINAL_DST mechanism.
2. Agent CNI modifies the CNI configuration, bridge, sysctl settings, and iptables rules on target nodes. You must first verify these changes on a dedicated Canary Worker.
3. Do not enable Agent CNI on bastion host nodes, control nodes, or nodes running critical production workloads.
4. agentCNI.installerEnabled is enabled by default. Only nodes with the Canary Tag will schedule the Installer and undergo CNI changes.
5. When agentCNI.installerEnabled=true, agentCNI.serviceCIDRs is a required installation parameter. If it is not provided, the Chart will refuse to render. You can omit this configuration only when installing the control plane only and explicitly disabling the Installer.
6. The Chart default value of agentCNI.fakeIPCIDR is 169.254.77.0/24, but it is not currently passed to the Installer as the actual CIDR parameter. When no AgentNetworkClass override is configured, the Installer derives a node-level /24 CIDR based on the node name. The actually allocated addresses must not conflict with node, Pod, Service, VPC, or other infrastructure network segments.
7. ZeroProxy uses 18080/TCP, and DNS Proxy uses 18053/UDP. Before installation, confirm that the target node ports do not conflict.
8. AgentNetworkPolicy uses valueFrom.name/key to reference a Secret mounted to ZeroProxy. The Controller converts it to valueFromFile in the runtime policy. valueFromEnv is not supported.
9. zeroproxy.tls.allowUnverifiedSNI is disabled by default. Do not enable it when no trusted DNS or identity verification capability is available.
10. Existing Pods are not automatically migrated to Agent CNI. You need to rebuild and schedule new Pods to Canary nodes according to your business plan. Currently, podSelector / workloadSelector do not serve as Pod-level CNI access switches, so Canary nodes should remain dedicated nodes.
11. You must perform CNI rollback before uninstalling the Addon. Uninstalling only the Helm Release or Addon does not replace host data plane cleanup.
12. AgentNetworkPolicy.spec.podSelector and AgentNetworkClass.spec.workloadSelector have been added to the API, but they are not currently used as Pod-level selective CNI access switches. At this stage, dedicated Canary nodes serve as the workload isolation boundary.
13. AgentNetworkClass.spec.proxy.failMode and spec.cni.defaultConnectivity are currently API/downstream fields. In v0.3.0, the data plane still runs in Fail-Close / ZeroConnectivity mode, so you cannot rely on FailOpen for automatic direct connectivity.
14. The Addon / Chart / team image release version is 0.3.0 / v0.3.0. However, the current Agent CNI node version record may still show v0.2.5. This issue does not affect the verified data plane features, but it affects version tracking and upgrade diagnosis, and needs to be fixed and re-verified later.

Preparations Before Installation

1. Planning Node Roles

Select at least two interruptible, non-critical Worker nodes:
The first node is used for single-node Canary validation.
The second node is used for two-node validation.
Bastion host nodes and critical business nodes must not be involved in CNI replacement.
View nodes:
kubectl get node -o wide
kubectl get pod -A -o wide

2. Tagging the First Canary Node

kubectl label node <first-worker-node-name> \\
  tke-agent-network.io/agent-cni-canary=true
After validation is complete and you are ready to perform two-node validation, apply the same label to the second Worker node:
kubectl label node <second-worker-node-name> \\
  tke-agent-network.io/agent-cni-canary=true

3. Confirming the Service CIDR

You must confirm the actual Service CIDR of the cluster. You can obtain it from the TKE cluster configuration or determine it with the help of existing ClusterIPs:
kubectl get svc -A \\
  -o jsonpath='{range .items[*]}{.spec.clusterIP}{"\\n"}{end}' \\
  | grep -v -E '^(None|<none>|)$' \\
  | sort -u \\
  | head
For example, when the ClusterIP is in the 192.168.x.x range, common Service CIDRs are:
192.168.0.0/16
Note:
The Service CIDR must be based on the actual cluster configuration and cannot be guessed solely from examples.

4. Preparing a Rollback Window

Before installation, confirm the following:
You can log in to the target Worker.
The current state of the node has been recorded.
A window is available for performing rollback and node residual checks.
Production traffic has been diverted away from the Canary node, or rebuilding is allowed during validation.

Installing agent-network

Method 1: Console Installation

1. Log in to the TKE console and go to the target cluster.
2. Go to "Component Management" and select Create Component.
3. Select agent-network.
4. Select Addon version 0.3.0.
5. Provide the actual Service CIDR in the parameter.
6. Submit the installation and wait for the component to run.
A basic installation requires at least the following:
agentCNI:
  serviceCIDRs:
    - <Actual Service CIDR>

Method 2: API Installation

Call the TKE InstallAddon API. The following is a basic installation JSON example:
{
  "Region": "ap-<region>",
  "ClusterId": "cls-xxxxxxxx",
  "AddonName": "agent-network",
  "AddonVersion": "0.3.0",
  "RawValues": "{\\"agentCNI\\":{\\"serviceCIDRs\\":[\\"<Actual Service CIDR>\\"]}}"
}
The default Chart already uses team component images, so you do not need to repeatedly set image.registry, image.tag, or the component repository in RawValues.
Only for full demo/e2e verification, additionally configure the test-specific settings:
credentialUpstream.enabled=true.
credentials.repoToken and credentials.ragToken.
Set zeroproxy.reload.enabled=true, and you must set a non-empty zeroproxy.reload.token.
Test mapping for zeroproxy.upstreams.
Credential policy rules.
These test tokens and test upstreams should not be directly reused in real production environments. The current Chart renders credentials.* and the reload token into component Secrets, so tokens for full demo/e2e verification can only be passed in through controlled API requests within an isolated test environment. Do not write production credentials into RawValues, command lines, sample files, or terminal history. After credential-upstreams is enabled, the test component reads the expected token from the Secret to verify the injection result. This does not change the product boundary that business Agent Pods do not mount credentials.

Post-Installation Verification

1. Viewing Component Status

The following command uses the default namespace tke-agent-network-real as an example:
kubectl get ds,deploy,pod -n tke-agent-network-real -o wide
Expected behavior for single-node Canary:
agent-cni-installer  1/1 Ready
zeroproxy            1/1 Ready
agent-network-controller 1/1 Ready
The full demo/e2e mode also runs:
credential-upstreams 1/1 Ready
When full demo/e2e is enabled, after the two-node Canary scale-out, the three DaemonSets agent-cni-installer, zeroproxy, and credential-upstreams are all expected to be 2/2 Ready. For a default installation, verify that the first two DaemonSets are 2/2 Ready.

2. Viewing the Actual CNI Installation Status

On the target Worker, check:
ip addr show agentcni0
ls -l /opt/cni/bin/agent-cni
ls -l /etc/cni/net.d/00-agent-cni.conf
ls -la /var/lib/tke-agent-network/agent-cni/
Check sysctl:
sysctl \\
  net.ipv4.ip_forward \\
  net.ipv4.conf.all.rp_filter \\
  net.ipv4.conf.default.rp_filter \\
  net.ipv4.conf.agentcni0.rp_filter
Expected:
net.ipv4.ip_forward = 1
rp_filter = 0

3. Running Built-in Diagnostics

kubectl exec -n tke-agent-network-real ds/agent-cni-installer -- \\
  /agent-cni --doctor \\
  --doctor-state-dir=/host/var/lib/tke-agent-network/agent-cni \\
  --doctor-host-cni-bin=/host/opt/cni/bin \\
  --doctor-host-cni-conf=/host/etc/cni/net.d \\
  --doctor-zeroproxy-url=http://127.0.0.1:18080/healthz
Expected output:
AGENT_CNI_DOCTOR_PASSED

4. Verifying HTTP e2e and Real CNI e2e

A complete verification should cover at least the following:
Verification Level
Verification Content
HTTP e2e
Allow, Credential, Deny, Ingress allow/deny, and Coding/RAG/Gateway demo of ZeroProxy
Real CNI e2e
Fake-IP Pod,iptables REDIRECT,Coding,RAG,Direct Bypass deny
Primary CNI Compatibility
DNS,ClusterIP Service
Control plane
Dual ZeroProxy ConfigMap projection/reload, AgentNetworkPolicy eventually Active
Security and observability
Audit logs do not leak credentials, and metrics are accessible.
The success markers in a complete verification are distinguished by verification level as follows:
HTTP e2e (policy, credentials, and ingress) should include:
EGRESS_ALLOWED_BY_POLICY
CREDENTIAL_INJECTED_BY_ZEROPROXY
EGRESS_DENIED_BY_POLICY
INGRESS_ALLOWED_BY_ZEROPROXY
INGRESS_DENIED_BY_ZEROPROXY
CODING_AGENT_DEMO_PASSED
RAG_AGENT_DEMO_PASSED
MULTI_AGENT_GATEWAY_DEMO_PASSED
Real CNI e2e (Fake IP, iptables REDIRECT, and node data plane) should include:
EGRESS_ALLOWED_BY_POLICY
CODING_AGENT_DEMO_PASSED
RAG_AGENT_DEMO_PASSED
DIRECT_BYPASS_DENIED_BY_ZEROPROXY
DNS and ClusterIP Service are independent primary CNI compatibility checks and should include:
MAIN_CNI_DNS_PASSED
MAIN_CNI_SERVICE_PASSED
MAIN_CNI_COMPAT_CHECKS_PASSED

Network and Security Configuration

Fake IP and Service CIDR

Agent CNI uses a node-level Fake IP address CIDR to assign addresses to Pods. When no AgentNetworkClass override is configured, the Installer derives a different node-level /24 CIDR based on the node name. agentCNI.fakeIPCIDR currently only participates in Chart parameter validation and is not passed to the Installer as an effective CIDR parameter. Service CIDR traffic must bypass ZeroProxy and be forwarded by kube-proxy and the primary CNI.
Fake-IP Pod
  ├── DNS(UDP/53)→ ZeroProxy DNS Proxy
  ├── ClusterIP Service → fwmark bypass → kube-proxy/primary CNI
  └── Other TCP → ZeroProxy policy proxy

Egress Governance and Auditing

ZeroProxy processes outbound traffic in the following priority order:
deny → credential → allow → deny by default
Recommendations:
By default, only domains that are genuinely required for business access are allowed.
AgentNetworkPolicy uses a Secret valueFrom.name/key reference. The Controller converts it to valueFromFile at runtime and does not write it into the Agent Pod.
Explicitly deny sensitive targets such as databases, customer data services, and Metadata.
Retain audit logs and configure alarms for abnormal deny/credential hits.

Direct Bypass

Default configuration:
policy:
  directBypass:
    defaultAction: deny
It is recommended to keep the default deny policy to prevent Agent Pods from directly connecting to targets within the Agent Fake-IP CIDR. Other TCP outbound requests are processed by the Egress policy and are denied by default when they do not match any Allow or Credential rules.

Upgrade, Uninstall, and Rollback

Upgrade

Upgrades should follow the same node canary principle as installation:
1. First, validate the target image and component status on a single-node Canary.
2. Run HTTP e2e and real CNI e2e.
3. Then extend to the second node.
4. Confirm the two-node policy reload, DNS/Service, and rollback.
5. Then proceed to more nodes or more regions.
Before the upgrade, record the current Addon parameters, policy CRs, AgentNetworkClass, and node labels.

Uninstallation

Do not directly uninstall the Addon as a substitute for CNI rollback.
Correct sequence:
Stop agent-cni-installer.
Execute rollback-agent-cni on the Canary node.
→ Check for residual files on the host.
→ Remove the Canary tag.
Then uninstall the Addon or clean up the remaining components.

Rollback Residue Check

Every Worker that has participated in a CNI replacement must confirm that the following items do not exist:
agentcni0 bridge
AGENT-CNI iptables rules
/opt/cni/bin/agent-cni
/etc/cni/net.d/00-agent-cni.conf
The /var/lib/tke-agent-network/agent-cni state file

Troubleshooting

agent-cni-installer Not Ready After Installation

Check:
kubectl get pod -n tke-agent-network-real -o wide
kubectl describe pod -n tke-agent-network-real <installer-pod>
kubectl logs -n tke-agent-network-real <installer-pod>
Common causes:
Symptom
Possible cause
Solution
The DaemonSet is 0/0.
The node does not have the Canary tag.
Add the tke-agent-network.io/agent-cni-canary=true label only to selected Worker nodes.
Chart rendering failed.
serviceCIDRs not provided.
Pass the actual cluster Service CIDR when Installer is enabled.
ImagePullBackOff
Abnormal image address, public permission, or node network
Check the team image address and node pull events.
preflight failed.
The CNI path, port, or host environment does not meet the requirements.
View Installer preflight logs.
Pod creation indicates that PriorityClass does not exist.
Transient race condition in resource creation order
Wait for the DaemonSet to retry automatically. If the failure persists, check whether the PriorityClass is created.

DNS or ClusterIP Service Unreachable

Check:
iptables -t nat -S
iptables -t mangle -S
kubectl get svc -A -o wide
Key points to confirm:
Whether agentCNI.serviceCIDRs is the actual Service CIDR.
Whether AGENT-CNI-MANGLE contains the 0x77 marking rule for the Service CIDR.
Whether AGENT-CNI-PREROUTING executes RETURN after the mark is hit.
Whether agentcni0, ip_forward, and rp_filter are normal.

AgentNetworkPolicy Not Active for a Long Time

Check:
kubectl get agentnetworkpolicy -A -o wide
kubectl logs -n tke-agent-network-real deploy/agent-network-controller --tail=200
kubectl logs -n tke-agent-network-real ds/zeroproxy --tail=200
In a dual ZeroProxy scenario, the ConfigMap volume projection may briefly return 409 policy version not yet projected. The Controller should retry and eventually bring the Policy to:
phase=Active
observedGeneration=<current generation>

Nodes Remain After rollback

Do not only delete the Addon. Re-execute the rollback and log in to each Canary Worker separately to check the bridge, iptables, CNI binaries, CNI configuration, and state directory.

FAQs

Q1: Will agent-network Replace the Primary CNI of the Entire Cluster?

No. The component only attaches Agent CNI to Pods that are subsequently created and scheduled to the node on target Workers with the Canary tag. Currently, selective attachment based on Pod Labels is not supported, so dedicated Canary nodes should be used. Service traffic is still handled by kube-proxy and the primary CNI. Bastion nodes and untagged Workers do not participate in the replacement.

Q2: Why Is the Service CIDR Required?

Agent CNI redirects TCP traffic to ZeroProxy, except for Service bypass traffic. If ClusterIP Service addresses cannot be identified, Service traffic may be incorrectly sent to the HTTP policy path, affecting Kubernetes service communication. Therefore, you must provide the actual Service CIDR before installation.

Q3: Why Are Single-Node and Two-Node Canary Required?

A single node is used to first verify installation, CNI takeover, and the minimal data plane. A dual-node setup is used to verify different Fake IP CIDR assignments, cross-node component operation, Service compatibility, and the policy reload recovery capability of multiple ZeroProxy Pods.

Q4: What Is the Difference Between HTTP e2e and Real CNI e2e?

HTTP e2e uses a hostNetwork Job to directly access the local ZeroProxy, verifying policies, credential injection, and proxy logic. Real CNI e2e uses a non-hostNetwork Pod to verify the complete data plane path involving Fake IP, agentcni0, node iptables REDIRECT, and ZeroProxy. Both should pass.

Q5: Will Nodes Recover Automatically After the Addon Is Uninstalled?

No guarantee is provided. CNI modifies the host network state, so you must perform rollback and complete residual checks first. Directly uninstalling the Addon cannot replace node-level rollback.

Q6: Can Test Tokens and Upstreams Be Used Directly in Production?

No. The full demo/e2e uses test tokens, test domains, and local test upstreams. Production environments should connect to real business upstreams, use controlled Secrets, and configure policies based on least privilege.

Parameter and Internal Component Reference

Common Installation Parameters

Parameter
Type
Default Value
Description
canaryLabel.key
string
tke-agent-network.io/agent-cni-canary
Select the tag Key of the Canary node.
canaryLabel.value
string
true
Tag Value for selecting the Canary node.
agentCNI.installerEnabled
bool
true
Create a real CNI Installer DaemonSet or not
agentCNI.serviceCIDRs
string array
[]
Actual cluster Service CIDR; required when Installer is enabled.
agentCNI.fakeIPCIDR
string
169.254.77.0/24
Currently only participates in Chart parameter validation. When NetworkClass override is not configured, the actual node CIDR is derived from the node name.
agentCNI.zeroProxyPort
int
18080
Target port for TCP redirection
zeroproxy.dnsProxy.listen
string
:18053
DNS Proxy listening address
zeroproxy.reload.enabled
bool
false
Enable the policy hot-reload authentication API from Controller to ZeroProxy or not
credentialUpstream.enabled
bool
false
Deploy test credentials to verify the upstream or not
controller.enabled
bool
true
Enable CRD Controller or not
rollback.enabled
bool
false
Render a temporary CNI rollback DaemonSet or not

Internal Component Description

Layer
Component
Responsibilities
Node data plane
agent-cni-installer
Install/run Agent CNI, and configure bridge, iptables, sysctl, and CNI status.
Node data plane
agent-cni
Real CNI binary invoked by kubelet to process Pod ADD/DEL/CHECK.
Node agent
zeroproxy
Egress, Ingress, Credential, DNS, Direct Bypass, audit, and metrics.
Control plane
agent-network-controller
Reconcile AgentNetworkPolicy / AgentNetworkClass, update ConfigMap, and coordinate reload.
Test dependencies
credential-upstreams
Protected test upstream for verifying credential injection in full e2e.
Validation tool
agent-network-e2e
Verification Job for HTTP, real CNI, DNS/Service, and Agent demo.
Temporary rollback component
rollback-agent-cni
Runs only when rollback.enabled=true to clean up the node CNI data plane.

Topik sebelumnya: Buffer Operator DescriptionTopik selanjutnya: TCR Hosts Updater

Bantuan dan Dukungan

Apakah halaman ini membantu?

masukan

Search
    Enter keywords to search documentation