Jan Novak
a78e4421ef
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>
65 lines
2.7 KiB
Markdown
65 lines
2.7 KiB
Markdown
# 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](https://gateway-api.sigs.k8s.io/) installed (`v1` APIs).
|
|
- [cert-manager](https://cert-manager.io/) installed (`v1` APIs).
|
|
|
|
## Usage
|
|
|
|
To use the operator, simply add the appropriate annotations to your `Certificate` resource.
|
|
|
|
### Example Certificate
|
|
```yaml
|
|
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:
|
|
|
|
```bash
|
|
kubectl apply -f deploy/manifests.yaml
|
|
```
|