Create and manage node pools

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

On Distributed Cloud connected servers, node pools are created and populated automatically when you create a cluster. You also have the option to configure additional node pools after you've created the cluster.

For more information about Distributed Cloud node pools, see How Distributed Cloud connected works.

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 (roles/edgecontainer.admin)

  • Edge Container Machine User role (roles/edgecontainer.machineUser)

    You must also have this role on the Google Cloud project that contains the Distributed Cloud connected 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 \
    --node-labels=NODE_LABELS \
    --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 connected cluster for this node pool is hosted.
  • CLUSTER_NAME: the name of the target Distributed Cloud connected 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.
  • NODE_LABELS: a comma-delimited list of key-value pairs that comprise labels for the individual nodes in the node pool.
  • MACHINE_FILTER (optional): specifies the filtering criteria for machine selection. To see the fields by which you can filter, see Get information about a machine. Only machines that match this filter are allowed to join this node pool. For multi-rack clusters, use this flag to specify the Distributed Cloud connected racks whose nodes comprise this node pool. If omitted, all available nodes in the zone are added to 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 connected with Cloud Key Management Service as described in Enable support for customer-managed encryption keys (CMEK) for local storage.

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,
 "nodeLabels": NODE_LABELS,
 "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 connected cluster for this node pool is hosted.
  • CLUSTER_NAME: the name of the target Distributed Cloud connected 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 connected zone. This zone must be in the region specified in REGION.
  • NODE_COUNT: the number of nodes that this node pool holds.
  • NODE_LABELS: a comma-delimited list of key-value pairs that comprise labels for the individual nodes in the node pool.
  • MACHINE_FILTER (optional): specifies the filtering criteria for machine selection. Only machines that match this filter are allowed to join this node pool. For multi-rack clusters, use this flag to specify the Distributed Cloud connected racks whose nodes comprise this node pool. If omitted, all available nodes in the zone are added to 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 connected with Cloud Key Management Service as described in Enable support for customer-managed encryption keys (CMEK) for local storage.

List node pools

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

To complete this task, you must have the Edge Container Viewer role (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 connected cluster has been created.
  • CLUSTER_NAME: the name of the target Distributed Cloud connected 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 connected 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 (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 connected cluster associated with this node pool is hosted.
  • CLUSTER_NAME: the name of the target Distributed Cloud connected 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 connected cluster associated with this node pool is hosted.
  • CLUSTER_NAME: the name of the target Distributed Cloud connected 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 (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 connected cluster associated with this node pool is hosted.
  • CLUSTER_NAME: the name of the target Distributed Cloud connected cluster.
  • NODE_COUNT: the number of nodes that this node pool holds.
  • MACHINE_FILTER (optional): specifies the filtering criteria for machine selection. To see the fields by which you can filter, see Get information about a machine. For multi-rack clusters, use this flag to specify the Distributed Cloud connected racks whose nodes comprise this node pool.

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 connected cluster associated with this node pool is hosted.
  • CLUSTER_NAME: the name of the target Distributed Cloud connected 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 connected 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 for machine selection. Only machines that match this filter are allowed to join this node pool. For multi-rack clusters, use this flag to specify the Distributed Cloud connected racks whose nodes comprise 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 connected with Cloud Key Management Service as described in Enable support for customer-managed encryption keys (CMEK) for local storage.

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 (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 connected cluster associated with this node pool is hosted.
  • CLUSTER_NAME: the name of the target Distributed Cloud connected 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 connected cluster associated with this node pool is hosted.
  • CLUSTER_NAME: the name of the target Distributed Cloud connected cluster.
  • POOL_NAME: the name of the target node pool.
  • REQUEST_ID: a unique programmatic ID that identifies this request.

What's next