使用Terraform管理组件

组件类型

容器服务ACK管理的集群组件类型包括系统组件和可选组件。更多组件信息，请参见组件概述。

系统组件

可选组件

可选组件是ACK提供的非必需部署的组件，您可选择性的安装组件，用于扩展集群功能。可选组件在类型上可划分为应用管理组件、日志与监控管理组件、存储组件、网络组件及安全组件等。

组件管理实践

通过Terraform，您可以在创建集群时指定需要安装的组件，并在集群创建结束后对组件进行全生命周期管理，下面将介绍如何管理集群中的组件生命周期，以及一些场景下的最佳实践。

在创建集群时指定需要安装的组件

您可以在创建集群时，指定集群需要安装的组件，创建集群涉及的Resource如下：

• Kubernetes托管版集群：alicloud_cs_managed_kubernetes

• Kubernetes专有版集群：alicloud_cs_kubernetes

• ACK Edge集群：alicloud_cs_edge_kubernetes

• ACK Serverless集群：alicloud_cs_serverless_kubernetes

以上Resource均可以通过addons属性定义创建集群时需要安装的组件，addons属性定义如下：

# 以托管版集群为例。
resource "alicloud_cs_managed_kubernetes" "default" {
  # 其它参数。
  # ...

  # addons为list结构，通过在Resource中定义addons属性，表明创建集群时安装该组件。
  addons {
    # 组件的名称，您可以通过Data Source中的alicloud_cs_kubernetes_addons查询。
    # 当前集群已经安装的，以及可以安装的组件和其对应版本信息。
    name = "XXX"

    # 组件的自定义参数，某些集群组件开启了自定义参数配置的能力，您可以使用该字段来为组件指定其自定义参数，具体指定方法，请参见下文“修改集群组件的自定义配置参数”一节。
    config = jsonencode(
      {
        ....
      }
    )

    # 该参数默认值为false（布尔值类型），ACK会默认安装部分组件，方便用户管理集群。若您在创建集群时不需安装这些组件，可设置disabled=true。
    disabled = XXX
  }
}

ACK中组件配置方式如下表所示。

在创建集群后管理组件生命周期

管理组件的生命周期前提是您已经创建了一个Kubernetes集群，如果您还没有创建Kubernetes集群，请先创建集群。

对于集群中的组件，您可以通过Resource中的alicloud_cs_kubernetes_addon来管理组件的生命周期，包括组件的安装、升级、卸载、自定义配置的修改。alicloud_cs_kubernetes_addon的属性和定义如下：

resource "alicloud_cs_kubernetes_addon" "addon-example" {
  # 集群ID。
  cluster_id = "XXXX"

  # 组件的名称，可以通过Data Source中的alicloud_cs_kubernetes_addons，查询当前集群所有已安装的以及可以安装的组件和其对应版本信息。
  name = "XXXX"

  # 组件的版本信息。
  version = "XXXX"

  # 组件的自定义参数，为JSON格式的字符串，可以使用Terraform自带的jsonencode方法进行配置，也可以直接使用JSON字符串进行配置（需要注意转义），某些集群组件开启了自定义参数配置的能力，您可以使用该字段来为组件指定其自定义参数，具体指定方法，请参见下文“修改集群组件的自定义配置参数”一节 。
  config = jsonencode(
    {
      ....
    }
  )
}

您可以通过直接写入JSON字符串的方式配置组件自定义参数，但是需要注意转义。例如对于nginx-ingress-controller组件，有以下两种配置方法：

• 通过jsonencode配置参数：

  config = jsonencode(   
    {       
      IngressSlbNetworkType="internet"       
      IngressSlbSpec="slb.s2.small"     
    }  
  )

• 通过直接使用字符串的方式配置参数：

  config = "{\"IngressSlbNetworkType\":\"internet\",\"IngressSlbSpec\":\"slb.s2.small\"}"

将集群已安装的组件导入Terraform管理

对于集群已经安装的组件，您可以通过terraform import的方式，将组件导入Terraform进行管理。下面以nginx-ingress-controller组件为例说明如何将集群已安装的组件导入Terraform管理。

1. 新建一个后缀名为.tf的文件或使用您已创建的.tf文件，并定义一个Resource。

   Resource中的alicloud_cs_kubernetes_addon用于管理集群的Addon，其中不需要填写任何内容。

   resource "alicloud_cs_kubernetes_addon" "nginx-ingress-controller" {
   }

2. 执行以下命令，导入集群已安装的nginx-ingress-controller组件。

   Terraform会拉取集群内的nginx-ingress-controller组件配置，并写入到后缀名为.state的文件中。

   terraform import alicloud_cs_kubernetes_addon.nginx-ingress-controller <cluster_id>:nginx-ingress-controller

3. 执行命令terraform plan，根据其得到的结果，您可以看到集群内nginx-ingress-controller组件配置和定义的Resource之间的差异。

   根据差异的结果，以及.state后缀的文件内容，补充您在步骤1中写入的Resource信息。直到执行指令terraform plan，显示本地的配置与集群中的组件配置没有任何差异后，即完成了组件的导入。

   resource "alicloud_cs_kubernetes_addon" "nginx-ingress-controller" {
     cluster_id = "XXXXX"
     name = "nginx-ingress-controller"
     version = "v1.2.1-aliyun.1"
     config = jsonencode(
       {
         IngressSlbNetworkType = "internet"
         IngressSlbSpec        = "slb.s2.small"
       }
     )
   }

安装集群组件

您可以通过Resource中的alicloud_cs_kubernetes_addon在已有集群中安装组件，下面以gatekeeper组件为例说明。

1. 在.tf文件中定义待安装组件的信息，需要指定以下信息。

   • 集群ID。

   • 组件名称和组件版本：

     集群可安装的组件名称和组件版本可以通过Data Source中的alicloud_cs_kubernetes_addons查询，查询结果仅返回每个组件最新的可安装版本。如果您需要安装组件的历史版本，请查看对应组件的Release日志，并指定对应的组件版本号。

   • （可选）组件的自定义配置：

     修改config字段进行组件自定义配置，可以使用Terraform内置的jsonencode方法来构建您需要的配置。组件的可配置参数可以通过Data Source中的alicloud_cs_kubernetes_addon_metadata进行查询，具体操作，请参见修改集群组件的自定义配置参数。

   展开查看详细信息

   resource "alicloud_cs_kubernetes_addon" "gatekeeper" {
     cluster_id = "ce36b7c61e126430b8b245730ca6d****"
     name = "gatekeeper"
     version = "v3.8.1.113-geb7947ef-aliyun"
     config = jsonencode(
       {
         AdmissionPodCpuLimit      = "1000m"
         AdmissionPodCpuRequest    = "100m"
         AdmissionPodMemoryLimit   = "512Mi"
         AdmissionPodMemoryRequest = "256Mi"
         AdmissionPodNumber        = 3
         AuditInterval             = 1800
         AuditPodCpuLimit          = "1000m"
         AuditPodCpuRequest        = "100m"
         AuditPodMemoryLimit       = "512Mi"
         AuditPodMemoryRequest     = "256Mi"
         EnableAuditPod            = false
         EnableMutatingWebhook     = false
       }
     )
   }

2. 执行以下命令，在集群中安装组件。

   terraform apply

   预期输出：

   Plan: 1 to add, 0 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_addon.gatekeeper: Creating...
   alicloud_cs_kubernetes_addon.gatekeeper: Still creating... [10s elapsed]
   alicloud_cs_kubernetes_addon.gatekeeper: Creation complete after 16s [id=XXXXX:gatekeeper]
   
   Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

   直到显示Apply complete!，说明组件安装完成。

升级集群组件

您可以通过Data Source中的alicloud_cs_kubernetes_addons来查询组件可升级的版本，如果发现有新版本的组件可升级，可以通过直接修改版本号的方式进行升级，下面以gatekeeper组件为例说明。

resource "alicloud_cs_kubernetes_addon" "gatekeeper" {
  cluster_id = "ce36b7c61e126430b8b245730ca6d****"
  name = "gatekeeper"

  # 修改Version为指定的可升级版本。
  version = "XXXXXXXXX"
  config = jsonencode(
    {
      AdmissionPodCpuLimit      = "1000m"
      AdmissionPodCpuRequest    = "100m"
      AdmissionPodMemoryLimit   = "512Mi"
      AdmissionPodMemoryRequest = "256Mi"
      AdmissionPodNumber        = 3
      AuditInterval             = 1800
      AuditPodCpuLimit          = "1000m"
      AuditPodCpuRequest        = "100m"
      AuditPodMemoryLimit       = "512Mi"
      AuditPodMemoryRequest     = "256Mi"
      EnableAuditPod            = false
      EnableMutatingWebhook     = false
    }
  )
}

执行命令terraform apply，进行组件升级，显示成功即完成了组件的升级。

修改集群组件的自定义配置参数

ACK的某些组件开启了用户自定义参数的配置能力，您可以通过Resource中的alicloud_cs_kubernetes_addons修改更新您的组件配置，以gatekeeper组件为例，您可以通过修改config字段来修改组件配置。

resource "alicloud_cs_kubernetes_addon" "gatekeeper" {
  cluster_id = "ce36b7c61e126430b8b245730ca6d****"
  name = "gatekeeper"
  version = "v3.8.1.113-geb7947ef-aliyun"

  # 您可以修改Config中的属性并应用，来修改集群组件配置。

}

如果您需要查看组件支持的全部可配置参数，可以通过Data Source中的alicloud_cs_kubernetes_addon_metadata进行查询，查询结果的返回值为JSON Schema格式，以gatekeeper组件为例，您可以将以下内容添加到.tf文件中。

# 定义Data Source获取gatekeeper组件的可配置参数Schema。
data "alicloud_cs_kubernetes_addon_metadata" "default" {
  cluster_id = "ce36b7c61e126430b8b245730ca6d****"
  name       = "gatekeeper"
  version    = "v3.8.1.113-geb7947ef-aliyun"
}

# 通过Output进行输出。
output "addon_config_schema" {
  value = data.alicloud_cs_kubernetes_addons.default.config_schema
}

addon_config_schema = <<EOT
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "AdmissionPodCpuLimit": {
      "default": "1000m",
      "description": "cpu limit for gatekeeper",
      "pattern": "^(|[1-9][0-9]*(m|\\.\\d+)?)$",
      "type": "string"
    },
    "AdmissionPodCpuRequest": {
      "default": "100m",
      "description": "cpu request for gatekeeper",
      "pattern": "^[1-9][0-9]*(m|\\.\\d+)?$",
      "type": "string"
    },
    "AdmissionPodMemoryLimit": {
      "default": "512Mi",
      "description": "memory limit for gatekeeper",
      "pattern": "^(|[1-9][0-9]*(\\.\\d+)?(K|Ki|M|Mi|G|Gi|T|Ti)?)$",
      "type": "string"
    },

    ......
  },
  "title": "Config",
  "type": "object"
}
EOT

配置网络组件

在ACK中，您可以通过Terway网络模式实现上述容器网络的能力。更多信息，请参见网络概述。

# 使用Terway作为网络组件，并且使用Pod独占弹性网卡模式，默认此方式。
# 该模式下，节点Pod数量将受到ECS弹性网卡配额限制。

resource "alicloud_cs_managed_kubernetes" "default" {
  # 其它参数。
  # ...

  addons {
    name = "terway-eni"
  }
}

# 使用Terway作为网络组件，并且使用IPVlan模式。
# 采用IPVlan + ebpf作为网卡共享模式虚拟化技术，只能使用Alibaba Cloud Linux 2系统。
resource "alicloud_cs_managed_kubernetes" "default" {
  # 其它参数。
  # ...

  addons {
    name   =  "terway-eniip",
    config = "{\"IPVlan\":\"true\",\"NetworkPolicy\":\"false\"}"
  }
}

# 使用Terway作为网络组件，并且IPVlan模式下启用NetworkPolicy策略支持。
# 采用IPVlan + ebpf作为网卡共享模式虚拟化技术，只能使用Alibaba Cloud Linux 2系统。
# IPVlan模式下，提供了基于策略的网络控制。
resource "alicloud_cs_managed_kubernetes" "default" {
  # 其它参数。
  # ...

  addons {
    name   =  "terway-eniip",
    config = "{\"IPVlan\":\"true\",\"NetworkPolicy\":\"true\"}"
  }
}

配置存储组件

# 使用CSI作为存储组件时，CSI包含csi-plugin、csi-provisioner；如果还想启用创建默认的NAS文件系统和CNFS容器网络文件系统动态存储类型，还需要安装storage-operator组件。
resource "alicloud_cs_managed_kubernetes" "default" {
  # 其它参数。
  # ...

  addons {
    name = "csi-plugin"
  }
  addons {
    name = "csi-provisioner"
  }
  addons {
    name   = "storage-operator"
    config = "{\"CnfsOssEnable\":\"false\",\"CnfsNasEnable\":\"true\"}"
  }
}

配置日志组件

# 使用自动创建SLS Project作为日志存储。
resource "alicloud_cs_managed_kubernetes" "default" {
  # 其它参数。
  # ...

  addons {
    name = "logtail-ds"
  }
}

# 使用自动创建SLS Project做日志存储。同时开启自动创建Ingress看板。
resource "alicloud_cs_managed_kubernetes" "default" {
  # 其它参数。
  # ...

  addons {
    name = "logtail-ds"
    config = "{\"IngressDashboardEnabled\":\"true\"}
  }
}


# 使用已有SLS Project做日志存储。同时开启自动创建Ingress看板。
resource "alicloud_cs_managed_kubernetes" "default" {
  # 其它参数。
  # ...

  addons {
    name = "logtail-ds"
    config = "{\"IngressDashboardEnabled\":\"true\",\"sls_project_name\":\"k8s-log-c55c35ff493df47b88783bea48827****\"}"
  }
}

# 安装配置node-problem-detector事件中心。
# 使用自动创建SLS Project作为事件中心的日志存储。
resource "alicloud_cs_managed_kubernetes" "default" {
  # 其它参数。
  # ...

  addons {
    name   = "ack-node-problem-detector"
    config = "{\"sls_project_name\":\"\"}"
  }
}

# 安装配置node-problem-detector事件中心。
# 使用已有SLS Project作为事件中心的日志存储。可以和logtail-ds共用同一个日志库。
resource "alicloud_cs_managed_kubernetes" "default" {
  # 其它参数。
  # ...

  addons {
    name   = "ack-node-problem-detector"
    config = "{\"sls_project_name\":\"k8s-log-c55c35ff493df47b88783bea48827****\"}"
  }
}

配置监控组件

# 安装ECS节点上安装的云监控插件。
resource "alicloud_cs_managed_kubernetes" "default" {
  # 其它参数。
  # ...
  install_cloud_monitor = true
}

# 安装Prometheus监控。
resource "alicloud_cs_managed_kubernetes" "default" {
  # 其它参数。
  # ...

  addons {
    name = "arms-prometheus"
  }
}

# 同时安装ECS节点上安装的云监控插件和Prometheus监控服务。

# 安装Prometheus监控, 推荐同时启用。
resource "alicloud_cs_managed_kubernetes" "default" {
  # 其它参数。
  # ...
  install_cloud_monitor = true
  addons {
    name = "arms-prometheus"
  }
}

配置Ingess路由组件

# 使用nginx-ingress-controller路由。
# 如果使用公网的SLB，需要在Config中设置IngressSlbNetworkType值为internet。
# 如果使用私网的SLB，需要在Config中设置IngressSlbNetworkType值为intranet。
resource "alicloud_cs_managed_kubernetes" "default" {
  # 其它参数。
  # ...

  addons {
    name   =  "nginx-ingress-controller",
    config = "{\"IngressSlbNetworkType\":\"internet\",\"IngressSlbSpec\":\"slb.s2.small\"}"
  }
}

# 使用ALB Ingress路由。
resource "alicloud_cs_managed_kubernetes" "default" {
  # 其它参数。
  # ...

  addons {
    name   = "alb-ingress-controller",
  }
}

禁用默认安装的组件

# 禁止安装nginx-ingress-controller组件。

resource "alicloud_cs_managed_kubernetes" "default" {
  # 其它参数。
  # ...

  addons {
    name     =  "nginx-ingress-controller",
    disabled = true
  }
}

未指定Addons的情况下默认安装的组件

如果集群创建时，没有指定任何Addons，会默认安装以下组件。

常用配置示例

# 集群创建不配置任何组件，则仅安装默认组件。
# 一个集群的最简配置，变量请替换为您自定义的变量。
resource "alicloud_cs_managed_kubernetes" "default" {
  name                         = var.name
  cluster_spec                 = "ack.pro.small"
  is_enterprise_security_group = true
  pod_cidr                     = "172.20.0.0/16"
  service_cidr                 = "172.21.0.0/20"
  worker_vswitch_ids           = ["var.vswitch_id"]
}

# 创建Terway网络集群。
# 使用Pod独占弹性网卡模式。

resource "alicloud_cs_managed_kubernetes" "default" {
  name                         = var.name
  cluster_spec                 = "ack.pro.small"
  is_enterprise_security_group = true
  pod_vswitch_ids              = [var.vswitch_id]
  service_cidr                 = "172.21.0.0/20"
  worker_vswitch_ids           = ["var.vswitch_id"]

  addons {
    name = "terway-eni"
  }
}

# 创建Terway网络集群。
# 同时使用IPVlan模式，并且开启网络策略。
resource "alicloud_cs_managed_kubernetes" "default" {
  name                         = var.name
  cluster_spec                 = "ack.pro.small"
  is_enterprise_security_group = true
  service_cidr                 = "172.21.0.0/20"
  pod_vswitch_ids              = ["var.vswitch_id"]
  worker_vswitch_ids           = ["var.vswitch_id"]

  addons {
    name   =  "terway-eniip"
    config = "{\"IPVlan\":\"true\",\"NetworkPolicy\":\"true\"}"
  }
}

# Terway + CSI + nginx-ingress通用模板。

resource "alicloud_cs_managed_kubernetes" "default" {
  name                         = var.name
  cluster_spec                 = "ack.pro.small"
  is_enterprise_security_group = true
  service_cidr                 = "172.21.0.0/20"
  pod_vswitch_ids              = ["var.vswitch_id"]
  worker_vswitch_ids           = ["var.vswitch_id"]

  addons {
    name = "terway-eniip",
    config = "{\"IPVlan\":\"true\",\"NetworkPolicy\":\"false\"}"
  }
  addons {
    name = "csi-plugin"
  }
  addons {
    name = "csi-provisioner"
  }
  addons {
    name = "storage-operator"
    config = "{\"CnfsOssEnable\":\"false\",\"CnfsNasEnable\":\"true\"}"
  }
  addons {
    name = "logtail-ds"
    config = "{\"IngressDashboardEnabled\":\"true\"}"
  }
  addons {
    name = "ack-node-problem-detector"
    config = "{\"sls_project_name\":\"\"}"
  }
  addons {
    name = "nginx-ingress-controller"
    config = "{\"IngressSlbNetworkType\":\"internet\",\"IngressSlbSpec\":\"slb.s2.small\"}"
  }
  addons {
    name = "ack-node-local-dns"
  }
  addons {
    name = "arms-prometheus"
  }
  addons {
    name = "alicloud-monitor-controller"
    config = "{\"group_contact_ids\":\"[10619]\"}"
  }
}