Use annotations for load balancers

Annotations are Kubernetes metadata fields attached to objects to configure behavior beyond the standard spec. For Gcore Load Balancers in Managed Kubernetes clusters, annotations control type, flavor, IP addressing, listener limits, pool routing, logging, and DDoS protection. All Gcore Load Balancer annotations use the loadbalancer.gcore.com/ prefix. When an annotation is not set, the value falls back to the cluster configuration defaults. Apply annotations either with kubectl or in the Kubernetes service manifest under 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

These annotations set the Load Balancer type, flavor, shared name, and custom metadata.

Annotation	Value	Description
`loadbalancer.gcore.com/type`	`internal`, `external`	Configures the Load Balancer type. 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

These annotations assign and manage floating and reserved IP addresses for the Load Balancer.

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

These annotations set connection limits and timeout values for Load Balancer listeners.

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

These annotations control node selection, proxy protocol, and timeout settings for Load Balancer pools.

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

This annotation attaches an Advanced DDoS Protection profile to the Load Balancer.

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

The following manifests illustrate common annotation configurations.

DDoS protection profile

To assign an Advanced DDoS Protection profile to the Load Balancer, add the ddos-profile annotation to the Service manifest:

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

Enable Load Balancer logging by adding both logging annotations to the Service manifest:

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

This manifest creates an internal Load Balancer and assigns a new floating IP automatically:

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

Account settings

Developer Tools

CDN

FastEdge

Edge Cloud

AI

Gclaw

Managed DNS

Public DNS

Hosting

Colocation

Object Storage

Video Streaming

DDoS protection

Edge Proxy

WAAP

Use annotations for load balancers

Available annotations

Load Balancer configuration

IP address configuration

Listener configuration

Pool configuration

Logging configuration

DDoS protection

Examples

DDoS protection profile

Logging configuration

Internal Load Balancer with floating IP

​Available annotations

​Load Balancer configuration

​IP address configuration

​Listener configuration

​Pool configuration

​Logging configuration

​DDoS protection

​Examples

​DDoS protection profile

​Logging configuration

​Internal Load Balancer with floating IP

Available annotations

Load Balancer configuration

IP address configuration

Listener configuration

Pool configuration

Logging configuration

DDoS protection

Examples

DDoS protection profile

Logging configuration

Internal Load Balancer with floating IP