Skip to Content
GuideGetting StartedTerraform and OpenTofu

Install CloudPilot AI with Terraform or OpenTofu

Use the CloudPilot AI modules to onboard an existing Amazon EKS or Google Kubernetes Engine (GKE) cluster and manage Node Autoscaler and Workload Autoscaler configuration as code.

Recommended: Start with the EKS or GKE module. The modules provide a cloud-specific interface, reusable NodeClass and NodePool templates, and the correct dependency wiring between the cluster and Workload Autoscaler resources. Use the provider resources directly only when you need lower-level lifecycle control.

Release compatibility

This guide targets the CloudPilot AI Server v1.36.4 API contract. The configuration updates below are available in these releases:

PackageVersion
CloudPilot AI provider0.7.0
EKS module0.6.0
GKE module0.3.0

The examples pin these minor release families. Earlier releases do not expose every input shown here, including GKE module workload settings.

Maintenance mode and Saving Report baseline dates remain outside these Terraform resources. The v1.36.4 interface also excludes CPU/Memory HPA state filters, target-reference UIDs, and cluster memory-request multiplier settings.

Choose an integration

IntegrationUse it forRegistry
EKS moduleRecommended EKS onboarding and configurationTerraform Registry  · OpenTofu Registry 
GKE moduleRecommended GKE onboarding and configurationTerraform Registry  · OpenTofu Registry 
CloudPilot AI providerDirect resource and data-source accessTerraform Registry  · OpenTofu Registry 

The same HCL configuration works with Terraform and OpenTofu. Run either the terraform commands or the equivalent tofu commands shown below.

Prerequisites

CloudPilot AI manages an existing Kubernetes cluster. Create the EKS or GKE cluster before applying the CloudPilot AI module.

Configure the provider

Declare the provider once in your root module. Keep the API key outside source control and pass it through a sensitive input variable.

terraform { # Required by this guide. Allowed: Terraform >= 1.0 or a compatible OpenTofu release. # Behavior: rejects runs that use an older CLI. required_version = ">= 1.0" required_providers { cloudpilotai = { # Required. Allowed: the official CloudPilot AI provider address. # Behavior: selects the provider package from the Terraform or OpenTofu Registry. source = "cloudpilot-ai/cloudpilotai" # Required for reproducible installs. Allowed: Terraform version constraints. # Behavior: accepts provider 0.7.x releases but not 0.8.0 or later. version = "~> 0.7.0" } } } variable "cloudpilotai_api_key" { # Required by the api_key authentication method. Allowed: a CloudPilot AI API key string. # Behavior: authenticates provider requests; sensitive hides it from normal CLI output. type = string sensitive = true } provider "cloudpilotai" { # Required unless api_key_profile is used. Allowed: a valid CloudPilot AI API key. # Behavior: authenticates every CloudPilot AI API request. api_key = var.cloudpilotai_api_key # Optional (default: https://api.cloudpilot.ai). Allowed: a valid HTTPS URL. # Behavior: sends provider requests to a custom CloudPilot AI API endpoint. # api_endpoint = "https://api.cloudpilot.ai" }

To read the API key from a file instead, replace api_key with api_key_profile. Do not configure both authentication methods.

provider "cloudpilotai" { # Required unless api_key is used. Allowed: path to a readable file containing the API key. # Behavior: reads the API key from disk; api_key takes precedence if both are set. api_key_profile = "/secure/path/cloudpilot-api-key" # Optional (default: https://api.cloudpilot.ai). Allowed: a valid HTTPS URL. # Behavior: sends provider requests to a custom CloudPilot AI API endpoint. # api_endpoint = "https://api.cloudpilot.ai" }

For local use, set the sensitive variable without adding a .tfvars file to Git:

export TF_VAR_cloudpilotai_api_key="<cloudpilot-api-key>"

The EKS module installs CloudPilot AI using the ambient AWS credential chain. Set aws_profile for local named-profile access or aws_assume_role for CI/OIDC workflows.

module "cloudpilotai_eks" { # Required. Allowed: the official EKS module address. # Behavior: downloads the CloudPilot AI EKS module. source = "cloudpilot-ai/eks/cloudpilotai" # Required for reproducible installs. Allowed: Terraform version constraints. # Behavior: accepts module 0.6.x releases but not 0.7.0 or later. version = "~> 0.6.0" # Required. Allowed: a non-empty existing EKS cluster name. # Behavior: selects the cluster to onboard and manage. cluster_name = "my-eks-cluster" # Required. Allowed: an AWS Region ID such as us-west-2. # Behavior: locates the EKS cluster and its AWS resources. region = "us-west-2" # Optional (default: false). Allowed: true or false. # Behavior: enables Node Autoscaler rebalance; true overrides only_install_agent. enable_rebalance = true # Optional (default: 0). Allowed: a non-negative integer; 0 disables restore. # Behavior: restores this many nodes before uninstall on destroy. restore_node_number = 3 # Optional (default: true). Allowed: true or false. # Behavior: creates and manages Workload Autoscaler configuration. enable_workload_autoscaler = true # Optional (default: []). Allowed: EKS NodeClass objects described in the full reference. # Behavior: creates concrete NodeClasses; names must be unique. nodeclasses = [ { # Required. Allowed: a unique Kubernetes-compatible NodeClass name. # Behavior: identifies this concrete NodeClass. name = "cloudpilot" # Optional. Allowed: a valid Karpenter EKS AMI alias such as al2023@latest. # Behavior: selects the base AMI family/version for launched nodes. ami_alias = "al2023@latest" # Optional. Allowed: a positive integer GiB; do not combine with block_device_mappings. # Behavior: sets the root system disk size. system_disk_size_gib = 80 } ] # Optional (default: []). Allowed: NodePool objects described in the full reference. # Behavior: creates concrete NodePools; names must be unique. nodepools = [ { # Required. Allowed: a unique Kubernetes-compatible NodePool name. # Behavior: identifies this concrete NodePool. name = "cloudpilot-general" # Optional. Allowed: the name of a NodeClass in this configuration. # Behavior: makes the NodePool launch nodes through that NodeClass. nodeclass = "cloudpilot" # Optional. Allowed: spot and/or on-demand. # Behavior: restricts the capacity types the NodePool may provision. capacity_type = ["spot", "on-demand"] # Optional. Allowed: amd64 and/or arm64. # Behavior: restricts CPU architectures unless instance_family takes precedence. instance_arch = ["amd64"] } ] }

For a regional cluster, region is also the cluster location. Set cluster_location for a zonal cluster. When project_id, cluster_uid, or kubeconfig is omitted, the provider attempts to discover it from GKE, Kubernetes, and the active gcloud configuration.

module "cloudpilotai_gke" { # Required. Allowed: the official GKE module address. # Behavior: downloads the CloudPilot AI GKE module. source = "cloudpilot-ai/gke/cloudpilotai" # Required for reproducible installs. Allowed: Terraform version constraints. # Behavior: accepts module 0.3.x releases but not 0.4.0 or later. version = "~> 0.3.0" # Required. Allowed: a non-empty existing GKE cluster name. # Behavior: selects the cluster to onboard and manage. cluster_name = "my-gke-cluster" # Required. Allowed: a Google Cloud region ID such as us-central1. # Behavior: selects the regional control-plane context and module resources. region = "us-central1" # Optional (default: discovered). Allowed: a Google Cloud project ID. # Behavior: locates the cluster; omitted uses metadata, then active gcloud project. project_id = "my-gcp-project" # Optional (default: false). Allowed: true or false. # Behavior: enables Node Autoscaler rebalance; true overrides only_install_agent. enable_rebalance = true # Optional (default: unset). Allowed: a non-negative integer; 0 means no restore. # Behavior: restores this total node count before uninstall on destroy. restore_node_number = 3 # Optional (default: true). Allowed: true or false. # Behavior: creates and manages Workload Autoscaler configuration. enable_workload_autoscaler = true # Optional (default: []). Allowed: GCE NodeClass objects described in the full reference. # Behavior: creates concrete NodeClasses; names must be unique. nodeclasses = [ { # Required. Allowed: a unique Kubernetes-compatible NodeClass name. # Behavior: identifies this concrete NodeClass. name = "cloudpilot" # Optional. Allowed: a valid Google service-account email. # Behavior: attaches that identity to nodes launched through the NodeClass. service_account = "nodes@my-gcp-project.iam.gserviceaccount.com" } ] # Optional (default: []). Allowed: NodePool objects described in the full reference. # Behavior: creates concrete NodePools; names must be unique. nodepools = [ { # Required. Allowed: a unique Kubernetes-compatible NodePool name. # Behavior: identifies this concrete NodePool. name = "cloudpilot-general" # Optional. Allowed: the name of a NodeClass in this configuration. # Behavior: makes the NodePool launch nodes through that NodeClass. nodeclass = "cloudpilot" # Optional. Allowed: spot and/or on-demand. # Behavior: restricts the capacity types the NodePool may provision. capacity_type = ["spot", "on-demand"] # Optional. Allowed: amd64 and/or arm64. # Behavior: restricts CPU architectures unless instance_family takes precedence. instance_arch = ["amd64"] # Optional. Allowed: GCE machine-family names available in the selected region. # Behavior: restricts provisioning to these families and takes precedence over architecture. instance_family = ["n4", "n2", "e2"] } ] }

Initialize, review, and apply

Use one CLI consistently for a working directory and commit its dependency lock file.

# Terraform terraform init terraform plan terraform apply # OpenTofu tofu init tofu plan tofu apply

Review every plan before applying it. A successful validate confirms HCL and schema wiring; provider validators that require real values or cluster access can run during plan.

Complete EKS module configuration

The following reference demonstrates the EKS module inputs. Optional raw JSON fields and mutually exclusive or deprecated alternatives are left commented so the example remains safe to adapt. Concrete nodeclasses and nodepools override fields inherited from module templates; templates expose the same nested fields.

Every input is preceded by a compact contract comment:

  • Required/Optional states whether the schema requires the field and gives the default or omission behavior when relevant.
  • Allowed lists an enum, range, format, or the kind of free-form value the field accepts.
  • Behavior explains what CloudPilot AI does with the value. Map entries such as tag keys and label keys are user-defined data, so the comment is attached to the containing map rather than repeated for every entry.
module "cloudpilotai_eks" { # Required. Allowed: the official EKS module address. # Behavior: downloads the CloudPilot AI EKS module. source = "cloudpilot-ai/eks/cloudpilotai" # Required for reproducible installs. Allowed: Terraform version constraints. # Behavior: accepts module 0.6.x releases but not 0.7.0 or later. version = "~> 0.6.0" # Required. Allowed: a non-empty existing EKS cluster name. # Behavior: selects the cluster to onboard and manage. cluster_name = "my-eks-cluster" # Required. Allowed: an AWS Region ID such as us-west-2. # Behavior: locates the EKS cluster and its AWS resources. region = "us-west-2" # Optional (default: null). Allowed: an existing CloudPilot cluster ID. # Behavior: binds to that registration; null lets the provider look it up or create it. cluster_id = null # Optional (default: ""). Allowed: an AWS shared-config profile name. # Behavior: an empty string uses the ambient/default AWS credential chain. aws_profile = "" # Optional (default: null). Allowed: an AWS role-assumption object. # Behavior: assumes the role before reading or changing cluster resources. aws_assume_role = { # Required in aws_assume_role. Allowed: a valid IAM role ARN. # Behavior: identifies the role to assume. role_arn = "arn:aws:iam::123456789012:role/cloudpilot-terraform" # Optional (default: cloudpilotai-terraform). Allowed: a valid STS session name. # Behavior: labels the AssumeRole session in AWS audit records. session_name = "cloudpilotai-terraform" } # Optional (default: null). Allowed: a readable kubeconfig path. # Behavior: null makes the provider generate an execution-local kubeconfig. kubeconfig = null # Optional (default: null). Allowed: an IAM role name, not an ARN. # Behavior: uses that node role for PassRole and install/upgrade operations. custom_node_role = "CloudPilotNodeRole-my-eks-cluster" # Optional (default: false). Allowed: true or false. # Behavior: true installs monitoring only, unless enable_rebalance is also true. only_install_agent = false # Optional (default: false). Allowed: true or false. # Behavior: enables Node Autoscaler rebalance and overrides only_install_agent. enable_rebalance = true # Optional (default: false). Allowed: true or false. # Behavior: true stops uploading workload metadata to CloudPilot AI. disable_workload_uploading = false # Optional (default: false). Allowed: true or false. # Behavior: checks the service and upgrades installed components when needed. enable_upgrade = true # Optional (default: null). Allowed: a cluster-setting object. # Behavior: null leaves these server-side settings unmanaged. cluster_setting = { # Optional (omitted: unmanaged). Allowed: true or false. # Behavior: enables or disables automatic unhealthy-node repair. enable_node_repair = true # Optional (omitted: unmanaged). Allowed: true or false. # Behavior: enables or disables node disk-pressure monitoring. enable_disk_monitor = true # Optional (omitted: unmanaged). Allowed: true or false. # Behavior: controls automatic decommissioning of obsolete node pools. enable_node_pool_decommission = true # Optional (omitted: unmanaged). Allowed: true or false. # Behavior: enforces each workload's minimum non-Spot replica target. enable_workload_min_non_spot = true # Optional (omitted: unmanaged). Allowed: a numeric discount ratio. # Behavior: adjusts cost calculations with the organization's effective discount. discount = 0.15 # Optional (omitted: unmanaged). Allowed: a shell command string. # Behavior: runs before CloudPilot AI's applicable cluster workflow. pre_run_command = "kubectl get nodes" # Optional (omitted: unmanaged). Allowed: a shell command string. # Behavior: runs after CloudPilot AI's applicable cluster workflow. post_run_command = "kubectl get pods -A" # Optional (omitted/null: preserve). Allowed: a duration; 0s disables the added delay. # Behavior: sets the cluster-wide disruption cooldown. disruption_cooldown = "10m" # Optional (omitted/null: preserve). Allowed: lowest-price or price-capacity-optimized. # Behavior: selects the AWS Spot allocation strategy; EKS only. aws_spot_allocation_strategy = "price-capacity-optimized" } # Optional (default: false). Allowed: true or false. # Behavior: true skips node restoration during destroy and overrides restore_node_number. skip_restore = false # Optional (default: 0). Allowed: a non-negative integer; 0 disables restore. # Behavior: restores this many nodes before uninstall during destroy. restore_node_number = 3 # Optional (default: []). Allowed: reusable EKS NodeClass template objects. # Behavior: defines settings inherited by nodeclasses that reference template_name. nodeclass_templates = [ { # Required. Allowed: a unique non-empty template name. # Behavior: identifies this reusable NodeClass template. template_name = "general" # Optional (default: CloudPilotNodeRole-{cluster_name}). Allowed: an IAM role name. # Behavior: attaches that role to EC2 instances launched through this NodeClass. role = "CloudPilotNodeRole-my-eks-cluster" # Optional (omitted: CloudPilot/server default). Allowed: true or false. # Behavior: enables or disables peer-assisted image acceleration on launched nodes. enable_image_accelerator = true # Optional (omitted: CloudPilot/server default). Allowed: true or false. # Behavior: uses instance-store NVMe as kubelet ephemeral storage when supported. enable_local_ssd_ephemeral_storage = true # Optional (omitted: CloudPilot default). Allowed: a Karpenter EKS AMI alias. # Behavior: selects an AMI family/version, for example al2023@latest. ami_alias = "al2023@latest" # Optional (omitted: no custom user data). Allowed: a MIME or shell user-data string. # Behavior: merges custom bootstrap data into launched instances. user_data = "#!/bin/bash\necho cloudpilot" # Optional (omitted: CloudPilot managed tags only). Allowed: map(string). # Behavior: adds these AWS tags to provisioned instances and related resources. instance_tags = { "cloudpilot.ai/managed" = "true" "environment" = "production" } # Optional (omitted: no extra allocation). Allowed: a non-negative integer millicores. # Behavior: reserves CPU capacity; enabled Memory Extension requires 100m. extra_cpu_allocation_mcore = 100 # Optional (omitted: no extra allocation). Allowed: a non-negative integer MiB. # Behavior: reserves memory capacity; enabled Memory Extension requires 256 MiB. extra_memory_allocation_mib = 256 # Optional (omitted/null: preserve). Allowed: a Memory Extension object; EKS only. # Behavior: configures cold and cached memory on newly provisioned AL2023 nodes. memory_extension = { # Optional. Allowed: true or false; enabling requires at least 4 GiB RAM. # Behavior: enables Memory Extension on nodes launched through this NodeClass. enabled = true # Optional. Allowed: Conservative. # Behavior: selects the memory reclaim policy. reclaim_policy = "Conservative" # Optional. Allowed: a cold-memory sizing object. # Behavior: bounds the disk-backed cold-memory capacity. cold_memory = { # Optional. Allowed: Auto. # Behavior: sizes cold memory automatically within the configured bounds. sizing_mode = "Auto" # Optional. Allowed: a percentage from 1 to 100. # Behavior: sizes automatic cold memory relative to node RAM. memory_ratio_percent = 30 # Optional. Allowed: 1-64 GiB. # Behavior: sets the minimum automatic cold-memory capacity. min_gib = 2 # Optional. Allowed: 1-64 GiB, at least min_gib. # Behavior: caps automatic cold-memory capacity. max_gib = 16 # Optional. Allowed: a percentage from 1 to 50. # Behavior: caps the share of disk capacity used for cold memory. max_disk_percent = 20 } # Optional. Allowed: a cached-memory sizing object. # Behavior: limits the RAM used for cached memory. cached_memory = { # Optional. Allowed: a percentage from 1 to 40. # Behavior: caps cached memory relative to node RAM. max_memory_percent = 20 } } # Optional (omitted: CloudPilot default disks). Allowed: block-device objects. # Behavior: configures EC2 volumes; mutually exclusive with system_disk_size_gib. block_device_mappings = [ { # Optional (omitted: provider/device default). Allowed: a Linux device path. # Behavior: selects the instance device name for this mapping. device_name = "/dev/xvda" # Optional (omitted: inferred). Allowed: true or false. # Behavior: marks this mapping as the root volume. root_volume = true # Optional (omitted: no EBS override). Allowed: an EBS configuration object. # Behavior: configures the EBS volume attached at device_name. ebs = { # Optional (omitted: image/provider default). Allowed: a positive size such as 80Gi. # Behavior: sets EBS volume capacity. volume_size = "80Gi" # Optional (omitted: image/provider default). Allowed: an EBS volume type such as gp3. # Behavior: selects the EBS storage class. volume_type = "gp3" # Optional (omitted: image/provider default). Allowed: true or false. # Behavior: enables or disables EBS encryption. encrypted = true # Optional (omitted/null: preserve). Allowed: a dynamic root-disk policy. # Behavior: grows future root disks from volume_size; only one mapping may own it. volume_size_policy = { # Optional. Allowed: GiB per vCPU, including 0, within cloud disk limits. # Behavior: adds capacity according to the provisioned instance's vCPU count. per_vcpu_gib = 5 # Required for a new policy. Allowed: GiB, at least the base volume_size. # Behavior: caps the dynamically calculated root-disk capacity. max_size_gib = 200 } } } ] # Optional alternative (omitted: CloudPilot default). Allowed: a positive integer GiB. # Behavior: sets root-disk size; do not set with block_device_mappings. # system_disk_size_gib = 80 # Optional (omitted: CloudPilot discovery-tag selector). Allowed: one or more OR terms. # Behavior: restricts node placement to matching subnets. subnet_selector_terms = [ { # Optional per term. Allowed: a non-empty map(string); keys are ANDed. # Behavior: matches subnets by tags; mutually exclusive with id in the same term. tags = { "karpenter.sh/discovery" = "my-eks-cluster" } } # Optional alternative per term. Allowed: a subnet ID. # Behavior: selects that subnet directly; mutually exclusive with tags. # { id = "subnet-0123456789abcdef0" } ] # Optional (omitted: CloudPilot discovery-tag selector). Allowed: one or more OR terms. # Behavior: attaches security groups matching any term. security_group_selector_terms = [ { # Optional per term. Allowed: a non-empty map(string); keys are ANDed. # Behavior: matches security groups by tags; use exactly one of tags, id, or name. tags = { "karpenter.sh/discovery" = "my-eks-cluster" } } # Optional alternatives per term. Allowed: a security-group ID or name. # Behavior: selects directly; use exactly one selector form per term. # { id = "sg-0123456789abcdef0" } # { name = "my-security-group" } ] } ] # Optional (default: []). Allowed: concrete EKS NodeClass objects. # Behavior: creates NodeClasses after merging referenced template settings. nodeclasses = [ { # Required. Allowed: a unique Kubernetes-compatible NodeClass name. # Behavior: identifies the concrete NodeClass. name = "cloudpilot" # Optional (omitted: no template). Allowed: a nodeclass_templates name. # Behavior: inherits that template before applying object-level overrides. template_name = "general" # Optional (omitted: use typed fields). Allowed: valid EC2NodeClass JSON. # Behavior: replaces the typed NodeClass settings; do not combine both approaches. # origin_nodeclass_json = file("ec2nodeclass.json") } ] # Optional (default: []). Allowed: reusable NodePool template objects. # Behavior: defines settings inherited by nodepools that reference template_name. nodepool_templates = [ { # Required. Allowed: a unique non-empty template name. # Behavior: identifies this reusable NodePool template. template_name = "general" # Optional (omitted: CloudPilot/server default). Allowed: true or false. # Behavior: enables or disables provisioning through matching NodePools. enable = true # Optional (omitted: CloudPilot default/reference). Allowed: a NodeClass name. # Behavior: selects the NodeClass used to launch nodes. nodeclass = "cloudpilot" # Optional (omitted: no GPU-specific restriction). Allowed: true or false. # Behavior: enables or disables GPU-capable provisioning for the pool. enable_gpu = false # Optional (omitted: inherit NodeClass/server setting). Allowed: true or false. # Behavior: enables image acceleration for nodes in this pool. enable_image_accelerator = true # Optional (omitted: CloudPilot default). Allowed: a signed integer; larger is higher. # Behavior: orders this pool relative to other eligible pools. provision_priority = 10 # Optional (omitted: no architecture filter). Allowed: amd64 and/or arm64. # Behavior: restricts architectures unless instance_family is configured. instance_arch = ["amd64"] # Optional (omitted: no family filter). Allowed: AWS instance-family names. # Behavior: restricts families and takes precedence over instance_arch. # instance_family = ["m7i", "m7a", "c7i"] # Optional (omitted: no capacity-type filter). Allowed: spot and/or on-demand. # Behavior: restricts which purchase models may be provisioned. capacity_type = ["spot", "on-demand"] # Optional (omitted: any eligible zone). Allowed: AWS Availability Zone IDs. # Behavior: restricts node placement to these zones. zone = ["us-west-2a", "us-west-2b"] # Optional (default/omitted: 0, no lower bound). Allowed: non-negative CPU cores. # Behavior: sets the minimum instance vCPU count. instance_cpu_min = 2 # Optional (default/omitted: 0, no upper bound). Allowed: non-negative CPU cores. # Behavior: sets the maximum instance vCPU count; must be >= the minimum. instance_cpu_max = 32 # Optional (default/omitted: 0, no lower bound). Allowed: non-negative MiB. # Behavior: sets the minimum instance memory. instance_memory_min = 4096 # Optional (default/omitted: 0, no upper bound). Allowed: non-negative MiB. # Behavior: sets maximum instance memory; must be >= the minimum. instance_memory_max = 131072 # Optional (omitted: CloudPilot default). Allowed: a Go duration such as 10m. # Behavior: delays disruption after a node becomes eligible. node_disruption_delay = "10m" # Optional (omitted/null: preserve). Allowed: a duration; 0s disables the added delay. # Behavior: overrides the cluster disruption cooldown for this pool. disruption_cooldown = "15m" # Optional (omitted/null: preserve). Allowed: a batch-workload optimization object. # Behavior: controls eligible run-to-completion workloads on a dedicated batch pool. job_nodepool_optimization = { # Optional. Allowed: a positive whole number. # Behavior: sets the active-node threshold; it does not reserve idle nodes. min_active_nodes = 2 # Optional. Allowed: a positive, finite Go duration such as 30s. # Behavior: delays provisioning for eligible batch workloads. provisioning_delay = "30s" } # Optional (omitted/null: preserve). Allowed: an NRI swap-policy object; EKS only. # Behavior: controls Pod swap on a supported Memory Extension pool. nri_swap_policy = { # Optional. Allowed: true or false; verify NRI environment requirements first. # Behavior: enables NRI swap only when the referenced NodeClass enables Memory Extension. enabled = false # Optional. Allowed: greater than 1 and at most 10, with at most three decimals. # Behavior: controls the NRI memory-limit multiplier. memory_limit_multiplier = 2 } # Optional (omitted/null: unmanaged). Allowed: one or more non-empty budget objects. # Behavior: limits simultaneous voluntary disruptions; entries are evaluated together. node_disruption_budgets = [ { # Required. Allowed: a non-negative integer string or percentage such as 20%. # Behavior: caps disruptions matching this budget. nodes = "20%" # Optional (omitted: all reasons). Allowed: Empty, Underutilized, and/or Drifted. # Behavior: limits the budget to these disruption reasons. reasons = ["Empty", "Underutilized"] }, { # Required. Allowed: a non-negative integer string or percentage. # Behavior: zero blocks matching voluntary disruptions during this window. nodes = "0" # Optional (omitted: all reasons). Allowed: Empty, Underutilized, and/or Drifted. # Behavior: applies this budget only to drift-driven disruptions. reasons = ["Drifted"] # Optional with duration. Allowed: a five-field cron expression. # Behavior: starts the recurring active budget window. schedule = "0 9 * * 1-5" # Optional with schedule. Allowed: a Go duration such as 8h. # Behavior: controls how long each scheduled budget window stays active. duration = "8h" } ] # Optional, deprecated (omitted: unmanaged). Allowed: count or percentage string. # Behavior: legacy single disruption cap; use node_disruption_budgets instead. # node_disruption_limit = "20%" # Optional (omitted: no additional labels). Allowed: map(string). # Behavior: applies these Kubernetes labels to provisioned nodes. labels = { team = "platform" } # Optional (omitted: no additional taints). Allowed: Kubernetes taint objects. # Behavior: applies scheduling taints to provisioned nodes. taints = [ { # Required. Allowed: a valid Kubernetes taint key. # Behavior: identifies the taint. key = "dedicated" # Optional (omitted: empty value). Allowed: a valid taint value string. # Behavior: supplies the taint value used by matching tolerations. value = "platform" # Required. Allowed: NoSchedule, PreferNoSchedule, or NoExecute. # Behavior: determines the taint's scheduling/eviction effect. effect = "NoSchedule" } ] } ] # Optional (default: []). Allowed: concrete NodePool objects. # Behavior: creates NodePools after merging referenced template settings. nodepools = [ { # Required. Allowed: a unique Kubernetes-compatible NodePool name. # Behavior: identifies the concrete NodePool. name = "cloudpilot-general" # Optional (omitted: no template). Allowed: a nodepool_templates name. # Behavior: inherits that template before applying object-level overrides. template_name = "general" # Optional (omitted: use typed fields). Allowed: valid NodePool JSON. # Behavior: replaces the typed NodePool settings; do not combine both approaches. # origin_nodepool_json = file("nodepool.json") } ] # Optional (default: []). Allowed: reusable workload template objects. # Behavior: defines scheduling/rebalance settings inherited by workloads. workload_templates = [ { # Required. Allowed: a unique non-empty template name. # Behavior: identifies this reusable workload template. template_name = "spot-friendly" # Optional (omitted: CloudPilot/server default). Allowed: true or false. # Behavior: permits or prevents Node Autoscaler from rebalancing this workload. rebalance_able = true # Optional (omitted: CloudPilot/server default). Allowed: true or false. # Behavior: marks whether replicas may run on Spot capacity. spot_friendly = true # Optional (omitted: CloudPilot/server default). Allowed: a non-negative integer. # Behavior: keeps at least this many replicas on non-Spot capacity. min_non_spot_replicas = 1 } ] # Optional (default: []). Allowed: workload configuration objects. # Behavior: manages Node Autoscaler behavior for specific Kubernetes workloads. workloads = [ { # Required. Allowed: the existing workload resource name. # Behavior: identifies the workload with type and namespace. name = "api" # Required. Allowed: a CloudPilot-supported workload type, for example deployment. # Behavior: selects the Kubernetes controller kind to configure. type = "deployment" # Required. Allowed: an existing Kubernetes namespace name. # Behavior: scopes the workload lookup. namespace = "production" # Optional (omitted: no template). Allowed: a workload_templates name. # Behavior: inherits that template before applying object-level overrides. template_name = "spot-friendly" # Optional (omitted: inherited/server default). Allowed: true or false. # Behavior: permits or prevents Node Autoscaler rebalance. rebalance_able = true # Optional (omitted: inherited/server default). Allowed: true or false. # Behavior: permits or prevents scheduling replicas on Spot capacity. spot_friendly = true # Optional (omitted: inherited/server default). Allowed: a non-negative integer. # Behavior: keeps at least this many replicas on non-Spot capacity. min_non_spot_replicas = 2 } ] # Optional (default: null). Allowed: null or a list of schedule objects. # Behavior: null leaves schedules unmanaged; [] removes previously module-managed schedules. scheduled_rebalances = [ { # Required. Allowed: a unique non-empty policy name. # Behavior: identifies the scheduled rebalance policy. name = "weekday-maintenance" # Required for a new policy. Allowed: a five-field cron expression. # Behavior: determines when the rebalance starts. cron = "0 10 * * 1-5" # Optional (omitted: server/default timezone). Allowed: an IANA timezone name. # Behavior: interprets cron in that timezone. timezone = "America/Los_Angeles" # Optional (omitted: preserve/default). Allowed: true or false. # Behavior: activates or suspends the policy. enabled = true # Optional (omitted: preserve/default). Allowed: true or false. # Behavior: true may force-drain nodes instead of waiting for graceful eviction. force_drain = false # Optional (omitted: server/default order). Allowed: oldest_first, newest_first, # name_asc, or lowest_utilization_first. Behavior: orders eligible nodes. selection_order = "lowest_utilization_first" # Optional (omitted: no additional constraints). Allowed: a constraint object. # Behavior: applies safety bounds before selecting nodes. node_constraints = { # Optional (omitted: no cap). Allowed: a non-negative integer. # Behavior: caps nodes selected by one run. max_nodes = 5 # Optional (omitted: no age floor). Allowed: non-negative seconds. # Behavior: excludes nodes younger than this age. min_age_seconds = 3600 # Optional (omitted: no size floor). Allowed: a non-negative integer. # Behavior: skips rebalance when the cluster is smaller than this value. min_cluster_size = 3 } # Optional (omitted: all eligible nodes). Allowed: a scope object. # Behavior: includes or excludes nodes before constraints and ordering are applied. scope = { # Optional (omitted/empty: any type). Allowed: spot and/or on-demand. # Behavior: limits the policy to these capacity types. capacity_types = ["spot"] # Optional (omitted/empty: any pool). Allowed: a NodePool name. # Behavior: limits the policy to one NodePool. node_pool_name = "cloudpilot-general" # Optional (omitted/empty: no name allowlist). Allowed: node-name strings. # Behavior: limits selection to these exact nodes when non-empty. node_names = [] # Optional (omitted/empty: no exclusions). Allowed: node-name strings. # Behavior: removes these exact nodes from selection. exclude_node_names = ["critical-node"] # Optional (omitted/empty: no selector allowlist). Allowed: ORed selector terms. # Behavior: includes nodes matching any term; expressions inside a term are ANDed. node_selector_terms = [ { # Required in a selector term. Allowed: one or more match expressions. # Behavior: all expressions in this term must match. match_expressions = [ { # Required. Allowed: a Kubernetes label key. # Behavior: selects the label evaluated by this expression. key = "team" # Required. Allowed: In, NotIn, Exists, or DoesNotExist. # Behavior: controls how the label is compared with values. operator = "In" # Optional by schema. Allowed: non-empty for In/NotIn; empty for Exists/DoesNotExist. # Behavior: supplies comparison values for the operator. values = ["platform"] } ] } ] # Optional (omitted/empty: no selector exclusions). Allowed: ORed selector terms. # Behavior: excludes nodes matching any term. exclude_node_selector_terms = [ { # Required in a selector term. Allowed: one or more match expressions. # Behavior: all expressions in this exclusion term must match. match_expressions = [ { # Required. Allowed: a Kubernetes label key. # Behavior: selects the label evaluated by this expression. key = "do-not-disrupt" # Required. Allowed: In, NotIn, Exists, or DoesNotExist. # Behavior: Exists matches when the key is present. operator = "Exists" # Optional by schema. Allowed: empty for Exists/DoesNotExist. # Behavior: no values are evaluated for Exists. values = [] } ] } ] } } ] # Add the shared Workload Autoscaler inputs from the section below. }

Dynamic root-disk sizing uses volume_size as the base. Only one root mapping may own volume_size_policy; max_size_gib is required for a new policy and must be at least the base size. per_vcpu_gib adds GiB per vCPU and may be zero. See Dynamic Boot Disk Sizing for cloud disk limits and Pod ephemeral-storage sizing. Policies affect future nodes; existing disks are not resized in place.

Memory Extension requires AL2023 nodes with at least 4 GiB RAM. It documents capacity ranges, NRI environment requirements, and rollout order. Enable nri_swap_policy only on a supported EKS pool referencing an enabled Memory Extension NodeClass.

When Memory Extension is enabled, Kubernetes reservations are fixed at 100m CPU and 256 MiB memory. Leave extra_cpu_allocation_mcore and extra_memory_allocation_mib omitted or null, or set them to 100 and 256 respectively. Other explicit values conflict with the feature and are rejected. When disabling Memory Extension, omit these fields or set them to null for that apply so the server can restore the reservations saved before enablement.

See Batch workload optimization for eligible Pods. min_active_nodes does not reserve idle nodes.

Complete GKE module configuration

This example covers the GKE module inputs and typed GCE NodeClass and NodePool fields. Concrete nodeclasses and nodepools override fields inherited from module templates; templates expose the same nested fields.

module "cloudpilotai_gke" { # Required. Allowed: the official GKE module address. # Behavior: downloads the CloudPilot AI GKE module. source = "cloudpilot-ai/gke/cloudpilotai" # Required for reproducible installs. Allowed: Terraform version constraints. # Behavior: accepts module 0.3.x releases but not 0.4.0 or later. version = "~> 0.3.0" # Required. Allowed: a non-empty existing GKE cluster name. # Behavior: selects the cluster to onboard and manage. cluster_name = "my-gke-cluster" # Required. Allowed: a Google Cloud region ID such as us-central1. # Behavior: supplies the module's regional context. region = "us-central1" # Optional (default: discovered). Allowed: a Google Cloud project ID. # Behavior: omitted uses instance metadata, then the active gcloud project. project_id = "my-gcp-project" # Optional (default: null/discovered). Allowed: the kube-system namespace UID. # Behavior: uniquely identifies the Kubernetes cluster when names may be reused. cluster_uid = null # Optional (default: null). Allowed: an existing CloudPilot cluster ID. # Behavior: binds to that registration; null lets the provider look it up or create it. cluster_id = null # Optional (default: region). Allowed: an exact GKE region or zone ID. # Behavior: set the zone for a zonal cluster; regional clusters normally omit it. cluster_location = "us-central1" # Optional (default: null). Allowed: a readable kubeconfig path. # Behavior: null makes the provider generate an execution-local kubeconfig. kubeconfig = null # Optional (default: false). Allowed: true or false. # Behavior: true stops uploading workload metadata to CloudPilot AI. disable_workload_uploading = false # Optional (default: null/full management). Allowed: true or false. # Behavior: true installs monitoring only, unless enable_rebalance is also true. only_install_agent = false # Optional (default: false). Allowed: true or false. # Behavior: checks the service and upgrades installed components when needed. enable_upgrade = true # Optional (default: false). Allowed: true or false. # Behavior: enables Node Autoscaler rebalance and overrides only_install_agent. enable_rebalance = true # Optional (default: null). Allowed: a cluster-setting object. # Behavior: null leaves these server-side settings unmanaged. cluster_setting = { # Optional (omitted: unmanaged). Allowed: true or false. # Behavior: enables or disables automatic unhealthy-node repair. enable_node_repair = true # Optional (omitted: unmanaged). Allowed: true or false. # Behavior: enables or disables node disk-pressure monitoring. enable_disk_monitor = true # Optional (omitted: unmanaged). Allowed: true or false. # Behavior: controls automatic decommissioning of obsolete node pools. enable_node_pool_decommission = true # Optional (omitted: unmanaged). Allowed: true or false. # Behavior: enforces each workload's minimum non-Spot replica target. enable_workload_min_non_spot = true # Optional (omitted: unmanaged). Allowed: a numeric discount ratio. # Behavior: adjusts cost calculations with the organization's effective discount. discount = 0.15 # Optional (omitted: unmanaged). Allowed: a shell command string. # Behavior: runs before CloudPilot AI's applicable cluster workflow. pre_run_command = "kubectl get nodes" # Optional (omitted: unmanaged). Allowed: a shell command string. # Behavior: runs after CloudPilot AI's applicable cluster workflow. post_run_command = "kubectl get pods -A" # Optional (omitted/null: preserve). Allowed: a duration; 0s disables the added delay. # Behavior: sets the cluster-wide disruption cooldown. disruption_cooldown = "10m" } # Optional (default: null/server default). Allowed: true or false. # Behavior: true skips restore during destroy and overrides all restore counts. skip_restore = false # Optional (default: null). Allowed: a non-negative integer; 0 means no restore. # Behavior: restores this total node count across pools during destroy. restore_node_number = 3 # Optional (default: null). Allowed: map(number) from node-pool name to non-negative total. # Behavior: restores per-pool desired sizes; named entries override the total count. restore_desired_sizes = { default-pool = 3 } # Optional (default: []). Allowed: reusable GCE NodeClass template objects. # Behavior: defines settings inherited by nodeclasses that reference template_name. nodeclass_templates = [ { # Required. Allowed: a unique non-empty template name. # Behavior: identifies this reusable NodeClass template. template_name = "general" # Optional (omitted: CloudPilot/server default). Allowed: true or false. # Behavior: enables or disables peer-assisted image acceleration on launched nodes. enable_image_accelerator = true # Optional (omitted: preserve server setting). Allowed: true or false. # Behavior: uses Local SSD as kubelet and container-runtime ephemeral storage. enable_local_ssd_ephemeral_storage = true # Optional (omitted: preserve server setting). Allowed: a Local SSD object. # Behavior: controls the Local SSD count for compatible machine types. ephemeral_storage_local_ssd = { # Optional (omitted/null: preserve). Allowed: true or false on compatible machines. # Behavior: automatically selects Local SSD count; do not set a positive count with true. auto_count = true # Optional alternative. Allowed: a fixed count from 1 to 32. # Behavior: attaches this many devices instead of selecting the count automatically. # count = 2 } # Optional (omitted: CloudPilot/default node identity). Allowed: a service-account email. # Behavior: attaches that Google service account to launched nodes. service_account = "nodes@my-gcp-project.iam.gserviceaccount.com" # Optional (omitted: cluster/default pod range). Allowed: an alias-IP secondary range name. # Behavior: allocates pod IPs from that secondary range. subnet_range_name = "pods" # Optional (omitted: CloudPilot/default boot disk). Allowed: GCE disk objects. # Behavior: configures disks attached to provisioned nodes. disks = [ { # Optional (omitted: inferred). Allowed: true or false. # Behavior: marks this disk as the boot disk. boot = true # Optional (omitted: provider default). Allowed: a GCE disk type such as pd-balanced. # Behavior: selects the disk storage class. category = "pd-balanced" # Optional (omitted: image/provider default). Allowed: a positive integer GiB. # Behavior: sets disk capacity. size_gib = 80 # Optional (omitted/null: preserve). Allowed: a dynamic policy on the boot disk only. # Behavior: grows future boot disks from the base size_gib. size_policy = { # Optional. Allowed: GiB per vCPU, including 0, within cloud disk limits. # Behavior: adds capacity according to the provisioned instance's vCPU count. per_vcpu_gib = 5 # Required for a new policy. Allowed: GiB, at least the base size_gib. # Behavior: caps the dynamically calculated boot-disk capacity. max_size_gib = 200 } } ] # Optional (omitted: CloudPilot image selection). Allowed: one or more OR terms. # Behavior: selects the OS image used to launch nodes. image_selector_terms = [ { # Optional per term. Allowed: ContainerOptimizedOS, Ubuntu2404, or Ubuntu2204. # Behavior: selects an image family; requires exactly one of channel or version. family = "ContainerOptimizedOS" # Optional per term. Allowed: rapid, regular, stable, extended, or cluster. # Behavior: follows that channel; valid only with ContainerOptimizedOS family. channel = "cluster" # Optional per term. Allowed: a full GCE image resource URL. # Behavior: selects an exact image; use id alone instead of family/channel/version. id = null # Optional per term. Allowed: latest or a family-specific release version. # Behavior: pins the family; use version instead of channel, not with it. version = null } ] # Optional (omitted: kubelet defaults). Allowed: a kubelet-configuration object. # Behavior: overrides reservations and eviction thresholds for launched nodes. kubelet_configuration = { # Optional (omitted: kubelet default). Allowed: map from eviction signal to quantity/%. # Behavior: immediately evicts pods after a hard threshold is crossed. eviction_hard = { "memory.available" = "5%" } # Optional (omitted: kubelet default). Allowed: map from eviction signal to quantity/%. # Behavior: starts graceful eviction after a soft threshold is crossed. eviction_soft = { "memory.available" = "10%" } # Optional (omitted: kubelet default). Allowed: map from resource to Kubernetes quantity. # Behavior: reserves node resources for Kubernetes system daemons. kube_reserved = { cpu = "200m" memory = "512Mi" } # Optional (omitted: kubelet default). Allowed: map from resource to Kubernetes quantity. # Behavior: reserves node resources for operating-system daemons. system_reserved = { cpu = "200m" memory = "512Mi" } } # Optional (omitted: no additional labels). Allowed: map(string). # Behavior: applies these labels through the GCE NodeClass. labels = { environment = "production" } # Optional (omitted: no additional metadata). Allowed: map(string). # Behavior: applies these GCE instance metadata entries. metadata = { "enable-oslogin" = "TRUE" } # Optional (omitted: no additional tags). Allowed: GCE network-tag strings. # Behavior: attaches tags used by firewall and network policies. network_tags = ["cloudpilot-managed"] # Optional (omitted: CloudPilot/default network settings). Allowed: a network object. # Behavior: controls primary and additional node network interfaces. network_config = { # Optional (omitted: server/default). Allowed: true or false. # Behavior: removes public node IPs when true; requires NAT or equivalent egress. enable_private_nodes = false # Optional (omitted: cluster/default subnet). Allowed: a subnetwork resource path. # Behavior: places the primary node interface on that subnetwork. subnetwork = "projects/my-gcp-project/regions/us-central1/subnetworks/nodes" # Optional (omitted: no extra interfaces). Allowed: interface objects. # Behavior: attaches additional VPC interfaces to each provisioned node. additional_network_interfaces = [ { # Optional (omitted: inferred from subnetwork). Allowed: a network resource path. # Behavior: selects the VPC for this additional interface. network = "projects/my-gcp-project/global/networks/secondary" # Optional (omitted: network default). Allowed: a subnetwork resource path. # Behavior: selects the subnet for this additional interface. subnetwork = "projects/my-gcp-project/regions/us-central1/subnetworks/secondary" } ] } # Optional (omitted: server/default). Allowed: true or false. # Behavior: automatically adds GKE-compatible taints to GPU nodes. auto_gpu_taint = true # Optional (default/omitted: default). Allowed: default, latest, or disabled. # Behavior: installs the stable, newest COS-only, or no NVIDIA driver; ignored on non-GPU nodes. gpu_driver_version = "latest" # Optional (omitted: use typed fields). Allowed: valid GCENodeClass JSON. # Behavior: replaces the typed NodeClass settings; do not combine both approaches. # origin_nodeclass_json = file("gcenodeclass.json") } ] # Optional (default: []). Allowed: concrete GCE NodeClass objects. # Behavior: creates NodeClasses after merging referenced template settings. nodeclasses = [ { # Required. Allowed: a unique Kubernetes-compatible NodeClass name. # Behavior: identifies the concrete NodeClass. name = "cloudpilot" # Optional (omitted: no template). Allowed: a nodeclass_templates name. # Behavior: inherits that template before applying object-level overrides. template_name = "general" } ] # Optional (default: []). Allowed: reusable NodePool template objects. # Behavior: defines settings inherited by nodepools that reference template_name. nodepool_templates = [ { # Required. Allowed: a unique non-empty template name. # Behavior: identifies this reusable NodePool template. template_name = "general" # Optional (omitted: CloudPilot/server default). Allowed: true or false. # Behavior: enables or disables provisioning through matching NodePools. enable = true # Optional (omitted: inherit NodeClass/server setting). Allowed: true or false. # Behavior: enables image acceleration for nodes in this pool. enable_image_accelerator = true # Optional (omitted: CloudPilot default/reference). Allowed: a NodeClass name. # Behavior: selects the NodeClass used to launch nodes. nodeclass = "cloudpilot" # Optional (omitted: no GPU-specific restriction). Allowed: true or false. # Behavior: enables or disables GPU-capable provisioning for the pool. enable_gpu = false # Optional (omitted: CloudPilot default). Allowed: a signed integer; larger is higher. # Behavior: orders this pool relative to other eligible pools. provision_priority = 10 # Optional (omitted: no family filter). Allowed: GCE machine-family names. # Behavior: restricts families and takes precedence over instance_arch. instance_family = ["n4", "n2", "e2"] # Optional (omitted: no architecture filter). Allowed: amd64 and/or arm64. # Behavior: restricts architectures unless instance_family is configured. instance_arch = ["amd64"] # Optional (omitted: no capacity-type filter). Allowed: spot and/or on-demand. # Behavior: restricts which purchase models may be provisioned. capacity_type = ["spot", "on-demand"] # Optional (omitted: any eligible zone). Allowed: Google Cloud zone IDs. # Behavior: restricts node placement to these zones. zone = ["us-central1-a", "us-central1-b"] # Optional (default/omitted: 0, no lower bound). Allowed: non-negative CPU cores. # Behavior: sets the minimum instance vCPU count. instance_cpu_min = 2 # Optional (default/omitted: 0, no upper bound). Allowed: non-negative CPU cores. # Behavior: sets the maximum instance vCPU count; must be >= the minimum. instance_cpu_max = 32 # Optional (default/omitted: 0, no lower bound). Allowed: non-negative MiB. # Behavior: sets the minimum instance memory. instance_memory_min = 4096 # Optional (default/omitted: 0, no upper bound). Allowed: non-negative MiB. # Behavior: sets maximum instance memory; must be >= the minimum. instance_memory_max = 131072 # Optional (omitted: CloudPilot default). Allowed: a Go duration such as 10m. # Behavior: delays disruption after a node becomes eligible. node_disruption_delay = "10m" # Optional (omitted/null: preserve). Allowed: a duration; 0s disables the added delay. # Behavior: overrides the cluster disruption cooldown for this pool. disruption_cooldown = "15m" # Optional (omitted/null: preserve). Allowed: a batch-workload optimization object. # Behavior: controls eligible run-to-completion workloads on a dedicated batch pool. job_nodepool_optimization = { # Optional. Allowed: a positive whole number. # Behavior: sets the active-node threshold; it does not reserve idle nodes. min_active_nodes = 2 # Optional. Allowed: a positive, finite Go duration such as 30s. # Behavior: delays provisioning for eligible batch workloads. provisioning_delay = "30s" } # Optional (omitted/null: unmanaged). Allowed: one or more non-empty budget objects. # Behavior: limits simultaneous voluntary disruptions; entries are evaluated together. node_disruption_budgets = [ { # Required. Allowed: a non-negative integer string or percentage such as 20%. # Behavior: caps disruptions matching this budget. nodes = "20%" # Optional (omitted: all reasons). Allowed: Empty, Underutilized, and/or Drifted. # Behavior: limits the budget to these disruption reasons. reasons = ["Empty", "Underutilized"] }, { # Required. Allowed: a non-negative integer string or percentage. # Behavior: zero blocks matching voluntary disruptions during this window. nodes = "0" # Optional (omitted: all reasons). Allowed: Empty, Underutilized, and/or Drifted. # Behavior: applies this budget only to drift-driven disruptions. reasons = ["Drifted"] # Optional with duration. Allowed: a five-field cron expression. # Behavior: starts the recurring active budget window. schedule = "0 9 * * 1-5" # Optional with schedule. Allowed: a Go duration such as 8h. # Behavior: controls how long each scheduled budget window stays active. duration = "8h" } ] # Optional, deprecated (omitted: unmanaged). Allowed: count or percentage string. # Behavior: legacy single disruption cap; use node_disruption_budgets instead. # node_disruption_limit = "20%" # Optional (omitted: no additional labels). Allowed: map(string). # Behavior: applies these Kubernetes labels to provisioned nodes. labels = { team = "platform" } # Optional (omitted: no additional taints). Allowed: Kubernetes taint objects. # Behavior: applies scheduling taints to provisioned nodes. taints = [ { # Required. Allowed: a valid Kubernetes taint key. # Behavior: identifies the taint. key = "dedicated" # Optional (omitted: empty value). Allowed: a valid taint value string. # Behavior: supplies the taint value used by matching tolerations. value = "platform" # Required. Allowed: NoSchedule, PreferNoSchedule, or NoExecute. # Behavior: determines the taint's scheduling/eviction effect. effect = "NoSchedule" } ] # Optional (omitted: use typed fields). Allowed: valid NodePool JSON. # Behavior: replaces the typed NodePool settings; do not combine both approaches. # origin_nodepool_json = file("gcenodepool.json") } ] # Optional (default: []). Allowed: concrete NodePool objects. # Behavior: creates NodePools after merging referenced template settings. nodepools = [ { # Required. Allowed: a unique Kubernetes-compatible NodePool name. # Behavior: identifies the concrete NodePool. name = "cloudpilot-general" # Optional (omitted: no template). Allowed: a nodepool_templates name. # Behavior: inherits that template before applying object-level overrides. template_name = "general" } ] # Optional (default: []). Allowed: direct workload configuration objects. # Behavior: manages Node Autoscaler settings for existing Kubernetes workloads. workloads = [ { # Required. Allowed: the existing workload resource name. # Behavior: identifies the workload with type and namespace. name = "api" # Required. Allowed: a supported workload type, for example deployment. # Behavior: selects the Kubernetes controller kind to configure. type = "deployment" # Required. Allowed: an existing Kubernetes namespace name. # Behavior: scopes the workload lookup. namespace = "example-apps" # Optional (omitted: preserve/server default). Allowed: true or false. # Behavior: permits or prevents Node Autoscaler rebalance. rebalance_able = true # Optional (omitted: preserve/server default). Allowed: true or false. # Behavior: permits or prevents scheduling replicas on Spot capacity. spot_friendly = true # Optional (omitted: preserve/server default). Allowed: a non-negative integer. # Behavior: keeps at least this many replicas on non-Spot capacity. min_non_spot_replicas = 1 } ] # Optional (default: null). Allowed: null or a list of schedule objects. # Behavior: null leaves schedules unmanaged; [] removes previously module-managed schedules. scheduled_rebalances = [ { # Required. Allowed: a unique non-empty policy name. # Behavior: identifies the scheduled rebalance policy. name = "weekday-maintenance" # Required for a new policy. Allowed: a five-field cron expression. # Behavior: determines when the rebalance starts. cron = "0 10 * * 1-5" # Optional (omitted: server/default timezone). Allowed: an IANA timezone name. # Behavior: interprets cron in that timezone. timezone = "America/Los_Angeles" # Optional (omitted: preserve/default). Allowed: true or false. # Behavior: activates or suspends the policy. enabled = true # Optional (omitted: preserve/default). Allowed: true or false. # Behavior: true may force-drain nodes instead of waiting for graceful eviction. force_drain = false # Optional (omitted: server/default order). Allowed: oldest_first, newest_first, # name_asc, or lowest_utilization_first. Behavior: orders eligible nodes. selection_order = "lowest_utilization_first" # Optional (omitted: no additional constraints). Allowed: a constraint object. # Behavior: applies safety bounds before selecting nodes. node_constraints = { # Optional (omitted: no cap). Allowed: a non-negative integer. # Behavior: caps nodes selected by one run. max_nodes = 5 # Optional (omitted: no age floor). Allowed: non-negative seconds. # Behavior: excludes nodes younger than this age. min_age_seconds = 3600 # Optional (omitted: no size floor). Allowed: a non-negative integer. # Behavior: skips rebalance when the cluster is smaller than this value. min_cluster_size = 3 } # Optional (omitted: all eligible nodes). Allowed: a scope object. # Behavior: includes or excludes nodes before constraints and ordering are applied. scope = { # Optional (omitted/empty: any type). Allowed: spot and/or on-demand. # Behavior: limits the policy to these capacity types. capacity_types = ["spot"] # Optional (omitted/empty: any pool). Allowed: a NodePool name. # Behavior: limits the policy to one NodePool. node_pool_name = "cloudpilot-general" # Optional (omitted/empty: no name allowlist). Allowed: node-name strings. # Behavior: limits selection to these exact nodes when non-empty. node_names = [] # Optional (omitted/empty: no exclusions). Allowed: node-name strings. # Behavior: removes these exact nodes from selection. exclude_node_names = ["critical-node"] # Optional (omitted/empty: no selector allowlist). Allowed: ORed selector terms. # Behavior: includes nodes matching any term; expressions inside a term are ANDed. node_selector_terms = [ { # Required in a selector term. Allowed: one or more match expressions. # Behavior: all expressions in this term must match. match_expressions = [ { # Required. Allowed: a Kubernetes label key. # Behavior: selects the label evaluated by this expression. key = "team" # Required. Allowed: In, NotIn, Exists, or DoesNotExist. # Behavior: controls how the label is compared with values. operator = "In" # Optional by schema. Allowed: non-empty for In/NotIn; empty for Exists/DoesNotExist. # Behavior: supplies comparison values for the operator. values = ["platform"] } ] } ] # Optional (omitted/empty: no selector exclusions). Allowed: ORed selector terms. # Behavior: excludes nodes matching any term. exclude_node_selector_terms = [ { # Required in a selector term. Allowed: one or more match expressions. # Behavior: all expressions in this exclusion term must match. match_expressions = [ { # Required. Allowed: a Kubernetes label key. # Behavior: selects the label evaluated by this expression. key = "do-not-disrupt" # Required. Allowed: In, NotIn, Exists, or DoesNotExist. # Behavior: Exists matches when the key is present. operator = "Exists" # Optional by schema. Allowed: empty for Exists/DoesNotExist. # Behavior: no values are evaluated for Exists. values = [] } ] } ] } } ] # Add the shared Workload Autoscaler inputs from the section below. }

Dynamic boot-disk sizing uses size_gib as the base. Only the boot disk may own size_policy; max_size_gib is required for a new policy and must be at least the base size. See Dynamic Boot Disk Sizing for cloud disk limits and how Pod ephemeral-storage requests affect sizing. When Local SSD backs ephemeral storage, those requests constrain Local SSD capacity instead of growing the boot disk. Policies affect future nodes; existing disks are not resized in place.

Automatic Local SSD sizing requires a compatible machine type. Set enable_local_ssd_ephemeral_storage = true when enabling automatic sizing; an omitted or null switch is accepted only if Local SSD is already enabled. Omit count when selecting auto_count = true: the provider clears any previous fixed count as part of the mode change. A positive count selects fixed-count mode. See Local SSD Terraform configuration for switching modes, preserving unmanaged values, and resetting to bundled-only storage.

See Batch workload optimization for eligible Pods. min_active_nodes does not reserve idle nodes.

One uncommon advanced NodeClass field is intentionally not included in the runnable example:

InputContract
confidential_instance_typeOptional (omitted: Confidential VM disabled). Allowed: SEV, SEV_SNP, or TDX. Behavior: enables in-use memory encryption with the selected Confidential VM technology; only use it with a compatible GCE machine family.

The following GKE inputs are optional compatibility aliases and are deprecated. Use the replacement inputs in new configurations.

Deprecated inputAllowed and behaviorReplacement
enable_node_autoscalerOptional (default: null). Allowed: true, false, or null. false maps to agent-only mode; null leaves the compatibility alias unused.only_install_agent and enable_rebalance
node_autoscaler_skip_restoreOptional (default: null). Allowed: true, false, or null. true skips restore during destroy unless the replacement input is set, which takes precedence.skip_restore
node_autoscaler_restore_desired_sizeOptional (default: null). Allowed: a non-negative number or null. Sets the total desired restore size unless the replacement input is set.restore_node_number
node_autoscaler_restore_desired_sizesOptional (default: null). Allowed: a map from node-pool name to non-negative desired total. Sets per-pool restore sizes unless the replacement input is set.restore_desired_sizes

Complete Workload Autoscaler configuration

The EKS and GKE modules expose the same Workload Autoscaler inputs. Add this configuration inside either module block.

# Optional (default: true). Allowed: true or false. # Behavior: creates the Workload Autoscaler resource and installs its components. enable_workload_autoscaler = true # Optional (default: ""). Allowed: a Kubernetes StorageClass name or empty string. # Behavior: selects VictoriaMetrics persistent storage; empty uses the cluster default. wa_storage_class = "" # Optional (default: true). Allowed: true or false. # Behavior: installs the per-node metrics DaemonSet when true. wa_enable_node_agent = true # Optional (default: false). Allowed: true or false. # Behavior: automatically enables proactive update when a new workload's recommendation is ready. wa_enable_new_workloads_proactive_update = false # Optional (default: 5). Allowed: an integer greater than zero. # Behavior: caps Workload Autoscaler operations in each limiter window. wa_limiter_quota_per_window = 5 # Optional (default: 10). Allowed: an integer greater than zero. # Behavior: sets the maximum temporary operation burst. wa_limiter_burst = 10 # Optional (default: 30). Allowed: an integer greater than zero, in seconds. # Behavior: sets the rate-limiter window length. wa_limiter_window_seconds = 30 # Optional (default: true). Allowed: true or false. # Behavior: garbage-collects pods left by preemption when true. wa_enable_preempted_pod_gc = true # Optional (default: 30m). Allowed: a Go duration such as 30m or 1h30m. # Behavior: waits this long before deleting a preempted pod. wa_preempted_pod_gc_ttl = "30m" # Optional (default: true). Allowed: true or false. # Behavior: waits for the initial data window before mutating or updating new workloads. wa_enable_initial_optimization_data_window_check = true # Optional (default: []). Allowed: RecommendationPolicy objects with unique names. # Behavior: [] manages no policies and removes previously module-managed policies when unreferenced. recommendation_policies = [ { # Required. Allowed: a unique non-empty RecommendationPolicy name. # Behavior: identifies the policy referenced by autoscaling policies. name = "balanced" # Optional (default for a new policy: percentile). Allowed: percentile. # Behavior: selects percentile-based resource recommendations. strategy_type = "percentile" # Optional (omitted/null: preserve; new policy: 95). Allowed: integer 50-100. # Behavior: targets this CPU-usage percentile independently of percentile_memory. percentile_cpu = 95 # Optional (omitted/null: preserve; new policy: 95). Allowed: integer 50-100. # Behavior: targets this memory-usage percentile independently of percentile_cpu. percentile_memory = 99 # Required. Allowed: a Go duration such as 24h or 168h. # Behavior: selects the CPU history used for recommendations. history_window_cpu = "24h" # Required. Allowed: a Go duration such as 48h or 168h. # Behavior: selects the memory history used for recommendations. history_window_memory = "48h" # Required. Allowed: a Go duration such as 1m or 1h. # Behavior: controls how often recommendations are evaluated. evaluation_period = "1m" # Optional (omitted: controller default). Allowed: CPU quantity or percentage. # Behavior: adds headroom to the computed CPU request. buffer_cpu = "10%" # Optional (omitted: controller default). Allowed: memory quantity or percentage. # Behavior: adds headroom to the computed memory request. buffer_memory = "20%" # Optional (omitted: no Terraform-managed floor). Allowed: a Kubernetes CPU quantity. # Behavior: prevents CPU recommendations below this value. request_min_cpu = "50m" # Optional (omitted: no Terraform-managed floor). Allowed: a Kubernetes memory quantity. # Behavior: prevents memory recommendations below this value. request_min_memory = "64Mi" # Optional (omitted: no Terraform-managed ceiling). Allowed: a Kubernetes CPU quantity. # Behavior: prevents CPU recommendations above this value; must be >= the minimum. request_max_cpu = "8" # Optional (omitted: no Terraform-managed ceiling). Allowed: a Kubernetes memory quantity. # Behavior: prevents memory recommendations above this value; must be >= the minimum. request_max_memory = "16Gi" # Optional (omitted: controller default). Allowed: a memory quantity or percentage. # Behavior: adds headroom to the JVM HeapXmx recommendation. jvm_heap_buffer = "300Mi" # Optional (omitted/null: preserve). Allowed: quantity or original-Xms percentage. # Behavior: floors JVM initial heap; an empty string clears this bound. jvm_min_heap_xms = "512Mi" # Optional (omitted/null: preserve). Allowed: quantity or original-Xms percentage. # Behavior: caps JVM initial heap; an empty string clears this bound. jvm_max_heap_xms = "1Gi" # Optional (omitted/null: preserve). Allowed: quantity or original-Xmx percentage. # Behavior: floors JVM maximum heap; an empty string clears this bound. jvm_min_heap_xmx = "768Mi" # Optional (omitted/null: preserve). Allowed: quantity or original-Xmx percentage. # Behavior: caps JVM maximum heap; an empty string clears this bound. jvm_max_heap_xmx = "4Gi" # Optional (omitted: unmanaged). Allowed: numeric string in [0, 1); 0 disables this floor. # Behavior: floors JVM Xms as a ratio of the memory recommendation. jvm_min_heap_xms_ratio_of_memory = "0.25" # Optional (omitted: controller default). Allowed: a Go duration such as 2h. # Behavior: protects recent JVM non-heap usage across this window. jvm_recent_non_heap_window = "2h" # Optional (controller default: 20). Allowed: integer 20-100. # Behavior: selects the JVM heap-used percentile for recommendations. jvm_heap_used_percentile = 95 }, { # Required: a distinct name for the independent startup recommendation pipeline. name = "startup-balanced" # Optional independently: integer 50-100; null preserves, new-policy default is 95 each. percentile_cpu = 99 percentile_memory = 99 # Required: Go durations for startup history and evaluation frequency. history_window_cpu = "48h" history_window_memory = "72h" evaluation_period = "1m" # Optional: quantity or percentage headroom on startup recommendations. buffer_cpu = "25%" buffer_memory = "0%" } ] # Optional (default: []). Allowed: AutoscalingPolicy objects with unique names. # Behavior: [] manages no policies and removes previously module-managed policies. autoscaling_policies = [ { # Required. Allowed: a unique non-empty AutoscalingPolicy name. # Behavior: identifies this workload-matching policy. name = "production" # Optional (omitted: server/default). Allowed: true or false. # Behavior: activates or suspends this policy. enable = true # Required. Allowed: the name of an existing or managed RecommendationPolicy. # Behavior: selects the recommendation algorithm used by matched workloads. recommendation_policy_name = "balanced" # Optional (default for a new policy: 0). Allowed: signed 32-bit integer. # Behavior: higher values win when multiple policies match; ties use the oldest. priority = 10 # Optional (omitted/null: preserve; new policy: cpu and memory). Allowed: cpu and/or memory, or []. # Behavior: restricts optimized resource requests; [] selects no resources. update_resources = ["cpu", "memory"] # Optional (omitted: controller default). Allowed: CPU quantity or percentage. # Behavior: requires at least this CPU drift before an update is eligible. drift_threshold_cpu = "5%" # Optional (omitted: controller default). Allowed: memory quantity or percentage. # Behavior: requires at least this memory drift before an update is eligible. drift_threshold_memory = "5%" # Optional (default for a new policy: off). Allowed: off, recreate, or inplace. # Behavior: controls how pods return toward baseline when this policy is removed. on_policy_removal = "recreate" # Optional (omitted/null: preserve). Allowed: true or false. # Behavior: boosts new Pods using the independent startup recommendation policy. startup_boost_enabled = true # Optional (omitted/null: preserve). Allowed: an existing RP name different from balanced. # Behavior: selects startup recommendations; takes precedence over legacy multipliers. startup_boost_recommendation_policy_name = "startup-balanced" # Optional (omitted/null: preserve; new policy: cpu and memory). Allowed: cpu and/or memory. # Behavior: limits startup boost to this scope; must overlap update_resources when boost is enabled. startup_boost_update_resources = ["cpu", "memory"] # Optional (omitted/null: preserve). Allowed: non-negative Go durations. # Behavior: requires both minimum Pod age and continuous Ready duration before reversion. startup_boost_min_boost_duration = "5m" startup_boost_min_ready_duration = "3m" # Optional (omitted: runtime optimization enabled). Allowed: true or false. # Behavior: disables runtime-language-specific optimization when true. disable_runtime_optimization = false # Optional (kind default: DaemonSet hold, otherwise recreate). Allowed: recreate or hold. # Behavior: chooses the fallback when an in-place update cannot continue. in_place_fallback_default_policy = "recreate" # Optional (omitted: use default fallback). Allowed keys are PodResizePending, # QoSChangeForbidden, MemoryLimitsAddForbidden, ResourceLimitsRemoveForbidden, # ResourceRequestsRemoveForbidden, ResourceMemoryLimitCannotBeDecreased, and # JVMHeapDrift; values: recreate or hold. Behavior: overrides fallback per reason. in_place_fallback_reason_policies = { JVMHeapDrift = "hold" } # Optional (omitted/null: preserve; []: clear). Allowed: target reference objects. # Behavior: selects workloads to which this AutoscalingPolicy applies. target_refs = [ { # Required. Allowed: a Kubernetes API version such as apps/v1. # Behavior: identifies the target resource API group/version. api_version = "apps/v1" # Required. Allowed: Deployment, StatefulSet, or DaemonSet. # Behavior: restricts the target controller kind. kind = "Deployment" # Optional (omitted/null: preserve; empty string: all names). Allowed: a workload name. # Behavior: restricts the target to this exact name. name = "api" # Optional (omitted/null: preserve; empty string: all namespaces). Allowed: a namespace name. # Behavior: restricts the target to this namespace. namespace = "production" # Optional (omitted/null: preserve; {}: clear). Allowed: a Kubernetes selector object. # Behavior: further restricts matching workloads; all selector parts are ANDed. label_selector = { # Optional (omitted/null: preserve; {}: clear exact-label constraints). Allowed: map(string). # Behavior: requires every listed label key/value pair. match_labels = { app = "api" } # Optional (omitted/null: preserve; []: clear expression constraints). Allowed: selector expressions. # Behavior: requires every listed expression to match. match_expressions = [ { # Required. Allowed: a valid Kubernetes label key. # Behavior: selects the label evaluated by this expression. key = "tier" # Required. Allowed: In, NotIn, Exists, or DoesNotExist. # Behavior: controls how the label is compared with values. operator = "In" # Optional by schema. Allowed: non-empty for In/NotIn; empty for Exists/DoesNotExist. # Behavior: supplies comparison values for the operator. values = ["backend"] } ] } } ] # Optional (omitted/null: preserve; []: clear and use controller defaults). Allowed: schedule objects. # Behavior: controls when matched workloads may update and which mode is active. update_schedules = [ { # Required. Allowed: a unique non-empty schedule name within this policy. # Behavior: identifies the update-window item. name = "weekday-window" # Required. Allowed: oncreate, recreate, inplace, or off. # Behavior: selects the update method during this item. mode = "inplace" # Optional. Allowed: a standard cron expression. # Behavior: starts the window; null preserves the matched item's value, while "" clears it. schedule = "0 9 * * 1-5" # Optional. Allowed: a Go duration such as 8h. # Behavior: sets window length; a new item with no schedule or duration is always active. duration = "8h" } ] # Optional (omitted/null: preserve; []: clear and use controller defaults). Allowed: per-resource policies. # Behavior: controls how CPU or memory limits relate to recommended requests. limit_policies = [ { # Required. Allowed: cpu or memory. # Behavior: selects the resource governed by this entry. resource = "cpu" # Optional. Allowed: true; configure only one action in a limit-policy entry. # Behavior: removes the CPU limit from matched workloads. remove_limit = true # Optional alternative. Allowed: true. # Behavior: keeps the baseline limit unchanged instead of removing it. # keep_limit = true # Optional legacy-compatible alternative. Allowed: numeric string 1.0-5.0. # Behavior: sets limit to recommended request multiplied by this value. # multiplier = "2.0" }, { # Required. Allowed: cpu or memory. # Behavior: selects the resource governed by this entry. resource = "memory" # Optional. Allowed: numeric string 1.0-5.0; configure only one action per entry. # Behavior: preserves existing limits unless more headroom is needed; never decreases them. auto_headroom = "1.5" } ] } ] # Optional (default: []). Allowed: proactive-update filter objects. # Behavior: performs enable operations during create/update; this is not a persistent policy list. enable_proactive = [ { # Optional (omitted/[]: all namespaces). Allowed: exact namespace names. # Behavior: matches workloads in these namespaces. namespaces = ["production"] # Optional (omitted/[]: all supported kinds). Allowed: Deployment, StatefulSet, DaemonSet. # Behavior: matches only these workload kinds. workload_kinds = ["Deployment", "StatefulSet"] # Optional (omitted/empty: any name). Allowed: a string. # Behavior: performs a substring match against workload names. workload_name = "api" # Optional (omitted/empty: any state). Allowed: Ready or NotReady. # Behavior: matches workloads currently in this readiness state. workload_state = "Ready" # Optional (omitted/[]: any policy). Allowed: AutoscalingPolicy names. # Behavior: matches workloads currently assigned to any listed policy. autoscaling_policy_names = ["production"] # Optional (omitted/[]: any state). Allowed: Ready, Recommending, Updating, Deleting. # Behavior: matches workloads in any listed optimization state. optimization_states = ["Ready"] # Optional (omitted: either state). Allowed: true or false. # Behavior: filters current state; true selects disabled workloads for this enable operation. disable_proactive_update = true # Optional (omitted/[]: any policy). Allowed: RecommendationPolicy names. # Behavior: matches workloads currently using any listed policy. recommendation_policy_names = ["balanced"] # Optional (omitted/[]: any runtime). Allowed: java, golang, python, nodejs, # dotnet, ruby, or php. Behavior: matches the primary detected runtime language. runtime_languages = ["java"] # Optional (omitted: either state). Allowed: true or false. # Behavior: matches workloads by whether their resources are already optimized. optimized = false # Optional (omitted/null: either state). Allowed: true or false. # Behavior: filters by startup boost state; false is also an active filter. startup_boost_enabled = true } ] # Optional (default: []). Allowed: the same filter fields as enable_proactive. # Behavior: performs disable operations during create/update; this is not a persistent policy list. disable_proactive = [ { # Optional (omitted/[]: all namespaces). Allowed: exact namespace names. # Behavior: limits this disable operation to kube-system workloads. namespaces = ["kube-system"] # Optional (omitted: either state). Allowed: true or false. # Behavior: false selects workloads where proactive update is currently enabled. disable_proactive_update = false } ]

Legacy startup boost compatibility

The startup boost multiplier inputs are nested inside an autoscaling_policies object and are exposed only for compatibility with legacy policies. Do not use them as the recommended configuration for a new policy.

# Legacy compatibility only. Add this list inside the module block. # Optional (default: []). Allowed: AutoscalingPolicy objects. # Behavior: this example represents an existing legacy startup-boost policy only. autoscaling_policies = [ { # Required. Allowed: a unique non-empty AutoscalingPolicy name. # Behavior: identifies the legacy policy. name = "legacy-startup-boost" # Optional (omitted: server/default). Allowed: true or false. # Behavior: activates or suspends the policy. enable = true # Required. Allowed: an existing RecommendationPolicy name. # Behavior: selects the steady-state recommendation policy. recommendation_policy_name = "balanced" # Optional, legacy compatibility only. Allowed: true or false. # Behavior: enables legacy multiplier-based startup boost. startup_boost_enabled = true # Optional, legacy compatibility only. Allowed: a Go duration such as 5m. # Behavior: keeps the boost active for at least this long. startup_boost_min_boost_duration = "5m" # Optional, legacy compatibility only. Allowed: a Go duration such as 3m. # Behavior: waits for this continuous ready duration before removing the boost. startup_boost_min_ready_duration = "3m" # Optional, legacy compatibility only. Allowed: numeric string 1.0-5.0. # Behavior: multiplies startup CPU resources by this value. startup_boost_multiplier_cpu = "2.0" # Optional, legacy compatibility only. Allowed: numeric string 1.0-5.0. # Behavior: multiplies startup memory resources by this value. startup_boost_multiplier_memory = "2.0" # Optional (omitted/null: preserve; []: clear). Allowed: target reference objects. # Behavior: selects workloads to which this legacy policy applies. target_refs = [ { # Required. Allowed: a Kubernetes API version such as apps/v1. # Behavior: identifies the target resource API group/version. api_version = "apps/v1" # Required. Allowed: Deployment, StatefulSet, or DaemonSet. # Behavior: restricts the target controller kind. kind = "Deployment" # Optional (omitted/null: preserve; empty string: all names). Allowed: a workload name. # Behavior: restricts the target to this exact name. name = "api" # Optional (omitted/null: preserve; empty string: all namespaces). Allowed: a namespace name. # Behavior: restricts the target to this namespace. namespace = "production" } ] } ]

Use the two distinct RecommendationPolicy objects in the complete Workload Autoscaler example for new policies. The dedicated startup policy takes precedence when its name is non-empty. To switch an existing policy back to legacy multipliers, explicitly set startup_boost_recommendation_policy_name = "" and configure the multipliers; null preserves the remote reference.

Startup boost requires Kubernetes v1.33 or later and compatible cluster CRDs, webhook, controller, and agent components. See Resource Startup Boost and JVM heap bounds for runtime requirements. Server v1.36.4 compatibility does not replace those managed-cluster requirements.

Management semantics

Optional policy and collection fields set to null are unmanaged: updates preserve the remote value. An explicit empty value requests a clear or reset, as listed below. Within a non-empty policy or EBS object, null child fields preserve their remote values. An object whose optional children are all null is treated as an empty object, so use a null object to leave the entire policy unmanaged.

With a referenced module template, an omitted key inherits the template value; an explicit null on the concrete object overrides that value and leaves the field unmanaged. An explicit {} overrides the template policy with a reset. New objects use creation defaults for unconfigured fields.

Omitting a top-level module input uses that input’s declared default, which is not always null. For example, collection inputs with a default of [] still manage an empty set when omitted. Pass null explicitly where accepted when you intend to leave the value unmanaged.

Value or changeEffect
nodeclasses, nodepools, scheduled_rebalances, recommendation_policies, or autoscaling_policies set to nullLeaves the corresponding remote objects unmanaged.
The same collection set to []Removes only objects previously managed by this module. RecommendationPolicies cannot be removed while still referenced.
workloads = null or workloads = []Stops managing workload overrides; does not reset settings already saved on the server.
job_nodepool_optimization = {}Removes the Job policy.
Job provisioning_delay = ""Clears only that delay and preserves null sibling fields.
EKS volume_size_policy = {} or GKE size_policy = {}Removes the dynamic disk policy while retaining the disk’s fixed size.
EKS block_device_mappings = []Removes custom block device mappings.
EKS ebs = {} or volume_size = ""Clears the selected EBS settings. A retained snapshot is required when clearing the size; a dynamic size policy also requires a fixed size.
EKS volume_type = ""Removes the volume-type override.
memory_extension = {} or nri_swap_policy = {}Disables the feature and clears its optional policy settings.
Memory Extension cold_memory = {} or cached_memory = {}Restores that section’s server defaults.
Memory Extension reclaim_policy = "" or cold-memory sizing_mode = ""Clears that override and restores its server default.
Memory Extension or NRI enabled = falseExplicitly disables that feature; null preserves it.
NodePool disruption_cooldown = ""Removes the pool override and uses the cluster setting.
disruption_cooldown = "0s"Explicitly disables the additional delay; null preserves it.
A JVM heap-bound field set to ""Clears that bound; null preserves it.
AP update_resources = []Explicitly manages no resources; omitted new-policy scope defaults to CPU and memory. Startup boost must be disabled if no resources are managed.
AP label_selector = {}Clears the selector; a null selector preserves it.
One limit-policy action selectedremove_limit = true, keep_limit = true, non-empty multiplier, or non-empty auto_headroom replaces the previous action. Configure at most one.
Limit-policy remove_limit = false, keep_limit = false, or a factor set to ""Disables only that action; does not select another action. All action fields null preserve the current action.
GKE auto_count = true or a positive countSelects automatic or fixed Local SSD sizing and clears the competing mode; do not configure both.
GKE ephemeral_storage_local_ssd = {}Clears the count and automatic mode, returning to bundled-only storage. Requires Local SSD to be already enabled or the enable switch to be explicitly true. To disable the feature, set enable_local_ssd_ephemeral_storage = false and omit the configuration object or set it to null.
EKS non-empty ami_aliasReplaces competing AMI selectors and clears an incompatible AMI family. An existing InstanceProfile-based NodeClass requires recreation before switching to role.

When upgrading to provider v0.7.0, review any AP update_resources = [] values. Earlier provider versions treated [] as CPU and memory; v0.7.0 explicitly selects no resources. Set update_resources = ["cpu", "memory"] to retain the former behavior.

Raw origin_nodeclass_json and origin_nodepool_json replace the corresponding typed configuration. Use one approach per object. skip_restore = true takes precedence over restore counts during destroy, and a GKE restore_desired_sizes entry takes precedence for that named node pool.

Empty values still need to be valid for their fields. Required fields, non-empty disruption budget lists, and startup boost resource lists cannot be cleared with an invalid empty value. cluster_setting = {} preserves existing settings.

Changing managed fields in the CloudPilot console can create drift; treat the Terraform or OpenTofu configuration as the source of truth for those fields. Maintenance mode and Saving Report baseline dates stay outside these resources; applying other cluster settings preserves their remote values.

Use provider resources directly

Direct provider resources are useful when an existing root module needs resource-level control or when module composition is not appropriate.

resource "cloudpilotai_eks_cluster" "example" { # Required. Allowed: a non-empty existing EKS cluster name. # Behavior: selects the EKS cluster to onboard and manage. cluster_name = "my-eks-cluster" # Required. Allowed: an AWS Region ID. # Behavior: locates the cluster and AWS resources. region = "us-west-2" # Optional (default: false). Allowed: true or false. # Behavior: enables Node Autoscaler rebalance. enable_rebalance = true # Optional (default: 0). Allowed: a non-negative integer. # Behavior: restores this many nodes before uninstall; 0 disables restore. restore_node_number = 3 } resource "cloudpilotai_gke_cluster" "example" { # Required. Allowed: a non-empty existing GKE cluster name. # Behavior: selects the GKE cluster to onboard and manage. cluster_name = "my-gke-cluster" # Required. Allowed: a Google Cloud region ID. # Behavior: supplies the resource's regional context. region = "us-central1" # Optional (default: discovered). Allowed: a Google Cloud project ID. # Behavior: locates the cluster; omitted uses metadata, then active gcloud project. project_id = "my-gcp-project" # Optional (default: false). Allowed: true or false. # Behavior: enables Node Autoscaler rebalance. enable_rebalance = true # Optional (default: unset). Allowed: a non-negative integer. # Behavior: restores this total node count before uninstall. restore_node_number = 3 }

The provider also includes cloudpilotai_workload_autoscaler and read-only data sources for EKS clusters, GKE clusters, and Workload Autoscaler state. See the provider documentation  for the generated resource and data-source schemas.

Next steps

Last updated on