feat(annotations): ingress-nginx → synapse migration parity#25
Merged
Conversation
Adds the ingress-nginx annotations that block cluster migration to
synapse, plus the conditional v2 schema emission ssl-passthrough
requires.
Annotations added (synapse.gen0sec.com/<key> + nginx-compat fallback)
proxy-body-size size → max_body_size (per-route 413 cap; nginx
suffixes k/m/g)
server-alias csv → duplicate the route under each alias host
with the same backend + settings (cert
binding NOT inferred — list aliases in
spec.tls[].hosts to get TLS for them)
ssl-passthrough bool → v2 tls.passthrough — SNI-routed TCP
passthrough; synapse terminates nothing
for these hosts
permanent-redirect url → redirect { status: 301, location }
permanent-redirect-code u → override the 301 default (e.g. 308)
temporal-redirect url → redirect { status: 302, location }
temporal-redirect-code u → override the 302 default (e.g. 307)
Synapse-prefixed keys take precedence over nginx-compat keys
(consistent with the rest of the parser). If both permanent-redirect
and temporal-redirect are set, permanent wins (stronger commitment).
Schema selection
When any Ingress carries ssl-passthrough, the operator switches the
WHOLE file to v2 (v1 schema has no passthrough representation, v2
parser is schema-version-strict). Otherwise emits v1, so deployments
without passthrough see zero behaviour change. Detection is
automatic — no operator config flag.
v2 emission faithfully covers terminate hosts: tls.terminate.cert,
paths{...} with upstream/upstreams + per-route ssl_enabled,
http2_enabled, force_https, disable_access_log, max_body_size,
timeouts{...}, headers{...}, redirect{...}, plus the boolean
healthcheck lowered to v2's structured health_check.type=tcp.
Depends on synapse's v2 RawRoute carrying those v1-compat fields
(companion synapse PR).
FIRST-WRITER-WINS extends to passthrough
addPassthroughHost rejects a host already claimed by a terminate
route (and vice versa). Conflict emits the existing RouteConflict
Warning Event + bumps synapse_operator_route_conflicts_total
counter. Same idempotent observability as the existing terminate-
on-terminate conflict path.
server-alias on conflict
Each alias gets its own addRoute call after the primary; collisions
on an alias hostname go through the same RouteConflict path.
Renamed v1 emission. Existing renderUpstreams stays the only path
when no passthrough host is present — diff is purely additive for
clusters that don't use ssl-passthrough.
Tests
- parseSize (bytes / k/m/g / whitespace / negative / unknown suffix)
- proxy-body-size parsing + synapse-vs-nginx precedence
- server-alias parsing (csv, fallbacks, precedence)
- server-alias emission (route duplicated under each alias)
- ssl-passthrough parsing
- addPassthroughHost FIRST-WRITER-WINS (terminate-on-passthrough
and passthrough-on-passthrough rejection)
- renderUpstreamsV2: scaffolding, sticky-sessions, ACME internal
block, terminate + passthrough mixed in one render, all per-route
v1-compat knobs threaded
- redirect: parsing of all 4 keys + permanent-wins-over-temporal,
emission in v1 and v2 renderers
- max_body_size emission (v1) — present when set, absent when None
Out of scope here (not yet wired)
- rewrite-target / app-root annotation. Synapse-side RewriteConfig
machinery is in place from the companion synapse PR but the
operator-side annotation wiring is a follow-up PR. app-root is
explicitly out of migration scope.
- mTLS annotations (auth-tls-*, proxy-ssl-*) — off the roadmap.
- basic/digest auth (auth-type, auth-secret, *) — no synapse
equivalent; flagged for the migration plan.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds the ingress-nginx annotations that block cluster migration to synapse, plus the conditional v2 schema emission ssl-passthrough requires. Companion synapse PR: gen0sec/synapse#328.
Annotations added
`synapse.gen0sec.com/` + nginx-compat (`nginx.ingress.kubernetes.io/`) fallback for all of these:
Synapse-prefixed keys take precedence over nginx-compat. When both `permanent-redirect` and `temporal-redirect` are set, permanent wins.
Schema selection
When any Ingress carries `ssl-passthrough`, the operator switches the whole file to v2 (v1 has no passthrough representation, v2 parser is schema-version-strict). Otherwise emits v1 — zero behaviour change for deployments not using passthrough. Detection is automatic, no operator config flag.
v2 emission faithfully covers terminate hosts: `tls.terminate.cert`, `paths{...}` with `upstream`/`upstreams` + per-route `ssl_enabled`, `http2_enabled`, `force_https`, `disable_access_log`, `max_body_size`, `timeouts`, `headers`, `redirect`, plus boolean `healthcheck` lowered to v2's structured `health_check.type=tcp`. Depends on the companion synapse PR carrying those v1-compat fields on v2 `RawRoute`.
Out of scope
Test plan