This assumes:
- You have an ArgoCD server up and running. If not, check out my article Install Red Hat OpenShift GitOps Operator using the console (Argo CD)
- You have installed the ArgoCD CLI.
- You are able to log into ArgoCD using the CLI. If not, check out my article Log into ArgoCD using the CLI on OpenShift
ArgoCD sits between your version control system (such as GitHub) and your Kubernetes or OpenShift clusters and is used to create resources (such as deployments, pods, services, routes, config maps and secrets) in a particular namespace in your Kubernetes or OpenShift clusters. Almost always, this means you will have YAML files for your various Kubernetes or OpenShift resources in your version control system, such as YAML files for your Kubernetes or OpenShift deployments, YAML files for your Kubernetes or OpenShift secrets, YAML files for your Kubernetes or OpenShift services, et cetera, and ArgoCD will create the corresponding resources in your Kubernetes or OpenShift clusters using the YAML files in your version control system. ArgoCD will also ensure the resources on your Kubernetes or OpenShift clusters remain in sync with their corresponding YAML files in your version control system.
Let's say you have the following deployment YAML file in some public version control system such as GitHub.
apiVersion: apps/v1
kind: Deployment
metadata:
name: python
spec:
replicas: 1
selector:
matchLabels:
app: python
template:
metadata:
labels:
app: python
spec:
containers:
- image: registry.example.com/python:latest
name: python
ports:
- containerPort: 80
And you want to deploy the app to a specific namespace in a Kubernetes or OpenShift cluster. If the namespace does not exist in the Kubernetes or OpenShift cluster you may need to use the kubectl (Kubernetes) or oc (OpenShift) login command to log into the cluster and then use the new-project command to create the project / namespace.
oc new-project my-project
The kubectl (Kubernetes) or oc (OpenShift) auth can-i command can be used to determine if you have permission to create an ArgoCD application.
~]$ oc whoami
john.doe
~]$ oc auth can-i create applications.argoproj.io
yes
If you do not have permission to create an ArgoCD application, the kubectl (Kubernetes) or oc (OpenShift) adm policy who-can command can be used to list the Users, Groups and Service Accounts that have permission to create an ArgoCD application.
~]$ oc adm policy who-can create applications.argoproj.io --namespace my-project
Namespace: my-project
Verb: create
Resource: applications.argoproj.io
Users: system:admin
system:serviceaccount:openshift-gitops-operator:openshift-gitops-operator-controller-manager
system:serviceaccount:openshift-gitops:my-service-account
Groups: Openshift_Admin
openshift_admins
openshift_operators
system:cluster-admins
system:masters
The argocd proj list command can be used to list your ArgoCD projects. These are NOT your namespace in Kubernetes or OpenShift. These are projects in ArgoCD.
The important thing to make note of here is
- The project SOURCES allow you to fetch the YAML file from your version control system (e.g. GitHub)
- The project DESTINATIONS allow you to create the app in the target namespace on Kubernetes or OpenShift
- There are no NAMESPACE-RESOURCE-BLACKLIST that deny the resources from being created in the target namespace on Kubernetes or OpenShift.
The "default" ArgoCD project allows any resource to be created from any source version control system in any namespace on Kubernetes or OpenShift.
~]$ argocd proj list
NAME DESCRIPTION DESTINATIONS SOURCES CLUSTER-RESOURCE-WHITELIST NAMESPACE-RESOURCE-BLACKLIST SIGNATURE-KEYS ORPHANED-RESOURCES DESTINATION-SERVICE-ACCOUNTS
default *,* * */* <none> <none> disabled <none>
my-project *,* * */* <none> <none> disabled <none>
The argocd cluster list command can be used to list the cluster you've added to ArgoCD. https://kubernetes.default.svc is the cluster that ArgoCD is running on.
~]$ argocd cluster list
SERVER NAME VERSION STATUS MESSAGE PROJECT
https://api.dev.openshift.example.com:6443 dev-cluster 1.27 Successful
https://api.stage.openshift.example.com:6443 stage-cluster 1.27 Successful
https://api.prod.openshift.example.com:6443 prod-cluster 1.27 Successful
https://kubernetes.default.svc in-cluster 1.27 Successful
The argocd repo list command can be used to list the repo's you have added to ArgoCD. If the repo your app will be used is not listed the argo repo add command can be used to add the repo.
~]$ argocd repo list
TYPE NAME REPO INSECURE OCI LFS CREDS STATUS MESSAGE PROJECT
git argocd-example-apps https://github.com/argoproj/argocd-example-apps false false false false Successful default
git foo git@github.com:example/foo.git false false false false Successful default
git bar git@github.com:example/bar.git false false false false Successful default
The argocd app create command can be used to create resources (such as deployments, pods, services, routes, config maps and secrets) in a particular namespace in your Kubernetes or OpenShift clusters.
- --path will be the name of the directory in the version control system (GitHub in this example) that contains the YAML files for the resources (such as deployments, pods, services, routes, config maps and secrets) that you want to create in a particular namespace in your Kubernetes or OpenShift clusters. In this example, the deployment.yaml file in GitHub is in a directory named "my-files" which is why --path my-files is used here
- --dest-server is the API Server URL for the Kubernetes or OpenShift cluster that you want the resources to be deployed to
- --dest-namespace is usually the namespace you want the resources to be created in on the target Kubernetes or OpenShift cluster
- --project is the name of the ArgoCD project that application will reside in
argocd app create demo \
--repo git@github.com:foo/bar.git \
--path my-files \
--dest-namespace my-namespace \
--dest-server https://api.dev.openshift.example.com:6443
--project my-project
Or in the ArgoCD console, at Applications > New App, complete the form and click the Create button.
Or you can create a YAML file like this.
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: hello-world
namespace: openshift-gitops
spec:
destination:
namespace: my-project
server: https://api.dev.openshift.example.com:6443
project: default
source:
path: my-files
repoURL: https://github.com/foo/bar.git
And then on the Kubernetes or OpenShift cluster that ArgoCD was installed on, use the kubectl (Kubernetes) or oc (OpenShift) apply command to create the application.
~]$ oc apply --filename hello-world.yaml
application.argoproj.io/hello-world created
The argocd app list command can then be used to list the app you have created.
~]$ argocd app list
NAME CLUSTER NAMESPACE PROJECT STATUS HEALTH SYNCPOLICY CONDITIONS REPO PATH TARGET
openshift-gitops/demo https://kubernetes.default.svc my-project default OutOfSync Missing Manual <none> https://github.com/my-project/my_repo.git python
The argocd app get command can be used to display more details.
~]$ argocd app get openshift-gitops/demo
Name: openshift-gitops/demo
Project: default
Server: https://kubernetes.default.svc
Namespace: default
URL: https://openshift-gitops-server-openshift-gitops.apps.openshift.example.com/applications/demo
Source:
- Repo: https://github.com/my-project/my_repo.git
Target:
Path: my-files
SyncWindow: Sync Allowed
Sync Policy: Manual
Sync Status: OutOfSync from (dbc57d6)
Health Status: Missing
GROUP KIND NAMESPACE NAME STATUS HEALTH HOOK MESSAGE
apps Deployment default python OutOfSync Missing
The kubectl (Kubernetes) or oc (OpenShift) get applications.argoproj.io command should list the application you created.
~]$ oc get applications.argoproj.io --namespace openshift-gitops
NAME SYNC STATUS HEALTH STATUS
hello-world Unknown Healthy
The "server" pod should contain logs like this.
~]$ oc logs openshift-gitops-server-6794f7fc56-sh8hx --namespace openshift-gitops
time="2025-01-14T02:09:43Z" level=warning msg="application does not exist" application=hello-world namespace=openshift-gitops user=admin
time="2025-01-14T02:09:43Z" level=info msg="admin created application" application=hello-world dest-namespace=my-project dest-server="https://api.dev.openshift.example.com:6443" reason=ResourceCreated type=Normal user=admin
In the ArgoCD console, you should see something like this, showing the various resources in your namespace.
Manifest Files
An ArgoCD app contains one or more resources (such as deployments, pods, services, routes, config maps and secrets) for a particular namespace in your Kubernetes or OpenShift clusters. In this example, the "demo" app contains a config map (cm), a service (svc), a service account (sa), a deployment (deploy), a route, an endpoint (ep), an endpoint slice, secrets, a replia set (rs), and a pod. When the app is created in ArgoCD, ArgoCD creates manifest files for each resources. For example, if the app contains a deployment, this means there was a YAML file for the deployment in the version control system (such as GitHub) being used by the app in ArgoCD. When the app was created in ArgoCD, ArgoCD would have fetched the deployment YAML file from the version control system and created a manifest file in ArgoCD for the deployment. The manifest file in ArgoCD is similar (but not identical) to the YAML file from the version control system.
At certain intervals, typically once every 3 minutes, ArgoCD will refresh to compare the manifest file in ArgoCD to the corresponding file in the version control system and if any differences are detected, ArgoCD will update it's manifest file to match the corresponding file in the version control system and ArgoCD will then attempt a sync to update the resource in your Kubernetes or OpenShift clusters. Assuming this works as designed, it's an excellent way to update resources on your Kubernetes or OpenShift clusters. You simply updated the YAML file in your version control system, then ArgoCD takes care of updating the resource on your Kubernetes or OpenShift clusters.
Almost always, after creating an app, you can simply wait a few minutes for the application to sync or you can manually sync.
In the ArgoCD console, you should see something like this, showing the various resources in your namespace.
Did you find this article helpful?
If so, consider buying me a coffee over at 