How to create an NGINX Ingress - Container Service for Kubernetes

An Ingress is a Kubernetes resource object that is used to enable external access to Services in a Kubernetes cluster. Container Service for Kubernetes (ACK) allows you to use Ingresses to configure multiple forwarding rules for handling requests to pods in a Kubernetes cluster. This topic describes how to create, view, update, and delete an NGINX Ingress in the ACK console or by using kubectl.

Prerequisites

An ACK cluster is created. For more information, see Create an ACK managed cluster.

Usage notes

Take note of the following items when you use the NGINX Ingress controller:

If you want to customize component parameters, go to the cluster details page in the ACK console or by calling the ACK API. If you use other methods to customize the component parameters, the component may not run as expected and may encounter update issues.
Do not delete the kube-system/nginx-ingress-lb Service, which is the default Service used by the NGINX Ingress controller. If you delete the Service, the NGINX Ingress component may not run as expected or even stop running.
We recommend that you configure the features of the component by using annotations and parameters instead of by using Snippet or Lua code. ACK does not provide technical support if you use Snippet configurations to configure the component and the Snippet configurations do not take effect as expected.
The NGINX Ingress controller may have bugs or vulnerabilities that are discovered in the open source version. Update the NGINX Ingress controller to the latest version to avoid negative impacts on your applications.
In heavy-load scenarios, we recommend that you deploy each pod of the NGINX Ingress controller on an exclusive node. For more information, see Deploy Ingress Controller in a high-reliability architecture.
For more information about how to use the NGINX Ingress controller, see Usage notes of the NGINX Ingress controller.

Procedure

Method 1: Use the ACK console

Create an NGINX Ingress

Log on to the ACK console. In the left-side navigation pane, click Clusters.
On the Clusters page, find the cluster that you want to manage and click its name. In the left-side pane, choose Network > Ingresses.

On the Ingresses page, click Create Ingress. In the Create Ingress dialog box, configure the Ingress.

Parameter	Description	Example
Gateway Type	You can select ALB Ingress, MSE Ingressy, or Nginx Ingress based on your requirements. For more information about the differences among the three gateway types, see Comparison among NGINX Ingresses, ALB Ingresses, and MSE Ingresses.	Nginx Ingress
Name	Specify the name of the Ingress.	nginx-ingress
Ingress Class	Specify the class of the Ingress.	nginx
Rules	Click +Add Rule to add an Ingress rule. Domain Name: Enter a custom domain name. Mappings: Specify the following parameters: Path: Enter the URL path of the backend Service. In this example, the root path / is used. Rule: You can select Prefix (Prefix-based Match), Exact (Exact Match), or ImplementationSpecific (Default Value). Service: Select the backend Service. Port: Specify the Service port that you want to expose. You can configure multiple paths for a domain name. Click + Add to add a path.	Domain Name: test.example.com Mappings: Path: In this example, the root path / is used. Rule: ImplementationSpecific (Default Value) Service: nginx-ingress-lb Port: 80
TLS Settings	You can enable TLS authentication for the Ingress. Domain Name: Enter a custom domain name. Secret: Select the Secret that you want to use. If you want to create a Secret, perform the following steps: Click Create on the right side of Secret. In the Create Secret dialog box, specify the Name, Cert, and Key parameters. Then, click OK. Select the Secret that you created from the Secret drop-down list. Click + Add to add a TLS certificate. For more information about how to use Ingresses, see Ingress support.	Enable TLS authentication. Domain Name: test.example.com Secret: cert
More	Canary Release: Enable canary releases. You can configure canary release rules based on request headers, cookies, and weights. Note You can configure canary release rules based on only one of the following elements: request headers, cookies, and weights. You can also configure canary release rules based on request headers, cookies, and weights at the same time. In this case, request headers, cookies, and weights take effect in descending order of precedence. Based on Request Header: Distribute traffic based on request headers by adding the `nginx.ingress.kubernetes.io/canary-by-header`, `nginx.ingress.kubernetes.io/canary-by-header-value`, or `nginx.ingress.kubernetes.io/canary-by-header-pattern` annotation. Based on Cookie: Distribute traffic based on cookies by adding the `nginx.ingress.kubernetes.io/canary-by-cookie` annotation. Based on Weight: Distribute traffic based on Service weights (integers from 0 to 100) by adding the `nginx.ingress.kubernetes.io/canary-weight` annotation. Protocol: Select the protocol used by the backend Service by adding the `nginx.ingress.kubernetes.io/backend-protocol` annotation. HTTP, HTTPS, gRPC, and gRPCS are supported. Rewrite Path: Add the `nginx.ingress.kubernetes.io/rewrite-target` annotation to rewrite the paths in client requests before the requests are forwarded to the backend Service.	Enable canary releases. Select Based on Request Header and then specify the following parameters: Request Header: foo Match Rule: Exact Match Match Value: bar Protocol: gRPC Rewrite Path: Leave this parameter empty.
Annotation	You can enter custom annotation names and values. You can also select or search for annotations by name from the drop-down list. For more information about Ingress annotations, see Annotations. Click +Add Annotation to add an annotation. ACK does not limit the number of Ingress annotations that you can add.	Name: nginx.ingress.kubernetes.io/proxy-body-size Value: 10m
Labels	You can add labels to describe the characteristics of the Ingress. Click +Add Label to add a label. No limit is imposed on the number of Ingress labels that you can add.	Name: foo Value: bar

After the configuration is complete, click OK.
On the Ingresses page, you can view the Ingress after it is created.
References
On the Ingresses page, you can click Update, Edit YAML, or Monitor, or choose > Delete in the Actions column to manage the Ingress.

Method 2: Use kubectl

Create an NGINX Ingress

Create a Deployment and a Service.

You must create a Service to enable external access before you create an Ingress.

Create a file named test-deployment-service.yaml and copy the following content to the file.

The following YAML template is used to create a Deployment named test-web1 and a Service named web1-service:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: test-web1
  labels:
    app: test-web1
spec:
  replicas: 1
  selector:
    matchLabels:
      app: test-web1
  template:
    metadata:
      labels:
        app: test-web1
    spec:
      containers:
      - name: test-web1
        imagePullPolicy: IfNotPresent
        image: registry.cn-hangzhou.aliyuncs.com/yilong/ingress-test:web1
        ports:
        - containerPort: 8080
--- 
apiVersion: v1
kind: Service
metadata:
  name: web1-service
spec:
  type: ClusterIP
  selector:
    app: test-web1
  ports:
    - port: 8080
      targetPort: 8080

Run the following command to create the Deployment and Service:
```
kubectl apply -f test-deployment-service.yaml
```

Create an Ingress.

Create a file named test-ingress.yaml and copy the following content to the file:

Clusters that run Kubernetes versions earlier than 1.19

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: test-ingress
  namespace: default
spec:
  rules:
  - host: test-ingress.com
    http:
      paths:
      - path: /foo
        backend:
          serviceName: web1-service
          servicePort: 8080
      - path: /bar
        backend:
          serviceName: web1-service
          servicePort: 8080

Clusters that run Kubernetes 1.19 or later

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: test-ingress
  namespace: default
spec:
  rules:
  - host: test-ingress.com
    http:
      paths:
      - path: /foo
        backend:
          service: 
            name: web1-service
            port:
              number: 8080
        pathType: ImplementationSpecific
      - path: /bar
        backend:
          service: 
            name: web1-service
            port:
              number: 8080
        pathType: ImplementationSpecific

: the name of the Ingress. In this example, the name is set to test-ingress.
: the domain name that allows external access to the backend Service.
: the URL paths that are used to match requests. SLB forwards traffic to the backend Service only when inbound requests match the host and path settings.
backend: the name and port number of the backend Service.
- Service name: the name of the backend Service.
- Service port: the Service port that is exposed.

Run the following command to create the Ingress:
```
kubectl apply -f test-ingress.yaml
```

View an Ingress

Run the following command to view an Ingress:

kubectl get ingress

Update an Ingress

Run the following command to update an Ingress:

kubectl edit ingress <Ingress name>

Delete an Ingress

Run the following command to delete an Ingress:

kubectl delete ingress <Ingress name>

Prerequisites

Usage notes

Procedure

Method 1: Use the ACK console

Create an NGINX Ingress

References

Method 2: Use kubectl

Create an NGINX Ingress

Clusters that run Kubernetes versions earlier than 1.19

Clusters that run Kubernetes 1.19 or later

View an Ingress

Update an Ingress

Delete an Ingress