kacerrandClaude Opus 5.5
ab408403bc
Covers current correct behaviour of the pure functions in internal/gateway. Known-buggy inputs (wildcards, collisions, truncation) are left out on purpose. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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/v1Certificategateway.networking.k8s.io/v1Gateway
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 (
v1APIs). - cert-manager installed (
v1APIs).
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-nameannotation on theCertificate. - Gateway Lookup: It fetches the designated target Gateway (
my-gateway). - Patching: For each DNS name defined in
spec.dnsNames, it mathematically appends a new HTTPSListeneron port443terminating TLS using the secret created bycert-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 updated (for instance if a DNS name is changed), the operator removes the older auto-* listeners and inserts the new ones while preserving the manually defined resources.
Known limitation: when a certificate is deleted, its listeners are removed only on the next reconcile of another certificate targeting the same Gateway.
Deployment
To deploy the operator, applying the provided manifest sets up the necessary RBAC permissions and the controller manager:
kubectl apply -k deploy/