使用 OCI Connector 以无密钥方式部署工作负载
在 Kubernetes 集群中,从私有镜像仓库拉取镜像通常需要将仓库凭证分发到各个 namespace,这会增加凭证泄露的风险。
OCI Connector 通过充当仓库代理提供了一种 无密钥 方案。这样,用户无需在每个 namespace 中存储长期密码或 robot token,即可访问私有镜像仓库,从而最大程度地提升凭证安全性。
本指南演示如何使用 OCI Connector 部署需要从私有 OCI 镜像仓库拉取镜像的工作负载。OCI Connector 作为 Kubernetes 集群与 OCI registry 之间的反向代理,负责处理身份认证和镜像获取。
目录
功能概览前提条件概览操作步骤步骤 1:创建 Connector步骤 2:创建 ServiceAccount Token步骤 3:创建 Image Pull Secret步骤 4:为 ServiceAccount 绑定 Image Pull Secret步骤 5:部署工作负载步骤 6:验证 Pod 状态故障排查常见问题验证命令结论功能概览
使用 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 实现无缝、无凭证的镜像拉取。
概览
该过程包含以下几个关键步骤:
- 创建一个定义到 OCI registry 连接的 Connector 资源。
- 设置身份认证 Secret。
- 为内部认证创建一个 ServiceAccount token。
- 配置 image pull secret。
- 使用适当的注解部署工作负载。
操作步骤
步骤 1:创建 Connector
首先,为演示创建一个 namespace:
接下来,创建一个定义到 OCI registry 连接的 Connector 资源。该资源将管理身份认证和代理操作。
建议: 如果你的 OCI registry 支持,建议使用
robot account访问 registry,而不是admin账号。
说明:
Connector资源定义了连接参数,包括 registry 地址和身份认证方法Secret资源用于安全存储 registry 凭证connectorClassName: oci指定这是一个 OCI 类型的 connectortokenAuth身份认证方法用于基于令牌的身份认证
现在,我们已经在 oci-connector-demo namespace 中创建了一个 connector,且该 connector 的状态为 Ready。
步骤 2:创建 ServiceAccount Token
为 namespace 中的默认 ServiceAccount 生成一个 token:
该 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:
说明:
docker-server 指向集群中的 connector proxy service 地址,你可以从 connector 状态中获取该地址
docker-username设置为 "u"(占位用户名)docker-password使用上一步中的 Service Account tokendocker-email可以是任意有效的电子邮件地址(用于兼容 CNCF Distribution Registry)
步骤 4:为 ServiceAccount 绑定 Image Pull Secret
将 image pull secret 附加到 ServiceAccount,以便使用该 ServiceAccount 的 Pod 可以自动使用该 secret 拉取镜像。
说明:
- 此命令会将
oci-connector-secret添加到默认 ServiceAccount 的imagePullSecrets列表中 - 使用该 ServiceAccount 的任何 Pod 都会自动使用此 secret 拉取镜像
- 这样就无需在每个 Pod 定义中单独指定 secret
这样可确保任何使用该 ServiceAccount 的 Pod 都会自动使用该 secret 进行镜像拉取。
步骤 5:部署工作负载
创建一个工作负载(此示例中为 Pod),并添加必要的注解以使用 OCI connector。
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 地址。
然后,检查 Pod 是否正在运行,并已通过 connector proxy 成功拉取镜像:
预期输出:
故障排查
常见问题
-
Pod 卡在 ImagePullBackOff:
- 确保 connector 配置正确且正在运行。
- 验证 ServiceAccount token 是否有效且未过期。
- 确认 image pull secret 已正确绑定到 ServiceAccount。
-
身份认证失败:
- 检查
harbor-secret中的 registry 凭证。 - 确保 connector 地址可访问。
- 验证 repository 参数是否与你的实际 repository 匹配。
- 检查
-
Proxy 注入未生效:
- 确认存在
connectors.cpaas.io/proxy-inject: "true"label。 - 检查 connector 注解格式是否正确。
- 确保指定 namespace 中存在该 connector。
- 确认存在
验证命令
结论
至此,你已经完成了使用 OCI Connector 以无密钥方式部署工作负载的流程。该方法通过集中管理凭证并避免将敏感信息分发给单个工作负载,从而增强了安全性。