简体中文

快速开始

本文档将帮助您快速了解如何创建 OCI Connector，并使用它安全访问容器镜像仓库，而无需直接处理凭据。

介绍

适用场景

OCI (Open Container Initiative) Connector 提供了一种安全的方式来：

访问容器镜像仓库（Docker Hub、Harbor 等），无需在工作负载中嵌入凭据
集中管理镜像仓库认证信息
通过代理机制安全地推送和拉取容器镜像
配置容器工具以配合镜像仓库代理使用

该方案特别适用于：

需要向私有仓库推送镜像的 CI/CD 流水线
多团队环境中需要安全共享仓库凭据的场景
Kubernetes 内的容器构建流程

预计阅读时间

15 分钟

注意事项

OCI connector 通过 CSI 驱动集成安全注入仓库凭据。
不同容器工具（Docker、Buildah 等）可能需要针对不安全仓库访问进行特定配置。
连接器生成的配置文件有效期为 30 分钟。

前提条件

已安装 Connectors 系统的 Kubernetes 集群（Operator、Core 和 OCI 组件）。详情请参见安装指南。
已配置 kubectl 可访问集群
容器镜像仓库的访问凭据（Docker Hub、Harbor 等）
具备 Kubernetes 资源的基础知识

流程概览

序号	操作步骤	说明
1	创建 Namespace	创建一个专用的命名空间用于演示
2	创建仓库凭据和 OCI Connector	配置连接器以连接容器镜像仓库
3	配置 RBAC 权限	授予使用连接器的相应权限
4	创建容器构建/推送 Job	部署一个使用连接器与仓库交互的 Job
5	验证操作	检查仓库操作是否成功完成

操作步骤

步骤 1：创建 Namespace

为本次演示创建一个专用命名空间：

kubectl create ns oci-connector-demo

步骤 2：创建仓库凭据和 OCI Connector

创建包含仓库凭据的 Secret 和 OCI Connector 资源。有关创建和配置连接器的详细信息，请参阅Connectors 快速开始指南。

cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Secret
metadata:
  name: registry-auth
  namespace: oci-connector-demo
type: cpaas.io/distribution-registry-token
stringData:
  username: your-username  # 替换为您的仓库用户名
  password: your-token     # 替换为您的仓库密码/令牌
---
apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: oci-connector
  namespace: oci-connector-demo
spec:
  connectorClassName: oci
  address: "https://index.docker.io"  # 替换为您的仓库地址
  auth:
    name: tokenAuth
    secretRef:
      name: registry-auth
EOF

确认连接器处于 "Ready" 状态：

kubectl get connector oci-connector -n oci-connector-demo

输出应显示：

NAME           CLASS   ADDRESS               READY   AGE
oci-connector  oci     https://index.docker.io True    1m

步骤 3：创建容器构建/推送 Job

创建包含示例 Dockerfile 的 ConfigMap：

cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: ConfigMap
metadata:
  name: dockerfile
  namespace: oci-connector-demo
data:
  Dockerfile: |
    FROM scratch
    LABEL maintainer="example@example.com"
    WORKDIR /app
    ENV APP_VERSION="1.0.0"
EOF

创建一个使用连接器构建并推送容器镜像的 Job：

cat <<EOF | kubectl apply -f -
apiVersion: batch/v1
kind: Job
metadata:
  name: image-build
  namespace: oci-connector-demo
spec:
  template:
    spec:
      restartPolicy: Never
      containers:
      - name: buildkit
        image: moby/buildkit:v0.11.0
        securityContext:
          privileged: true
        env:
        - name: BUILDKITD_FLAGS
          value: "--config /etc/buildkit/buildkitd.toml"
        command:
        - /bin/sh
        - -c
        args:
        - |
          set -ex
          buildctl-daemonless.sh \
          build \
          --progress=plain \
          --frontend=dockerfile.v0 \
          --local context=/workspace \
          --local dockerfile=/workspace \
          --output type=image,name=c-oci-connector.oci-connector-demo.svc.cluster.local/namespaces/oci-connector-demo/connectors/oci-connector/your-username/test-image:v1,push=true
        volumeMounts:
        - name: dockerfile
          mountPath: /workspace
        - name: docker-config
          mountPath: /root/.docker
        - name: buildkitd-config
          mountPath: /etc/buildkit
      volumes:
      - name: dockerfile
        configMap:
          name: dockerfile
      - name: docker-config
        csi:
          readOnly: true
          driver: connectors-csi
          volumeAttributes:
            connector.name: "oci-connector"
            configuration.names: "docker-config"
      - name: buildkitd-config
        csi:
          readOnly: true
          driver: connectors-csi
          volumeAttributes:
            connector.name: "oci-connector"
            configuration.names: "buildkitd"
EOF

卷定义中的关键参数：

connector.name：您的 OCI connector 名称
configuration.names：指定从 OCI ConnectorClass 生成的配置类型：
- "docker-config"：生成用于任何仓库操作的认证配置（config.json）
- "buildkitd"：生成用于不安全仓库访问的 BuildKit 守护进程配置
mountPath：指定配置文件在容器中的挂载路径：
- "/root/.docker" 用于 Docker 认证配置
- "/etc/buildkit" 用于 BuildKit 配置

步骤 4：验证操作

查看 Job 日志，确认镜像构建并推送成功：

kubectl logs -f job/image-build -n oci-connector-demo

您应看到构建过程完成，并且镜像已推送到仓库。

预期结果

完成所有步骤后，您将看到：

OCI connector 处于 "Ready" 状态：

NAME           CLASS   ADDRESS               READY   AGE
oci-connector  oci     https://index.docker.io True    5m

Job 日志中显示镜像构建和推送成功，表明镜像通过连接器代理推送到了仓库。

连接器状态字段中的代理地址：

status:
  proxy:
    httpAddress:
      url: http://c-oci-connector.oci-connector-demo.svc.cluster.local

工作原理

OCI Connector 的工作流程：

创建一个代理服务，位于您的工作负载和容器镜像仓库之间
请求通过代理时注入认证信息
提供容器工具使用的配置文件以配合代理工作

连接器生成三种类型的配置文件，分别用于不同目的：

docker-config：生成包含访问代理服务所需认证信息的 config.json 文件
```
{
  "auths": {
    "<proxy-address>": {
      "auth": "<auth-token>"
    }
  }
}
```
该配置是认证的关键，所有容器操作均需使用。
buildkitd：生成配置 BuildKit 信任不安全仓库代理的 buildkitd.toml 文件
```
insecure-entitlements = [ "network.host", "security.insecure" ]
[registry."<proxy-address>"]
  http = true
```
仅在使用 BuildKit 构建和推送镜像时需要。

查看生成的配置：

cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Pod
metadata:
  name: inspect-config
  namespace: oci-connector-demo
spec:
  containers:
  - name: inspector
    image: busybox
    command: ["sleep", "3600"]
    volumeMounts:
    - name: docker-config
      mountPath: /mnt/docker
  volumes:
  - name: docker-config
    csi:
      readOnly: true
      driver: connectors-csi
      volumeAttributes:
        connector.name: "oci-connector"
        configuration.names: "docker-config"
EOF

查看生成的配置内容：

kubectl exec -it inspect-config -n oci-connector-demo -- cat /mnt/docker/config.json

故障排查

如果容器操作失败，请检查以下内容：

连接器状态：确保连接器处于 "Ready" 状态：

kubectl describe connector oci-connector -n oci-connector-demo

RBAC 权限：确认 RoleBinding 配置正确。
仓库访问：确认凭据有权访问指定的仓库。
配置挂载：确保配置卷正确挂载到 Job 中。
代理地址：确保镜像引用中使用了 status.proxy.httpAddress.url 中的正确代理地址。

后续步骤

成功使用 OCI Connector 推送首个镜像后，您可以：

在 Kubernetes 工作负载中使用连接器拉取私有镜像
集成到 CI/CD 流水线中构建和推送镜像
配置不同容器工具配合连接器使用
将连接器用于不同的镜像仓库服务

Connector APIs

Operator APIs

快速开始

目录

介绍

适用场景

预计阅读时间

注意事项

前提条件

流程概览

操作步骤

步骤 1：创建 Namespace

步骤 2：创建仓库凭据和 OCI Connector

步骤 3：创建容器构建/推送 Job

步骤 4：验证操作

预期结果

工作原理

故障排查

后续步骤

Connector APIs

Operator APIs

#快速开始

#目录

#介绍

#适用场景

#预计阅读时间

#注意事项

#前提条件

#流程概览

#操作步骤

#步骤 1：创建 Namespace

#步骤 2：创建仓库凭据和 OCI Connector

#步骤 3：创建容器构建/推送 Job

#步骤 4：验证操作

#预期结果

#工作原理

#故障排查

#后续步骤

快速开始

目录

介绍

适用场景

预计阅读时间

注意事项

前提条件

流程概览

操作步骤

步骤 1：创建 Namespace

步骤 2：创建仓库凭据和 OCI Connector

步骤 3：创建容器构建/推送 Job

步骤 4：验证操作

预期结果

工作原理

故障排查

后续步骤