Istio Resources

BB-Common provides base Istio resources to secure and configure service mesh behavior for your applications.

Overview

When Istio is enabled, BB-Common creates foundational security and networking resources:

• PeerAuthentication: Enforces mutual TLS between services
• Sidecar: Controls outbound traffic policy (when enabled)
• Waypoint Gateway: Creates optional ambient waypoint proxies for L7 policy, routing, and telemetry
• AuthorizationPolicies: Implements service-to-service authorization (see Authorization Policies)
• Custom Resources: Allows end users to define application-specific ServiceEntries and AuthorizationPolicies for last-mile configuration

Configuration

Basic Configuration

istio:
  enabled: true

Resource Naming

By default, Istio resources are named without the Helm release name prefix. When deploying multiple releases to the same namespace, enable prependReleaseName to avoid naming conflicts:

istio:
  enabled: true
  prependReleaseName: true  # e.g. "my-release-default-peer-auth" instead of "default-peer-auth"

Resources Created

NetworkPolicy

Creates a network policy that allows kubelet to contact readiness probes when operting in ambient mode. Please refer to this link for additional information/justification.

Resource Name: default-ingress-allow-ambient-kubelet

Ambient mode also derives related bb-common behavior:

• Istio Sidecar resources are not rendered.
• default-ingress-allow-prometheus-to-istio-sidecar is not rendered.
• default-egress-allow-istiod is not rendered.
• AuthorizationPolicies are enabled and generated from NetworkPolicy configuration.

HBONE port injection is not derived from ambient mode. Big Bang should set networkPolicies.hbonePortInjection.enabled=true explicitly for packages that need to receive or send HBONE traffic.

If istio.ambient.enabled=true and istio.sidecar.enabled=true are both set, bb-common emits a render warning and does not create the Sidecar resource.

Configuration:

istio:
  enabled: true
  ambient:
    enabled: true
networkPolicies:
  enabled: true

PeerAuthentication

Enforces mutual TLS (mTLS) for service-to-service communication within the namespace.

Resource Name: default-peer-auth

Default Mode: STRICT

Configuration:

istio:
  enabled: true
  mtls:
    mode: STRICT  # Options: STRICT, PERMISSIVE, DISABLE

Sidecar

When enabled, creates a Sidecar resource that restricts outbound traffic to only services registered in the Istio service registry.

Note: The Sidecar resource is separate from the Sidecar dataplane mode and is not applicable when using Ambient mode. Setting istio.sidecar.enabled=true with istio.ambient.enabled=true emits a render warning and does not create the Sidecar resource.

Resource Name: {{ .Release.Name }}-sidecar

Default Outbound Policy: REGISTRY_ONLY

Configuration:

istio:
  enabled: true
  sidecar:
    enabled: true
    outboundTrafficPolicyMode: REGISTRY_ONLY  # Options: REGISTRY_ONLY, ALLOW_ANY

The REGISTRY_ONLY mode prevents sidecars from accessing external services that are not explicitly defined in the mesh, providing defense-in-depth security.

Waypoint Gateway

In ambient mode, ext_authz is enforced at an L7 waypoint. There is no standalone waypoint configuration key: bb-common auto-creates a single shared waypoint Gateway for the namespace whenever an inbound route enables authservice. The Gateway uses the istio-waypoint GatewayClass, is named waypoint (release-name-prefixed when istio.prependReleaseName=true), and is labeled istio.io/waypoint-for: service. Istio manages the backing waypoint proxy from this resource.

Note: bb-common creates the waypoint Gateway only. Enrolling a namespace, service, or workload onto it with labels such as istio.io/use-waypoint (and istio.io/ingress-use-waypoint for north-south traffic) is a separate action owned by the consuming package or umbrella configuration — see Enrolling your Service onto the waypoint for the labels and why Service-level enrollment is preferred. The cluster must already have Gateway API CRDs installed and the istio-waypoint GatewayClass available.

See Protecting a Route with Authservice for how the waypoint is triggered and the accompanying resources.

Authservice

Authservice (OIDC ext_authz) protection is configured per inbound route via routes.inbound.<name>.authservice — see Protecting a Route with Authservice in the routes docs for the full configuration and generated resources. There is no standalone istio.authservice block; the binding is always derived from the route.

When enabled on a route, bb-common generates a RequestAuthentication (OIDC JWT validation), a CUSTOM AuthorizationPolicy that delegates to a registered ext_authz provider, and a DENY AuthorizationPolicy (<route>-authservice-jwt-deny) as the JWT enforcement backstop. In ambient mode, enabling authservice also auto-creates the shared Waypoint Gateway that serves as the L7 enforcement point — there is nothing else to turn on.

Prerequisite: an extensionProviders entry named authservice must exist in the Istio mesh config (istiod values) — the provider name, like the authservice Service address (authservice/authservice:10003), is the fixed Big Bang authservice contract and is not configurable. That wiring lives outside bb-common.

Binding scope (derived from the route):

• Sidecar mode: bound via spec.selector.matchLabels from the route’s selector.
• Ambient mode (service-scoped): bound via spec.targetRefs to the route’s Service (kind: Service). The shared waypoint can front many services while only that Service is subject to authservice — other apps routed through the same waypoint are untouched.

Ambient ingress prerequisite: a waypoint only mediates east-west traffic by default. To enforce authservice on north-south (ingress gateway) traffic, the protected namespace/Service must also carry istio.io/ingress-use-waypoint: "true" so ingress is routed through the waypoint. bb-common makes a route’s resources waypoint-aware automatically when that route enables authservice: the route AuthorizationPolicy targets the Service (enforced at the waypoint with the deny-all), a NetworkPolicy admitting the gateway to the waypoint on HBONE (15008) is generated, and the waypoint→authservice ext_authz egress NetworkPolicy is auto-generated (targeting the conventional authservice/authservice:10003). Routes in the same namespace that do not enable authservice are untouched: their AuthorizationPolicy keeps the workload selector binding (enforced by ztunnel), matching their non-enrolled Services. See tests/test-values-authservice.yaml.

Custom Resources

BB-Common allows you to define custom Istio resources for last-mile configuration. These are typically used by end users to add application-specific Istio resources that complement the base resources generated by BB-Common.

Custom ServiceEntries

ServiceEntries allow you to add external services to the Istio service registry, making them accessible from within the mesh. This is commonly used to:

• Define external databases, APIs, or third-party services
• Enable egress traffic to specific external hosts when using REGISTRY_ONLY mode
• Configure DNS resolution and TLS settings for external services

Configuration:

istio:
  enabled: true
  sidecar:
    enabled: true
  serviceEntries:
    custom:
      - name: external-database
        labels:
          app: myapp
          environment: production
        annotations:
          description: "External PostgreSQL database"
        spec:
          hosts:
            - postgres.example.com
          ports:
            - number: 5432
              name: tcp-postgres
              protocol: TCP
          location: MESH_EXTERNAL
          resolution: DNS

      - name: external-api
        spec:
          hosts:
            - api.partner.com
          ports:
            - number: 443
              name: https
              protocol: HTTPS
          location: MESH_EXTERNAL
          resolution: DNS

Custom AuthorizationPolicies

Custom AuthorizationPolicies allow you to define fine-grained access control rules beyond what’s automatically generated from NetworkPolicies. Common use cases include:

• Deny rules for specific operations or paths
• Complex authorization logic based on JWT claims or request attributes
• Layer 7 (HTTP/gRPC) authorization rules
• Allow/deny rules for specific workloads

Configuration:

istio:
  enabled: true
  authorizationPolicies:
    enabled: true
    custom:
      - name: deny-admin-paths
        labels:
          security-level: high
        annotations:
          owner: security-team
        spec:
          selector:
            matchLabels:
              app: web-frontend
          action: DENY
          rules:
            - to:
                - operation:
                    paths:
                      - "/admin/*"
                      - "/internal/*"

      - name: allow-metrics-scraping
        spec:
          selector:
            matchLabels:
              app: myapp
          action: ALLOW
          rules:
            - from:
                - source:
                    namespaces:
                      - monitoring
              to:
                - operation:
                    paths:
                      - "/metrics"
                    methods:
                      - "GET"

Configuration Options

Both custom resource types support:

Field	Type	Required	Description
name	string	Yes	Name of the resource
labels	object	No	Additional labels for the resource
annotations	object	No	Annotations for the resource
spec	object	Yes	Full Istio resource spec (see Istio documentation)

Notes: - All resources in the list are always created (no enable/disable toggle) - Custom resources are rendered alongside BB-Common’s base Istio resources - Resources are deployed to the same namespace as the Helm release - The spec field accepts the full Istio resource specification

Last-Mile Configuration Pattern

Custom resources are designed for last-mile configuration - allowing end users to add application-specific policies without modifying the base chart. This pattern enables:

1. Chart maintainers to provide secure defaults via BB-Common’s base resources
2. End users to extend with application-specific requirements via custom resources
3. Clean separation between platform-level and application-level policies

Example: A platform team uses BB-Common to enforce mTLS and default-deny policies, while application teams add custom ServiceEntries for their specific external dependencies and custom AuthorizationPolicies for their HTTP path-based access control.

Related Documentation

BB-Common Documentation

• Authorization Policies - Service-to-service authorization

Istio Documentation

• Istio PeerAuthentication
• Istio Sidecar
• Istio ServiceEntry
• Istio AuthorizationPolicy