From d0326e973b3b5459fd2cb69694ffe666f8f1a6f2 Mon Sep 17 00:00:00 2001 From: "shipmill-romamo[bot]" <338557544+shipmill-romamo[bot]@users.noreply.github.com> Date: Thu, 19 Nov 2026 13:36:31 +0200 Subject: [PATCH 1/2] Let operators turn HTTP/2 off on the managed Nginx vhost The cloudfall_nginx_site role takes cloudfall_nginx_site_http2 (bool, default true). When false the TLS server renders listen 443 ssl; and listen [::]:443 ssl; with no http2 on either side of Nginx 1.25.1. The template reads it through | bool, since a key=value --extra-vars hands the role the truthy string "false". The default render is byte-identical to the golden files. Co-Authored-By: Claude Opus 5.5 --- changelog.d/551-nginx-http2-switch.md | 3 ++ engine/README.md | 5 +- .../cloudfall_nginx_site/defaults/main.yml | 2 + .../meta/argument_specs.yml | 3 ++ .../templates/domain-site.conf.j2 | 9 +++- engine/tests/test_nginx_site_routes.py | 51 +++++++++++++++++-- engine/tests/test_nginx_site_templates.py | 35 ++++++++++++- 7 files changed, 102 insertions(+), 6 deletions(-) create mode 100644 changelog.d/551-nginx-http2-switch.md diff --git a/changelog.d/551-nginx-http2-switch.md b/changelog.d/551-nginx-http2-switch.md new file mode 100644 index 00000000..47cd71e2 --- /dev/null +++ b/changelog.d/551-nginx-http2-switch.md @@ -0,0 +1,3 @@ +### Added + +- The `cloudfall_nginx_site` role takes `cloudfall_nginx_site_http2` (bool, default `true`): set it to `false` in the inventory or with `--extra-vars cloudfall_nginx_site_http2=false` and the managed vhost's HTTPS server renders `listen 443 ssl;` and `listen [::]:443 ssl;` with no `http2` on any Nginx version, so turning HTTP/2 off survives the next `domains` run. The default renders a byte-identical vhost (#551) diff --git a/engine/README.md b/engine/README.md index f9f6bed7..bf0965e6 100644 --- a/engine/README.md +++ b/engine/README.md @@ -371,7 +371,10 @@ The site role installs Nginx and Certbot, serves the ACME challenge webroot, and converges in two phases: until a certificate exists the route serves plain HTTP so the site stays reachable during cutover; once TLS material is present (or issuance is explicitly requested via `ISSUE_CERTIFICATES=true`) -HTTP redirects to HTTPS with TLS 1.2+. The proxy discards any +HTTP redirects to HTTPS with TLS 1.2+. The HTTPS server speaks HTTP/2; to +turn it off, set `cloudfall_nginx_site_http2: false` in the inventory's host +or group vars, or pass `--extra-vars cloudfall_nginx_site_http2=false` to +`ansible-playbook`. The proxy discards any client-supplied forwarding chain and sends only the canonical `$remote_addr` as `X-Forwarded-For` and `X-Real-IP`, so upstream applications cannot be spoofed by forged headers. When TLS is required the diff --git a/engine/ansible/roles/cloudfall_nginx_site/defaults/main.yml b/engine/ansible/roles/cloudfall_nginx_site/defaults/main.yml index 17530a1e..5c530e1f 100644 --- a/engine/ansible/roles/cloudfall_nginx_site/defaults/main.yml +++ b/engine/ansible/roles/cloudfall_nginx_site/defaults/main.yml @@ -2,5 +2,7 @@ cloudfall_nginx_site_issue_certificate: false cloudfall_nginx_site_acme_webroot: /var/lib/letsencrypt cloudfall_nginx_site_receipt_directory: "" +# false renders the TLS server without HTTP/2 on every Nginx version. +cloudfall_nginx_site_http2: true # Debian's Nginx runs its workers as www-data. cloudfall_nginx_site_worker_user: www-data diff --git a/engine/ansible/roles/cloudfall_nginx_site/meta/argument_specs.yml b/engine/ansible/roles/cloudfall_nginx_site/meta/argument_specs.yml index 7f17fa11..f63817dc 100644 --- a/engine/ansible/roles/cloudfall_nginx_site/meta/argument_specs.yml +++ b/engine/ansible/roles/cloudfall_nginx_site/meta/argument_specs.yml @@ -105,6 +105,9 @@ argument_specs: cloudfall_nginx_site_receipt_directory: type: str default: "" + cloudfall_nginx_site_http2: + type: bool + default: true cloudfall_nginx_site_worker_user: type: str default: www-data diff --git a/engine/ansible/roles/cloudfall_nginx_site/templates/domain-site.conf.j2 b/engine/ansible/roles/cloudfall_nginx_site/templates/domain-site.conf.j2 index 8ec49cad..56b05fe3 100644 --- a/engine/ansible/roles/cloudfall_nginx_site/templates/domain-site.conf.j2 +++ b/engine/ansible/roles/cloudfall_nginx_site/templates/domain-site.conf.j2 @@ -90,7 +90,14 @@ server { {% if cloudfall_nginx_site_tls_active %} server { -{% if cloudfall_nginx_site_version is version('1.25.1', '>=') %} +{# + `| bool` because a key=value `--extra-vars` hands the role the string + "false", which is truthy. +#} +{% if not cloudfall_nginx_site_http2 | bool %} + listen 443 ssl; + listen [::]:443 ssl; +{% elif cloudfall_nginx_site_version is version('1.25.1', '>=') %} listen 443 ssl; listen [::]:443 ssl; http2 on; diff --git a/engine/tests/test_nginx_site_routes.py b/engine/tests/test_nginx_site_routes.py index e4b148d1..c6738b29 100644 --- a/engine/tests/test_nginx_site_routes.py +++ b/engine/tests/test_nginx_site_routes.py @@ -155,10 +155,21 @@ def _play(tmp_path: Path, name: str, play: dict[str, object]) -> str: return done.stdout +def _role_default(name: str) -> object: + defaults = yaml.safe_load((ROLE / "defaults" / "main.yml").read_text("utf-8")) + return cast("dict[str, object]", defaults)[name] + + def _render_all( - tmp_path: Path, domains: dict[str, dict[str, object]] + tmp_path: Path, + domains: dict[str, dict[str, object]], + overrides: dict[str, dict[str, object]], ) -> dict[str, str]: - """Render each Domain with TLS on and off on both Nginx versions.""" + """Render each Domain with TLS on and off on both Nginx versions. + + Role variables come from the role's defaults unless ``overrides`` names + the Domain's label. + """ output = tmp_path / "rendered" output.mkdir() tasks: list[dict[str, object]] = [] @@ -182,7 +193,11 @@ def _render_all( "cloudfall_nginx_site_acme_webroot": "/var/lib/letsencrypt", "cloudfall_nginx_site_tls_active": tls_active, "cloudfall_nginx_site_version": version, - }, + "cloudfall_nginx_site_http2": _role_default( + "cloudfall_nginx_site_http2" + ), + } + | overrides.get(label, {}), } ) _play(tmp_path, "render", {"tasks": tasks}) @@ -200,6 +215,13 @@ def rendered(tmp_path_factory: pytest.TempPathFactory) -> dict[str, str]: "nested": _routed_domain(tmp_path, _NESTED_ROUTES), "reversed": _routed_domain(tmp_path, _NESTED_ROUTES_REVERSED), "no-root": _routed_domain(tmp_path, _NO_ROOT_ROUTES), + "no-http2": _upstream_only_domain(), + "no-http2-extra-var": _upstream_only_domain(), + }, + { + "no-http2": {"cloudfall_nginx_site_http2": False}, + # What `--extra-vars cloudfall_nginx_site_http2=false` hands the role. + "no-http2-extra-var": {"cloudfall_nginx_site_http2": "false"}, }, ) @@ -318,6 +340,29 @@ def test_s003_7_an_upstream_only_domain_renders_byte_identical( assert rendered[f"upstream/{name}"] == golden +@pytest.mark.parametrize("nginx_version", NGINX_VERSIONS) +@pytest.mark.parametrize("label", ["no-http2", "no-http2-extra-var"]) +def test_http2_off_drops_it_from_the_tls_server_on_every_version( + rendered: dict[str, str], label: str, nginx_version: str +) -> None: + """Only the listen lines differ from the default render (#551).""" + vhost = rendered[f"{label}/tls-{nginx_version}.conf"] + golden = (GOLDEN / f"tls-{nginx_version}.conf").read_text(encoding="utf-8") + tls = _servers(vhost)[1] + + assert tls.startswith( + "server {\n" + " listen 443 ssl;\n" + " listen [::]:443 ssl;\n" + " server_name crm.example.test www.crm.example.test;\n" + ) + assert "http2" not in vhost + assert vhost == golden.replace("ssl http2;", "ssl;").replace(" http2 on;\n", "") + assert rendered[f"{label}/http-{nginx_version}.conf"] == ( + GOLDEN / f"http-{nginx_version}.conf" + ).read_text(encoding="utf-8") + + # proves: S-003-2 @pytest.mark.parametrize("nginx_version", NGINX_VERSIONS) @pytest.mark.parametrize("tls_active", [True, False]) diff --git a/engine/tests/test_nginx_site_templates.py b/engine/tests/test_nginx_site_templates.py index 7736e92d..fb484ec7 100644 --- a/engine/tests/test_nginx_site_templates.py +++ b/engine/tests/test_nginx_site_templates.py @@ -5,6 +5,8 @@ from pathlib import Path import pytest +import yaml +from ansible.plugins.filter.core import FilterModule as AnsibleFilters # Aliased so pytest does not collect Ansible's plugin class as a test class. from ansible.plugins.test.core import TestModule as AnsibleTests @@ -35,7 +37,9 @@ def _domain() -> dict[str, object]: } -def _render(*, tls_active: bool, nginx_version: str = "1.26.3") -> str: +def _render( + *, tls_active: bool, nginx_version: str = "1.26.3", http2: object = True +) -> str: # trim_blocks matches the template module's default. environment = Environment( loader=FileSystemLoader(TEMPLATES), @@ -46,11 +50,13 @@ def _render(*, tls_active: bool, nginx_version: str = "1.26.3") -> str: ) # Ansible's own tests, so `is version(...)` compares as on the host. environment.tests.update(AnsibleTests().tests()) + environment.filters.update(AnsibleFilters().filters()) return environment.get_template("domain-site.conf.j2").render( cloudfall_nginx_site_domain=_domain(), cloudfall_nginx_site_acme_webroot="/var/lib/letsencrypt", cloudfall_nginx_site_tls_active=tls_active, cloudfall_nginx_site_version=nginx_version, + cloudfall_nginx_site_http2=http2, ) @@ -113,3 +119,30 @@ def test_nginx_from_1_25_1_gets_the_http2_directive(nginx_version: str) -> None: " server_name crm.example.test www.crm.example.test;\n" ) in rendered assert "ssl http2;" not in rendered + + +@pytest.mark.parametrize("http2", [False, "false"]) +@pytest.mark.parametrize("nginx_version", [DEBIAN_12_NGINX, "1.26.3"]) +def test_http2_off_renders_no_http2_on_either_side_of_1_25_1( + nginx_version: str, http2: object +) -> None: + """`"false"` is what a key=value `--extra-vars` hands the role (#551).""" + rendered = _render(tls_active=True, nginx_version=nginx_version, http2=http2) + + assert ( + "server {\n" + " listen 443 ssl;\n" + " listen [::]:443 ssl;\n" + " server_name crm.example.test www.crm.example.test;\n" + ) in rendered + assert "http2" not in rendered + + +def test_http2_defaults_on_in_the_role_and_its_argument_spec() -> None: + role = TEMPLATES.parent + defaults = yaml.safe_load((role / "defaults" / "main.yml").read_text("utf-8")) + specs = yaml.safe_load((role / "meta" / "argument_specs.yml").read_text("utf-8")) + option = specs["argument_specs"]["main"]["options"]["cloudfall_nginx_site_http2"] + + assert defaults["cloudfall_nginx_site_http2"] is True + assert option == {"type": "bool", "default": True} From 93fc258602b6092349dc13a40bb5722f9db5f947 Mon Sep 17 00:00:00 2001 From: "shipmill-romamo[bot]" <338557544+shipmill-romamo[bot]@users.noreply.github.com> Date: Thu, 19 Nov 2026 22:02:19 +0200 Subject: [PATCH 2/2] Default cloudfall_nginx_site_http2 to false The maintainer chose option 1 on #552's question: the managed vhost's HTTPS server drops HTTP/2 by default, and an operator turns it back on with the variable once the installed Nginx carries the HTTP/2 fix. The golden files keep the HTTP/2-on shape: the routes test renders them with the variable true, and a new role-default case proves the role's default renders the vhost without http2 on 1.22.1 and 1.26.3. Part of #551 Co-Authored-By: Claude Opus 5.5 --- changelog.d/551-nginx-http2-switch.md | 4 ++-- engine/README.md | 7 ++++--- .../roles/cloudfall_nginx_site/defaults/main.yml | 5 +++-- .../cloudfall_nginx_site/meta/argument_specs.yml | 2 +- engine/tests/test_nginx_site_routes.py | 16 ++++++++++------ engine/tests/test_nginx_site_templates.py | 6 +++--- 6 files changed, 23 insertions(+), 17 deletions(-) diff --git a/changelog.d/551-nginx-http2-switch.md b/changelog.d/551-nginx-http2-switch.md index 47cd71e2..43d46d52 100644 --- a/changelog.d/551-nginx-http2-switch.md +++ b/changelog.d/551-nginx-http2-switch.md @@ -1,3 +1,3 @@ -### Added +### Changed -- The `cloudfall_nginx_site` role takes `cloudfall_nginx_site_http2` (bool, default `true`): set it to `false` in the inventory or with `--extra-vars cloudfall_nginx_site_http2=false` and the managed vhost's HTTPS server renders `listen 443 ssl;` and `listen [::]:443 ssl;` with no `http2` on any Nginx version, so turning HTTP/2 off survives the next `domains` run. The default renders a byte-identical vhost (#551) +- The managed vhost's HTTPS server no longer serves HTTP/2 by default: the `cloudfall_nginx_site` role takes `cloudfall_nginx_site_http2` (bool, default `false`), and the next `domains` run renders `listen 443 ssl;` and `listen [::]:443 ssl;` with no `http2` on any Nginx version. Once the installed Nginx carries the HTTP/2 fix, set it to `true` in the inventory or with `--extra-vars cloudfall_nginx_site_http2=true` to render HTTP/2 as before (#551) diff --git a/engine/README.md b/engine/README.md index bf0965e6..be57a1e2 100644 --- a/engine/README.md +++ b/engine/README.md @@ -371,9 +371,10 @@ The site role installs Nginx and Certbot, serves the ACME challenge webroot, and converges in two phases: until a certificate exists the route serves plain HTTP so the site stays reachable during cutover; once TLS material is present (or issuance is explicitly requested via `ISSUE_CERTIFICATES=true`) -HTTP redirects to HTTPS with TLS 1.2+. The HTTPS server speaks HTTP/2; to -turn it off, set `cloudfall_nginx_site_http2: false` in the inventory's host -or group vars, or pass `--extra-vars cloudfall_nginx_site_http2=false` to +HTTP redirects to HTTPS with TLS 1.2+. The HTTPS server serves HTTP/1.1 +only by default; once the installed Nginx carries the HTTP/2 fix, turn +HTTP/2 on with `cloudfall_nginx_site_http2: true` in the inventory's host +or group vars, or pass `--extra-vars cloudfall_nginx_site_http2=true` to `ansible-playbook`. The proxy discards any client-supplied forwarding chain and sends only the canonical `$remote_addr` as `X-Forwarded-For` and `X-Real-IP`, so upstream diff --git a/engine/ansible/roles/cloudfall_nginx_site/defaults/main.yml b/engine/ansible/roles/cloudfall_nginx_site/defaults/main.yml index 5c530e1f..edfbbafa 100644 --- a/engine/ansible/roles/cloudfall_nginx_site/defaults/main.yml +++ b/engine/ansible/roles/cloudfall_nginx_site/defaults/main.yml @@ -2,7 +2,8 @@ cloudfall_nginx_site_issue_certificate: false cloudfall_nginx_site_acme_webroot: /var/lib/letsencrypt cloudfall_nginx_site_receipt_directory: "" -# false renders the TLS server without HTTP/2 on every Nginx version. -cloudfall_nginx_site_http2: true +# Off by default until the installed Nginx carries the HTTP/2 fix (#551); +# true renders HTTP/2 in the form the installed Nginx parses. +cloudfall_nginx_site_http2: false # Debian's Nginx runs its workers as www-data. cloudfall_nginx_site_worker_user: www-data diff --git a/engine/ansible/roles/cloudfall_nginx_site/meta/argument_specs.yml b/engine/ansible/roles/cloudfall_nginx_site/meta/argument_specs.yml index f63817dc..8f3af8b2 100644 --- a/engine/ansible/roles/cloudfall_nginx_site/meta/argument_specs.yml +++ b/engine/ansible/roles/cloudfall_nginx_site/meta/argument_specs.yml @@ -107,7 +107,7 @@ argument_specs: default: "" cloudfall_nginx_site_http2: type: bool - default: true + default: false cloudfall_nginx_site_worker_user: type: str default: www-data diff --git a/engine/tests/test_nginx_site_routes.py b/engine/tests/test_nginx_site_routes.py index c6738b29..26760e83 100644 --- a/engine/tests/test_nginx_site_routes.py +++ b/engine/tests/test_nginx_site_routes.py @@ -167,8 +167,8 @@ def _render_all( ) -> dict[str, str]: """Render each Domain with TLS on and off on both Nginx versions. - Role variables come from the role's defaults unless ``overrides`` names - the Domain's label. + HTTP/2 is on, the shape the golden files hold, unless ``overrides`` + names the Domain's label. """ output = tmp_path / "rendered" output.mkdir() @@ -193,9 +193,7 @@ def _render_all( "cloudfall_nginx_site_acme_webroot": "/var/lib/letsencrypt", "cloudfall_nginx_site_tls_active": tls_active, "cloudfall_nginx_site_version": version, - "cloudfall_nginx_site_http2": _role_default( - "cloudfall_nginx_site_http2" - ), + "cloudfall_nginx_site_http2": True, } | overrides.get(label, {}), } @@ -215,10 +213,16 @@ def rendered(tmp_path_factory: pytest.TempPathFactory) -> dict[str, str]: "nested": _routed_domain(tmp_path, _NESTED_ROUTES), "reversed": _routed_domain(tmp_path, _NESTED_ROUTES_REVERSED), "no-root": _routed_domain(tmp_path, _NO_ROOT_ROUTES), + "role-default": _upstream_only_domain(), "no-http2": _upstream_only_domain(), "no-http2-extra-var": _upstream_only_domain(), }, { + "role-default": { + "cloudfall_nginx_site_http2": _role_default( + "cloudfall_nginx_site_http2" + ) + }, "no-http2": {"cloudfall_nginx_site_http2": False}, # What `--extra-vars cloudfall_nginx_site_http2=false` hands the role. "no-http2-extra-var": {"cloudfall_nginx_site_http2": "false"}, @@ -341,7 +345,7 @@ def test_s003_7_an_upstream_only_domain_renders_byte_identical( @pytest.mark.parametrize("nginx_version", NGINX_VERSIONS) -@pytest.mark.parametrize("label", ["no-http2", "no-http2-extra-var"]) +@pytest.mark.parametrize("label", ["role-default", "no-http2", "no-http2-extra-var"]) def test_http2_off_drops_it_from_the_tls_server_on_every_version( rendered: dict[str, str], label: str, nginx_version: str ) -> None: diff --git a/engine/tests/test_nginx_site_templates.py b/engine/tests/test_nginx_site_templates.py index fb484ec7..4ce7ccf7 100644 --- a/engine/tests/test_nginx_site_templates.py +++ b/engine/tests/test_nginx_site_templates.py @@ -138,11 +138,11 @@ def test_http2_off_renders_no_http2_on_either_side_of_1_25_1( assert "http2" not in rendered -def test_http2_defaults_on_in_the_role_and_its_argument_spec() -> None: +def test_http2_defaults_off_in_the_role_and_its_argument_spec() -> None: role = TEMPLATES.parent defaults = yaml.safe_load((role / "defaults" / "main.yml").read_text("utf-8")) specs = yaml.safe_load((role / "meta" / "argument_specs.yml").read_text("utf-8")) option = specs["argument_specs"]["main"]["options"]["cloudfall_nginx_site_http2"] - assert defaults["cloudfall_nginx_site_http2"] is True - assert option == {"type": "bool", "default": True} + assert defaults["cloudfall_nginx_site_http2"] is False + assert option == {"type": "bool", "default": False}