#OCI Connector

The OCI Connector is a platform-agnostic connector that allows you to connect to any OCI Registry, such as Docker Hub, Harbor, etc. You can use the OCI Connector to securely access private OCI repositories in CI/CD pipelines or perform OCI operations in containerized workloads without providing credentials. Additionally, you can centrally manage OCI access configurations, avoiding the need to duplicate OCI credential configurations in each namespace.

This document will describe:

• Access requirements for OCI Registry
• How to create an OCI Connector based on the OCI Connector type
• The proxy and configuration capabilities of the OCI Connector

#OCI Registry Requirements

The OCI Registry to be accessed must meet the following conditions:

1. Interface implementation requirements:

   • Must implement at least the interfaces defined in the opencontainers/distribution-spec v1.0 specification
   • Must be able to pass the conformance tests of the distribution-spec

2. Authentication method requirements:

   • Must implement Token-based authentication and comply with the CNCF Distribution Token Authentication Specification

#Creating an OCI Connector Based on OCI Connector Type

Here's how to create a basic OCI Connector:

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: dockerhub-demo
spec:
  connectorClassName: oci
  address: https://index.docker.io
  auth:
    name: tokenAuth

#spec.connectorClassName

Use the constant value oci.

#description

You can add descriptive information to the OCI Connector through the annotations field.

• cpaas.io/description: Description of the OCI Connector.

For example:

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: dockerhub-demo
  annotations:
    cpaas.io/description: "Connect to Docker Hub for team public repository access"

#Address

The spec.address specifies the access address of the OCI Registry, for example: https://index.docker.io.

#Authentication

The OCI Connector supports the following authentication types:

• tokenAuth: Token-based authentication (optional)
  • Corresponding credential type: cpaas.io/distribution-registry-token, this type of credential is used for the authentication process defined in the CNCF Distribution Token Authentication Specification, and the credential must provide username and password information.

#Using Token-based Authentication

For example:

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: dockerhub-demo
spec:
  connectorClassName: oci
  address: https://index.docker.io
  # . . .
  auth:
    name: tokenAuth
    secretRef:
      name: oci-secret
---
apiVersion: v1
stringData:
  password: your-password
  username: your-username
kind: Secret
metadata:
  name: oci-secret
type: cpaas.io/distribution-registry-token

If the target OCI Registry does not require authentication, you can omit the authentication information. The configuration example is as follows:

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: dockerhub-demo
spec:
  connectorClassName: oci
  address: https://index.docker.io
  auth:
    name: tokenAuth

#Token Permissions Required

The required permissions for the configured token depend on how you intend to use it in your Pods/Pipelines.

For example:

• Image pull operations: If you only need to pull images using this connector, the token only require read permissions for the target repositories.
• Image pull and push operations: If you need to push images using this connector, the token must have both read and write permissions for the target repositories. In other words, the token should allow you to both pull from and push to the registry.

For security best practices, we recommend creating token with minimal required permissions. When additional privileges are needed, create separate Connectors with more privileged secret and use namespace isolation to control which users can access each Connector.

#Proxy and Configuration

To provide clients with the ability to access OCI repositories without credentials, the OCI Connector type offers a proxy server to automatically inject authentication information.

Clients with access to the connector can use this proxy server to access OCI repositories without configuring credentials on the client side.

To simplify usage, the OCI Connector type provides configuration information that can be mounted into Pods via CSI. In the Pod, when performing OCI operations, the proxy service can be automatically used to complete OCI operations.

#Proxy

#Proxy Address

When a Connector is created, the system will:

1. Automatically create a Service for the proxy.
2. Record the proxy address in the status.proxy.httpAddress field.

You can use this proxy address for image push and pull operations.

For example:

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: dockerhub-demo
  namespace: default
spec:
  address: https://index.docker.io
  auth:
    name: tokenAuth
    secretRef:
      name: dockerhub-demo
  connectorClassName: oci
status:
  conditions:
  # . . .
  proxy:
    httpAddress:
      url: http://c-dockerhub-demo.default.svc.cluster.local/namespaces/oci-connector-demo/connectors/oci-connector

#Forward Proxy

You can mount proxy information into Pods using CSI, and then use the proxy information through environment variables or configuration files.

volumes:
- name: proxyconfig
  csi:
    readOnly: true
    driver: connectors-csi
    volumeAttributes:
      connector.name: "harbor"

Then, before executing container operations, use the proxy information through environment variables or configuration files.

export http_proxy=$(cat /{mount-path}/http.proxy)
export https_proxy=$(cat /{mount-path}/https.proxy)
export HTTP_PROXY=$http_proxy
export HTTPS_PROXY=$https_proxy
export no_proxy=localhost,127.0.0.1
export NO_PROXY=$no_proxy
echo "Using proxy: http_proxy=$http_proxy, https_proxy=$https_proxy, no_proxy=$no_proxy"

#Reverse Proxy

When using a reverse proxy, you need to modify the target image address to the proxy address.

Example: index.docker.io/test/abc:v1 → c-dockerhub-demo.default.svc.cluster.local/namespaces/oci-connector-demo/connectors/oci-connector/test/abc:v1

and mount the credential configuration files into the Pod and configure the proxy address in insecure-registries.

The OCI Connector created based on the OCI Connector type provides the following configurations:

docker-config: Configuration credentials required by OCI CLI like buildkit, buildah.

• Provides the config.json configuration file.
• Contains the authentication information required to access the proxy.

For example:

// config.json

{
  "auths": {
      "<proxy address of the connector>": {
          "auth": "<authentication information required to access the connector proxy>"
      }
  }
}

buildkitd: Configuration information required by the BuildKit Daemon.

• Provides the buildkitd.toml configuration file.
• In the configuration file, the current connector will be set as insecure-registries by default.

For example:

insecure-entitlements = [ "network.host", "security.insecure" ]
[registry."<proxy address of the connector>"]
  http = true

You can mount this configuration information into Pods using connectors-csi, and combined with the proxy capability, achieve image push or pull operations in a secretless manner.

#More

• What is OCI Registry
• General Introduction to Using the OCI Connector Proxy in K8S Workload
• Building Images Using OCI Connector in K8S Job
• Building Images Using OCI Connector in Tekton Pipeline