ConnectorsProxy
Connectors Proxy 是 Connectors 系统的核心能力,为集成工具提供安全、无密钥的访问。它通常作为 HTTP 服务运行,可充当前向代理或反向代理,为客户端应用提供代理功能。
当客户端通过 Connectors Proxy 访问工具资源时,代理会自动将必要的身份验证凭证注入请求,从而实现无缝访问,而无需客户端直接处理凭证。这种方式具有显著的安全优势:
- 无密钥访问:使用 Kubernetes 签发的短期令牌,避免直接向客户端分发工具凭证。这可以防止凭证暴露在日志或环境变量等客户端环境中。
为满足不同工具的身份验证要求,该平台同时支持内置代理实现和自定义代理实现。每个 ConnectorClass 都可以提供自己的代理服务,从而灵活满足特定的工具身份验证需求。
目录
内置 Connectors Proxy前向代理前向代理凭证注入目标反向代理自定义 Connectors ProxyConnector Proxy 地址与 Connectors CSI Driver 搭配使用深入了解 Connectors Proxy在 ConnectorClass 中指定代理Connectors Proxy 身份验证内置前向代理身份验证内置反向代理身份验证基于自定义 Rego 的身份验证Connector 标识使用内置反向代理时将身份验证凭证注入后端请求Basic AuthBearer Token自定义 Rego推荐设置参考后续步骤内置 Connectors Proxy
内置的 ConnectorsProxy 实现提供全面的 HTTP/HTTPS 协议支持,以及 Basic Auth 和 Bearer Token 身份验证方法。它同时支持前向代理和反向代理功能。
前向代理
使用 http_proxy 和 https_proxy 环境变量作为标准 HTTP 代理运行。当代理收到客户端请求时,它会:
- 对客户端进行身份验证
- 仅当请求目标为该 Connector 的允许地址时,注入 Connector 中指定的工具凭证
- 将经过身份验证的请求转发至目标工具
Connectors Proxy 不支持通过 CONNECT 方法访问 HTTP tunneling。客户端必须直接向代理服务器发送 HTTP 请求。
前向代理凭证注入目标
对于内置前向代理模式,凭证注入目标包括:
Connector.spec.addressConnector.spec.addressExtensions[*].value
当未配置 addressExtensions 时,只有 spec.address 符合条件。
更改这些地址需要拥有更新 Connector 本身的权限,因此此功能不会创建新的凭证所有权边界。
反向代理
客户端通过直接连接到 Connector Proxy 地址,而不是原始工具 URL,来访问工具。代理会:
- 在代理端点接收客户端请求
- 执行客户端身份验证
- 注入 Connector 中指定的工具凭证,并将请求转发至后端工具
自定义 Connectors Proxy
对于需要专用身份验证机制的工具,可以开发自定义代理实现。根据具体需求,这些代理可以实现为前向代理或反向代理。
示例:OCI Connector 使用自定义 OCI Plugin Proxy,该代理支持 OCI 协议,并为 Harbor 和 CNCF Distribution Registry 等 registry 提供 Bearer Token 授权。
用户可以开发自定义代理服务器,并在 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 proxy 环境变量配置代理身份验证:
%2F是/按 Connector 命名空间/名称格式进行 URL 编码后的形式。- 指定多个 Connector 时,请使用逗号分隔。可以列出的 Connector 数量没有严格限制,但应避免配置过多 Connector,以防止请求标头过大以及相关问题。
内置反向代理身份验证
对于反向代理模式,客户端直接连接到 Connector 的代理地址。身份验证令牌可以使用 Basic Auth 或 Bearer Token 方法提供,而 Connector 标识则通过 Connector 代理地址处理。
Basic Authentication
- 用户名:任意值(会被忽略)
- 密码:对 Connector 具有读取权限的 ServiceAccount 令牌
示例:
Bearer Token Authentication
- Authorization 标头:
Bearer <service-account-token>
示例:
基于自定义 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 代理地址,并且每个 Connector 的代理地址都具有唯一性。使用前,必须从 Connector 资源的 status.proxy.httpAddress 字段中获取 Connector 代理地址。
示例:
对于 default 命名空间中的 github Connector:
代理会验证身份验证令牌,并在将请求转发到 GitHub 服务时,自动注入 default/github Connector 的身份验证凭证。
使用内置反向代理时将身份验证凭证注入后端请求
内置反向代理验证客户端请求后,会根据 Connector 中配置的凭证类型,将身份验证凭证注入后端请求。支持以下注入方法:
- Basic Auth
- Bearer Token
- 自定义 Rego
Basic Auth
当 Connector 配置的 secret 类型为 kubernetes.io/basic-auth 时,代理会使用 Basic Authentication 将凭证注入后端请求标头。
Bearer Token
当 Connector 配置的 secret 类型为 connectors.cpaas.io/bearer-token 时,代理会使用 Bearer Token 身份验证将凭证注入后端请求标头。
自定义 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 所引用 Secrets 的命名空间中创建 Pod 或运行流水线,并且对这些 Secrets 没有读取权限,因为 Kubernetes 不会在 Pod 从其自身命名空间挂载 Secret 时检查 Secret 的读取权限。