腾讯云轻量服务器折腾 K3s 实录 (续)：ArgoCD 部署避坑指南

上回说到我们在腾讯云的 4G 轻量服务器上成功把 K3s 跑起来了，并打通了外网 kubectl 的直连。

今天这篇，我们继续推进，实战部署 GitOps 的核心控制面 ------ ArgoCD。

本以为有了 K8s 集群，装个 ArgoCD 只是 kubectl apply 一把梭的事，结果依然是"步步惊心"。这里把遇到的两个巨坑和终极解法记录下来。

坑一：ArgoCD CRD 文件过大导致 Annotation 溢出报错

按照官方文档，我们满心欢喜地敲下安装命令：

bash 复制代码

kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

结果终端直接糊了一长串红字：

The CustomResourceDefinition "applicationsets.argoproj.io" is invalid: metadata.annotations: Too long: may not be more than 262144 bytes

原因分析：

K8s 默认的 kubectl apply 使用的是 Client-Side Apply (客户端应用) 模式。它会非常实诚地把你整个 YAML 文件的内容塞进这个对象的 last-applied-configuration 注解 (Annotation) 里。

偏偏 ArgoCD 的核心 CRD（比如 ApplicationSet）的声明文件巨大无比，轻轻松松突破了 K8s 注解长度 256KB 的硬性限制，直接被 API Server 拒收了。

终极解法：使用 Server-Side Apply

既然客户端算不过来，就把合并的压力丢给服务端。只需要在命令里加一个 --server-side 参数，让 K8s 的 API Server 自己去处理状态合并：

bash 复制代码

kubectl apply --server-side -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

敲下这行命令，看着屏幕刷刷刷地输出 serverside-applied，简直强迫症福音。

坑二：国内网络拉取沙盒镜像 (Pause) 失败导致 Pod 卡死

资源对象虽然建好了，但我通过 kubectl get pods -n argocd 一看，所有的 Pod 像木头一样死死卡在 ContainerCreating 状态，十几分钟一动不动。

用 describe 命令深挖日志，发现了老熟人：

Failed to pull image "rancher/mirrored-pause:3.6"... dial tcp 162.125.x.x:443: connect: connection refused

原因分析：

这是国内云主机的通病。K3s/K8s 在启动任何 Pod 之前，都需要先从 Docker Hub 拉取基础的沙盒镜像（pause 镜像）。但目前国内直连 registry-1.docker.io 基本被掐断，连最底层的环境都初始化不了，业务镜像更是没戏。

终极解法：给 K3s 配置国内容器镜像加速器

注意，K3s 底层用的是 containerd，而不是 Docker，所以不要去改 /etc/docker/daemon.json。

你需要登录到服务器上，直接修改 K3s 的镜像配置表：

bash 复制代码

# 写入国内镜像加速源 (例如 DaoCloud, 南大源等)
cat << 'EOF' | sudo tee /etc/rancher/k3s/registries.yaml
mirrors:
  docker.io:
    endpoint:
      - "https://docker.m.daocloud.io"
      - "https://docker.nju.edu.cn"
      - "https://registry.docker-cn.com"
EOF

# 重启 K3s 让配置生效
sudo systemctl restart k3s

K3s 重启速度极快（通常不到两秒）。重启完成后，被卡住的 Pod 就像久旱逢甘霖一样，瞬间开始拉取镜像，状态全部变为 Running。

收尾与效果验证

当所有 Pod 都跑起来后，为了方便在外面通过浏览器直接访问 ArgoCD 的炫酷界面，我们直接把它原本内部的 ClusterIP 服务改成 NodePort，并固定映射到 30080 端口：

bash 复制代码

# 暴露 NodePort
kubectl patch svc argocd-server -n argocd -p '{"spec": {"type": "NodePort", "ports": [{"port": 443, "nodePort": 30080}]}}'

# 窃取初始的超级管理员密码
kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d; echo

最后，记得去腾讯云控制台的安全组里把 TCP 30080 端口放通。

打开浏览器，访问 https://你的公网IP:30080（忽略证书警告），输入 admin 和刚拿到的密码。看到 ArgoCD 后台界面的那一刻，所有的折腾都值了！

下一篇，我们将继续向这台 4G 战舰里塞入 Kong 网关数据面，真正把 GitOps 闭环跑通。敬请期待！