Alauda DevOps Connectors Docs
  • 简体中文

    • ConnectorsProxy

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

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

    • 免密访问：通过使用 Kubernetes 签发的短期令牌，避免将工具凭证直接分发给客户端。这可以防止凭证暴露在客户端环境中，例如日志或环境变量。

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

    目录

    内置 Connectors Proxy正向代理反向代理自定义 Connectors ProxyConnector Proxy Address与 Connectors CSI Driver 配合使用深入理解 Connectors Proxy在 ConnectorClass 中指定 ProxyConnectors Proxy 认证内置正向代理认证内置反向代理认证基于 Rego 的自定义认证使用内置反向代理时将认证凭证注入后端请求Basic AuthBearer TokenCustom Rego参考资料

    内置 Connectors Proxy

    内置的 ConnectorsProxy 实现提供了完整的 HTTP/HTTPS 协议支持，并支持 Basic Auth 和 Bearer Token 认证方式。它同时具备正向代理和反向代理能力。

    正向代理

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

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

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

    反向代理

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

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

    自定义 Connectors Proxy

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

    示例：OCI Connector 使用自定义的 OCI Plugin Proxy，支持对 Harbor 和 CNCF Distribution Registry 等仓库的 OCI 协议及 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> # Namespace where Connector components are deployed

    自定义代理配置：

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

    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 请求头：

    # 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://<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 是 / 在 connector namespace/name 格式中的 URL 编码形式。

    内置反向代理认证

    在反向代理模式下，客户端直接连接到 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 请求头：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
    • Path 格式：http://<proxy-address>/namespaces/<connector-namespace>/connectors/<connector-name>

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

    示例：

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

    参考资料