Files

T

kacerrandClaude Opus 5.5 7a559bacd0 docs: rewrite CLAUDE.md to house conventions, fix flows.md and README

- CLAUDE.md in five sections with Go, testing, plan, changelog, branching
  and tagging rules; known sharp edges moved to Gotchas
- docs/flows.md: metrics are served on :8080, name collisions are rejected
  by the API server, last-cert deletion never cleans up
- README moved to the repo root, deploy command corrected

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

2026-10-08 20:31:00 +02: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 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/

2.7 KiB Raw Blame History