Skip to content

TLS Setup with Gateway API

This guide configures HTTPS for QMigrator using cert-manager to automatically provision and renew TLS certificates via Let's Encrypt.

Tip

Skip this guide if you do not need HTTPS. QMigrator deploys successfully with HTTP only. You can add TLS at any time by following these steps.

Prerequisites

  • A Gateway API controller is installed and a GatewayClass is available — see Gateway Controller.
  • A valid domain name pointing to your cluster's external IP.

Step 1: Install cert-manager

  1. Add the cert-manager Helm repository: 

    helm repo add jetstack https://charts.jetstack.io --force-update

  2. Install cert-manager with Gateway API support enabled: 

    helm upgrade --install cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --create-namespace \
  --set config.enableGatewayAPI=true \
  --set crds.enabled=true

  3. Verify all cert-manager pods are running: 

    kubectl get pods -n cert-manager

Step 2: Create a Certificate Issuer

Choose ClusterIssuer (cluster-wide) or Issuer (namespace-scoped):

cert-issuer.yaml
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    privateKeySecretRef:
      name: letsencrypt
    solvers:
      - http01:
          gatewayHTTPRoute:
            parentRefs:
              - name: qmig-gateway  # (1)!
  1. Use your gateway name to be created or leave as qmig-gateway if using Helm-deployed gateway.

Apply: 

kubectl apply -f cert-issuer.yaml

cert-issuer.yaml
apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: letsencrypt
  namespace: <namespace> # (1)!
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    privateKeySecretRef:
      name: letsencrypt
    solvers:
      - http01:
          gatewayHTTPRoute:
            parentRefs:
              - name: qmig-gateway # (2)!
                namespace: <namespace>
  1. Replace with your target namespace (e.g., qmigrator).
  2. Use your gateway name to be created or leave as qmig-gateway if using Helm-deployed gateway.

Apply: 

kubectl apply -f cert-issuer.yaml

Step 3: Configure the Gateway for TLS

Annotate the Gateway so cert-manager issues a certificate automatically, then add an HTTPS listener:

values.yaml
gateway:
  annotations:
    cert-manager.io/cluster-issuer: "letsencrypt"
  listeners:  # (1)!
  - name: http
    protocol: HTTP
    port: 80
    allowedRoutes:
      namespaces:
        from: Same
  - name: https
    hostnames: ["your-domain.com"] # (3)!
    protocol: HTTPS
    port: 443
    tls:
      mode: Terminate
      certificateRefs:
      - name: qmig-tls-cert  # (2)!
    allowedRoutes:
      namespaces:
        from: Same
  1. Gateway listeners configured for both HTTP and HTTPS.
  2. Certificate name managed by cert-manager (e.g., qmig-tls-cert).
  3. Replace with your domain name (e.g., qmigrator.example.com or use the gateway external IP).

Step 4: Configure HTTPRoutes for HTTPS

Reference both http and https listeners in your HTTPRoute values:

values.yaml
httpRoutes:
  enabled: true
  hostnames: ["your-domain.com"]  # (1)!
  parentRefs:
  - name: qmig-gateway
    namespace: qmigrator
    sectionName: http
  - name: qmig-gateway
    namespace: qmigrator
    sectionName: https
  1. Replace with your actual domain name.

Step 5: Verify the Certificate

After applying, cert-manager requests the certificate from Let's Encrypt. Check the status:

kubectl get certificate -n qmigrator

A READY: True status confirms the certificate was issued. It may take a minute for the ACME challenge to complete.

kubectl describe certificate qmig-tls-cert -n qmigrator

References