ConnectorsProxy

Connectors Proxy 是 Connectors 系统的核心功能,可为集成工具提供安全的无密钥访问。它通常作为 HTTP 服务运行,可充当客户端应用程序的正向代理或反向代理。

当客户端通过 Connectors Proxy 访问工具资源时,代理会自动将必要的身份验证凭证注入请求,从而实现无缝访问,而无需客户端直接处理凭证。这种方式可带来显著的安全优势:

  • 无密钥访问:使用 Kubernetes 签发的短期令牌,免去了直接向客户端分发工具凭证的需要,从而防止凭证暴露在日志或环境变量等客户端环境中。

为满足不同工具的身份验证要求,该平台同时支持内置代理实现和自定义代理实现。每个 ConnectorClass 都可以提供自己的代理服务,从而灵活满足特定工具的身份验证需求。

内置 Connectors Proxy

内置的 ConnectorsProxy 实现提供全面的 HTTP/HTTPS 协议支持,以及 Basic Auth 和 Bearer Token 身份验证方法。它同时支持正向代理和反向代理功能。

正向代理

使用 http_proxy 和 https_proxy 环境变量作为标准 HTTP 代理运行。当代理收到客户端请求时,它会:

  1. 对客户端进行身份验证
  2. 仅当请求目标为该 Connector 的允许地址时,注入 Connector 中指定的工具凭证
  3. 将经过身份验证的请求转发到目标工具
DANGER

Connectors Proxy 不支持用于 HTTP tunneling 的 CONNECT 方法。客户端必须直接向代理服务器发送 HTTP 请求。

正向代理凭证注入目标

对于内置正向代理模式,凭证注入目标为:

  • Connector.spec.address
  • Connector.spec.addressExtensions[*].value

未配置 addressExtensions 时,只有 spec.address 符合条件。 更改这些地址需要具备更新 Connector 本身的权限,因此此功能不会产生新的凭证所有权边界。

反向代理

客户端通过直接连接到 Connector Proxy 地址,而不是原始工具 URL,来访问工具。代理会:

  1. 在代理端点接收客户端请求
  2. 执行客户端身份验证
  3. 注入 Connector 中指定的工具凭证,并将请求转发到后端工具

自定义 Connectors Proxy

对于需要专用身份验证机制的工具,可以开发自定义代理实现。根据具体需求,这些代理可以实现为正向代理或反向代理。

示例:OCI Connector 使用自定义 OCI Plugin Proxy,支持 OCI 协议,并通过 Bearer Token 为 Harbor 和 CNCF Distribution Registry 等 registry 提供授权。

用户可以开发自定义代理服务器,并在 ConnectorClass 中指定该服务器。

Connector Proxy 地址

每个 Connector 都有一个用于访问工具资源的唯一代理地址。代理地址存储在 status.proxy.httpAddress 字段中:

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: github
spec:
  address: https://github.com/kubernetes/kubernetes.git
  auth:
    name: basicAuth
    params:
    - name: repository
      value: kubernetes/kubernetes.git
  connectorClassName: git
status:
  # . . .
  proxy:
    httpAddress:
      url: http://c-github.default.svc.cluster.local

客户端使用此代理地址访问 Connector 指定的工具中的资源。

有关 ConnectorClass 的更多字段,请参阅 ConnectorClass

与 Connectors CSI Driver 配合使用

Connectors Proxy 可与 Connectors CSI Driver 无缝配合,为无密钥访问提供完整解决方案:

  1. Connectors CSI Driver 挂载包含代理地址和代理身份验证信息的必要配置文件
  2. Connectors Proxy 处理身份验证注入,并将请求路由到目标工具。
  3. 客户端无需管理凭证即可访问资源。

此集成特别适用于以下场景:

  • Kubernetes Jobs 中的 Git clone 操作
  • Tekton Pipelines 中的镜像推送/拉取操作
  • 自定义工作负载中的 API 访问

有关使用 Connectors Proxy 和 Connectors CSI Driver 实现完整无密钥访问场景的信息,请参阅如何使用 Git Connector 在客户端不存储凭证的情况下完成 Git clone

深入了解 Connectors Proxy

在 ConnectorClass 中指定代理

可以在 ConnectorClass 中指定要使用的代理服务器:

apiVersion: connectors.alauda.io/v1alpha1
kind: ConnectorClass
metadata:
  name: example
spec:
  proxy:
    ref:
      kind: Service
      name: connectors-proxy-service
      namespace: connectors-system

从此 ConnectorClass 创建的 Connector 将使用 connectors-proxy-service 作为实际代理服务器。

内置代理配置:

ref:
  kind: Service
  name: connectors-proxy-service
  namespace: <connector-namespace> # Namespace where Connector components are deployed

自定义代理配置:

自定义代理可以指向任何能够处理代理请求的地址。

Connectors Proxy 身份验证

使用 Connectors Proxy 时,客户端必须提供正确的身份验证凭证才能访问代理。身份验证过程需要包含两个关键要素:

  1. Connector 标识:指定要用于凭证注入的 Connector
  2. 授权令牌:提供对目标 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 标头:

# credentials format: <connector-namespace>/<connector-name>:<service-account-token>
# example: default/github:sa-token-xxxxxxx
Proxy-Authorization: Basic <base64-encoded-credentials>

HTTP Proxy 环境变量示例:

可以使用标准 HTTP 代理环境变量配置代理身份验证:

export http_proxy=http://<connector1-namespace>%2F<connector1-name>,<connector2-namespace>%2F<connector2-name>:<service-account-token>@<connector-proxy-address>
export https_proxy=http://<connector1-namespace>%2F<connector1-name>,<connector2-namespace>%2F<connector2-name>:<service-account-token>@<connector-proxy-address>
WARNING
  • %2F 是 Connector 命名空间/名称格式的 / 经过 URL 编码后的形式。
  • 指定多个 Connector 时,请使用逗号分隔。可列出的 Connector 数量没有严格限制,但应避免配置过多 Connector,以防请求标头过大及产生相关问题。

内置反向代理身份验证

对于反向代理模式,客户端直接连接到 Connector 的代理地址。身份验证令牌可以使用 Basic Auth 或 Bearer Token 方法提供,而 Connector 标识则通过 Connector Proxy 地址处理。

Basic Authentication
  • 用户名:任意值(会被忽略)
  • 密码:对 Connector 具有读取权限的 ServiceAccount 令牌

示例:

curl -u "user:sa-token-xxxxxxx" "http://c-github.default.svc.cluster.local/"
Bearer Token Authentication
  • Authorization 标头:Bearer <service-account-token>

示例:

curl -H "Authorization: Bearer sa-token-xxxxxxx" "http://c-github.default.svc.cluster.local/"

基于 Custom Rego 的身份验证

使用内置 HTTP 反向代理访问采用非标准身份验证方法的工具时,客户端可能无法使用标准 Basic Auth 或 Bearer Token 方法提供令牌。此时,客户端必须使用工具原生的凭证格式。

要支持这些自定义身份验证格式,可以使用 Rego 规则自定义从客户端请求中提取令牌的方式。这样,无论客户端以何种方式提供令牌,内置 HTTP 反向代理都可以提取并验证令牌。

例如:

spec:
  proxy:
    authExtractor:
      rego: |
        package proxy
        auth = {
          "token": input.request.headers["Private-Token"][0]
        }

此配置会从客户端请求中的 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:

# Using Bearer Token and service address format
curl -H "Authorization: Bearer sa-token-xxxxxxx" \
     "http://c-github.default.svc.cluster.local/"

# Using Basic Auth and path address format
curl -u ":sa-token-xxxxxxx" \
     "http://connector-proxy.example.com/namespaces/default/connectors/github"

代理会验证身份验证令牌,并在将请求转发到 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 规则定义自定义身份验证注入逻辑。例如:

spec:
  auth:
    types:
    - name: rego-auth
      secretType: Opaque
      generator:
        rego: |
          package proxy
          auth = {
            "position": "header",
            "auth": {
              "Private-Token": input.data.token
            }
          }

此配置会将 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 的读取权限。

参考资料

后续步骤