快速开始

本文档将帮助你快速了解并使用 Connectors 系统。

简介

适用场景

Connectors 系统为在整个 Kubernetes 集群中安全管理外部系统连接提供了一种统一方式。通过使用 connectors,你可以:

  • 集中管理外部服务的凭证
  • 消除应用代码中的硬编码凭证
  • 确保整个组织内一致的访问模式
  • 在一个位置监控和审计服务连接

本指南以 GitHub 为例,但相同的原则也适用于连接其他服务。

预计阅读时间

10-15 分钟

注意事项

  • 本快速开始假设你已经安装了 Connectors Operator,并且 ConnectorsConfig 已协调到 Ready(operator 会自动创建一个 — 参见 安装指南)。默认安装会启用所有组件,包括本指南所需的 core 和 git。
  • 你需要一个 GitHub 账户以及一个具有适当权限的 Personal Access Token (PAT)。
  • connector 状态反映连接的健康状况和可访问性。

前提条件

  • 已安装 Connectors Operator 且 ConnectorsConfig 已协调到 Ready 的 Kubernetes 集群。默认安装会启用本指南所需的 core 和 git 组件。
  • 已配置 kubectl 以便与集群通信
  • GitHub 账户和有效的 Personal Access Token (PAT)
  • 对 Kubernetes 资源的基本了解

流程概览

编号操作步骤描述
1验证所需组件确保 connector 基础设施已正确安装
2创建认证 Secret创建包含 GitHub 凭证的 Kubernetes Secret
3创建 GitHub connector配置到 GitHub 的 connector
4验证 connector 状态检查 connector 是否已准备好可供使用

操作步骤

第 1 步:验证所需组件

在创建 GitHub connector 之前,请验证集群中的 connector 基础设施已正确安装。

  1. 检查 ConnectorsConfig 是否已协调到 Ready:

    kubectl get connectorsconfig -A

    READY 应显示为 True。若要查看各组件的阶段,请运行 kubectl describe connectorsconfig connectors-config -n <namespace>。

  2. 验证 Git ConnectorClass 是否存在:

    kubectl get connectorclass git

    如果未找到 Git ConnectorClass,则说明 git 组件已禁用或尚未完成安装。请在 ConnectorsConfig 中启用它(spec.components.git.enabled: true),然后重新检查 — 配置语法请参见 安装指南。

第 2 步:创建认证 Secret

创建一个包含 GitHub 凭证的 Kubernetes Secret。

  1. 执行以下命令,使用你的 GitHub 凭证创建一个 Secret:

    kubectl create secret generic github-auth \
      --namespace default \
      --type=kubernetes.io/basic-auth \
      --from-literal=username=your-github-username \
      --from-literal=password=your-github-token

    将 your-github-username 替换为你的 GitHub 用户名,将 your-github-token 替换为你的 GitHub Personal Access Token。

  2. 验证 Secret 是否已成功创建:

    kubectl get secret github-auth -n default

第 3 步:创建 GitHub connector

使用 Git ConnectorClass 创建一个到 GitHub 的 connector。

  1. 将以下 YAML 保存为 github-connector.yaml:

    apiVersion: connectors.alauda.io/v1alpha1
    kind: Connector
    metadata:
      name: github-connector
      namespace: default
    spec:
      connectorClassName: git
      address: "https://github.com"
      auth:
        name: basicAuth
        secretRef:
          name: github-auth
          namespace: default
  2. 应用该 connector:

    kubectl apply -f github-connector.yaml

第 4 步:验证 connector 状态

创建 connector 后,请检查其状态以确保其正常工作。

  1. 使用以下命令检查 connector 状态:

    kubectl get connector github-connector -n default
  2. 如需查看详细状态信息,请使用:

    kubectl get connector github-connector -n default -o yaml

预期结果

成功完成所有步骤后,你将看到以下结果:

  1. GitHub connector 资源状态显示为 "Ready":

    NAME               CLASS   ADDRESS              READY   AGE
    github-connector   git     https://github.com   True    2m
  2. 详细状态信息中的所有条件均为 "True":

    status:
      conditions:
      - type: ConnectorClassReady
        status: "True"
      - type: SecretReady
        status: "True"
      - type: LivenessReady
        status: "True"
      - type: AuthReady
        status: "True"
      - type: ProxyServiceReady
        status: "True"
      - type: Ready
        status: "True"
  3. 如果 connector 配置了代理功能,你还会在状态中看到一个代理地址:

    status:
      proxy:
        httpAddress:
          url: http://c-github-connector.default.svc.cluster.local

现在,你已经成功创建了一个 GitHub connector,并验证其可正常工作。

你的应用可以使用该 connector 安全地访问 GitHub 仓库,而无需将凭证直接嵌入应用代码中。

故障排查

如果你的 connector 未能达到 "Ready" 状态,请检查以下内容:

  1. ConnectorClass 可用性:确保 Git ConnectorClass 存在:

    kubectl get connectorclass git

    如果不存在,则说明 ConnectorsConfig 上的 git 组件已禁用或尚未完成安装。有关配置语法,请参见 安装指南。

  2. 认证配置:确保 Secret 中的凭证正确且具有适当权限。

  3. 仓库可访问性:验证 auth 参数中指定的仓库是否存在,并且使用所提供的凭证可以访问。

  4. 检查控制器日志:查看 connector controller 日志以获取详细错误信息:

    kubectl logs -n connectors-system -l app.kubernetes.io/name=connectors-controller-manager

下一步

现在你已经创建了第一个 connector,可以继续:

  • 为其他 Git 服务(GitLab、Harbor 等)创建 connector
  • 配置应用以使用该 connector 安全访问 Git 仓库