#ConnectorsProxy

Connectors Proxy 是 Connectors 系统的核心能力，提供对集成工具的安全无秘访问。它通常作为一个 HTTP 服务运行，可以作为客户端应用的正向代理或反向代理。

当客户端通过 Connectors Proxy 访问工具资源时，代理会自动将所需的认证凭证注入请求中，实现无缝访问，无需客户端直接处理凭证。这种方式带来了显著的安全优势：

• 无秘访问：通过 Kubernetes 签发的短期令牌，消除直接向客户端分发工具凭证的需求，防止凭证在客户端环境（如日志或环境变量）中暴露。

为了满足不同工具的认证需求，平台支持内置和自定义代理实现。每个 ConnectorClass 可以提供自己的代理服务，灵活满足特定工具的认证需求。

#内置 Connectors Proxy

内置的 ConnectorsProxy 实现支持完整的 HTTP/HTTPS 协议，支持 Basic Auth 和 Bearer Token 认证方式，具备正向代理和反向代理功能。

#正向代理

作为标准 HTTP 代理，使用 http_proxy 和 https_proxy 环境变量。当代理接收到客户端请求时，会：

1. 验证客户端身份
2. 如果当前请求路径指向 Connector 指定的目标工具，则注入 Connector 中指定的工具凭证
3. 将认证后的请求转发到目标工具

#反向代理

客户端通过直接连接 Connector 代理地址而非原始工具 URL 来访问工具。代理会：

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

#自定义 Connectors Proxy

对于需要特殊认证机制的工具，可以开发自定义代理实现。根据具体需求，这些代理可以作为正向代理或反向代理实现。

示例：OCI Connector 使用自定义的 OCI 插件代理，支持 Harbor 和 CNCF Distribution Registry 等注册表的 OCI 协议和 Bearer Token 授权。

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

#Connector 代理地址

每个 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 Job 中的 Git 克隆操作
• Tekton Pipelines 中的镜像推送/拉取操作
• 自定义工作负载中的 API 访问

有关使用 Connectors Proxy 和 Connectors CSI Driver 实现完整无秘访问场景，请参见 如何使用 Git Connector 完成无凭证存储的 Git 克隆

#深入理解 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 创建的 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 具有必要权限，验证通过后注入认证凭证到请求中。

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

#内置正向代理认证

正向代理模式下，认证信息通过 Proxy-Authorization 头使用 HTTP Proxy Basic Authentication 传递。

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

Proxy-Authorization 头示例：

# 凭证格式：<connector-namespace>/<connector-name>:<service-account-token>
# 示例：default/github:sa-token-xxxxxxx
Proxy-Authorization: Basic <base64-encoded-credentials>

HTTP 代理环境变量示例：

可以使用标准 HTTP 代理环境变量配置代理认证：

export http_proxy=http://<connector-namespace>%2F<connector-name>:<service-account-token>@<connector-proxy-address>
export https_proxy=http://<connector-namespace>%2F<connector-name>:<service-account-token>@<connector-proxy-address>

注意：%2F 是命名空间/名称格式中 / 的 URL 编码形式。

#内置反向代理认证

反向代理模式下，客户端直接连接到 Connector 的代理地址。认证令牌可以通过 Basic Auth 或 Bearer Token 方式提供，Connector 标识通过代理地址处理。

#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/"

#自定义基于 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 代理地址由系统自动生成，且每个 Connector 唯一。使用前 必须 从 Connector 资源的 status.proxy.httpAddress 字段获取代理地址。

示例：

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

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

# 使用 Basic Auth 和路径地址格式
curl -u ":sa-token-xxxxxxx" \
     "http://connector-proxy.example.com/namespaces/default/connectors/github"

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

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 反向代理时的自定义认证机制。

#参考资料

• Kubernetes Authentication documentation