NodeClass Field Reference
A NodeClass defines the cloud identity, image, networking, storage, and host configuration used for new nodes. NodePool requirements select compatible capacity and placement. Changing a template does not reconfigure every running machine in place; review drift and replacement impact before saving.
This page maps the Console’s provider-specific field groups, including advanced structured editors. It is not a promise that every raw YAML field accepted by every upstream CRD is supported on every installed version. Provider API ranges, cloud availability, installed schemas, and image compatibility remain authoritative.
Read paths, defaults, and readiness
Use list_node_classes to discover names and get_node_class with organization_id, cluster_id, and name for the complete saved configuration. Use default: true instead of name for the cluster-specific provider template. Paths in this page are relative to MCP data.configuration; nodeClassSpec corresponds to the native NodeClass spec. Summary lists omit this object; request a named get or detail: "full".
| Read field / path | Interpretation |
|---|---|
data.name, data.provider, configuration.name | Resource identity and provider. Names are fixed resource identities, not an editable rename. |
data.nodePoolNames, configuration.nodePoolNames | Pools that reference the class; check them before changing shared settings. |
data.status, configuration.nodeClassStatus | Reported readiness for supported AWS, GCP, and Azure runtimes. Missing status is unknown, not Ready. AlibabaCloud does not expose this wrapper status in the current API. |
nodeClassStatus.phase, .message | ready, notReady, resolving, or unknown, plus human-readable reason. |
nodeClassStatus.generation, .observedGeneration, .reportedAt | Whether the controller has observed the current generation and how fresh the report is. |
nodeClassStatus.conditions[] | type, status, reason, message, optional generation and transition time; use these to explain resolution failures. |
nodeClassStatus.resources | Resolved subnets, securityGroups, amis, instanceProfile, gceImages, aksImages, or kubernetesVersion, depending on provider. |
data.revision, data.default | Read configuration fingerprint and whether this is a default template; not write permission or a native resource version. |
AWS reads can retain the compatibility wrapper nodeClassAnnotation; preserve existing entries rather than assuming these are provider-spec fields or ordinary cloud tags.
Do not infer one universal default from a schema or an example. Read the cluster default and the named saved class: discovered role/subnets, provider defaults, CloudPilot presets, and older stored configurations can differ. Empty selectors or omitted advanced maps do not mean all cloud resources are permitted.
AWS EKS: EC2NodeClass
| Console group / path | Values and units | Meaning and constraints |
|---|---|---|
AMI family / nodeClassSpec.amiFamily | Provider-supported family, e.g. AL2023; availability depends on Kubernetes/provider version. | Determines bootstrap semantics. Do not change family independently of image and user data compatibility. |
AMI alias / nodeClassSpec.amiSelectorTerms[].alias | Alias such as al2023@<version> or provider-supported @latest. | An alias must be the sole selector term and sole field in that term. Pin a version when controlled image rollout is required. |
Image selector / nodeClassSpec.amiSelectorTerms[] | Non-alias terms use supported id, name, tags, and optional provider selector fields. | Terms are ORed; conditions inside a term are ANDed. Images must match architecture and cluster requirements. |
Subnet selectors / nodeClassSpec.subnetSelectorTerms[] | id or tags. | Terms OR, conditions AND. Selection controls reachable zones and private/public routing. |
Security group selectors / nodeClassSpec.securityGroupSelectorTerms[] | id, name, or tags. | Same selector semantics. Verify control-plane/node connectivity and avoid accidentally broad matches. |
Node identity / nodeClassSpec.role or .instanceProfile | Exactly one identity mode. Cluster default is discovered/configured during onboarding. | role is immutable after native class creation in the current provider. IAM/pass-role and instance-profile permissions are prerequisites, not granted by saving this field. |
Instance tags / nodeClassSpec.tags | String map. | Cloud tags, not Kubernetes node labels. Preserve required discovery/ownership tags. |
User data / nodeClassSpec.userData | Bootstrap script/configuration in the selected AMI family’s supported format. | Provider merge behavior applies. Custom bootstrap can conflict with generated settings and add-ons. |
Instance metadata options / nodeClassSpec.metadataOptions | httpEndpoint, httpProtocolIPv6, httpTokens, httpPutResponseHopLimit. | IMDS exposure/security. Required tokens and a restrictive hop limit reduce exposure but can affect software using node credentials. Read installed defaults rather than assume values. |
Kube reserved / nodeClassSpec.kubelet.kubeReserved | Resource quantities, e.g. CPU 100m, memory 256Mi. | Capacity reserved for Kubernetes components; reduces Allocatable. |
System reserved / nodeClassSpec.kubelet.systemReserved | Resource quantity map. | Host-service reservation, separate from Pod requests. |
The structured block-device editor writes nodeClassSpec.blockDeviceMappings[]:
| Field | Unit / value | Interpretation |
|---|---|---|
deviceName, rootVolume | Device name and optional boolean. | Identifies the mapping and root policy target. Do not apply dynamic root sizing to arbitrary data disks. |
ebs.volumeSize, .volumeType | Quantity such as 20Gi; supported EBS type such as gp3. | Fixed disk capacity/type. The general CloudPilot AWS preset uses a 20 GiB root disk; this is not a safe size for every workload. |
ebs.iops, .throughput | IOPS, MiB/s. | Type-dependent provisioned performance and cloud limits/cost. |
ebs.encrypted, .kmsKeyID | Boolean and optional key identifier. | Encryption and key-access requirements. A key reference does not grant decrypt permissions. |
ebs.snapshotID, .deleteOnTermination | Snapshot ID and boolean. | Seed contents and deletion lifecycle; node-local disks are not durable application backup. |
ebs.volumeSizePolicy.perVCPUGiB, .maxSizeGiB | GiB per vCPU and required maximum GiB. | Optional supported-provider dynamic root disk sizing; see dynamic sizing for minimums, formula, and bounds. |
The full native kubelet object can additionally contain podsPerCore, maxPods, clusterDNS, evictionHard, evictionSoft, evictionSoftGracePeriod, evictionMaxPodGracePeriod, imageGCHighThresholdPercent, imageGCLowThresholdPercent, and cpuCFSQuota. Counts are integers, eviction grace periods are durations, memory/storage thresholds are quantities or percentages, and image-GC values are percentages. These YAML-level fields require the installed AMI/provider schema; changing them can affect node registration and eviction behavior. Advanced native instanceStorePolicy, detailedMonitoring, and associatePublicIPAddress are also provider/version-dependent, not portable Console defaults.
AlibabaCloud ACK: ECSNodeClass
| Console field / path | Values / default source | Meaning |
|---|---|---|
Image alias / nodeClassSpec.imageSelectorTerms[].alias | Supported OS alias; current preset AlibabaCloudLinux3. | Must match instance architecture and runtime support. |
Image ID / nodeClassSpec.imageSelectorTerms[].id | Explicit compatible image ID. | Use an explicit selection intentionally; do not leave conflicting alias/ID fields in a term. |
VSwitch selectors / nodeClassSpec.vSwitchSelectorTerms[] | id or tags. | Discovers network placement; zone and IP capacity still constrain provisioning. |
Security groups / nodeClassSpec.securityGroupSelectorTerms[] | id, name, or tags. | Selects node network security groups. |
System disk size / nodeClassSpec.systemDisk.size | GiB; general preset 20. | New node OS capacity, not a PVC size. |
System disk categories / nodeClassSpec.systemDisk.categories[] | Allowed ECS disk categories. | Provider chooses from compatible allowed categories; region and instance constraints apply. |
Instance tags / nodeClassSpec.tags | String map. | Cloud resource metadata; distinct from NodePool labels. |
ACK does not expose the AWS IAM selector, GCP service account, AKS subnet fields, or CloudPilot NodeClass readiness wrapper. Do not synthesize these fields for AlibabaCloud. Cloud credentials and runtime RAM permissions are established during onboarding; see permissions and the selected-version installation script.
GKE: GCENodeClass
| Console field / path | Values / default source | Meaning |
|---|---|---|
Image family / nodeClassSpec.imageSelectorTerms[].family | ContainerOptimizedOS, Ubuntu2404, Ubuntu2204; general preset ContainerOptimizedOS. | OS family supported by the installed provider. The older top-level .imageFamily may remain in existing configurations. |
Image source/channel/version / nodeClassSpec.imageSelectorTerms[].{id,channel,version} | Image ID or family selection with supported channel (rapid, regular, stable, extended, cluster) and optional version; preset stable. | Follow the editor’s mutually compatible selector mode. Legacy .alias may be present; do not interpret it as a new default. |
Service account / nodeClassSpec.serviceAccount | Cloud service account; discovered/default identity if omitted where supported. | Requires correct identity-use and image/registry permissions. |
Pod subnet range / nodeClassSpec.subnetRangeName | Named secondary Pod IP range. | Must exist on the relevant subnet and have enough addresses. |
Private nodes / nodeClassSpec.networkConfig.enablePrivateNodes | Boolean; current general preset true. | Private addressing still requires working egress/registry/control-plane routes. |
Primary subnetwork / nodeClassSpec.networkConfig.subnetwork | GCP subnetwork identifier. | Must match cluster/project/region networking. |
Additional network interfaces / nodeClassSpec.networkConfig.additionalNetworkInterfaces[] | subnetwork, optional network, and installed-schema extensions. | Requires compatible machine and GKE network configuration. |
Boot disk size/type / nodeClassSpec.disks[].{sizeGiB,category,boot} | GiB, disk category, boolean; preset 50 GiB pd-balanced, boot: true. | Inspect all disks, not only the first entry. Fixed size and dynamic minimum are distinct from ephemeral storage consumption. |
Dynamic size / nodeClassSpec.disks[].sizePolicy.{perVCPUGiB,maxSizeGiB} | GiB per vCPU and cap in GiB. | Supported boot-disk policy only; see dynamic sizing. |
Kubelet configuration / nodeClassSpec.kubeletConfiguration | Structured object, fields below. | Host scheduling/eviction configuration, not a container resource policy. |
Confidential VM / nodeClassSpec.confidentialInstanceType | SEV, SEV_SNP, or TDX, where supported. | Restricts compatible machine/image combinations; not an ordinary interchangeable boolean. |
Automatic GPU taint / nodeClassSpec.autoGPUTaint | Optional boolean. | GPU-specific scheduling protection; Pods need compatible tolerations and resources. |
GPU driver version / nodeClassSpec.gpuDriverVersion | default, latest, disabled; preset default. | Match GPU model, OS, and driver lifecycle. |
Instance labels / nodeClassSpec.labels | Cloud label map; CloudPilot key cloudpilot-ai-managed. | GCE labels are not Kubernetes labels: do not use dotted/slashed keys such as cloudpilot.ai/managed. |
Instance metadata / nodeClassSpec.metadata | String map. | Includes startup metadata; preserve CloudPilot-managed startup script entries. |
Network tags / nodeClassSpec.networkTags[] | GCP network tag strings. | Can select firewall rules; not the same as labels or service-account permissions. |
The GCP kubelet editor exposes clusterDNS, maxPods, podsPerCore, kubeReserved, systemReserved, evictionHard, evictionSoft, evictionSoftGracePeriod, evictionMaxPodGracePeriod, imageGCHighThresholdPercent, imageGCLowThresholdPercent, and cpuCFSQuota. Use IP lists for DNS, integers for counts, resource quantities for reservations, durations for grace periods, and percentages/quantities for supported thresholds. Omission preserves provider defaults; unsupported entries are not made valid merely by using the structured editor.
AKS: AKSNodeClass
| Console field / path | Values / units | Meaning |
|---|---|---|
Image family / nodeClassSpec.imageFamily | Ubuntu, Ubuntu2204, Ubuntu2404, AzureLinux, subject to provider/Kubernetes support. | Compatible AKS base image; use cluster default rather than assuming all families work on every version. |
FIPS mode / nodeClassSpec.fipsMode | FIPS or Disabled, when supported. | Must be compatible with the chosen image and AKS version. |
VNet subnet / nodeClassSpec.vnetSubnetID | Azure resource ID. | Node placement, routing, IP availability, and identity permissions must match the cluster. |
OS disk size / nodeClassSpec.osDiskSizeGB | GiB as exposed by the provider’s GB field name. | Fixed new-node OS capacity; not a workload PVC. |
Dynamic disk size / nodeClassSpec.osDiskSizePolicy.{perVCPUGiB,maxSizeGiB} | GiB/vCPU and cap in GiB. | Optional supported-provider policy; see dynamic sizing. |
Maximum Pods / nodeClassSpec.maxPods | Integer; network/provider-dependent valid range. | Pod density must fit cluster networking and allocatable resources. |
Kubelet configuration / nodeClassSpec.kubelet | Provider-specific structured object. | Includes supported CPU policy/quota, GC, topology, logs, PID, sysctl and swap controls; details below. |
Encryption at host / nodeClassSpec.security.encryptionAtHost | Optional boolean. | Requires supported VM SKU/subscription; not equivalent to disk KMS configuration. |
Local DNS / nodeClassSpec.localDNS | Structured object with mode and VNet/Kube DNS overrides. | Requires supported AKS/provider versions; incorrect forwarding can break DNS. |
Linux OS configuration / nodeClassSpec.linuxOSConfig | Structured object. | Host-level swap/sysctl/transparent huge page settings; changes require validation with workload characteristics. |
Resource tags / nodeClassSpec.tags | String map. | Azure metadata, not Kubernetes node labels. |
Artifact streaming / nodeClassSpec.artifactStreaming.enabled | Optional boolean. | Azure image feature, distinct from CloudPilot Image Accelerator. Requires supported image, registry, and provider/runtime. |
The AKS kubelet structured object uses provider casing: cpuManagerPolicy, cpuCFSQuota, cpuCFSQuotaPeriod, imageGCHighThresholdPercent, imageGCLowThresholdPercent, topologyManagerPolicy, allowedUnsafeSysctls, containerLogMaxSize, containerLogMaxFiles, podPidsLimit, and failSwapOn. The Linux OS object includes swapFileSize, sysctls, transparentHugePageDefrag, and transparentHugePageEnabled. Local DNS arrays nodeClassSpec.localDNS.vnetDNSOverrides[] and .kubeDNSOverrides[] contain zone, queryLogging, protocol, forwardDestination, forwardPolicy, maxConcurrent, cacheDuration, serveStaleDuration, and serveStale. Use the installed provider schema for per-key enum/range validation; these objects are not portable AWS kubelet configurations.
CloudPilot storage and runtime extensions
These wrapper fields are beside nodeClassSpec. Availability requires compatible released components; a field in the current Console/API is not proof that an older node runtime supports it.
| Field | Scope / values | Effect |
|---|---|---|
enableImageAccelerator | AWS and GCP; optional boolean, opt-in. | Configures compatible new-node bootstrap/runtime. AWS also needs its pool switch; GCP pool markers and cluster/runtime configuration must agree. Azure uses pool configuration rather than this class switch; ACK is not supported here. |
enableLocalSSDEphemeralStorage | AWS and GCP; optional boolean, opt-in. | Uses local instance storage for kubelet ephemeral data and constrains referencing pools to compatible capacity. Data does not survive node loss. |
nodeClassSpec.ephemeralStorageLocalSSD.{count,autoCount} | GCP-specific Local SSD configuration. | Choose explicit count or supported automatic count mode; constrained by machine family. Do not combine incompatible modes. |
memoryExtension.enabled | AWS EKS, AL2023, supported runtime; opt-in. | Configures disk-backed cold memory and compressed cached memory on new nodes. Minimum physical RAM and disk headroom requirements apply. |
memoryExtension.coldMemory.sizingMode | Auto. | Current sizing mode, not a choice of arbitrary algorithms. |
memoryExtension.coldMemory.memoryRatioPercent | 1–100%; enabled-policy default 30%. | RAM-based cold-memory target, not guaranteed capacity. |
memoryExtension.coldMemory.minGiB, .maxGiB | Each 1–64 GiB, minimum no larger than maximum; defaults 2/16. | Bounds before disk headroom constraints. |
memoryExtension.coldMemory.maxDiskPercent | 1–50%; default 20%. | Root-disk capacity ceiling for cold memory. |
memoryExtension.cachedMemory.maxMemoryPercent | 1–40%; default 20%. | Upper bound for compressed cached pages; not an immediate reservation. |
memoryExtension.reclaimPolicy | Conservative. | Current fixed policy. |
See Local SSD, Memory Extension, and Image Accelerator for compatibility, runtime validation, and rollback behavior. Keep CloudPilot-managed annotations, startup scripts, reservations, and taints intact when editing unrelated raw fields.
Safe change scenarios
Change image, identity, or networking
Read the current class, its resolved status, and referencing pools first. Verify permissions using the provider permissions guide; a NodeClass cannot grant IAM/RAM/cloud identity permissions. For immutable identity changes or a high-risk network/image switch, create a separate class and a limited pool rather than overwrite a shared class. Confirm fresh Ready nodes and application network/registry access before replacing wider capacity.
Increase disk capacity or enable Memory Extension
Start with one non-critical pool and retain ordinary capacity elsewhere. Read the effective disk size/policy and verify candidates, free disk, node readiness, application latency, and memory/eviction signals after new nodes appear. Dynamic sizing and Memory Extension do not resize existing nodes. Do not treat cold memory as extra schedulable RAM, bypass container memory limits, or treat local SSD as persistent storage. Disable the feature and replace affected nodes through normal disruption controls if application behavior regresses.