#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. 将经过身份验证的请求转发到目标工具

#正向代理凭证注入目标

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

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

当未配置 addressExtensions 时，仅 spec.address 有资格。 更改这些地址需要有权限更新 Connector 本身，因此该能力不会形成新的凭证所有权边界。

#反向代理

客户端通过连接到 Connector Proxy Address，而不是原始工具 URL 来访问工具。代理会：

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

#自定义 Connectors Proxy

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

示例：OCI Connector 使用自定义的 OCI Plugin Proxy，该代理支持 OCI 协议，并为 Harbor 和 CNCF Distribution Registry 等 registry 提供 Bearer Token 授权。。

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

#Connector Proxy Address

每个 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 中的镜像 push/pull 操作
• 自定义工作负载中的 API 访问

如需了解使用 Connectors Proxy 和 Connectors CSI Driver 的完整无凭证访问场景，请参见 如何使用 Git Connector 完成 Git clone 而不在客户端存储凭证

#深入理解 Connectors Proxy

#在 ConnectorClass 中指定 Proxy

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

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

由该 ConnectorClass 创建的 Connectors 将使用 connectors-proxy-service 作为其真实代理服务器。

内置代理配置：

ref:
  kind: Service
  name: connectors-proxy-service
  namespace: <connector-namespace> # 部署 Connector 组件的命名空间

自定义代理配置：

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

#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 Permission Model。

关于 ServiceAccount 令牌和 RBAC 配置的详细信息，请参见 Kubernetes Authentication documentation。

#内置正向代理身份验证

对于正向代理模式，身份验证信息通过 Proxy-Authorization header 使用 HTTP Proxy Basic Authentication 传递。

• 用户名：<connector-namespace>/<connector-name>
• 密码：对该 Connector 具有读取权限的 ServiceAccount 令牌

Proxy-Authorization Header：

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

HTTP Proxy 环境变量示例：

您可以使用标准 HTTP proxy 环境变量来配置代理身份验证：

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>

#内置反向代理身份验证

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

#Basic Authentication

• 用户名：任意值（会被忽略）
• 密码：对该 Connector 具有读取权限的 ServiceAccount 令牌

示例：

curl -u "user:sa-token-xxxxxxx" "http://c-github.default.svc.cluster.local/"

#Bearer Token Authentication

• Authorization Header：Bearer <service-account-token>

示例：

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

#基于 Rego 的自定义身份验证

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

为了支持这些自定义身份验证格式，您可以使用 Rego 规则来自定义从客户端请求中提取令牌的方式。这样，内置 HTTP 反向代理就可以无论客户端如何提供令牌，都能提取并验证它们。

例如：

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

此配置会从客户端请求中的 Private-Token header 提取令牌，然后由代理使用该令牌来验证客户端身份。

这种方式为非标准 HTTP 身份验证机制提供了很高的灵活性。客户端 CLI 可以使用工具原始的凭证格式提供 Kubernetes 令牌，而代理则通过 Rego 规则提取令牌并完成身份验证验证。

关于使用 Rego 规则提取令牌的更详细配置，请参见 ConnectorClass。

关于在使用内置反向代理时将身份验证凭证注入后端请求的更多信息，请参见 使用内置反向代理时将身份验证凭证注入后端请求。

#Connector 标识

可以通过不同的代理地址格式来标识 Connector：

• Service 格式：例如 http://c-<connector-name>.<namespace>.svc.cluster.local
• Path 格式：http://<proxy-address>/namespaces/<connector-namespace>/connectors/<connector-name>

Connector proxy address 由系统自动生成，并且对每个 Connector 都是唯一的。使用前，您必须先从 connector 资源的 status.proxy.httpAddress 字段中获取该地址。

示例：

对于 default 命名空间中的 github Connector：

# 使用 Bearer Token 和 service 地址格式
curl -H "Authorization: Bearer sa-token-xxxxxxx" \
     "http://c-github.default.svc.cluster.local/"

# 使用 Basic Auth 和 path 地址格式
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 type kubernetes.io/basic-auth 时，代理会使用 Basic Authentication 将凭证注入到后端请求 header 中。

#Bearer Token

当 Connector 配置了 secret type connectors.cpaas.io/bearer-token 时，代理会使用 Bearer Token 身份验证将凭证注入到后端请求 header 中。

#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 header 中。

更多详细配置，请参见 ConnectorClass。

在使用自定义 Rego 身份验证时，通常需要配置 spec.proxy.authExtractor，以便从客户端请求中提取令牌，从而让内置 HTTP 反向代理能够验证客户端身份。 同时，使用 spec.auth.types[].generator.rego 将身份验证凭证注入后端请求中。 这种组合使得在使用内置 HTTP 反向代理时能够支持自定义身份验证机制。

#参考

• Kubernetes Authentication documentation

#后续步骤

• Connectors Permission Model
• Connectors Approval & Permission Gating
• Connectors CSI Driver