Connectors CSI Driver
目录
概述快速入门1. 创建 ConnectorClass2. 创建 Connector3. 使用 CSI Driver 创建 Pod内置配置CSI 卷参数configuration.params格式默认值的工作方式模板中的可用变量多个 Connector配置合并配置文件渲染可用变量内置函数关于代理服务配置示例建议设置后续步骤概述
Connectors CSI Driver 是基于 Container Storage Interface (CSI) 规范实现的存储驱动。它可以将 Connector 中的配置作为卷挂载到 Kubernetes 工作负载中。主要功能包括:
- 将 Connector 中的配置文件挂载到 Pod
- 支持在配置文件中动态渲染变量,以自动注入运行时信息
- 支持同时挂载多个配置文件
所有配置数据都来自与 Connector 关联的 ConnectorClass 配置。
使用本文档了解工作负载如何挂载 Connector 渲染的配置并使用与代理相关的运行时数据。
本文档重点介绍挂载和渲染行为。有关代理流量和身份验证,请参阅 Connectors Proxy。有关权限控制以及由审批触发的运行时访问,请参阅 Connectors Approval & Permission Gating。
快速入门
1. 创建 ConnectorClass
首先,创建一个包含 Git 配置的 ConnectorClass:
2. 创建 Connector
然后,创建一个连接到 GitHub 的 Connector:
3. 使用 CSI Driver 创建 Pod
创建一个挂载配置的 Pod:
验证挂载的文件:
内置配置
CSI Driver 会自动提供默认挂载到 Pod 中的内置配置文件。
你可以在 configuration.names 中使用 !<fileName> 排除特定的挂载文件(例如 !context.token),其中包括内置文件以及由 configuration.names 选择的 ConnectorClass 渲染文件。
正向代理使用方式:
Connectors forward proxy 会对 TLS 流量重新签名,因此 curl 默认会拒绝代理证书。通过 --cacert 传入内置的 ca.crt(与 .curlrc 一同挂载):
无法将 cacert 指令直接写入 .curlrc:CSI driver 在模板渲染时不知道容器内的挂载路径,并且挂载的卷为只读,因此每次调用 curl 时都必须在命令行中指定绝对的 ca.crt 路径。
反向代理使用方式:
CSI 卷参数
卷参数
卷属性
令牌过期时间
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 proxy 使用该令牌发出的请求将无法通过身份验证。 - driver 不强制执行最小值或最大值。该值会作为
expirationSeconds传递到 Kubernetes TokenRequest 中,因此可接受的范围以及签发令牌的生命周期由集群 kube-apiserver 的 TokenRequest 策略决定。
示例
挂载单个配置:
挂载多个配置:
挂载多个 Connector 以进行 proxy 身份验证:
排除特定的挂载文件:
仅挂载内置配置时排除特定的内置文件:
注意:
- 如果省略
configuration.names,则仅挂载内置配置 - 当多个配置包含同名文件时,后面的配置会覆盖前面的配置
- 排除项(
!<fileName>)会在收集并合并配置后,针对最终挂载的文件名应用。 - 如果指定了要包含的配置名称,但未找到任何配置,则请求会失败,即使提供了排除项也是如此。
- 使用
connectors参数可为挂载配置指定多个 Connector。
configuration.params
configuration.params允许调用方在挂载时将运行时参数传递到配置模板中。ConnectorClass 中的每个配置都可以声明一组命名参数;创建 CSI 卷时,configuration.params会为这些参数提供值。
格式
该值是一个以配置名称为键的 JSON 对象,其中每个值都是由键值对组成的对象:
示例 — 在一次挂载中,将 mirrorRepository 传递给 settings 配置,并将 registry 传递给 npmrc 配置:
按配置名称限定作用域,可以确保无论挂载多少个 Connector 或 Connector 的名称是什么,参数都保持稳定。特定于 Connector 的值应放在 Connector.spec.params 中,并可在模板中通过 .connectors[i].spec.params 访问。
默认值的工作方式
当 ConnectorClass 配置声明了带默认值的参数,而调用方未提供该参数时,CSI Driver 会在渲染模板前自动注入默认值。无需在 configuration.params 中显式提供值。
示例 — strictSSL 的默认值为 "true",因此可以省略:
如果参数未声明 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> 在配置模板中可用:
多个 Connector
Connectors CSI Driver 支持使用多个 Connector 提供配置。您可以使用 connectors 卷属性,以 namespace/name 或 name 的格式指定多个 Connector;如果省略 namespace,则使用 Pod 的 namespace。多个 Connector 应以逗号分隔。
在一个 CSI 卷中使用多个 Connector 之前,请在 ConnectorsConfig 上启用 enable-multi-connector 功能标志。有关详细信息,请参阅功能标志。
指定多个 Connector 时,CSI Driver 会根据 configuration.names 属性合并配置文件。有关合并行为的详细信息,请参阅配置合并部分。
您可以列出的 Connector 数量没有严格限制;但是,请避免指定过多 Connector,以防止请求标头过大及其他与代理相关的问题。
配置合并
指定多个 Connector 时,CSI Driver 会根据 configuration.names 属性合并所有指定 Connector 中的配置文件。
处理配置文件时可能存在多种情况;以下各例描述了每种情况下的行为。
相同的配置名称
对于配置名称相同的 Connector,指定多个 Connector 时,其配置数据会合并到一个配置文件中。
配置模板应支持渲染多个 Connector 的数据,以便单个文件可以包含多个特定于 Connector 的数据集。
例如:
在上述示例中,配置文件 .multi-connector-config 将包含 connectors 卷属性中指定的每个 Connector 对应的部分。
如果合并的 Connector 来自不同的 ConnectorClass,且其配置文件名称相同,则后一个 ConnectorClass 的配置会覆盖前一个 ConnectorClass 的配置。因此,在此场景中,建议使用不同的配置文件名称,以避免冲突。
不同的配置名称
当指定的 Connector 具有不同的配置名称时,CSI Driver 会分别挂载所有配置。
使用这两个 Connector 和配置名称进行挂载时:
挂载的卷将包含 config.xml 和 settings.json,二者分别填充来自各自 Connector 的数据。
配置文件渲染
CSI Driver 使用 Go template 语法,在挂载配置文件时执行变量渲染。
可用变量
内置函数
有关支持的函数,请参阅 sprig。
例如:b64enc:对字符串进行 Base64 编码
关于代理服务
Connectors 为每个 Connector 提供代理服务,使客户端无需存储原始凭证即可访问目标资源。有关更多详细信息,请参阅 connectors-proxy。
配置示例
固定内容
使用 connector.spec.params
以下 ConnectorClass 定义了一个参数 sslVerify,用于控制 git clone 期间的 SSL 验证。
使用代理服务和令牌
以下 ConnectorClass 提供一个名为 .gitconfig 的文件,该文件通过使用代理服务和令牌,在 git clone 期间自动注入标头并替换 git URL。
在 range 块中,. 表示当前 Connector,因此通过根上下文引用卷级别的令牌,即 $.context.token。[http "<proxyAddress>"] 部分将 Authorization 标头的作用域限制为代理地址 — 对任何其他主机的请求都不会携带 Connector 注入的标头。
建议设置
启用时机。每当 pipeline Tasks 或其他工作负载挂载 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.crt 重复,并且将被弃用,除非某个工具仍读取该文件名,否则应使用 !ca.cert:
将 <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。在一个卷中挂载多个 Connector 需要启用 enable-multi-connector 功能标志,具体说明请参阅 Multiple Connectors。如果启用了可选的审批控制,未经授权的挂载仅包含 .error.json;请参阅 Enable Proxy Permission Checks and Approval Gating。只有在运行工作负载的用户无法在存储 Connector 所引用 Secrets 的命名空间中创建 Pod 或运行 pipeline,并且没有这些 Secrets 的读取权限时,工作负载才不会持有长期有效的工具凭证,因为 Kubernetes 不会在 Pod 从其自身命名空间挂载 Secret 时检查 Secret 的读取权限。