Repository navigation
docs(temporal-proxy): update for v1.2.0 - #5719
Open
pseudomuto wants to merge 3 commits into
Open
pseudomuto wants to merge 3 commits into
pseudomuto wants to merge 3 commits into
Conversation
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 latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
📖 Docs PR preview links
|
Contributor
There was a problem hiding this comment.
🟡 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
Add compression to the configuration overview · New Clarify proxy compression cannot bypass the gateway request-size limit · New Clarify that the ratio measures algorithm output, not actual savings · New Label the histogram as elapsed operation time, not CPU time · New Account for mTLS when recommending HTTPS health probes · New Limit the pass-through guarantee to outbound Payloads · New
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
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
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
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.

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
compressionblock, per-Namespace overrides, ordering with encryption, and its metrics.--require-encryptionand the chart'srequireEncryption.scheme: nonefor bare-token auth headers such as IAP./healthzroute.