tencent cloud

Ingress Annotation
Download PDF
Last updated: 2025-08-14 11:33:58
Ingress Annotation
Last updated: 2025-08-14 11:33:58
Download PDF

Overview

View the ingress-controller version of the current cluster: kubectl -n kube-system get cm tke-ingress-controller-config -o jsonpath='{.data.VERSION}'

List

Specifying Ingress Type

Name: kubernetes.io/ingress.class
Description:
Specifies the ingress type. If not specified, Tencent Kubernetes Engine (TKE) assumes the value is qcloud, indicating that this ingress is of CLB type.
Type: string
Version requirement: >=v1.0.0
Example:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    kubernetes.io/ingress.class: 'qcloud'
  name: example
spec:
  rules:
  - host: example.com
    http:
      paths:
      - backend:
          service:
            name: example
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific


CLB Instance ID

Name: kubernetes.io/ingress.qcloud-loadbalance-id
Description:
Read-only annotation. The component provides the LoadBalanceId referenced by the current Ingress.
Type: string
Version requirement: >=v1.0.0

Reusing Existing CLB Instances

Name: kubernetes.io/ingress.existLbId
Description:
When an existing CLB instance is used, pay attention to the impact of different usage methods on Tencent Cloud tags.
Type: string
Version requirement: >=v1.0.0
Example:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    kubernetes.io/ingress.existLbId: 'lb-6swtxxxx'
  name: example
spec:
  rules:
  - host: example.com
    http:
      paths:
      - backend:
          service:
            name: example
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific


Creating a Private Network CLB Instance

Name: kubernetes.io/ingress.subnetId
Description:
Create a private network CLB instance in the specified subnet.
Type: enum
Version requirement: >=v1.0.0
Example:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    kubernetes.io/ingress.subnetId: 'subnet-xxx'
  name: example
spec:
  rules:
  - host: example.com
    http:
      paths:
      - backend:
          service:
            name: example
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific


Specifying the Payment Type

Name: kubernetes.io/ingress.internetChargeType
Description:
The payment type of the CLB instance can only be configured during creation and cannot be changed after creation. This annotation is invalid if the payment type is modified after creation.
Specifies the payment type of CLB when a CLB instance is created. Use this capability together with the annotation kubernetes.io/ingress.internetMaxBandwidthOut.
Valid values:
BANDWIDTH_POSTPAID_BY_HOUR: postpayment by bandwidth on an hourly basis
TRAFFIC_POSTPAID_BY_HOUR: postpayment by traffic on an hourly basis
Type: enum
Version requirement: >=v1.0.0
Example:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    kubernetes.io/ingress.internetChargeType: 'BANDWIDTH_POSTPAID_BY_HOUR'
    kubernetes.io/ingress.internetMaxBandwidthOut: '10'
  name: example
spec:
  rules:
  - host: example.com
    http:
      paths:
      - backend:
          service:
            name: example
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific


Specifying the Public Network Bandwidth Limit

Name: kubernetes.io/ingress.internetMaxBandwidthOut
Description:
CLB bandwidth settings. Currently, it can only be configured during creation and cannot be modified after creation. This annotation is invalid if the bandwidth is modified after creation.
Maximum outbound bandwidth of CLB when the specified CLB instance is created. It is only effective for LBs with public network attributes. Use this capability together with the annotation kubernetes.io/ingress.internetChargeType.
Value range: [1, 2048] Mbps.
Type: int
Version requirement: >=v1.0.0
Example:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    kubernetes.io/ingress.internetMaxBandwidthOut: '10'
    kubernetes.io/ingress.internetChargeType: 'TRAFFIC_POSTPAID_BY_HOUR'
  name: example
spec:
  rules:
  - host: example.com
    http:
      paths:
      - backend:
          service:
            name: example
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific


CLB Exetnsion Parameters

Name: kubernetes.io/ingress.extensiveParameters
Description:
Specifies the parameters during CLB creation. Currently, these parameters can only be configured during CLB creation and cannot be modified after creation. This annotation is invalid if parameters are modified after creation.
For details, see CreateLoadBalancer. Add custom parameters for creating a CLB instance.
Type: json
Version requirement: >=v1.0.0
Example:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    kubernetes.io/ingress.extensiveParameters: '{"VipIsp":"CTCC"}'
  name: example
spec:
  rules:
  - host: example.com
    http:
      paths:
      - backend:
          service:
            name: example
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific


Enabling Bypass Backend Security Group

Name: ingress.cloud.tencent.com/pass-to-target
Description:
Whether to enable bypass backend security group for CLB. Allow the traffic between CLB and CVM by default; traffic from CLB only needs to be verified by the security group on CLB.
Note:
See the limitations for using security groups of CLB in Configuring CLB Security Group.
Normally, the ability to bind security groups is requird. Corresponding Annotation: ingress.cloud.tencent.com/security-groups.
Type: bool
Version requirement: >=v1.8.3
Example:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    ingress.cloud.tencent.com/pass-to-target: 'true'
  name: example
spec:
  rules:
  - host: example.com
    http:
      paths:
      - backend:
          service:
            name: example
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific


Binding/Unbinding Security Groups

Name: ingress.cloud.tencent.com/security-groups
Note:
Bind a security group to CLB. A single CLB can bind up to 5 security groups.
Note:
See the limitations for using security groups of CLB in Configuring CLB Security Group.
Enabling bypass backend security group capability is required. Allow the traffic between CLB and CVM by default; traffic from CLB only needs to be verified by the security group on CLB. Corresponding Annotation: ingress.cloud.tencent.com/pass-to-target.
For Using an Existing CLB for Direct Pod Connection scenario, this annotation can not be used to configure a security group for CLB.
Type: string
Version requirement: >=v1.8.3
Example:
Bind security group:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    ingress.cloud.tencent.com/security-groups: 'sg-xxxxx,sg-yyyyy,sg-zzzzz'
  name: example
spec:
  rules:
  - host: example.com
    http:
      paths:
      - backend:
          service:
            name: example
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific
Unbind partial security groups:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    ingress.cloud.tencent.com/security-groups: 'sg-xxxxx'
  name: example
spec:
  rules:
  - host: example.com
    http:
      paths:
      - backend:
          service:
            name: example
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific
Unbind all security groups (>=v2.5.2):
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    ingress.cloud.tencent.com/security-groups: ''
  name: example
spec:
  rules:
  - host: example.com
    http:
      paths:
      - backend:
          service:
            name: example
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific

Modification Protection

Name: ingress.cloud.tencent.com/modification-protection
Description:
Configure CLB modification protection. Once enabled, the attributes of the CLB instance cannot be modified through the CLB console or API.
Type: bool
Version requirement: >=v1.7.3
Example:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    ingress.cloud.tencent.com/modification-protection: 'true'
  name: example
spec:
  rules:
  - host: example.com
    http:
      paths:
      - backend:
          service:
            name: example
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific


Custom Listening Port

Name: ingress.cloud.tencent.com/listen-ports
Description:
Customize the listening port of Ingress.
By default, HTTP uses port 80 and HTTPS uses port 443. This Annotation can be used to customize the ports listened by CLB corresponding to Ingress. Customizing one or more ports for HTTP and HTTPS protocols respectively is supported.
Note:
If you need to use automatic redirection (ingress.cloud.tencent.com/auto-rewrite: "true"), it is valid only when both HTTP:80 and HTTPS:443 exist.
Type: json
Version requirement: >=v2.4.1
Example:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    ingress.cloud.tencent.com/listen-ports: '[{"HTTP": 80}, {"HTTPS": 443}, {"HTTP": 8080}, {"HTTPS": 8443}]'
  name: example
spec:
  rules:
  - host: example.com
    http:
      paths:
      - backend:
          service:
            name: example
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific


Using Extended Configuration

Name: ingress.cloud.tencent.com/tke-service-config
Description:
Configure CLB through tke-service-config.
Type: string
Version requirement: >=v1.3.0
Example:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    ingress.cloud.tencent.com/tke-service-config: 'config-name'
  name: example
spec:
  rules:
  - host: example.com
    http:
      paths:
      - backend:
          service:
            name: example
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific


Using Automatically Generated Extended Configuration

Name: ingress.cloud.tencent.com/tke-service-config-auto
Description:
This annotation can be used for automatic creation of TkeServiceConfig, and you can modify configurations as needed.
Type: bool
Version requirement: >=v1.3.0
Example:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    ingress.cloud.tencent.com/tke-service-config-auto: 'true'
  name: example
spec:
  rules:
  - host: example.com
    http:
      paths:
      - backend:
          service:
            name: example
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific


Automatic Redirection

Name: ingress.cloud.tencent.com/auto-rewrite
Description:
Provide automatic redirection capability for HTTP port, all forwarding rules declared on HTTPS port will create corresponding redirection rules.
For details, see TKE Ingress Redirection.
Note:
If the automatic redirection feature is previously enabled but now it needs to be disabled, explicitly set the annotation to "false" instead of directly deleting the annotation.
Type: bool
Version requirement: >=v1.3.0
Example:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    ingress.cloud.tencent.com/auto-rewrite: 'true'
    ingress.cloud.tencent.com/rewrite-support: "true"
  name: example
spec:
  rules:
  - host: example.com
    http:
      paths:
      - backend:
          service:
            name: example
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific


Supporting Redirection

Name: ingress.cloud.tencent.com/rewrite-support
Description:
Enable redirection support, and implement manual redirection through using kubernetes.io/ingress.http-rules and kubernetes.io/ingress.https-rules.
Note:
If the automatic redirection feature is previously enabled but now it needs to be disabled, explicitly set the annotation to "false" instead of directly deleting the annotation.
Type: bool
Version requirement: >=v1.3.0
Example:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    ingress.cloud.tencent.com/rewrite-support: 'true'
  name: example
spec:
  rules:
  - host: example.com
    http:
      paths:
      - backend:
          service:
            name: example
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific


Mixed Use of Protocols

Name: kubernetes.io/ingress.rule-mix
Description:
Supports configuration of mixed use of protocols, supports forwarding through both HTTP and HTTPS simultanepously, and supports manual configuration of redirection rules.
Type: bool
Version requirement: >=v1.3.0
Example:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    kubernetes.io/ingress.rule-mix: 'true'
    kubernetes.io/ingress.http-rules: '[{"host":"example.com","path":"/","backend":{"serviceName":"example","servicePort":"80"}}]'
    kubernetes.io/ingress.https-rules: '[{"host":"example.com","path":"/","backend":{"serviceName":"example","servicePort":"80"}}]'
  name: example
spec:
  rules:
  - host: example.com
    http:
      paths:
      - backend:
          service:
            name: example
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific


Configuring Http Forwarding Rules

Name: kubernetes.io/ingress.http-rules
Note:
Configures HTTP forwarding rules and supports manual configuration of redirection rules.
Type: json
Version requirement: >=v1.3.0
Example:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    kubernetes.io/ingress.http-rules: '[{"host":"example.com","path":"/","backend":{"serviceName":"example","servicePort":"80"}}]'
    kubernetes.io/ingress.rule-mix: "true"
  name: example
spec:
  rules:
  - host: example.com
    http:
      paths:
      - backend:
          service:
            name: example
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific


Configuring Https Forwarding Rules

Name: kubernetes.io/ingress.https-rules
Description:
Configures HTTPS forwarding rules and supports manual configuration of redirection rules.
Type: json
Version requirement: >=v1.3.0
Example:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    kubernetes.io/ingress.https-rules: '[{"host":"example.com","path":"/","backend":{"serviceName":"example","servicePort":"80"}}]'
    kubernetes.io/ingress.rule-mix: "true"
  name: example
spec:
  rules:
  - host: example.com
    http:
      paths:
      - backend:
          service:
            name: example
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific


Enabling Direct Connection

Name: ingress.cloud.tencent.com/direct-access
Description:
Supports layer-7 direct connection for user CLB. Pay attention to service dependencies accessed by direct connection under various networks.
Type: bool
Version requirement: >=v1.3.0
Example:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    ingress.cloud.tencent.com/direct-access: 'true'
  name: example
spec:
  rules:
  - host: example.com
    http:
      paths:
      - backend:
          service:
            name: example
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific


Graceful Shutdown

Name: ingress.cloud.tencent.com/enable-grace-shutdown
Description:
Supports graceful shutdown in the CLB direct connection mode. When a Pod is deleted, it has DeletionTimestamp and its status is set to Terminating. At this point, the weight of the CLB to that Pod should be adjusted to 0.
Supported only in direct connection mode. Use this capability together with ingress.cloud.tencent.com/direct-access.
Deprecated starting from v2.2.0. It is enabled by default.
For details, see Graceful Ingress Shutdown.
Type: bool
Version requirement: >=v1.5.0
Example:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    ingress.cloud.tencent.com/enable-grace-shutdown: 'true'
    ingress.cloud.tencent.com/direct-access: 'true'
  name: example
spec:
  rules:
  - host: example.com
    http:
      paths:
      - backend:
          service:
            name: example
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific


Graceful Shutdown for Tkex

Name: ingress.cloud.tencent.com/enable-grace-shutdown-tkex
Description:
Supports graceful exit of CLB direct connection mode. If the status of endpoints in the Endpoint object is not-ready, set the backend weight of CLB in the not-ready status to 0.
Supported only in direct connection mode. Use this fature together with ingress.cloud.tencent.com/direct-access.
Deprecated starting from v2.2.0. It is enabled by default.
For details, see Graceful Ingress Shutdown.
Type: bool
Version requirement: >=v1.5.0
Example:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    ingress.cloud.tencent.com/enable-grace-shutdown-tkex: 'true'
    ingress.cloud.tencent.com/direct-access: 'true'
  name: example
spec:
  rules:
  - host: example.com
    http:
      paths:
      - backend:
          service:
            name: example
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific


Graceful Deletion

Name: ingress.cloud.tencent.com/enable-grace-deletion
Description:
Once enabled, kubelet waits for the controller to adjust the weights of all pods to 0 and then deletes the CLB RS.
Supported only in direct connection mode. Use this capability together with ingress.cloud.tencent.com/direct-access.
Type: bool
Version requirement: >=v2.4.0
Example:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    ingress.cloud.tencent.com/enable-grace-deletion: 'true'
    ingress.cloud.tencent.com/direct-access: 'true'
  name: example
spec:
  rules:
  - host: example.com
    http:
      paths:
      - backend:
          service:
            name: example
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific


Customizing Backend Weight

Name: ingress.cloud.tencent.com/lb-rs-weight
Description:
Supports customizing backend weights and setting the default weight as well as weights for stateful services.
Type: json
Version requirement: >=v1.6.0
Example:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    ingress.cloud.tencent.com/lb-rs-weight: '{"defaultWeight":10,"groups":[{"key":{"proto":"TCP","port":80},"statefulSets":[{"name":"ti-ai-gateway-gz-shared-st-v1","weights":[{"weight":0,"podIndexes":[0]}]},{"name":"ti-ai-gateway-gz-shared-st-v2","weights":[{"weight":10,"podIndexes":[0]}]}]}]}'
  name: example
spec:
  rules:
  - host: example.com
    http:
      paths:
      - backend:
          service:
            name: example
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific



Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No

Feedback