mirror of
https://github.com/shankar0123/certctl.git
synced 2026-06-07 16:41:36 +00:00
shankar0123
d327ace885
Extracts the file-based deploy target connectors: - haproxy.md (107 lines) — combined-PEM (cert+chain+key) deploy with haproxy -c validate; multi-frontend + crt-list directory guidance - traefik.md (105 lines) — file-provider zero-reload deploy; file watcher latency notes; mixing with built-in ACME guidance - caddy.md (100 lines) — admin API mode (recommended) vs file mode; admin-API exposure threat model - envoy.md (112 lines) — file SDS mode (recommended) vs static bootstrap; service-mesh interactions - postfix.md (175 lines) — dual-mode (Postfix MTA / Dovecot IMAPS) connector with daemon-specific quirks (STARTTLS chain expectations, no shared session cache); Bundle 11 test pins Index forward-list expanded to enumerate all 10 target connectors (5 from Phase 4 structural + 5 from this batch) in alphabetical order. This is part 3 of 4 for the Phase 4 follow-on (per-connector page extraction) tracked in cowork/docs-overhaul-phase-2-restructure-2026-05-04/log.md. Net add: 5 files, 599 lines. No content removed from index.md.
113 lines
4.2 KiB
Markdown
113 lines
4.2 KiB
Markdown
# Envoy Connector — Operator Deep-Dive
|
|
|
|
> Last reviewed: 2026-05-05
|
|
>
|
|
> Operator-grade documentation for the Envoy target connector. For
|
|
> the connector-development context (interface contract, registry,
|
|
> atomic deploy primitive shared across all targets), see the
|
|
> [connector index](index.md).
|
|
|
|
## Overview
|
|
|
|
The Envoy connector uses **file-based certificate delivery** — it
|
|
writes certificate and key files to a directory that Envoy watches
|
|
via its SDS (Secret Discovery Service) file-based configuration or
|
|
static `filename` references in the bootstrap config. When files
|
|
change, Envoy automatically picks up the new certificates without
|
|
requiring a reload command.
|
|
|
|
Implementation lives at `internal/connector/target/envoy/`.
|
|
|
|
## When to use this connector
|
|
|
|
Use the Envoy connector when:
|
|
|
|
- Envoy fronts your services (standalone, as part of a service
|
|
mesh, or as an API gateway like Emissary or Gloo).
|
|
- You want certctl to drive cert rotation and let Envoy's file
|
|
SDS handle the rolling reload across worker threads.
|
|
|
|
Look elsewhere when:
|
|
|
|
- You're running an Envoy-based service mesh (Istio, Consul
|
|
Connect) — those meshes have their own cert distribution
|
|
pipelines, and integrating certctl at the mesh layer is a
|
|
different design than this connector covers.
|
|
- You're using Envoy's xDS/gRPC SDS path (not file-based SDS) —
|
|
the gRPC SDS-server connector is on the V3-Pro roadmap.
|
|
|
|
## Configuration
|
|
|
|
```json
|
|
{
|
|
"cert_dir": "/etc/envoy/certs",
|
|
"cert_filename": "cert.pem",
|
|
"key_filename": "key.pem",
|
|
"chain_filename": "chain.pem",
|
|
"sds_config": true
|
|
}
|
|
```
|
|
|
|
| Field | Type | Default | Description |
|
|
|---|---|---|---|
|
|
| `cert_dir` | string | (required) | Directory where Envoy watches for certificate files |
|
|
| `cert_filename` | string | `cert.pem` | Filename for the certificate (leaf + chain unless `chain_filename` is set) |
|
|
| `key_filename` | string | `key.pem` | Filename for the private key |
|
|
| `chain_filename` | string | (empty) | If set, chain is written to a separate file instead of appended to the cert |
|
|
| `sds_config` | bool | `false` | If true, writes an `sds.json` file for Envoy's file-based SDS provider |
|
|
|
|
## SDS mode (recommended for production)
|
|
|
|
When `sds_config` is `true`, the connector writes an SDS JSON
|
|
file (`{cert_dir}/sds.json`) containing a `tls_certificate`
|
|
resource that points to the cert and key file paths. Envoy's
|
|
file-based SDS (`path_config_source`) watches this file for
|
|
changes, providing automatic hot-reload of certificates without
|
|
restarting worker threads.
|
|
|
|
This is the recommended approach for production Envoy deployments
|
|
using dynamic TLS configuration.
|
|
|
|
## Static-bootstrap mode
|
|
|
|
When `sds_config` is `false` (the default), the connector simply
|
|
writes cert and key files. Use this mode when Envoy's bootstrap
|
|
config references the cert / key files directly via static
|
|
`filename` fields in the TLS context.
|
|
|
|
In this mode Envoy still picks up file changes via its filesystem
|
|
watcher, but the operator should verify the bootstrap config sets
|
|
`watched_directory` (or equivalent) on each `tls_certificate`
|
|
entry — without it, the cert is loaded once at startup and
|
|
subsequent file changes are ignored.
|
|
|
|
## Deploy contract
|
|
|
|
Standard atomic-write + post-deploy verify (file-based deploy
|
|
primitive shared across all file-deploy connectors). When SDS
|
|
mode is on, the SDS JSON file is updated last so Envoy sees the
|
|
cert / key on disk before the SDS resource pointer changes.
|
|
|
|
## Operator playbook
|
|
|
|
### Hot-reload across worker threads
|
|
|
|
Envoy's file SDS path triggers a per-worker-thread reload as each
|
|
worker re-reads the SDS file. In-flight TLS connections on each
|
|
worker continue with the OLD cert until they close; new
|
|
connections after the reload pick up the NEW cert.
|
|
|
|
### Service mesh interactions
|
|
|
|
If you're running Istio or Consul Connect, the mesh's own cert
|
|
distribution pipeline (citadel / SDS server) is the system of
|
|
record for sidecar certs. Don't point this connector at sidecar
|
|
cert paths — point it at standalone Envoy gateways or API edges
|
|
that aren't sidecar-managed.
|
|
|
|
## Related docs
|
|
|
|
- [Connector index](index.md) — interface contract, registry, deploy primitive
|
|
- [NGINX](nginx.md) — explicit-reload-command counterpart
|
|
- [Traefik](traefik.md) — file-watcher counterpart with simpler semantics
|