You can configure Pod density for individual node pools to override the
cluster-wide setting, which helps you improve resource efficiency. This
capability is useful for specialized node pools, such as nodes with GPUs, where
workload requirements or efficient IP address allocation require a different
value for maximum Pods per node.

## Before you begin

The capability to specify Pod density for node pools is only available for
clusters with one of the following network configurations:

- [Flat IPv4 static mode networking](https://docs.cloud.google.com/kubernetes-engine/distributed-cloud/bare-metal/docs/how-to/flat-network.md.txt)
- [IPv4/IPv6 dual-stack networking](https://docs.cloud.google.com/kubernetes-engine/distributed-cloud/bare-metal/docs/how-to/dual-stack-networking.md.txt)

## Configure Pod density for a node pool

Configure Pod density within the `NodePool` specification to override
cluster-level settings. This configuration is optional. The system derives the
size of the CIDR range assigned to the node from the maximum Pods per node
parameter.

The `maxPodsPerNode` configuration is immutable after node pool creation. The
system validates the `maxPodsPerNode` setting to ensure sufficient IP addresses
for nodes in the node pool. This validation uses strict label binding, where a
`ClusterCIDRConfig` binds to a node pool using a node selector. You can skip this
validation by setting the `baremetal.cluster.gke.io/skip-pod-cidr-size-check`
annotation on the Cluster CR or at the NodePool level.

1. Create a `ClusterCIDRConfig` resource.

   This resource binds to a specific NodePool using a node selector.

   ```yaml
   apiVersion: networking.gke.io/v1alpha1
   kind: ClusterCIDRConfig
   metadata:
     name: my-nodepool-cidr-config
   spec:
     nodeSelector:
       matchLabels:
         baremetal.cluster.gke.io/node-pool: NODE_POOL_NAME
     # ... other CIDR config fields (e.g., podCIDR, perNodeMaskSize)
   ```

   Replace `NODE_POOL_NAME` with the name of your NodePool.
2. Create the node pool with overridden Pod density.

   Specify the `nodeConfigOverride` field in the NodePool definition. This
   field contains the `podDensity` configuration.

   ```yaml
   apiVersion: baremetal.cluster.gke.io/v1
   kind: NodePool
   metadata:
     name: NODEPOOL_NAME
     namespace: CLUSTER_NAMESPACE
   spec:
     cluster: CLUSTER_NAME
     nodeConfigOverride:
       podDensity:
         maxPodsPerNode: MAX_PODS_PER_NODE
     # ... other NodePoolSpec fields like nodeCount, taints, labels etc. ...
   ```

   Replace the following:
   - `NODEPOOL_NAME`: the name of the node pool resource
     whose maximum Pods per node value you are overriding.

   - `CLUSTER_NAMESPACE`: the namespace of the cluster
     where the node pool resides.

   - `CLUSTER_NAME`: the name of the cluster where you
     override node pool settings.

   - `MAX_PODS_PER_NODE`: the maximum number of Pods you
     can run on a single node in the specified node pool.

## What's next

- Learn about the differences between the [flat mode and island mode network models](https://docs.cloud.google.com/kubernetes-engine/distributed-cloud/bare-metal/docs/reference/flat-vs-island-network.md.txt).
- Learn how to [Implement flat IPv4 mode network model](https://docs.cloud.google.com/kubernetes-engine/distributed-cloud/bare-metal/docs/how-to/flat-network.md.txt).
- Learn how to [create a cluster with IPv4/IPv6 dual-stack networking](https://docs.cloud.google.com/kubernetes-engine/distributed-cloud/bare-metal/docs/how-to/dual-stack-networking.md.txt).
- Learn about the [bundled NVIDIA GPU Operator](https://docs.cloud.google.com/kubernetes-engine/distributed-cloud/bare-metal/docs/how-to/update-clusters.md.txt#gpu-oper).
- Understand how [Pod CIDR blocks, the number of nodes, and the Pod density correlate](https://docs.cloud.google.com/kubernetes-engine/distributed-cloud/bare-metal/docs/how-to/scale.md.txt#pod_cidr_and_maximum_node_number).