Kong Ingress Controller

Kong-Ingress-Controller in Cloud-Native Engineering

Category: kubernetes
Status: Active
Stars: 2,380
Last Updated: 2026-04-20
Primary Language: Go
Documentation: https://github.com/Kong/kubernetes-ingress-controller

Purpose and Use Cases

Kong-Ingress-Controller is a cloud-native project that provides kubernetes functionality for modern distributed systems.

What Problem Does It Solve?

Kong-Ingress-Controller addresses the challenges of kubernetes in cloud-native environments, enabling teams to implement kubernetes features without embedding them in application code.

When to Use This Project

Use kong-ingress-controller when you need kubernetes capabilities in your Kubernetes or cloud-native infrastructure. It's ideal when you require kubernetes with minimal application code changes.

Key Use Cases

• kubernetes for microservices
• Integration with Kubernetes and CNCF ecosystem
• kubernetes with declarative configuration
• kubernetes for observability and monitoring
• kubernetes for security and compliance

Architecture Design Patterns

Core Components

• Primary Component: Core functionality
• Controller: Cluster management
• Agent: Node-level execution
• API Server: Management interface
• Storage: Configuration persistence

Component Interactions

1. Client → Core: Request routing
2. Core → Storage: Configuration persistence
3. Controller → Agents: Command distribution
4. Agents → Controller: Status reporting
5. Storage → Controllers: Configuration sync

Data Flow Patterns

1. Request Flow: Client → Core → Backend
2. Configuration Flow: API → Storage → Nodes
3. State Flow: Nodes → Control Plane → Dashboard
4. Telemetry Flow: Data → Collector → Storage

Design Principles

• Declarative Configuration: YAML/CRD-based configuration
• Kubernetes-Native: Leverages Kubernetes APIs
• Extensible: Plugin/adapter architecture
• Observability First: Built-in metrics, tracing, logging
• High Availability: Multi-node clustering
• Secure by Default: TLS, authentication, authorization

Integration Approaches

Integration with Other CNCF Projects

• Kubernetes: Native integration with K8s APIs
• Prometheus: Metrics collection integration
• Grafana: Dashboard visualization
• Jaeger/Zipkin: Distributed tracing
• CoreDNS: Service discovery integration
• Envoy: Service mesh integration
• Istio: Service mesh control plane

API Patterns

• RESTful API: Management endpoints
• gRPC API: Internal communication
• WebSocket API: Real-time updates
• Admin API: Configuration management

Configuration Patterns

• YAML Manifests: Human-readable configs
• JSON: Machine-readable format
• Environment Variables: Runtime configuration
• ConfigMaps: Kubernetes config storage
• CRDs: Kubernetes custom resources

Extension Mechanisms

• Plugins: Extend functionality
• Filters: Process requests
• Hooks: Event callbacks
• Modules: Add features

Common Pitfalls and How to Avoid Them

Misconfigurations

• Endpoint Configuration: Wrong API endpoints
• Authentication: Missing or incorrect auth
• Resource Limits: Insufficient resource allocation
• SSL/TLS: Certificate validation issues
• Network Policy: Incorrect network rules
• Scaling: Under/over-provisioned resources

Performance Issues

• Request Latency: High latency
• Throughput: Low throughput
• Memory Usage: High memory consumption
• CPU Usage: High CPU usage
• Connection Pooling: Pool exhaustion
• Cache Misses: High cache miss rate

Operational Challenges

• Configuration Management: Config drift
• Upgrade Management: Rolling upgrades
• Monitoring: Metrics collection
• Logging: Log aggregation
• Troubleshooting: Issue diagnosis
• Security: Security audits

Security Pitfalls

• Authentication: Missing authentication
• Authorization: Overly permissive ACLs
• TLS Configuration: Weak TLS settings
• Secrets Management: Exposed secrets
• RBAC: Insufficient access control
• Vulnerabilities: Outdated dependencies

Coding Practices

Idiomatic Configuration

• YAML: Configuration files
• JSON: API payloads
• Environment Variables: Runtime config
• ConfigMaps: Kubernetes config

API Usage Patterns

• REST API: Management endpoints
• gRPC API: Internal communication
• WebSocket API: Real-time updates

Observability Best Practices

• Prometheus Metrics: Custom metrics
• Tracing: Distributed tracing
• Access Logs: Request logging
• Alerting: Health checks

Testing Strategies

• Unit Tests: Component tests
• Integration Tests: Service tests
• E2E Tests: Full stack tests
• Load Tests: Performance tests

Development Workflow

• Development: Local dev setup
• Testing: Unit and integration tests
• Debugging: Logging, tracing
• Deployment: Docker, Kubernetes
• CI/CD: GitHub Actions
• Tools: Project CLI tools

Fundamentals

Essential Concepts

• Cluster: Node group
• Node: Individual server
• Pod: Container unit
• Service: Network service
• Config: Configuration data
• Secret: Sensitive data
• Volume: Storage volume
• Namespace: Logical partition

Terminology Glossary

• Cluster: Cluster of nodes
• Node: Individual node
• Service: Service endpoint
• Config: Configuration data
• Secret: Secret data
• Volume: Storage
• Namespace: Namespace
• Pod: Pod unit

Data Models and Types

• Config: Config spec
• Secret: Secret spec
• Service: Service spec
• Deployment: Deployment spec
• Pod: Pod spec
• Volume: Volume spec
• Namespace: Namespace spec

Lifecycle Management

• Service Lifecycle: Create → Deploy → Scale → Delete
• Pod Lifecycle: Pending → Running → Succeeded/Failed
• Config Lifecycle: Create → Apply → Update → Delete
• Secret Lifecycle: Create → Encrypt → Decrypt → Delete

State Management

• Config State: Applied config
• Service State: Service state
• Pod State: Pod state
• Volume State: Volume state
• Secret State: Encrypted data
• Namespace State: Namespace data

Scaling and Deployment Patterns

Horizontal Scaling

• Node Scaling: Add/remove nodes
• Container Scaling: Pod replicas
• Database Scaling: Database clusters
• Cache Scaling: Cache clusters
• Load Balancing: Frontend balancing

High Availability

• Multiple Instances: Redundant instances
• Load Balancing: Frontend balancing
• Health Checking: Automatic failover
• Graceful Shutdowns: Clean shutdown
• Data Replication: HA storage

Production Deployments

• Configuration: Production config
• Load Balancing: Frontend HA
• Monitoring: Metrics setup
• Alerting: Alerting setup
• Logging: Centralized logging
• Security: Security hardening

Upgrade Strategies

• Rolling Update: Rolling deployment
• Blue-Green: Blue-green deployment
• Canary: Canary release
• Backup: Pre-upgrade backup
• Validation: Post-upgrade validation

Resource Management

• Memory Configuration: Memory limits
• CPU Configuration: CPU limits
• Storage Configuration: Storage limits
• Network Configuration: Network limits
• Connection Limits: Connection limits

Additional Resources

• Official Documentation: {repo_info['html_url']}
• GitHub Repository: {repo_info['html_url']}
• CNCF Project Page: cncf.io/projects/{project_info['name']}/
• Community: Check the GitHub repository for community channels
• Versioning: Refer to project's release notes for version-specific features

Troubleshooting

Common Issues

1. Deployment Failures

   • Check pod logs for errors
   • Verify configuration values
   • Ensure network connectivity

2. Performance Issues

   • Monitor resource usage
   • Adjust resource limits
   • Check for bottlenecks

3. Configuration Errors

   • Validate YAML syntax
   • Check required fields
   • Verify environment-specific settings

4. Integration Problems

   • Verify API compatibility
   • Check dependency versions
   • Review integration documentation

Getting Help

• Check official documentation
• Search GitHub issues
• Join community channels
• Review logs and metrics Content generated automatically. Verify against official documentation before production use.

Examples

Kong Ingress Controller with Plugins

# Kong Ingress Controller configuration with plugins
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: myapp-ingress
  annotations:
    kubernetes.io/ingress.class: kong
    konghq.com/strip-path: "true"
spec:
  rules:
  - host: api.example.com
    http:
      paths:
      - path: /api
        pathType: Prefix
        backend:
          service:
            name: myapp-service
            port:
              number: 80

---
# KongPlugin for rate limiting
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: rate-limiting
config:
  minute: 100
  policy: local
  limit_by: consumer
plugin: rate-limiting

---
# KongPlugin for request transformation
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: request-transformer
config:
  add:
    headers:
    - X-Request-ID:$pid
    - X-Forwarded-Proto:$remote_addr
plugin: request-transformer

KongConsumer and Credentials

# KongConsumer with API key credential
apiVersion: v1
kind: Secret
metadata:
  name: myapp-api-key
  namespace: production
type: Opaque
stringData:
  apikey: my-secret-api-key-12345

---
apiVersion: configuration.konghq.com/v1
kind: KongConsumer
metadata:
  name: myapp-consumer
  namespace: production
  annotations:
    konghq.com/credentials: myapp-api-key
username: myapp
tags:
- app: myapp
- env: production

---
# KongPlugin for HMAC authentication
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: hmac-auth
config:
  methods:
  - HMAC
  clock_skew: 300
  encoding: hex
  hide_credentials: false
plugin: hmac-auth

KongService and KongRoute

# KongService configuration
apiVersion: configuration.konghq.com/v1
kind: KongService
metadata:
  name: myapp-service
  namespace: production
spec:
  url: http://myapp-service.production.svc:8080
  connect_timeout: 60000
  write_timeout: 60000
  read_timeout: 60000
  retries: 3
  protocol: http
  tags:
  - app: myapp

---
# KongRoute configuration
apiVersion: configuration.konghq.com/v1
kind: KongRoute
metadata:
  name: myapp-route
  namespace: production
spec:
  service:
    name: myapp-service
  paths:
  - /api
  - /api/*
  strip_path: true
  preserve_host: true
  protocols:
  - http
  - https
  regex_priority: 10
  methods:
  - GET
  - POST
  - PUT
  - DELETE
  tags:
  - app: myapp

When to Use

Use this skill when:

• Integrating a CNCF project into Kubernetes infrastructure — You need to configure, deploy, or troubleshoot a cloud-native tool within a cluster
• Designing cloud-native architecture — You are selecting and integrating CNCF tools to solve specific infrastructure challenges
• Resolving operational issues — A CNCF component is misbehaving, underperforming, or needs configuration changes

Core Workflow

1. Assess Requirements — Understand the use case, scale, integration needs, and existing infrastructure. Checkpoint: Document requirements, constraints, and success criteria.

2. Design Architecture — Plan component interactions, data flow, and deployment strategy using cloud-native best practices. Checkpoint: Verify the architecture addresses all requirements and follows CNCF conventions.

3. Implement & Configure — Create manifests, configurations, and deployment scripts. Include resource limits, health checks, and observability hooks. Checkpoint: Validate all YAML against schema and test in a staging environment.

4. Deploy & Monitor — Apply manifests to the cluster, verify component health, and confirm observability is working. Checkpoint: Confirm all pods/services are running, probes passing, and metrics/alerts configured.

Constraints

MUST DO

• Include at least one complete working YAML manifest example
• Note when content is auto-generated vs. manually verified
• Reference relevant CNCF project documentation

MUST NOT DO

• Deploy manifests without testing in a staging environment first
• Use deprecated API versions (e.g., apps/v1beta1)
• Omit resource limits and requests in Kubernetes manifests