Gateway Certificate Operator

The gateway-cert-operator automates the configuration of Gateway API Gateway listeners when using cert-manager for TLS certificate management.

Overview

When you create a Certificate resource using cert-manager, this operator automatically and dynamically creates an HTTPS Listener on your target Gateway. This eliminates the need for manual configuration of the Gateway each time a new certificate is provisioned or its DNS names change.

Architecture

The operator acts as a bridge between two standard Kubernetes APIS:

• cert-manager.io/v1 Certificate
• gateway.networking.k8s.io/v1 Gateway

By watching both resources, the controller ensures that the Gateway always has the correct listeners configured to serve HTTPs traffic for the domains requested in the certificates.

Prerequisites

• A Kubernetes cluster.
• Gateway API installed (v1 APIs).
• cert-manager installed (v1 APIs).

Usage

To use the operator, simply add the appropriate annotations to your Certificate resource.

Example Certificate

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: my-app-cert
  namespace: default
  annotations:
    # Required: The name of the target Gateway
    gateway-cert-operator.io/gateway-name: "my-gateway"
    
    # Optional: If the Gateway is in a different namespace
    # gateway-cert-operator.io/gateway-namespace: "gateway-system"
spec:
  secretName: my-app-tls
  dnsNames:
    - "app.example.com"
  issuerRef:
    name: letsencrypt-prod
    kind: ClusterIssuer

Lifecycle

1. Trigger: The operator detects the gateway-cert-operator.io/gateway-name annotation on the Certificate.
2. Gateway Lookup: It fetches the designated target Gateway (my-gateway).
3. Patching: For each DNS name defined in spec.dnsNames, it mathematically appends a new HTTPS Listener on port 443 terminating TLS using the secret created by cert-manager (my-app-tls).
4. Safe Coexistence: To safely coexist with manually defined listeners, the operator uniquely prefixes its configured listeners with auto- (e.g., auto-my-app-cert-app-example-com). It solely manages listeners with this prefix.

When a certificate is deleted or updated (for instance if a DNS name is changed), the operator will instantly reconcile the modified states by cleanly removing older auto-* listeners and inserting the new ones while preserving the manually defined resources.

Deployment

To deploy the operator, applying the provided manifest sets up the necessary RBAC permissions and the controller manager:

kubectl apply -f deploy/manifests.yaml