📚 课程目录第4章环境搭建与工具链

4. 环境搭建与工具链：安装 Service Catalog Helm Chart、配置 kubectl 插件、验证集群状态

本章将指导你完成 Service Catalog 运行环境的完整搭建。你将依次完成 Helm Chart 安装、kubectl 插件配置以及集群状态验证。这是后续所有模板设计与服务消费实验的基础，请确保每一步都执行成功。

4.1 前置条件检查清单

在开始安装之前，请确认你的 Kubernetes 集群满足以下最低要求。任何一项不满足都可能导致安装失败或运行时异常。

检查项	最低版本 / 要求	验证命令
Kubernetes 集群	v1.16+（推荐 v1.24+）	`kubectl version --short`
Helm 客户端	v3.8+	`helm version`
集群管理员权限	cluster-admin 绑定	`kubectl auth can-i '' '' --all-namespaces`
etcd 集群健康	所有节点健康	`kubectl get componentstatuses`
CoreDNS 运行	Pod 状态 Running	`kubectl get pods -n kube-system -l k8s-app=kube-dns`

提示：如果你使用的是 Minikube 或 Kind 等本地集群，请确保分配了足够的资源（建议 4 vCPU、8 GB 内存）。Service Catalog 的 API 服务器和控制器会占用额外的计算资源。

4.2 安装 Service Catalog Helm Chart

Service Catalog 官方推荐使用 Helm Chart 进行部署。我们将使用 svc-cat/catalog Chart，它包含了 API 服务器、控制器管理器以及必要的 CRD 资源。

4.2.1 添加 Helm 仓库

# 添加 Service Catalog 官方 Helm 仓库
helm repo add svc-cat https://svc-catalog-charts.storage.googleapis.com

# 更新本地仓库索引
helm repo update

# 确认仓库已添加
helm search repo svc-cat/catalog

4.2.2 创建命名空间并安装 Chart

建议将 Service Catalog 组件部署在独立的命名空间 catalog-system 中，便于管理和清理。

# 创建目标命名空间
kubectl create namespace catalog-system

# 使用 Helm 安装 Service Catalog
helm install catalog svc-cat/catalog \
  --namespace catalog-system \
  --set apiserver.storage.etcd.persistence.enabled=true \
  --set apiserver.storage.etcd.persistence.size=8Gi \
  --set controllerManager.healthcheck.nodePort=30444 \
  --wait

  关键参数说明：
  apiserver.storage.etcd.persistence.enabled：启用 etcd 持久化存储，防止重启后数据丢失。
apiserver.storage.etcd.persistence.size：为 etcd 分配的持久卷大小，根据集群规模调整。
controllerManager.healthcheck.nodePort：控制器健康检查的 NodePort，用于外部监控。
--wait：等待所有 Pod 进入 Ready 状态后再返回。

4.2.3 验证 Chart 安装状态

# 查看 Helm Release 状态
helm status catalog -n catalog-system

# 查看所有相关 Pod 是否正常运行
kubectl get pods -n catalog-system -l app=catalog-catalog

# 预期输出示例（3 个 Pod 均为 Running）：
# NAME                                                   READY   STATUS    RESTARTS   AGE
# catalog-catalog-apiserver-7d8f6c9b6f-abc12             1/1     Running   0          2m
# catalog-catalog-controller-manager-5f4d7e8c9d-xyz34    1/1     Running   0          2m
# catalog-catalog-etcd-0                                  1/1     Running   0          2m

4.3 配置 kubectl 插件：svcat

svcat 是 Service Catalog 官方提供的 kubectl 插件，用于简化对 Service Catalog 资源的操作。它提供了比原生 kubectl 更直观的交互方式。

4.3.1 安装 svcat 二进制

根据你的操作系统选择对应的安装方式：

操作系统	安装命令
Linux (amd64)	`curl -sL https://download.svcat.sh/cli/latest/linux/amd64/svcat -o /usr/local/bin/svcat && chmod +x /usr/local/bin/svcat`
macOS (amd64)	`curl -sL https://download.svcat.sh/cli/latest/darwin/amd64/svcat -o /usr/local/bin/svcat && chmod +x /usr/local/bin/svcat`
Windows	从官方下载页面获取 exe 文件，并加入 PATH

4.3.2 验证插件集成

# 确认 svcat 可以作为 kubectl 插件使用
kubectl plugin list

# 预期输出应包含：
# /usr/local/bin/svcat

# 测试 svcat 基本命令
svcat version

# 预期输出示例：
# Client Version: v0.4.0
# Server Version: v0.4.0

注意：如果 kubectl plugin list 没有显示 svcat，请检查 svcat 二进制文件是否在 PATH 中，并且文件名是否以 kubectl- 开头。你可以通过创建符号链接来解决：ln -s /usr/local/bin/svcat /usr/local/bin/kubectl-svcat。

4.4 验证集群状态

安装完成后，需要从多个维度验证 Service Catalog 是否正常工作。以下验证流程将帮助你确认 API 可用性、资源注册能力以及端到端通信。

4.4.1 验证 API 资源列表

# 查看 Service Catalog 注册的 API 资源
kubectl api-resources --api-group=servicecatalog.k8s.io

# 预期输出应包含以下核心资源：
# NAME                SHORTNAMES   APIGROUP                       NAMESPACED   KIND
# clusterservicebrokers   csb      servicecatalog.k8s.io          false        ClusterServiceBroker
# clusterserviceclasses   csc      servicecatalog.k8s.io          false        ClusterServiceClass
# clusterserviceplans     csp      servicecatalog.k8s.io          false        ClusterServicePlan
# serviceinstances        si       servicecatalog.k8s.io          true         ServiceInstance
# servicebindings         sb       servicecatalog.k8s.io          true         ServiceBinding

4.4.2 验证控制器健康状态

# 查看控制器日志，确认没有错误
kubectl logs -n catalog-system -l app=catalog-catalog,component=controller-manager --tail=50

# 查看 API 服务器健康端点
kubectl get --raw /apis/servicecatalog.k8s.io/v1beta1 | jq .

# 预期输出应包含 "resources" 数组，列出所有可用资源版本

4.4.3 端到端连通性测试

创建一个临时的 ClusterServiceBroker 资源，验证 Service Catalog 能否正常与 Broker 通信。这里使用一个模拟 Broker 进行测试。

# 创建一个测试用的 ClusterServiceBroker
cat <<EOF | kubectl apply -f -
apiVersion: servicecatalog.k8s.io/v1beta1
kind: ClusterServiceBroker
metadata:
  name: test-broker
spec:
  url: https://mock-broker.example.com
EOF

# 查看 Broker 状态
kubectl get clusterservicebroker test-broker -o wide

# 清理测试资源
kubectl delete clusterservicebroker test-broker

提示：如果 Broker 状态显示为 Ready，说明 Service Catalog 的 API 服务器和控制器能够正常处理 Broker 注册请求。即使 Broker URL 不可达，只要 API 层正常工作，状态也会正确反映为 NotReady 并显示错误信息。

4.5 环境架构总览

下图展示了安装完成后，Service Catalog 各组件在 Kubernetes 集群中的部署关系与通信路径。

4.6 常见问题与排查

在环境搭建过程中，可能会遇到以下典型问题。提前了解解决方案可以节省大量调试时间。

问题现象	可能原因	解决措施
Pod 一直处于 `Pending` 状态	集群资源不足，或 PVC 无法绑定	检查节点资源 `kubectl describe nodes`；确认 StorageClass 是否存在
API 资源列表为空	CRD 未正确安装，或 API 服务器未启动	检查 `kubectl get crd \| grep servicecatalog`；查看 apiserver 日志
`svcat version` 报连接拒绝	API 服务器 Service 未暴露或端口错误	确认 `kubectl get svc -n catalog-system`；检查 kubeconfig 上下文
Broker 状态一直 `NotReady`	网络不通或 Broker URL 不可达	从集群内部 `curl` 测试 Broker 地址；检查网络策略

最佳实践：完成安装后，建议将以下命令保存为脚本，用于快速验证环境健康状态：

#!/bin/bash
echo "=== 1. 检查 Pod 状态 ==="
kubectl get pods -n catalog-system -l app=catalog-catalog
echo ""
echo "=== 2. 检查 API 资源 ==="
kubectl api-resources --api-group=servicecatalog.k8s.io | head -10
echo ""
echo "=== 3. 检查 svcat 版本 ==="
svcat version
echo ""
echo "=== 4. 检查 etcd 健康 ==="
kubectl exec -n catalog-system catalog-catalog-etcd-0 -- etcdctl endpoint health