Manage an existing cluster with Terraform-Container Service for Kubernetes(ACK)-阿里云帮助中心

Use Terraform to manage existing clusters

Terraform supports importing existing Container Service for Kubernetes (ACK) resources — clusters and node pools — into its state. Once imported, you can manage those resources through Terraform configuration files like any resource you created with Terraform.

This topic walks through importing an existing ACK managed cluster and its node pool, verifying that state is consistent with the live resources, and testing scale-out on the imported node pool.

Before you begin

An ACK managed cluster with a node pool that has two nodes. See Use Terraform to create an ACK managed cluster.
Terraform installed and the alicloud provider available.

Risks and precautions

Review the following before running any terraform import or terraform apply command:

Risk	Precaution
Import modifies state directly and cannot be previewed	Back up `terraform.tfstate` before running `terraform import`
Fields marked `# forces replacement` in plan output destroy and recreate the resource if applied	Do not add these fields to `main.tf` unless you intend to recreate the resource
Fields marked `(known after apply)` are computed by Terraform	Skip these fields entirely
Incomplete configuration causes a non-zero plan	Run `terraform plan` repeatedly until it reports no changes before running `terraform apply`

Set up the working directory

Create a working directory and add a main.tf file with the provider block:
```
HELPCODEESCAPE-json
provider "alicloud" {
}
```

Initialize Terraform:

HELPCODEESCAPE-shell
terraform init

Expected output:

HELPCODEESCAPE-json
Initializing the backend...

Initializing provider plugins...
- Checking for available provider plugins...
- Downloading plugin for provider "alicloud" (hashicorp/alicloud) 1.90.1...
...

You may now begin working with Terraform. Try running "terraform plan" to see
any changes that are required for your infrastructure. All Terraform commands
should now work.

If you ever set or change modules or backend configuration for Terraform,
rerun this command to reinitialize your working directory. If you forget, other
commands will detect it and remind you to do so if necessary.

Import the cluster

Add an empty resource block for the cluster to main.tf:

HELPCODEESCAPE-json
# ACK managed cluster
resource "alicloud_cs_managed_kubernetes" "default" {
}

Import the cluster. Replace <Cluster-ID> with your cluster ID:

HELPCODEESCAPE-shell
terraform import alicloud_cs_managed_kubernetes.default <Cluster-ID>

Expected output:

HELPCODEESCAPE-json
alicloud_cs_managed_kubernetes.default: Importing from ID "cc7c582b0XXXXXcb80ae118eef0cb12"...
alicloud_cs_managed_kubernetes.default: Import complete!
  Imported alicloud_cs_managed_kubernetes
alicloud_cs_managed_kubernetes.default: Refreshing state... [id=cc7c582b0XXXXXcb80ae118eef0cb12]

Import successful!

The resources that were imported are shown above. These resources are now in
your Terraform state and will henceforth be managed by Terraform.

The cluster's full configuration is now written to terraform.tfstate.

Open terraform.tfstate and copy the required field values into main.tf. Start with the minimum required field:

HELPCODEESCAPE-json
provider "alicloud" {
}

resource "alicloud_cs_managed_kubernetes" "default" {
  worker_vswitch_ids = [   # Required — copy from terraform.tfstate
    .....
  ]
}

Run terraform plan to compare your configuration against the live cluster:

Symbol in plan output	Meaning	Action
`->`	Value update	Add the field to `main.tf` with the current live value
`+`	New field	Add the field to `main.tf`
`(known after apply)`	Computed by Terraform	Skip — do not add to `main.tf`
`# forces replacement`	Adding this field destroys and recreates the resource	Do not add unless you intend to recreate the resource. See alicloud_cs_managed_kubernetes — Only works for Create Operation.

HELPCODEESCAPE-shell
terraform plan

The plan output lists differences between main.tf and the live resource. Use the following guide to decide which fields to add: Example plan output (abbreviated):

HELPCODEESCAPE-json
alicloud_cs_managed_kubernetes.default: Refreshing state..
Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
-/+ destroy and then create replacement

Terraform will perform the following actions:
  # alicloud_cs_managed_kubernetes.default must be replaced
      ~ cluster_spec                 = "ack.pro.small" -> (known after apply)
      ~ connections                  = {
          - "api_server_internet" = ""
          - "api_server_intranet" = "https://10.XX.XX.154:6443"
          - "service_domain"      = "*.ca28e9fbefe8647d2a21057bcf5c993e0.cn-hangzhou.alicontainer.com"
        } -> (known after apply)
      - control_plane_log_components = [] -> null
      + control_plane_log_project    = (known after apply)
      + control_plane_log_ttl        = (known after apply)
        deletion_protection          = false
      - enable_rrsa                  = false -> null
      ~ id                           = "ca28e9fbeXXXXXX1057bcf5c993e0" -> (known after apply)
      + install_cloud_monitor        = (known after apply)
      + is_enterprise_security_group = (known after apply)
      + load_balancer_spec           = "slb.s1.small"
      ~ name                         = "TFCESHI" -> (known after apply)
      + name_prefix                  = "Terraform-Creation"  # Changes the cluster name to Terraform-Creation. If you do not want to change the name, you can use the name field instead.
      ~ nat_gateway_id               = "ngw-bp17XXXXguwkeyj" -> (known after apply)
      + new_nat_gateway              = true
      ~ node_cidr_mask               = 26 -> 24 # forces replacement
      + node_port_range              = (known after apply)
      + platform                     = (known after apply)
      - pod_cidr                     = "172.16.224.0/20" -> null # forces replacement
        proxy_mode                   = "ipvs"
      ~ resource_group_id            = "rg-acfmwXXXXesq" -> (known after apply)
      ~ rrsa_metadata                = [
          - {
              - enabled                = false
              - ram_oidc_provider_arn  = ""
              - ram_oidc_provider_name = ""
              - rrsa_oidc_issuer_url   = ""
            },
        ] -> (known after apply)
      ~ security_group_id            = "sg-bp11XXXXXX9d8rp3" -> (known after apply)
      - service_cidr                 = "192.168.0.0/16" -> null # forces replacement
      ~ slb_id                       = "lb-bp1dqXXXXXXeifbb3" -> (known after apply)
      + slb_internet                 = (known after apply)
      + slb_internet_enabled         = true
      ~ slb_intranet                 = "10.XX.XXX.154" -> (known after apply)
      - tags                         = {} -> null
      - timezone                     = "Asia/Shanghai" -> null # forces replacement
      ~ version                      = "1.31.1-aliyun.1" -> (known after apply)
      ~ vpc_id                       = "vpc-bp1l44aXXXXXXc54ev" -> (known after apply)
      + worker_auto_renew_period     = (known after apply)
      + worker_disk_size             = (known after apply)
      + worker_instance_charge_type  = (known after apply)
      + worker_period                = (known after apply)
      + worker_period_unit           = (known after apply)
      ~ worker_ram_role_name         = "KubernetesWorkerRole-04d86599-xxxx-487a-b927-379e63b9d485" -> (known after apply)
        worker_vswitch_ids           = [
            "vsw-bp1fXXXXX2nuig6h",
        ]

      ~ maintenance_window {
          ~ duration         = "3h" -> (known after apply)
          ~ enable           = true -> (known after apply)
          ~ maintenance_time = "2024-10-22T16:00:00.000Z" -> (known after apply)
          ~ weekly_period    = "Wednesday" -> (known after apply)
        }

      + operation_policy {
          + cluster_auto_upgrade {
              + channel = (known after apply)
              + enabled = (known after apply)
            }
        }

      - timeouts {}

      + worker_nodes {
          + id         = (known after apply)
          + name       = (known after apply)
          + private_ip = (known after apply)
        }
    }

Plan: 1 to add, 0 to change, 1 to destroy.

Note To ensure the resource template is consistent with the resource status, you must manually add the missing parameter definitions to the template until running terraform plan no longer shows any changes. A complete main.tf looks similar to:

HELPCODEESCAPE-json
provider "alicloud" {
  region = "cn-hangzhou"   # The region where the cluster resides
}

resource "alicloud_cs_managed_kubernetes" "default" {
  worker_vswitch_ids           = [
            "vsw-bp1fXXXXX2nuig6h"
        ]
  deletion_protection          = false
  load_balancer_spec           = "slb.s1.small"
  name                         = "TFCESHI"
  new_nat_gateway              = true
  proxy_mode                   = "ipvs"
  slb_internet_enabled         = true
  node_cidr_mask               = 26
  service_cidr                 = "192.168.0.0/16"
  pod_cidr                     = "172.16.224.0/20"
  control_plane_log_components = []
  enable_rrsa                  = false
  tags                         = {}
  timezone                     = "Asia/Shanghai"
}

Apply the configuration to sync the state:

HELPCODEESCAPE-shell
terraform apply

Expected output:

HELPCODEESCAPE-json
alicloud_cs_managed_kubernetes.default: Modifying... [id=cc7c582b0XXXXXcb80ae118eef0cb12]
alicloud_cs_managed_kubernetes.default: Modifications complete after 2s [id=cc7c582b0XXXXXcb80ae118eef0cb12]

Apply complete! Resources: 0 added, 1 changed, 0 destroyed.

Import the node pool

Add an empty resource block for the node pool to main.tf:

HELPCODEESCAPE-json
# Node pool
resource "alicloud_cs_kubernetes_node_pool" "default" {
}

Import the node pool. Replace <Cluster-ID> with the cluster ID from the previous section and <Nodepool-ID> with the node pool ID. Separate the two IDs with a colon (:):

HELPCODEESCAPE-shell
terraform import alicloud_cs_kubernetes_node_pool.default <Cluster-ID>:<Nodepool-ID>

Expected output:

HELPCODEESCAPE-json
alicloud_cs_kubernetes_node_pool.default: Importing from ID "cc7c582b0XXXXXcb80ae118eef0cb12*:np0f8f219XXXXX5d4aa503c3d24ca****"...
alicloud_cs_kubernetes_node_pool.default: Import complete!
  Imported alicloud_cs_kubernetes_node_pool
alicloud_cs_kubernetes_node_pool.default: Refreshing state... [id=cc7c582b0XXXXXcb80ae118eef0cb12:np651662XXXXXd9979360b24b1a009]

Import successful!

The resources that were imported are shown above. These resources are now in
your Terraform state and will henceforth be managed by Terraform.

The node pool configuration is written to terraform.tfstate.

Copy the required fields from terraform.tfstate into the node pool resource block in main.tf:

HELPCODEESCAPE-json
# Node pool
resource "alicloud_cs_kubernetes_node_pool" "default" {
  name           = ....  # The node pool name
  instance_types = ....  # The instance type
  vswitch_ids    = ....  # The vSwitch ID
  cluster_id     = alicloud_cs_managed_kubernetes.default.id
}

Apply the configuration:

HELPCODEESCAPE-shell
terraform apply

Expected output:

HELPCODEESCAPE-json
alicloud_cs_kubernetes_node_pool.default: Refreshing state... [id=cc7c5XXXXX546dcb80ae118eef0cb12:np651662dfc3e4440d9979360b24b1a009]
alicloud_cs_managed_kubernetes.default: Refreshing state... [id=cc7c582XXXXX6dcb80ae118eef0cb12]

Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
  ~ update in-place

Terraform will perform the following actions:

  ............


        # (2 unchanged blocks hidden)
    }
Plan: 0 to add, 1 to change, 0 to destroy.

Both the cluster and node pool are now managed by Terraform. Use main.tf to make future configuration changes.

Verify scale-out

Test that the imported node pool responds to configuration changes by scaling out from 2 to 3 nodes.

Add desired_size = 3 to the node pool resource block in main.tf:

HELPCODEESCAPE-json
resource "alicloud_cs_kubernetes_node_pool" "default" {
  .....
  desired_size = 3
}

Apply the change:

HELPCODEESCAPE-shell
terraform apply

When prompted, type yes and press Enter. Expected output:

HELPCODEESCAPE-json
alicloud_cs_kubernetes_node_pool.default: Refreshing state... [id=cc7c5XXXXX546dcb80ae118eef0cb12:np651662dfc3e4440d9979360b24b1a009]
alicloud_cs_managed_kubernetes.default: Refreshing state... [id=cc7c582bXXXXXcb80ae118eef0cb12]

Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
  ~ update in-place

Terraform will perform the following actions:

  # alicloud_cs_kubernetes_node_pool.default will be updated in-place
  ~ resource "alicloud_cs_kubernetes_node_pool" "default" {
      ~ desired_size               = 2 -> 3
        # (2 unchanged blocks hidden)
    }

Plan: 0 to add, 1 to change, 0 to destroy.

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value: yes

alicloud_cs_kubernetes_node_pool.default: Modifying... [id=cc7c582b0XXXXXcb80ae118eef0cb12:np651662dfc3e4440d9979360b24b1a009]
alicloud_cs_kubernetes_node_pool.default: Still modifying... [id=cc7c582XXXXX6dcb80ae118eef0cb12:np651662dXXXXX0d9979360b24b1a009, 10s elapsed]
alicloud_cs_kubernetes_node_pool.default: Still modifying... [id=cc7c582bXXXXX6dcb80ae118eef0cb12:np651662XXXXX0d9979360b24b1a009, 20s elapsed]
alicloud_cs_kubernetes_node_pool.default: Still modifying... [id=cc7c582bXXXXXdcb80ae118eef0cb12:np65166XXXXX440d9979360b24b1a009, 30s elapsed]
alicloud_cs_kubernetes_node_pool.default: Still modifying... [id=cc7c582b0XXXXXae118eef0cb12:np6516XXXXX3e4440d9979360b24b1a009, 40s elapsed]
alicloud_cs_kubernetes_node_pool.default: Still modifying... [id=cc7c582b0XXXXX6dcb80ae118eef0cb12:np65166XXXXXe4440d9979360b24b1a009, 50s elapsed]
alicloud_cs_kubernetes_node_pool.default: Modifications complete after 1m0s [id=cc7c582b0b2b546dcb80ae118eef0cb12:np651662dfc3e4440d9979360b24b1a009]

Apply complete! Resources: 0 added, 1 changed, 0 destroyed.

In the ACK console, open Node Pools for your cluster and confirm that the node count has increased to 3.

What's next

Terraform is available as a managed service in Resource Orchestration Service (ROS). Deploy Terraform templates directly in the ROS console. See Create a Terraform stack.

References

Configure Terraform Init Acceleration