Connectors CSI 驱动

概览

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

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

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

INFO

使用本文档了解工作负载如何挂载 Connector 渲染后的配置并消费与 proxy 相关的运行时数据。

本文档重点介绍挂载和渲染行为。有关 proxy 流量和认证,请参阅 Connectors Proxy。有关权限门控和审批触发的运行时访问,请参阅 Connectors Approval & Permission Gating。

快速开始

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 Driver 创建 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

验证已挂载的文件:

# List all mounted files (including built-in configurations)
kubectl exec -ti csi-demo -- ls -l /tmp/config

# View the custom configuration from ConnectorClass
kubectl exec -ti csi-demo -- cat /tmp/config/.gitconfig

内置配置

CSI Driver 默认会自动提供并挂载内置配置文件到 Pod 中。 你可以在 configuration.names 中使用 !<fileName> 排除特定的挂载文件(例如 !context.token),这包括由 configuration.names 选择的内置文件和 ConnectorClass 渲染文件。

文件名描述
.env包含 http_proxy、https_proxy 和 no_proxy 的环境变量文件,格式为 key=value。
如果存在多个 Connector Category,则会应用最后一个 ConnectorClass 中的代理设置。
http.proxy用于 HTTP 的带认证正向代理 URL。
如果存在多个 Connector Category,则会应用最后一个 ConnectorClass 中的代理设置。
https.proxy用于 HTTPS 的带认证正向代理 URL。
如果存在多个 Connector Category,则会应用最后一个 ConnectorClass 中的代理设置。
.curlrc一个 curl 配置文件,包含单行 proxy = <scheme>://<username>:<token>@<host>:<port>,这样工具就可以直接运行 curl --config /{mount-path}/.curlrc,而无需手动导出代理环境变量。
如果挂载了多个 Connector,则所有 Connector 标识会合并到 username 中(ns1%2Fname1,ns2%2Fname2,...),并且将使用最后一个 ConnectorClass 的代理地址。
context.tokenproxy 服务的认证令牌
context.proxy.caCertConnectors proxy 的 CA 证书
connector.status.proxyAddressproxy 地址(参见 Connectors Proxy)。
如果存在多个 Connector,则会使用最后一个 ConnectorClass 中的 proxy 信息。
ca.certConnectors proxy 的 CA 证书,与 context.proxy.caCert 相同,即将废弃;请改用 ca.crt。
ca.crtConnectors proxy 的 CA 证书,与 context.proxy.caCert 相同
.error.json仅在审批被拒绝时存在。当此文件存在时,不会挂载其他任何配置文件。详情请参阅 Connectors Approval。

正向代理使用:

# Option 1
export http_proxy=$(cat /{mount-path}/http.proxy)
export https_proxy=$(cat /{mount-path}/https.proxy)

# Option 2
source /{mount-path}/.env

# Option 3 — for tools driven by curl
curl --config /{mount-path}/.curlrc http://{backend-url}
HTTPS 目标需要 proxy CA 证书

Connectors 正向代理会重新签名 TLS 流量,因此 curl 默认会拒绝该代理证书。请通过 --cacert 传入内置的 ca.crt(与 .curlrc 一同挂载):

curl --config /{mount-path}/.curlrc --cacert /{mount-path}/ca.crt https://{backend-url}

cacert 指令无法直接写入 .curlrc 本身:CSI driver 在模板渲染时并不知道容器内的挂载路径,而且挂载卷是只读的——因此每次 curl 调用都必须在命令行中指定 ca.crt 的绝对路径。

反向代理使用:

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 配置;使用 !<fileName>(例如 !context.token)以从最终挂载输出中排除特定文件。
configuration.params否命名配置的运行时参数 JSON 字符串(参见 configuration.params)
token.expiration否令牌过期时间(默认:30m)
connectors是以逗号分隔的 Connector 列表,格式为 namespace/name 或 name;如果省略 namespace,则使用 Pod 的 namespace。用于指定多个 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"

排除特定的挂载文件:

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

在仅挂载内置配置时排除某个内置文件:

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

说明:

  • 如果省略 configuration.names,则只会挂载内置配置
  • 当多个配置包含同名文件时,后面的配置会覆盖前面的配置
  • 排除项(!<fileName>)会在配置收集和合并后,应用于最终挂载的文件名。
  • 如果指定了包含的配置名称,但未找到任何配置,即使提供了排除项,请求也会失败。
  • connectors 参数用于指定多个用于挂载配置的 Connector。

configuration.params

configuration.params 允许调用方在挂载时将运行时参数传入配置模板。ConnectorClass 中的每个配置都可以声明一组命名参数;在创建 CSI 卷时,configuration.params 为这些参数提供值。

格式

其值是一个 以配置名称为键 的 JSON 对象,其中每个值都是一个键值对对象:

configuration.params: '{"<configName>": {"key": "value", ...}, ...}'

示例——在一次挂载中,将 mirrorRepository 传递给 settings 配置,并将 registry 传递给 npmrc 配置:

volumeAttributes:
  configuration.names: "settings,npmrc"
  configuration.params: '{"settings": {"mirrorRepository": "maven-public"}, "npmrc": {"registry": "npm-proxy"}}'

按配置名称进行作用域划分,可以确保无论挂载了多少个 Connector 或它们的名称是什么,参数都保持稳定。与 Connector 相关的特定值应放在 Connector.spec.params 中,可通过模板中的 .connectors[i].spec.params 访问。

默认值的工作方式

当 ConnectorClass 配置声明了一个带默认值的参数,而调用方省略该参数时,CSI Driver 会在渲染模板之前自动注入默认值。此时无需在 configuration.params 中显式提供值。

示例——strictSSL 的默认值为 "true",因此可以省略:

# This is equivalent to passing '{"npmrc": {"registry": "npm-proxy", "strictSSL": "true"}}'
configuration.params: '{"npmrc": {"registry": "npm-proxy"}}'

如果某个参数未声明 default,而调用方省略了它,CSI 挂载将失败,并返回 required configuration param "<name>" is missing。要让参数成为可选项,ConnectorClass 作者应声明 default: ""(或其他哨兵值),并且在模板中对正文进行条件保护,使缺失值渲染为占位注释,而不是生成损坏的文件。Nexus 和 JFrog 连接器在其 npmrc.registry、yarnrc.registry、pipconf.repository 和 pypirc.deployRepository 参数中采用了此模式——有关渲染后的占位格式,请参阅 Nexus 和 JFrog 的 ConnectorClass 页面。

模板中可用的变量

处理完成后,传入的参数(以及默认参数)可在配置模板中通过 .configurations.<paramName> 使用:

{{ .configurations.mirrorRepository }}
{{ .configurations.registry }}

多个 Connector

Connectors CSI Driver 支持使用多个 Connector 进行配置。你可以通过 connectors 卷属性指定多个 Connector,格式为 namespace/name 或 name;如果省略 namespace,则使用 Pod 的 namespace。多个 Connector 之间应以逗号分隔。

INFO

在一个 CSI 卷中使用多个 Connector 之前,请先在 ConnectorsConfig 上启用 enable-multi-connector 特性标志。详情请参阅 Feature Flags。

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

当指定多个 Connector 时,CSI Driver 会根据 configuration.names 属性合并配置文件。合并行为详见 Configuration Merging 部分。

WARNING

你可以列出的 Connector 数量没有严格限制;不过,请避免指定过多 Connector,以防请求头过大以及其他与 proxy 相关的问题。

配置合并

当指定多个 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/
# Output:
# - .multi-connector-config
WARNING

如果合并后的 Connector 来自不同的 ConnectorClass,且它们具有同名配置文件,那么后面的 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 }}
        ]}

同时挂载 connectors 和 configuration names 时:

- 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/
# Output:
# - config.xml
# - settings.json

配置文件渲染

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

可用变量

变量描述
.connector.status.proxyAddressConnector 的 proxy 地址;请参阅 connectors-proxy
.connector.spec.*Connector 的 Spec,你可以获取 Connector Spec 的所有字段,例如 .connector.spec.address 或 .connector.spec.params
.context.token访问 proxy 服务的认证令牌
.context.proxy.caCert用于访问 connectors proxy(正向代理)的 CA 证书;请参阅 connectors-proxy
.connectors在指定多个 Connector 时的 Connector 列表;每个 Connector 的结构都与 .connector 相同
.connectorclass.proxyAddress在指定多个 ConnectorClass 时,ConnectorClass 的 proxy 地址。

内置函数

支持的函数请参阅 sprig

例如:b64enc:对字符串进行 Base64 编码

关于 proxy 服务

Connectors 为每个 Connector 提供 proxy 服务,使客户端无需保存原始凭据即可访问目标资源。更多详情请参阅 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 }}

使用 proxy 服务和令牌

以下 ConnectorClass 提供了一个名为 .gitconfig 的文件,它会自动注入 header,并在 git clone 期间借助 proxy 服务和令牌替换 git URL。

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

在 range 块内部,. 表示当前 Connector,因此卷级令牌通过根上下文 $.context.token 引用。[http "<proxyAddress>"] 部分只会将 Authorization header 作用域限制到 proxy 地址——对任何其他 host 的请求都不会携带由 Connector 注入的 header。

下一步