Kubeflow KFServing 使用私有 Harbor 仓库镜像的配置方法

在使用 Kubeflow KFServing 部署模型服务时，经常会遇到需要从私有 Harbor 镜像仓库拉取容器镜像的场景。本文将详细介绍如何正确配置 KFServing 以支持从私有 Harbor 仓库拉取镜像。

问题背景

当在 KFServing 的 InferenceService 配置中指定了私有 Harbor 仓库的镜像地址时，服务部署可能会失败，并出现类似以下的错误信息：

failed to pull and unpack image "harbor.example.com/repo/image:tag": 
pull access denied, repository does not exist or may require authorization: 
authorization failed: no basic auth credentials

这个错误表明 Kubernetes 集群没有正确的凭证来访问私有 Harbor 仓库。

解决方案

要解决这个问题，我们需要为 Kubernetes 集群配置访问私有 Harbor 仓库的凭证。以下是具体的配置步骤：

1. 创建 Docker 注册表 Secret

首先，我们需要创建一个包含 Harbor 仓库认证信息的 Kubernetes Secret：

apiVersion: v1
kind: Secret
metadata:
  name: harbor-credentials
  namespace: <your-namespace>
type: kubernetes.io/dockerconfigjson
data:
  .dockerconfigjson: <base64-encoded-docker-config>

其中，.dockerconfigjson 的值可以通过以下方式生成：

1. 创建 config.json 文件：

{
  "auths": {
    "harbor.example.com": {
      "username": "your-username",
      "password": "your-password",
      "auth": "base64-encoded-username:password"
    }
  }
}

2. 使用 base64 编码该文件：

cat config.json | base64

2. 在 InferenceService 中引用 Secret

在 InferenceService 的配置中，我们需要引用这个 Secret。对于 transformer 组件，配置如下：

apiVersion: serving.kserve.io/v1beta1
kind: InferenceService
metadata:
  name: my-model
spec:
  transformer:
    containers:
    - image: harbor.example.com/repo/image:tag
      name: kserve-container
    imagePullSecrets:
    - name: harbor-credentials

3. 验证配置

部署完成后，可以通过以下命令检查服务状态：

kubectl get pods -n <namespace>
kubectl describe pod <pod-name> -n <namespace>

如果配置正确，应该能看到容器成功拉取了镜像并正常运行。

最佳实践

1. 命名空间管理：建议在每个命名空间中都创建相应的 Secret，而不是使用默认命名空间的 Secret。

2. 权限控制：为不同的服务使用不同的 Harbor 账户，遵循最小权限原则。

3. Secret 更新：当 Harbor 密码变更时，记得更新对应的 Secret。

4. 安全考虑：确保 Secret 的访问权限受到严格控制，避免敏感信息泄露。

常见问题排查

如果仍然遇到镜像拉取失败的问题，可以检查以下几点：

1. Secret 是否创建在正确的命名空间
2. Secret 的名称是否与 InferenceService 中引用的名称一致
3. Harbor 仓库地址是否正确（包括协议头如 https://）
4. 网络连接是否正常，特别是跨网络的 Harbor 仓库访问
5. Harbor 仓库的证书是否被集群信任

通过以上配置，KFServing 就能够顺利地从私有 Harbor 仓库拉取所需的容器镜像，为模型服务提供完整的部署能力。这种配置方式不仅适用于 transformer 组件，也同样适用于 predictor 等其他组件。