ALB Ingress Controller use cases

Available in VPC

In Ncloud Kubernetes Service, you can add annotations to Service and Ingress to implement various routing strategies. This guide provides use examples based on Setting up ALB Ingress Controller.

Install example workload

Run the following command to install example deployments and services. When you run the command, deployments and services of which names are "naver," "cloud," and "platform" are created.

kubectl --kubeconfig=$KUBE_CONFIG apply -f https://raw.githubusercontent.com/NaverCloudPlatform/nks-alb-ingress-controller/main/docs/examples/pub/nks-alb-ingress-sample-services.yaml

ALB Ingress Controller use cases

Example of path-based routing

This example shows how to route a request to different services based on the specified path. Incoming requests to the /naver path are routed to the NAVER service, while incoming requests to the /cloud path are routed to the Cloud service.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: path-ingress
spec:
  ingressClassName: alb
  rules:
  - http:
      paths:
      - path: /naver
        pathType: Prefix
        backend:
          service:
            name: naver 
            port:
              number: 80
      - path: /cloud
        pathType: Prefix
        backend:
          service:
            name: cloud
            port:
              number: 80

Example of host-based routing

This example shows how to route a request to different services based on the specified host. All incoming requests to the svc.naver.com host are routed to the NAVER service, while all incoming requests to the svc.cloud.com host are routed to the Cloud service.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: host-ingress
spec:
  ingressClassName: alb
  rules:
  - host: svc.naver.com
    http:
      paths:
      - path: /*
        pathType: Prefix
        backend:
          service:
            name: naver
            port:
              number: 80
  - host: svc.cloud.com
    http:
      paths:
      - path: /*
        pathType: Prefix
        backend:
          service:
            name: cloud
            port:
              number: 80

Example of HTTP header-based routing

This example shows how to route traffic based on the HTTP header value. It uses the alb.ingress.kubernetes.io/conditions annotation to define the HTTP header rules. Here, only requests where the HTTP header "HeaderName" includes "HeaderValue1" or "HeaderValue2" are routed to the NAVER service.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: condition-ingress
  annotations:
    alb.ingress.kubernetes.io/conditions.naver: >
      [{"field":"httpHeader","httpHeader":{"key": "HeaderName", "values":["HeaderValue1", "HeaderValue2"]}}]
spec:
  ingressClassName: alb
  rules:
    - http:
        paths:
          - path: /*
            pathType: Prefix
            backend:
              service:
                name: naver
                port:
                  number: 80

Service port name use cases

You can define traffic routing rules in the Ingress rule by using the port name (port.name) of the service. For this, you need to explicitly set port.name when defining the service. In this example, the name "http-web" is assigned for the NAVER service port and is referred to by the Ingress rule.

apiVersion: v1
kind: Service
metadata:
  name: naver
spec:
  ports:
  - name: http-web
    nodePort: 30080
    port: 80
    protocol: TCP
    targetPort: 80
  selector:
    app: naver
  type: NodePort
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: portname-ingress
spec:
  ingressClassName: alb
  rules:
  - http:
      paths:
      - path: /naver
        pathType: Prefix
        backend:
          service:
            name: naver
            port:
              name: http-web

Example of redirecting HTTP to HTTPS

This example shows how to redirect the traffic coming from HTTP to HTTPS using the ssl-redirect annotation. To execute this example, the following elements are required:

Domain
The certificate of the domain registered to Certificate Manager

To redirect the traffic coming to HTTP(80) to HTTPS(443), create an Ingress as shown in the following example:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    alb.ingress.kubernetes.io/listen-ports: '[{"HTTP": 80},{"HTTPS":443}]'
    alb.ingress.kubernetes.io/ssl-certificate-no: "1004"
    alb.ingress.kubernetes.io/ssl-redirect: "443"
  name: redirect-ingress
spec:
  ingressClassName: alb
  defaultBackend:
    service:
      name: cloud
      port:
        number: 80

The following describes how to add 2 ports in order to redirect Port 80 to Port 443 in the above settings:
```
alb.ingress.kubernetes.io/listen-ports: '[{"HTTP": 80},{"HTTPS":443}]'
```
The following describes how to get the certificate number to register to the HTTPS listener in the above settings:
```
alb.ingress.kubernetes.io/ssl-certificate-no: "1004"
```
Note

The certificate number can be checked at the nrn of Resource Manager. (for example: nrn:PUB:CertificateManager::000:Certificate/External/${certificateNo})
The following describes how to register the port for redirection in the above setting:
```
alb.ingress.kubernetes.io/ssl-redirect: "443"
```

Example of using multi-certificates

You can register multiple certificates to a load balancer. This example shows how to configure the default certificate and additional certificates.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    alb.ingress.kubernetes.io/listen-ports: '[{"HTTP": 80},{"HTTPS":443}]'
    alb.ingress.kubernetes.io/ssl-certificate-no: "1234, 1004"
    alb.ingress.kubernetes.io/ssl-redirect: "443"
  name: multi-ssl-ingress
spec:
  ingressClassName: alb
  rules:
  - http:
      paths:
      - path: /*
        pathType: Prefix
        backend:
          service:
            name: naver 
            port:
              number: 80

The following describes how to register the certificates in the above setting. The first certificate is added as the default certificate and the rest are set as additional certificates.
```
alb.ingress.kubernetes.io/ssl-certificate-no: "1234, 1004"
```

Example of weight-based routing through action

This example defines how to handle the traffic to a specific path using Ingress rules and annotations. For the /navercloud path, use the annotation to redirect traffic to either NAVER or Cloud services.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: action-ingress
  annotations:
    alb.ingress.kubernetes.io/listen-ports: '[{"HTTP": 80}]'
    alb.ingress.kubernetes.io/description: 'alb ingress controller'
    alb.ingress.kubernetes.io/actions.navercloud: >
      {"type":"targetGroup","targetGroup":{"targetGroups":[{"serviceName":"naver","servicePort":80,"weight":50},{"serviceName":"cloud","servicePort":80,"weight":50}]}}
spec:
  ingressClassName: alb
  defaultBackend:
    service:
      name: naver
      port:
        number: 80
  rules:
    - http:
        paths:
          - path: /platform
            pathType: Prefix
            backend:
              service:
                name: platform
                port:
                  number: 80
          - path: /navercloud
            pathType: Exact
            backend:
              service:
                name: navercloud
                port:
                  name: use-annotation

The following is the part where traffic is distributed to NAVER and Cloud services in the setting above:

alb.ingress.kubernetes.io/actions.navercloud: >
  {"type":"targetGroup","targetGroup":{"targetGroups":[{"serviceName":"naver","servicePort":80,"weight":50},{"serviceName":"cloud","servicePort":80,"weight":50}]}}

To apply the annotation, the path defined in Ingress specifications and the actionName in actions.${actionName} must match.

Example of setting services that exist in different namespaces through action

This example shows how to manage services that exist in different namespaces in one Ingress using Ingress rules and annotations. When you access /navercloud path, you are routed to the NAVER service that exists in the NAVER Cloud namespace.

apiVersion: v1
kind: Service
metadata:
  name: naver
  namespace: navercloud
spec:
  type: NodePort
  selector:
    app: naver
  ports:
    - port: 80
      targetPort: 80
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: naver
  namespace: navercloud
spec:
  replicas: 1
  selector:
    matchLabels:
      app: naver
  template:
    metadata:
      labels:
        app: naver
    spec:
      containers:
        - name: naver
          image: nks.kr.ncr.ntruss.com/hello:plain-text
          ports:
            - containerPort: 80
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: action-ingress
  annotations:
    alb.ingress.kubernetes.io/actions.navercloud: >
      {"type":"targetGroup","targetGroup":{"targetGroups":[{"serviceName":"navercloud/naver","servicePort":80,"weight":100}]}}
spec:
  ingressClassName: alb
  defaultBackend:
    service:
      name: cloud 
      port:
        number: 80
  rules:
    - http:
        paths:
          - path: /navercloud
            pathType: Exact
            backend:
              service:
                name: navercloud
                port:
                  name: use-annotation

In the setting above, the following is the part where the service that exists in another namespace is defined: The service in the action should be defined as namespace/service format.
```
alb.ingress.kubernetes.io/actions.navercloud: >
  {"type":"targetGroup","targetGroup":{"targetGroups":[{"serviceName":"navercloud/naver","servicePort":80,"weight":100}]}}
```
To apply the annotation, the path defined in Ingress specifications and the actionName in actions.${actionName} must match.
The service specified in the action should be NodePort type.

Example of using condition to add a condition

This example defines how to add a condition for a specific path using Ingress rules and annotations. The traffic is routed from the /naver path to the NAVER service following the rules specified in the specifications, and annotations are used to add conditions.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: condition-ingress
  annotations:
    alb.ingress.kubernetes.io/conditions.naver: >
      [{"field":"hostHeader","hostHeader":{"values":["svc.naver.com"]}},{"field":"pathPattern","pathPattern":{"values":["/cloud"]}}]
spec:
  ingressClassName: alb
  rules:
    - http:
        paths:
          - path: /naver
            pathType: Prefix
            backend:
              service:
                name: naver
                port:
                  number: 80

The following is the part where the svc.naver.com host header conditions and additional paths are applied in the setting above:

alb.ingress.kubernetes.io/conditions.naver: >
  [{"field":"hostHeader","hostHeader":{"values":["svc.naver.com"]}},{"field":"pathPattern","pathPattern":{"values":["/cloud"]}}]

To apply the annotation, the path defined in Ingress specifications and the conditionName in conditions.${conditionName} must match.

Example of setting the health check path by target groups

If the target of an annotation is Ingress or Service, the annotation is available for both resource types. If the same annotation is found in both Ingress and Service, the annotation applied to Service takes priority.

In this example, the health check for each service registered in each path is set individually. The specific health check setting for each service is implemented by the annotation of the service.

# naver-service.yaml
apiVersion: v1
kind: Service
metadata:
  annotations:
    alb.ingress.kubernetes.io/healthcheck-path: /naver
  name: naver
spec:
  ports:
  - port: 80
    protocol: TCP
    targetPort: 80
  selector:
    app: naver
  type: NodePort
---
# cloud-service.yaml
apiVersion: v1
kind: Service
metadata:
  annotations:
    alb.ingress.kubernetes.io/healthcheck-path: /cloud
  name: cloud
spec:
  ports:
  - port: 80
    protocol: TCP
    targetPort: 80
  selector:
    app: cloud
  type: NodePort
---
# healthcheck-alb.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: healthcheck-alb
  annotations:
    kubernetes.io/ingress.class: alb
    alb.ingress.kubernetes.io/listen-ports: '[{"HTTP": 80}]'
    alb.ingress.kubernetes.io/healthcheck-path: "/"
spec:
  defaultBackend:
    service:
      name: platform 
      port:
        number: 80
  rules:
  - http:
      paths:
      - path: /naver
        pathType: Prefix
        backend:
          service:
            name: naver
            port:
              number: 80
      - path: /cloud
        pathType: Prefix
        backend:
          service:
            name: cloud
            port:
              number: 80

The health check conditions of the target group to be routed to the /naver path in the setting above is as follows. These settings must be defined by the annotation of the service to apply specific health check conditions to each target group.
```
alb.ingress.kubernetes.io/healthcheck-path: /naver
```

Example of specifying Sticky Session

Sticky Session of load balancer is provided as the Sticky Session function configurable in the listener rule and the Sticky Session function configurable in the target group.
In this example, we specify the Sticky Sessions of all target groups created and set to use the Sticky Session of the rules created through action.

Note

Sticky Session function may not operate properly in Ncloud Kubernetes Service product because NAVER Cloud Platform's Application Load Balancer specifies the server as the target group.
In order to use Sticky Session function, you need to set the externalTrafficPolicy of the service to Local and deploy 1 pod for each node.
This function will be improved in the future, and in the meantime, you should use the session management features of the operation application if possible.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: sticky-ingress 
  annotations:
    alb.ingress.kubernetes.io/listen-ports: '[{"HTTP": 80}]'
    alb.ingress.kubernetes.io/enable-sticky-session: 'true'
    alb.ingress.kubernetes.io/actions.targets: >
      {"type":"targetGroup","targetGroup":{"targetGroups":[{"serviceName":"naver","servicePort":80,"weight":50},{"serviceName":"cloud","servicePort":80,"weight":50}],"enableStickySession":true}}
spec:
  ingressClassName: alb
  rules:
  - http:
      paths:
      - path: /navercloud
        pathType: Prefix
        backend:
          service:
            name: targets 
            port:
              name: use-annotation 
      - path: /platform
        pathType: Prefix
        backend:
          service:
            name: platform 
            port:
              number: 80

In the setting above, the following is the part where the Sticky Session of the target group is used:
```
alb.ingress.kubernetes.io/enable-sticky-session: 'true'
```

In the setting above, the following is the part where the Sticky Session is used for the requests coming to the /navercloud path:

alb.ingress.kubernetes.io/actions.targets: >
  {"type":"targetGroup","targetGroup":{"targetGroups":[{"serviceName":"naver","servicePort":80,"weight":50},{"serviceName":"cloud","servicePort":80,"weight":50}],"enableStickySession":true}}

Access Control List settings examples

This example shows how to control access to the Ingress resource using the Access Control List (ACL) based on the assigned ACL ID. ACL ID 123 is applied to port 80 through the annotation, and the request coming through /acl path is routed to Naver service. You can use ACL settings to control only the allowed IP or the request within the range of CIDR to access the path.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: acl-ingress
  annotations:
    alb.ingress.kubernetes.io/listen-ports: '[{"HTTP": 80}]'
    alb.ingress.kubernetes.io/listener-acl-id.80: "123"
spec:
  ingressClassName: alb
  rules:
  - http:
      paths:
      - path: /acl
        pathType: Prefix
        backend:
          service:
            name: naver
            port:
              number: 80