> ## Documentation Index
> Fetch the complete documentation index at: https://astronomer.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Route Astro Private Cloud traffic through an Istio Gateway

> Provide access to Astro services through an existing Istio Gateway instead of the built-in NGINX ingress controller.

By default, Astro Private Cloud (APC) provides access to Astro services through the built-in NGINX ingress controller. You can instead attach the platform to an [Istio Gateway](https://istio.io/latest/docs/reference/config/networking/gateway/) that you already run. APC then suppresses every platform Ingress and renders a `VirtualService` in place of each one.

> [!NOTE]
>
> **Astro Private Cloud 2.2**
>
> This feature was introduced in Astro Private Cloud 2.2. To access this feature, upgrade your Astro Private Cloud installation to 2.2 or later.

The Astronomer Helm chart neither installs Istio nor creates the Gateway. You install and manage both yourself, and APC attaches its `VirtualService` resources to the Gateway you name.

## Prerequisites

* Istio installed on both your control plane cluster and your data plane cluster. See the [Istio installation documentation](https://istio.io/latest/docs/setup/install/istioctl/).
* Access to the `values.yaml` file on both your control plane cluster and your data plane cluster.
* Permission to apply platform Helm configuration changes. See [Apply a config change](https://astronomer.io/docs/astro-private-cloud/v-2-x/apply-platform-config.md).

## Route traffic through a Gateway

**1. Create or identify your Gateway**

APC attaches its `VirtualService` resources to a `Gateway` resource that you manage. To list the existing Gateways, run:

```bash theme={null}
kubectl get gateways --all-namespaces
```

You need the Gateway's namespace and name in the form `<namespace>/<name>`, such as `istio-system/default-gateway`. If no suitable Gateway exists, create one that serves your APC base domain on port 443 with your TLS certificate. See the [Istio Gateway reference](https://istio.io/latest/docs/reference/config/networking/gateway/) for the resource specification.

**2. Update your platform values**

Add the following configuration to the `values.yaml` file on both your control plane cluster and your data plane cluster:

```yaml theme={null}
global:
  istio:
    gateway:
      enabled: true
      name: "istio-system/default-gateway"
  authSidecar:
    enabled: true
    tlsSecret: astronomer-tls
  nginx:
    enabled: false
```

Setting `global.nginx.enabled: false` disables the NGINX subchart because the Gateway handles inbound traffic instead.

**3. Apply the configuration change**

Apply your updated `values.yaml` file to each cluster. See [Apply a config change](https://astronomer.io/docs/astro-private-cloud/v-2-x/apply-platform-config.md) for the full procedure, including how to retrieve your current configuration first.

**4. Verify that APC created the VirtualService resources**

On each cluster, run:

```bash theme={null}
kubectl get virtualservices -n <your-platform-namespace>
```

Confirm that the platform hosts appear and that each `VirtualService` references the Gateway you configured. Then confirm that you can reach the APC UI at your base domain.

## Name an existing Gateway

`global.istio.gateway.name` takes the `<namespace>/<name>` of a Gateway that you created. It has no default. You set it in [Update your platform values](#route-traffic-through-a-gateway).

> [!WARNING]
>
> The Gateway you name must already exist. The Kubernetes API server accepts a `VirtualService` that points at a missing Gateway, and that `VirtualService` silently routes no traffic. You get no error, and the platform hosts don't resolve. Rendering fails if `global.istio.gateway.enabled` is `true` and `name` is empty.

## Enable the auth sidecar

The auth sidecar is required when you route traffic through a Gateway. The Gateway handles traffic outside the platform, so the auth sidecar is the only component that authenticates the platform hosts. Set `global.authSidecar.enabled: true` as shown earlier. For the other sidecar options, see [Auth sidecar (OpenShift)](https://astronomer.io/docs/astro-private-cloud/v-2-x/helm-config-reference.md#auth-sidecar-openshift).

> [!WARNING]
>
> Rendering fails if `global.istio.gateway.enabled` is `true` and `global.authSidecar.enabled` is `false`. The chart fails the render deliberately to avoid publishing the platform hosts without authentication.

> [!NOTE]
>
> The [APC MCP server](https://astronomer.io/docs/astro-private-cloud/v-2-x/apc-mcp-server.md) isn't supported with an Istio Gateway in this release, because the server's authentication gate exists only on the built-in NGINX ingress controller. On a control plane or unified plane, rendering fails if `astronomer.mcpServer.enabled` and `global.authSidecar.enabled` are both `true`. See [Stated limitations](https://astronomer.io/docs/astro-private-cloud/v-2-x/apc-mcp-server-security.md#stated-limitations).

## Configuration reference

| Value | Type | Description | Default |
| - | - | - | - |
| `global.istio.gateway.enabled` | bool | Routes platform traffic through an Istio Gateway instead of the NGINX ingress controller. Suppresses every platform Ingress and renders a `VirtualService` for each one. Requires `global.authSidecar.enabled: true`. | `false` |
| `global.istio.gateway.name` | string | The `<namespace>/<name>` of an existing Istio Gateway that the platform `VirtualService` resources attach to. Required when `global.istio.gateway.enabled` is `true`. | None |
| `global.authSidecar.enabled` | bool | Enables the auth sidecar, which authenticates the platform hosts. | `false` |
| `global.nginx.enabled` | bool | Enables the NGINX subchart. Set to `false` when an Istio Gateway handles inbound traffic. | `true` |

## Related documentation

* [Apply an Astro Private Cloud platform Helm configuration change](https://astronomer.io/docs/astro-private-cloud/v-2-x/apply-platform-config.md)
* [Network configuration](https://astronomer.io/docs/astro-private-cloud/v-2-x/network-configuration.md)
* [Use a third-party ingress controller](https://astronomer.io/docs/astro-private-cloud/v-2-x/third-party-ingress-controllers.md)
* [Helm configuration reference](https://astronomer.io/docs/astro-private-cloud/v-2-x/helm-config-reference.md)