Use Terraform to manage existing clusters - Container Service for Kubernetes

Terraform enables you to import and manage existing Container Service for Kubernetes (ACK) resources, such as clusters and node pools. This topic describes how to use Terraform to manage existing ACK managed clusters.

Prerequisites

An ACK managed cluster is created. The cluster contains a node pool that consists of two nodes. For more information, see Use Terraform to create an ACK managed cluster.

Procedure

Create a working directory, and then create a configuration file named main.tf in that directory.
```
provider "alicloud" {
}
```

Run the following command to initialize the environment for Terraform:

terraform init

If the following information is returned, Terraform is initialized:

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 the cluster resources to the main.tf file.

# The ACK managed cluster.
resource "alicloud_cs_managed_kubernetes" "default" {
}

Run the following command to import the cluster.

Replace <Cluster-ID> with the ID of the cluster that you want to import.

terraform import alicloud_cs_managed_kubernetes.default <Cluster-ID>

Expected output:

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 following imported cluster information is displayed in the terraform.tfstate file:

{
      "mode": "managed",
      "type": "alicloud_cs_managed_kubernetes",
      "name": "default",
      "provider": "provider.alicloud",
      "instances": [
        {
          "mode": "managed",
          "type": "alicloud_cs_managed_kubernetes",
          "name": "default",
          "provider": "provider.alicloud",
          "instances": [
             ........
          ]
        }
      ]
    }

Based on the content of the terraform.tfstate file, complete the required fields in main.tf.

provider "alicloud" {
}

resource "alicloud_cs_managed_kubernetes" "default" {
  worker_vswitch_ids = [   # Configure the required fields.
    .....
  ]
}

Run the following command to compare your local resources with those in the cluster, ensuring that the main.tf file is consistent with the cluster resources:

terraform plan

Add the following content marked with -> for status updates or + for new fields to the main.tf file. You can ignore fields labeled (known after apply). For more information, see Only works for Create Operation.

alicloud_cs_managed_kubernetes.default: Refreshing state..
erraform 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:
# Add the following fields whose values are updated to the main.tf file.
  # 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.

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"
}

Run the following command to import the preceding fields to the cluster:

terraform apply

The following information is returned after the fields are imported:

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 the cluster's node resources to the main.tf file.

# The ACK managed cluster.
resource "alicloud_cs_kubernetes_node_pool" "default" {
}

Run the following commands to import the node pool.

Replace <Cluster-ID> with the cluster ID that you specified in the previous step. Replace <Nodepool-ID> with the ID of the node pool that you want to import. Separate the cluster ID and node pool ID with a colon (:).

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

Expected output:

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 following imported node pool information is included in the terraform.tfstate file:

.....
"resources": [
    {
      "mode": "managed",
      "type": "alicloud_cs_kubernetes_node_pool",
      "name": "default",
      "provider": "provider.alicloud",
      "instances": [
        .....
      ]
    }
  ]

Based on the content of the terraform.tfstate file, populate the required fields in main.tf.

provider "alicloud" {
}

# The node pool.
resource "alicloud_cs_kubernetes_node_pool" "default" {
  name           =  ....  # The name of the node pool.
  instance_types =  ....  # The instance type of the node pool.
  vswitch_ids    =  ....  # The vSwitch ID of the node pool.
  cluster_id     = alicloud_cs_managed_kubernetes.default.id # Use the cluster_id
}

Run the following command to import the preceding fields to the cluster:

terraform apply

The following information is returned after the fields are imported:

alicloud_cs_kubernetes_node_pool.default: Refreshing state... [id=cc7c5XXXXX6dcb80ae118eef0cb12:np651662XXXXXd9979360b24b1a009]
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.

After the cluster is imported, you can use the main.tf file to manage the cluster or node pool.

Verify the scale-out operation of the node pool.

Verify the node pool scale-out operation using main.tf.

For example, to scale out the imported node pool to 3 nodes, add a desired_size = 3 field to the main.tf file.

......

# The ACK managed cluster.
resource "alicloud_cs_kubernetes_node_pool" "default" {
  .....
  # The expected number of nodes in the node pool is three.
  desired_size = 3
}

.....

Run the following command to apply the change:

terraform apply

In the returned information, type yes, press Enter, and wait for the change to complete.

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:np651662dfc3e4XXXXX360b24b1a009]
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.

You can log on to the ACK console and go to the Node Pools page to see that a node has been added to the node pool.

References

Terraform is available as a managed service in ROS. You can deploy Terraform templates in the ROS console. For more information, see Create a Terraform stack.