kacerrandClaude Opus 5.5
7a559bacd0
- 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>
67 lines
2.7 KiB
Markdown
67 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 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:
|
|
|
|
```bash
|
|
kubectl apply -k deploy/
|
|
```
|