additional_karpenter_nodepools_config

Description

The additional_karpenter_nodepools_config parameter creates custom Karpenter NodePools beyond the built-in workload and build pools. Each entry in the JSON array produces its own NodePool + EC2NodeClass pair with the same infrastructure settings (subnet discovery, security groups, IAM role) as the workload pool.

Use this for dedicated GPU pools, tenant isolation, specialized instance requirements, or batch processing pools.

Default Value

The default value is empty (no custom NodePools).

Setting the Parameter

Using a JSON string:

$ convox rack params set additional_karpenter_nodepools_config='[{"name":"gpu","instance_families":"g5,g6","capacity_types":"on-demand","cpu_limit":64,"memory_limit_gb":256,"taints":"nvidia.com/gpu=true:NoSchedule","disk":200}]' -r rackName
Updating parameters... OK

Target Services to the GPU pool using nodeSelectorLabels and scale.gpu in convox.yml:

services:
  ml-worker:
    build: .
    scale:
      gpu:
        count: 1
        vendor: nvidia
    nodeSelectorLabels:
      convox.io/nodepool: gpu

Using a JSON file:

$ convox rack params set additional_karpenter_nodepools_config=/path/to/nodepools.json -r rackName
Updating parameters... OK

Removing a Pool

The parameter holds the full list, so you remove a pool by submitting the list without it. Because that drains and deletes the pool's nodes, the CLI refuses the change unless you pass --force:

$ convox rack params set additional_karpenter_nodepools_config='[{"name":"batch","instance_families":"c5"}]' -r rackName
ERROR: destructive change, removes node pools from the rack: analytics
  Their nodes are drained and deleted. Services pinned to convox.io/nodepool=analytics become unschedulable.
  Re-run with --force to proceed

$ convox rack params set additional_karpenter_nodepools_config='[{"name":"batch","instance_families":"c5"}]' --force -r rackName
Updating parameters... OK

--force also accepts the short form -f.

The guard triggers on any change that drops a pool name, which includes renaming a pool and clearing the parameter. Adding a pool, and editing one in place such as raising its cpu_limit, are accepted with no flag.

This check runs in the convox CLI as of 3.25.4 and returns before any Terraform apply, so it arrives with an updated CLI rather than with a Rack update, and it does not cover a parameter change made through Console. Services left pinned to a pool that no longer exists cannot schedule, and a deploy that targets a missing pool is rejected up front. See Node Pool Validation.

Additional Information

• Input formats: Raw JSON string, base64-encoded JSON, or a .json file path.
• Every custom pool automatically gets a convox.io/nodepool={name} label. Target Services to a custom pool using nodeSelectorLabels in convox.yml.
• Pool name validation: Lowercase alphanumeric with dashes, max 63 chars. Reserved names: workload, build, default, system. Duplicate names are rejected.
• Custom AMIs: Set "ami_id": "ami-..." on a pool to run its nodes on your own AL2023-based AMI, which a GPU pool needs to run an NVIDIA driver newer than the one AWS ships. See GPU Nodes and Custom AMIs.
• CLI version for ami_id: Editing this pool list needs convox CLI 3.25.5 or newer once the field is in use. An older CLI rewrites the parameter without it.
• Pool isolation: Set "dedicated": true on a pool entry to automatically add a dedicated-node={name}:NoSchedule taint. Convox auto-injects the matching toleration for Services targeting the pool via nodeSelectorLabels. This is the simplest way to isolate a pool without manual taint configuration.
• For pools with custom taints beyond dedicated, see Using Taints to Protect Nodes for how tolerations are handled (GPU taints are auto-tolerated via scale.gpu; convox.yml does not have a tolerations field).
• See the Karpenter feature page for the full per-pool field reference and examples.

See Also

• Karpenter for the full Karpenter configuration reference
• karpenter_config for overriding the workload NodePool
• additional_node_groups_config for custom EKS managed node groups
• Workload Placement for node targeting with nodeSelectorLabels
• GPU Nodes and Custom AMIs for the ami_id field and the NVIDIA driver it carries