Connectors CSI 驱动
目录
概述快速入门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 正向代理会重新签署 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 代理使用该令牌发出的请求将无法通过身份验证。 - driver 不强制要求最小值或最大值。该值会作为
expirationSeconds传递到 Kubernetes TokenRequest 中,因此可接受的范围和所签发令牌的生命周期由集群 kube-apiserver 的 TokenRequest 策略决定。
示例
挂载单个配置:
挂载多个配置:
挂载多个 Connector 以进行代理身份验证:
排除特定的挂载文件:
仅挂载内置配置,同时排除某个内置文件:
注意:
- 如果省略
configuration.names,则仅挂载内置配置 - 当多个配置包含同名文件时,后面的配置会覆盖前面的配置
- 排除项(
!<fileName>)会在收集并合并配置后,针对最终挂载的文件名应用。 - 如果指定了要包含的配置名称,但一个也未找到,则请求会失败,即使提供了排除项也是如此。
connectors参数用于指定多个 Connector,以挂载配置。
configuration.params
configuration.params 允许调用方在挂载时将运行时参数传入配置模板。ConnectorClass 中的每个配置都可以声明一组命名参数;创建 CSI 卷时,configuration.params 会为这些参数提供值。
格式
该值是一个以配置名称为键的 JSON 对象,其中每个值都是由键值对组成的对象:
示例 — 在一次挂载中,向 settings 配置传入 mirrorRepository,并向 npmrc 配置传入 registry:
按配置名称限定作用域后,无论挂载多少个 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 volume 属性,以 namespace/name 或 name 的格式指定多个 Connector;如果省略 namespace,则使用 Pod 的 namespace。多个 Connector 应使用逗号分隔。
在单个 CSI volume 中使用多个 Connector 之前,请在 ConnectorsConfig 上启用 enable-multi-connector feature flag。有关详细信息,请参阅 Feature Flags。
指定多个 Connector 后,CSI Driver 会根据 configuration.names 属性合并配置文件。有关合并行为的详细信息,请参阅配置合并部分。
您可以列出的 Connector 数量没有严格限制;但是,请避免指定过多 Connector,以防止请求标头过大以及其他与代理相关的问题。
配置合并
指定多个 Connector 后,CSI Driver 会根据 configuration.names 属性合并所有指定 Connector 的配置文件。
处理配置文件时可能存在多种情况;以下内容介绍每种情况下的行为。
相同的配置名称
对于配置名称相同的 Connector,指定多个 Connector 后,其配置数据会合并到单个配置文件中。
配置模板应支持为多个 Connector 渲染数据,以便单个文件可以包含多个特定于 Connector 的数据集。
例如:
在上述示例中,配置文件 .multi-connector-config 将包含 connectors volume 属性中指定的每个 Connector 对应的部分。
如果合并的 Connector 来自不同的 ConnectorClass,且其配置文件具有相同名称,则后一个 ConnectorClass 的配置会覆盖前一个 ConnectorClass 的配置。因此,在此场景中,建议使用不同的配置文件名称,以避免冲突。
不同的配置名称
当指定的 Connector 具有不同的配置名称时,CSI Driver 会分别挂载所有配置。
同时使用 Connector 和配置名称进行挂载时:
挂载的 volume 将同时包含 config.xml 和 settings.json,每个文件分别填充来自对应 Connector 的数据。
配置文件渲染
CSI Driver 在挂载配置文件时使用 Go 模板 语法执行变量渲染。
可用变量
内置函数
支持的函数请参阅 sprig
例如:b64enc:对字符串进行 Base64 编码
关于代理服务
Connectors 会为每个 Connector 提供代理服务,使客户端无需存储原始凭证即可访问目标资源。有关详细信息,请参阅 connectors-proxy。
配置示例
固定内容
使用 connector.spec.params
以下 ConnectorClass 定义了参数 sslVerify,用于控制 git clone 期间的 SSL 验证。
使用代理服务和令牌
以下 ConnectorClass 提供名为 .gitconfig 的文件,该文件使用代理服务和令牌,在 git clone 期间自动注入标头并替换 git URL。
在 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,并将被弃用:
将 <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 的读取权限。