1. 项目背景与核心需求
在企业级容器化部署场景中,私有镜像仓库的搭建与配置是保障应用交付安全性和效率的关键环节。最近在帮某金融客户部署K8s集群时,发现他们使用的Ubuntu 22.04系统默认采用containerd作为容器运行时,而内部Harbor仓库的配置文档大多基于Docker环境。这个实际需求促使我整理了这套containerd对接Harbor的完整方案。
相比Docker使用daemon.json的配置方式,containerd需要通过修改config.toml文件实现仓库认证,这对很多刚接触容器生态的运维人员来说是个技术盲区。特别是在金融、政务等安全要求严格的行业,内网私有仓库的配置不仅要考虑连通性,还需要处理证书信任链、认证信息加密存储等细节问题。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 基础环境准备
2.1 系统与软件版本确认
首先通过以下命令验证基础环境:
bash复制# 查看系统版本
lsb_release -a
# 输出应包含:Description: Ubuntu 22.04 LTS
# 检查containerd版本
containerd --version
# 典型输出:containerd containerd.io 1.6.8-0ubuntu1
注意:如果系统预装的是snap版本的containerd,建议卸载后改用apt安装:
bash复制sudo snap remove containerd
sudo apt update && sudo apt install -y containerd.io
2.2 Harbor仓库信息收集
需要提前准备以下Harbor信息:
- 仓库地址(如:harbor.example.com)
- 项目名称(如:library)
- 登录凭证(用户名/密码)
- CA证书(如果是自签名证书)
通过curl测试仓库连通性:
bash复制curl -k https://harbor.example.com/api/v2.0/ping
# 正常应返回:{"message":"success"}
3. containerd核心配置解析
3.1 配置文件定位与结构
containerd的主配置文件默认位于:
bash复制sudo vi /etc/containerd/config.toml
典型配置文件结构包含以下关键section:
toml复制[plugins]
[plugins."io.containerd.grpc.v1.cri"]
[plugins."io.containerd.grpc.v1.cri".registry]
[plugins."io.containerd.grpc.v1.cri".registry.mirrors]
[plugins."io.containerd.grpc.v1.cri".registry.configs]
3.2 私有仓库镜像配置
在[registry.mirrors]下添加Harbor仓库镜像:
toml复制[plugins."io.containerd.grpc.v1.cri".registry.mirrors]
[plugins."io.containerd.grpc.v1.cri".registry.mirrors."harbor.example.com"]
endpoint = ["https://harbor.example.com"]
3.3 认证信息配置
在[registry.configs]中添加认证信息:
toml复制[plugins."io.containerd.grpc.v1.cri".registry.configs]
[plugins."io.containerd.grpc.v1.cri".registry.configs."harbor.example.com".auth]
username = "admin"
password = "Harbor12345"
安全提示:建议将密码存储在系统中,通过credential helper引用:
bash复制sudo apt install -y pass
echo "Harbor12345" | pass insert -e harbor-pwd
然后在config.toml中改为:
toml复制password = "@pass:harbor-pwd"
4. TLS证书配置
4.1 自签名证书处理
对于自签名证书,需要将CA证书放入系统信任链:
bash复制sudo cp harbor-ca.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates
验证证书安装:
bash复制openssl s_client -connect harbor.example.com:443 -CAfile /etc/ssl/certs/ca-certificates.crt
4.2 containerd证书配置
在config.toml中添加证书路径:
toml复制[plugins."io.containerd.grpc.v1.cri".registry.configs."harbor.example.com".tls]
ca_file = "/etc/ssl/certs/harbor-ca.pem"
insecure_skip_verify = false
5. 服务重启与验证
5.1 配置生效
重新加载containerd配置:
bash复制sudo systemctl restart containerd
sudo systemctl status containerd
5.2 镜像操作验证
使用ctr命令测试镜像拉取:
bash复制sudo ctr images pull --user admin:Harbor12345 harbor.example.com/library/nginx:latest
sudo ctr images list | grep nginx
6. 常见问题排查
6.1 证书验证失败
错误现象:
code复制x509: certificate signed by unknown authority
解决方案:
- 确认CA证书路径正确
- 检查证书有效期:
openssl x509 -in harbor-ca.crt -noout -dates - 重新加载证书:
sudo update-ca-certificates --fresh
6.2 认证失败
错误现象:
code复制failed to resolve reference: unauthorized: authentication required
检查步骤:
- 确认config.toml中auth配置格式正确
- 测试直接使用curl认证:
bash复制
curl -u admin:Harbor12345 https://harbor.example.com/v2/_catalog - 检查Harbor用户权限
6.3 网络连通性问题
诊断命令:
bash复制# 测试基础连通性
telnet harbor.example.com 443
# 检查DNS解析
nslookup harbor.example.com
# 查看防火墙规则
sudo iptables -L -n | grep 443
7. 高级配置技巧
7.1 多项目仓库配置
对于多租户场景,可以为不同项目配置独立认证:
toml复制[plugins."io.containerd.grpc.v1.cri".registry.configs]
[plugins."io.containerd.grpc.v1.cri".registry.configs."harbor.example.com/project1".auth]
username = "project1-user"
password = "xxxxxx"
[plugins."io.containerd.grpc.v1.cri".registry.configs."harbor.example.com/project2".auth]
username = "project2-user"
password = "xxxxxx"
7.2 镜像缓存策略优化
在[plugins."io.containerd.grpc.v1.cri".registry]下添加:
toml复制[plugins."io.containerd.grpc.v1.cri".registry]
[plugins."io.containerd.grpc.v1.cri".registry.mirrors]
[plugins."io.containerd.grpc.v1.cri".registry.mirrors."harbor.example.com"]
endpoint = ["https://harbor.example.com"]
[plugins."io.containerd.grpc.v1.cri".registry.mirrors."harbor.example.com".rewrite]
"^library/(.*)": "cache/$1"
7.3 配置自动生成脚本
对于大规模部署,可以使用以下脚本自动生成配置:
bash复制#!/bin/bash
HARBOR_URL="harbor.example.com"
USERNAME="admin"
PASSWORD=$(pass show harbor-pwd)
cat <<EOF | sudo tee /etc/containerd/config.toml
[plugins]
[plugins."io.containerd.grpc.v1.cri"]
[plugins."io.containerd.grpc.v1.cri".registry]
[plugins."io.containerd.grpc.v1.cri".registry.mirrors]
[plugins."io.containerd.grpc.v1.cri".registry.mirrors."${HARBOR_URL}"]
endpoint = ["https://${HARBOR_URL}"]
[plugins."io.containerd.grpc.v1.cri".registry.configs]
[plugins."io.containerd.grpc.v1.cri".registry.configs."${HARBOR_URL}".auth]
username = "${USERNAME}"
password = "${PASSWORD}"
EOF
8. 性能调优建议
8.1 连接池配置
在config.toml的[plugins."io.containerd.grpc.v1.cri".registry]段添加:
toml复制[plugins."io.containerd.grpc.v1.cri".registry]
[plugins."io.containerd.grpc.v1.cri".registry.configs."harbor.example.com".tls]
max_idle_conns = 100
idle_conn_timeout = "90s"
8.2 并行下载优化
调整containerd的下载并发度:
toml复制[plugins]
[plugins."io.containerd.grpc.v1.cri"]
max_concurrent_downloads = 10
8.3 镜像层缓存清理
设置自动垃圾回收:
toml复制[plugins]
[plugins."io.containerd.internal.v1.opt"]
path = "/var/lib/containerd/opt"
[plugins."io.containerd.internal.v1.restart"]
interval = "24h"
9. 安全加固措施
9.1 认证信息加密
使用containerd的secret store功能:
bash复制sudo mkdir -p /etc/containerd/secrets
echo "Harbor12345" | sudo tee /etc/containerd/secrets/harbor-pwd
sudo chmod 600 /etc/containerd/secrets/harbor-pwd
然后在config.toml中引用:
toml复制password = "/etc/containerd/secrets/harbor-pwd"
9.2 审计日志配置
启用containerd的完整操作日志:
toml复制[debug]
level = "info"
[debug.containerd]
filters = ["*"]
9.3 网络策略限制
通过iptables限制containerd只允许访问Harbor仓库:
bash复制sudo iptables -A OUTPUT -p tcp -m owner --uid-owner containerd -d harbor.example.com --dport 443 -j ACCEPT
sudo iptables -A OUTPUT -p tcp -m owner --uid-owner containerd -j REJECT
