kubernetes-ingress

NGINX and NGINX Plus Ingress Controllers for Kubernetes

4,648

1,961

4,648

119

View on GitHub

Top Related Projects

ingress-nginx

17,241

Ingress-NGINX Controller for Kubernetes

traefik

50,858

The Cloud Native Application Proxy

istio

35,857

Connect, secure, control, and observe services.

contour

3,721

Contour is a Kubernetes ingress controller using Envoy proxy.

kubernetes-ingress-controller

2,198

:gorilla: Kong for Kubernetes: The official Ingress Controller for Kubernetes.

Quick Overview

The nginxinc/kubernetes-ingress repository is an official NGINX Ingress Controller for Kubernetes. It provides a robust solution for managing external access to HTTP and HTTPS services in a Kubernetes cluster, offering advanced traffic management, load balancing, and security features.

Pros

Highly configurable and feature-rich, supporting various NGINX and NGINX Plus capabilities
Excellent performance and scalability, suitable for high-traffic environments
Regular updates and active maintenance by NGINX, Inc.
Comprehensive documentation and community support

Cons

Steeper learning curve compared to some simpler Ingress controllers
Some advanced features require NGINX Plus, which is a paid product
Configuration can be complex for intricate setups
May require more resources compared to lightweight alternatives

Code Examples

Basic Ingress resource:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-ingress
  annotations:
    kubernetes.io/ingress.class: nginx
spec:
  rules:
  - host: example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: example-service
            port: 
              number: 80

This example defines a basic Ingress resource that routes traffic for example.com to an example-service.

VirtualServer resource (NGINX Ingress Controller specific):

apiVersion: k8s.nginx.org/v1
kind: VirtualServer
metadata:
  name: cafe
spec:
  host: cafe.example.com
  upstreams:
  - name: tea
    service: tea-svc
    port: 80
  - name: coffee
    service: coffee-svc
    port: 80
  routes:
  - path: /tea
    action:
      pass: tea
  - path: /coffee
    action:
      pass: coffee

This example uses the NGINX-specific VirtualServer resource to define more advanced routing rules.

ConfigMap for NGINX configuration:

kind: ConfigMap
apiVersion: v1
metadata:
  name: nginx-config
  namespace: nginx-ingress
data:
  proxy-connect-timeout: "10s"
  proxy-read-timeout: "10s"
  client-max-body-size: "2m"

This ConfigMap example shows how to customize NGINX settings for the Ingress Controller.

Getting Started

Install the NGINX Ingress Controller:

kubectl apply -f https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v2.4.2/deployments/common/ns-and-sa.yaml
kubectl apply -f https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v2.4.2/deployments/rbac/rbac.yaml
kubectl apply -f https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v2.4.2/deployments/common/default-server-secret.yaml
kubectl apply -f https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v2.4.2/deployments/common/nginx-config.yaml
kubectl apply -f https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v2.4.2/deployments/deployment/nginx-ingress.yaml

Create an Ingress resource for your application:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-app-ingress
  annotations:
    kubernetes.io/ingress.class: nginx
spec:
  rules:
  - host: myapp.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: my-app-service
            port: 
              number: 80

Apply this YAML file using kubectl apply -f ingress.yaml.

Competitor Comparisons

ingress-nginx

17,241

Ingress-NGINX Controller for Kubernetes

Pros of ingress-nginx

Open-source and community-driven, with frequent updates and contributions
Extensive documentation and wide community support
Supports a broader range of Kubernetes versions

Cons of ingress-nginx

May have slower release cycles for critical updates
Less optimized for enterprise-grade deployments
Limited commercial support options

Code Comparison

ingress-nginx:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-ingress
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /$2
spec:
  rules:
  - host: example.com
    http:
      paths:
      - path: /prefix(/|$)(.*)
        pathType: Prefix
        backend:
          service:
            name: example-service
            port: 
              number: 80

kubernetes-ingress:

apiVersion: k8s.nginx.org/v1
kind: VirtualServer
metadata:
  name: example-virtual-server
spec:
  host: example.com
  upstreams:
  - name: example-upstream
    service: example-service
    port: 80
  routes:
  - path: /prefix
    action:
      proxy:
        upstream: example-upstream
        rewritePath: /$request_uri

The code examples showcase different approaches to configuring ingress rules. ingress-nginx uses standard Kubernetes Ingress resources with annotations, while kubernetes-ingress introduces custom resources like VirtualServer for more advanced configurations.

traefik

50,858

The Cloud Native Application Proxy

Pros of Traefik

Automatic service discovery and configuration
Built-in support for multiple providers (Docker, Kubernetes, etc.)
Easy to set up and configure with minimal manual intervention

Cons of Traefik

Less mature and battle-tested compared to NGINX Ingress Controller
May have performance limitations for high-traffic scenarios
Smaller community and ecosystem compared to NGINX

Code Comparison

Traefik configuration:

apiVersion: traefik.containo.us/v1alpha1
kind: IngressRoute
metadata:
  name: myingress
spec:
  entryPoints:
    - web
  routes:
    - match: Host(`example.com`)
      kind: Rule
      services:
        - name: myservice
          port: 80

NGINX Ingress Controller configuration:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: myingress
  annotations:
    kubernetes.io/ingress.class: nginx
spec:
  rules:
    - host: example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: myservice
                port: 
                  number: 80

Both Traefik and NGINX Ingress Controller are popular choices for Kubernetes ingress controllers. Traefik offers simplicity and auto-configuration, while NGINX Ingress Controller provides robust performance and a larger ecosystem. The choice between them depends on specific project requirements and preferences.

istio

35,857

Connect, secure, control, and observe services.

Pros of Istio

Offers a comprehensive service mesh solution with advanced traffic management, security, and observability features
Provides automatic sidecar injection for easier deployment and management
Supports multi-cluster and multi-cloud environments out of the box

Cons of Istio

Higher complexity and steeper learning curve compared to simpler ingress controllers
Requires more resources and can introduce additional latency due to its sidecar proxy architecture
May be overkill for smaller applications or teams not requiring advanced service mesh capabilities

Code Comparison

Istio (Virtual Service configuration):

apiVersion: networking.istio.io/v1alpha3
kind: VirtualService
metadata:
  name: my-service
spec:
  hosts:
  - my-service.example.com
  http:
  - route:
    - destination:
        host: my-service

Kubernetes-ingress (NGINX Ingress configuration):

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-ingress
spec:
  rules:
  - host: my-service.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: my-service
            port: 
              number: 80

The code comparison shows that Istio uses its own Custom Resource Definitions (CRDs) for traffic routing, while Kubernetes-ingress uses standard Kubernetes Ingress resources. Istio's configuration is more flexible and powerful, but may require more familiarity with its specific concepts and syntax.

contour

3,721

Contour is a Kubernetes ingress controller using Envoy proxy.

Pros of Contour

Lightweight and efficient, designed specifically for Kubernetes
Built-in support for WebSocket and gRPC protocols
Simpler configuration model with CRDs like HTTPProxy

Cons of Contour

Less mature and fewer features compared to NGINX Ingress Controller
Smaller community and ecosystem support
Limited to Layer 7 load balancing, lacking some advanced traffic management features

Code Comparison

Contour (using HTTPProxy CRD):

apiVersion: projectcontour.io/v1
kind: HTTPProxy
metadata:
  name: example
spec:
  virtualhost:
    fqdn: example.com
  routes:
    - conditions:
      - prefix: /
      services:
        - name: example-service
          port: 80

NGINX Ingress Controller:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example
  annotations:
    kubernetes.io/ingress.class: nginx
spec:
  rules:
  - host: example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: example-service
            port: 
              number: 80

Both repositories provide Kubernetes Ingress solutions, but Contour focuses on simplicity and efficiency, while NGINX Ingress Controller offers more advanced features and wider adoption. Contour's HTTPProxy CRD provides a more Kubernetes-native approach to configuration, while NGINX relies on standard Ingress resources with annotations for extended functionality.

kubernetes-ingress-controller

2,198

:gorilla: Kong for Kubernetes: The official Ingress Controller for Kubernetes.

Pros of kubernetes-ingress-controller

More extensive API management capabilities, including rate limiting and authentication
Built-in analytics and monitoring features
Supports multiple protocols beyond HTTP, such as TCP and gRPC

Cons of kubernetes-ingress-controller

Steeper learning curve due to additional features and complexity
Potentially higher resource consumption compared to the NGINX-based solution
May require additional configuration for advanced features

Code Comparison

kubernetes-ingress:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-ingress
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /$2
spec:
  rules:
  - host: example.com
    http:
      paths:
      - path: /prefix(/|$)(.*)
        pathType: Prefix
        backend:
          service:
            name: example-service
            port: 
              number: 80

kubernetes-ingress-controller:

apiVersion: configuration.konghq.com/v1
kind: KongIngress
metadata:
  name: example-kong-ingress
config:
  protocols:
  - http
  - https
  methods:
  - GET
  - POST
  strip_path: true
  preserve_host: false
  upstream:
    hash_on: none
    hash_fallback: none
    healthchecks:
      active:
        healthy:
          http_statuses:
          - 200
          interval: 5
          successes: 5

Both controllers offer Kubernetes Ingress functionality, but kubernetes-ingress-controller provides more advanced features and configuration options out of the box, while kubernetes-ingress focuses on simplicity and performance.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

NGINX Ingress Controller

This repo provides an implementation of an Ingress Controller for NGINX and NGINX Plus from the people behind NGINX.

Join The Next Community Call

We value community input and would love to see you at the next community call. At these calls, we discuss PRs by community members as well as issues, discussions and feature requests.

Zoom Link: KIC - GitHub Issues Triage
Password: 197738
Slack: Join our channel #nginx-ingress-controller on the NGINX Community Slack for updates and discussions.
When: 15:00 GMT / Convert to your timezone, every other Monday.

Community Call Dates	Notes
2024-07-15
2024-07-29
2024-08-12
2024-08-26
2024-09-09
2024-09-23

NGINX Ingress Controller works with both NGINX and NGINX Plus and supports the standard Ingress features - content-based routing and TLS/SSL termination.

Additionally, several NGINX and NGINX Plus features are available as extensions to the Ingress resource via annotations and the ConfigMap resource. In addition to HTTP, NGINX Ingress Controller supports load balancing Websocket, gRPC, TCP and UDP applications. See ConfigMap and Annotations docs to learn more about the supported features and customization options.

As an alternative to the Ingress, NGINX Ingress Controller supports the VirtualServer and VirtualServerRoute resources. They enable use cases not supported with the Ingress resource, such as traffic splitting and advanced content-based routing. See VirtualServer and VirtualServerRoute resources doc.

TCP, UDP and TLS Passthrough load balancing is also supported. See the TransportServer resource doc.

Read this doc to learn more about NGINX Ingress Controller with NGINX Plus.

Note

This project is different from the NGINX Ingress Controller in kubernetes/ingress-nginx repo. See this doc to find out about the key differences.

Ingress and Ingress Controller

What is the Ingress?

The Ingress is a Kubernetes resource that lets you configure an HTTP load balancer for applications running on Kubernetes, represented by one or more Services. Such a load balancer is necessary to deliver those applications to clients outside of the Kubernetes cluster.

The Ingress resource supports the following features:

Content-based routing:
- Host-based routing. For example, routing requests with the host header foo.example.com to one group of services and the host header bar.example.com to another group.
- Path-based routing. For example, routing requests with the URI that starts with /serviceA to service A and requests with the URI that starts with /serviceB to service B.
TLS/SSL termination for each hostname, such as foo.example.com.

See the Ingress User Guide to learn more about the Ingress resource.

What is the Ingress Controller?

The Ingress Controller is an application that runs in a cluster and configures an HTTP load balancer according to Ingress resources. The load balancer can be a software load balancer running in the cluster or a hardware or cloud load balancer running externally. Different load balancers require different Ingress Controller implementations.

In the case of NGINX, the Ingress Controller is deployed in a pod along with the load balancer.

Getting Started

Note

All documentation should only be used with the latest stable release, indicated on the releases page of the GitHub repository.

Install NGINX Ingress Controller using the Helm chart or the Kubernetes manifests.
Configure load balancing for a simple web application:
- Use the Ingress resource. See the Cafe example.
- Or the VirtualServer resource. See the Basic configuration example.
See additional configuration examples.
Learn more about all available configuration and customization in the docs.

NGINX Ingress Controller Releases

We publish NGINX Ingress Controller releases on GitHub. See our releases page.

The latest stable release is 3.6.2. For production use, we recommend that you choose the latest stable release.

The edge version is useful for experimenting with new features that are not yet published in a stable release. To use it, choose the edge version built from the latest commit from the main branch.

To use NGINX Ingress Controller, you need to have access to:

An NGINX Ingress Controller image.
Installation manifests or a Helm chart.
Documentation and examples.

It is important that the versions of those things above match.

The table below summarizes the options regarding the images, Helm chart, manifests, documentation and examples and gives your links to the correct versions:

Version	Description	Image for NGINX	Image for NGINX Plus	Installation Manifests and Helm Chart	Documentation and Examples
Latest stable release	For production use	Use the 3.6.2 images from DockerHub, GitHub Container, Amazon ECR Public Gallery or Quay.io or build your own image.	Use the 3.6.2 images from the F5 Container Registry or the AWS Marketplace or Build your own image.	Manifests. Helm chart.	Documentation. Examples.
Edge/Nightly	For testing and experimenting	Use the edge or nightly images from DockerHub, GitHub Container, Amazon ECR Public Gallery or Quay.io or build your own image.	Build your own image.	Manifests. Helm chart.	Documentation. Examples.

SBOM (Software Bill of Materials)

We generate SBOMs for the binaries and the Docker images.

Binaries

The SBOMs for the binaries are available in the releases page. The SBOMs are generated using syft and are available in SPDX format.

Docker Images

The SBOMs for the Docker images are available in the DockerHub, GitHub Container, Amazon ECR Public Gallery or Quay.io repositories. The SBOMs are generated using syft and stored as an attestation in the image manifest.

For example to retrieve the SBOM for linux/amd64 from Docker Hub and analyze it using grype you can run the following command:

docker buildx imagetools inspect nginx/nginx-ingress:edge --format '{{ json (index .SBOM "linux/amd64").SPDX }}' | grype

Contacts

Weâd like to hear your feedback! If you have any suggestions or experience issues with our Ingress Controller, please create an issue or send a pull request on GitHub. You can contact us directly via kubernetes@nginx.com or on the NGINX Community Slack.

Contributing

If you'd like to contribute to the project, please read our Contributing guide.

Support

For NGINX Plus customers NGINX Ingress Controller (when used with NGINX Plus) is covered by the support contract.

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot