Skip to main content
Mapagam

Configuring Ingress Gateways

1. Creating Ingress Gateway Resources

Field Description Example Value
apiVersion API version of the Ingress Gateway resource networking.istio.io/v1beta1
kind Kind of the resource (must be IngressGateway) IngressGateway
metadata.name Name of the Ingress Gateway resource my-ingress-gateway
spec.ports List of ports to expose on the gateway [{ port: 80, name: "http", protocol: "HTTP" }]
spec.servers Configuration for the servers that handle traffic [{ hosts: ["example.com"], port: { number: 80, name: "http", protocol: "HTTP" } }]

Example: Basic Ingress Gateway Configuration

apiVersion: networking.istio.io/v1beta1
kind: Gateway
metadata:
  name: my-ingress-gateway
spec:
  selector:
    istio: ingressgateway
  servers:
  - port:
      number: 80
      name: http
      protocol: HTTP
    hosts:
    - example.com
Note: The selector field is used to bind the Gateway to a specific Istio ingress gateway deployment.

2. Setting Up Gateway Servers

Property Value Description
gateway.name ingress-gateway Name of the gateway server instance
gateway.type ingress Type of gateway (ingress, egress, or mesh)
gateway.port 80 Port to listen for incoming traffic
gateway.protocol http Protocol to use for traffic (http, https, tcp)

Example: Basic Ingress Gateway Configuration

apiVersion: networking.istio.io/v1beta1
kind: Gateway
metadata:
  name: ingress-gateway
spec:
  selector:
    istio: ingressgateway
  servers:
  - port:
      number: 80
      name: http
      protocol: HTTP
    hosts:
    - "*"

Example: HTTPS Ingress Gateway

apiVersion: networking.istio.io/v1beta1
kind: Gateway
metadata:
  name: https-gateway
spec:
  selector:
    istio: ingressgateway
  servers:
  - port:
      number: 443
      name: https
      protocol: HTTPS
    hosts:
    - "example.com"
    tls:
      mode: TERMINATE
      credentialName: example-com-tls

3. Configuring TLS Termination

Property Value Description
tls.mode TERMINATE Enables TLS termination at the gateway
tls.certificate /path/to/cert.pem Path to the TLS certificate file
tls.key /path/to/key.pem Path to the private key file
tls.caCertificate /path/to/ca.pem Path to the CA certificate for client verification (optional)

Example: TLS Termination Configuration

apiVersion: networking.istio.io/v1beta1
kind: Gateway
metadata:
  name: ingress-gateway
spec:
  selector:
    istio: ingressgateway
  servers:
  - port:
      number: 443
      name: https
      protocol: HTTPS
    tls:
      mode: TERMINATE
      serverCertificate: /etc/certs/cert.pem
      privateKey: /etc/certs/key.pem
      caCertificates: /etc/certs/ca.pem

4. Implementing TLS Passthrough

Configuration Description Notes
istio.io/tls-passthrough enabled Enables TLS passthrough for the gateway
istio.io/tls-mode PASSTHROUGH Indicates that TLS termination is not performed at the gateway

Example: Gateway Configuration with TLS Passthrough

apiVersion: networking.istio.io/v1beta1
kind: Gateway
metadata:
  name: ingress-gateway
spec:
  selector:
    istio: ingressgateway
  servers:
  - port:
      number: 443
      name: https
      protocol: HTTPS
    hosts:
    - example.com
    tls:
      mode: PASSTHROUGH
Note: TLS passthrough allows the client's TLS handshake to be handled by the application directly, bypassing Istio's proxy for encrypted traffic.
Warning: Ensure that the application is configured to handle TLS termination properly when using passthrough.

5. Configuring Mutual TLS

Property Description Default Notes
mtls.enabled Enables mutual TLS for ingress gateways false Set to true to enable mTLS
mtls.mode Specifies the mTLS mode (permissive, strict) permissive Strict mode requires client certificates
mtls.caBundle Path to CA certificate bundle for mTLS "" Required if mtls.enabled is true

Example: Enabling mTLS in Ingress Gateway

apiVersion: networking.istio.io/v1beta1
kind: Gateway
metadata:
  name: ingress-gateway
spec:
  selector:
    istio: ingressgateway
  servers:
  - port:
      number: 443
      name: https
      protocol: HTTPS
    tls:
      mode: MUTUAL
      serverCertificate: /etc/certs/tls.crt
      privateKey: /etc/certs/tls.key
      caCertificates: /etc/certs/root.crt
Note: When mtls.mode is set to STRICT, all traffic must present a valid client certificate.
Warning: Ensure that all clients have valid certificates before enabling strict mTLS.

6. Managing Gateway Selectors

Selector Type Description Usage Example Notes
labels Defines label-based selection for gateways { "app": "frontend", "version": "v1" } Used to match gateways based on pod or service labels
namespace Specifies the namespace where gateways are selected "istio-system" Ensures gateways are only selected from the specified namespace
name Matches gateways by their specific name "ingress-gateway" Allows for precise selection of a gateway instance

Example: Selecting Gateways by Labels

apiVersion: networking.istio.io/v1beta1
kind: Gateway
metadata:
  name: my-gateway
  namespace: istio-system
spec:
  selector:
    app: frontend
    version: v1
  servers:
  - port:
      number: 80
      name: http
      protocol: HTTP
    hosts:
    - "*"
Note: Gateway selectors are used to bind a Gateway resource to specific Istio workloads (e.g., pods or services) in the cluster.

7. Implementing Multi-Host Gateways

Property Description Example
hosts List of hostnames to match for this gateway ["api.example.com", "admin.example.com"]
tls Configuration for TLS settings (optional) { "mode": "SIMPLE", "credentialName": "tls-cert" }
port Port configuration for the gateway { "number": 443, "name": "https", "protocol": "HTTPS" }

Example: Multi-Host Gateway Configuration

apiVersion: networking.istio.io/v1beta1
kind: Gateway
metadata:
  name: multi-host-gateway
spec:
  selector:
    istio: ingressgateway
  servers:
  - port:
      number: 443
      name: https
      protocol: HTTPS
    hosts:
    - api.example.com
    - admin.example.com
    tls:
      mode: SIMPLE
      credentialName: multi-host-cert
Note: The hosts field in a Gateway resource allows you to define multiple hostnames that can be handled by the same gateway, enabling shared ingress for different services or domains.

Key Points

  • Multi-host gateways allow routing traffic to different services based on the hostname.
  • Each host can be associated with a specific TLS configuration if needed.
  • The selector field determines which ingress gateway instance to use.

8. Configuring Gateway Resources

Field Description Example
apiVersion API version for the Gateway resource gateway.networking.k8s.io/v1
kind Resource kind Gateway
metadata.name Name of the Gateway resource my-gateway
spec.listeners List of listeners for the gateway 
[
  {
    "name": "http",
    "port": 80,
    "protocol": "HTTP"
  }
]
spec.addresses Addresses to bind the gateway to 
[
  {
    "type": "IPAddress",
    "value": "192.168.1.100"
  }
]

Example: Basic Gateway Configuration

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: my-gateway
spec:
  listeners:
  - name: http
    port: 80
    protocol: HTTP

Example: Gateway with TLS

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: secure-gateway
spec:
  listeners:
  - name: https
    port: 443
    protocol: HTTPS
    tls:
      mode: Terminate
      certificateRef:
        name: my-tls-cert
Note: Gateway resources are part of the gateway.networking.k8s.io API group and require a GatewayClass to be operational.

9. Setting Up Custom Gateway Deployments

Custom gateway deployments allow you to define and manage ingress gateways with specific configurations tailored to your service mesh needs.

Configuration Description Example
gateway.name Name of the custom gateway deployment custom-ingress-gateway
gateway.namespace Kubernetes namespace where the gateway is deployed istio-system
gateway.type Type of gateway (e.g., ingress, egress) ingress
gateway.labels Labels to apply to the gateway deployment { "app": "custom-gateway" }

Example: Custom Gateway Deployment Manifest

apiVersion: v1
kind: Service
metadata:
  name: custom-ingress-gateway
  namespace: istio-system
spec:
  selector:
    app: custom-gateway
  ports:
    - port: 80
      targetPort: 8080
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: custom-ingress-gateway
  namespace: istio-system
spec:
  replicas: 1
  selector:
    matchLabels:
      app: custom-gateway
  template:
    metadata:
      labels:
        app: custom-gateway
    spec:
      containers:
        - name: istio-proxy
          image: istio/proxyv2:latest
          ports:
            - containerPort: 8080
Note: Ensure that the custom gateway deployment is properly configured with appropriate labels and selector to integrate with the Istio control plane.
Warning: Misconfiguring the gateway deployment can lead to traffic not being routed correctly through the service mesh.

10. Troubleshooting Ingress Gateway Issues

Issue Possible Cause Solution
503 Service Unavailable Gateway not routing traffic to backend services Check service endpoints and ensure they are healthy. Validate the gateway configuration for correct route definitions.
404 Not Found Incorrect route or path configuration in gateway Review the Ingress Gateway's route rules and ensure paths match the requested URLs.
Timeout Errors Backend service is unresponsive or slow Monitor backend service health and adjust timeout configurations in the gateway.
Certificate Errors Invalid or expired TLS certificates on the gateway Verify and update TLS certificate configurations in the Ingress Gateway.
Authentication Failures Incorrect or missing authentication in gateway rules Ensure that the gateway is configured to handle authentication properly (e.g., JWT, OAuth).

Example: Debugging 503 Errors

# Check service status
kubectl get pods -n istio-system

# Validate gateway configuration
kubectl get ingressgateway -n istio-system -o yaml

# Inspect logs for errors
kubectl logs -n istio-system <gateway-pod-name>
Note: Use kubectl describe to get detailed information about the Ingress Gateway's status and events.
Warning: Ensure that the backend services are accessible from the Ingress Gateway's network namespace.

11. Configuring Gateway High Availability

Example: Basic HA Gateway Configuration

apiVersion: networking.istio.io/v1beta1
kind: Gateway
metadata:
  name: ingress-gateway-ha
spec:
  selector:
    istio: ingressgateway
  servers:
  - port:
      number: 80
      name: http
      protocol: HTTP
    hosts:
    - &#34;example.com&#34;
Field Description Values Notes
selector Labels to select gateway pods istio: ingressgateway Must match deployment labels
servers.port.number Port to listen on 80, 443 Standard HTTP/HTTPS ports
servers.hosts Hostnames to route to this gateway "example.com" Must match DNS or routing rules
Note: Ensure that the gateway pods are scheduled across multiple nodes for true HA. This can be achieved using nodeSelector or affinity rules in the gateway deployment.
Warning: Without proper pod anti-affinity or node spreading, HA gateways may still result in single points of failure during node outages.

12. Managing Gateway TLS Certificates

Property Description Values Notes
tls.certificate Path to the TLS certificate file /etc/certs/tls.crt Must be in PEM format
tls.key Path to the TLS private key file /etc/certs/tls.key Must be in PEM format
tls.caCertificate Path to the CA certificate file for client verification /etc/certs/ca.crt Optional, used for mutual TLS (mTLS)
tls.mode Specifies the TLS mode for the gateway PASSTHROUGH, TERMINATE PASSTHROUGH forwards TLS traffic without termination
tls.minVersion Minimum TLS version allowed TLSv1.2, TLSv1.3 Defaults to TLSv1.2
tls.maxVersion Maximum TLS version allowed TLSv1.2, TLSv1.3 Defaults to TLSv1.3

Example: Gateway with TLS Termination

apiVersion: networking.istio.io/v1beta1
kind: Gateway
metadata:
  name: ingress-gateway
spec:
  selector:
    app: ingress-gateway
  servers:
  - port:
      number: 443
      name: https
      protocol: HTTPS
    tls:
      mode: TERMINATE
      serverCertificate: /etc/certs/tls.crt
      privateKey: /etc/certs/tls.key
      caCertificates: /etc/certs/ca.crt

Example: Gateway with TLS Passthrough

apiVersion: networking.istio.io/v1beta1
kind: Gateway
metadata:
  name: passthrough-gateway
spec:
  selector:
    app: ingress-gateway
  servers:
  - port:
      number: 443
      name: https
      protocol: HTTPS
    tls:
      mode: PASSTHROUGH
Note: When using TERMINATE, ensure that the certificate and key files are accessible to the gateway pod.
Warning: Mutual TLS (mTLS) requires both server and client certificates to be configured correctly.

Was this article helpful?

Related Cheat Sheets