Connectors CSI Driver

Overview

Connectors CSI Driver 是基于 Container Storage Interface (CSI) 规范实现的存储驱动。它可以将来自 Connector 的配置作为卷挂载到 Kubernetes 工作负载中。主要功能包括：

将来自 Connector 的配置文件挂载到 Pod 中
支持配置文件中的动态变量渲染，自动注入运行时信息
支持同时挂载多个配置文件

所有配置数据均来自与 Connector 关联的 ConnectorClass 配置。

Quick Start

1. 创建 ConnectorClass

首先，创建一个包含 Git 配置的 ConnectorClass：

cat << EOF | kubectl apply -f -
apiVersion: connectors.alauda.io/v1alpha1
kind: ConnectorClass
metadata:
  name: my-git
spec:
  address:
    type: string
  configurations:
  - name: config
    data:
      .gitconfig: |
        this is git config
EOF

2. 创建 Connector

然后，创建一个连接到 GitHub 的 Connector：

cat << EOF | kubectl apply -f -
apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: git-connector
spec:
  address: https://github.com
  connectorClassName: my-git
EOF

3. 创建使用 CSI 驱动的 Pod

创建一个挂载配置的 Pod：

cat << EOF | kubectl create -f -
apiVersion: v1
kind: Pod
metadata:
  name: csi-demo
  namespace: default
spec:
  restartPolicy: Never
  containers:
  - name: web
    image: bitnami/git:2.47.1
    imagePullPolicy: IfNotPresent
    command: ["sleep", "3600"]
    volumeMounts:
    - name: git-config
      mountPath: /tmp/config
  volumes:
  - name: git-config
    csi:
      readOnly: true
      driver: connectors-csi
      volumeAttributes:
        connectors: "default/git-connector"
        configuration.names: "config"
EOF

验证挂载的文件：

# 列出所有挂载的文件（包括内置配置）
kubectl exec -ti csi-demo -- ls -l /tmp/config

# 查看来自 ConnectorClass 的自定义配置
kubectl exec -ti csi-demo -- cat /tmp/config/.gitconfig

内置配置

CSI Driver 会自动提供内置配置文件，这些文件始终挂载到 Pod 中。

文件名	描述
`.env`	环境变量文件，包含 `http_proxy`、`https_proxy` 和 `no_proxy`，格式为 `key=value`。如果存在多个 Connector 类别，则使用最后一个 ConnectorClass 的代理设置。
`http.proxy`	带认证的 HTTP 正向代理 URL。如果存在多个 Connector 类别，则使用最后一个 ConnectorClass 的代理设置。
`https.proxy`	带认证的 HTTPS 正向代理 URL。如果存在多个 Connector 类别，则使用最后一个 ConnectorClass 的代理设置。
`context.token`	代理服务的认证令牌
`context.proxy.caCert`	Connectors 代理的 CA 证书
`connector.status.proxyAddress`	代理地址（参见 Connectors Proxy）。如果存在多个 Connector，则使用最后一个 ConnectorClass 的代理信息。
`ca.cert`	Connectors 代理的 CA 证书，与 `context.proxy.caCert` 相同

正向代理使用示例：

# 方案一
export http_proxy=$(cat /{mount-path}/http.proxy)
export https_proxy=$(cat /{mount-path}/https.proxy)

# 方案二
source /{mount-path}/.env

反向代理使用示例：

export TOKEN=$(cat /{mount-path}/context.token)
export SERVER=$(cat /{mount-path}/connector.status.proxyAddress)

{cli} --server $SERVER --token $TOKEN

CSI 卷参数

卷参数

参数	必填	描述
readOnly	是	必须为 `true`
driver	是	必须为 `connectors-csi`

卷属性

参数	必填	描述
connector.name	否	Connector 名称（已废弃 — 请使用 `connectors`）
connector.namespace	否	Connector 命名空间，默认为 Pod 所在命名空间（已废弃 — 请使用 `connectors`）
configuration.names	否	逗号分隔的配置名称（如 `config1,config2`），配置名称为 ConnectorClass 中配置的名称
token.expiration	否	令牌过期时间（默认：`30m`）
connectors	是	逗号分隔的 Connector 列表，格式为 `namespace/name` 或 `name`；若省略命名空间，则使用 Pod 所在命名空间。用于指定多个 Connector。

示例

挂载单个配置：

volumes:
- name: config
  csi:
    driver: connectors-csi
    readOnly: true
    volumeAttributes:
      connectors: "my-connector"
      configuration.names: "config1"

挂载多个配置：

volumes:
- name: config
  csi:
    driver: connectors-csi
    readOnly: true
    volumeAttributes:
      connectors: "my-connector"
      configuration.names: "config1,config2"

挂载多个 Connector 用于代理认证：

volumes:
- name: config
  csi:
    driver: connectors-csi
    readOnly: true
    volumeAttributes:
      connectors: "namespace1/connector1,namespace2/connector2"
      configuration.names: "config1,config2"

注意：

如果省略 configuration.names，则只挂载内置配置
当多个配置包含同名文件时，后面的配置会覆盖前面的
connectors 参数用于指定多个 Connector 以挂载配置

多个 Connector

Connectors CSI Driver 支持使用多个 Connector 进行配置。可以通过 connectors 卷属性指定多个 Connector，格式为 namespace/name 或 name；若省略命名空间，则使用 Pod 所在命名空间。多个 Connector 之间用逗号分隔。

volumes:
- name: config
  csi:
    driver: connectors-csi
    readOnly: true
    volumeAttributes:
      connectors: "namespace1/connector1,namespace2/connector2"
      configuration.names: "config1,config2"

当指定多个 Connector 时，CSI Driver 会基于 configuration.names 属性合并配置文件。合并行为详见配置合并部分。

WARNING

对可列出的 Connector 数量没有严格限制；但建议避免指定过多 Connector，以防请求头过大及其他代理相关问题。

配置合并

当指定多个 Connector 时，CSI Driver 会根据 configuration.names 属性合并所有指定 Connector 的配置文件。

处理配置文件时有多种情况，以下描述各情况的行为。

相同配置名称

对于具有相同配置名称的 Connector，当指定多个 Connector 时，它们的配置数据会合并为单个配置文件。

配置模板应支持渲染多个 Connector 的数据，以便单个文件包含多个 Connector 特定的数据集。

例如：

apiVersion: connectors.alauda.io/v1alpha1
kind: ConnectorClass
metadata:
  name: multi-connector
spec:
  configurations:
  - name: config
    data:
      .multi-connector-config: |
        {{- range .connectors }}
        # Configuration for Connector: {{ .name }}
        param_name = {{ .name }}
        param_value = {{ .spec.address }}
        {{- end }}

上述示例中，配置文件 .multi-connector-config 会包含 connectors 卷属性中每个 Connector 的配置段。

kubectl exec -ti pod-name -- ls -l /mount-path/
# 输出：
# - .multi-connector-config

WARNING

如果合并的 Connector 来自不同的 ConnectorClass，且存在同名配置文件，则后面的 ConnectorClass 配置会覆盖前面的。因此建议在此场景下使用不同的配置文件名以避免冲突。

不同配置名称

当指定的 Connector 具有不同的配置名称时，CSI Driver 会分别挂载所有配置。

apiVersion: connectors.alauda.io/v1alpha1
kind: ConnectorClass
metadata:
  name: connector-a
spec:
  configurations:
  - name: config-a
    data:
      config.xml: |
        {{- range .connectors }}
        # Configuration for Connector: {{ .name }}
        param_name = {{ .name }}
        param_value = {{ .spec.address }}
        {{- end }}
---
apiVersion: connectors.alauda.io/v1alpha1
kind: ConnectorClass
metadata:   
  name: connector-b
spec:
  configurations:
  - name: config-b
    data:
      settings.json: |
        {"connectors": [
        {{- range .connectors }}
          {"name": "{{ .name }}", "address": "{{ .spec.address }}"},
        {{- end }}
        ]}

当同时挂载多个 Connector 和配置名称时：

- name: config
  csi:
    driver: connectors-csi
    readOnly: true
    volumeAttributes:
      connectors: "namespace-a/connector-a,namespace-b/connector-b"
      configuration.names: "config-a,config-b"

挂载的卷将包含 config.xml 和 settings.json，每个文件均填充对应 Connector 的数据。

kubectl exec -ti pod-name -- ls -l /mount-path/
# 输出：
# - config.xml
# - settings.json

配置文件渲染

CSI Driver 在挂载配置文件时会进行变量渲染，使用 Go template 语法。

可用变量

变量	描述
`.connector.status.proxyAddress`	Connector 的代理地址；参见 connectors-proxy
`.connector.spec.*`	Connector 的 Spec，可以获取 Spec 的所有字段，例如 `.connector.spec.address` 或 `.connector.spec.params`
`.context.token`	访问代理服务的认证令牌
`.context.proxy.caCert`	访问 Connectors 代理（正向代理）所用的 CA 证书；参见 connectors-proxy
`.connectors`	当指定多个 Connector 时的 Connector 列表；每个 Connector 结构与 `.connector` 相同
`.connectorclass.proxyAddress`	当指定多个 ConnectorClass 时，ConnectorClass 的代理地址

内置函数

支持的函数请参考 sprig

例如：b64enc：字符串的 Base64 编码

关于代理服务

Connectors 为每个 Connector 提供代理服务，允许客户端访问目标资源时无需存储原始凭据。详情请参见 connectors-proxy。

配置示例

固定内容

apiVersion: connectors.alauda.io/v1alpha1
kind: ConnectorClass
metadata:
  name: my-git
spec:
  address:
    type: string
  configurations:
  - name: config
    data:
      .gitconfig: |
        this is git config

使用 connector.spec.params

以下 ConnectorClass 定义了参数 sslVerify，用于控制 git clone 时的 SSL 验证。

kind: ConnectorClass
metadata:
  name: git
spec:

  params:
  - name: sslVerify
    type: string
    default: "true"

  configurations:
  - name: config
    data:
      .gitconfig: |
        {{ $sslVerify := "true" -}}
        {{- range .connector.spec.params }}{{- if eq .name "sslVerify" }}{{$sslVerify = .value }}{{ end }}{{- end }}
        [http]
          sslVerify = {{ $sslVerify }}

使用代理服务和令牌

以下 ConnectorClass 提供了一个名为 .gitconfig 的文件，利用代理服务和令牌在 git clone 时自动注入头信息并替换 git URL。

kind: ConnectorClass
metadata:
  name: git
spec:
  configurations:
  - name: config
    data:
      .gitconfig: |
        [http]
            extraHeader = Authorization: Basic {{ printf ":%s" .context.token | b64enc }}
        {{- range .connectors }}
        [url "{{ .status.proxyAddress }}"]
            insteadOf = {{.spec.address}}
        {{- end }}

#Connectors CSI Driver

#目录

#Overview

#Quick Start

#1. 创建 ConnectorClass

#2. 创建 Connector

#3. 创建使用 CSI 驱动的 Pod

#内置配置

#CSI 卷参数

#多个 Connector

#配置合并

#配置文件渲染

#可用变量

#内置函数

#关于代理服务

#配置示例