Learning Gateway API: Building a Website to Master Kubernetes Networking

The Kubernetes ecosystem is constantly evolving, and one of the most significant changes in recent times has been the retirement of Ingress NGINX and the industry's shift toward Gateway API. As someone who needed to stay current with Kubernetes networking, I found myself facing a learning curve that required a more structured approach. This is the story of how I built a dedicated learning website to master Gateway API concepts and why it became one of my most effective learning tools.

The Catalyst: Ingress NGINX Retirement

The announcement of Ingress NGINX's retirement marked a pivotal moment for many Kubernetes practitioners. While Ingress NGINX served the community well, the industry recognized the need for a more standardized, extensible approach to Kubernetes networking. Gateway API emerged as the successor, offering:

• Standardized API: A vendor-neutral specification that works across different implementations
• Better separation of concerns: Clear distinction between infrastructure and application concerns
• Enhanced capabilities: More powerful routing, traffic management, and policy enforcement
• Future-proof design: Built with extensibility and evolution in mind

This transition meant that my existing knowledge of Ingress resources needed to be updated, and I needed a comprehensive understanding of Gateway API's core concepts, resource relationships, and practical implementation patterns.

Why Build a Learning Website?

Traditional learning methods—reading documentation, watching tutorials, or following along with examples—weren't giving me the deep understanding I needed. I realized that to truly internalize Gateway API concepts, I needed to:

1. Create structured content that builds from basics to advanced topics
2. Visualize relationships between Gateway API resources (GatewayClass, Gateway, HTTPRoute, etc.)
3. Compare concepts with familiar Ingress NGINX patterns
4. Provide hands-on examples with working YAML configurations
5. Build a reference I could return to as I implemented Gateway API in production

The act of building the website itself became a learning exercise. By researching, organizing, and presenting Gateway API concepts, I was forced to understand them at a deeper level than passive consumption would allow.

Building the Gateway API Learning Website

The website is built using modern web technologies and is deployed at https://gatewayapilearning.stanho.dev/. The complete source code, including the website, documentation, examples, and setup files, is available in my GitHub repository: https://github.com/TheStanHo/GatewayAPILearning.

Tech Stack

The website is built with a modern, production-ready technology stack designed for performance, maintainability, and excellent developer experience:

Core Framework & Runtime:

• Next.js 16: Latest version with App Router for file-based routing and server components
• React 19: Modern React with latest features and optimizations
• TypeScript 5.4: Full type safety throughout the application for better code quality and developer experience

Styling & UI:

• Tailwind CSS 3.4: Utility-first CSS framework for rapid, responsive design
• @tailwindcss/typography: Enhanced typography for markdown content
• Lucide React: Modern icon library for consistent, beautiful icons

Content Management:

• MDX: Markdown with JSX for rich, interactive content
• next-mdx-remote: Server-side MDX processing for optimal performance
• gray-matter: Frontmatter parsing for metadata extraction
• remark: Powerful markdown processing ecosystem
• remark-gfm: GitHub Flavored Markdown support (tables, task lists, etc.)
• remark-html: HTML rendering for markdown content

Code & Content Features:

• react-syntax-highlighter: Beautiful syntax highlighting for code examples
• js-yaml: YAML parsing for Kubernetes configuration examples
• fuse.js: Fast, fuzzy search implementation for documentation and examples

Development & Quality:

• Jest: Comprehensive testing framework
• React Testing Library: Component testing utilities
• ESLint: Code linting with Next.js configuration
• TypeScript strict mode: Maximum type safety

Deployment:

• Static Export: Optimized for GitHub Pages with static site generation
• Performance Optimizations: Code splitting, image optimization, and bundle size optimization
• SEO Ready: Built-in sitemap and robots.txt generation

This tech stack enables the website to deliver fast, interactive learning experiences with beautiful code examples, smooth navigation, and comprehensive search capabilities—all while maintaining excellent performance and developer experience.

Key Features of the Website

The learning platform includes:

• Structured Learning Paths: Step-by-step tutorials that guide you from introduction to advanced topics, covering all 10 documentation modules

• Visual Diagrams: Traffic flow diagrams showing how requests move through Gateway API resources

• Resource Relationship Maps: Clear visualizations of how GatewayClass, Gateway, and HTTPRoute connect

• Side-by-Side Comparisons: Gateway API examples compared with equivalent Ingress NGINX configurations

• Working Examples: Real YAML configurations organized by topic (basic setup, path routing, header routing, traffic splitting, TLS, filters, advanced scenarios, and migration examples)

• Comprehensive Documentation: Detailed explanations of concepts, from basics to advanced routing and policies

• Quick Setup Guides: Ready-to-use YAML files for getting NGINX Gateway Fabric running in your cluster

• Migration Resources: Step-by-step guides for transitioning from Ingress NGINX to Gateway API

The Cognitive Benefits

Building and using this website revealed something important about how I learn: active creation beats passive consumption. Here's what made the difference:

1. Forced Understanding Through Explanation

When you have to explain a concept to others (even if "others" is your future self), you're forced to understand it deeply. Writing explanations for Gateway API concepts required me to:

• Break down complex ideas into digestible pieces
• Identify the relationships between different resources
• Anticipate questions and confusion points
• Create clear examples that illustrate concepts

2. Visual Learning Reinforcement

The website includes visual diagrams showing:

• Traffic flow from client through Gateway to pods
• Resource hierarchy and relationships
• Comparison between Gateway API and Ingress NGINX patterns

These visuals helped me form mental models that made it easier to recall concepts later.

3. Structured Progression

Unlike jumping between documentation pages or tutorial videos, the repository provides a clear, numbered learning path that builds progressively:

1. Introduction - Understanding what Gateway API is and why it exists
2. Core Concepts - GatewayClass, Gateway, and HTTPRoute fundamentals
3. Basic Routing - Hostname and path matching
4. Advanced Routing - Header, query parameter, and method matching
5. Traffic Splitting - Weighted routing and canary deployments
6. TLS/SSL - Certificate management and TLS configuration
7. Request/Response Modifications - URL rewriting and header modifications
8. Policies - Policy attachments and advanced features
9. Migration Guide - Step-by-step migration from Ingress NGINX
10. Best Practices - Recommendations and production-ready patterns

Each documentation file corresponds to working examples in the Examples/ directory, allowing you to read the concept and immediately see it in practice. This structure prevented the common problem of learning advanced concepts before understanding fundamentals.

4. Reference Material

Having a well-organized reference that I built myself means I know exactly where to find information when I need it. The website serves as both a learning tool and a quick reference guide.

Leveraging AI Tools in the Development Process

Building this website also became an interesting experiment in using AI development tools effectively. I used two complementary approaches:

Cursor for Development

Cursor was instrumental in building the website itself. It helped with:

• Code generation: Creating React components, routing logic, and styling
• Problem solving: Debugging issues and optimizing performance
• Best practices: Ensuring the code followed modern web development standards
• Documentation: Generating code comments and component documentation

Cursor's context-aware assistance meant I could focus on the content and learning structure while it handled much of the boilerplate and implementation details.

ChatGPT Deep Research for Content Validation

After building the website, I used ChatGPT's Deep Research feature to evaluate the information I had published. This served multiple purposes:

1. Accuracy verification: Ensuring the Gateway API concepts were correctly explained
2. Completeness check: Identifying any gaps in coverage or missing important concepts
3. Clarity assessment: Getting feedback on whether explanations were clear and accessible
4. Best practices validation: Confirming that the examples and recommendations aligned with industry standards

This two-tool approach—Cursor for building and ChatGPT Deep Research for validation—created a powerful workflow for creating high-quality educational content.

Future Plans: Practical AKS Deployment

While the website has been excellent for learning concepts, the next step is practical implementation. I'm planning to:

Deploy Gateway API to Azure Kubernetes Service (AKS)

The goal is to deploy real-world examples to AKS, including:

• Basic routing scenarios: Simple HTTPRoute configurations
• Traffic splitting: Canary and blue-green deployment patterns
• TLS termination: Setting up secure connections with certificates
• Advanced policies: Request/response modifications and rate limiting
• Multi-tenant scenarios: Gateway API's excellent support for shared infrastructure

Document Real-World Challenges

As I deploy these examples, I plan to document:

• Common configuration mistakes and how to avoid them
• Performance considerations and optimizations
• Integration with Azure services (Application Gateway, Key Vault, etc.)
• Troubleshooting tips and debugging strategies

These real-world experiences will enhance the learning website with practical, battle-tested knowledge.

Key Takeaways

Building the Gateway API learning website taught me several valuable lessons:

1. Active Learning is More Effective

Creating content forces deeper understanding than consuming it. The process of researching, organizing, and explaining concepts solidifies knowledge in ways that passive learning cannot.

2. Structure Matters

A well-organized learning path prevents confusion and builds knowledge progressively. Starting with fundamentals before moving to advanced topics creates a solid foundation.

3. Visual Aids Enhance Understanding

Diagrams and visualizations help form mental models that make concepts easier to recall and apply.

4. AI Tools Can Accelerate Learning

When used thoughtfully, AI development tools like Cursor and ChatGPT Deep Research can significantly accelerate both the creation of learning materials and the validation of their accuracy.

5. Practical Application is Essential

While theoretical understanding is important, real-world deployment is where true mastery develops. The combination of learning resources and hands-on practice creates comprehensive expertise.

Conclusion

The transition from Ingress NGINX to Gateway API represents more than just a technology change—it's an evolution toward better standards, clearer abstractions, and more powerful capabilities. By building a dedicated learning website, I not only created a resource for myself and others but also discovered a highly effective learning methodology.

The website at https://gatewayapilearning.stanho.dev/ continues to evolve as I learn more about Gateway API and implement it in real-world scenarios. The upcoming AKS deployments will provide practical experience that will further enhance both my understanding and the website's content.

If you're also navigating the transition to Gateway API, I encourage you to explore the website and consider building your own learning resources. The process of creating educational content is itself one of the most effective ways to master new technologies.

---

Ready to dive into Gateway API? Visit https://gatewayapilearning.stanho.dev/ to start your learning journey, or check out the official Gateway API documentation for the latest specifications.