Skip to content

Add HTTP header size guideline to production deployment checklist #11601

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dushaniw wants to merge 1 commit into
base: master
Choose a base branch
from
+25 −2
Open

Add HTTP header size guideline to production deployment checklist #11601

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 25 additions & 2 deletions ...l-and-setup/setup/deployment-best-practices/production-deployment-guidelines.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,17 +119,40 @@ Given below is a checklist that will guide you to set up your production environ
</td>
</tr>
<tr class="odd">
<td>HTTP header size</td>
<td>
<div class="content-wrapper">
<p>The default value of <code>maxHttpHeaderSize</code> on both the HTTP and HTTPS connectors in <code>&lt;APIM_HOME&gt;/repository/conf/tomcat/catalina-server.xml</code> is set to <strong>32 KB (32768 bytes)</strong>.</p>
<p>This value <strong>must not be set to less than 32 KB (32768 bytes)</strong>, specifically on the <strong>API Control Plane (ACP) node</strong> in a distributed deployment (or on the single node in an all-in-one deployment), if <strong>Multi-Option Authentication</strong> is used for portal (Publisher, DevPortal, Admin) logins in federated authentication flows.</p>
Comment on lines +125 to +126
<p>If set lower, the <code>/commonauth</code> redirect from the external Identity Provider carries the full OAuth scope list in the request URI, and the combined size of the request line and headers exceeds the buffer. Tomcat then rejects the request with a <code>400 Bad Request</code> or <code>414 Request-URI Too Long</code> error, breaking the federated login flow.</p>
<p>If you need to override the value via <code>deployment.toml</code>, keep it at or above the default:</p>
<div class="code panel pdl" style="border-width: 1px;">
<div class="codeContent panelContent pdl">
<div class="sourceCode" id="cb2" data-syntaxhighlighter-params="brush: text; gutter: false; theme: Confluence" data-theme="Confluence" style="brush: text; gutter: false; theme: Confluence">
<pre class="sourceCode text"><code class="sourceCode text">[transport.http.properties]
maxHttpHeaderSize = 32768

[transport.https.properties]
maxHttpHeaderSize = 32768</code></pre>
</div>
</div>
</div>
<p>If a reverse proxy, load balancer, ingress controller, or CDN is deployed in front of APIM, ensure its header and URL size limits are also aligned to at least 32 KB — otherwise the request will be rejected at the front tier before it reaches APIM.</p>
Comment on lines +122 to +140

@coderabbitai coderabbitai Bot Jul 10, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '\n== Relevant files ==\n'
git ls-files \
  'en/docs/install-and-setup/setup/deployment-best-practices/production-deployment-guidelines.md' \
  'en/tools/config-catalog-generator/data/_http-transport.toml' \
  'en/tools/config-catalog-generator/data/_https-transport.toml' \
  'en/tools/config-catalog-generator/data/*transport*.toml' \
  'en/tools/config-catalog-generator/data/*toml' | sort

printf '\n== Document excerpt ==\n'
sed -n '118,145p' en/docs/install-and-setup/setup/deployment-best-practices/production-deployment-guidelines.md

printf '\n== Template defaults ==\n'
for f in en/tools/config-catalog-generator/data/_http-transport.toml en/tools/config-catalog-generator/data/_https-transport.toml; do
  echo "--- $f"
  rg -n 'maxHttpHeaderSize|default|32768|8192' "$f" || true
done

printf '\n== Search for other mentions ==\n'
rg -n 'maxHttpHeaderSize|32768|8192|HTTP header size|header size' \
  en/docs \
  en/tools/config-catalog-generator/data \
  . \
  -g '!**/node_modules/**' \
  -g '!**/dist/**' \
  -g '!**/build/**' || true

Repository: wso2/docs-apim

Length of output: 50371

Align the documented default with the generated config defaults.

maxHttpHeaderSize is documented here as 32768, but the transport templates and config catalog still default it to 8192. Update both sources together, or narrow this note to the release where the default changes.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In
`@en/docs/install-and-setup/setup/deployment-best-practices/production-deployment-guidelines.md`
around lines 122 - 140, Align the maxHttpHeaderSize default consistently: update
the transport templates and config catalog from 8192 to 32768, matching the
documentation and generated configuration, or revise the documentation to apply
only to the release that changes the default. Locate the relevant
maxHttpHeaderSize entries in the transport configuration templates and config
catalog and update them together.

</div>
</td>
</tr>
<tr class="even">
<td>High availability</td>
<td>
<p>Configure your deployment with high availability. Refer the <a href="{{base_path}}/install-and-setup/setup/deployment-overview">recommended deployment patterns</a> and select an option that fits your requirements.</p>
<p>In the cloud native deployment, high availability should be achieved via the container orchestration system (Kubernetes).</p>
</td>
</tr>
<tr class="even">
<tr class="odd">
<td>Data backup and archiving</td>
<td>Implement a <a href="{{base_path}}/install-and-setup/setup/deployment-best-practices/backup-recovery">backup and recovery strategy</a> for your system.</td>
</tr>
<tr class="odd">
<tr class="even">
<td>Encryption Key</td>
<td>
<p>Generate a symmetric encryption key and add it to the <code>deployment.toml</code> file. See <a href="{{base_path}}/install-and-setup/setup/security/encryption/symmetric-encryption/#generate-a-secret-key">Configuring Encryption Key</a> for instructions.</p>
Expand Down