ConnectorsProxy
Connectors Proxy 是 Connectors 系统的核心功能,可为集成工具提供安全的无密钥访问。它通常作为 HTTP 服务运行,可充当客户端应用程序的正向代理或反向代理。
当客户端通过 Connectors Proxy 访问工具资源时,代理会自动将必要的身份验证凭证注入请求,从而实现无缝访问,而无需客户端直接处理凭证。这种方式可带来显著的安全优势:
- 无密钥访问:使用 Kubernetes 签发的短期令牌,免去了直接向客户端分发工具凭证的需要,从而防止凭证暴露在日志或环境变量等客户端环境中。
为满足不同工具的身份验证要求,该平台同时支持内置代理实现和自定义代理实现。每个 ConnectorClass 都可以提供自己的代理服务,从而灵活满足特定工具的身份验证需求。
目录
内置 Connectors Proxy正向代理正向代理凭证注入目标反向代理自定义 Connectors ProxyConnector Proxy 地址与 Connectors CSI Driver 配合使用深入了解 Connectors Proxy在 ConnectorClass 中指定代理Connectors Proxy 身份验证内置正向代理身份验证内置反向代理身份验证基于 Custom Rego 的身份验证Connector 标识使用内置反向代理向后端请求注入身份验证凭证Basic AuthBearer TokenCustom Rego建议设置参考资料后续步骤内置 Connectors Proxy
内置的 ConnectorsProxy 实现提供全面的 HTTP/HTTPS 协议支持,以及 Basic Auth 和 Bearer Token 身份验证方法。它同时支持正向代理和反向代理功能。
正向代理
使用 http_proxy 和 https_proxy 环境变量作为标准 HTTP 代理运行。当代理收到客户端请求时,它会:
- 对客户端进行身份验证
- 仅当请求目标为该 Connector 的允许地址时,注入 Connector 中指定的工具凭证
- 将经过身份验证的请求转发到目标工具
Connectors Proxy 不支持用于 HTTP tunneling 的 CONNECT 方法。客户端必须直接向代理服务器发送 HTTP 请求。
正向代理凭证注入目标
对于内置正向代理模式,凭证注入目标为:
Connector.spec.addressConnector.spec.addressExtensions[*].value
未配置 addressExtensions 时,只有 spec.address 符合条件。
更改这些地址需要具备更新 Connector 本身的权限,因此此功能不会产生新的凭证所有权边界。
反向代理
客户端通过直接连接到 Connector Proxy 地址,而不是原始工具 URL,来访问工具。代理会:
- 在代理端点接收客户端请求
- 执行客户端身份验证
- 注入 Connector 中指定的工具凭证,并将请求转发到后端工具
自定义 Connectors Proxy
对于需要专用身份验证机制的工具,可以开发自定义代理实现。根据具体需求,这些代理可以实现为正向代理或反向代理。
示例:OCI Connector 使用自定义 OCI Plugin Proxy,支持 OCI 协议,并通过 Bearer Token 为 Harbor 和 CNCF Distribution Registry 等 registry 提供授权。
用户可以开发自定义代理服务器,并在 ConnectorClass 中指定该服务器。
Connector Proxy 地址
每个 Connector 都有一个用于访问工具资源的唯一代理地址。代理地址存储在 status.proxy.httpAddress 字段中:
客户端使用此代理地址访问 Connector 指定的工具中的资源。
有关 ConnectorClass 的更多字段,请参阅 ConnectorClass
与 Connectors CSI Driver 配合使用
Connectors Proxy 可与 Connectors CSI Driver 无缝配合,为无密钥访问提供完整解决方案:
- Connectors CSI Driver 挂载包含代理地址和代理身份验证信息的必要配置文件
Connectors Proxy处理身份验证注入,并将请求路由到目标工具。- 客户端无需管理凭证即可访问资源。
此集成特别适用于以下场景:
- Kubernetes Jobs 中的 Git clone 操作
- Tekton Pipelines 中的镜像推送/拉取操作
- 自定义工作负载中的 API 访问
有关使用 Connectors Proxy 和 Connectors CSI Driver 实现完整无密钥访问场景的信息,请参阅如何使用 Git Connector 在客户端不存储凭证的情况下完成 Git clone
深入了解 Connectors Proxy
在 ConnectorClass 中指定代理
可以在 ConnectorClass 中指定要使用的代理服务器:
从此 ConnectorClass 创建的 Connector 将使用 connectors-proxy-service 作为实际代理服务器。
内置代理配置:
自定义代理配置:
自定义代理可以指向任何能够处理代理请求的地址。
Connectors Proxy 身份验证
使用 Connectors Proxy 时,客户端必须提供正确的身份验证凭证才能访问代理。身份验证过程需要包含两个关键要素:
- Connector 标识:指定要用于凭证注入的 Connector
- 授权令牌:提供对目标 Connector 具有读取权限的 ServiceAccount 令牌
代理服务器会验证所提供的 ServiceAccount 令牌,确保其在处理请求前对指定的 Connector 具有必要权限,并在验证通过后将身份验证凭证注入请求。
默认情况下,当 enable-connector-proxy-permissions 被禁用时,只要对 Connector 具有读取权限,即可使用 Connectors Proxy。
启用 enable-connector-proxy-permissions 后,系统会对目标 Connector 额外执行 connectors/proxy 权限检查。这项额外的能力权限将 Connector 发现与通过代理路径进行实际运行时使用区分开来。
有关整体模型以及 connectors/proxy 的含义,请参阅 Connectors 权限模型。
有关 ServiceAccount 令牌和 RBAC 配置的详细信息,请参阅 Kubernetes 身份验证文档。
内置正向代理身份验证
对于正向代理模式,身份验证信息通过 Proxy-Authorization 标头传递,并使用 HTTP Proxy Basic Authentication。
- 用户名:
<connector-namespace>/<connector-name> - 密码:对 Connector 具有读取权限的 ServiceAccount 令牌
Proxy-Authorization 标头:
HTTP Proxy 环境变量示例:
可以使用标准 HTTP 代理环境变量配置代理身份验证:
%2F是 Connector 命名空间/名称格式的/经过 URL 编码后的形式。- 指定多个 Connector 时,请使用逗号分隔。可列出的 Connector 数量没有严格限制,但应避免配置过多 Connector,以防请求标头过大及产生相关问题。
内置反向代理身份验证
对于反向代理模式,客户端直接连接到 Connector 的代理地址。身份验证令牌可以使用 Basic Auth 或 Bearer Token 方法提供,而 Connector 标识则通过 Connector Proxy 地址处理。
Basic Authentication
- 用户名:任意值(会被忽略)
- 密码:对 Connector 具有读取权限的 ServiceAccount 令牌
示例:
Bearer Token Authentication
- Authorization 标头:
Bearer <service-account-token>
示例:
基于 Custom Rego 的身份验证
使用内置 HTTP 反向代理访问采用非标准身份验证方法的工具时,客户端可能无法使用标准 Basic Auth 或 Bearer Token 方法提供令牌。此时,客户端必须使用工具原生的凭证格式。
要支持这些自定义身份验证格式,可以使用 Rego 规则自定义从客户端请求中提取令牌的方式。这样,无论客户端以何种方式提供令牌,内置 HTTP 反向代理都可以提取并验证令牌。
例如:
此配置会从客户端请求中的 Private-Token 标头提取令牌,然后由代理使用该令牌验证客户端身份。
这种方式为非标准 HTTP 身份验证机制提供了很大的灵活性。客户端 CLI 可以使用工具原生的凭证格式提供 Kubernetes 令牌,代理则通过 Rego 规则提取令牌,完成身份验证。
有关使用 Rego 规则提取令牌的详细配置,请参阅 ConnectorClass。
有关向后端请求注入身份验证凭证的更多信息,请参阅使用内置反向代理向后端请求注入身份验证凭证。
Connector 标识
可以通过不同的代理地址格式标识 Connector:
- Service 格式:例如
http://c-<connector-name>.<namespace>.svc.cluster.local - 路径格式:
http://<proxy-address>/namespaces/<connector-namespace>/connectors/<connector-name>
系统会自动生成 Connector Proxy 地址,并且每个 Connector 都具有唯一的代理地址。使用前,必须从 Connector 资源的 status.proxy.httpAddress 字段获取 Connector Proxy 地址。
示例:
对于 default 命名空间中的 github Connector:
代理会验证身份验证令牌,并在将请求转发到 GitHub 服务时,自动注入 default/github Connector 的身份验证凭证。
使用内置反向代理向后端请求注入身份验证凭证
内置反向代理验证客户端请求后,会根据 Connector 中配置的凭证类型,将身份验证凭证注入后端请求。支持以下注入方式:
- Basic Auth
- Bearer Token
- Custom Rego
Basic Auth
当 Connector 配置的 secret 类型为 kubernetes.io/basic-auth 时,代理会使用 Basic Authentication 将凭证注入后端请求标头。
Bearer Token
当 Connector 配置的 secret 类型为 connectors.cpaas.io/bearer-token 时,代理会使用 Bearer Token 身份验证将凭证注入后端请求标头。
Custom Rego
除标准 Basic Auth 和 Bearer Token 方法外,还可以使用 Rego 规则定义自定义身份验证注入逻辑。例如:
此配置会将 Connector secret 数据中的令牌值注入后端请求的 Private-Token 标头。
有关详细配置,请参阅 ConnectorClass。
使用自定义 Rego 身份验证时,通常需要配置 spec.proxy.authExtractor,以从客户端请求中提取令牌,使内置 HTTP 反向代理能够验证客户端身份验证。
同时,使用 spec.auth.types[].generator.rego 将身份验证凭证注入后端请求。
这种组合支持在使用内置 HTTP 反向代理时实现自定义身份验证机制。
建议设置
启用时机。当流水线必须访问 Git 服务器、registry 或其他工具,且不能持有这些工具的长期凭证时,请使用此设置。流水线随后通过 Connectors Proxy 访问工具:代理会注入存储在 Connector 中的凭证,而客户端仅提供由 Kubernetes 签发的短期 ServiceAccount 令牌(请参阅 Connectors Proxy Authentication)。这些设置不会阻止流水线直接访问工具的网络连接;它们只会确保工具凭证不会出现在流水线中。
建议值。要在项目的各个命名空间之间共享 Connectors,请在 Connector Resource Levels and Permissions 中所述的项目级别创建它们。工作负载通过 Connectors CSI Driver 挂载 Connectors,并使用挂载配置中的短期令牌,通过 Connectors Proxy 访问工具。在默认功能标志设置下,对 Connector 的读取(get)权限足以通过 Connectors Proxy 使用该 Connector(请参阅 Connectors Proxy Authentication 和 Connectors Permission Model);在 ACP 上,平台已经向项目成员命名空间中的每个 ServiceAccount 授予了项目级 Connector 的该权限。因此,这些命名空间中的每个工作负载都可以通过 Connectors Proxy 使用项目的 Connectors。要将代理的使用限制为特定的 ServiceAccount,请启用代理权限检查。除读取权限外,该检查还要求 connectors/proxy 权限,并且只能向运行流水线的 ServiceAccount 授予该权限;请参阅 Enable Proxy Permission Checks and Approval Gating。该指南还介绍了如何仅在审批后发布敏感 Connector。这两项控制均为可选项,并会更改整个集群范围的功能标志。
前提条件。流水线应在指定名称的 ServiceAccount 下运行,以便在启用代理权限检查时向其授予代理权限。工作负载通过 Connectors CSI Driver 挂载代理地址和令牌。只有在以下条件同时满足时,流水线才不会持有工具的任何长期凭证:流水线用户无法在存储 Connectors 所引用 Secret 的命名空间中创建 Pod 或运行流水线,并且对这些 Secret 没有读取权限。这是因为,当 Pod 从其自身命名空间挂载 Secret 时,Kubernetes 不会检查 Secret 的读取权限。