> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gcore.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Use annotations for load balancers

> Configure Gcore Load Balancers in Managed Kubernetes with annotations for type, flavor, IP, listeners, pools, logging, and DDoS protection.

Annotations are Kubernetes [metadata fields](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) attached to objects to configure behavior beyond the standard spec. For Gcore Load Balancers in [Managed Kubernetes clusters](/cloud/kubernetes/clusters/create-a-kubernetes-cluster), 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](https://kubernetes.io/docs/reference/kubectl/generated/kubectl_annotate/) or in the Kubernetes service manifest under the `annotations` field:

```yaml theme={null}
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](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors) string in set-based or equality-based format. |
| `loadbalancer.gcore.com/pool-proxy-protocol` | Port names | Enables [Proxy Protocol](/cloud/networking/create-and-configure-a-load-balancer#pool) (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](/cloud/networking/create-and-configure-a-load-balancer#pool) (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](/cloud/logging-as-a-service/about-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](/api-reference/cloud#tag/DDOS-Protection). 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:

```yaml theme={null}
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:

```yaml theme={null}
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:

```yaml theme={null}
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
```