Alauda DevOps Connectors Docs

ConnectorsProxy

Connectors Proxy is a core capability of the Connectors system that provides secure, secretless access to integrated tools. It typically operates as an HTTP service that can function as either a forward proxy or a reverse proxy for client applications.

When clients access tool resources through Connectors Proxy, the proxy automatically injects the necessary authentication credentials into requests, enabling seamless access without requiring clients to handle credentials directly. This approach delivers a significant security benefit:

  • Secretless Access: Eliminates the need to distribute tool credentials directly to clients by using short-lived tokens issued by Kubernetes. This prevents credential exposure in client environments such as logs or environment variables.

To accommodate diverse tool authentication requirements, the platform supports both built-in and custom proxy implementations. Each ConnectorClass can provide its own proxy service, offering flexibility to meet specific tool authentication needs.

TOC

Built-in Connectors Proxy

The built-in ConnectorsProxy implementation provides comprehensive HTTP/HTTPS protocol support with Basic Auth and Bearer Token authentication methods. It offers both forward proxy and reverse proxy capabilities.

Forward Proxy

Operates as a standard HTTP proxy using http_proxy and https_proxy environment variables. When the proxy receives client requests, it:

  1. Authenticates the client
  2. Injects tool credentials specified in the Connector into the request if current request path is pointing to the target tool specified by the Connector
  3. Forwards the authenticated request to the target tool
DANGER

Connectors Proxy does not support the CONNECT method for HTTP tunneling. Clients must send HTTP requests directly to the proxy server.

Reverse Proxy

Clients access tools by connecting directly to the Connector Proxy Address instead of the original tool URL. The proxy:

  1. Receives client requests at the proxy endpoint
  2. Performs client authentication
  3. Injects tool credentials specified in the Connector and forwards requests to the backend tool

Custom Connectors Proxy

For tools requiring specialized authentication mechanisms, custom proxy implementations can be developed. These proxies can be implemented as either forward or reverse proxies based on specific requirements.

Example: The OCI Connector uses a custom OCI Plugin Proxy that supports OCI protocol with Bearer Token authorization for registries like Harbor and Docker Registry.

User can develop a custom proxy server and specified in the connectorclass.

Connector Proxy Address

Each Connector has a unique proxy address for accessing tool resources. The proxy address is stored in the status.proxy.httpAddress field:

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

Clients use this proxy address to access resources within the tool specified by the Connector.

For more fields about connectorclass, please refer to ConnectorClass

Use with Connectors CSI Driver

Connectors Proxy works seamlessly with the Connectors CSI Driver to provide a complete secretless access solution:

  1. The Connectors CSI Driver mounts necessary configuration files that contains the proxy address and proxy authentication information
  2. Connectors Proxy handles authentication injection and request routing to target tool.
  3. Clients can access resources without credential management.

This integration is particularly useful in scenarios like:

  • Git clone operations in Kubernetes Jobs
  • Image push/pull operations in Tekton Pipelines
  • API access in custom workloads

For complete secretless access scenarios using Connectors Proxy and Connectors CSI Driver, see How to use the Git Connector to complete Git clone without storing credentials on the client

Deep Understanding of Connectors Proxy

Specifying Proxy in ConnectorClass

You can specify the proxy server to use in the ConnectorClass:

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

Connectors created from this ConnectorClass will use connectors-proxy-service as their real proxy server.

Built-in Proxy Configuration:

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

Custom Proxy Configuration:

Custom proxies can point to any address capable of handling proxy requests.

Connectors Proxy Authentication

When using Connectors Proxy, clients must provide proper authentication credentials to access the proxy. The authentication process requires two key elements:

  1. Connector Identification: Specify which connector to use for credential injection
  2. Authorization Token: Provide a ServiceAccount token with read permissions for the target Connector

The proxy server validates the provided ServiceAccount token to ensure it has the necessary permissions for the specified Connector before processing requests and injects the authentication credentials into the request when valid.

For detailed information about ServiceAccount tokens and RBAC configuration, see the Kubernetes Authentication documentation.

Built-in Forward Proxy Authentication

For forward proxy mode, authentication information is passed through the Proxy-Authorization header using HTTP Proxy Basic Authentication.

  • Username: <connector-namespace>/<connector-name>
  • Password: ServiceAccount token with read permissions for the Connector

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 Environment Example:

You can configure proxy authentication using standard HTTP proxy environment variables:

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>

Note: The %2F is the URL-encoded form of / in the connector namespace/name format.

Built-in Reverse Proxy Authentication

For reverse proxy mode, clients connect directly to the connector's proxy address. The authentication token can be provided using either Basic Auth or Bearer Token methods, while connector identification is handled through the connector proxy address.

Basic Authentication
  • Username: Any value (ignored)
  • Password: ServiceAccount token with read permissions for the Connector

Example:

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

Example:

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

Custom Rego-based Authentication

When using the built-in HTTP reverse proxy with tools that use non-standard authentication methods, clients may be unable to provide tokens using standard Basic Auth or Bearer Token methods. Instead, they must use the tool's original credential format.

To support these custom authentication formats, you can use Rego rules to customize token extraction from client requests. This allows the built-in HTTP reverse proxy to extract and validate tokens regardless of how they are provided by the client.

For example:

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

This configuration extracts the token from the Private-Token header in client requests, which the proxy then uses to validate client authentication.

This approach provides significant flexibility for non-standard HTTP authentication mechanisms. Client CLIs can provide Kubernetes tokens using the tool's original credential format, and the proxy extracts the token through Rego rules to complete authentication validation.

For more detailed configuration on using Rego rules to extract tokens, see ConnectorClass.

For more about injecting authentication credentials into backend request, see Injecting Authentication Credentials into Backend Request when using built-in Reverse Proxy.

Connector Identification

The connector can be identified through different proxy address formats:

  • Service Format: e.g. http://c-<connector-name>.<namespace>.svc.cluster.local
  • Path Format: http://<proxy-address>/namespaces/<connector-namespace>/connectors/<connector-name>

The connector proxy address is automatically generated by the system and is unique for each connector. You must retrieve the connector proxy address from the status.proxy.httpAddress field of the connector resource before using it.

Example:

For a github connector in the default namespace:

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

The proxy will validate the authentication token and automatically inject the default/github connector's authentication credentials when forwarding requests to GitHub services.

Injecting Authentication Credentials into Backend Request when using built-in Reverse Proxy

After the built-in reverse proxy validates the client request, it injects authentication credentials into the backend request based on the credential type configured in the Connector. The following injection methods are supported:

  • Basic Auth
  • Bearer Token
  • Custom Rego

Basic Auth

When a Connector is configured with the secret type kubernetes.io/basic-auth, the proxy injects the credentials into the backend request headers using Basic Authentication.

Bearer Token

When a Connector is configured with the secret type connectors.cpaas.io/bearer-token, the proxy injects the credentials into the backend request headers using Bearer Token authentication.

Custom Rego

In addition to the standard Basic Auth and Bearer Token methods, you can use Rego rules to define custom authentication injection logic. For example:

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

This configuration injects the token value from the connector's secret data into the Private-Token header of backend requests.

For more detailed configuration, see ConnectorClass.

When using custom Rego authentication, you typically need to configure spec.proxy.authExtractor to extract tokens from client requests, enabling the built-in HTTP reverse proxy to validate client authentication. Simultaneously, use spec.auth.types[].generator.rego to inject authentication credentials into backend requests. This combination enables support for custom authentication mechanisms when using the built-in HTTP reverse proxy.

References