Skip to content
openkruisePublic

About

No description, website, or topics provided.

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

51 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Ztunnel

ztunnel is the Layer 4 traffic enforcement data plane for Agentio.

How does it differ from Istio ztunnel?

  • Workload traffic policies — enforces native TrafficPolicy references ordered by the control plane for every Workload.
  • Non-TCP firewall enforcement — translates traffic policies into inbound and outbound iptables or nftables rules for UDP, ICMP, and other supported non-TCP traffic, with automatic backend detection and live rule updates.
  • Per-workload sidecar deployment — runs a dedicated ztunnel alongside each sandbox workload instead of as a node-level proxy, enforcing traffic policy at the workload boundary.

Sandbox preparation

With ENABLE_SANDBOX_MANAGER=true, PrepareSandbox waits for the local Sandbox configuration and Workload binding, then persists the registration before returning gRPC OK. Success confirms local preparation, not EPE replica readiness or completion of asynchronous firewall rule installation.

The file token module is optional and disabled by default. Agents deployments using the file token protocol must explicitly set SANDBOX_TOKEN_ENABLED=true alongside ENABLE_SANDBOX_MANAGER=true. When enabled, preparation additionally requires a nonempty loaded token: a missing or empty token returns FAILED_PRECONDITION; provision it and retry the same Sandbox ID. Token read or JSON validation errors return INTERNAL, and token module initialization errors fail proxy creation. Outbound requests carry identity fields in x-agentio-sandbox-metadata. When disabled, ztunnel does not create or watch the token directory, require a token for preparation, or add the metadata header. Sandbox registration and the Sandbox ID header are unaffected.

In dedicated mode, tokens are read directly from SANDBOX_TOKEN_PATH (default: /var/opt/sandbox/agent-token/), and registration is stored in SANDBOX_STATE_DIR. The enabled token module creates the token directory when starting. The agents producer writes <md5(namespace-name)>.token containing the token response JSON; no Workload UID subdirectory or filename match with the xDS Sandbox ID is required. The configured directory must expose the runtime's token files to ztunnel. SANDBOX_WATCHER_DEBOUNCE_MS controls the enabled module's watcher debounce. This preparation flow is validated for dedicated deployment; node-level token delivery is outside this scope.

The manager owns the shared preparation operation used by RPC, including binding checks and durable registration, and restores registered identities on startup. Each outbound TCP connection or UDP session captures its ready Sandbox and cached metadata before routing. Policy selection, pooling and HBONE headers use this context; HBONE construction does not read token files. Unprepared connections continue with Workload policies and carry no Sandbox identity or metadata. Token readiness retries both missing files and cached empty files without waiting for a watcher update. Token formats and explicit RPC preparation remain unchanged.

Sandbox metadata header

Token files are JSON objects with nonempty string fields accessToken and sandboxClientId. Other response fields are ignored. File loading parses these fields and caches their metadata entries under the existing filename key; multiple files remain separate Map entries. The token module contributes its agent-identity.* entries to a shared SandboxMetadata collection. Other modules can contribute their own namespaced entries to the same collection; outbound connection setup serializes the combined collection as a Structured Fields Dictionary with String values, defined by RFC 9651. Replacing an existing key updates its value, so serialization emits each key only once, in key order. No JWT signature or expiry validation is performed by ztunnel.

x-agentio-sandbox-metadata: agent-identity.access-token="eyJ...abc.def", agent-identity.sandbox-client-id="AbC+/xyz="

Consumers use a Structured Fields Dictionary parser, not comma splitting or a JSON parser. Known entries must be String Items with nonempty values; Inner Lists and other bare-item types are not accepted for those entries. Unknown keys and parameters are ignored. Strings contain only printable ASCII (0x20..=0x7e); quotes and backslashes are escaped by the standard serializer. Token loading rejects controls and non-ASCII values without including credentials in errors. Percent signs, commas, +, /, and = retain their literal meaning after SF parsing; no percent-decoding or Base64 decoding is required.

The sender emits one header and omits it for empty metadata. Recipients combine repeated field lines in order using the standard SF rules; duplicate Dictionary keys use the last value, as specified by RFC 9651. A parse failure or an invalid known entry invalidates the entire field. Missing or invalid metadata supplies no credentials and must not bypass the gateway's authentication requirements.

The header is marked sensitive to avoid HTTP/2 dynamic-table indexing. It is an internal credential header, separate from tracing baggage, and must not be logged as ordinary metadata. The receiving gateway must support Structured Fields before this change is deployed; neither the previous unquoted KV encoding nor JSON is emitted.

The previous x-agentio-sandbox-token header containing Base64-encoded JSON is no longer emitted. EPE must support the new header before deploying this change. The token file format is unchanged. The Sandbox discovery ID is sent in x-agentio-sandbox-id; the gateway captures it as agentio.sandbox.id. The previous x-agentio-sandbox-uid header is no longer emitted. Upgrade the sending ztunnel and receiving gateway together.

About

No description, website, or topics provided.

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages