使用 OCI Connector 以无密钥方式部署工作负载

在 Kubernetes 集群中,从私有镜像仓库拉取镜像通常需要将仓库凭证分发到各个 namespace,这会增加凭证泄露的风险。

OCI Connector 通过充当仓库代理提供了一种 无密钥 方案。这样,用户无需在每个 namespace 中存储长期密码或 robot token,即可访问私有镜像仓库,从而最大程度地提升凭证安全性。

本指南演示如何使用 OCI Connector 部署需要从私有 OCI 镜像仓库拉取镜像的工作负载。OCI Connector 作为 Kubernetes 集群与 OCI registry 之间的反向代理,负责处理身份认证和镜像获取。

功能概览

使用 OCI Connector 部署工作负载时,请注意以下关键点:

  • 要在 Kubernetes runtime 中通过 OCI Connector proxy 启用镜像拉取,必须通过 NodePort 或 Ingress 暴露 oci 组件的 service,并通过 ConnectorsConfig 中的 spec.components.oci.spec.expose 进行配置。完整配置请参见 将 OCI Proxy 暴露到集群外部。
  • 工作负载中指定的镜像地址会自动重写为指向 OCI Connector proxy。由于 proxy 使用 HTTP,因此必须将 runtime 配置为允许不安全的 registry。
  • OCI Connector 作为 OCI registry 的反向代理,代表你的工作负载处理身份认证和镜像拉取。
  • OCI Connector proxy 使用 service account token 对客户端进行身份认证,确保只有已授权的工作负载才能访问指定的 connector。

前提条件

  • 已安装 Connectors system: 已安装 Connectors Operator,且其 ConnectorsConfig 已调和为 Ready。必须启用 core 和 oci 组件。详情请参见 安装指南。
  • OCI 组件已对外暴露(NodePort 或 Ingress): 在 ConnectorsConfig 中配置 spec.components.oci.spec.expose,将 OCI Connector proxy 暴露到集群外部。请参见 将 OCI Proxy 暴露到集群外部。
  • 可访问私有 OCI registry: 你必须拥有目标 registry 的有效凭证和访问权限。
  • 已配置 kubectl: 确保已安装 kubectl,并已正确配置为可访问你的集群。
  • 已启用特性开关: 在 ConnectorsConfig 上设置 spec.components.core.spec.featureFlags.enable-pod-image-pull-via-connector: "true"。默认情况下此能力处于禁用状态;详情请参见 Feature Flags。

借助 OCI Connector,你可以在 Kubernetes 集群中安全地从私有 registry 拉取镜像,而无需在客户端保存凭证。这种方式可确保敏感凭证集中管理,并且不会暴露给单个工作负载或用户。

OCI Connector 通过一个安全、集中式的服务代理身份认证和镜像请求,为 Pod 实现无缝、无凭证的镜像拉取。

概览

该过程包含以下几个关键步骤:

  1. 创建一个定义到 OCI registry 连接的 Connector 资源。
  2. 设置身份认证 Secret。
  3. 为内部认证创建一个 ServiceAccount token。
  4. 配置 image pull secret。
  5. 使用适当的注解部署工作负载。

操作步骤

步骤 1:创建 Connector

首先,为演示创建一个 namespace:

kubectl create namespace oci-connector-demo

接下来,创建一个定义到 OCI registry 连接的 Connector 资源。该资源将管理身份认证和代理操作。

kubectl apply -n oci-connector-demo -f - <<'EOF'
apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: harbor
spec:
  address: https://harbor.example.com # Replace with your OCI registry address
  auth:
    name: tokenAuth
    secretRef:
      name: harbor-secret
  connectorClassName: oci
---
apiVersion: v1
stringData: # Replace with actual authentication information
  password: robotsecret
  username: robot$demo
kind: Secret
metadata:
  name: harbor-secret
type: cpaas.io/distribution-registry-token
EOF

建议: 如果你的 OCI registry 支持,建议使用 robot account 访问 registry,而不是 admin 账号。

说明:

  • Connector 资源定义了连接参数,包括 registry 地址和身份认证方法
  • Secret 资源用于安全存储 registry 凭证
  • connectorClassName: oci 指定这是一个 OCI 类型的 connector
  • tokenAuth 身份认证方法用于基于令牌的身份认证

现在,我们已经在 oci-connector-demo namespace 中创建了一个 connector,且该 connector 的状态为 Ready。

$ kubectl get connector.connectors -n oci-connector-demo
NAME     CLASS   ADDRESS                      READY   REASON   AGE
harbor   oci     https://harbor.example.com   True             30s

步骤 2:创建 ServiceAccount Token

为 namespace 中的默认 ServiceAccount 生成一个 token:

$ kubectl create token default -n oci-connector-demo
eyJhbGciOiJSUzI1NiIsImtpZCI6xxxximJ0VNVV_GblYvYy3dg...

该 token 将用于通过 connector proxy 拉取镜像。任何具有访问 connector 权限的 ServiceAccount 都可以作为 Pod 的 pull secret 使用。 有关 Connector 资源权限的更多信息,请参见 Connector Scope Permissions。

说明:

  • 该 token 将用于对发往 connector proxy 的请求进行身份认证
  • 该 token 的作用域限定为特定的 namespace(oci-connector-demo)
  • 请安全保存该 token,因为下一步将使用它

注意: ServiceAccount token 有过期时间(默认:1 小时)。你可以使用 --duration 标志延长其过期时间。更多详情请参见 Kubernetes documentation。

步骤 3:创建 Image Pull Secret

使用 ServiceAccount token 创建一个 registry secret:

kubectl create secret docker-registry oci-connector-secret \
  --docker-server="192.168.x.x:31567" \
  --docker-username="u" \
  --docker-password="eyJhbGciOiJSUzI1NiIsImtpZCI6xxxximJ0VNVV_GblYvYy3dg" \
  --docker-email=xxx@xxxx \
  --namespace=oci-connector-demo

说明:

docker-server 指向集群中的 connector proxy service 地址,你可以从 connector 状态中获取该地址

$ kubectl get connectors.connector harbor -n oci-connector-demo -o jsonpath='{.status.proxy.httpAddress.url}'
http://192.168.x.x:31567/namespaces/oci-connector-demo/connectors/harbor
  • docker-username 设置为 "u"(占位用户名)
  • docker-password 使用上一步中的 Service Account token
  • docker-email 可以是任意有效的电子邮件地址(用于兼容 CNCF Distribution Registry)

步骤 4:为 ServiceAccount 绑定 Image Pull Secret

将 image pull secret 附加到 ServiceAccount,以便使用该 ServiceAccount 的 Pod 可以自动使用该 secret 拉取镜像。

kubectl patch serviceaccount default -n oci-connector-demo -p "{\"imagePullSecrets\": [{\"name\": \"oci-connector-secret\"}]}"

说明:

  • 此命令会将 oci-connector-secret 添加到默认 ServiceAccount 的 imagePullSecrets 列表中
  • 使用该 ServiceAccount 的任何 Pod 都会自动使用此 secret 拉取镜像
  • 这样就无需在每个 Pod 定义中单独指定 secret

这样可确保任何使用该 ServiceAccount 的 Pod 都会自动使用该 secret 进行镜像拉取。

步骤 5:部署工作负载

创建一个工作负载(此示例中为 Pod),并添加必要的注解以使用 OCI connector。

kubectl apply -n oci-connector-demo -f - <<EOF
apiVersion: v1
kind: Pod
metadata:
  name: oci-connector-pod
  annotations:
    connectors.cpaas.io/connector: oci-connector-demo/harbor
  labels:
    connectors.cpaas.io/proxy-inject: "true"
spec:
  containers:
    - name: oci-connector-container
      image: harbor.example.com/oci-connector-demo:v1
  serviceAccountName: default
EOF
  • connectors.cpaas.io/connector 注解指定要使用的 connector(namespace/connector-name)。
  • connectors.cpaas.io/proxy-inject: "true" label 启用该 Pod 的 proxy 注入。
  • image 字段应指定原始镜像地址。
  • serviceAccountName: default 确保 Pod 使用带有 image pull secret 的 ServiceAccount。

步骤 6:验证 Pod 状态

Pod 创建后,你可以看到 Pod 中的镜像地址已被重写为 connector proxy 地址。

$ kubectl get pod oci-connector-pod -n oci-connector-demo -o jsonpath='{.spec.containers[0].image}'
# Example output:
# 192.168.x.x:31567/namespaces/oci-connector-demo/connectors/harbor/oci-connector-demo:v1

然后,检查 Pod 是否正在运行,并已通过 connector proxy 成功拉取镜像:

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

预期输出:

NAME                  READY   STATUS    RESTARTS   AGE
oci-connector-pod     1/1     Running   0          2m

故障排查

常见问题

  1. Pod 卡在 ImagePullBackOff:

    • 确保 connector 配置正确且正在运行。
    • 验证 ServiceAccount token 是否有效且未过期。
    • 确认 image pull secret 已正确绑定到 ServiceAccount。
  2. 身份认证失败:

    • 检查 harbor-secret 中的 registry 凭证。
    • 确保 connector 地址可访问。
    • 验证 repository 参数是否与你的实际 repository 匹配。
  3. Proxy 注入未生效:

    • 确认存在 connectors.cpaas.io/proxy-inject: "true" label。
    • 检查 connector 注解格式是否正确。
    • 确保指定 namespace 中存在该 connector。

验证命令

# Check connector status
kubectl get connector.connectors harbor -n oci-connector-demo

# Verify secret exists
kubectl get secret oci-connector-secret -n oci-connector-demo

# Check ServiceAccount configuration
kubectl get serviceaccount default -n oci-connector-demo -o yaml

# View pod events for troubleshooting
kubectl describe pod oci-connector-pod -n oci-connector-demo

结论

至此,你已经完成了使用 OCI Connector 以无密钥方式部署工作负载的流程。该方法通过集中管理凭证并避免将敏感信息分发给单个工作负载,从而增强了安全性。