Connectors CSI 驱动
概览
Connectors CSI Driver 是一个基于 Container Storage Interface (CSI) 规范实现的存储驱动。它可以将来自 Connector 的配置作为卷挂载到 Kubernetes 工作负载中。其主要功能包括:
- 将来自 Connector 的配置文件挂载到 Pod 中
- 支持在配置文件中进行动态变量渲染,以自动注入运行时信息
- 支持同时挂载多个配置文件
所有配置数据都来自与该 Connector 关联的 ConnectorClass 配置。
快速开始
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 渲染文件。
正向代理使用:
# 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 卷参数
卷参数
卷属性
示例
挂载单个配置:
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 语法。
可用变量
内置函数
支持的函数请参阅 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。
下一步