使用 Config Controller 和 KRM 蓝图管理 GKE 集群

本教程介绍如何使用 Config Controller 编写 KRM 蓝图以预配 Google Kubernetes Engine (GKE) 集群和所需的网络基础架构,例如 Virtual Private Cloud (VPC)、用于托管 GKE 集群的子网以及 pod 和服务的命名 IP 地址范围。如果您是 GKE 集群运维人员,并且希望以声明方式管理集群配置和网络基础架构,请遵循本教程中的做法。

配置控制器是一个托管式服务,用于预配和编排 Anthos 和 Google Cloud 资源。它提供一个 API 端点,可以作为 Anthos Config Management 的组件预配、启用和编排 Google Cloud 资源。

KRM 蓝图是一种将常用的资源打包在一起的方法,同时将可在整个组织中推广的最佳做法编写为代码。

GKE 集群蓝图是一种 KRM 蓝图,其中包含在现有 Google Cloud VPC、子网和 IP 范围之上管理 GKE 集群所需的所有资源。您可以多次实例化蓝图以设置多个集群。

网络蓝图是一组 KRM 蓝图,可帮助您创建创建 GKE 集群所需的必要网络组件,例如 VPC、子网和别名 IP 范围。您可以多次实例化这些蓝图,以设置多个集群所需的多个子网和别名 IP 地址范围。

目标

  • 以声明方式创建托管 GKE 集群所需的网络基础架构。
  • 在此网络基础架构中以声明方式配置 GKE 集群。
  • 使用配置控制器应用配置。

费用

本教程使用 Google Cloud 的以下收费组件:

如需查看 GKE 集群蓝图中包含的资源的完整列表,请参阅 GKE 软件包的“Resources”部分及其子软件包。

如需根据您的预计使用量来估算费用,请使用价格计算器

完成本教程后,您可以删除所创建的资源以避免继续计费。如需了解详情,请参阅清理

要求

准备工作

  1. 在 Cloud Console 中,激活 Cloud Shell。

    激活 Cloud Shell

    Cloud Shell 会话随即会在 Cloud Console 的底部启动,并显示命令行提示符。Cloud Shell 是一个已安装 Google Cloud CLI 且已为当前项目设置值的 Shell 环境。该会话可能需要几秒钟时间来完成初始化。

  2. 您可以从 Cloud Shell 运行本教程中的所有命令。

设置环境

在 Cloud Shell 中,运行以下命令:

  1. 安装 Kubernetes 的主要命令行界面 kubectl

    gcloud components install kubectl
    
  2. 安装 KRM 蓝图的主要命令行界面 kpt

    gcloud components install kpt
    
  3. 配置 kubectlkpt 以连接到配置控制器:

    gcloud anthos config controller get-credentials CONFIG_CONTROLLER_NAME \
        --location COMPUTE_REGION \
        --project CONFIG_CONTROLLER_PROJECT_ID
    

    替换以下内容:

    • CONFIG_CONTROLLER_NAME:配置控制器集群的名称。

    • COMPUTE_REGION:配置控制器集群的区域(例如 us-central1)。

    • CONFIG_CONTROLLER_PROJECT_ID:配置控制器集群的项目 ID。

  4. 启用 Resource Manager API:

    gcloud services enable cloudresourcemanager.googleapis.com \
        --project PROJECT_ID
    

    PROJECT_ID 替换为您的项目 ID。

  5. 验证项目命名空间中是否已配置配置连接器且运行状况良好:

    kubectl get ConfigConnectorContext -n PROJECT_NAMESPACE \
        -o "custom-columns=NAMESPACE:.metadata.namespace,NAME:.metadata.name,HEALTHY:.status.healthy"
    

    PROJECT_NAMESPACE 替换为您要用于管理项目资源的命名空间(例如 config-control)。

    输出示例:

    NAMESPACE        NAME                                                HEALTHY
    config-control   configconnectorcontext.core.cnrm.cloud.google.com   true
    

为集群配置 VPC、子网和别名 IP 范围

配置 VPC

如需使用网络蓝图设置和配置 VPC,请运行以下命令。

  1. 使用 kpt 从所需的工作目录中提取网络蓝图:

    kpt pkg get \
      https://github.com/GoogleCloudPlatform/blueprints.git/catalog/networking/network/vpc@networking-blueprint-v0.4.0 \
      VPC_NAME
    

    VPC_NAME 替换为要用于 VPC 的名称(例如 my-vpc)。

  2. 转到新创建的目录:

    cd VPC_NAME
    
  3. 通过修改 setters.yaml 文件来配置软件包:

    更新该文件中的以下字段。请务必提供您自己的项目 ID:

      namespace: PROJECT_NAMESPACE
      network-name: VPC_NAME
      project-id: PROJECT_ID
    

    替换以下内容:

    • PROJECT_ID:您的项目的 ID。

      在本教程中,集群和网络部署到同一项目。

    • PROJECT_NAMESPACE:用于管理项目资源的命名空间(例如 config-control)。

      在本教程中,集群、网络和服务的启用在同一命名空间中进行管理。

  4. 在文件末尾添加一个名为“prefix”的新字段。确保缩进正确:

      prefix: NAT-PREFIX
    

    NAT-PREFIX 替换为前缀(例如 nat)。

    这将在设置 VPC 时用作 NAT 名称的前缀。

    您的文件将如下所示:

    apiVersion: v1
    kind: ConfigMap
    metadata: # kpt-merge: /setters
      name: setters
    data:
      namespace: PROJECT_NAMESPACE
      network-name: VPC_NAME
      project-id: PROJECT_ID
      prefix: NAT-PREFIX
    
  5. 使用 kpt set-namespace 函数更改蓝图中的命名空间,如下所示:

      kpt fn eval --image set-namespace:v0.1 -- namespace=PROJECT_NAMESPACE
    

    PROJECT_NAMESPACE 替换为用于管理项目资源的命名空间(例如 config-control)。

配置子网

  1. 使用 VPC_NAMEkpt 目录中提取子网蓝图:

    kpt pkg get \
      https://github.com/GoogleCloudPlatform/blueprints.git/catalog/networking/network/subnet@networking-blueprint-v0.4.0 \
      SUBNET_NAME
    

    SUBNET_NAME 替换为用于管理项目资源的命名空间(例如 gke-subnet)。

  2. 转到子网目录:

    cd SUBNET_NAME
    
  3. 修改 subnet.yaml 文件并将以下代码段添加到文件末尾的 spec 部分下。这会定义两个命名的范围,这些范围将用于为 GKE 集群 pod 和服务分配 IP 地址:

      secondaryIpRange:
      - ipCidrRange: 172.17.0.0/16
        rangeName: pods
      - ipCidrRange: 172.18.0.0/16
        rangeName: services
    

    您的 subnet.yaml 文件将如下所示:

    apiVersion: compute.cnrm.cloud.google.com/v1beta1
    kind: ComputeSubnetwork
    metadata: # kpt-merge: networking/network-name-subnetwork
      name: network-name-subnetwork # kpt-set: ${prefix}${network-name}-subnetwork
      namespace: networking # kpt-set: ${namespace}
      annotations:
        cnrm.cloud.google.com/project-id: project-id # kpt-set: ${project-id}
        cnrm.cloud.google.com/blueprint: cnrm/landing-zone:networking/v0.4.0
    spec:
      description: Subnetwork
      ipCidrRange: 10.2.0.0/16 # kpt-set: ${ip-cidr-range}
      logConfig:
        metadata: INCLUDE_ALL_METADATA
        aggregationInterval: INTERVAL_10_MIN
        flowSampling: 0.5
      networkRef:
        name: network-name # kpt-set: ${network-name}
      privateIpGoogleAccess: false
      region: us-central1 # kpt-set: ${region}
      secondaryIpRange:
      - ipCidrRange: 172.17.0.0/16
        rangeName: pods
      - ipCidrRange: 172.18.0.0/16
        rangeName: services
    

呈现蓝图

必须先呈现蓝图,然后才能应用该蓝图。此步骤会针对蓝图中的资源执行函数流水线,如 Kptfile 中所定义。一个典型的可能执行的函数示例就是 apply-setters,它会应用您之前修改的 setter。

  1. 现在转回 VPC_NAME 目录,然后使用 kpt 将 setter 值呈现为模板化资源:

    cd ..
    kpt fn render
    

    输出应类似如下所示:

    [RUNNING] "gcr.io/kpt-fn/apply-setters:v0.1"
    [PASS] "gcr.io/kpt-fn/apply-setters:v0.1" in 5.4s
      Results:
        [INFO] set field value to "ALL_SUBNETWORKS_ALL_IP_RANGES" in file "nat.yaml" in field "spec.sourceSubnetworkIpRangesToNat"
        [INFO] set field value to "10.2.0.0/16" in file "subnet.yaml" in field "spec.ipCidrRange"
    
    Package "my-vpc":
    [RUNNING] "gcr.io/kpt-fn/apply-setters:v0.1"
    [PASS] "gcr.io/kpt-fn/apply-setters:v0.1" in 2.3s
      Results:
        [INFO] set field value to "00-my-vpc-router-nat" in file "nat.yaml" in field "metadata.name"
        [INFO] set field value to "config-control" in file "nat.yaml" in field "metadata.namespace"
        [INFO] set field value to "krm-playground-00" in file "nat.yaml" in field "metadata.annotations.cnrm.cloud.google.com/project-id"
        [INFO] set field value to "00-my-vpc-router" in file "nat.yaml" in field "spec.routerRef.name"
        ...(13 line(s) truncated, use '--truncate-output=false' to disable)
    
    Successfully executed 2 function(s) in 2 package(s).
    

应用配置更改

上述步骤中的本地更改在应用之前不会影响云。

如需应用配置更改,请运行以下命令。

  1. 使用 kpt 初始化工作目录,此操作会创建一个资源来跟踪更改:

    kpt live init --namespace PROJECT_NAMESPACE
    

    PROJECT_NAMESPACE 替换为用于管理项目资源的命名空间(例如 config-control)。

    initializing Kptfile inventory info (namespace: config-control)...success
    
  2. 预览将创建的资源:

    kpt live apply --dry-run
    

    所有资源都应显示“created (dry-run)”。

    输出示例:

    computerouter.compute.cnrm.cloud.google.com/my-vpc-router created (dry-run)
    computerouternat.compute.cnrm.cloud.google.com/my-vpc-router-nat created (dry-run)
    computesubnetwork.compute.cnrm.cloud.google.com/my-vpc-subnetwork created (dry-run)
    service.serviceusage.cnrm.cloud.google.com/proj-id-00-compute created (dry-run)
    computenetwork.compute.cnrm.cloud.google.com/my-vpc created (dry-run)
    5 resource(s) applied. 5 created, 0 unchanged, 0 configured, 0 failed (dry-run)
    
  3. 使用 kpt 应用资源:

    kpt live apply
    

    所有资源都应显示“reconciled”。

    输出示例:

    computenetwork.compute.cnrm.cloud.google.com/my-vpc created
    computerouter.compute.cnrm.cloud.google.com/my-vpc-router created
    computerouternat.compute.cnrm.cloud.google.com/my-vpc-router-nat created
    computesubnetwork.compute.cnrm.cloud.google.com/my-vpc-subnetwork created
    service.serviceusage.cnrm.cloud.google.com/proj-id-00-compute created
    5 resource(s) applied. 5 created, 0 unchanged, 0 configured, 0 failed
    

验证已成功创建网络资源

如需验证更改是否已应用并且其指定的资源是否已预配,请运行以下命令。

  1. 等待资源准备就绪:

    kpt live status --output table --poll-until current
    

    该命令将进行轮询,直到所有资源的状态为 Current,条件为 Ready

    如果需要,请使用 ctrl-c 来中断操作。

    输出示例:

    NAMESPACE   RESOURCE                                STATUS      CONDITIONS      AGE     MESSAGE
    config-con  ComputeNetwork/my-vpc                   Current     Ready           2m      Resource is Ready
    config-con  ComputeRouter/my-vpc-router             Current     Ready           2m      Resource is Ready
    config-con  ComputeRouterNAT/my-vpc-router-nat      Current     Ready           2m      Resource is Ready
    config-con  ComputeSubnetwork/my-vpc-subnetwork     Current     Ready           2m      Resource is Ready
    config-con  Service/proj-id-00-compute              Current     Ready           2m      Resource is Ready
    
  2. 如果出现错误,使用默认事件输出来查看完整的错误消息:

    kpt live status
    

    所有资源创建完成并准备就绪需要几分钟时间。

    成功创建网络资源后,向上移动一个目录,开始配置 GKE 集群。

    cd ..
    

配置 GKE 集群

如需使用 GKE 集群蓝图配置 GKE 集群,请运行以下命令。

  1. 使用 kpt 从所需工作目录中提取 GKE 集群蓝图:

    kpt pkg get \
        https://github.com/GoogleCloudPlatform/blueprints.git/catalog/gke@gke-blueprint-v0.4.0 \
        CLUSTER_NAME
    

    CLUSTER_NAME 替换为要用于 GKE 集群的所需名称(例如 hello-cluster)。

  2. 移至集群目录:

    cd ./CLUSTER_NAME/
    
  3. 通过修改 setters.yaml 文件来配置软件包:

    cat > setters.yaml << EOF
    apiVersion: v1
    kind: ConfigMap
    metadata: # kpt-merge: /setters
      name: setters
    data:
      # The name of this cluster
      cluster-name: CLUSTER_NAME
      # The compute location (region for a regional cluster or zone for a zonal cluster)
      location: us-central1
      # The private IP range for masters to use when peering to the VPC
      master-ip-range: 10.254.0.0/28
      # The reference to the network
      network-ref: projects/PROJECT_ID/global/networks/VPC_NAME
      # The reference to the subnet
      subnet-ref: projects/PROJECT_ID/regions/us-central1/subnetworks/subnetwork
      # The namespace in which to manage cluster resources
      platform-namespace: PROJECT_NAMESPACE
      # The project in which to manage cluster resources
      project-id: PROJECT_ID
      # The namespace in which to manage service enablement resources
      projects-namespace: PROJECT_NAMESPACE
      # The private IP range name for Pods to use, this range must already exist
      pods-range-name: pods
      # The private IP range name for services to use, this range must already exist
      services-range-name: services
      # The group in which to manage the list of groups that can be used for RBAC.
      # Must be named exactly 'gke-security-groups'.
      security-group: gke-security-groups@YOUR_DOMAIN
    EOF
    

    替换以下内容:

    • PROJECT_ID:您的项目的 ID。

      在本教程中,集群和网络部署到同一项目。

    • PROJECT_NAMESPACE:用于管理项目资源的命名空间(例如 config-control)。

      在本教程中,集群、网络和服务的启用在同一命名空间中进行管理。

    • YOUR_DOMAIN:您的群组使用的网域(例如 example.com)。

    • network-ref:应在其中创建集群的网络的 selfLink 引用。

      格式为:projects/{network-project-id}/global/networks/{vpc-name}

    • subnet-ref:应在其中创建集群的子网的 selfLink 引用。

      格式为:projects/{network-project-id}/regions/{region}/subnetworks/{subnet-name}

    其他所有数据字段可根据需要进行重新配置。

    提供的默认值应该在其他具有默认网络的空项目中有效。

停用 Google RBAC 群组

如果您不希望将 RBAC 配置为使用 Google 群组进行授权,则除了个人之外,您还可以更改集群配置以停用“Google RBAC 群组”功能。例如,如果您没有创建 gke-security-groups 并且缺少创建它的权限,则可能需要执行此操作。如需了解详情,请参阅群组设置

  1. 如需停用 Google RBAC 群组,只需直接修改 cluster/cluster.yaml 文件即可。

  2. 找到包含 authenticatorGroupsConfig 字段的部分并移除以下三行:

      # Enable Groups for GKE, to allow role binding to Google Groups.
      authenticatorGroupsConfig:
        securityGroup: gke-security-group@example.com # kpt-set: ${security-group}
    
  3. 保存文件。

    这会停用“Google RBAC 群组”功能。

呈现蓝图

此步骤会针对蓝图中的资源执行函数流水线,如 Kptfile 中所定义。通常情况下,这会执行 apply-setters,它会应用您之前修改的 setter。

  1. 将 setter 值呈现为模板化资源:

    kpt fn render
    

    输出示例:

    Package "example/cluster":
    [RUNNING] "gcr.io/kpt-fn/apply-setters:v0.1"
    [PASS] "gcr.io/kpt-fn/apply-setters:v0.1" in 3.3s
      Results:
        [INFO] set field value to "example-us-west4" in file "cluster.yaml" in field "metadata.name"
        [INFO] set field value to "config-control" in file "cluster.yaml" in field "metadata.namespace"
        [INFO] set field value to "project-id" in file "cluster.yaml" in field "metadata.annotations.cnrm.cloud.google.com/project-id"
        ...(9 line(s) truncated, use '--truncate-output=false' to disable)
    
    Package "test-00/nodepools/primary":
    [RUNNING] "gcr.io/kpt-fn/apply-setters:v0.1"
    [PASS] "gcr.io/kpt-fn/apply-setters:v0.1" in 2.2s
      Results:
        [INFO] set field value to "gke-example-us-east4-primary" in file "node-iam.yaml" in field "metadata.name"
        [INFO] set field value to "config-control" in file "node-iam.yaml" in field "metadata.namespace"
        [INFO] set field value to "project-id" in file "node-iam.yaml" in field "metadata.annotations.cnrm.cloud.google.com/project-id"
        [INFO] set field value to "gke-example-us-east4-primary" in file "node-iam.yaml" in field "spec.displayName"
        ...(23 line(s) truncated, use '--truncate-output=false' to disable)
    
    Package "test-00":
    [RUNNING] "gcr.io/kpt-fn/apply-setters:v0.1"
    [PASS] "gcr.io/kpt-fn/apply-setters:v0.1" in 2.3s
      Results:
        [INFO] set field value to "test-00" in file "cluster.yaml" in field "metadata.name"
        [INFO] set field value to "config-control" in file "cluster.yaml" in field "metadata.namespace"
        [INFO] set field value to "krm-playground-00" in file "cluster.yaml" in field "metadata.annotations.cnrm.cloud.google.com/project-id"
        ...(36 line(s) truncated, use '--truncate-output=false' to disable)
    
    Successfully executed 3 function(s) in 3 package(s).
    

应用配置更改

上述步骤中的本地更改在应用之前不会影响云。

如需应用配置更改,请运行以下命令。

  1. 使用 kpt 初始化工作目录,此操作会创建一个资源来跟踪更改:

    kpt live init --namespace PROJECT_NAMESPACE
    

    PROJECT_NAMESPACE 替换为用于管理项目资源的命名空间(例如 config-control)。

  2. 预览将创建的资源:

    kpt live apply --dry-run
    

    所有资源都应显示“created (dry-run)”。

    输出示例:

    service.serviceusage.cnrm.cloud.google.com/proj-id-00-test-00-container created (dry-run)
    containercluster.container.cnrm.cloud.google.com/test-00 created (dry-run)
    containernodepool.container.cnrm.cloud.google.com/test-00-primary created (dry-run)
    iampolicymember.iam.cnrm.cloud.google.com/artifactreader-gke-test-00-primary created (dry-run)
    iampolicymember.iam.cnrm.cloud.google.com/logwriter-gke-test-00-primary created (dry-run)
    iampolicymember.iam.cnrm.cloud.google.com/metricwriter-gke-test-00-primary created (dry-run)
    iamserviceaccount.iam.cnrm.cloud.google.com/gke-test-00-primary created (dry-run)
    7 resource(s) applied. 7 created, 0 unchanged, 0 configured, 0 failed (dry-run)
    
  3. 使用 kpt 应用资源:

    kpt live apply
    

    所有资源都应显示“已创建”。

    输出示例:

    iamserviceaccount.iam.cnrm.cloud.google.com/gke-test-00-primary created
    service.serviceusage.cnrm.cloud.google.com/proj-id-00-test-00-container created
    containercluster.container.cnrm.cloud.google.com/test-00 created
    containernodepool.container.cnrm.cloud.google.com/test-00-primary created
    iampolicymember.iam.cnrm.cloud.google.com/artifactreader-gke-test-00-primary created
    iampolicymember.iam.cnrm.cloud.google.com/logwriter-gke-test-00-primary created
    iampolicymember.iam.cnrm.cloud.google.com/metricwriter-gke-test-00-primary created
    7 resource(s) applied. 7 created, 0 unchanged, 0 configured, 0 failed
    

验证已成功创建 GKE 集群资源

如需验证更改是否已应用并且其指定的资源是否已预配,请运行以下命令。

  1. 等待资源准备就绪:

    kpt live status --output table --poll-until current
    

    该命令将进行轮询,直到所有资源的状态为 Current,条件为 Ready

    如果需要,请使用 ctrl-c 来中断操作。

    输出示例:

    NAMESPACE   RESOURCE                                  STATUS      CONDITIONS      AGE     MESSAGE
    config-con  ContainerCluster/test-00                  Current     Ready           12m     Resource is Ready
    config-con  ContainerNodePool/test-00-primary         Current     Ready           12m     Resource is Ready
    config-con  IAMPolicyMember/artifactreader-gke-test-  Current     Ready           12m     Resource is Ready
    config-con  IAMPolicyMember/logwriter-gke-test-00-pr  Current     Ready           12m     Resource is Ready
    config-con  IAMPolicyMember/metricwriter-gke-test-00  Current     Ready           12m     Resource is Ready
    config-con  IAMServiceAccount/gke-test-00-primary     Current     Ready           12m     Resource is Ready
    config-con  Service/proj-id-00-test-00-contai         Current     Ready           12m     Resource is Ready
    
  2. 如果出现错误,使用默认事件输出来查看完整的错误消息:

    kpt live status
    

常见问题解答

清理

如果您决定停止使用配置控制器,则应先清理使用配置控制器创建的所有资源,然后删除配置控制器本身。

  1. 首先使用 kpt 从 GKE 集群蓝图工作目录中删除集群资源:

    kpt live destroy
    
  2. 等待所有资源删除完毕:

    until [ -z "$(kubectl get -R -f . --ignore-not-found | tee /dev/fd/2)" ]; \
    do sleep 1; done
    

    该命令将进行轮询,直到所有资源的状态为 Deleted

    如果需要,请使用 ctrl-c 来中断操作。

  3. 如果您在本教程中创建了网络资源,请删除它们。 从您为蓝图创建的 VPC 目录使用 kpt

    kpt live destroy
    
  4. 等待所有资源删除完毕:

    until [ -z "$(kubectl get -R -f . --ignore-not-found | tee /dev/fd/2)" ]; \
    do sleep 1; done
    

    该命令将进行轮询,直到所有资源的状态为 Deleted

    如果需要,请使用 ctrl-c 来中断操作。

后续步骤