Kubernetes纯内网环境ArgoCD生产环境部署与运维最佳实践指南
CI/CD 持续集成,Developer
|
|
572
|
0

Kubernetes纯内网环境ArgoCD生产环境部署与运维最佳实践指南

一、前言

在企业生产Kubernetes集群中，绝大多数业务均运行在纯内网隔离环境，集群节点无公网出口、无法直接拉取外网镜像、无法访问GitHub官方Yaml源。传统ArgoCD部署方式依赖公网资源，无法适配内网生产场景。

本文聚焦纯内网K8s集群，提供开箱即用的一键部署脚本、生产级配置、中高级运维技巧、常见故障排查、集群迁移方案，为企业GitOps落地提供完整生产最佳实践。

适用场景：

  • 无公网隔离Kubernetes生产集群
  • 内网私有镜像仓库（Harbor/Registry）环境
  • 企业级GitOps持续交付生产落地
  • ArgoCD日常运维、故障修复、集群迁移

环境前置条件：

  • Kubernetes 1.24+ 生产集群（全面兼容1.24~1.31最新主流版本）
  • 内网私有镜像仓库（已同步ArgoCD官方镜像）
  • 集群节点可正常解析内网域名、连通私有仓库
  • 已安装kubectl且集群权限为cluster-admin

二、内网环境前置准备（核心关键）

纯内网部署最大难点：镜像无法拉取、官方资源无法访问，需提前完成资源本地化。

2.1 同步ArgoCD官方镜像到内网仓库

本文全程采用当前生产最新稳定版 v2.12.6（修复大量 CVE 漏洞、优化内网同步稳定性、兼容 K8s 1.24~1.31 全系列版本），需同步以下核心镜像至内网Harbor：

  • quay.io/argoproj/argocd
  • quay.io/argoproj/argocd-repo-server
  • quay.io/argoproj/argocd-application-controller
  • quay.io/argoproj/argocd-dex-server
  • quay.io/argoproj/argocd-redis

镜像同步脚本（可离线执行）：

#!/bin/bash
# 内网镜像同步脚本
VERSION="v2.12.6"
INNER_REGISTRY="harbor.n.xiaomi.com/argocd"

# 拉取官方镜像
docker pull quay.io/argoproj/argocd:$VERSION
docker pull quay.io/argoproj/argocd-repo-server:$VERSION
docker pull quay.io/argoproj/argocd-application-controller:$VERSION
docker pull quay.io/argoproj/argocd-dex-server:$VERSION
docker pull quay.io/argoproj/argocd-redis:$VERSION

# 重命名内网镜像
docker tag quay.io/argoproj/argocd:$VERSION $INNER_REGISTRY/argocd:$VERSION
docker tag quay.io/argoproj/argocd-repo-server:$VERSION $INNER_REGISTRY/argocd-repo-server:$VERSION
docker tag quay.io/argoproj/argocd-application-controller:$VERSION $INNER_REGISTRY/argocd-application-controller:$VERSION
docker tag quay.io/argoproj/argocd-dex-server:$VERSION $INNER_REGISTRY/argocd-dex-server:$VERSION
docker tag quay.io/argoproj/argocd-redis:$VERSION $INNER_REGISTRY/argocd-redis:$VERSION

# 推送内网仓库
docker push $INNER_REGISTRY/argocd:$VERSION
docker push $INNER_REGISTRY/argocd-repo-server:$VERSION
docker push $INNER_REGISTRY/argocd-application-controller:$VERSION
docker push $INNER_REGISTRY/argocd-dex-server:$VERSION
docker push $INNER_REGISTRY/argocd-redis:$VERSION

2.2 离线Yaml资源本地化

纯内网环境无法通过网络拉取官方在线YAML清单，必须手动下载官方标准部署清单、本地化存储、批量替换镜像域名与外网依赖配置，彻底消除部署阶段公网依赖。本小节提供完整离线YAML本地化实操步骤，全程可离线操作。

2.2.1 外网机器下载官方离线YAML

找一台有公网权限的设备，下载对应版本官方完整部署清单，本文适配最新生产稳定版 v2.12.6：

# 下载官方完整部署yaml（v2.12.6 稳定版）
wget https://raw.githubusercontent.com/argoproj/argo-cd/v2.12.6/manifests/install.yaml -O argocd-official-install.yaml

2.2.2 批量替换外网镜像为内网镜像

通过sed命令批量替换文件中所有 quay.io/argoproj 官方镜像地址为企业内网Harbor地址，同时清理外网遥测、更新检测等配置：

# 定义内网仓库地址
INNER_REGISTRY="harbor.n.xiaomi.com/argocd"
# 批量替换镜像源
sed -i "s#quay.io/argoproj#${INNER_REGISTRY}#g" argocd-official-install.yaml
# 禁用外网更新检测与遥测
sed -i '/containers:/a        - name: ARGOCD_DISABLE_TELEMETRYn          value: "true"n        - name: ARGOCD_ENABLE_UPDATESn          value: "false"' argocd-official-install.yaml

2.2.3 离线文件迁移与校验

将修改完成的 argocd-official-install.yaml 文件通过U盘、内网传输等方式拷贝至生产内网K8s集群运维节点，执行配置校验，确保无外网域名、无公网镜像残留：

# 校验是否残留官方外网镜像
grep "quay.io" argocd-official-install.yaml
# 校验禁用外网配置是否生效
grep -E "TELEMETRY|UPDATES" argocd-official-install.yaml

若无任何输出，则代表YAML本地化改造完成，可用于内网环境部署。本文上方一键部署脚本已整合所有本地化配置，可直接替代官方YAML部署，更适配生产高可用需求。

三、纯内网ArgoCD一键生产部署脚本

以下为生产级一键离线部署脚本，无需公网、自动创建命名空间、替换内网镜像、配置生产资源限制、关闭外网监控、适配内网DNS。

创建文件：argocd-intranet-install.sh

#!/bin/bash
# ArgoCD 纯内网生产一键部署脚本
# 版本：v2.12.6 稳定生产版
# 适配无公网K8s集群、内网私有镜像仓库
# 生产环境优化：资源限制、高可用、安全加固、内网适配

set -e

# ====================== 自定义内网配置======================
NAMESPACE="argocd"
ARGOCD_VERSION="v2.12.6"
INNER_REGISTRY="harbor.n.xiaomi.com/argocd"
INGRESS_HOST="harbor.n.xiaomi.com"
# ==========================================================================

echo "[1] 创建ArgoCD命名空间"
kubectl create namespace ${NAMESPACE} --dry-run=client -o yaml | kubectl apply -f -

echo "[2] 部署内网版ArgoCD核心组件"
cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: ServiceAccount
metadata:
  name: argocd-admin
  namespace: ${NAMESPACE}
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: argocd-admin-binding
subjects:
- kind: ServiceAccount
  name: argocd-admin
  namespace: ${NAMESPACE}
roleRef:
  kind: ClusterRole
  name: cluster-admin
  apiGroup: rbac.authorization.k8s.io
EOF

# 部署内网定制化ArgoCD核心资源
cat <<EOF | kubectl apply -f -
apiVersion: apps/v1
kind: Deployment
metadata:
  name: argocd-server
  namespace: ${NAMESPACE}
spec:
  replicas: 2
  selector:
    matchLabels:
      app: argocd-server
  template:
    metadata:
      labels:
        app: argocd-server
    spec:
      serviceAccountName: argocd-admin
      containers:
      - name: argocd-server
        image: ${INNER_REGISTRY}/argocd:${ARGOCD_VERSION}
        imagePullPolicy: Always
        resources:
          requests:
            cpu: 100m
            memory: 256Mi
          limits:
            cpu: 1000m
            memory: 1Gi
        ports:
        - containerPort: 8080
        - containerPort: 8083
        env:
        # 关闭外网遥测、监控、更新检查（内网必备）
        - name: ARGOCD_DISABLE_TELEMETRY
          value: "true"
        - name: ARGOCD_ENABLE_UPDATES
          value: "false"
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: argocd-repo-server
  namespace: ${NAMESPACE}
spec:
  replicas: 2
  selector:
    matchLabels:
      app: argocd-repo-server
  template:
    metadata:
      labels:
        app: argocd-repo-server
    spec:
      containers:
      - name: argocd-repo-server
        image: ${INNER_REGISTRY}/argocd-repo-server:${ARGOCD_VERSION}
        imagePullPolicy: Always
        resources:
          requests:
            cpu: 100m
            memory: 256Mi
          limits:
            cpu: 500m
            memory: 512Mi
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: argocd-application-controller
  namespace: ${NAMESPACE}
spec:
  replicas: 2
  selector:
    matchLabels:
      app: argocd-application-controller
  template:
    metadata:
      labels:
        app: argocd-application-controller
    spec:
      containers:
      - name: argocd-application-controller
        image: ${INNER_REGISTRY}/argocd-application-controller:${ARGOCD_VERSION}
        imagePullPolicy: Always
        resources:
          requests:
            cpu: 100m
            memory: 256Mi
          limits:
            cpu: 500m
            memory: 512Mi
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: argocd-redis
  namespace: ${NAMESPACE}
spec:
  replicas: 1
  selector:
    matchLabels:
      app: argocd-redis
  template:
    metadata:
      labels:
        app: argocd-redis
    spec:
      containers:
      - name: argocd-redis
        image: ${INNER_REGISTRY}/argocd-redis:${ARGOCD_VERSION}
        imagePullPolicy: Always
        resources:
          requests:
            cpu: 50m
            memory: 64Mi
          limits:
            cpu: 200m
            memory: 256Mi
---
# 内网Service暴露
apiVersion: v1
kind: Service
metadata:
  name: argocd-server
  namespace: ${NAMESPACE}
spec:
  selector:
    app: argocd-server
  ports:
  - port: 80
    targetPort: 8080
  type: ClusterIP
---
# 内网Ingress配置
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: argocd-ingress
  namespace: ${NAMESPACE}
  annotations:
    kubernetes.io/ingress.class: nginx
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
spec:
  rules:
  - host: ${INGRESS_HOST}
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: argocd-server
            port:
              number: 80
EOF

echo "[3] 等待ArgoCD组件启动"
kubectl wait --for=condition=ready pod -n ${NAMESPACE} --all --timeout=300s

echo "[4] 获取初始登录密码"
echo "ArgoCD初始密码："
kubectl get secret argocd-initial-admin-secret -n ${NAMESPACE} -o jsonpath="{.data.password}" | base64 -d

echo -e "n✅ 内网ArgoCD v2.12.6 生产部署完成！访问地址：https://${INGRESS_HOST}"

3.1 脚本执行方式

# 授权
chmod +x argocd-intranet-install.sh
# 执行部署
./argocd-intranet-install.sh

3.2 v2.12.6 版本升级 & 生产优化点说明

  • 高危漏洞修复：v2.12.6 修复旧版任意代码执行、权限越权、路径遍历等多条高危CVE，满足等保生产要求
  • 禁用外网遥测与更新检查：彻底杜绝内网环境外网探针请求，100%离线运行
  • 多副本高可用：核心组件双副本部署，消除生产单点故障
  • 资源配额精细化限制：适配新版组件内存、CPU占用特性，避免集群资源抢占与雪崩
  • 内网Ingress安全适配：强制HTTPS跳转、仅内网域名解析访问，杜绝公网暴露风险
  • 内网同步稳定性优化：新版优化repo-server缓存与重试机制，大幅降低内网延迟导致的同步失败概率

四、内网ArgoCD基础使用配置

4.1 重置Admin密码

# 进入argocd容器或本地安装argocd客户端
argocd login harbor.n.xiaomi.com
# 重置密码
argocd account update-password

4.2 配置内网Git仓库

内网环境禁止配置外网Git地址，仅对接企业内网GitLab/Gitee私有仓库：

  1. ArgoCD UI → Settings → Repositories
  2. 添加内网Git仓库地址
  3. 配置内网Git账号密码/SSH密钥
  4. 关闭外网仓库自动同步检测

4.3 配置内网私有镜像仓库

在ArgoCD中配置内网Harbor，实现镜像内网拉取，避免镜像拉取失败：

# 创建镜像仓库密钥
kubectl create secret docker-registry inner-harbor 
-n argocd 
--docker-server=harbor.n.xiaomi.com 
--docker-username=xxx 
--docker-password=xxx

五、中高级生产运维指南

5.1 ArgoCD高可用运维配置

生产环境必须开启自动扩缩容、故障自愈、资源监控。

5.1.1 开启HPA自动扩容

# 为repo-server开启HPA（同步任务密集组件）
kubectl autoscale deployment argocd-repo-server -n argocd --min=2 --max=10 --cpu-percent=70

5.1.2 开启资源快照与自愈

修改argocd-cm配置，开启内网环境自愈机制，关闭外网校验：

kubectl edit cm argocd-cm -n argocd

新增配置：

data:
  timeout.reconciliation: 180s
  statusbadge.enabled: "false"
  telemetry.enabled: "false"

5.2 应用同步策略最佳实践

生产环境推荐手动审核+自动同步策略，避免误更新：

  • 同步方式：Prune=false（禁止自动删除资源）
  • 自愈开启：开启自动修复漂移资源
  • 超时时间：生产环境调整为180s，避免内网延迟超时
  • 重试机制：开启同步失败自动重试3次

5.3 权限精细化运维

回收默认cluster-admin权限，配置命名空间级权限，实现最小权限原则。

六、生产常见问题排查手册

汇总内网环境ArgoCD高频故障及解决方案，覆盖90%生产异常。

6.1 问题一：镜像拉取失败（内网最高频）

现象：Pod状态ImagePullBackOff，提示镜像不存在/无法连接仓库

根因：镜像地址未替换为内网、节点无仓库权限、DNS解析失败

解决方案：

  1. 检查Deployment镜像地址是否为内网Harbor地址
  2. 节点手动执行docker pull测试镜像连通性
  3. 配置节点内网DNS，关闭外网DNS
  4. 确认镜像同步版本与部署版本一致

6.2 问题二：应用同步超时、Sync Failed

现象：内网Git同步缓慢，同步超时、资源渲染失败

根因：内网网络延迟高、默认超时时间过短、repo-server资源不足

解决方案：

  1. 修改argocd-cm延长同步超时时间至180s+
  2. 扩容repo-server CPU内存资源
  3. 检查内网Git仓库连通性，清理仓库大文件

6.3 问题三：ArgoCD UI无法访问、503报错

根因：Ingress配置错误、argocd-server副本异常、端口冲突

排查命令：

# 查看pod状态
kubectl get pod -n argocd
# 查看ingress状态
kubectl get ingress -n argocd
# 查看日志
kubectl logs deployment/argocd-server -n argocd

6.4 问题四：资源漂移、自动自愈失效

解决方案：检查应用同步策略，确认Self Heal开启，手动触发同步：

argocd app sync 应用名

6.5 问题五：Redis连接异常、缓存失效

现象：页面卡顿、同步状态异常、数据缓存丢失

解决方案：重启redis组件、检查网络连通、清理缓存异常：

kubectl rollout restart deployment argocd-redis -n argocd

七、ArgoCD生产故障迁移与备份恢复

生产集群迭代、服务器更替时，需实现零停机迁移、配置完整迁移。

7.1 全量备份方案

备份ArgoCD所有配置、应用、密钥、权限，创建备份脚本 argocd-backup.sh

#!/bin/bash
# ArgoCD内网环境全量备份
DATE=$(date +%Y%m%d)
BACKUP_DIR="./argocd-backup-$DATE"
mkdir -p $BACKUP_DIR

# 备份所有资源
kubectl get all -n argocd -o yaml > $BACKUP_DIR/argocd-all-resource.yaml
# 备份配置文件
kubectl get cm argocd-cm -n argocd -o yaml > $BACKUP_DIR/argocd-cm.yaml
kubectl get cm argocd-rbac-cm -n argocd -o yaml > $BACKUP_DIR/argocd-rbac.yaml
# 备份密钥
kubectl get secrets -n argocd -o yaml > $BACKUP_DIR/argocd-secrets.yaml
# 备份所有应用配置
argocd app list -o yaml > $BACKUP_DIR/argocd-apps.yaml

echo "✅ 备份完成：$BACKUP_DIR"

7.2 跨集群迁移步骤（纯内网）

适用场景：旧K8s集群迁移至新内网集群、版本升级迁移

  1. 新集群前置准备：同步所有ArgoCD镜像至新集群内网仓库，保持版本一致
  2. 执行全量备份：在旧集群执行备份脚本
  3. 新集群部署基础环境：执行本文一键部署脚本
  4. 导入备份配置：
# 导入配置与密钥
kubectl apply -f argocd-cm.yaml -n argocd
kubectl apply -f argocd-secrets.yaml -n argocd
# 导入应用
argocd app create -f argocd-apps.yaml
  1. 校验同步状态：确认所有应用同步正常、状态健康
  2. 切换域名解析：将内网域名解析至新集群Ingress
  3. 下线旧集群：平稳割接，无业务中断

7.3 故障快速恢复方案

集群意外故障、组件损坏时，直接基于备份文件一键恢复：

kubectl apply -f argocd-backup-20260112/

八、生产运维规范与最佳实践总结

8.1 必须遵守的内网生产规范

  • 所有镜像、仓库、Git地址全部内网化，禁止任何外网请求
  • 核心组件多副本部署，杜绝单点故障
  • 开启资源限制，防止ArgoCD雪崩影响集群
  • 每日定时备份，保留7天备份快照
  • 权限最小化，禁止开放公网访问

8.2 运维巡检清单

  • 检查所有Pod运行状态，无重启、无异常
  • 检查应用同步状态，无Sync Error、无资源漂移
  • 检查内网仓库、Git连通性
  • 检查资源使用率，及时扩容
  • 核对备份文件完整性

九、结尾

本文完全适配企业纯内网生产环境，解决了官方ArgoCD无法离线部署、外网依赖、生产故障频发等核心问题。整套方案包含一键部署、配置优化、日常运维、故障排查、集群迁移全流程，可直接落地企业生产，作为GitOps标准化运维手册使用。

上一篇
下一篇

推荐文章

干货｜自研基于API实现有道云笔记全格式导出
车载刷写中0x3E80为何是ECU升级的关键报文
DoIP刷写技术差异分析：以大众、奔驰与吉利、比亚迪为例
车载诊断技术对比：CAN vs DoIP
深入浅出车载以太网诊断DoIP技术
密码保护：整车开发流程（Vehicle Development Process）
现代胎压监测系统（TPMS）的技术概念与应用
版本号定义：开源项目中的实践与策略
Switch语句与循环展开在数据复制优化中的实践
通过Linux脚本实现回收站功能及自动化清理