Annotations

VNGCLOUDTypeDefault
/ignorebooleanfalse
/load-balancer-idstring""
/load-balancer-namestringauto generate with rule
/package-idstringlbp-f562b658-0fd4-4fa6-9c57-c1a803ccbf86
/tagsstringMap""
/schemeinternal / internet-facinginternet-facing
/security-groupsstringListauto create secgroup
/inbound-cidrsstring0.0.0.0/0
/healthy-threshold-countinteger'3'
/unhealthy-threshold-countinteger'3'
/healthcheck-interval-secondsinteger'30'
/healthcheck-timeout-secondsinteger'5'
/healthcheck-protocolTCP / HTTPTCP
/healthcheck-http-methodGET / POST / PUTGET
/healthcheck-pathstring"/"
/healthcheck-http-version1.0 / 1.11.0
/healthcheck-http-domain-namestring""
/healthcheck-portintegertraffic port
/success-codesstringList'200'
/idle-timeout-clientinteger50
/idle-timeout-memberinteger50
/idle-timeout-connectioninteger5
/pool-algorithmROUND_ROBIN / LEAST_CONNECTIONS / SOURCE_IPROUND_ROBIN
/enable-sticky-sessionbooleanfalse
/enable-tls-encryptionbooleanfalse
/target-node-labelsstringMap""
/certificate-idsstringList""
/headerjson"{"http":["X-Forwarded-For", "X-Forwarded-Proto", "X-Forwarded-Port"],"https":["X-Forwarded-For", "X-Forwarded-Proto", "X-Forwarded-Port"]}"
/client-certificate-idstring""
/implementation-specific-paramsjson"[]"

Compare with AWS Ingress Annotation.

AWSVNGCLOUDTypeDefaultLocationMergeBehavior
/subnets❌ only subnet of worker nodestringListN/AIngressExclusive
/mutual-authentication❌ mutual authentication configurationjson'[{"port": 443, "mode": "off"}]'IngressExclusive
/certificate-arn❌ The first certificate in the list will be added as default certificate. And remaining certificate will be added to the optional certificate liststringListN/AIngressMerge
/listen-ports❌ set defaultjson'[{"HTTP": 80}]' / '[{"HTTPS": 443}]'IngressMerge
/group.name❌ IngressGroup resourcestringN/AIngressN/A
/group.order❌ order across all Ingresses within IngressGroup. The smaller the order, the rule will be evaluated firstinteger0IngressN/A
/load-balancer-attributes❌ access_logs.s3.enabled=true,...stringMapN/AIngressExclusive
/ssl-redirect❌ every HTTP listener will be configured with a default action which redirects to HTTPSintegerN/AIngressExclusive
/target-type❌ specifies how to route traffic to pods (instance mode will route traffic to all ec2 instances, ip mode will route traffic directly to the pod IP)instance / ipinstanceIngress,ServiceN/A
/backend-protocol❌ Only support HTTPHTTP / HTTPSHTTPIngress,ServiceN/A
/target-group-attributes❌ specifies Target Group Attributes which should be applied to Target GroupsstringMapN/AIngress,ServiceN/A
/ip-address-type❌❌ ipv4 / dualstackipv4 / dualstackipv4IngressExclusive
/manage-backend-security-group-rules❌❌ auto configure security group rules on Node/PodbooleanN/AIngressExclusive
/customer-owned-ipv4-pool❌❌ specifies the customer-owned IPv4 addressstringN/AIngressExclusive
/wafv2-acl-arn❌❌ specifies ARN for the Amazon WAFv2 web ACLstringN/AIngressExclusive
/waf-acl-id❌❌ specifies the identifier for the Amazon WAF web ACLstringN/AIngressExclusive
/shield-advanced-protection❌❌ turns on / off the AWS Shield Advanced protectionbooleanN/AIngressExclusive
/ssl-policy❌❌ specifies the Security Policy that should be assigned to the ALBstringELBSecurityPolicy-2016-08IngressExclusive
/backend-protocol-version❌❌ No optionsstringHTTP1Ingress,ServiceN/A
/auth-type❌❌ specifies the authentication type on targetsnone/oidc/cognitononeIngress,ServiceN/A
/auth-idp-cognito❌❌ specifies the cognito idp configurationjsonN/AIngress,ServiceN/A
/auth-idp-oidc❌❌ specifies the oidc idp configurationjsonN/AIngress,ServiceN/A
/auth-on-unauthenticated-request❌❌ specifies the behavior if the user is not authenticatedauthenticate/allow/denyauthenticateIngress,ServiceN/A
/auth-scope❌❌stringopenidIngress,ServiceN/A
/auth-session-cookie❌❌stringAWSELBAuthSessionCookieIngress,ServiceN/A
/auth-session-timeout❌❌integer'604800'Ingress,ServiceN/A
/actions.${action-name}❌❌jsonN/AIngressN/A
/conditions.${conditions-name}❌❌jsonN/AIngressN/A

Traffic Routing

Traffic Routing can be controlled with following annotations:

  • vks.vngcloud.vn/ignore specifies Ingress is ignored by controller.

    vks.vngcloud.vn/ignore: "true"

  • vks.vngcloud.vn/load-balancer-id specifies the id of the load balancer.

    ⚠️ Warnings: If you specify this annotation, load-balancer will not auto recreate when delete.

    ⚠️ Warnings: If you want many ingress use a same load-balancer, we highly recommended use annotation vks.vngcloud.vn/load-balancer-name.

    vks.vngcloud.vn/load-balancer-id: "lb-xxxxxxxxxxxxxx"

  • vks.vngcloud.vn/load-balancer-name specifies the custom name to use for the load balancer.

    ℹ️ Info: Rule auto genearte load balancer name: ******__******

    ⚠️ Warnings: Name longer than 50 characters will be treated as an error.

    ⚠️ Warnings: Ingress with same this annotation value with use a same load-balancer.

    ⚠️ Warnings: Update this field will cause create/update another load-balancer and redundant resource (old load-balabncer).

    vks.vngcloud.vn/load-balancer-name: "custom-name"

  • vks.vngcloud.vn/package-id The ID of the network load-balancer package to be used for the service. If this annotation is not specified, the default package will be used.

    ⚠️ Warnings: Update this field after apply success will not effect.

    vks.vngcloud.vn/package-id: "lbp-c531bc55-27d7-4a3e-be0b-eac265658a50"

  • vks.vngcloud.vn/target-node-labels specifies which nodes to include in the target group registration.

    vks.vngcloud.vn/target-node-labels: "worker=vmonitor,kubernetes.io/os=linux"
vks.vngcloud.vn/target-node-labels: "key=v1,key=v2" # => "key=v2"

Resource Tags

The VNGCLOUD Ingress Controller automatically applies following tags to the Load Balancer resources, it creates:

  • vks-cluster-ids: ${clusterID}_${clusterID}_${clusterID}

In addition, you can use annotations to specify additional tags

  • vks.vngcloud.vn/tags specifies additional tags that will be applied to vLB resources created.

    ⚠️ Warnings: When user update tags manual in portal, our agent will not sync the change (load balancer not update updateAt when update tags)

    ⚠️ Warnings: It'll update the config tag and append to the current tag.

    vks.vngcloud.vn/tags: "Environment=dev,Team=test"

Access control

Access control for LoadBalancer can be controlled with following annotations:

  • vks.vngcloud.vn/scheme specifies whether your LoadBalancer will be internet facing.

    vks.vngcloud.vn/scheme: "internal"

  • vks.vngcloud.vn/inbound-cidrs specifies the CIDRs that are allowed to access LoadBalancer.

    vks.vngcloud.vn/inbound-cidrs: "10.0.0.0/24"

  • vks.vngcloud.vn/security-groups specifies the securityGroups you want to attach to Node.

    ⚠️ Warnings: If you NOT specify this annotation, the controller will automatically create one security group, the security group will be attached to the Node and allow access from inbound-cidrs to the listen-ports.

    ⚠️ Warnings: If you specify this annotation, you need to ensure the security groups on your Node to allow inbound traffic from the load balancer.

    ⚠️ Warnings: If you specify this annotation, it'll configure only security group only include in this annotation. Ensure include them all here.

    vks.vngcloud.vn/security-groups: "sg-xxxx,sg-yyyyy"

  • vks.vngcloud.vn/idle-timeout-client Connection idle timeout is the maximum time a connection can remain open without any data transfer, after which the load balancer will close the connection. Range: (1-3600).

    vks.vngcloud.vn/idle-timeout-client: "51"

  • vks.vngcloud.vn/idle-timeout-member Backend member inactivity timeout in seconds. Range: (1-3600).

    vks.vngcloud.vn/idle-timeout-member: "51"

  • vks.vngcloud.vn/idle-timeout-connection Backend member connection timeout in seconds.

    vks.vngcloud.vn/idle-timeout-connection: "5"

  • vks.vngcloud.vn/certificate-ids specifies the certificates will be use in HTTPS listeners.

    ⚠️ Warnings: If you specify .Spec.TLS in your ingress resource, this annotation is requires to config certificate default for HTTPS listener.

    ⚠️ Warnings: The first secret in list will be the default certificate, the other will in SNI cert list.

    vks.vngcloud.vn/certificate-ids: "secret-xxx, secret-yyy"

  • vks.vngcloud.vn/header specifies the header for HTTP and HTTPS listeners.

    ⚠️ Warnings: If you specify in wrong format, the consequences will be unpredictable.

    ⚠️ Warnings: You should choose the header allowed in portal.

    vks.vngcloud.vn/header: "{"http":["X-Forwarded-For", "X-Forwarded-Proto", "X-Forwarded-Port"],"https":["X-Forwarded-For", "X-Forwarded-Proto", "X-Forwarded-Port","X-SSL-Client-Verify","X-SSL-Client-Has-Cert","X-SSL-Client-DN","X-SSL-Client-CN","X-SSL-Issuer","X-SSL-Client-SHA1","X-SSL-Client-Not-Before","X-SSL-Client-Not-After"]}"

  • vks.vngcloud.vn/client-certificate-id specifies the client certificate authentication will be use in HTTPS listener.

    vks.vngcloud.vn/client-certificate-id: "secret-xxx"

  • vks.vngcloud.vn/implementation-specific-params specifies the policy when use ImplementSpecific PathType. This annotation is an array of JSON objects, each object contains the path, rules (compare type HOST_NAME, PATH), and action (REJECT, REDIRECT_TO_URL, REDIRECT_TO_POOL).

    JSON format value:

    [
  {
    "path": "/haha", // this value should match path value
    "rules": [
      {
        "type": "PATH", // HOST_NAME, PATH
        "compare": "EQUAL_TO", // CONTAINS, EQUAL_TO, REGEX, STARTS_WITH, ENDS_WITH
        "value": "/foo#" // value to compare
      },
      {
        "type": "PATH",
        "compare": "REGEX",
        "value": "/foo#anchor"
      }
      // more rules ...
    ],
    "action": {
      "action": "REJECT"                    // REJECT, REDIRECT_TO_URL, REDIRECT_TO_POOL
      "redirectUrl": "https://example.com", // required when action is REDIRECT_TO_URL
      "redirectHttpCode": 301,              // required when action is REDIRECT_TO_URL
      "keepQueryString": true               // required when action is REDIRECT_TO_URL
    }
  }
]

    ⚠️ Warnings: If you specify in wrong format, the consequences will be unpredictable.

    For example, when you have a rule use ImplementSpecific PathType, you can use this annotation to specify the policy for this rule.

    spec:
  rules:
    - host: "a-1.vngcloud.vn"
      http:
        paths:
          - path: /haha # this value should match in annotation
            pathType: ImplementationSpecific
            backend:
              service:
                name: netperf-service
                port:
                  number: 80

    # To create a policy REJECT for this rule, you can use this example:
vks.vngcloud.vn/implementation-specific-params: '[{"path":"/haha","rules":[{"type":"PATH","compare":"EQUAL_TO","value":"/foo#"}],"action":{"action":"REJECT"}}]'

# To create a policy REDIRECT_TO_URL for this rule, you can use this example:
vks.vngcloud.vn/implementation-specific-params: '[{"path":"/haha","rules":[{"type":"PATH","compare":"EQUAL_TO","value":"/foo#"}],"action":{"action":"REDIRECT_TO_URL","redirectUrl":"https://example.com","redirectHttpCode":301,"keepQueryString":true}}]'

# To create a policy REDIRECT_TO_POOL for this rule, you can use this example:
vks.vngcloud.vn/implementation-specific-params: '[{"path":"/haha","rules":[{"type":"PATH","compare":"EQUAL_TO","value":"/foo#"}],"action":{"action":"REDIRECT_TO_POOL"}}]'

Health Check

Health check on target groups can be controlled with following annotations:

Pool configuration