eks.nodegroups.create

Add a node group

POST /eks/api/clusters/{cluster}/nodegroupsIAM eks:CreateNodegroupChanges state

The nodes run the cluster’s Kubernetes version and appear in Compute, locked to the node group. nodeRole needs iam:PassRole on that role.

Request syntax

POST /eks/api/clusters/{cluster}/nodegroups
{
  "name": "string",
  "drainTimeoutMinutes": "number",
  "forceAfterTimeout": "boolean",
  "autoscaling": "boolean",
  "zones": "array of string",
  "instanceTypes": "array of string",
  "capacityFallback": "object",
  "instanceType": "string",
  "labels": "map of string",
  "taints": "array of json",
  "nodeRole": "string",
  "tags": "map of string",
  "minSize": "number",
  "desiredSize": "number",
  "maxSize": "number"
}

Path parameters

  • clusterRequired

    string

    Constraints: /^(ewk-[0-9a-f]{12}|[a-z]([a-z0-9-]{0,38}[a-z0-9])?)$/

Request body

  • nameRequired

    string

    Node group name, unique in the cluster (409 when taken): lowercase letters, digits and hyphens, starting with a letter, at most 32 characters

    Constraints: /^[a-z]([a-z0-9-]{0,30}[a-z0-9])?$/

  • drainTimeoutMinutesOptional

    number

    Upgrades: minutes a node’s drain may wait on PodDisruptionBudgets; default 60

    Constraints: integer, 5-1440

  • forceAfterTimeoutOptional

    boolean

    Upgrades: after the timeout, remove the node anyway (true) or pause the upgrade (false, default)

  • autoscalingOptional

    boolean

    Let the cluster autoscaler change desiredSize between minSize and maxSize (pending pods grow the group, underused nodes shrink it)

  • zonesOptional

    array of string

    Availability zones the nodes spread over, balanced (e.g. ["de1a","de1b"]); default the region’s default zone. Applies to nodes created from then on

    Constraints: /^[a-z]+[0-9]+[a-z]$/

  • instanceTypesOptional

    array of string

    Instance types to buy, in order, when instanceType is sold out in a zone (same CPU architecture), e.g. performance-8

    Constraints: /^[a-z0-9-]{2,24}$/

  • capacityFallbackOptional

    object

    Stock fallback; default off. otherZones: zones outside `zones` may be used; equivalentTypes: an equivalent server type may be bought

    Constraints: JSON

  • instanceTypeRequired

    string

    An instance type, e.g. performance-4. The provider’s own type names are still accepted, deprecated.

    Constraints: 1-32 chars

  • labelsOptional

    map of string

    Kubernetes labels on every node, e.g. {"workload":"web"}; at most 20. kubernetes.io/, k8s.io/ and eks.ews.cloud/ keys are refused (400). Default none

    Constraints: key=value

  • taintsOptional

    array of json

    Kubernetes taints on every node: { key, value?, effect: NoSchedule | PreferNoSchedule | NoExecute }; at most 10. Default none

  • nodeRoleOptional

    string

    Name of an IAM role the nodes act as; needs iam:PassRole on it

    Constraints: 1-128 chars

  • tagsOptional

    map of string

    Tags for the new resource, e.g. {"env": "prod", "project": "shop"}. Keys your organization marks required must be present, or the create is refused with the missing keys (GET /tags/api/keys lists them).

    Constraints: key=value

  • minSizeRequired

    number

    Fewest nodes, 0–100; the cluster autoscaler never goes below it. minSize ≤ desiredSize ≤ maxSize, else 400

    Constraints: integer, 0-100

  • desiredSizeRequired

    number

    Nodes to run now, 0–100; with autoscaling on, the cluster autoscaler changes it between minSize and maxSize

    Constraints: integer, 0-100

  • maxSizeRequired

    number

    Most nodes, 1–100; what the quotas count (nodes per node group, and nodes per cluster summed over its node groups; 20 and 50 by default): 409 QuotaExceeded above them

    Constraints: integer, 1-100

Response

201 with the node group, no nodes yet: id, name, instanceType, minSize, desiredSize, maxSize, labels, taints, version, nodeRoleId, autoscaling, zones, drainTimeoutMinutes, forceAfterTimeout, status, reconcileError, readyNodes, nodes (name, instanceId, status, version, zone, drainMessage, privateIpv4, publicIpv4, createdAt), createdAt. Its nodes are built in the background. 400 for a type that cannot run a node, a zone outside the cluster’s region, a cluster minor past its end of support, or a missing required tag; 404 for an unknown cluster or nodeRole, 403 without the permission; 409 when the name is taken, the cluster is being deleted or upgraded, or a quota is full.

A JSON response is wrapped as { "success": true, "data": … }; the CLI prints the whole body with --json.

Errors

  • 400The request does not pass the schema above. The body is { "error": …, "issues": […] }, one issue per field.
  • 401No credentials, or an access key that is unknown, revoked or expired.
  • 403The caller's policies do not allow eks:CreateNodegroup on this resource. The body names the action and the resource, and the refusal is recorded in the audit log.
  • 404The resource does not exist in your organization.

Examples

The required parameters only, with example values. Replace id and the other placeholders with your own.

dcloud eks nodegroups create cluster --name example --instance-type example --min-size 1 --desired-size 1 --max-size 1

Generated from the API description, the same one the API checks requests against and the CLI is built from. MCP tool: dcloud_eks_nodegroups_create.