gateway api deployment guide

Gateway API Deployment Guide for ReportPortal

This guide provides comprehensive instructions for deploying ReportPortal using the Kubernetes Gateway API, the modern replacement for Ingress.

Table of Contents

• Overview
• Why Gateway API?
• Prerequisites
• Gateway API Concepts
• Deployment Steps
• TLS Configuration
  • Using Your Own Certificate
  • Using Let's Encrypt with Cert-Manager
• Configuration Examples
• Gateway Controller: Envoy Gateway
• Troubleshooting
• Migration from Ingress

Overview

Gateway API is the next-generation Kubernetes API for managing external access to services. It provides more expressive, extensible, and role-oriented interfaces compared to the legacy Ingress API.

The latest version (v1.4.1) includes GA support for:

• v1.GatewayClass
• v1.Gateway
• v1.HTTPRoute
• v1.GRPCRoute
• v1.BackendTLSPolicy

Why Gateway API?

Feature	Ingress	Gateway API
Role separation	Limited	Gateway/Route split
Protocol support	HTTP/HTTPS	HTTP, HTTPS, TCP, UDP, gRPC
Header-based routing	Controller-specific	Native support
Traffic splitting	Limited	Native support
Cross-namespace	Limited	ReferenceGrant
Extensibility	Annotations	Policy attachments

Prerequisites

1. Kubernetes Cluster

• Kubernetes 1.26+ (Gateway API v1.4.1)
• kubectl configured with cluster access

2. Gateway API CRDs

Install the Gateway API Custom Resource Definitions:

kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.4.1/standard-install.yaml

Verify installation:

kubectl get crd | grep gateway.networking.k8s.io

Expected output:

gatewayclasses.gateway.networking.k8s.io
gateways.gateway.networking.k8s.io
grpcroutes.gateway.networking.k8s.io
httproutes.gateway.networking.k8s.io
referencegrants.gateway.networking.k8s.io

3. Gateway Controller

You need a Gateway controller implementation. See Gateway Controller: Envoy Gateway for installation instructions.

Gateway API Concepts

Key Resources

1. GatewayClass: Defines the controller implementation (similar to IngressClass)
2. Gateway: Represents a load balancer with listeners
3. HTTPRoute: Defines routing rules to backend services

ReportPortal Gateway API Architecture

┌─────────────────────────────────────────────────────────────┐
│                         Gateway                              │
│  (LoadBalancer with HTTP/HTTPS listeners)                   │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                        HTTPRoute                             │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐           │
│  │   /     │ │  /ui    │ │  /uat   │ │  /api   │           │
│  └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘           │
└───────┼──────────┼──────────┼──────────┼────────────────────┘
        ▼          ▼          ▼          ▼
   ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
   │ Index  │ │   UI   │ │  UAT   │ │  API   │
   │Service │ │Service │ │Service │ │Service │
   └────────┘ └────────┘ └────────┘ └────────┘

Deployment Steps

Step 1: Create Values File

Create a values-gateway-api.yaml file:

# Disable legacy Ingress
ingress:
  enable: false

# Enable Gateway API
gatewayAPI:
  enable: true
  hostnames: reportportal.example.com
  
  # Reference an existing Gateway
  gatewayRef:
    name: my-gateway
    namespace: gateway-system  # optional
  
  # Or create a new Gateway
  gateway:
    create: true
    className: envoy-gateway

Step 2: Deploy ReportPortal

# Add the Helm repository
helm repo add reportportal https://reportportal.github.io/kubernetes
helm repo update

# Deploy ReportPortal with Gateway API
helm install reportportal reportportal/reportportal \
  --namespace reportportal \
  --create-namespace \
  --values values-gateway-api.yaml \
  --set uat.superadminInitPasswd.password="YourSecurePassword"

Step 3: Verify Deployment

# Check Gateway status
kubectl get gateway -n reportportal

# Check HTTPRoute status
kubectl get httproute -n reportportal

# Check if routes are attached
kubectl describe httproute -n reportportal

TLS Configuration

Using Your Own Certificate

Option 1: Create TLS Secret and Reference in Gateway

1. Create a TLS secret from your certificate files:

kubectl create secret tls reportportal-tls \
  --cert=path/to/tls.crt \
  --key=path/to/tls.key \
  -n reportportal

2. Configure Gateway with TLS:

ingress:
  enable: false

gatewayAPI:
  enable: true
  hostnames: reportportal.example.com
  gateway:
    create: true
    className: envoy-gateway
    tls:
      enable: true
      secretName: reportportal-tls

Option 2: Use Custom Certificate References

For advanced scenarios with multiple certificates:

gatewayAPI:
  enable: true
  hostnames:
    - reportportal.example.com
    - rp.example.com
  gateway:
    create: true
    className: envoy-gateway
    tls:
      enable: true
      certificateRefs:
        - kind: Secret
          name: reportportal-tls
          namespace: reportportal

Option 3: Custom Gateway Listeners

For full control over Gateway configuration:

gatewayAPI:
  enable: true
  hostnames: reportportal.example.com
  gateway:
    create: true
    className: envoy-gateway
    listeners:
      - name: http
        protocol: HTTP
        port: 80
        hostname: reportportal.example.com
        allowedRoutes:
          namespaces:
            from: Same
      - name: https
        protocol: HTTPS
        port: 443
        hostname: reportportal.example.com
        tls:
          mode: Terminate
          certificateRefs:
            - kind: Secret
              name: reportportal-tls
        allowedRoutes:
          namespaces:
            from: Same

Using Let's Encrypt with Cert-Manager

Cert-Manager supports Gateway API natively for automatic certificate management.

Step 1: Install Cert-Manager

kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.16.2/cert-manager.yaml

Verify installation:

kubectl -n cert-manager get pods

Step 2: Create ClusterIssuer for Let's Encrypt

Create a file called letsencrypt-issuer.yaml:

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: your-email@example.com  # Replace with your email
    privateKeySecretRef:
      name: letsencrypt-prod-account-key
    solvers:
      - http01:
          gatewayHTTPRoute:
            parentRefs:
              - name: reportportal-gateway
                namespace: reportportal
                kind: Gateway

Apply the issuer:

kubectl apply -f letsencrypt-issuer.yaml

Step 3: Create Certificate Resource

Create a file called certificate.yaml:

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: reportportal-tls
  namespace: reportportal
spec:
  secretName: reportportal-tls
  issuerRef:
    name: letsencrypt-prod
    kind: ClusterIssuer
  dnsNames:
    - reportportal.example.com

Apply the certificate:

kubectl apply -f certificate.yaml

Step 4: Deploy ReportPortal with TLS

ingress:
  enable: false

gatewayAPI:
  enable: true
  hostnames: reportportal.example.com
  gateway:
    create: true
    className: envoy-gateway
    tls:
      enable: true
      secretName: reportportal-tls  # Managed by cert-manager

Step 5: Verify Certificate

# Check certificate status
kubectl get certificate -n reportportal

# Check certificate details
kubectl describe certificate reportportal-tls -n reportportal

# Check the secret was created
kubectl get secret reportportal-tls -n reportportal

Using DNS-01 Challenge (Wildcard Certificates)

For wildcard certificates or when HTTP-01 is not available:

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-dns
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: your-email@example.com
    privateKeySecretRef:
      name: letsencrypt-dns-account-key
    solvers:
      - dns01:
          cloudflare:
            email: your-cloudflare-email@example.com
            apiTokenSecretRef:
              name: cloudflare-api-token
              key: api-token

Configuration Examples

Example 1: Basic HTTP Deployment

ingress:
  enable: false

gatewayAPI:
  enable: true
  hostnames: reportportal.example.com
  gatewayRef:
    name: shared-gateway
    namespace: gateway-system

Example 2: HTTPS with Custom Certificate

ingress:
  enable: false

gatewayAPI:
  enable: true
  hostnames: reportportal.example.com
  gateway:
    create: true
    className: envoy-gateway
    annotations:
      external-dns.alpha.kubernetes.io/hostname: reportportal.example.com
    tls:
      enable: true
      mode: Terminate
      secretName: reportportal-tls

Example 3: With Base Path

ingress:
  enable: false

gatewayAPI:
  enable: true
  hostnames: example.com
  path: /reportportal
  gatewayRef:
    name: shared-gateway

This creates routes:

• /reportportal → Index service
• /reportportal/ui → UI service
• /reportportal/uat → UAT service
• /reportportal/api → API service

Example 4: Multiple Hostnames

ingress:
  enable: false

gatewayAPI:
  enable: true
  hostnames:
    - reportportal.example.com
    - rp.example.com
    - testing.example.com
  gateway:
    create: true
    className: envoy-gateway
    tls:
      enable: true
      secretName: reportportal-tls

Example 5: Reference Existing Gateway in Different Namespace

ingress:
  enable: false

gatewayAPI:
  enable: true
  hostnames: reportportal.example.com
  gatewayRef:
    name: central-gateway
    namespace: gateway-infra
    sectionName: https  # Specific listener name

Note: You may need a ReferenceGrant to allow cross-namespace references.

Example 6: Advanced with HTTPRoute Annotations

ingress:
  enable: false

gatewayAPI:
  enable: true
  hostnames: reportportal.example.com
  httpRoute:
    annotations:
      external-dns.alpha.kubernetes.io/hostname: reportportal.example.com
      external-dns.alpha.kubernetes.io/ttl: "60"
  gateway:
    create: true
    className: envoy-gateway
    tls:
      enable: true
      secretName: reportportal-tls

Gateway Controller: Envoy Gateway

This guide uses Envoy Gateway - a lightweight, Envoy-based Gateway controller.

Install Envoy Gateway

# Install Envoy Gateway
# Note: Use --skip-crds if you already installed Gateway API CRDs separately
helm install eg oci://docker.io/envoyproxy/gateway-helm \
  --version v1.3.0 \
  -n envoy-gateway-system \
  --create-namespace \
  --skip-crds

# Wait for Envoy Gateway to be ready
kubectl wait --for=condition=Available deployment/envoy-gateway -n envoy-gateway-system --timeout=120s

# Create GatewayClass
kubectl apply -f - <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: envoy-gateway
spec:
  controllerName: gateway.envoyproxy.io/gatewayclass-controller
EOF

# Verify GatewayClass is accepted
kubectl get gatewayclass envoy-gateway

Use with ReportPortal

gatewayAPI:
  gateway:
    className: envoy-gateway

Other Gateway Controllers

ReportPortal Gateway API support is compatible with any Gateway API implementation. For other controllers, consult their documentation:

• Istio
• Cilium
• NGINX Gateway Fabric
• GKE Gateway Controller

Troubleshooting

Common Issues

1. Gateway Not Programmed

# Check Gateway status
kubectl get gateway -n reportportal -o yaml

# Check GatewayClass exists and is accepted
kubectl get gatewayclass

# Check controller logs
kubectl logs -n <controller-namespace> deployment/<controller-name>

2. HTTPRoute Not Attached

# Check HTTPRoute status
kubectl describe httproute -n reportportal

# Verify parentRefs match Gateway
kubectl get gateway -n reportportal -o jsonpath='{.metadata.name}'

3. TLS Certificate Issues

# Check certificate status (if using cert-manager)
kubectl describe certificate -n reportportal

# Check secret exists
kubectl get secret -n reportportal | grep tls

# Verify secret has correct keys
kubectl get secret reportportal-tls -n reportportal -o jsonpath='{.data}' | jq 'keys'

4. Services Not Reachable

# Check services exist
kubectl get svc -n reportportal

# Test from within cluster
kubectl run curl --rm -it --image=curlimages/curl -- \
  curl -H "Host: reportportal.example.com" http://<gateway-ip>/api/health

Debugging Commands

# Get Gateway address
kubectl get gateway -n reportportal -o jsonpath='{.status.addresses[0].value}'

# Check attached routes
kubectl get gateway -n reportportal -o jsonpath='{.status.listeners[*].attachedRoutes}'

# View HTTPRoute conditions
kubectl get httproute -n reportportal -o jsonpath='{.status.parents[*].conditions}'

# Check Envoy config (for Envoy Gateway)
kubectl port-forward -n envoy-gateway-system deploy/envoy-gateway 19000:19000
curl localhost:19000/config_dump

Migration from Ingress

Step 1: Deploy Gateway API Resources

Deploy ReportPortal with both Ingress and Gateway API temporarily:

# Keep Ingress enabled during migration
ingress:
  enable: true
  class: nginx
  hosts: reportportal.example.com

# Enable Gateway API in parallel
gatewayAPI:
  enable: true
  hostnames: reportportal-new.example.com  # Use different hostname initially
  gateway:
    create: true
    className: envoy-gateway

Step 2: Test Gateway API

Verify Gateway API routing works:

curl -H "Host: reportportal-new.example.com" http://<gateway-ip>/api/health

Step 3: Switch DNS

Update DNS to point to Gateway instead of Ingress:

# Get Gateway IP
kubectl get gateway -n reportportal -o jsonpath='{.status.addresses[0].value}'

Step 4: Disable Ingress

Once verified, disable Ingress:

ingress:
  enable: false

gatewayAPI:
  enable: true
  hostnames: reportportal.example.com  # Original hostname
  gateway:
    create: true
    className: envoy-gateway

Additional Resources

• Gateway API Documentation
• Cert-Manager Gateway API Integration
• Envoy Gateway Documentation
• ReportPortal Documentation

Support

For issues specific to ReportPortal Gateway API deployment:

• Check the ReportPortal GitHub Issues
• Review Gateway controller documentation
• Consult cert-manager documentation for TLS issues