Install and Enroll Istio Ambient Safely

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 HelixWorks 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 HelixWorks 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.

The customer outcome is a reviewable install and enroll istio ambient safely change, not a collection of requirements. This day starts with the implementation boundary, then uses the command or manifest below to produce positive, denied, and recovery evidence.

Istio CNI, ztunnel DaemonSet, waypoint proxy, control plane, and HelixWorks workloads; node and pod compute; Kubernetes etcd and telemetry stores; cache: not involved.

This map names the implementation boundary for this day. The service or controller changes only the state it owns; runtime and audit evidence let the operator distinguish a declared change from an effective one.

Pin and install the cluster boundary

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

The official Istio Helm guide currently shows Gateway API v1.5.1 experimental resources and separate ambient components, matching the repository’s pinned sequence (Istio Helm installation). The repository is authoritative for this lab’s exact pins; “latest” is not an accepted input.

export MESH_CONTEXT="${MESH_CONTEXT:?set the exact disposable cluster context}"
export MESH_INSTALL_APPROVED=1
./scripts/install-istio-ambient.sh
./scripts/verify-istio-ambient.sh control-plane

The script refuses to continue unless the shell’s current context equals MESH_CONTEXT, the API answers, the explicit approval equals one, and the downloaded SHA-256 matches. Only then do the API server and Helm controllers change software state. A successful exit proves named component presence and rollout; it does not yet prove HelixWorks traffic or enrollment.

Installing ambient-capable components does not automatically redirect HelixWorks 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: helixworks-forge
  labels:
    istio.io/dataplane-mode: ambient
---
apiVersion: security.istio.io/v1
kind: PeerAuthentication
metadata:
  name: forge-strict-mtls
  namespace: helixworks-forge
spec:
  mtls:
    mode: STRICT

In ambient mode, STRICT is useful for ensuring that connections cannot bypass the mesh; DISABLE is not supported (Istio PeerAuthentication). This object proves declared policy, not observed encryption. Packet or ztunnel telemetry proof belongs to a later evidence gate.

kubectl kustomize gitops/apps/forge/overlays/ambient-enrollment-local >/tmp/forge-ambient-enrollment-local.yaml
./scripts/verify-ambient-source.sh
kubectl --context "${MESH_CONTEXT:?set the exact disposable cluster context}" apply -k gitops/apps/forge/overlays/ambient-enrollment-local
MESH_CONTEXT="$MESH_CONTEXT" ./scripts/verify-istio-ambient.sh enrollment
kubectl --context "$MESH_CONTEXT" -n helixworks-forge get pod -o custom-columns='NAME:.metadata.name,CONTAINERS:.spec.containers[*].name,SERVICE_ACCOUNT:.spec.serviceAccountName'

The source verifier renders all three stages and checks their ordering before mutation. This explicit apply reconciles only enrollment. The scoped live verifier checks ambient label, strict mode, HBONE/health NetworkPolicies, and cluster components; it deliberately does not claim a live L4 denial, waypoint, or HTTP policy. Day 30 remains the last sealed customer-traffic baseline until Day 32 adds and probes L4 authorization.

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, HelixWorks 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 helixworks-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
• [ ] helixworks-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