Connectors CSI 驱动

概述

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

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

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

INFO

使用本文档了解工作负载如何挂载 Connector 渲染的配置,以及如何使用与代理相关的运行时数据。

本文档重点介绍挂载和渲染行为。有关代理流量和身份验证,请参阅 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 标识将合并到用户名中(ns1%2Fname1,ns2%2Fname2,...),并使用最后一个 ConnectorClass 中的代理地址。
context.token代理服务的身份验证令牌
context.proxy.caCertConnectors 代理的 CA 证书
connector.status.proxyAddress代理地址(请参阅 Connectors Proxy)。
如果存在多个 Connector,将使用最后一个 ConnectorClass 中的代理信息。
ca.certConnectors 代理的 CA 证书,与 context.proxy.caCert 相同,即将弃用;请改用 ca.crt。
ca.crtConnectors 代理的 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 目标需要代理 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是以 namespace/name 或 name 格式表示的、以逗号分隔的 Connector 列表;如果省略命名空间,则使用 Pod 的命名空间。用于指定多个 Connector。

令牌过期时间

  • token.expiration 使用 Go duration 格式,例如 30m、90m 或 2h。不带单位的值(0 除外)或带有天数单位(例如 1d)的值会被拒绝,并导致卷挂载失败。空值或 0 会回退到 30m。
  • kubelet 为 Pod 挂载卷时会请求令牌,此时 Pod 的容器尚未启动,并且该令牌绑定到该 Pod。CSIDriver 会设置 requiresRepublish: false,因此 kubelet 不会要求 driver 重新发布卷,driver 也不会在 Pod 运行期间续订令牌。将 token.expiration 设置为长于使用该卷的 Pod 或 Task 预期最长运行时间的值;令牌过期后,通过 Connector 代理使用该令牌发出的请求将无法通过身份验证。
  • driver 不强制要求最小值或最大值。该值会作为 expirationSeconds 传递到 Kubernetes TokenRequest 中,因此可接受的范围和所签发令牌的生命周期由集群 kube-apiserver 的 TokenRequest 策略决定。

示例

挂载单个配置:

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", ...}, ...}'

示例 — 在一次挂载中,向 settings 配置传入 mirrorRepository,并向 npmrc 配置传入 registry:

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

按配置名称限定作用域后,无论挂载多少个 Connector 或这些 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 Connector 会对其 npmrc.registry、yarnrc.registry、pipconf.repository 和 pypirc.deployRepository 参数采用此模式 — 有关渲染后的占位符格式,请参阅 Nexus 和 JFrog ConnectorClass 页面。

模板中的可用变量

处理完成后,提供的参数(以及默认参数)会以 .configurations.<paramName> 的形式在配置模板中可用:

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

多个 Connector

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

INFO

在单个 CSI volume 中使用多个 Connector 之前,请在 ConnectorsConfig 上启用 enable-multi-connector feature flag。有关详细信息,请参阅 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 属性合并配置文件。有关合并行为的详细信息,请参阅配置合并部分。

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 volume 属性中指定的每个 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 }}
        ]}

同时使用 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"

挂载的 volume 将同时包含 config.xml 和 settings.json,每个文件分别填充来自对应 Connector 的数据。

kubectl exec -ti pod-name -- ls -l /mount-path/
# Output:
# - config.xml
# - settings.json

配置文件渲染

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

可用变量

变量描述
.connector.status.proxyAddressConnector 的代理地址;请参阅 connectors-proxy
.connector.spec.*Connector 的 Spec,可以获取 Connector Spec 的所有字段,例如 .connector.spec.address 或 .connector.spec.params
.context.token用于访问代理服务的认证令牌
.context.proxy.caCert用于访问 connectors proxy(正向代理)的 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: |
        {{- 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,因此通过根上下文引用 volume 级别的令牌,即 $.context.token。[http "<proxyAddress>"] 部分将 Authorization 标头的作用域限定为代理地址;对任何其他主机的请求都不会携带 Connector 注入的标头。

推荐设置

启用时机。当 pipeline Task 或其他工作负载挂载 Connector 配置,而不是保存工具凭证时,请使用这些设置,以便 Pod 不保存任何长期有效的工具凭证,并使用短期有效的代理令牌,通过 Connectors Proxy 访问工具。Pod 仍可携带自身的 ServiceAccount 令牌;除非将 automountServiceAccountToken 设置为 false,否则该令牌默认会被挂载。

推荐值。将 token.expiration 保持为其默认值 30m,仅对代理访问必须保持更长有效期的挂载提高该值;包括 OCIArtifact 在内的内置 ResourceInterface 资源使用 30m。使用 connectors 属性标识 Connectors,而不要使用已弃用的 connector.name 和 connector.namespace 属性。在 configuration.names 中,仅列出工作负载所需的配置,并使用 !ca.cert 排除 ca.cert 文件,除非某个工具仍读取该文件名;该文件重复了 ca.crt,并将被弃用:

volumes:
- name: config
  csi:
    driver: connectors-csi
    readOnly: true
    volumeAttributes:
      connectors: "<project-namespace>/<connector-name>"
      configuration.names: "config1,!ca.cert"
      token.expiration: 30m

将 <project-namespace>/<connector-name> 替换为 Connector 的命名空间和名称。当 Connector 不在 Pod 自身的命名空间中时,必须指定命名空间。例如,项目级 Connector 位于以项目命名的命名空间中,但从该项目的成员命名空间使用时,就属于这种情况:如果未指定命名空间,则使用 Pod 的命名空间(请参阅 CSI Volume Parameters)。config1 是一个占位符:将其替换为 Connector 的 ConnectorClass 定义的配置名称,因为即使指定了排除项,只要挂载中包含的配置名称全部未知,挂载就会失败。

前提条件。必须安装 Connectors CSI Driver,并且必须允许 Pod 在其资源级别使用 Connector,具体说明请参阅 Connector Resource Levels and Permissions。在一个 volume 中挂载多个 Connectors 需要启用 enable-multi-connector 功能标志,详见 Multiple Connectors。如果启用了可选的审批门控,则未经授权的挂载仅包含 .error.json;请参阅 Enable Proxy Permission Checks and Approval Gating。只有在运行工作负载的用户无法在存放 Connectors 所引用 Secrets 的命名空间中创建 Pod 或运行 pipeline,并且没有这些 Secrets 的读取权限时,工作负载才不会持有长期有效的工具凭证,因为 Kubernetes 在 Pod 从其自身命名空间挂载 Secret 时不会检查 Secret 的读取权限。

后续步骤