Skip to content

docs(temporal-proxy): update for v1.2.0 - #5719

Open
pseudomuto wants to merge 3 commits into
mainfrom
docs/temporal-proxy-1.2.0
Open

pseudomuto wants to merge 3 commits into
mainfrom
docs/temporal-proxy-1.2.0

Conversation

@pseudomuto

Copy link
Copy Markdown
Contributor

The proxy docs were last synced to v0.10.0, so they missed everything that shipped in v1.1.0 through v1.2.0. Verified against the v1.2.0 source rather than the release notes.

Highlights

  • Add a Compress payloads page covering the new compression block, per-Namespace overrides, ordering with encryption, and its metrics.
  • Document --require-encryption and the chart's requireEncryption.
  • Document scheme: none for bare-token auth headers such as IAP.
  • Document TLS certificate hot reload and its expiry/reload metrics.
  • Document the HTTP listener's unauthenticated /healthz route.
  • Correct Cloud Search Attribute translation, which now includes the built-in attributes, and allow name fragments in Cloud suffixes.
  • Align the support policy with the upstream README: critical fixes go to the current minor and the two before it.
  • Add version notes for each change.

The proxy docs were last synced to v0.10.0, so they missed everything
that shipped in v1.1.0 through v1.2.0. Verified against the v1.2.0
source rather than the release notes.

**Highlights**

- Add a Compress payloads page covering the new `compression` block,
  per-Namespace overrides, ordering with encryption, and its metrics.
- Document `--require-encryption` and the chart's `requireEncryption`.
- Document `scheme: none` for bare-token auth headers such as IAP.
- Document TLS certificate hot reload and its expiry/reload metrics.
- Document the HTTP listener's unauthenticated `/healthz` route.
- Correct Cloud Search Attribute translation, which now includes the
  built-in attributes, and allow name fragments in Cloud suffixes.
- Align the support policy with the upstream README: critical fixes go
  to the current minor and the two before it.
- Add version notes for each change.
@vercel

vercel Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
temporal-documentation Ready Ready Preview Nov 18, 2026 11:11pm UTC

Request Review

@pseudomuto
pseudomuto marked this pull request as ready for review November 13, 2026 18:13
@pseudomuto
pseudomuto requested a review from a team as a code owner November 13, 2026 18:13
Copilot AI balanced review requested due to automatic review settings November 13, 2026 18:13
@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Unresolved documentation issues misrepresent compression behavior, metrics, and request limits, give incorrect mTLS health-probe guidance, and omit compression from the configuration overview.

6 open issues
What changed in this PR

Updates the Temporal Proxy documentation for v1.2.0, adding payload compression guidance and documenting recent security, health-check, and compatibility changes.

Changes:

  • Add compression configuration, rollout guidance, metrics, and navigation.
  • Document encryption requirements, bare-token authentication, certificate hot reload, and HTTP health checks.
  • Update Cloud translation behavior, observability, and version support policy.
File Description
sidebars.js Adds the compression page to navigation.
docs/​production-deployment/​temporal-proxy/​index.mdx Updates the overview, flags, metrics, and support policy.
docs/​production-deployment/​temporal-proxy/​encrypt-payloads.mdx Documents encryption requirements and compression interactions.
docs/​production-deployment/​temporal-proxy/​deploy-kubernetes.mdx Adds certificate rotation and HTTP probe guidance.
docs/​production-deployment/​temporal-proxy/​configure.mdx Updates Cloud translation, authentication, and TLS configuration guidance.
docs/​production-deployment/​temporal-proxy/​compress-payloads.mdx Introduces compression configuration, behavior, and monitoring.
docs/​production-deployment/​temporal-proxy/​codec-server.mdx Documents /healthz and compression metrics.

Review effort: Balanced

</ReleaseNoteHeader>

The proxy can compress Payloads before forwarding them to an upstream and restore them on the way back, set under the
top-level `compression` block. It is off by default. Like [encryption](/production-deployment/temporal-proxy/encrypt-payloads),
Comment on lines +28 to +30
Compression reduces the bandwidth to the upstream and the size of the data stored in Event History. Because the
Temporal Service sees the compressed bytes, it can also bring large Payloads, or requests that carry many of them, back
under the [Payload and gRPC message size limits](/troubleshooting/blob-size-limit-error).
Comment on lines +153 to +163
`payload_bytes` includes Payloads that came out no smaller and were forwarded uncompressed, so the ratio of its two
stages is what compression actually saves. With the default metric prefix, the ratio for each Namespace is:

```promql
sum by (namespace) (rate(tmprl_proxy_compression_payload_bytes_sum{stage="pre_compress"}[5m]))
/
sum by (namespace) (rate(tmprl_proxy_compression_payload_bytes_sum{stage="post_compress"}[5m]))
```

A ratio of 2 means compressed Payloads are half their original size. The `namespace` label reports a value only when
`metrics.labels.namespace` is on.
A ratio of 2 means compressed Payloads are half their original size. The `namespace` label reports a value only when
`metrics.labels.namespace` is on.

To see how much CPU compression uses, sum `ops_duration_seconds`, which reads as the number of cores busy compressing:
Comment on lines +154 to +155
[`/healthz`](/production-deployment/temporal-proxy/codec-server#http-health-check) route, which needs no credential.
Beyond loopback the listener serves TLS, so set `scheme: HTTPS` on an `httpGet` check.
The proxy reads only the Namespace and the fields it translates, so it needs no knowledge of your Data Converter or
codec, and payload data passes through untouched unless encryption is configured. The gateway accepts gzip-compressed
requests, so a Client with gRPC compression turned on works through it.
codec. Payload data passes through untouched unless you configure encryption or compression. Payload compression is
@Duncanma
Duncanma enabled auto-merge (squash) November 18, 2026 22:35
- Limit the compression size-limit claim to the Payload limit; the proxy's
  4 MiB receive limit applies before compression runs.
- Describe payload_bytes as the algorithm's ratio and ops_duration_seconds
  as elapsed time, matching what the code records.
- Note that an httpGet probe can't pass an mTLS listener's /healthz check.
- Qualify the pass-through statement: compressed Payloads are always restored.
- Add compression to the configure overview, blob-size remedies, and the
  sizing test checklist.
- v1.2.1: document decompression limits and compression.maxDecodedInFlight,
  the literal-domain rule for templated hosts, and the 100-value cap on
  metadata metric labels.

This branch was successfully deployed

1 active deployment
Preview — 8f557568 Deployed Nov 18, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants