document h2c_upstream k8s ingress annotation

[wasaga]

Summary

Documents the new ingress.pomerium.io/h2c_upstream Ingress annotation introduced in pomerium/ingress-controller#1516.

• Adds an h2c_upstream row to the Ingress annotations reference table.
• Adds an HTTP/2 Cleartext Upstreams section under Services, next to the existing Upstream mutual TLS section, linking to the h2c:// scheme docs in the route to reference.
• Notes that h2c_upstream cannot be combined with secure_upstream (or the ssh/tcp/udp upstream annotations).

Related

• Code change: ingress: add h2c_upstream annotation ingress-controller#1516

[netlify]

✅ Deploy Preview for pomerium-docs ready!

Name	Link
🔨 Latest commit	58b7472
🔍 Latest deploy log	https://app.netlify.com/projects/pomerium-docs/deploys/6aa15cd22bfb3a00083bce43
😎 Deploy Preview	https://deploy-preview-2361--pomerium-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[greptile-apps]

Greptile Summary

This PR documents the new Kubernetes Ingress annotation for cleartext HTTP/2 upstream connections.

• Adds ingress.pomerium.io/h2c_upstream to the annotation reference.
• Adds configuration guidance for insecure HTTP/2 and gRPC services.
• Documents mutually exclusive upstream-mode annotations, although the table provides an incomplete version of that constraint.

Confidence Score: 4/5

The documentation is safe to merge after a non-blocking consistency fix to list every incompatible upstream annotation in the reference row.

The new section and links are sound, but the annotation table incompletely summarizes the controller constraint and can mislead readers who use it as a standalone reference.

Files Needing Attention: content/docs/deploy/k8s/ingress.md

Important Files Changed

Filename	Overview
content/docs/deploy/k8s/ingress.md	Adds the h2c annotation reference and usage guidance; the reference row omits three conflicts documented later on the same page.

_{Reviews (1): Last reviewed commit: "document h2c_upstream k8s ingress annota..." | Re-trigger Greptile}

[greptile-apps]

Incomplete incompatibility list

The annotation reference says h2c_upstream cannot be combined only with secure_upstream, while the detailed section also lists ssh_upstream, tcp_upstream, and udp_upstream. Someone relying on the table can therefore configure a combination that the documented controller behavior rejects instead of creating the route.

This red test demonstrates the incomplete table entry:

import assert from 'node:assert/strict';
import fs from 'node:fs';
import test from 'node:test';

test('h2c annotation row lists every incompatible upstream mode', () => {
  const markdown = fs.readFileSync('content/docs/deploy/k8s/ingress.md', 'utf8');
  const row = markdown
    .split('\n')
    .find((line) => line.startsWith('| `ingress.pomerium.io/h2c_upstream`'));

  for (const annotation of [
    'secure_upstream',
    'ssh_upstream',
    'tcp_upstream',
    'udp_upstream',
  ]) {
    assert.match(row, new RegExp(`\\`${annotation}\\``));
  }
});

It fails on the current row at the ssh_upstream assertion, while the detailed section establishes that all four annotations are incompatible.

Suggested change

	| `ingress.pomerium.io/h2c_upstream` | When set to `"true"`, use cleartext HTTP/2 (`h2c`) when connecting to the upstream endpoint. See the [example below](#http2-cleartext-upstreams) for more information. Cannot be combined with `secure_upstream`. |
	| `ingress.pomerium.io/h2c_upstream` | When set to `"true"`, use cleartext HTTP/2 (`h2c`) when connecting to the upstream endpoint. See the [example below](#http2-cleartext-upstreams) for more information. Cannot be combined with `secure_upstream`, `ssh_upstream`, `tcp_upstream`, or `udp_upstream`. |