All Products
Search
Document Center

Container Service for Kubernetes:Create an NGINX Ingress

Last Updated:Sep 12, 2023

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.

The NGINX Ingress controller is installed.

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 Ingresses in a high-reliability architecture.

  • For more information about how to use the NGINX Ingress controller, see NGINX.

Create an NGINX Ingress

You can use the following methods to create an NGINX Ingress.

Method 1: Create an NGINX Ingress in the ACK console

  1. Log on to the ACK console. In the left-side navigation pane, click Clusters.

  2. On the Clusters page, click the name of the cluster that you want to manage and choose Network > Ingresses in the left-side navigation pane.

  3. 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, MSE Cloud-native Gateway, or Nginx 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

    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.

      • 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:

      1. Click Create on the right side of Secret.

      2. In the Create Secret dialog box, specify the Name, Cert, and Key parameters. Then, click OK.

      3. 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.

    Annotations

    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. ACK does not limit the number of Ingress labels that you can add.

    • Name: foo

    • Value: bar

  4. After the configuration is complete, click OK.

    On the Ingresses page, you can view the Ingress after it is created.

    What to do next

    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: Create an NGINX Ingress by using kubectl

  1. Create a Deployment and a Service.

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

    1. 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
    2. Run the following command to create the Deployment and Service:

      kubectl apply -f test-deployment-service.yaml
  2. Create an Ingress.

    1. 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
      • name: the name of the Ingress. In this example, the name is set to test-ingress.

      • host: the domain name that allows external access to the backend Service.

      • path: 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.

    2. 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 <The Ingress name>

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>