This page describes how to create and manage Google Distributed Cloud node
pool resources in a Distributed Cloud zone.

For more information about Distributed Cloud node pools, see
[How Distributed Cloud
works](https://docs.cloud.google.com/distributed-cloud/connected/1.5.1/docs/how-it-works).

> [!NOTE]
> **Note:** The Google Cloud CLI instructions on this page assume that you are using [Cloud Shell](https://docs.cloud.google.com/shell/docs) or another environment with `bash` installed.

## Create a node pool

To create a Distributed Cloud node pool, complete the steps
in this section.

To complete this task, you must have the following roles in your
Google Cloud project:

- [Edge Container Admin role](https://docs.cloud.google.com/distributed-cloud/connected/1.5.1/docs/permissions#edge-admin) (`roles/edgecontainer.admin`)
- [Edge Container Machine User role](https://docs.cloud.google.com/distributed-cloud/connected/1.5.1/docs/permissions#edge-machine-user)
  (`roles/edgecontainer.machineUser`)

  You must also have this role on the Google Cloud project that
  contains the Distributed Cloud machines that will be
  assigned to this node pool if that project is different from the
  Google Cloud project in which you are creating the node pool.

### Console

If you are using the Google Cloud console, you can only create a node pool when
you create a cluster. To create a standalone node pool, you must use the
Google Cloud CLI or the Distributed Cloud Edge Container API.

### gcloud

Use the `gcloud edge-cloud container clusters node-pools create` command:

```
gcloud edge-cloud container clusters node-pools create POOL_NAME \
    --project=PROJECT_ID \
    --location=REGION \
    --cluster=CLUSTER_NAME \
    --node-location=ZONE_NAME \
    --node-count=NODE_COUNT \
    --machine-filter=MACHINE_FILTER \
    --local-disk-kms-key=POOL_KMS_KEY
```

Replace the following:

- `POOL_NAME`: a descriptive name that uniquely identifies this node pool. This name must be RFC 1213-compliant and consist only of lowercase alphanumeric characters and hyphens (`-`). It must begin and end with an alphanumeric character.
- `PROJECT_ID`: the ID of the target Google Cloud project.
- `REGION`: the Google Cloud region in which the target Distributed Cloud cluster for this node pool is hosted.
- `CLUSTER_NAME`: the name of the target Distributed Cloud cluster.
- `ZONE_NAME`: the name of the target Distributed Cloud zone. This zone must be in the region specified in `REGION`.
- `NODE_COUNT`: the number of nodes that this node pool holds.
- `MACHINE_FILTER` (optional): specifies the [filtering criteria](https://google.aip.dev/160) for machine selection. To see the fields by which you can filter, see [Get information about a machine](https://docs.cloud.google.com/distributed-cloud/connected/1.5.1/docs/machines#machine-info). Only machines that match this filter are allowed to join this node pool.
- `POOL_KMS_KEY` (optional): the full path to the
  Cloud KMS key that you want to use with this node pool.
  For example:

  ```
  /projects/myProject/locations/us-west1-a/keyRings/myKeyRing/cryptoKeys/myGDCE-Key
  ```

  This flag only applies if you have integrated
  Distributed Cloud with Cloud Key Management Service as described in
  [Enable support for customer-managed encryption keys (CMEK) for local
  storage](https://docs.cloud.google.com/distributed-cloud/connected/1.5.1/docs/security#cmek).

### API

Make a `POST` request to the `projects.locations.clusters.nodePools.create`
method:

```
POST /v1/PROJECT_ID/locations/REGION/clusters/CLUSTER_NAME?nodePoolId=NODEPOOL_ID&requestId=REQUEST_ID
{
 "name": POOL_NAME,
 "labels": { LABELS,
  },
 "nodeLocation": ZONE_NAME,
 "nodeCount": NODE_COUNT,   
 "machineFilter": MACHINE_FILTER,
 "localDiskEncryption": {
   "kmsKey": POOL_KMS_KEY,
  }
}
```

Replace the following:

- `PROJECT_ID`: the ID of the target Google Cloud project.
- `REGION`: the Google Cloud region in which the target Distributed Cloud cluster for this node pool is hosted.
- `CLUSTER_NAME`: the name of the target Distributed Cloud cluster.
- `NODEPOOL_ID`: a unique programmatic ID that identifies this node pool resource.
- `REQUEST_ID`: a unique programmatic ID that identifies this request.
- `POOL_NAME`: a descriptive name that uniquely identifies this node pool.
- `LABELS`: a list of labels to apply to this node pool resource.
- `ZONE_NAME`: the name of the target Distributed Cloud zone. This zone must be in the region specified in `REGION`.
- `NODE_COUNT`: the number of nodes that this node pool holds.
- `MACHINE_FILTER` (optional): specifies the [filtering criteria](https://google.aip.dev/160) for machine selection. Only machines that match this filter are allowed to join this node pool.
- `POOL_KMS_KEY` (optional): the full path to the
  Cloud KMS key that you want to use with this node pool.
  For example:

  ```
  /projects/myProject/locations/us-west1-a/keyRings/myKeyRing/cryptoKeys/myGDCE-Key
  ```

  This parameter only applies if you have integrated
  Distributed Cloud with Cloud Key Management Service as described in
  [Enable support for customer-managed encryption keys (CMEK) for local
  storage](https://docs.cloud.google.com/distributed-cloud/connected/1.5.1/docs/security#cmek).

## List node pools

To list the Distributed Cloud node pools available in a
Distributed Cloud zone, complete the steps in this section.

To complete this task, you must have the
[Edge Container Viewer role](https://docs.cloud.google.com/distributed-cloud/connected/1.5.1/docs/permissions#edge-viewer)
(`roles/edgecontainer.viewer`) in your Google Cloud project.

### gcloud

Use the `gcloud edge-cloud container clusters node-pools list` command:

```
gcloud edge-cloud container clusters node-pools list \
    --project=PROJECT_ID \
    --location=REGION \
    --cluster=CLUSTER_NAME
```

Replace the following:

- `PROJECT_ID`: the ID of the target Google Cloud project.
- `REGION`: the Google Cloud region in which the target Distributed Cloud cluster has been created.
- `CLUSTER_NAME`: the name of the target Distributed Cloud cluster.

### API

Make a `GET` request to the `projects.locations.clusters.nodePools.list`
method:

```
GET /v1/PROJECT_ID/locations/REGION/clusters/CLUSTER_NAME/nodePools?filter=FILTER&pageSize=PAGE_SIZE&orderBy=SORT_BY&pageToken=PAGE_TOKEN
```

Replace the following:

- `PROJECT_ID`: the ID of the target Google Cloud project.
- `REGION`: the Google Cloud region in which the target Distributed Cloud cluster has been created.
- `CLUSTER_NAME`: the name of the target Distributed Cloud cluster.
- `FILTER`: an expression that constrains the returned results to specific values.
- `PAGE_SIZE`: the number of results to return per page.
- `SORT_BY`: a comma-delimited list of field names by which the returned results are sorted. The default sort order is ascending; for descending sort order, prefix the desired field with `~`.
- `PAGE_TOKEN`: a token received in the response to the last list request in the `nextPageToken` field in the response. Send this token to receive a page of results.

## Get information about a node pool

To get information about a Distributed Cloud node pool,
complete the steps in this section.

To complete this task, you must have the
[Edge Container Viewer role](https://docs.cloud.google.com/distributed-cloud/connected/1.5.1/docs/permissions#edge-viewer)
(`roles/edgecontainer.viewer`) in your Google Cloud project.

### gcloud

Use the `gcloud edge-cloud container clusters node-pools describe` command:

```
gcloud edge-cloud container clusters node-pools describe POOL_NAME \
    --project=PROJECT_ID \
    --location=REGION \
    --cluster=CLUSTER_NAME
```

Replace the following:

- `POOL_NAME`: the name of the target node pool.
- `PROJECT_ID`: the ID of the target Google Cloud project.
- `REGION`: the Google Cloud region in which the Distributed Cloud cluster associated with this node pool is hosted.
- `CLUSTER_NAME`: the name of the target Distributed Cloud cluster.

### API

Make a `GET` request to the `projects.locations.clusters.nodePools.get`
method:

```
GET /v1/PROJECT_ID/locations/REGION/clusters/CLUSTER_NAME/nodePools/POOL_NAME
```

Replace the following:

- `PROJECT_ID`: the ID of the target Google Cloud project.
- `REGION`: the Google Cloud region in which the Distributed Cloud cluster associated with this node pool is hosted.
- `CLUSTER_NAME`: the name of the target Distributed Cloud cluster.
- `POOL_NAME`: the name of the target node pool.

## Modify a node pool

To modify a Distributed Cloud node pool, complete the steps
in this section.

To complete this task, you must have the
[Edge Container Admin role](https://docs.cloud.google.com/distributed-cloud/connected/1.5.1/docs/permissions#edge-admin)
(`roles/edgecontainer.admin`) in your Google Cloud project.

### gcloud

Use the `gcloud edge-cloud container clusters node-pools update` command:

```
gcloud edge-cloud container clusters node-pools update POOL_NAME \
    --project=PROJECT_ID \
    --location=REGION \
    --cluster=CLUSTER_NAME \
    --node-count=NODE_COUNT \
    --machine-filter=MACHINE_FILTER
```

Replace the following:

- `POOL_NAME`: the name of the target node pool.
- `PROJECT_ID`: the ID of the target Google Cloud project.
- `REGION`: the Google Cloud region in which the Distributed Cloud cluster associated with this node pool is hosted.
- `CLUSTER_NAME`: the name of the target Distributed Cloud cluster.
- `NODE_COUNT`: the number of nodes that this node pool holds.
- `MACHINE_FILTER` (optional): specifies the [filtering criteria](https://google.aip.dev/160) for machine selection. To see the fields by which you can filter, see [Get information about a machine](https://docs.cloud.google.com/distributed-cloud/connected/1.5.1/docs/machines#machine-info).

### API

Make a `PATCH` request to the `projects.locations.clusters.nodePools.patch`
method:

```
PATCH /v1/PROJECT_ID/locations/REGION/clusters/CLUSTER_NAME?nodePoolId=NODEPOOL_ID&requestId=REQUEST_ID
{
 "name": POOL_NAME,
 "labels": { LABELS,
  },
 "nodeLocation": ZONE_NAME,
 "nodeCount": NODE_COUNT,
 "machineFilter": MACHINE_FILTER,
 "localDiskEncryption": {
   "kmsKey": KMS_KEY,
  }
}
```

Replace the following:

- `PROJECT_ID`: the ID of the target Google Cloud project.
- `REGION`: the Google Cloud region in which the Distributed Cloud cluster associated with this node pool is hosted.
- `CLUSTER_NAME`: the name of the target Distributed Cloud cluster.
- `NODEPOOL_ID`: a unique programmatic ID that identifies this node pool.
- `REQUEST_ID`: a unique programmatic ID that identifies this request.
- `POOL_NAME`: a descriptive name that uniquely identifies this node pool.
- `LABELS`: a list of labels to apply to this node pool resource.
- `ZONE_NAME`: the name of the target Distributed Cloud zone. This zone must be in the region specified in `REGION`.
- `NODE_COUNT`: the number of nodes that this node pool holds.
- `MACHINE_FILTER` (optional): specifies the [filtering criteria](https://google.aip.dev/160) for machine selection. Only machines that match this filter are allowed to join this node pool.
- `KMS_KEY` (optional): the full path to the
  Cloud KMS key that you want to use with this node pool.
  For example:

  ```
  /projects/myProject/locations/us-west1-a/keyRings/myKeyRing/cryptoKeys/myGDCE-Key
  ```

  This parameter only applies if you have integrated
  Distributed Cloud with Cloud Key Management Service as described in
  [Enable support for customer-managed encryption keys (CMEK) for local
  storage](https://docs.cloud.google.com/distributed-cloud/connected/1.5.1/docs/security#cmek).

## Delete a node pool

To delete a Distributed Cloud node pool, complete the steps
in this section.

To complete this task, you must have the
[Edge Container Admin role](https://docs.cloud.google.com/distributed-cloud/connected/1.5.1/docs/permissions#edge-admin)
(`roles/edgecontainer.admin`) in your Google Cloud project.

### gcloud

Use the `gcloud edge-cloud container clusters node-pools delete` command:

```
gcloud edge-cloud container clusters node-pools delete POOL_NAME \
    --project=PROJECT_ID \
    --location=REGION \
    --cluster=CLUSTER_NAME
```

Replace the following:

- `POOL_NAME`: the name of the target node pool.
- `PROJECT_ID`: the ID of the target Google Cloud project.
- `REGION`: the Google Cloud region in which the Distributed Cloud cluster associated with this node pool is hosted.
- `CLUSTER_NAME`: the name of the target Distributed Cloud cluster.

### API

Make a `DELETE` request to the `projects.locations.clusters.nodePools.delete`
method:

```
DELETE /v1/PROJECT_ID/locations/REGION/clusters/CLUSTER_NAME/nodePools/POOL_NAME?requestId=REQUEST_ID
```

Replace the following:

- `PROJECT_ID`: the ID of the target Google Cloud project.
- `REGION`: the Google Cloud region in which the Distributed Cloud cluster associated with this node pool is hosted.
- `CLUSTER_NAME`: the name of the target Distributed Cloud cluster.
- `POOL_NAME`: the name of the target node pool.
- `REQUEST_ID`: a unique programmatic ID that identifies this request.

## What's next

- [Deploy workloads on Distributed Cloud](https://docs.cloud.google.com/distributed-cloud/connected/1.5.1/docs/deploy)
- [Manage zones](https://docs.cloud.google.com/distributed-cloud/connected/1.5.1/docs/zones)
- [Manage machines](https://docs.cloud.google.com/distributed-cloud/connected/1.5.1/docs/machines)
- [Create and manage clusters](https://docs.cloud.google.com/distributed-cloud/connected/1.5.1/docs/clusters)
- [Create and manage VPN connections](https://docs.cloud.google.com/distributed-cloud/connected/1.5.1/docs/vpn-connections)
- [Manage virtual machines](https://docs.cloud.google.com/distributed-cloud/connected/1.5.1/docs/virtual-machines)
- [Manage GPU workloads](https://docs.cloud.google.com/distributed-cloud/connected/1.5.1/docs/gpu)