Bring Your Own Istio¶

Overview¶

By default, Customer-Managed Prefect requires the prefect-istiod Helm chart to be installed first — it deploys the Istio CRDs, cluster resources, and istiod control plane used by the prefect-cloud chart.

If your cluster already runs Istio (for example, your platform team manages a shared istio controlplane), you can skip the prefect-istiod chart entirely. The prefect-cloud chart uses only standard Istio APIs and works with any conformant Istio 1.x installation.

What the prefect-istiod chart provides¶

The prefect-istiod chart is a thin wrapper around three upstream Istio charts:

Component	What it installs
`istioBase`	Istio CRDs and cluster-scoped RBAC
`istioDiscovery`	The `istiod` control plane deployment
`istioCNI`	Optional CNI plugin which is required for OpenShift deployments (disabled by default)

If all three (or the required two) of these are already present in your cluster, you do not need prefect-istiod.

Differences when using your own Istio¶

The prefect-cloud chart itself does not install istiod. It only creates:

A prefect-istio-gateway ingress gateway deployment (a standalone Envoy pod, controlled by istio.gateway.enabled)
An Istio Gateway CRD resource (also controlled by istio.gateway.enabled)
VirtualService, DestinationRule, and AuthorizationPolicy resources for routing and auth

These resources are independent of which istiod instance manages them. Your existing Istio control plane will pick them up automatically once the namespace has sidecar injection enabled.

Deploying with your own Istio¶

Step 1 — Label your namespace¶

Customer-Managed pods require Istio sidecar injection. How you label the namespace depends on whether your Istio uses the default injection label or a named revision.

Default injection labelRevision-based Istio

kubectl create namespace customer-managed
kubectl label namespace customer-managed istio-injection=enabled

If your cluster uses revision-based Istio (common with istioctl or operator-managed installs), use the revision label instead. Do not set both labels at the same time — they conflict.

kubectl create namespace customer-managed
kubectl label namespace customer-managed istio.io/rev=<your-revision>

Replace <your-revision> with the revision tag used by your istiod (for example, 1.25 or stable). You can find active revisions with:

kubectl get mutatingwebhookconfigurations -l app=sidecar-injector

Step 2 — Skip the prefect-istiod chart¶

Do not install prefect-istiod. Proceed directly to installing the prefect-cloud chart as described in Deploy Customer-Managed.

Note

The Istio Gateway and VirtualService CRDs must already exist in your cluster before the prefect-cloud chart is installed. These are provided by the istioBase component (or equivalent) in your existing Istio installation. The chart will fail to render if the CRDs are absent.

Step 3 — Install the prefect-cloud chart¶

helm install customer-managed prefect-cloud-<version>.tgz \
  -n customer-managed \
  -f values-override.yaml

No additional values are required — the default chart behavior works with any compliant Istio installation.

Attaching to an existing edge gateway¶

If your cluster already has an Istio Gateway that handles external traffic (for example, a shared ingress gateway managed by your platform team), you can route traffic from that gateway to Customer-Managed rather than exposing the prefect-istio-gateway service directly.

Enable serviceMesh.routing.edgeVirtualService to create a VirtualService that routes from your existing gateway to the prefect-istio-gateway:

serviceMesh:
  routing:
    edgeVirtualService:
      enabled: true
      # The hosts and gateways of your existing edge Gateway resource
      hosts:
        - "prefect.company.com"
      gateways:
        - "istio-system/shared-gateway"
      # Optional: path prefixes if Customer-Managed is not at the root
      pathPrefix:
        frontend: ""  # e.g. "prefect" to serve the UI at /prefect/
        backend: ""   # e.g. "api" to serve the API at /api/

With this configuration, the prefect-istio-gateway service does not need to be exposed outside the cluster — your edge gateway handles external traffic and delegates to it.

Disabling the prefect-istio-gateway deployment¶

If you want to front Customer-Managed entirely with your own gateway deployment and associated Gateway custom resource (rather than the bundled prefect-istio-gateway pod and custom resource), you can disable the gateway chart:

istio:
  gateway:
    enabled: false

Warning

When istio.gateway.enabled: false, the chart does not create a Gateway CRD resource or an ingress gateway deployment. You must configure your own Istio Gateway resource to match traffic to the prefect-istio-gateway name, or adjust the VirtualService host references accordingly. This is an advanced configuration — confirm with your platform team before disabling the bundled gateway.

Upgrading Customer-Managed when using your own Istio¶

When a new prefect-cloud chart version is released:

Check the upgrade guide for any Istio-related changes (for example, updated VirtualService or AuthorizationPolicy templates)
Upgrade only the prefect-cloud chart — skip any step that references prefect-istiod

helm upgrade customer-managed prefect-cloud-<new_version>.tgz \
  -n customer-managed \
  -f values-override.yaml

If the upgrade guide notes a required Istio version bump, ensure your cluster's Istio version is compatible before upgrading.