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

# IP Set

> Reserve and manage public IP addresses per GVC location for workloads, including binding, permissions, and configuration options.

## Overview

An IP Set reserves a static public IP address per [GVC](/reference/gvc) location, preventing the address from changing when a workload is redeployed or infrastructure is updated.

<Note>To prevent ongoing charges, IP addresses must be explicitly released once they are no longer needed.</Note>

## Binding

An IP Set can be linked to a [workload](/reference/workload) or a [GVC](/reference/gvc) through its `spec.link` property. Linking requires configuration on **both** the IP Set and the target resource — each must reference the other for the binding to take effect.

<Warning>
  The IP Set will only function if cross-linking is fully configured. The IP Set must reference the workload or GVC via `spec.link`, and the workload or GVC must reference the IP Set via its load balancer configuration.
</Warning>

### Workload

To link an IP Set to a workload, the workload must have the [direct load balancer](/reference/workload/load-balancing#direct-load-balancer) enabled.

<Tabs>
  <Tab title="YAML">
    **1. Configure the IP Set** — set `spec.link` to point to the target workload:

    ```yaml theme={null}
    kind: ipset
    name: example
    spec:
      link: /org/example-org/gvc/example-gvc/workload/example-workload
      locations:
        - name: //location/aws-us-west-2
          retentionPolicy: keep
    ```

    **2. Configure the Workload** — set `loadBalancer.direct.ipSet` to reference the IP Set:

    ```yaml theme={null}
    kind: workload
    name: example-workload
    spec:
      loadBalancer:
        direct:
          enabled: true
          ipSet: /org/example-org/ipset/example
          ports:
            - externalPort: 443
              protocol: TCP
              containerPort: 8080
    ```
  </Tab>

  <Tab title="JSON">
    **1. Configure the IP Set** — set `spec.link` to point to the target workload:

    ```json theme={null}
    {
      "kind": "ipset",
      "name": "example",
      "spec": {
        "link": "/org/example-org/gvc/example-gvc/workload/example-workload",
        "locations": [
          {
            "name": "//location/aws-us-west-2",
            "retentionPolicy": "keep"
          }
        ]
      }
    }
    ```

    **2. Configure the Workload** — set `loadBalancer.direct.ipSet` to reference the IP Set:

    ```json theme={null}
    {
      "kind": "workload",
      "name": "example-workload",
      "spec": {
        "loadBalancer": {
          "direct": {
            "enabled": true,
            "ipSet": "/org/example-org/ipset/example",
            "ports": [
              {
                "externalPort": 443,
                "protocol": "TCP",
                "containerPort": 8080
              }
            ]
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

### GVC

To link an IP Set to a GVC, the GVC must have the [dedicated load balancer](/reference/gvc#dedicated-load-balancer) enabled.

<Tabs>
  <Tab title="YAML">
    **1. Configure the IP Set** — set `spec.link` to point to the target GVC:

    ```yaml theme={null}
    kind: ipset
    name: example
    spec:
      link: //gvc/example-gvc
      locations:
        - name: //location/aws-us-west-2
          retentionPolicy: keep
    ```

    **2. Configure the GVC** — set `loadBalancer.ipSet` to reference the IP Set:

    ```yaml theme={null}
    kind: gvc
    name: example-gvc
    spec:
      loadBalancer:
        dedicated: true
        ipSet: //ipset/example
    ```
  </Tab>

  <Tab title="JSON">
    **1. Configure the IP Set** — set `spec.link` to point to the target GVC:

    ```json theme={null}
    {
      "kind": "ipset",
      "name": "example",
      "spec": {
        "link": "//gvc/example-gvc",
        "locations": [
          {
            "name": "//location/aws-us-west-2",
            "retentionPolicy": "keep"
          }
        ]
      }
    }
    ```

    **2. Configure the GVC** — set `loadBalancer.ipSet` to reference the IP Set:

    ```json theme={null}
    {
      "kind": "gvc",
      "name": "example-gvc",
      "spec": {
        "loadBalancer": {
          "dedicated": true,
          "ipSet": "//ipset/example"
        }
      }
    }
    ```
  </Tab>
</Tabs>

## Releasing

To release an IP address from a location, set the `retentionPolicy` for that location to `"free"`.

<Note>An IP address will not be released unless it is no longer in use (no workload linked, GVC location not active, etc.)</Note>

<Tabs>
  <Tab title="YAML">
    ```yaml theme={null}
    kind: ipset
    name: example
    spec:
      link: /org/example-org/gvc/example-gvc/workload/example-workload
      locations:
        - name: //location/aws-us-west-2
          retentionPolicy: free
    ```
  </Tab>

  <Tab title="JSON">
    ```json theme={null}
    {
      "kind": "ipset",
      "name": "example",
      "spec": {
        "link": "/org/example-org/gvc/example-gvc/workload/example-workload",
        "locations": [
          {
            "name": "//location/aws-us-west-2",
            "retentionPolicy": "free"
          }
        ]
      }
    }
    ```
  </Tab>
</Tabs>

## Status

Once the IP Set is initialized, its status is updated with the reserved IP address(es) for each location. The following is an example API response:

```json theme={null}
{
  "kind": "ipset",
  "name": "example",
  "spec": {
    "link": "/org/example-org/gvc/example-gvc/workload/example-workload",
    "locations": [
      {
        "name": "//location/aws-us-west-2",
        "retentionPolicy": "keep"
      }
    ]
  },
  "status": {
    "ipAddresses": [
      {
        "name": "aws-us-west-2",
        "ip": "10.20.30.40",
        "id": "eipalloc-0a1b2c3d4e5f67890",
        "state": "bound",
        "created": "2024-07-30T14:18:36.327Z"
      }
    ]
  }
}
```