Install and Enroll Istio Ambient Safely

This course is built around the public Zheta Kubernetes Lab monorepo. The excerpt below is runnable source, not pseudocode.

Source: gitops/apps/forge/mesh/ambient-enrollment/namespace-patch.yaml

metadata:
  name: zheta-forge
  labels:
    istio.io/dataplane-mode: ambient

Code to reality

Declared intent

Enroll Forge in ambient transport without selecting a waypoint or injecting application sidecars.

Interpreter

Kustomize patches the Namespace; Istio CNI and ztunnel observe the ambient label while later L4/L7 components remain absent.

Software effect

Forge traffic becomes eligible for ambient HBONE transport while application Pod specs and ServiceAccount mappings stay unchanged.

Hardware effect

Per-node ztunnel processes consume node CPU, memory, and network capacity outside application containers.

Observable evidence

Ambient label, strict peer authentication, compatibility policies, unchanged container identities, and later-stage absence checks prove enrollment state.

The source tables below remain the detailed contract. Begin with these customer paths:

• D31-UC-01
  • Person: Platform operator
  • Job: Install approved ambient prerequisites into one exact cluster
  • Observable result: Gateway API CRD, istio-base, istiod, istio-cni, and ztunnel are present at pinned versions while Forge remains unenrolled
• D31-UC-02
  • Person: Forge service owner
  • Job: Enroll only zheta-forge without changing application containers or introducing a waypoint
  • Observable result: The ambient label and forge-strict-mtls reconcile; HBONE and kubelet-health paths remain declared; five workloads retain existing ServiceAccounts

Now turn each customer job into a story with a result that an engineer can check:

• D31-US-01
  • Story: As a platform operator, I want pinned ambient components installed behind context and approval gates, so that an accidental cluster or version…
  • Observable acceptance: Record contains context, cluster-info result, approval, Gateway API URL and checksum, Helm chart versions, rollout identities, time, and run ID
• D31-US-02
  • Story: As a Forge service owner, I want Git-controlled namespace enrollment with strict peer authentication, so that I can reverse only this namespace…
  • Observable acceptance: Ambient label and STRICT mode equal source; no waypoint label or AuthorizationPolicy exists; five ServiceAccounts persist

Finally trace each story through the system that owns its state and the evidence that proves the outcome:

• D31-FLOW-01
  • Trigger: Approved operator selects a disposable cluster and service owner approves namespace enrollment
  • Responsible systems: Shell gates, curl, checksum tool, Kubernetes API server, Helm, Istio charts, Deployment and DaemonSet controllers
  • Authoritative state: mesh/istio-ambient/versions.env, install script, Helm release records, and Kubernetes API objects
  • Owned record: MeshVersionPin
  • Observable evidence: Context, approval, source revision, checksums, Helm releases, rollout UIDs, enrollment objects, absence checks, environment, time, and run ID
  • Failure signal: Context or checksum veto, non-deployed Helm release, unavailable CRD, or failed istiod, CNI, or ztunnel rollout
• D31-FLOW-02
  • Trigger: Context, approval, checksum, rollout, or post-enrollment probe disagrees
  • Responsible systems: Kustomize, Kubernetes API server, Istio controllers, Istio CNI, ztunnel, and Forge Deployment controllers
  • Authoritative state: Git overlay is desired state; Namespace, PeerAuthentication, NetworkPolicies, ServiceAccounts, Pods, and evidence record are observed state
  • Owned record: MeshInstallation
  • Observable evidence: Veto reason, last completed gate, unchanged or recovered baseline result, affected namespace, context, source revision, time, and incident ID
  • Failure signal: Label/strict-mode drift, missing compatibility policy, unexpected waypoint/authorization state, or workload identity change

Enterprise problem: Installing a mesh and enrolling workloads as one opaque action can redirect live packets before the cluster components, target context, or rollback boundary are proven, turning a security change into an outage. Whole-course context: The incoming Day 30 artifact is a revision-bound live baseline of the five-service Forge request path, including checked-in positive and denied NetworkPolicy evidence. Today’s slice: The platform operator installs checksum-pinned Gateway API v1.5.1 resources and Helm-pinned Istio 1.30.3 components; the Forge owner then applies only ambient-enrollment-local, which adds ambient enrollment, namespace-wide STRICT peer authentication, and HBONE/health-probe NetworkPolicy compatibility. End-of-day evidence: Exact context, approval, versions, Helm releases, controller and node-agent rollouts, the ambient label, strict mode, compatibility policies, and unchanged workload identities form the enrollment record. Still unsolved: L4 authorization, waypoint selection, L7 method/path policy, live denial, mutual-TLS telemetry, bounded failure, rollback execution, customer ingress, and production rollout remain deferred.

A cluster can support ambient mode without enrolling every namespace. Separating installation from enrollment keeps the platform boundary and application boundary independently reviewable and reversible.

Component readiness and customer traffic are different claims, so neither can replace the other. These stories require both platform evidence and application-owner evidence.

Enrollment must begin with the operator naming the target, not with Helm changing it. Istio’s Helm guide installs base resources, Gateway API resources, istiod, the CNI node agent, and the ztunnel DaemonSet as separate components (Istio Helm installation).

The risk is hidden ownership: Helm does not own the Forge namespace, and the Forge overlay does not own cluster-scoped Istio prerequisites. Ambient ztunnel is a per-node Layer 4 proxy, while a waypoint is an optional Layer 7 proxy (Istio ambient overview).

An installation record cannot authorize namespace enrollment, and a namespace label cannot prove the installed versions. Correlate the records, but keep their owners and rollback lifecycles separate.

Generated-application database: Not created in this slice — cluster and namespace desired state plus immutable enrollment evidence are sufficient; generated applications keep ownership of their tenant and domain records.

Downloading a mutable remote manifest or using an unpinned Helm chart can make two operators install different systems from the same instructions. The implementation fixes that problem with this exact mesh/istio-ambient/versions.env content.

ISTIO_VERSION=1.30.3
GATEWAY_API_VERSION=v1.5.1
GATEWAY_API_SHA256=64ec76609a6ac885e0405dea79ca509c229fa019d342f0857aa8b6bdc8b8ba92

Installing ambient-capable components does not automatically redirect Forge traffic. Istio documents namespace enrollment through istio.io/dataplane-mode=ambient; unlabeled namespaces remain out of the ambient data plane (enable ambient mode).

These are the exact enrollment and peer-authentication objects from mesh/ambient-enrollment/namespace-patch.yaml and peer-authentication.yaml:

apiVersion: v1
kind: Namespace
metadata:
  name: zheta-forge
  labels:
    istio.io/dataplane-mode: ambient
---
apiVersion: security.istio.io/v1
kind: PeerAuthentication
metadata:
  name: forge-strict-mtls
  namespace: zheta-forge
spec:
  mtls:
    mode: STRICT

Partial installation is not permission to enroll, and successful enrollment is not permission to continue after a customer regression. Diagnose from the lowest changed layer upward.

Before this day, Forge had a measured Kubernetes-only path but no mesh workload transport. Afterward, the same containers and ServiceAccounts are enrolled through one Git label, node ztunnels can carry their traffic, strict peer authentication is declared, and later waypoint/L4/L7 objects remain absent. This structural enrollment evidence does not claim live authorization or mutual-TLS telemetry.

Treating installation and enrollment as one command hides which owner must stop or recover a failure. Ambient enrollment is a controlled ownership handoff.

• Pin remote bytes and Helm charts; verify context and explicit approval before mutation.
• Installing ambient support and enrolling zheta-forge are separate decisions owned by different teams.
• The ambient label selects ztunnel transport; waypoint selection belongs to Day 33.
• STRICT declares required tunneled mutual TLS, while live authorization evidence belongs to the next stages.
• Keep the change only when components, source, enrollment state, absence checks, and workload identities agree.

Day 31 is complete only when the cluster and customer evidence come from the same reviewed window.

• [ ] MESH_CONTEXT equals the current reachable disposable context
• [ ] Gateway API v1.5.1 bundle matches the pinned SHA-256
• [ ] Four Istio 1.30.3 Helm releases and their rollouts are ready
• [ ] ambient-enrollment-local renders and applies without L4, waypoint, or L7 objects
• [ ] zheta-forge has only the ambient mesh label and forge-strict-mtls is STRICT
• [ ] Five application containers retain their same-named ServiceAccounts
• [ ] Enrollment verifier passes without claiming live authorization evidence