Skip to content

Ingress annotations

You can add kubernetes annotations to ingress and service objects to customize their behavior.


  • Annotations applied to service have higher priority over annotations applied to ingress. Location column below indicates where that annotation can be applied to.
  • Annotation keys and values can only be strings. Advanced format are encoded as below:
    • integer: '42'
    • stringMap: k1=v1,k2=v2
    • stringList: s1,s2,s3
    • json: 'jsonContent'


The annotation prefix can be changed using the --annotations-prefix command line argument, by default it's, as described in the table below.


Name Type Default Location${action-name} json N/A ingress json N/A ingress,service json N/A ingress,service authenticate|allow|deny authenticate ingress,service string openid ingress,service string AWSELBAuthSessionCookie ingress,service integer 604800 ingress,service none|oidc|cognito none ingress,service HTTP | HTTPS HTTP ingress,service string N/A ingress integer '15' ingress,service string / ingress,service integer | traffic-port traffic-port ingress,service HTTP | HTTPS HTTP ingress,service integer '5' ingress,service integer '2' ingress,service stringList ingress ipv4 | dualstack ipv4 ingress json '[{"HTTP": 80}]' | '[{"HTTPS": 443}]' ingress stringMap N/A ingress internal | internet-facing internal ingress stringList N/A ingress string ELBSecurityPolicy-2016-08 ingress stringList N/A ingress string '200' ingress,service stringMap N/A ingress stringMap N/A ingress,service instance | ip instance ingress,service integer '2' ingress,service

Traffic Listening

Traffic Listening can be controlled with following annotations:

Traffic Routing

Traffic Routing can be controlled with following annotations:

  • specifies how to route traffic to pods. You can choose between instance and ip:

    • instance mode will route traffic to all ec2 instances within cluster on NodePort opened for your service.

      service must be of type "NodePort" or "LoadBalancer" to use instance mode

    • ip mode will route traffic directly to the pod IP.

      network plugin must use secondary IP addresses on ENI for pod IP to use ip mode. e.g.

    Example instance
  • specifies the protocol used when route traffic to pods.

    Example HTTPS
  • specifies the Availability Zone that ALB will route traffic to. See Load Balancer subnets for more details.

    You must specify at least two subnets in different AZ. both subnetID or subnetName(Name tag on subnets) can be used.


    You can enable subnet auto discovery to avoid specify this annotation on every ingress. See Subnet Auto Discovery for instructions.

    Example subnet-xxxx, mySubnet
  •${action-name} Provides a method for configuring custom actions on a listener, such as for Redirect Actions.

    The action-name in the annotation must match the serviceName in the ingress rules, and servicePort must be use-annotation.


    • fixed 503 response
      apiVersion: extensions/v1beta1
      kind: Ingress
        namespace: default
        name: ingress
 '{"Type": "fixed-response", "FixedResponseConfig": {"ContentType":"text/plain", "StatusCode":"503", "MessageBody":"503 error text"}}'
          - http:
                - path: /503
                    serviceName: response-503
                    servicePort: use-annotation

Access control

Access control for LoadBalancer can be controlled with following annotations:

  • specifies whether your LoadBalancer will be internet facing. See Load balancer scheme in the AWS documentation for more details.

    Example internal
  • specifies the CIDRs that are allowed to access LoadBalancer.

    this annotation will be ignored if is specified.

  • specifies the securityGroups you want to attach to LoadBalancer.

    When this annotation is not present, the controller will automatically create 2 security groups: the first security group will be attached to the LoadBalancer and allow access from inbound-cidrs to the listen-ports. The second security group will be attached to the EC2 instance(s) and allow all TCP traffic from the first security group created for the LoadBalancer.

    both name or ID of securityGroups are supported.

    The default limit of security groups per network interface in AWS is 5. This limit is quickly reached when multiple load balancers are provisioned by the controller without this annotation, therefore it is recommended to set this annotation to a self-managed security group (or request AWS support to increase the number of security groups per network interface for your AWS account). If this annotation is specified, you should also manage the security group used by the EC2 instances to allow inbound traffic from the security group attached to the LoadBalancer.

    Example sg-xxxx, nameOfSg1, nameOfSg2


ALB supports authentication with Cognito or OIDC. See Authenticate Users Using an Application Load Balancer for more details.

  • specifies the authentication type on targets.

    Example cognito
  • specifies the cognito idp configuration.

    If you are using Amazon Cognito Domain, the UserPoolDomain should be set to the domain prefix(xxx) instead of full domain(

    Example '{"UserPoolArn":"arn:aws:cognito-idp:us-west-2:xxx:userpool/xxx", "UserPoolClientId":"xxx", "UserPoolDomain":"xxx"}'
  • specifies the oidc idp configuration.

    You need to create an secret within the same namespace as ingress to hold your OIDC clientID and clientSecret. The format of secret is as below:

    apiVersion: v1
    kind: Secret
      namespace: testcase
      name: customizedSecretName
      clientId: base64 of your plain text clientId
      clientSecret: base64 of your plain text clientSecret

    Example '{"Issuer":"xxx","AuthorizationEndpoint":"xxx","TokenEndpoint":"xxx","UserInfoEndpoint":"xxx","SecretName":"customizedSecretName"}'
  • specifies the behavior if the user is not authenticated.


    • authenticate: try authenticate with configured IDP.
    • deny: return an HTTP 401 Unauthorized error.
    • allow: allow the request to be forwarded to the target.

    Example openid
  • specifies the set of user claims to be requested from the IDP(cognito or oidc).

    Example openid
  • specifies the name of the cookie used to maintain session information

    Example custom-cookie
  • specifies the maximum duration of the authentication session, in seconds

    Example 86400

Health Check

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

  • specifies the protocol used when performing health check on targets.

    default protocol can be set via --backend-protocol flag

    Example HTTPS

  • specifies the port used when performing health check on targets.


    • set the healthcheck port to the traffic port traffic-port
    • set the healthcheck port to the NodePort(when target-type=instance) or TargetPort(when target-type=ip) of a named port my-port
    • set the healthcheck port to 80/tcp '80'

    When using target-type: instance with a service of type "NodePort", the healthcheck port can be set to traffic-port to automatically point to the correct port.

  • specifies the HTTP path when peforming health check on targets.

    Example /ping
  • specifies the interval(in seconds) between health check of an individual target.

    Example '10'
  • specifies the timeout(in seconds) during which no response from a target means a failed health check

    Example '8'
  • specifies the HTTP status code that should be expected when doing health checks against the specified health check path.


    • use single value '200'
    • use multiple values 200,201
    • use range of value 200-300
  • specifies the consecutive health checks successes required before considering an unhealthy target healthy.

    Example '2'
  • specifies the consecutive health check failures required before considering a target unhealthy.

    Example '2'


SSL support can be controlled with following annotations:

Custom attributes

Custom attributes to LoadBalancers and TargetGroups can be controlled with following annotations:

  • specifies Load Balancer Attributes that should be applied to the ALB.


    • enable access log to s3,access_logs.s3.bucket=my-access-log-bucket,access_logs.s3.prefix=my-app
    • enable deletion protection
    • enable http2 support
  • specifies Target Group Attributes which should be applied to Target Groups.


    • set the slow start duration to 5 seconds slow_start.duration_seconds=5
    • set the deregistration delay to 30 seconds deregistration_delay.timeout_seconds=30
    • enable sticky sessions stickiness.enabled=true,stickiness.lb_cookie.duration_seconds=60

Resource Tags

ALB Ingress controller will automatically apply following tags to AWS resources(ALB/TargetGroups/SecurityGroups) created.

  • ${namespace}
  • ${ingress-name}

In addition, you can use annotations to specify additional tags

  • specifies additional tags that will be applied to AWS resources created.

    Example Environment=dev,Team=test