📚 课程目录第2章 Kubernetes Service Catalog API

2. Kubernetes Service Catalog API：API资源对象概述

Kubernetes Service Catalog（服务目录）通过一组自定义 API 资源对象，将外部托管服务（如数据库、消息队列、监控系统）以标准化方式接入集群。理解这四种核心资源对象——ClusterServiceBroker、ClusterServiceClass、ServiceInstance、ServiceBinding——是掌握服务目录模板设计的基石。

核心概念速览：Service Catalog 遵循“注册 → 发现 → 申请 → 绑定”四步流程。Broker 注册服务目录，Class 描述服务规格，Instance 代表一次服务申请，Binding 将服务凭据注入工作负载。

2.1 四种资源对象的关系与生命周期

下图展示了四种资源对象在集群中的协作关系与数据流向：

2.2 资源对象详解

2.2.1 ClusterServiceBroker

ClusterServiceBroker 是服务目录的入口点，代表一个外部服务代理（如 Open Service Broker API 兼容的 Broker）。它负责向集群注册可用的服务列表，并管理服务的生命周期。

字段	类型	说明
spec.url	string	Broker 的 API 端点地址，必须支持 Open Service Broker API
spec.authInfo	object	与 Broker 通信的认证信息（basic / bearer / tls）
spec.relistBehavior	string	服务列表刷新策略：Duration / Manual
spec.relistDuration	duration	自动刷新间隔（如 5m、1h）
status.conditions	array	Broker 连接状态：Ready / Failed / NotReady

  关键行为：当 ClusterServiceBroker 创建后，Service Catalog Controller 会立即调用 Broker 的 /v2/catalog 端点，获取服务列表并自动生成对应的 ClusterServiceClass 和 ClusterServicePlan 资源。

2.2.2 ClusterServiceClass

ClusterServiceClass 是 Broker 注册的“服务类型”的集群级表示。它由 Controller 自动生成，用户只能读取，不能直接创建或修改。每个 Class 对应 Broker 返回的一个服务条目。

spec.externalName：Broker 定义的服务名称（如 "azure-postgresql-db"）
spec.externalID：Broker 返回的唯一标识符（UUID）
spec.description：服务描述文本
spec.bindable：布尔值，标识该服务是否支持绑定操作
spec.planUpdatable：布尔值，标识是否支持在线变更服务计划
spec.clusterServiceBrokerName：所属 Broker 的名称

注意：ClusterServiceClass 是集群作用域资源，所有命名空间均可发现。但实际使用时，需要配合 RBAC 控制哪些命名空间可以申请该服务。

2.2.3 ServiceInstance

ServiceInstance 是用户对某个 ClusterServiceClass 的“一次申请”或“一个服务实例”。它运行在特定命名空间下，代表一个真实的后端服务实例（如一个 PostgreSQL 数据库实例）。

apiVersion: servicecatalog.k8s.io/v1beta1
kind: ServiceInstance
metadata:
  name: my-postgres-instance
  namespace: production
spec:
  clusterServiceClassExternalName: azure-postgresql-db
  clusterServicePlanExternalName: standard
  parameters:
    location: eastus
    storageGB: 100
    sslEnforcement: enabled

字段	说明
spec.clusterServiceClassExternalName	引用的 ClusterServiceClass 名称（或 externalID）
spec.clusterServicePlanExternalName	选择的服务计划（如 standard、premium）
spec.parameters	传递给 Broker 的配置参数（JSON 对象）
spec.parametersFrom	从 Secret / ConfigMap 引用参数
status.provisionStatus	实例状态：Provisioning / Provisioned / Failed

2.2.4 ServiceBinding

ServiceBinding 将 ServiceInstance 的访问凭据（如用户名、密码、连接地址）以 Secret 形式注入到工作负载所在的命名空间。它是服务目录与 Pod 之间的“连接器”。

apiVersion: servicecatalog.k8s.io/v1beta1
kind: ServiceBinding
metadata:
  name: my-postgres-binding
  namespace: production
spec:
  instanceRef:
    name: my-postgres-instance
  secretName: my-postgres-credentials

spec.instanceRef.name：绑定到哪个 ServiceInstance
spec.secretName：生成的 Secret 名称，包含连接凭据
status.currentOperation：当前操作状态（bind / unbind）
status.inboundSecretRef：指向生成的 Secret 对象

最佳实践：ServiceBinding 生成的 Secret 通常包含 host、port、username、password、database 等字段。Pod 可以通过 envFrom 或 volumeMount 直接引用该 Secret，实现零配置接入。

2.3 四种资源对象对比总结

资源对象	作用域	创建者	是否可修改	核心职责
ClusterServiceBroker	集群	管理员	是	注册外部服务代理，拉取服务目录
ClusterServiceClass	集群	Controller（自动）	否（只读）	描述可用的服务类型与计划
ServiceInstance	命名空间	用户/应用	部分字段可更新	申请并管理一个服务实例
ServiceBinding	命名空间	用户/应用	否（重建）	生成凭据 Secret，连接实例与工作负载

2.4 资源对象交互流程

下图展示了从 Broker 注册到 Pod 使用服务的完整数据流：

  流程总结：管理员创建 ClusterServiceBroker → Controller 自动生成 ClusterServiceClass → 用户在命名空间创建 ServiceInstance（选择 Class 和 Plan）→ 创建 ServiceBinding 获取凭据 Secret → Pod 通过 Secret 连接外部服务。整个过程无需手动管理连接字符串或重启应用。

2.5 常见问题与避坑指南

Broker 不可达：确保 ClusterServiceBroker 的 url 在集群网络内可访问，且返回符合 Open Service Broker API 规范。使用 kubectl get clusterservicebroker <name> -o yaml 查看 status.conditions 定位问题。
Class 未生成：检查 Broker 的 /v2/catalog 响应格式是否正确，特别是 services[].id 和 plans[].id 必须为 UUID 格式。
Instance 一直 Provisioning：查看 ServiceInstance 的 status.conditions 和 Controller 日志。常见原因包括参数校验失败、后端资源不足、Broker 超时。
Binding 失败：确认 ServiceInstance 状态为 Provisioned，且该 Class 的 bindable 字段为 true。检查 Secret 是否已存在同名对象。
跨命名空间访问：ClusterServiceClass 是集群级资源，但 ServiceInstance 和 ServiceBinding 是命名空间级。不同命名空间可以申请同一个 Class 的多个独立实例。

安全提醒：ServiceBinding 生成的 Secret 包含敏感凭据，务必通过 RBAC 限制对 Secret 的访问。避免将 Secret 明文存储在代码仓库中。