Skip to content

Prepare a Mission Application for Istio Ambient Mode

This guide identifies the namespace, Kubernetes NetworkPolicy, and Istio AuthorizationPolicy requirements commonly needed before deploying a mission application into Big Bang’s ambient mesh. Apply only the policies the application needs and replace every placeholder with values for the target workload.

Before You Start

  • Enable ambient mode as described in Configuring Istio Ambient Mode in Big Bang.
  • Identify the application’s namespace, workload labels, service ports, metrics ports, ingress gateway, and required callers.
  • Determine the kubelet or node source CIDRs used for health probes on the target platform.
  • Prefer integrating the chart with bb-common when the chart can be modified.

Network Policy Requirements

Allowing HBONE Traffic

Once ambient mode is enabled, traffic is tunneled between workloads using TCP port 15008. As a result, this port is required for communication to continue as expected. Additionally, the original port should remain open to allow non-HBONE traffic to continue working.

Original:

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: allow-ingress-hbone-from-public-ingressgateway
  namespace: parabol
spec:
  ingress:
    - from:
        - namespaceSelector:
            matchLabels:
              kubernetes.io/metadata.name: istio-gateway
          podSelector:
            matchLabels:
              app.kubernetes.io/name: public-ingressgateway
              istio: ingressgateway
      ports:
        - port: 3000
          protocol: TCP
  podSelector:
    matchLabels:
      app.kubernetes.io/name: parabol
      app.kubernetes.io/component: webserver
  policyTypes:
    - Ingress

Updated:

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: allow-ingress-hbone-from-public-ingressgateway
  namespace: parabol
spec:
  ingress:
    - from:
        - namespaceSelector:
            matchLabels:
              kubernetes.io/metadata.name: istio-gateway
          podSelector:
            matchLabels:
              app.kubernetes.io/name: public-ingressgateway
              istio: ingressgateway
      ports:
        - port: 3000
          protocol: TCP
        - port: 15008
          protocol: TCP
  podSelector:
    matchLabels:
      app.kubernetes.io/name: parabol
      app.kubernetes.io/component: webserver
  policyTypes:
    - Ingress

[!NOTE] If the application does not communicate outside its namespace and runs in sidecar mode, this is not needed.

Allowing Kubelet Traffic

When a package is in ambient mode, it also requires an additional network policy to allow traffic from the kubelet so health and readiness probes continue functioning as expected.

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: ingress-allow-kubelet-healthprobes
spec:
  podSelector: {}
  ingress:
    - from:
        - ipBlock:
            cidr: 169.254.7.127/32

For more information about these network policies, please refer to Istio’s Ambient and Kubernetes Network Policy Documentation.

Authorization Policies

Ambient mode enables authorization policy generation for integrated packages regardless of the global authorizationPolicies.enabled value. A chart that is not integrated with bb-common must provide equivalent policies itself. When an Istio ALLOW policy applies to a workload, requests that do not match an applicable ALLOW rule are denied. Most applications therefore need a policy that permits their required same-namespace traffic.

apiVersion: security.istio.io/v1
kind: AuthorizationPolicy
metadata:
  name: default-authz-allow-all-in-ns
  namespace: <Update with Package Namespace>
spec:
  action: ALLOW
  rules:
    - from:
        - source:
            namespaces:
              - <Update with Package Namespace>

It is also recommended to have an allow-nothing authorization policy as shown below:

apiVersion: security.istio.io/v1
kind: AuthorizationPolicy
metadata:
  name: default-authz-allow-nothing
  namespace: <Update with Package Namespace>
spec: {}

Prometheus Ingress

Another common authorization policy allows Prometheus to scrape metrics endpoints via an application’s ServiceMonitor:

apiVersion: security.istio.io/v1
kind: AuthorizationPolicy
metadata:
  name: allow-ingress-to-metrics-from-ns-monitoring-with-identity-monitoring-monitoring-kube-prometheus
  namespace: <Update with Package Namespace>
spec:
  action: ALLOW
  rules:
    - from:
        - source:
            principals:
              - cluster.local/ns/monitoring/sa/monitoring-monitoring-kube-prometheus
      to:
        - operation:
            ports:
              - <Update with Appropriate Port>
  selector:
    matchLabels: <Update with Appropriate Pod Labels>

Istio Gateway Ingress

If the application allows traffic from an Istio ingress gateway, the following authorization policy may also be needed:

apiVersion: security.istio.io/v1
kind: AuthorizationPolicy
metadata:
  name: ingress-gateway-authz-policy
  namespace: <Update with Package Namespace>
spec:
  action: ALLOW
  rules:
    - from:
        - source:
            namespaces:
              - istio-gateway
            principals:
              - cluster.local/ns/istio-gateway/sa/public-ingressgateway-ingressgateway-service-account
  selector:
    matchLabels: <Update with Appropriate Pod Labels>

[!NOTE] You may need to update the principal accordingly if using a non-default gateway.

Namespace Labels

To label an application for ambient mode, use the following namespace label instead of the typical sidecar injection label:

istio.io/dataplane-mode: ambient

[!NOTE] This is handled automatically when using the packages key method.

Verify the Ambient Prerequisites

After the namespace and policies reconcile, verify them before deploying or testing the application:

MISSION_NAMESPACE="replace-me"
kubectl get namespace "$MISSION_NAMESPACE" --show-labels
kubectl get networkpolicy -n "$MISSION_NAMESPACE"
kubectl get authorizationpolicy -n "$MISSION_NAMESPACE"
istioctl ztunnel-config workloads | grep "$MISSION_NAMESPACE"

Confirm that:

  • The namespace has istio.io/dataplane-mode=ambient.
  • The expected workload appears in the ztunnel workload list after it is deployed.
  • Network policies allow both the application port and HBONE port 15008 where ambient traffic enters.
  • Health probes, ingress traffic, and metrics callers match explicit policy rules.

Do not copy the example kubelet CIDR without confirming it for the target cluster.