NGINX Documentation

Basic Configuration

The example below shows a basic Ingress resource definition. It load balances requests for two services – coffee and tea – comprising a hypothetical cafe app hosted at cafe.example.com:

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: cafe-ingress
spec:
  tls:
  - hosts:
    - cafe.example.com
    secretName: cafe-secret
  rules:
  - host: cafe.example.com
    http:
      paths:
      - path: /tea
        backend:
          serviceName: tea-svc
          servicePort: 80
      - path: /coffee
        backend:
          serviceName: coffee-svc
          servicePort: 80

Here is a breakdown of what this Ingress resource definition means:

  • The metadata.name field defines the name of the resource cafe‑ingress.
  • In the spec.tls field we set up SSL/TLS termination:
    • In the secretName, we reference a secret resource by its name, cafe‑secret. This resource contains the SSL/TLS certificate and key and it must be deployed prior to the Ingress resource.
    • In the hosts field, we apply the certificate and key to our cafe.example.com host.
  • In the spec.rules field, we define a host with domain name cafe.example.com.
  • In the paths field, we define two path‑based rules:
    • The rule with the path /tea instructs NGINX to distribute the requests with the /tea URI among the pods of the tea service, which is deployed with the name tea‑svc in the cluster.
    • The rule with the path /coffee instructs NGINX to distribute the requests with the /coffee URI among the pods of the coffee service, which is deployed with the name coffee‑svc in the cluster.
    • Both rules instruct NGINX to distribute the requests to port 80 of the corresponding service (the servicePort field).
For complete instructions on deploying the Ingress and Secret resources in the cluster, see the complete-example in our GitHub repo.
To learn more about the Ingress resource, see the Ingress resource documentation in the Kubernetes docs.

New Features Available in Kubernetes 1.18 and Above

Starting from Kubernetes 1.18, you can use the following new features:

  • The host field supports wildcard domain names, such as *.example.com.

  • The path supports different matching rules with the new field PathType, which takes the following values: Prefix for prefix-based matching, Exact for exact matching and ImplementationSpecific, which is the default type and is the same as Prefix. For example:

      - path: /tea
        pathType: Prefix
        backend:
          serviceName: tea-svc
          servicePort: 80
      - path: /tea/green
        pathType: Exact
        backend:
          serviceName: tea-svc
          servicePort: 80
      - path: /coffee
        pathType: ImplementationSpecific # default
        backend:
          serviceName: coffee-svc
          servicePort: 80
    
  • The ingressClassName field is now supported:

      apiVersion: networking.k8s.io/v1beta1
      kind: Ingress
      metadata:
        name: cafe-ingress
      spec:
        ingressClassName: nginx
        tls:
        - hosts:
          - cafe.example.com
          secretName: cafe-secret
        rules:
        - host: cafe.example.com
      . . .
    

    When using this filed you need to create the IngressClass resource with the corresponding name. See Step 3 Create an IngressClass resource of the Create Common Resources section.

Restrictions

The NGINX Ingress Controller imposes the following restrictions on Ingress resources:

  • When defining an Ingress resource, the host field is required.
  • The host value needs to be unique among all Ingress and VirtualServer resources unless the Ingress resource is a mergeable minion. See also Handling Host Collisions.

Advanced Configuration

The Ingress resource only allows you to use basic NGINX features – host and path-based routing and TLS termination. Advanced features like rewriting the request URI or inserting additional response headers are available through annotations. See the Advanced Configuration with Annotations doc.

The Ingress Controller generates NGINX configuration by executing a template file that contains configuration options. These options are set via the Ingress resource and the Ingress Controller’s ConfigMap. Advanced NGINX users who require more control over the generated NGINX configurations can use snippets to insert raw NGINX config. See Advanced Configuration with Snippets for more information. Additionally, it is possible to customize the template. See Custom Templates for instructions.