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

# Gateway API Configuration

> Kubernetes Gateway API configuration for CrewAI Platform routing (alternative to Ingress).

The Gateway API provides a modern, standardized way to expose services in Kubernetes. It's the successor to Ingress and is recommended for new deployments, especially on GKE where it's natively supported.

<Note>
  **Gateway API vs Ingress:** Gateway API offers more flexibility and features compared to traditional Ingress resources. It supports advanced routing, traffic splitting, and is designed for multi-tenancy. GKE has built-in Gateway API support with no additional controller installation needed.
</Note>

## Core Configuration

<ParamField path="gateway.enabled" type="boolean" default="false">
  Enable Gateway API for routing traffic to web and OAuth services.

  **When Enabled:**

  * Creates or references a Gateway resource
  * Configures HTTPRoutes for web and OAuth services (when their respective `gateway.enabled` is true)
  * Requires Gateway API CRDs installed in the cluster

  **Prerequisites:**

  * Cluster must have Gateway API CRDs installed
  * On GKE, enable with: `gcloud container clusters update CLUSTER --gateway-api=standard`

  **Example:**

  ```yaml theme={null}
  gateway:
    enabled: true
    create: true
    gatewayClassName: gke-l7-global-external-managed
  ```
</ParamField>

<ParamField path="gateway.create" type="boolean" default="true">
  Create a new Gateway resource or reference an existing one.

  **When true:**

  * Chart creates a new Gateway resource
  * Gateway name defaults to `<release-name>-gateway` or can be set via `gateway.name`
  * Gateway is created in the same namespace as the Helm release

  **When false:**

  * Chart references an existing Gateway by name
  * Must specify `gateway.name` and optionally `gateway.namespace`
  * Useful for shared Gateway across multiple applications

  **Example - Create New Gateway:**

  ```yaml theme={null}
  gateway:
    enabled: true
    create: true
    gatewayClassName: gke-l7-global-external-managed
  ```

  **Example - Reference Existing Gateway:**

  ```yaml theme={null}
  gateway:
    enabled: true
    create: false
    name: shared-gateway
    namespace: gateway-infra
  ```
</ParamField>

<ParamField path="gateway.name" type="string" default="">
  Name of the Gateway resource.

  **Default Behavior:**

  * When `create: true` and empty: Defaults to `<release-name>-gateway`
  * When `create: false`: Must be specified (name of existing Gateway)

  **Example:**

  ```yaml theme={null}
  gateway:
    enabled: true
    create: false
    name: shared-gateway
    namespace: istio-system
  ```
</ParamField>

<ParamField path="gateway.namespace" type="string" default="">
  Namespace of the Gateway resource (only used when `create: false`).

  **Purpose:** Allows HTTPRoutes to reference a Gateway in a different namespace.

  **Default Behavior:** If empty when `create: false`, assumes Gateway is in the same namespace as the Helm release.

  **Example:**

  ```yaml theme={null}
  gateway:
    enabled: true
    create: false
    name: shared-gateway
    namespace: gateway-infra
  ```
</ParamField>

<ParamField path="gateway.gatewayClassName" type="string" default="" required>
  Gateway controller class name.

  **Required:** Yes (when `gateway.enabled: true`)

  **GKE Built-in Classes:**

  * `gke-l7-global-external-managed` - Global external Application Load Balancer
  * `gke-l7-regional-external-managed` - Regional external Application Load Balancer
  * `gke-l7-rilb` - Regional internal Application Load Balancer

  **Other Controllers:**

  * `istio` - Istio Gateway
  * `nginx` - NGINX Gateway (if NGINX Gateway Fabric is installed)

  **Example:**

  ```yaml theme={null}
  gateway:
    enabled: true
    gatewayClassName: gke-l7-global-external-managed
  ```

  <Note>
    On GKE, verify available GatewayClasses with: `kubectl get gatewayclass`
  </Note>
</ParamField>

<ParamField path="gateway.annotations" type="object" default="{}">
  Annotations for the Gateway resource.

  **Use Cases:**

  * GCP certificate maps for managed certificates
  * Cloud-specific load balancer configuration
  * Custom metadata

  **Example - GCP Managed Certificate:**

  ```yaml theme={null}
  gateway:
    enabled: true
    gatewayClassName: gke-l7-global-external-managed
    annotations:
      networking.gke.io/certmap: crewai-cert-map
  ```

  **Example - Static IP:**

  ```yaml theme={null}
  gateway:
    annotations:
      networking.gke.io/static-ip: crewai-static-ip
  ```
</ParamField>

## Listeners Configuration

<ParamField path="gateway.listeners" type="array" required>
  List of Gateway listeners (ports and protocols).

  **Purpose:** Defines which ports the Gateway listens on and how traffic is handled.

  **Default Configuration:**

  ```yaml theme={null}
  listeners:
    - name: http
      protocol: HTTP
      port: 80
  ```

  **Each listener must specify:**

  * `name` - Unique listener name
  * `protocol` - HTTP, HTTPS, TCP, or TLS
  * `port` - Port number (80, 443, etc.)

  **Optional fields:**

  * `hostname` - Hostname filter for this listener
  * `tls` - TLS configuration (for HTTPS/TLS protocols)

  <Note>
    The chart automatically configures `allowedRoutes.namespaces.from: Same` to restrict HTTPRoutes to the same namespace.
  </Note>
</ParamField>

### HTTP Listener Example

```yaml theme={null}
gateway:
  enabled: true
  gatewayClassName: gke-l7-global-external-managed
  listeners:
    - name: http
      protocol: HTTP
      port: 80
```

### HTTPS Listener with Kubernetes TLS Secret

```yaml theme={null}
gateway:
  enabled: true
  gatewayClassName: gke-l7-global-external-managed
  listeners:
    - name: https
      protocol: HTTPS
      port: 443
      tls:
        mode: Terminate
        certificateRefs:
          - name: crewai-tls-secret
```

### HTTPS Listener with GCP Managed Certificate

```yaml theme={null}
gateway:
  enabled: true
  gatewayClassName: gke-l7-global-external-managed
  annotations:
    networking.gke.io/certmap: crewai-cert-map
  listeners:
    - name: https
      protocol: HTTPS
      port: 443
```

<Note>
  When using GCP-managed certificates via `networking.gke.io/certmap`, the listener doesn't need `tls.certificateRefs`. The certificate map is applied at the Gateway level via annotations.
</Note>

### HTTP and HTTPS Listeners (Dual-Stack)

```yaml theme={null}
gateway:
  enabled: true
  gatewayClassName: gke-l7-global-external-managed
  listeners:
    - name: http
      protocol: HTTP
      port: 80
    - name: https
      protocol: HTTPS
      port: 443
      tls:
        mode: Terminate
        certificateRefs:
          - name: crewai-tls-secret
```

## Complete Examples

### Basic HTTP Gateway (Development)

```yaml theme={null}
gateway:
  enabled: true
  create: true
  gatewayClassName: gke-l7-regional-external-managed
  listeners:
    - name: http
      protocol: HTTP
      port: 80

web:
  gateway:
    enabled: true
    hostnames:
      - crewai.dev.company.com
```

### Production HTTPS Gateway with Managed Certificate

```yaml theme={null}
gateway:
  enabled: true
  create: true
  gatewayClassName: gke-l7-global-external-managed
  annotations:
    networking.gke.io/certmap: crewai-cert-map
  listeners:
    - name: https
      protocol: HTTPS
      port: 443
    - name: http
      protocol: HTTP
      port: 80

web:
  gateway:
    enabled: true
    hostnames:
      - crewai.company.com

oauth:
  enabled: true
  gateway:
    enabled: true
    pathPrefix: /oauthsvc
```

### Shared Gateway Across Multiple Applications

**Install infrastructure Gateway once:**

```bash theme={null}
# Create shared gateway namespace
kubectl create namespace gateway-infra

# Install gateway
helm install shared-gateway ./gateway-chart \
  --namespace gateway-infra \
  --set gatewayClassName=gke-l7-global-external-managed
```

**Reference from CrewAI Platform:**

```yaml theme={null}
gateway:
  enabled: true
  create: false
  name: shared-gateway
  namespace: gateway-infra

web:
  gateway:
    enabled: true
    hostnames:
      - crewai.company.com
```

### OAuth with Dedicated Hostname

When using a dedicated hostname for OAuth (recommended for non-NGINX ingress controllers):

```yaml theme={null}
gateway:
  enabled: true
  create: true
  gatewayClassName: gke-l7-global-external-managed
  annotations:
    networking.gke.io/certmap: crewai-cert-map
  listeners:
    - name: https
      protocol: HTTPS
      port: 443

web:
  gateway:
    enabled: true
    hostnames:
      - crewai.company.com

oauth:
  enabled: true
  gateway:
    enabled: true
    hostname: oauth.company.com
    pathPrefix: /
```

<Warning>
  When using a dedicated OAuth hostname, ensure:

  1. The hostname is included in your TLS certificate or certificate map
  2. DNS points to the same Gateway IP address
  3. OAuth provider callback URLs are configured with the dedicated hostname
</Warning>

## Troubleshooting

### Gateway Not Found

**Error:** HTTPRoute shows `Gateway not found` in status

**Solution:** Verify Gateway exists and is in the correct namespace:

```bash theme={null}
kubectl get gateway -n <namespace>
```

If using `create: false`, ensure the referenced Gateway exists:

```bash theme={null}
kubectl get gateway <gateway-name> -n <gateway-namespace>
```

### No GatewayClass Available

**Error:** `no matches for kind "Gateway"` or `GatewayClass not found`

**Solution:** Enable Gateway API on your cluster:

**GKE:**

```bash theme={null}
gcloud container clusters update CLUSTER_NAME \
  --gateway-api=standard \
  --region REGION
```

**Other Kubernetes clusters:**

```bash theme={null}
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.0.0/standard-install.yaml
```

### HTTPRoute Not Attached to Gateway

**Error:** HTTPRoute shows `Accepted: False` in status

**Possible causes:**

1. Gateway namespace mismatch
2. Listener protocol mismatch
3. Hostname conflicts

**Debug:**

```bash theme={null}
kubectl describe httproute <release-name>-web -n <namespace>
```

Check the `Status.Parents` section for detailed error messages.

***

## Related Configuration

**Web HTTPRoute:** See [Web Configuration - Gateway API](/reference/chart-values/web#web-gateway) for web service routing configuration.

**OAuth HTTPRoute:** See [OAuth Configuration - Gateway API](/reference/chart-values/oauth#oauth-gateway) for OAuth service routing configuration.

**GCP Gateway API Guide:** See [GCP Integration Guide - External Access](/cloud-providers/gcp#option-1-gateway-api-recommended) for GCP-specific Gateway API setup including managed certificates and load balancer configuration.