Use annotations for load balancers

Annotations are a way to add custom, non-identifiable metadata to objects. They configure additional behavior for Load Balancers service in Kubernetes clusters beyond the standard configuration offerings. Learn more about annotations in the official Kubernetes documentation.

The load balancer is configured through annotations with some fallbacks to the configuration file for default values. All annotations use the loadbalancer.gcore.com/ prefix.

Add annotations via the command line (kubectl) or the Kubernetes service manifest using the annotations field:

metadata:
  annotations:
    loadbalancer.gcore.com/type: "external"

Available annotations

The following annotations apply to Load Balancers created in Gcore Managed Kubernetes.

Load balancer configuration

Annotation	Value	Description
loadbalancer.gcore.com/type	internal, external	Configures the type of load balancer. Determines whether the load balancer is created in a private or public network. Default is internal. Changing load balancer type is not supported.
loadbalancer.gcore.com/flavor	lb1-1-2, lb1-4-8	The load balancer flavor name.
loadbalancer.gcore.com/shared-load-balancer-name	String	Shared load balancer name. Allows sharing a single load balancer instance between multiple Service resources.
metadata.loadbalancer.gcore.com/<key>	String	Sets custom metadata key-value pairs on the load balancer.

IP address configuration

Annotation	Value	Description
loadbalancer.gcore.com/floating-ip	IP address or ""	Specifies a floating IP address for a private load balancer. The value can be an existing floating IP address to assign, or "" to create a new one. Only supported for load balancers on internal network.
loadbalancer.gcore.com/floating-ip-cleanup	true, false	When set to true, the floating IP assigned to the load balancer is cleaned up after the Service is deleted.
loadbalancer.gcore.com/reserved-ip	IP address	Specifies the reserved fixed IP address of a load balancer. The value must be an existing reserved fixed IP address. For backwards compatibility, .spec.loadBalancerIP field is consulted if this annotation is not present.
loadbalancer.gcore.com/reserved-ip-cleanup	true, false	When set to true, the reserved fixed IP assigned to the load balancer is cleaned up after the Service is deleted. Default is false.

Listener configuration

Annotation	Value	Description
loadbalancer.gcore.com/listener-connection-limit	Integer	Sets the listener connection limit. When the annotation is removed, the previously set value persists.
loadbalancer.gcore.com/listener-timeout-client-data	Duration (30s, 1m)	Sets the timeout-client-data value for load balancer listeners. When removed, the previously set value persists.
loadbalancer.gcore.com/listener-timeout-member-connect	Duration (30s, 1m)	Sets the timeout-member-connect value for load balancer listeners. When removed, the previously set value persists.
loadbalancer.gcore.com/listener-timeout-member-data	Duration (30s, 1m)	Sets the timeout-member-data value for load balancer listeners. When removed, the previously set value persists.

Pool configuration

Annotation	Value	Description
loadbalancer.gcore.com/node-selector	Label selector	Restricts which Nodes are added to load balancer pools. Accepts a Kubernetes label selector string in set-based or equality-based format.
loadbalancer.gcore.com/pool-proxy-protocol	Port names	Enables Proxy Protocol (v1) on load balancer pools. Accepts a list of comma-separated service port names for which PROXY protocol should be used. Service ports with UDP and other unsupported protocols are ignored.
loadbalancer.gcore.com/pool-proxyv2-protocol	Port names	Enables Proxy Protocol (v2) on load balancer pools. Accepts a list of comma-separated service port names for which PROXYV2 protocol should be used. Service ports with UDP and other unsupported protocols are ignored.
loadbalancer.gcore.com/pool-timeout-client-data	Duration (30s, 1m)	Sets the timeout-client-data value for load balancer pools. When removed, the previously set value persists.
loadbalancer.gcore.com/pool-timeout-member-connect	Duration (30s, 1m)	Sets the timeout-member-connect value for load balancer pools. When removed, the previously set value persists.
loadbalancer.gcore.com/pool-timeout-member-data	Duration (30s, 1m)	Sets the timeout-member-data value for load balancer pools. When removed, the previously set value persists.

Logging configuration

To enable pushing logs to Logging as a Service, both logging-topic-name and logging-destination-region-id annotations must be set.

Annotation	Value	Description
loadbalancer.gcore.com/logging-topic-name	String	LaaS topic name for pushing logs.
loadbalancer.gcore.com/logging-destination-region-id	Integer	LaaS destination region ID for pushing logs.
loadbalancer.gcore.com/logging-retention-policy-period	Integer	Log retention policy for the LaaS topic (in days).

DDoS protection

Annotation	Value	Description
loadbalancer.gcore.com/ddos-profile	JSON string	An Advanced DDoS Protection profile configuration. The value format is the same as supported by the DDoS Protection API. Only profile_template and fields parameters are required. The profile_template_name parameter is optional, while ip_address, resource_id, and resource_type are inferred automatically.

Examples

DDoS protection profile

To assign an Advanced DDoS Protection profile to the cluster, add the ddos-profile annotation:

apiVersion: v1
kind: Service
metadata:
  annotations:
    loadbalancer.gcore.com/ddos-profile: |
      {"profile_template":65,"fields":[{"base_field":272,"field_value":40}]}
  labels:
    app: grafana
  name: grafana
  namespace: default
spec:
  ports:
  - port: 80
    protocol: TCP
    targetPort: 80
  selector:
    app: grafana
  type: LoadBalancer

Replace the sample values (65, 272, and 40) with the appropriate values for the project.

Logging configuration

To enable logging for the cluster, add both logging annotations:

apiVersion: v1
kind: Service
metadata:
  annotations:
    loadbalancer.gcore.com/logging-topic-name: my-logs
    loadbalancer.gcore.com/logging-destination-region-id: "15"
  labels:
    app: grafana
  name: grafana
  namespace: default
spec:
  ports:
  - port: 80
    protocol: TCP
    targetPort: 80
  selector:
    app: grafana
  type: LoadBalancer

Replace my-logs and 15 with the appropriate LaaS topic name and destination region ID for the project.

Internal load balancer with floating IP

To create an internal load balancer with automatic floating IP assignment:

apiVersion: v1
kind: Service
metadata:
  annotations:
    loadbalancer.gcore.com/type: "internal"
    loadbalancer.gcore.com/floating-ip: ""
    loadbalancer.gcore.com/floating-ip-cleanup: "true"
  name: web-service
  namespace: default
spec:
  ports:
  - port: 443
    protocol: TCP
    targetPort: 8443
  selector:
    app: web
  type: LoadBalancer