Files

Jan Novak a78e4421ef feat: initial implementation of gateway-cert-operator

Kubernetes operator that automates HTTPS listener configuration on
Gateway API Gateway resources whenever a cert-manager Certificate is
created or updated.

Core behaviour:
- Watches cert-manager Certificate resources for the annotation
  gateway-cert-operator.io/gateway-name to identify the target Gateway
- Builds HTTPS listeners (prefixed "auto-") from each Certificate's
  DNS SANs and merges them into the target Gateway's listener list
- Preserves any manually-managed listeners; removes stale auto-listeners
  when Certificates are deleted or their annotations are removed
- Supports optional annotations to override the target namespace and
  listener port (default 443)

Components:
- main.go                            – manager setup, scheme registration,
                                       health/readiness probes
- internal/controller/               – Certificate reconciler with field
                                       indexing and dual-watch pattern
- internal/gateway/patch.go          – listener construction, merge, and
                                       equality helpers
- deploy/manifests.yaml              – Namespace, RBAC, and Deployment
- docs/README.md                     – usage guide and architecture notes
- Dockerfile                         – distroless multi-stage build

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-03-26 10:54:33 +01:00

2.7 KiB

Raw Blame History

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

Trigger: The operator detects the gateway-cert-operator.io/gateway-name annotation on the Certificate.
Gateway Lookup: It fetches the designated target Gateway (my-gateway).
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).
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

2.7 KiB Raw Blame History