Alauda DevOps Connectors Docs
简体中文

快速开始

本文档将帮助您快速了解如何创建一个OCI Connector，并安全地访问容器注册中心，而无需直接处理凭据。

目录

介绍

适用场景

OCI（开放容器倡议）Connector提供了一种安全的方式来：

  • 访问容器注册中心（Docker Hub、Harbor等），而无需将凭据嵌入工作负载中
  • 中心化管理注册表身份验证信息
  • 使用代理机制安全地推动和拉取容器镜像
  • 配置容器工具与注册表代理一起使用

这种方法特别适用于：

  • 需要将镜像推送到私有注册中心的CI/CD管道
  • 需要安全共享注册表凭据的多团队环境
  • Kubernetes内的容器构建过程

预计阅读时间

15分钟

注意事项

  • OCI Connector使用CSI驱动程序集成以安全地注入注册表凭据。
  • 不同的容器工具（如Docker、Buildah等）可能需要特定配置以访问不安全的注册中心。
  • Connector生成的配置文件在30分钟后过期。

前提条件

  • 已安装Connectors系统的Kubernetes集群（Operator、Core和OCI组件）。有关安装这些组件的详细信息，请参见安装指南。
  • 已配置kubectl与您的集群通信
  • 容器注册中心的访问凭据（Docker Hub、Harbor等）
  • 基本的Kubernetes资源知识

流程概述

No.操作步骤描述
1创建命名空间为演示创建一个专用的命名空间
2创建注册表凭据和OCI Connector将Connector配置为指向一个容器注册中心
3配置RBAC权限授予使用Connector所需的适当权限
4创建容器构建/推送作业部署一个使用Connector与注册中心交互的作业
5验证操作检查注册操作是否成功完成

操作步骤

步骤1：创建命名空间

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

kubectl create ns oci-connector-demo

步骤2：创建注册表凭据和OCI Connector

创建一个包含注册表凭据的秘密和OCI Connector资源。有关创建和配置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

验证Connector是否处于“准备就绪”状态：

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

输出应显示：

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

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

创建一个ConfigMap并包含一个示例Dockerfile：

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

创建一个使用Connector构建和推送容器镜像的作业：

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/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连接器的名称
  • configuration.names：指定从OCI ConnectorClass生成哪个配置：
    • "docker-config"：生成进行任何注册操作所需的身份验证配置（config.json）
    • "buildkitd"：生成用于不安全注册访问的BuildKit守护进程配置
  • mountPath：指定配置文件在容器中挂载的位置：
    • "/root/.docker" 用于Docker身份验证配置
    • "/etc/buildkit" 用于BuildKit配置

步骤4：验证操作

检查作业的日志以确认镜像已成功构建并推送：

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

您应会看到构建过程完成及镜像被推送到注册中心。

预期结果

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

  1. OCI Connector处于“准备就绪”状态：

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

  2. 在作业日志中看到成功的镜像构建和推送操作，显示镜像通过连接器代理推送到注册中心。

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

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

工作原理

OCI Connector的工作原理如下：

  1. 创建一个代理服务，位于您的工作负载和容器注册中心之间
  2. 在请求通过代理时注入身份验证信息
  3. 为容器工具提供配置文件以与代理一起工作

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

  1. docker-config：创建一个config.json文件，包含必要的身份验证信息以访问代理服务

    {
  "auths": {
    "<proxy-address>": {
      "auth": "<auth-token>"
    }
  }
}

    该配置对于身份验证至关重要，是所有容器操作所需。

  2. buildkitd：创建一个buildkitd.toml文件，配置BuildKit信任不安全注册代理

    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

故障排除

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

  1. 连接器状态：确保连接器处于“准备就绪”状态：

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

  2. RBAC权限：验证RoleBinding是否配置正确。

  3. 注册访问：确认凭据具有对指定存储库的访问权限。

  4. 配置挂载：确保配置卷在作业中正确挂载。

  5. 代理地址：确保您在图像引用中使用了来自status.proxy.httpAddress.url的正确代理地址。

下一步

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

  • 在Kubernetes工作负载中使用连接器拉取私有镜像
  • 将连接器集成到CI/CD管道以构建和推送镜像
  • 配置不同的容器工具以与连接器一起使用
  • 使用连接器与不同的注册服务