一、ArgoCD核心概念¶
1.1 Argo CD Application¶
来源 (Source)：来源是指存储 Kubernetes 资源配置的 Git 仓库中的具体位置。
目标 (Destination)：目标是指资源在 Kubernetes 集群中的部署位置。
1.2 Argo CD Project¶
项目（Project）的用途：
-
多租户环境：为不同团队分配不同的项目，实现多租户环境，确保团队之间的隔离性和安全性。
-
细粒度的权限控制：项目支持对部署内容、目标环境和资源类型的限制，确保只有经过授权的内容才能被部署到指定的环境。
-
角色和权限管理：定义项目角色和绑定 RBAC 角色，为用户或用户组提供适当的访问权限，确保每个人员只能访问其被授权的资源。
二、配置仓库¶
2.1 准备工作¶
浏览器输入http://gitlab.example.com/登录gitlab，账号为root，密码为<gitlab-password>
1、依次点击【群组】-【新建群组】
2、点击【创建群组】
3、定义群组名称为demoteam
4、依次点击【项目】-【创建项目】
5、点击【创建空白项目】
6、定义项目名称为Argocd
7、上传测试文件
# 配置全局用户名和密码
[root@master01 17]# git config --global user.name "zq"
[root@master01 17]# git config --global user.email "123456@qq.com"
# 配置验证
[root@master01 17]# git config --global --list
user.name=zq
user.email=123456@qq.com
# 克隆
[root@master01 17]# git clone http://gitlab.example.com/demoteam/argocd.git
Cloning into 'argocd'...
Username for 'http://gitlab.example.com': root
Password for 'http://root@gitlab.example.com': <gitlab-password>
# 上传文件到gitlab
[root@master01 17]# cd argocd/
[root@master01 argocd]# echo "this is test" > README.md
[root@master01 argocd]# git push
Username for 'http://gitlab.example.com': root
Password for 'http://root@gitlab.example.com': <gitlab-password>
2.2 添加gitlab仓库¶
1）web UI 添加 gitlab 仓库
argocd 支持多种拉取仓库的方式，下面我们主要介绍 https 和 ssh 这两种较为常见的方式。
依次点击【Settings】-【Repositories】
点击【+CONNECT REPO】
2）argo CLI 命令方式
更多命令，参照：https://argo-cd.readthedocs.io/en/latest/user-guide/commands/argocd_repo add/
# 删除自身所带网络策略
[root@master01 17]# k delete networkpolicy -n argocd --all
# 先使用初始密码登录
[root@master01 17]# argocd login argocd.example.com
Username: admin
Password: <new-admin-password>
# 添加到argocd repo的列表
[root@master01 17]#
argocd repo add http://gitlab.example.com/demoteam/argocd.git --username root --password <gitlab-password> --insecure-skip-server-verification
# 验证查看
[root@master01 argocd]# argocd repo list
WARN[0000] Failed to invoke grpc call. Use flag --grpc-web in grpc calls. To avoid this warning message, use flag --grpc-web.
TYPE NAME REPO INSECURE OCI LFS CREDS STATUS MESSAGE PROJECT
git http://gitlab.example.com/demoteam/argocd.git true false false true Successful
2.3 遇到的问题¶
添加 repo 报错：
FATA[0030] rpc error: code = Unavailable desc = connection error: desc ="transport: Error while dialing: dial tcp <node-ip>:8081: i/o timeout"
官方 issue 解决：https://github.com/argoproj/argo-cd/issues/13644
It's an error with network policy argocd-repo-server-network-policy. If you delete this resource, everything will be works.
删除网络策略
[root@master01 ~]# k delete networkpolicy -n argocd --all
2.4 验证¶
webUI方式查看：
在CLI中查看详细的状态信息：
[root@master01 argocd]# argocd repo list
TYPE NAME REPO INSECURE OCI LFS CREDS STATUS MESSAGE PROJECT
git http://gitlab.example.com/demoteam/argocd.git true false false true Successful
三、配置APP¶
3.1 代码提交至 Gitlab¶
在 GitHub 上创建一个项目，取名为 argocd。
在仓库中新建 dev 目录，在目录中创建两个 YAML 配置清单，分别是 deployment.yaml 和 service.yaml 。
控制器文件内容
# 克隆
[root@master01 17]# git clone http://gitlab.example.com/demoteam/argocd.git
Cloning into 'argocd'...
Username for 'http://gitlab.example.com': root
Password for 'http://root@gitlab.example.com': <gitlab-password>
# 编写deployment.yaml
[root@master01 17]# cd argocd/
[root@master01 argocd]# vim deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: myapp
namespace: demo
spec:
selector:
matchLabels:
app: myapp
replicas: 2
template:
metadata:
labels:
app: myapp
spec:
containers:
- name: myapp
image: registry.cn-hangzhou.aliyuncs.com/abroad_images/nginx:1.15.12
ports:
- containerPort: 80
# 编写service.yaml
[root@master01 argocd]# vim service.yaml
apiVersion: v1
kind: Service
metadata:
name: myapp-service
namespace: demo
spec:
selector:
app: myapp
ports:
- port: 80
protocol: TCP
targetPort: 80
# 编写ingress.yaml
[root@master01 argocd]# vim ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: nginx-ingress
namespace: demo
spec:
ingressClassName: nginx
rules:
- host: nginx.example.com
http:
paths:
- backend:
service:
name: myapp-service
port:
number: 80
path: /
pathType: Prefix
# 查看
[root@master01 argocd]# ls
deployment.yaml ingress.yaml README.md service.yaml
代码提交：
# 初始化
[root@master01 argocd]# git init
# 添加远端仓库
[root@master01 argocd]# git remote add origin http://gitlab.example.com/demoteam/argocd.git
# 验证查看
[root@master01 argocd]# git remote -v
origin http://gitlab.example.com/demoteam/argocd.git (fetch)
origin http://gitlab.example.com/demoteam/argocd.git (push)
# 添加到暂存区
[root@master01 argocd]# git add .
# 提交到本地仓库
[root@master01 argocd]# git commit -m "first for argocd dev"
# 切换到main分支
[root@master01 argocd]# git branch -M main
# 上传到main分支
[root@master01 argocd]# git push -uf origin main
Username for 'http://gitlab.example.com': root
Password for 'http://root@gitlab.example.com': <gitlab-password>
...
...
gitlab验证查看
3.2 创建 ArgoCD 应用¶
代码准备
编写相关文件内容
[root@master01 ~]# mkdir /root/17/myapp
[root@master01 ~]# cd /root/17/myapp/
[root@master01 myapp]# mkdir dev test
[root@master01 myapp]# cd dev/
# 编写deployment.yaml
[root@master01 dev]# vim deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: myapp
namespace: demo
spec:
selector:
matchLabels:
app: myapp
replicas: 2
template:
metadata:
labels:
app: myapp
spec:
containers:
- name: myapp
image: registry.cn-hangzhou.aliyuncs.com/abroad_images/nginx:1.15.12
ports:
- containerPort: 80
# 编写service.yaml
[root@master01 dev]# vim service.yaml
apiVersion: v1
kind: Service
metadata:
name: myapp-service
namespace: demo
spec:
selector:
app: myapp
ports:
- port: 80
protocol: TCP
targetPort: 80
# 编写ingress.yaml
[root@master01 dev]# vim ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: nginx-ingress
namespace: demo
spec:
ingressClassName: nginx
rules:
- host: nginx.example.com
http:
paths:
- backend:
service:
name: myapp-service
port:
number: 80
path: /
pathType: Prefix
# 验证
[root@master01 dev]# ls
deployment.yaml ingress.yaml service.yaml
[root@master01 dev]# cd ..
[root@master01 myapp]# cd test/
# 编写deployment.yaml
[root@master01 dev]# vim deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: busybox-deployment
namespace: demo
spec:
replicas: 2
selector:
matchLabels:
app: busybox
template:
metadata:
labels:
app: busybox
spec:
containers:
- name: busybox
image: registry.cn-hangzhou.aliyuncs.com/abroad_images/busybox:1.30
command:
- "/bin/sh"
- "-c"
- "while true; do sleep 3600; done"
# 编写service.yaml
[root@master01 dev]# vim service.yaml
apiVersion: v1
kind: Service
metadata:
name: busybox-service
namespace: demo
spec:
selector:
app: busybox
ports:
- protocol: TCP
port: 80
targetPort: 80
type: ClusterIP
# 验证查看
[root@master01 test]# ls
deployment.yaml service.yaml
在上传代码文件前，需要取消"受保护分支"，否则推送代码会提示如下内容:
[root@master01 myapp]# git push -uf origin main
Username for 'http://gitlab.example.com': root
Password for 'http://root@gitlab.example.com': <gitlab-password>
Counting objects: 9, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (9/9), done.
Writing objects: 100% (9/9), 1.22 KiB | 0 bytes/s, done.
Total 9 (delta 1), reused 0 (delta 0)
remote: GitLab: You are not allowed to force push code to a protected branch on this project.To http://gitlab.example.com/demoteam/argocd.git
! [remote rejected] main -> main (pre-receive hook declined)
error: failed to push some refs to 'http://gitlab.example.com/demoteam/argocd.git'
点击【项目】，选择"Argocd"项目
点击【设置】-【仓库】，展开【受保护分支】，取消分支保护
上传代码文件到gitlab
# 初始化
[root@master01 ~]# cd /root/17/myapp/
[root@master01 myapp]# git init
# 添加远端仓库
[root@master01 argocd]# git remote add origin http://gitlab.example.com/demoteam/argocd.git
# 验证查看
[root@master01 argocd]# git remote -v
origin http://gitlab.example.com/demoteam/argocd.git (fetch)
origin http://gitlab.example.com/demoteam/argocd.git (push)
# 添加到暂存区
[root@master01 argocd]# git add .
# 提交到本地仓库
[root@master01 argocd]# git commit -m "second for argocd dev"
# 切换到main分支
[root@master01 argocd]# git branch -M main
# 上传到main分支
[root@master01 myapp]# git push -uf origin main
Username for 'http://gitlab.example.com': root
Password for 'http://root@gitlab.example.com':
Counting objects: 9, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (9/9), done.
Writing objects: 100% (9/9), 1.22 KiB | 0 bytes/s, done.
Total 9 (delta 1), reused 0 (delta 0)
To http://gitlab.example.com/demoteam/argocd.git
+ 1f93755...1c84f2e main -> main (forced update)
Branch main set up to track remote branch main from origin.
gitlab页面上进行验证
方法一：使用 CLI 创建 APP
常见的一些命令：
[root@master01 17]# argocd app create --help
Create an application
Usage:
argocd app create APPNAME [flags]
Examples:
# Create a directory app
argocd app create guestbook --repo https://github.com/argoproj/argocd-example-apps.git --path guestbook --dest-namespace default --dest-server https://kubernetes.default.svc --directory-recurse
# Create a Jsonnet app
argocd app create jsonnet-guestbook --repo https://github.com/argoproj/argocd-example-apps.git --path jsonnet-guestbook --dest-namespace default --dest-server https://kubernetes.default.svc --jsonnet-ext-str replicas=2
# Create a Helm app
argocd app create helm-guestbook --repo https://github.com/argoproj/argocd-example-apps.git --path helm-guestbook --dest-namespace default --dest-server https://kubernetes.default.svc --helm-set replicaCount=2
# Create a Helm app from a Helm repo
argocd app create nginx-ingress --repo https://charts.helm.sh/stable --helm-chart nginx-ingress --revision 1.24.3 --dest-namespace default --dest-server https://kubernetes.default.svc
# Create a Kustomize app
argocd app create kustomize-guestbook --repo https://github.com/argoproj/argocd-example-apps.git --path kustomize-guestbook --dest-namespace default --dest-server https://kubernetes.default.svc --kustomize-image gcr.io/heptio-images/ks-guestbook-demo:0.1
# Create a MultiSource app while yaml file contains an application with multiple sources
argocd app create guestbook --file <path-to-yaml-file>
# Create a app using a custom tool:
argocd app create kasane --repo https://github.com/argoproj/argocd-example-apps.git --path plugins/kasane --dest-namespace default --dest-server https://kubernetes.default.svc --config-management-plugin kasane
Flags:
...
...
执行创建命令：
# 创建ns
[root@master01 17]# k create ns demo
# 创建应用
[root@master01 17]#
argocd app create myapp \
--repo http://gitlab.example.com/demoteam/argocd.git \
--path dev \
--dest-server https://kubernetes.default.svc \
--dest-namespace demo \
--sync-policy automated
如上主要参数解释：
myapp是你要创建的应用名称。
http://gitlab.example.com/demoteam/argocd.git 是包含应用配置的Git仓库URL
path dev 是应用配置文件所在的路径，也可以多级：path/to/your/app。
demo 是myapp部署的目标命名空间。
https://kubernetes.default.svc 是Kubernetes API服务器的URL.
--sync-policy automated 开启自动同步
查看&验证：
# 列出应用
[root@master01 myapp]# argocd app list
NAME CLUSTER NAMESPACE PROJECT STATUS HEALTH SYNCPOLICY CONDITIONS REPO PATH TARGET
argocd/myapp https://kubernetes.default.svc demo default Synced Progressing Auto <none> http://gitlab.example.com/demoteam/argocd.git dev
# 查看 myapp 应用
[root@master01 myapp]# argocd app get myapp
Name: argocd/myapp
Project: default
Server: https://kubernetes.default.svc
Namespace: demo
URL: https://argocd.example.com/applications/myapp
Source:
- Repo: http://gitlab.example.com/demoteam/argocd.git
Target:
Path: dev
SyncWindow: Sync Allowed
Sync Policy: Automated
Sync Status: Synced to (1c84f2e)
Health Status: Progressing
GROUP KIND NAMESPACE NAME STATUS HEALTH HOOK MESSAGE
Service demo myapp-service Synced Healthy service/myapp-service created
apps Deployment demo myapp Synced Healthy deployment.apps/myapp created
networking.k8s.io Ingress demo nginx-ingress Synced Progressing ingress.networking.k8s.io/nginx-ingress created
# 应用同步
[root@master01 myapp]# argocd app sync myapp
TIMESTAMP GROUP KIND NAMESPACE NAME STATUS HEALTH HOOK MESSAGE
2025-04-21T20:19:51+08:00 Service demo myapp-service Synced Healthy
2025-04-21T20:19:51+08:00 apps Deployment demo myapp Synced Healthy
2025-04-21T20:19:51+08:00 networking.k8s.io Ingress demo nginx-ingress Synced Healthy
2025-04-21T20:19:51+08:00 Service demo myapp-service Synced Healthy service/myapp-service unchanged
2025-04-21T20:19:51+08:00 apps Deployment demo myapp Synced Healthy deployment.apps/myapp unchanged
2025-04-21T20:19:51+08:00 networking.k8s.io Ingress demo nginx-ingress Synced Healthy ingress.networking.k8s.io/nginx-ingress unchanged
Name: argocd/myapp
Project: default
Server: https://kubernetes.default.svc
Namespace: demo
URL: https://argocd.example.com/applications/myapp
Source:
- Repo: http://gitlab.example.com/demoteam/argocd.git
Target:
Path: dev
SyncWindow: Sync Allowed
Sync Policy: Automated
Sync Status: Synced to (1c84f2e)
Health Status: Healthy
Operation: Sync
Sync Revision: 1c84f2eea01a0faa317100c9be02a734de189a12
Phase: Succeeded
Start: 2025-04-21 20:19:51 +0800 CST
Finished: 2025-04-21 20:19:51 +0800 CST
Duration: 0s
Message: successfully synced (all tasks run)
GROUP KIND NAMESPACE NAME STATUS HEALTH HOOK MESSAGE
Service demo myapp-service Synced Healthy service/myapp-service unchanged
apps Deployment demo myapp Synced Healthy deployment.apps/myapp unchanged
networking.k8s.io Ingress demo nginx-ingress Synced Healthy ingress.networking.k8s.io/nginx-ingress unchanged
# 配置可替换参数，只对helm应用有效
[root@master01 myapp]# argocd app set myapp -p image.tag=v1.0.1
# 环境复原
[root@master01 myapp]# argocd app delete myapp
方法二：使用 YAML 文件创建
[root@master01 ~]# cd /root/17
[root@master01 17]# vim application.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: myapp-argo-application
namespace: argocd
spec:
project: default
source:
repoURL: http://gitlab.example.com/demoteam/argocd.git
targetRevision: HEAD
path: dev
destination:
server: https://kubernetes.default.svc
namespace: demo
syncPolicy:
syncOptions:
- CreateNamespace=true
automated:
selfHeal: true
prune: true
参数解释：
-
syncPolicy : 指定自动同步策略和频率，不配置时需要手动触发同步。
-
syncOptions : 定义同步方式。
-
CreateNamespace=true : 如果不存在这个 namespace，就会自动创建它。
-
automated : 检测到实际状态与期望状态不一致时，采取的同步措施。
-
selfHeal : 当集群状态不符合期望状态时，自动同步。
-
prune : 自动同步时，删除 Git 中不存在的资源。
创建：
# 旧版本
[root@master01 17]# argocd app create myapp --spec-file application.yaml
# 新版本
[root@master01 17]# kubectl apply -f application.yaml
# 环境复原
[root@master01 17]# kubectl delete -f application.yaml
Argo CD 默认情况下 每 3 分钟 会检测 Git 仓库一次，用于判断应用实际状态是否和 Git 中声明的期望状态一致，如果不一致，状态就转换为 OutOfSync 。
默认情况下并不会触发更新，除非通过 syncPolicy 配置了自动同步。
如果嫌周期性同步太慢了，也可以通过设置 Webhook 来使 Git 仓库更新时立即触发同步。后续会介绍到。
方法三：使用界面创建APP
应用信息：
-
Application Name: 服务名称
-
Project Name: 服务所属项目，没有创建项目，默认为空
-
SYNC POLICY: 同步策略
-
Manual: 手动同步
-
Automatic: 自动同步
-
RRUNE RESOURCES：自动修剪。集群上某个资源在 GitRepo 中找不到对应的配置时， 自动删除集群上的该资源
-
SELF HEAL：自愈。因各种原因（如手动修改）集群上资源的实时状态而导致与 GitRepo 不匹配时，自动将实际状态与 GitRepo 的期望状态同步。例如，GitRepo 中定义 pod 的 数量为2，你在集群上改为了 3 个 pod，如果你不勾选 self heal。则 ArgoCD 则不会在 同步（对一次提交只同步一次），这时 pod 的数量就一直为 3。但你如果勾选了 self heal，ArgoCD 就会轮询去同步，将你的 pod 改为你 GitRepo 里的数量
-
-
SYNC OPTIONS（同步选项）
-
SKIP SCHEMA VALIDATION：是否执行资源规范格式的校验，相当于 ”kubectl apply -- validate={true|false}“，默认为 true
-
AUTO-CREATE NAMESPACE：自动创建命名空间。如果部署的应用没有命名空间，则自动创建
-
PRUNE LAST：同步后进行修剪，即其他资源已经部署且转为健康状态后在进行 prune
-
APPLY OUT OF SYNC ONLY：仅对那些处于 OutOfSync 状态的资源执行同步操作。避免大量 对象时资源APl消耗
-
RESPECT IGNORE DIFFERENCES：支持忽略差异配置
-
SERVER-SIDE APPLY：部署操作在服务端运行（避免文件过大）
-
PRUNE PROPAGATION POLICY：资源修剪传播策略，默认值使用 foreground 策略，还有 background 和 orphan
-
REPLACE：将使用 kubectl replace 命令同步资源，而非默认的 apply
syncPolicy:
automated:
prune: true
selfHeal: true
syncOptions:
- Validate=false # 禁用Kubectl验证
- CreateNamespace=true # 自动创建命名空间
- PruneLast=true # 同步后进行修剪
- ApplyOutOfSyncOnly=true # 仅对那些处于OutOfSync状态的资源执行同步操作
- RespectIgnoreDifferences=true # 支持忽略差异配置 (ignoreDifferences)
- PrunePropagationPolicy=background # 级联删除策略 (background, foreground and orphan.)
- Replace=true # kubectl replace替换
项目地址信息：
-
SOURCE
-
Repository URL：定义k8s资源清单的 git 仓库地址
-
Revision：要使用的 Revision，通常是指源码库上的 branch、tag、commit 或 helm chart版本
-
Path：git 仓库中含有配置文件的子目录路径
部署集群信息：
-
DESTINATION
-
CLuster URL：部署的目标集群
-
Namespace：部署集群的 namespace
- Directory：这里还可以选择 helm、Kustomize、Plugin 等
下面展示具体实例说明：
依次点击【Applications】-【Create Application】
GENERAL填写下面信息：
-
Application Name：busybox
-
Project Name：default
-
SYNC POLICY：Automatic
SOURCE填写下面信息：
-
Repository URL：http://gitlab.example.com/demoteam/argocd.git
-
Path：test
DESTINATION填写下面信息：
-
Cluster URL：https://kubernetes.default.svc
-
Namespace：demo
上面内容填写完成后，点击【CREATE】
验证查看
3.3 测试验证¶
本次演示采用第二种方式：
[root@master01 17]# kubectl apply -f application.yaml
点进去可以看到应用的同步详情和各个资源的健康状况：
底层命令验证：
[root@master01 17]# kgp -n demo
NAME READY STATUS RESTARTS AGE
busybox-deployment-664f97c87d-q6pmr 1/1 Running 0 72s
busybox-deployment-664f97c87d-ztl7c 1/1 Running 0 72s
myapp-5cc554d6bb-hrcvd 1/1 Running 0 12m
myapp-5cc554d6bb-ztbp2 1/1 Running 0 12m
3.4 代码迭代¶
1）代码更新
-
新增 replicas：2 --> 3
-
变更底层镜像：registry.cn-hangzhou.aliyuncs.com/abroad_images/busybox:1.30 --> registry.cn-hangzhou.aliyuncs.com/abroad_images/busybox:1.28
[root@master01 ~]# cd /root/17/myapp/test/
[root@master01 test]# vim deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: busybox-deployment
namespace: demo
spec:
replicas: 3
selector:
matchLabels:
app: busybox
template:
metadata:
labels:
app: busybox
spec:
containers:
- name: busybox
image: registry.cn-hangzhou.aliyuncs.com/abroad_images/busybox:1.28
command:
- "/bin/sh"
- "-c"
- "while true; do sleep 3600; done"
2）代码提交
[root@master01 ~]# cd /root/17/myapp/
[root@master01 myapp]# git commit -am "update deploy"
[root@master01 myapp]# git push
...
Username for 'http://gitlab.example.com': root
Password for 'http://root@gitlab.example.com': <gitlab-password>
...
3）点击【SYNC】-【SYNCHRONIZE】
4）watch 观察实时应用动态
[root@master01 myapp]# kubectl get pod -n demo | grep busybox
busybox-deployment-5d4ff66c89-g5jtm 1/1 Running 0 61s
busybox-deployment-5d4ff66c89-p8bjd 1/1 Running 0 60s
busybox-deployment-5d4ff66c89-v7q2j 1/1 Running 0 56s
5）webUI 验证
观察到副本数变为3
观察到镜像变为registry.cn-hangzhou.aliyuncs.com/abroad_images/busybox:1.28
四、总结¶
ArgoCD 是一个强大的工具，不仅支持基本的自动化部署功能，还提供了多种资源描述方式和高级功能，以满足复杂的企业级需求。
通过监控 Git 仓库中的配置文件变化来自动触发部署，Argo CD 可以帮助团队实现高效的 DevOps 流程。
随着我们将继续探索 ArgoCD 的更多高级特性和最佳实践。