Terraform GKE模块生成的.kube/config文件IP错误无法使用排查

• 使用Terraform模块创建GKE集群并自动生成本地kubeconfig配置文件后，执行kubectl命令终端持续挂起无响应
• 集群创建完成后手动执行gcloud container clusters get-credentials拉取配置凭证后，kubectl可正常工作
• 诉求为排查配置错误，免去Terraform部署后手动执行gcloud命令的操作

问题复现配置 #

terraform {
  required_providers {
    google = {
        source = "hashicorp/google"
        version = ">= 3.42.0"
    }
    google-beta = {
        source = "hashicorp/google-beta"
        version = ">= 3.0.0"
    }
  }
}

provider "google" {
  credentials = var.gcp_creds
  project = var.project_id
  region  = var.region
  zone    = var.zone
}

provider "google-beta" {
  credentials = var.gcp_creds
  project = var.project_id
  region  = var.region
  zone    = var.zone
}

module "gke" {
  source                 = "terraform-google-modules/kubernetes-engine/google//modules/beta-private-cluster"
  project_id             = var.project_id
  name                   = "cluster"
  regional               = true
  region                 = var.region
  zones                  = ["${var.region}-a", "${var.region}-b", "${var.region}-c"]
  network                = module.vpc.network_name
  subnetwork             = module.vpc.subnets_names[0]
  ip_range_pods          = "gke-pod-ip-range"
  ip_range_services      = "gke-service-ip-range"
  horizontal_pod_autoscaling = true
  enable_private_nodes       = true
  master_ipv4_cidr_block     = "${var.control_plane_cidr}"
  node_pools = [
    {
      name                      = "node-pool"
      machine_type              = "${var.machine_type}"
      node_locations            = "${var.region}-a,${var.region}-b,${var.region}-c"
      min_count                 = "${var.node_pools_min_count}"
      max_count                 = "${var.node_pools_max_count}"
      disk_size_gb              = "${var.node_pools_disk_size_gb}"
      auto_repair               = true
      auto_upgrade              = true
    },
  ]
}


# 配置集群认证授权
module "gke_auth" {
  source = "terraform-google-modules/kubernetes-engine/google//modules/auth"
  depends_on   = [module.gke]
  project_id   = var.project_id
  location     = module.gke.location
  cluster_name = module.gke.name
}

# 生成本地kubeconfig文件，存储集群访问所需的证书、用户、端点信息
resource "local_file" "kubeconfig" {
  content  = module.gke_auth.kubeconfig_raw
  filename = "~/.kube/config"
}

问题补充排查结论 #

Terraform自动生成的~/.kube/config文件中记录的API Server公网IP错误，手动通过gcloud命令生成的配置文件中API Server IP为正确值。

核心问题出在私有集群的端点配置与auth模块的默认行为不匹配本地访问场景：

• 你使用的是beta-private-cluster私有集群模块，仅配置了enable_private_nodes = true和控制平面私有CIDR，未显式配置enable_private_endpoint参数，该参数默认值为true，即集群控制平面仅暴露内网访问端点，公网端点默认未正式启用，返回的公网IP为无效占位值。
• GKE auth模块默认优先拉取集群的私有端点IP写入kubeconfig，未显式指定端点类型时，不会主动校验本地网络与端点的连通性。本地执行kubectl的环境不在集群VPC内网，无法访问私有IP，就会出现请求挂起无响应的问题。
• 手动执行gcloud命令拉取凭证时，gcloud CLI会自动探测集群当前可达的端点，自动选择正确的可达IP写入配置，因此手动生成的配置可以正常使用。

根据你的访问场景调整配置即可，无需手动执行gcloud命令：

1. 如果本地环境通过公网访问集群，调整GKE集群模块配置，开启公网控制平面端点并配置访问授权：
   在module "gke"块中补充以下参数：

# 同时启用公网、内网控制平面端点
enable_private_endpoint = false
# 配置控制平面授权网段，仅允许信任的公网IP访问控制平面
master_authorized_networks_config = {
  cidr_blocks = [
    {
      cidr_block   = "本地公网出口IP/32"
      display_name = "local-workstation"
    }
  ]
}

同时在module "gke_auth"块中补充参数，显式指定使用公网端点生成kubeconfig：

use_private_endpoint = false

2. 如果本地环境已经通过VPN/专线与GCP VPC打通，直接在module "gke_auth"块中设置use_private_endpoint = true，确认本地到集群控制平面私有网段的路由、防火墙策略放通即可。

调整完成后重新执行terraform apply，生成的kubeconfig会写入正确的API Server地址，kubectl可直接正常连通集群。

注意：不建议在未配置master_authorized_networks_config的情况下开启公网控制平面端点，避免控制平面暴露在公网带来安全风险。

内容的提问来源于stack exchange，提问作者Nitin G