#快速开始

本文档将帮助您快速了解如何创建一个 kubernetes connector 以连接到 kubernetes 集群，并在不直接处理凭据的情况下安全地执行 kubectl 操作。

#预计阅读时间

15 分钟

#前提条件

• 已安装 Connectors 系统（Operator、Core 和 K8S 组件）的 Kubernetes 集群。有关安装这些组件的详细信息，请参见安装指南。
• kubernetes 集群 apiserver 地址和具有列出 kubernetes pod 权限的 bearer token
• Kubernetes 基础知识

#流程概览

#操作步骤

#步骤 1：生成 ServiceAccount token

为 k8s connector 生成 ServiceAccount token 以执行操作。

1. 创建一个 ServiceAccount 并绑定一个 clusterrole，clusterrole 应具有与您的用例匹配的所需权限，以便 k8s connector 执行操作。请参阅创建 ServiceAccount 并绑定 clusterrole指南。
2. 生成一个 ServiceAccount token 供 k8s connector 执行操作。请参阅ServiceAccount tokens指南。

#步骤 2：创建 Namespace

为本次演示创建一个专用命名空间：

kubectl create ns k8s-connector-demo

#步骤 3：创建 K8S 凭据和 Connector

创建包含 k8s 凭据的 Secret 和 kubernetes connector 资源。有关创建和配置 connector 的详细信息，请参阅Connectors 快速开始指南。

cat <<EOF | kubectl apply -n k8s-connector-demo -f -
kind: Secret
apiVersion: v1
metadata:
  name: k8s-secret
type: connectors.cpaas.io/bearer-token
stringData:
  token: eyJhbGciOiJSUzI1NiIxxxxxxxx # 替换为您的 k8s bearer token
---
apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: k8s-connector
spec:
  connectorClassName: k8s
  address: https://192.168.1.100:6443 # 替换为您的 k8s apiserver 地址
  auth:
    name: bearerTokenAuth
    secretRef:
      name: k8s-secret
EOF

验证 connector 是否处于 “Ready” 状态：

kubectl get connector k8s-connector -n k8s-connector-demo

输出应显示：

NAME           CLASS   ADDRESS            READY   AGE
k8s-connector  k8s     https://192.168.1.100:6443 True    1m

#步骤 4：创建 Job 执行 Kubectl 操作

创建一个使用 connector 执行 k8s 操作的 Job：

cat <<EOF | kubectl apply -n k8s-connector-demo -f -
apiVersion: batch/v1
kind: Job
metadata:
  name: k8s-access
spec:
  template:
    spec:
      restartPolicy: Never
      containers:
      - name: kubectl
        image: bitnami/kubectl:1.30.1 # 替换为包含 kubectl 的镜像
        imagePullPolicy: IfNotPresent
        env:
        - name: KUBECONFIG
          value: /opt/kube/kubeconfig
        command:
        - "kubectl"
        args: [ "get", "pods", "-v=5", "--all-namespaces" ]  # 替换为您的 kubectl 操作
        volumeMounts:
        - name: kubeconfig
          mountPath: /opt/kube
      volumes:
      - name: kubeconfig
        csi:
          readOnly: true
          driver: connectors-csi
          volumeAttributes:
            connector.name: "k8s-connector"
            configuration.names: "kubeconfig"
EOF

volumeAttributes 中的关键参数：

• connector.name：您的 kubernetes connector 名称
• configuration.names：设置为 "kubeconfig"，引用 kubernetes connectorClass 中定义的特定配置模板。该模板用于生成带有适当认证设置的 ".kubeconfig" 文件。

#步骤 5：验证操作

检查 Job 的日志，确认 kubectl 操作成功执行：

kubectl logs -f job/k8s-access -n k8s-connector-demo

您应看到 kubectl 操作成功完成，并列出集群中所有 pod，且 Job 中无任何秘密配置。

#底层原理

kubernetes connector 的工作原理：

1. 创建一个代理服务，位于您的工作负载和目标 k8s 集群之间
2. 当请求通过代理时注入认证信息
3. 为客户端提供 kubeconfig 文件，以便通过代理执行 kubectl 操作

为演示此机制，我们查看生成的 kubeconfig 文件：

cat <<EOF | kubectl apply -n k8s-connector-demo -f -
apiVersion: v1
kind: Pod
metadata:
  name: inspect-k8s-access
spec:
  restartPolicy: Never
  containers:
  - name: kubectl
    image: bitnami/kubectl:1.30.1 # 替换为包含 kubectl 的镜像
    command: ["sleep", "3600"]
    env:
    - name: KUBECONFIG
      value: /opt/kube/kubeconfig
    volumeMounts:
    - name: kubeconfig
      mountPath: /opt/kube
  volumes:
  - name: kubeconfig
    csi:
      readOnly: true
      driver: connectors-csi
      volumeAttributes:
        connector.name: "k8s-connector"
        configuration.names: "kubeconfig"
EOF

查看生成的 kubeconfig 文件：

kubectl exec -it inspect-k8s-access -n k8s-connector-demo -- cat /opt/kube/kubeconfig

示例输出：

apiVersion: v1
kind: Config
clusters:
- name: k8s
  cluster:
    server: https://192.168.1.100:6443
    proxy-url: http://k8s-connector-demo%2Fk8s-connector:eyJhbGcxxxx@c-k8s-connector.k8s-connector-demo.svc.cluster.local
    certificate-authority-data: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0xxxxxQo=
contexts:
- name: k8s
  context:
    cluster: k8s
    user: k8s
users:
- name: k8s
  user:
    token: fake-token
current-context: k8s

#关键观察点

• server 字段与 Connector 中指定的 Kubernetes API 服务器地址匹配
• 额外的代理相关字段支持基于代理的认证，如 cluster.proxy-url 和 cluster.certificate-authority-data
• kubeconfig 文件不包含原始 bearer token，通过 Connectors CSI Driver 挂载到 Pod

#代理配置字段

• cluster.proxy-url：来自名为 k8s-connector 的 connector 的 status.proxy.httpAddress 字段中的代理地址：

  kubectl get connector k8s-connector -n k8s-connector-demo -o yaml

  输出示例：

  apiVersion: connectors.alauda.io/v1alpha1
  kind: Connector
  metadata:
    name: k8s-connector
    namespace: k8s-connector-demo
  spec:
    # ...
  status:
    # ...
    proxy:
      httpAddress:
        url: http://c-k8s-connector.k8s-connector-demo.svc.cluster.local

  cluster.proxy-url 包含代理认证信息：

  • 用户名：格式为 <connector-namespace>/<connector-name>，即 connector 的命名空间和名称
  • 密码：由 connector 自动生成的临时 ServiceAccount token（30 分钟后过期）（非原始 k8s 集群 token）

• cluster.certificate-authority-data：代理服务器 TLS 验证的 CA 证书数据，客户端应信任代理服务器的证书。

#认证流程

inspect-k8s-access Pod 不包含原始集群 token。当 kubectl 向 Kubernetes API 服务器发起 HTTPS 请求时，代理服务器拦截请求，从 k8s-connector 注入认证凭据，并将认证后的请求转发到后端 API 服务器。

#Kubeconfig 卷

kubeconfig 文件通过 Connectors CSI Driver 挂载到 Pod。

  volumes:
  - name: kubeconfig
    csi:
      readOnly: true
      driver: connectors-csi
      volumeAttributes:
        connector.name: "k8s-connector"
        configuration.names: "kubeconfig"

有关卷参数，请参阅 Kubernetes Connector Concepts 文档中的使用 Connectors CSI Driver 挂载 kubeconfig 文件。

#故障排除

如果您的 kubectl 操作失败，请检查以下内容：

1. Connector 状态：确保 connector 处于 “Ready” 状态：

   kubectl describe connector k8s-connector -n k8s-connector-demo

2. 验证 connectors 部署状态：确保所有组件均已部署且处于 “Ready” 状态

   kubectl get pods -n <connector-component-namespace>

#延伸阅读

成功使用 kubernetes connector 执行 kubectl 操作后，您可以：

• 将 kubectl 命令更改为您需要的操作，如 kubectl create、kubectl apply
• 了解更多关于 Kubernetes Connectors 概念
• 在 CI/CD 流水线中使用 Kubernetes Connectors

#参考资料

• Kubernetes Connector 安装指南