DEV Community: Michael Uzukwu

Why Early Request Header Modification Matters in API Gateways

Michael Uzukwu — Wed, 21 Jan 2026 13:42:53 +0000

When people think about API gateway security, they often focus on authentication, rate limiting, or Transport Layer Security (TLS). Headers are usually treated as minor details, often like metadata attached to a request.

But in practice, headers are often the inputs that drive routing, identity, and policy decisions.

During my recent documentation work on the kgateway project, I spent time documenting and understanding the early request header modification feature. The more I worked and documented, the clearer it became that this isn’t just a “nice-to-have” feature, but a foundational pattern for building secure and predictable API gateways.

This article is based on that real contribution, and it’s written for developers and platform engineers working in cloud-native systems who want to apply the same idea, whether they use kgateway or not.

The Real Problem: Trusting Client-Supplied Headers

Let’s start with a realistic scenario. A client sends a request like this:

GET /orders HTTP/1.1
Host: api.example.com
x-user-id: 12345
x-tenant: premium
x-auth-source: internal

If your gateway or downstream services rely on headers like x-user-id, x-tenant, or x-auth-source, you already have a problem:

Clients can forge headers
Routing logic may make decisions based on untrusted input
Authorization policies may be evaluated with faked identity data

Many API gateways allow header modification but often only after route selection.
By then, the request may already have:

Matched the wrong route
Triggered the wrong policy
Been forwarded to the wrong backend

That’s too late.

Why “Early” Header Modification Exists

Early request header modification means sanitizing headers before routing and policy evaluation happen.

Conceptually, the flow looks like this:

Client Request
  (untrusted headers)
        ↓
Early Header Modification
  - Remove unsafe headers
  - Inject trusted metadata
        ↓
Route Selection
        ↓
Policy Evaluation
        ↓
Upstream Services

This guarantees that:

Routing logic only sees clean, trusted headers
Policies behave consistently
Downstream services don’t need to guess what’s safe to trust

Think of it like security screening at an airport: you don’t wait until someone boards the plane to remove dangerous items.

A Real-World Example

The Goal

Prevent clients from spoofing identity headers
Ensure routing and policies rely only on gateway-controlled metadata

Early Header Modification (Conceptual)

earlyHeaderModifier:
  remove:
    - x-user-id
    - x-tenant
    - x-auth-source
  add:
    - name: x-auth-source
      value: gateway

What this achieves:

Client-supplied identity headers are stripped immediately
A trusted header is injected by the gateway
All routing and policies downstream see predictable input

Downstream services can now safely assume:

“If this header exists, it came from the gateway — not the client.”

Why Timing Is the Critical Detail

Modification Type	When It Runs	Risk
Standard header modification	After route selection	Client headers may already influence routing
Early header modification	Before route selection	Only trusted headers affect routing & policies

This timing difference is subtle, but it’s the difference between:

Defensive design
And accidental trust in user input

How This Is Implemented in kgateway

In kgateway, early request header modification is implemented using the HTTPListenerPolicy API.

This allows header sanitization to occur before routing, which is especially important for:

Multi-tenant routing
Policy-driven architectures
Zero-trust gateway setups

I recently documented this behavior as part of a contribution to the kgateway docs, including:

When the feature runs
How it differs from standard header modifiers
How to configure it safely

📘 Official Guide

Early Request Header Modification (kgateway)

Applying the Pattern Beyond kgateway

Even if you’re not using kgateway, the pattern applies broadly:

Never trust client-supplied headers
Sanitize before routing, not after
Inject trusted metadata at the gateway boundary
Make policies deterministic by design

This approach works whether you’re using:

Envoy-based gateways
Kubernetes ingress controllers
Service mesh edge proxies
Custom gateway layers

The idea is universal, only the configuration syntax changes.

Why Documentation Matters Here

This is one of those features that’s easy to misuse if it’s not documented clearly.Without good documentation, users may:

Modify headers too late
Assume headers are safe when they’re not
Miss the feature entirely

Clear docs help users understand not just how to configure something, but why it exists in the first place. That’s what motivated my contribution and this article.

Final Thoughts

API gateway security isn’t only about auth tokens and firewalls.

Sometimes, it’s the small architectural details - like when a header is modified that determines whether your system is safe or fragile.

Early request header modification prevents problems before they happen.

If you design, operate, or document cloud-native systems, it’s a pattern worth understanding deeply.

How I Added Glossary Tooltip Hover to Kgateway Docs (Using Hugo Shortcodes)

Michael Uzukwu — Thu, 11 Dec 2025 13:12:08 +0000

When I joined the Kgateway documentation team as a Technical Writer and contributor, one pattern kept repeating during reviews and user feedback:

Readers were constantly getting stuck on core terms.

Kgateway touches so many different domains:

Kubernetes
Envoy
Service Mesh
AI / Agentic patterns
Kgateway-specific architecture

So concepts like Clusters (Envoy), Backends, A2A, Ambient Mesh, or Data Plane appear everywhere.

But new readers often had to leave the page just to understand what these terms meant.

Not good for learning flow.

So I decided to solve it the way modern docs teams do (think Stripe, Datadog, GitHub):

I implemented a reusable glossary tooltip hover system using Hugo shortcodes.

It ended up improving clarity, reducing confusion, and making the docs feel far more polished.

In this article, I’ll walk through:

Why this feature matters
Where to place (and not place) tooltips
The exact files I built (gloss.html, YAML store, and CSS)
Screenshots
Lessons learned as a documentation contributor

Why Glossary Tooltips Matter (Especially in Technical Documentation)

Tooltips look like a small UI detail, but they significantly improve the reading experience.

Here’s why:

1. Faster learning, fewer context switches

Readers shouldn’t need to open three tabs just to understand a sentence.

A simple hover = instant definition.

2. Helps unify mixed terminology

Kgateway mixes:

Kubernetes CRDs
Envoy concepts
Agentic AI terms
Mesh networking terminology
Kgateway-specific keywords

A central glossary helps create consistency.

3. Cleaner, more readable pages

Instead of repeating definitions everywhere, a tooltip keeps things neat.

4. One source of truth (via YAML)

Whenever a definition changes, update it once → it updates everywhere.

But There’s a Catch: Don’t Overuse Tooltips

While building this feature, the docs maintainer and I agreed on one rule:

Do NOT apply tooltips on every instance of a term.

Too many hover effects distract readers, especially on dense technical pages.

So we adopted a strategic placement model👇

Where to Place Tooltips (and Where Not To)

Use tooltips in these places:

Location	Why
Where a term is first introduced	Helps readers build initial understanding
Overview or conceptual pages	These pages often introduce many new ideas
Pages discussing a concept heavily	Add tooltips once or twice only
Glossary page	Optional, but helpful

Avoid tooltips in:

Every repeated occurrence
Tables with long text
Code blocks
Headings (breaks formatting)

This keeps the UI clean and professional.

How I Implemented Glossary Tooltips (Hugo Shortcodes + YAML + CSS)

This is the entire structure I added to the Kgateway docs.

1. YAML Glossary Data Store

File: /data/glossary.yaml

A2A:
  short: "Agent-to-Agent Protocol — secure, policy-driven communication between sidecarless agents."

Agentgateway:
  short: "An open-source data plane optimized for agentic AI connectivity."

Cluster (Envoy):
  short: "Envoy 'cluster' — a logical grouping of upstream endpoints used for load balancing."

Backends:
  short: "Destination services or endpoints Kgateway routes traffic to (Kubernetes services, Lambdas, external hosts)."

This acts like a central mini-database for terms. We ended up storing 30+ key concepts.

2. Hugo Tooltip Shortcode

File: layouts/shortcodes/gloss.html

{{ $key := .Get 0 }}
{{ $entry := index site.Data.glossary $key }}

{{ if $entry }}
<span class="glossary-term" tabindex="0" data-glossary-term="{{ $key }}">
  {{ .Inner | default $key }}
  <span class="tooltip-content">
    <strong>{{ $key }}</strong>
    <span>{{ $entry.short }}</span>
    {{ if $entry.link }}
    <a href="{{ $entry.link }}" class="tooltip-link" target="_blank">
      Learn more
    </a>
    {{ end }}
  </span>
</span>
{{ else }}
{{ .Inner | default $key }}
{{ end }}

Usage in Markdown:
The translation cycle starts by defining {{< gloss "Cluster (Envoy)" >}}Envoy clusters{{< /gloss >}}...

Fig 1: Tooltip Hover Definition for 'Control Plane' in the Concept Architecture page

3. Tooltip Styling (CSS)

File: static/css/glossary.css

.glossary-term {
  position: relative;
  cursor: help;
  border-bottom: 1px dotted #666;
}

.glossary-term > span {
  visibility: hidden;
  opacity: 0;
  width: 280px;
  padding: 12px;
  background: #fff;
  border-radius: 6px;
  position: absolute;
  bottom: 125%;
  left: 50%;
  transform: translateX(-50%);
  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
  transition: opacity .3s;
}

.glossary-term:hover > span,
.glossary-term:focus > span {
  visibility: visible;
  opacity: 1;
}

Accessible, responsive, and subtle.

4. The Glossary Page

We also created a full glossary.md page, which:

improves SEO
collects all terms in one place
creates a complete reference index

Final Thoughts

Glossary hover tooltips may look small, but they make your docs:

easier to read
friendlier to beginners
more consistent
more modern

And in my experience contributing to Kgateway docs, this little feature created a big difference in user experience.

If you're building technical documentation on Hugo or not, I highly recommend adding it.

Thanks for reading!
Feel free to ask if you want a reusable template or module version. Meanwhile here's a link my merged Pull Request for this task: Tooltip Hover feature

A Beginner-Friendly Guide to Docs as Code & CI/CD Pipelines

Michael Uzukwu — Fri, 08 Aug 2025 22:17:22 +0000

In today's software world, documentation is no longer a side task—it’s a core part of the development lifecycle. If you've heard terms like “Docs as Code” and “CI/CD pipelines”, but they sound intimidating or too advanced, this guide is for you.

Whether you’re a technical writer, developer, or contributor to an open-source project, you'll learn how to automate documentation deployment using a static site generator and GitHub Actions. No complex DevOps background needed.

What Is “Docs as Code”?

Docs as Code is a modern approach that treats documentation just like source code. Instead of writing docs in Google Docs or Word, you write them in Markdown, version them in Git, and manage them in the same repository as the project.

This approach allows:

Team collaboration through version control (like Git)
Code reviews and pull requests for documentation
Automated building and deployment (CI/CD)
Reuse of developer tools for docs workflows

CI/CD Pipeline

CI/CD stands for Continuous Integration and Continuous Deployment. It means:

CI: Automatically checking your code or docs when you push changes (e.g., spellcheck, linting, tests).
CD: Automatically building and deploying your site to the web without manual steps.

In this article, we’ll use GitHub’s Actions feature to run our CI/CD pipeline whenever we push to the main branch.

Why This Guide Matters

While some static site generators (SSGs) like Astro Starlight or Next.js do offer native/auto-deployment especially on platforms like Vercel, Netlify, etc, others like MkDocs, Hugo, and Docusaurus don't—especially when using GitHub Pages for hosting.

To solve this gap, we’ll create our own automated workflow using:

MkDocs (a Python-based static site generator)
GitHub Actions (for automation)
GitHub Pages (for free hosting)

By the end, you’ll have a workflow where your documentation deploys automatically each time you push changes.

Benefits of This Setup

Zero cost: Everything uses free GitHub features.
Automation: No need to deploy manually.
Versioned and traceable: Every change is recorded in Git.
Lightweight: Minimal setup needed for personal or team docs.

Prerequisites

Before starting, you should have:

A GitHub account and repository set up
Basic knowledge of Markdown and Git
Python installed locally
MkDocs installed (pip install mkdocs mkdocs-material)

Project Recap: What We Deployed

For this demo, we built and deployed a simple Vue.js documentation site using MkDocs and hosted it at:
👉 demo site
It currently includes:

A custom homepage
Introduction page
Quick Start guide

Step-by-Step: Set Up CI/CD for MkDocs with GitHub Pages

Here’s how we set up the pipeline:

Understand the Flow When you push changes to your main branch, GitHub Actions will:
Detect the change (triggered by the on: push event in deploy.yml).

Checkout your repo code into the workflow environment.
Set up Python (since MkDocs is Python-based).
Install MkDocs and the Material theme.
Build the documentation into static HTML.
Deploy it to the gh-pages branch, which GitHub Pages serves as your live site.

Project Folder Structure Your folder should look like this:

vue.js-mkdocs-demo/
├── docs/
│   ├── index.md
│   ├── introduction.md
│   └── quick-start.md
├── mkdocs.yml
├── .github/
│   └── workflows/
│       └── deploy.yml

Create a deploy.yml Workflow File Inside .github/workflows/, create a file named deploy.yml and include your script similar to this:

name: Deploy MkDocs Site

on:
  push:
    branches:
      - main  # deploy when pushing to main

permissions:
  contents: write  # needed to push to gh-pages branch

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repo
        uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.10'

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install mkdocs mkdocs-material

      - name: Build and deploy
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: mkdocs gh-deploy --force --remote-name origin

Fig1: Code syntax showing the 'deploy.yml' file setup for the CI/CD Pipeline

This pipeline:

Runs when you push to the main branch
Installs Python and MkDocs
Builds your docs
Deploys them to GitHub Pages

Push and Watch the Pipeline Run Once you’ve created the file:

git add .github/workflows/deploy.yml
git commit -m "Add MkDocs deployment workflow"
git push origin main

Go to the Actions tab in your GitHub repo.
You should see the “Deploy MkDocs Site” workflow running.
Click into it to watch each step (checkout, setup, install, build, deploy).
All steps should turn green ✅ when successful.

Fig2: Set up Configurations for Github Pages

Fig4: Github Actions Flow Showing Successful deployment.

View Your Live Documentation Once the workflow finishes, your site will be live at:

https://<your-username>.github.io/<repo-name>/

Fig5: Live Site of deployed Vue.js docs built with Mkdocs

Wrapping Up

This guide proves that documentation automation isn’t just for large dev teams—it’s beginner-friendly and accessible. By using Docs as Code practices with GitHub Actions and MkDocs, you ensure your docs stay live, versioned, and up-to-date with zero manual deployment effort.

Treating docs like code saves time, builds consistency, and improves collaboration. If you're new to CI/CD or static site generators, this hands-on tutorial is a solid start.

[Live Site](https://mike-4-prog.github.io/vue.js-mkdocs-demo/)
[Github Repo](https://github.com/Mike-4-prog/vue.js-mkdocs-demo)

From Code to Live in Minutes: Deploying My Astro Starlight Static Site on Vercel.

Michael Uzukwu — Tue, 08 Jul 2025 21:53:49 +0000

When I set out to recreate the Vue.js documentation using Astro Starlight a month ago, I had two main goals — keep it static, and make it accessible online with minimal setup.

At first, I figured GitHub Pages would do the trick — but I ran into a few headaches pretty quickly. Then I made the switch to Vercel, and it turned out to be one of the best decisions for this project.

In this post, I’ll walk you through how I deployed my Astro-powered documentation site using Vercel, and why it’s now my preferred tool for static site hosting.

Why Vercel for Static Sites?

So, what made me go with Vercel? Here’s what really convinced me before I even got to the setup:

Instant GitHub integration – Deploy right from your repository with no CLI fuss.
Global CDN out of the box – Blazing-fast performance for static assets.
Custom domain support – Easy setup and automatic HTTPS
Automatic deploy previews – See what each branch or PR looks like live.
Zero-config setup – Frameworks like Astro are detected automatically.
Free tier available – Ideal for personal projects and experimentation.

Project Context: Rebuilding Vue.js Docs with Astro Starlight

As part of Product Documentation Cohort-1 of the Technical Writing Mentorship Program (TWMP), I recreated the Vue.js documentation using Astro Starlight — a lightweight static site generator that focuses on performance, markdown-based content, and great developer experience.

The idea was to restructure and improve the official Vue.js docs — but powered by Astro.

Since the content was static, with no backend or dynamic data, this made it perfect for static deployment — no server needed, just HTML, CSS, and JavaScript.

Step-by-Step: Deploying an Astro Site on Vercel

Prerequisites

Make sure you have:

A GitHub account with your static site code pushed to a repo.

Figure 1: Ensure your static site code (like this Vue.js repo) is pushed to GitHub before importing it into Vercel.

A Vercel account (you can sign up with GitHub for seamless integration).

1. Import Your Project into Vercel

Figure 2: Vercel automatically detects Astro as the framework and applies default build and output settings.

Go to vercel.com/dashboard
Click “Add New Project”
Select your GitHub repository (Vercel may ask for GitHub access the first time).

Vercel will auto-detect Astro as the framework and pre-fill the build command (astro build) and output directory (dist).

2. Configure the Settings

You can usually go with the defaults:

Framework: Astro  
Build command: astro build  
Output directory: dist

3. Deploy

Click the “Deploy” button.

Vercel will:

Clone your repo
Install dependencies
Build the project
Host the dist/ output on its CDN

After a minute or so, you’ll get a unique .vercel.app URL to view your live site.

Figure 3: Vercel deployment success screen. Once the build completes, your site is live on a unique .vercel.app URL.

Setting Up a Custom Domain (Optional but Awesome)

If you want a branded URL:

In the project dashboard, go to the Domains tab
Click “Add” to connect your custom domain
Update your domain’s DNS to point to Vercel’s servers

HTTPS is auto-enabled with Let’s Encrypt — no extra setup needed.

Figure 4: A quick look at the domain setup screen on Vercel.

Why I Switched from GitHub Pages to Vercel

GitHub Pages is great for simple projects, but I ran into issues like:

Having to manually build and push the dist/ folder to a gh-pages branch
Problems with routing (e.g., missing _redirects support)
Extra configuration for Astro and Starlight projects

With Vercel, all that friction disappeared.

Tips & Best Practices

Add .vercel/ to your .gitignore
Use Vercel’s dashboard to securely manage environment variables
Enable analytics (available on paid plans)
👥 Working in a team? Preview deployments make collaboration smooth and safe.

Conclusion

Deploying with Vercel made the process incredibly smooth. From GitHub integration to instant deployment and live previews, it handled everything I needed for a modern static site — no DevOps headaches.

Whether you’re building documentation, blogs, or full sites using Astro, Next.js, or even plain HTML — Vercel is a solid choice.

🔗 Want to see the live site? Check it out here: https://vue-js-nine-rouge.vercel.app/

💻 Project repository:

https://github.com/Mike-4-prog/vue.js

(Note: The documentation is still a work in progress, with more pages and improvements coming soon!)

Have you tried deploying with Vercel? Got stuck with GitHub Pages too?

💬 Feel free to drop your questions or share your experience in the comments!