<a id="manage-ip-groups"></a>

# Manage IP Groups on Confluent Cloud

IP groups are collections of source [CIDR blocks](../../../_glossary.md#term-CIDR-block) used to
define access control policies in Confluent Cloud. IP groups are used in IP filtering
to help organize and manage network access rules based on specific sets of IP
addresses.

IP groups provide several key benefits for organizing and managing your
network access controls in Confluent Cloud:

* **Reusable Address Collections**: Create reusable groups of IP addresses
  that can be referenced across multiple IP filters, eliminating the need to
  repeatedly specify the same IP addresses.
* **Simplified Updates**: Update IP addresses in one central location.
  Updates to an IP group automatically apply to all IP filters using that
  group, reducing maintenance overhead and potential configuration errors.
* **Logical Organization**: Group IP addresses based on meaningful
  categories like office locations, data centers, or business units for
  better organization and management of network access rules.
* **Reduced Configuration Complexity**: Instead of managing long lists of
  individual IP addresses across multiple filters, use IP groups to create a
  more maintainable and scalable configuration.

The following sections describe how to use the Confluent Cloud Console,
Confluent CLI, and Confluent Cloud APIs to create, update, describe, list, and
delete IP groups.

## Prerequisites

To manage IP groups in the Confluent Cloud Console, you must meet the following
prerequisites:

* A Confluent Cloud account with the [OrganizationAdmin](../rbac/predefined-rbac-roles.md#organizationadmin-role) role to manage IP
  groups for your organization.
* A list of IPv4 CIDR blocks that represent the trusted source networks you want
  to allow to access Confluent Cloud resources. A list of CIDR blocks is required to
  define an IP group.
* To use the `confluent iam ip-group` CLI command, you must have
  Confluent CLI version 4.18.0 or later.

<a id="specify-cidr-blocks-for-ip-groups"></a>

## Specify CIDR blocks for IP groups

A CIDR block is a 32-bit IP address and a netmask. For example,
`192.168.1.0/24` is a CIDR block that includes all IP addresses from
`192.168.1.0` to `192.168.1.255`. The netmask `24` indicates that the
first 24 bits of the provided CIDR block are used to match incoming
requests.

To specify a single IP address as a CIDR block, use the `/32` suffix. For
example, if the IP address is `64.235.154.88`, to add it as a CIDR block,
specify the CIDR block as `64.235.154.88/32`. This is useful for creating
an IP group that includes a single IP address that you want to ensure is
allowed access.

When you create an IP filter for management, ensure the IP groups
you select include all the locations you will use for further IP filtering
configuration. One simple way to ensure that an IP filter includes the IP address
that you are using to access Confluent Cloud is to specify your current IP address as a
CIDR block in an IP group and then select that IP group in your first IP filter.
If you do not correctly set up this filter, you could unintentionally limit
access to managing your resources.

<a id="no-public-networks-group"></a>

### Block public networks

If you want to block all access from public networks, you can do this directly
when creating your IP filter. For more information, see [Block all public networks](manage-ip-filters.md#use-no-public-networks-group).

<a id="create-ip-group"></a>

## Create an IP group

An administrator creates an IP group by adding IPv4 CIDR blocks that define
a set of IP addresses. IP groups are used to restrict access to Confluent Cloud
resources.

### Confluent Cloud Console

1. Go to the **IP filtering** tab on the **Accounts & access** page
   at [https://confluent.cloud/settings/org/ip-filtering](https://confluent.cloud/settings/org/ip-filtering).

   The **IP filtering** page, with the **IP group** view, appears.
2. Click **Add IP group**. The **Add IP group** page appears.
3. In the **Add IP group** page, enter these details:
   \* **IP group name**: The descriptive name of your group.
   \* **IPv4 CIDR block**: The IP address range for the
   IP group. If you need to add additional CIDR blocks, click **Add CIDR block**.
4. Click **Save** to save the IP group. The **Accounts & access** page
   reappears displaying the IP group name, IP group ID, and CIDR blocks
   in the **IP groups** section.

Next, create an IP filter to restrict access to Confluent Cloud resources. For more, see [Create an IP filter](manage-ip-filters.md#create-ip-filter).

### Confluent CLI

Use the `confluent iam ip-group create` command
([Confluent CLI reference](https://docs.confluent.io/confluent-cli/current/command-reference/iam/ip-group/confluent_iam_ip-group_create.html))
to create an IP group. The `--cidr-blocks` flag is required. The IPv4
CIDR blocks must be formatted as a comma-separated
list of one or more IPv4 CIDR blocks with no spaces between the CIDR blocks.

For example, the following command creates an IP group named
`NYC Office` that includes two CIDR blocks, `168.150.200.0/24`
and `147.150.200.0/24`.

```shell
confluent iam ip-group create "NYC Office" \
  --cidr-blocks 168.150.200.0/24,147.150.200.0/24
```

The following example shows the response to the request. The Confluent CLI
sorts the CIDR blocks before printing them.

```text
+-------------+--------------------------------+
| ID          | ipg-34mq3                      |
| Name        | NYC Office                     |
| CIDR blocks | 147.150.200.0/24,              |
|             | 168.150.200.0/24               |
+-------------+--------------------------------+
```

### Confluent Cloud APIs

To make a request to create an IP group, use the `POST /iam/v2/ip-groups/` API endpoint (see
[Create an IP Group](/cloud/current/api.html#tag/IP-Groups-(iamv2)/operation/createIamV2IpGroup)).

For example, the following request creates an IP group named
`NYC Office` that includes two CIDR blocks, `168.150.200.0/24` and `147.150.200.0/24`.

```shell
curl --request POST \
  --url https://api.confluent.cloud/iam/v2/ip-groups \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH' \
  --header 'content-type: application/json' \
  --data '{"group_name":"NYC Office","cidr_blocks":["168.150.200.0/24","147.150.200.0/24"]}'
```

The following example shows the response to the request:

```json
{
  "api_version": "iam/v2",
  "cidr_blocks": [
    "168.150.200.0/24",
    "147.150.200.0/24"
  ],
  "group_name": "NYC Office",
  "id": "ipg-ek49z",
  "kind": "IpGroup",
  "metadata": {
    "created_at": "2025-03-15T23:36:34.281728Z",
    "resource_name": "crn://confluent.cloud/organization=c9bc3446-0754-4d26-9fe5-c24a58e96a01/ip-group=ipg-ek49z",
    "self": "https://confluent.cloud/iam/v2/ip-groups/ipg-ek49z",
    "updated_at": "2025-03-15T23:36:34.281728Z"
  }
}
```

### Terraform

Create an IP group by using the Confluent Terraform provider. For more
information, see [confluent_ip_group Resource](https://registry.terraform.io/providers/confluentinc/confluent/latest/docs/resources/confluent_ip_group).

<a id="update-ip-group"></a>

## Update an IP group

### Confluent Cloud Console

1. Go to the **IP filtering** tab on the **Accounts & access** page
   at [https://confluent.cloud/settings/org/ip-filtering](https://confluent.cloud/settings/org/ip-filtering).

   The **IP filtering** page, with the **IP groups** view, appears.
2. In the table of IP groups, click the name of the IP group under **Name**
   that you want to update.
3. Click **Edit IP group**.
4. Within the window, you can make these changes to your IP group:
   * Edit the current **IP group name**.
   * Edit an existing **CIDR block**.
   * Click **Add CIDR block** to add a new CIDR block to the IP group, or click
     x to the right of a CIDR block to remove the CIDR block from the IP group.
5. Click **Save** to save your IP group updates.

The IP group is updated and the **Accounts & access** page reappears
displaying the IP group name, IP group ID, and CIDR blocks in the **IP groups**
section.

### Confluent CLI

Use the `confluent iam ip-group update` command
([Confluent CLI reference](https://docs.confluent.io/confluent-cli/current/command-reference/iam/ip-group/confluent_iam_ip-group_update.html))
to update an IP group. You must specify at least one of the `--name`,
`--add-cidr-blocks`, or `--remove-cidr-blocks` flags.

For example, the following command updates the `ipg-12345` group, changing
the IP group name to `SF Office`.

```shell
confluent iam ip-group update ipg-12345 \
  --name "SF Office"
```

The following example shows the response to the request:

```text
+-------------+--------------------------------+
| ID          | ipg-12345                      |
| Name        | SF Office                      |
| CIDR blocks | 168.150.200.0/24               |
+-------------+--------------------------------+
```

To add a CIDR block to the IP group, use the `--add-cidr-blocks` flag.

For example, the following command adds the `147.150.200.0/24` CIDR
block to the `SF Office` IP group.

```shell
confluent iam ip-group update ipg-12345 \
  --add-cidr-blocks 147.150.200.0/24
```

The following example shows the response to the request:

```text
+-------------+--------------------------------+
| ID          | ipg-12345                      |
| Name        | SF Office                      |
| CIDR blocks | 147.150.200.0/24,              |
|             | 168.150.200.0/24               |
+-------------+--------------------------------+
```

To remove a CIDR block from the IP group, use the `--remove-cidr-blocks`
flag.

For example, the following command removes the `168.150.200.0/24`
CIDR block from the `SF Office` IP group.

```shell
confluent iam ip-group update ipg-12345 \
  --remove-cidr-blocks 168.150.200.0/24
```

The following example shows the response to the request:

```text
+-------------+--------------------------------+
| ID          | ipg-12345                      |
| Name        | SF Office                      |
| CIDR blocks | 147.150.200.0/24               |
+-------------+--------------------------------+
```

You can’t remove every CIDR block from an IP group. If you do, the
command fails with `Cannot remove all CIDR blocks from IP group`.

### Confluent Cloud APIs

To make a request to update an IP group, use the `PATCH /iam/v2/ip-groups/{id}` API endpoint (see
[Update an IP Group](/cloud/current/api.html#tag/IP-Groups-(iamv2)/operation/updateIamV2IpGroup)).

#### NOTE
The `PATCH` method replaces the `cidr_blocks` list with the
list you send. Include the full set of CIDR blocks that the IP group
should have after the update, not just the blocks that you want to add.

For example, the following request updates the `ipg-12345` IP group, changing
the IP group name to `SF Office`.

```shell
curl --request PATCH \
  --url 'https://api.confluent.cloud/iam/v2/ip-groups/ipg-12345' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH' \
  --header 'content-type: application/json' \
  --data '{"group_name":"SF Office","cidr_blocks":["192.168.0.0/24","192.168.7.0/24"]}'
```

The following example shows the response to the request:

```json
{
  "api_version": "iam/v2",
  "kind": "IpGroup",
  "id": "ipg-12345",
  "metadata": {
    "self": "https://api.confluent.cloud/iam/v2/ip-groups/ipg-12345",
    "resource_name": "crn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/ip-group=ipg-12345",
    "created_at": "2006-01-02T15:04:05-07:00",
    "updated_at": "2006-01-02T15:04:05-07:00"
  },
  "group_name": "SF Office",
  "cidr_blocks": [
    "192.168.0.0/24",
    "192.168.7.0/24"
  ]
}
```

<a id="describe-ip-group"></a>

## Describe an IP group

### Confluent Cloud Console

1. Go to the **IP filtering** tab on the **Accounts & access** page
   at [https://confluent.cloud/settings/org/ip-filtering](https://confluent.cloud/settings/org/ip-filtering).

   The **IP filtering** page, with the **IP groups** view, appears.
2. Click the name of the IP group that you want to view. The IP group
   details page appears, showing the IP group name, IP group ID, and
   CIDR blocks.

To return to the list of IP groups, click “IP filtering” in the breadcrumb
navigation at the top of the page.

### Confluent CLI

Use the `confluent iam ip-group describe` command
([Confluent CLI reference](https://docs.confluent.io/confluent-cli/current/command-reference/iam/ip-group/confluent_iam_ip-group_describe.html#))
to describe an IP group. For example, the following command shows the
details about the `SF Office` IP group, with the ID `ipg-12345`:

```shell
confluent iam ip-group describe ipg-12345
```

The following example shows the response to the request:

```text
+-------------+--------------------------------+
| ID          | ipg-12345                      |
| Name        | SF Office                      |
| CIDR blocks | 147.150.200.0/24,              |
|             | 168.150.200.0/24               |
+-------------+--------------------------------+
```

### Confluent Cloud APIs

To make a request to describe, or read, an IP group, use the `GET /iam/v2/ip-groups/{id}` API endpoint (see
[Read an IP Group](/cloud/current/api.html#tag/IP-Groups-(iamv2)/operation/getIamV2IpGroup)).

For example, the following request describes the `ipg-12345` IP group.

```shell
curl --request GET \
  --url 'https://api.confluent.cloud/iam/v2/ip-groups/ipg-12345' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'
```

The following example shows the response to the request:

```json
{
  "api_version": "iam/v2",
  "kind": "IpGroup",
  "id": "ipg-12345",
  "metadata": {
    "self": "https://api.confluent.cloud/iam/v2/ip-groups/ipg-12345",
    "resource_name": "crn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/ip-group=ipg-12345",
    "created_at": "2006-01-02T15:04:05-07:00",
    "updated_at": "2006-01-02T15:04:05-07:00"
  },
  "group_name": "SF Office",
  "cidr_blocks": [
    "192.168.0.0/24",
    "192.168.7.0/24"
  ]
}
```

<a id="list-ip-group"></a>

## List IP groups

### Confluent Cloud Console

1. Go to the **IP filtering** tab on the **Accounts & access** page
   at [https://confluent.cloud/settings/org/ip-filtering](https://confluent.cloud/settings/org/ip-filtering).

The IP groups are displayed showing IP group names and IP group IDs. Click on an IP group name to
see the details view, which shows the IP group name, IP group ID, and CIDR blocks.

### Confluent CLI

Use the `confluent iam ip-group list` command
([Confluent CLI reference](https://docs.confluent.io/confluent-cli/current/command-reference/iam/ip-group/confluent_iam_ip-group_list.html))
to list IP groups.

For example, the following command lists the IP groups.

```shell
confluent iam ip-group list
```

The following example shows the response to the request:

```text
     ID     |      Name              |          CIDR blocks
------------+----------------------+-----------------------------------
  ipg-34mq3 | San Francisco Office | 168.150.200.0/24, 147.150.200.0/24
  ipg-12345 | Madrid Office        | 1.2.3.4/32
```

### Confluent Cloud APIs

To retrieve a list of IP groups, use the `GET /iam/v2/ip-groups` API endpoint. For more information, see
[List of IP Groups](/cloud/current/api.html#tag/IP-Groups-(iamv2)/operation/listIamV2IpGroups).
Results are paginated. Use the `page_size` query parameter, which
defaults to `25` and has a maximum of `100`, and the `page_token`
query parameter to page through the results.

For example, the following request lists the IP groups.

```shell
curl --request GET \
  --url https://api.confluent.cloud/iam/v2/ip-groups \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'
```

```json
{
  "api_version": "iam/v2",
  "kind": "IpGroupList",
  "metadata": {
    "first": "https://api.confluent.cloud/iam/v2/ip-groups",
    "last": "https://api.confluent.cloud/iam/v2/ip-groups?page_token=bcAOehAY8F16YD84Z1wT",
    "prev": "https://api.confluent.cloud/iam/v2/ip-groups?page_token=YIXRY97wWYmwzrax4dld",
    "next": "https://api.confluent.cloud/iam/v2/ip-groups?page_token=UvmDWOB1iwfAIBPj6EYb",
    "total_size": 123
  },
  "data": [
    {
      "api_version": "iam/v2",
      "kind": "IpGroup",
      "id": "ipg-73zpe",
      "metadata": {
        "self": "https://api.confluent.cloud/iam/v2/ip-groups/ipg-73zpe",
        "resource_name": "crn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/ip-group=ipg-73zpe",
        "created_at": "2023-10-27T20:35:53.476383Z",
        "updated_at": "2023-11-28T18:13:57.715874Z"
      },
      "group_name": "New York Office",
      "cidr_blocks": [
        "168.150.200.0/24",
        "147.150.200.0/24"
      ]
    },
    {
      "api_version": "iam/v2",
      "kind": "IpGroup",
      "id": "ipg-31j53",
      "metadata": {
        "self": "https://api.confluent.cloud/iam/v2/ip-groups/ipg-31j53",
        "resource_name": "crn://confluent.cloud/organization=9bb441c4-edef-46ac-8a41-c49e44a3fd9a/ip-group=ipg-31j53",
        "created_at": "2023-10-27T20:37:13.535279Z",
        "updated_at": "2023-11-28T18:13:57.715874Z"
      },
      "group_name": "Corporate VPN",
      "cidr_blocks": [
        "11.22.33.44/32",
        "5.6.7.8/32"
      ]
    }
  ]
}
```

<a id="delete-ip-group"></a>

## Delete an IP group

Before deleting an IP group, ensure the IP group is not referenced by an IP
filter. Confluent Cloud rejects the request if any IP filter still references the IP
group. To find the IP filters that reference an IP group, run
`confluent iam ip-filter list` and then either
[update](manage-ip-filters.md#update-ip-filter) or [delete](manage-ip-filters.md#delete-ip-filter) those IP
filters first.

You can’t delete the system-defined **No Public Networks** IP group
(`ipg-none`).

### Confluent Cloud Console

1. Go to the **IP filtering** tab on the **Accounts & access** page
   at [https://confluent.cloud/settings/org/ip-filtering](https://confluent.cloud/settings/org/ip-filtering).

   The **IP filtering** page, with the **IP group** view, appears.
2. Click **IP groups** and then click the name of the IP group you want to
   delete.

   The IP group details view appears.
3. Click **Delete IP group**. The **Delete IP group** page appears.
4. Enter the IP group name to confirm that you want to delete the IP group,
   then click **Confirm**.

The IP group is deleted and the IP group view appears listing the remaining IP groups.

### Confluent CLI

Use the `confluent iam ip-group delete` command
([Confluent CLI reference](https://docs.confluent.io/confluent-cli/current/command-reference/iam/ip-group/confluent_iam_ip-group_delete.html#))
to delete an IP group. For example, the following command deletes
the `ipg-12345` IP group:

```shell
confluent iam ip-group delete ipg-12345
```

The following example shows the response to the request:

```text
Deleted IP group "ipg-12345".
```

### Confluent Cloud APIs

To make a request to delete an IP group, use the `DELETE /iam/v2/ip-groups/{id}` API endpoint (see
[Delete an IP group](/cloud/current/api.html#tag/IP-Groups-(iamv2)/operation/deleteIamV2IpGroup)).

For example, the following request deletes the `ipg-12345` IP group.

```shell
curl --request DELETE \
  --url 'https://api.confluent.cloud/iam/v2/ip-groups/ipg-12345' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'
```

A successful request returns `204 No Content` with an empty response
body.

<a id="ip-group-limits"></a>

## IP group limits

Confluent Cloud enforces the following limits on IP groups:

| Limit                      | Value                                                                                                                                     |
|----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------|
| IP groups per organization | 25                                                                                                                                        |
| CIDR blocks per IP group   | 1 minimum, 25 maximum                                                                                                                     |
| IP group name length       | 1 to 64 characters                                                                                                                        |
| IP group name characters   | Letters, numbers, the space character, and the following special<br/>characters: `[`, `]`, `|`, `&`, `+`, `-`, `_`, `/`,<br/>`.`, and `,` |
| IP group name uniqueness   | Names must be unique within your organization                                                                                             |
| CIDR block format          | IPv4 only. The reserved CIDR block `0.0.0.0/32` can’t be used, and<br/>an IP group can’t list the same CIDR block twice.                  |

<a id="ip-group-failure-modes"></a>

## IP group errors

The following table lists the errors that Confluent Cloud returns for IP group
operations and how to resolve them.

| Operation                   | Error                                                                                                                                                                                     | Resolution                                                                                                                                                                                                                                                                                                    |
|-----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Create, Update              | `group_name cannot be empty`, `group_name must be less than or equal<br/>to 64 characters`, or `group_name can only contain letters, numbers,<br/>spaces, and certain special characters` | Provide a name that meets the constraints in [IP group limits](#ip-group-limits).                                                                                                                                                                                                                             |
| Create, Update              | `IP group with group_name '<name>' already exists`                                                                                                                                        | Choose a name that isn’t already used by another IP group in your<br/>organization.                                                                                                                                                                                                                           |
| Create, Update              | `cannot have an empty CIDR block` or `cannot have more than 25 CIDR<br/>blocks`                                                                                                           | Provide between 1 and 25 CIDR blocks.                                                                                                                                                                                                                                                                         |
| Create, Update              | `invalid CIDR block: '<cidr>'`                                                                                                                                                            | Correct the CIDR notation. For example, use `64.235.154.88/32` for a<br/>single IP address.                                                                                                                                                                                                                   |
| Create, Update              | `invalid input: IPv6 is not supported`                                                                                                                                                    | Use IPv4 CIDR blocks only.                                                                                                                                                                                                                                                                                    |
| Create, Update              | `invalid input: CIDR block '0.0.0.0/32' is reserved`                                                                                                                                      | Use a different CIDR block. Confluent Cloud reserves `0.0.0.0/32` for the<br/>system-defined **No Public Networks** IP group. To block all public<br/>network access, see [Block all public networks](manage-ip-filters.md#use-no-public-networks-group).                                                     |
| Create, Update              | `duplicate CIDR block: '<cidr>'`                                                                                                                                                          | Remove the repeated CIDR block from the request.                                                                                                                                                                                                                                                              |
| Create                      | `IP group quota exceeded` (HTTP `402`)                                                                                                                                                    | Delete an unused IP group. Your organization can have at most 25 IP<br/>groups.                                                                                                                                                                                                                               |
| Update                      | `this action would lock out the requester from IP address<br/><ip-address>`                                                                                                               | The updated IP group would block your own IP address from an IP filter<br/>that uses it. Keep a CIDR block that covers your current IP address, or<br/>retry from an IP address that another IP filter permits. For details,<br/>see [Specify CIDR blocks for IP groups](#specify-cidr-blocks-for-ip-groups). |
| Update, Delete              | `IP group No Public Networks cannot be deleted or modified`                                                                                                                               | The system-defined `ipg-none` IP group is read-only.                                                                                                                                                                                                                                                          |
| Update (Confluent CLI only) | `Cannot remove all CIDR blocks from IP group`                                                                                                                                             | An IP group must keep at least one CIDR block. Delete the IP group<br/>instead, or add a replacement CIDR block in the same command.                                                                                                                                                                          |
| Delete                      | `Cannot delete an IP group that has related IP filters`                                                                                                                                   | Run `confluent iam ip-filter list` to find the IP filters that<br/>reference this IP group, then update or delete those IP filters first.                                                                                                                                                                     |
| Describe, Update, Delete    | `IP group not found` (HTTP `404`)                                                                                                                                                         | Verify the IP group ID with `confluent iam ip-group list`.                                                                                                                                                                                                                                                    |
| All                         | `user_unauthorized` (HTTP `403`)                                                                                                                                                          | You need the [OrganizationAdmin](../rbac/predefined-rbac-roles.md#organizationadmin-role) role to manage IP groups.                                                                                                                                                                                           |
| All                         | HTTP `429`                                                                                                                                                                                | You exceeded the API rate limit. Wait for the number of seconds in the<br/>`Retry-After` response header and retry.                                                                                                                                                                                           |

## Related content

* [IP Filtering (overview)](overview.md#ip-filtering)
* [Manage IP Filters](manage-ip-filters.md#manage-ip-filters)
* [Best Practices for IP Filtering](best-practices.md#ip-filtering-best-practices)
* [Confluent CLI Reference: confluent iam ip-group](https://docs.confluent.io/confluent-cli/current/command-reference/iam/ip-group/index.html)
* [Confluent CLI Reference: confluent iam ip-filter](https://docs.confluent.io/confluent-cli/current/command-reference/iam/ip-filter/index.html)
* [Confluent API Reference: IP Groups](/cloud/current/api.html#tag/IP-Groups-(iamv2))
* [Confluent API Reference: IP Filters](/cloud/current/api.html#tag/IP-Filters-(iamv2))