Skip to main content

Deploying to Kubernetes with the Atlas Operator and Argo CD

GitOps is a software development and deployment methodology that uses Git as the central repository for both code and infrastructure configurations, enabling automated and auditable deployments.

ArgoCD is a Kubernetes-native continuous delivery tool that implements GitOps principles. It uses a declarative approach to deploy applications to Kubernetes, ensuring that the desired state of the application is always maintained.

Kubernetes Operators are software extensions to Kubernetes that enable the automation and management of complex, application-specific operational tasks and domain-specific knowledge within a Kubernetes cluster.

In this guide, we will demonstrate how to use the Atlas Kubernetes Operator and ArgoCD to achieve a GitOps-based deployment workflow for your database schema.


  • A running Kubernetes cluster - For learning purposes, you can use Minikube, which is a tool that runs a single-node Kubernetes cluster inside a VM on your laptop.
  • kubectl - a command-line tool for interacting with Kubernetes clusters.
  • Helm - a package manager for Kubernetes.

High-level architecture

Before we dive into the details of the deployment flow, let’s take a look at the high-level architecture of our application.

Application Architecture

On a high level, our application consists of the following components:

  1. A backend application - in our example we will use a plain NGINX server as a placeholder for a real backend application.
  2. A database - in our example we will use a MySQL pod for the database. In a more realistic scenario, you might want to use a managed database service like AWS RDS or GCP Cloud SQL.
  3. An AtlasSchema Custom Resource that defines the database schema and is managed by the Atlas Operator.

In our application architecture, we have a database that is connected to our application and managed using Atlas CR (Custom Resource). The database plays a crucial role in storing and retrieving data for the application, while the Atlas CR provides seamless integration and management of the database schema within our Kubernetes environment.

How should you run schema changes in an Argo CD deployment?

Integrating GitOps practices with a database in our application stack poses a unique challenge.

Argo CD provides a declarative approach to GitOps, allowing us to define an Argo CD application and seamlessly handle the synchronization process. By pushing changes to the database schema or application code to the Git repository, Argo CD automatically syncs those changes to the Kubernetes cluster.

However, as we discussed in the introduction, ensuring the proper order of deployments is critical. In our scenario, the database deployment must succeed before rolling out the application to ensure its functionality. If the database deployment encounters an issue, it is essential to address it before proceeding with the application deployment.

Argo CD provides Sync Waves and Sync Hooks as features that help to control the order in which manifests are applied within an application. Users may add an annotation to each resource to specify in which "wave" it should be applied. Argo CD will then apply the resources in the order of the waves.

By using annotations with specific order numbers, you can determine the sequence of manifest applications. Lower numbers indicate the earlier application and negative numbers are also allowed.

To ensure that database resources are created and applied before our application, we will utilize Argo CD Sync Waves. The diagram shows our application deployment order:

Application Architecture

To achieve the above order we'll annotate each resource with a sync wave annotation order number:

annotations: "<order-number>"

For more information refer to the official documentation.

With the theoretical background out of the way, let’s take a look at a practical example of how to deploy an application with Argo CD and the Atlas Operator.


1. Install ArgoCD

To install ArgoCD run the following commands:

kubectl create namespace argocd
kubectl apply -n argocd -f

Wait until all the pods in the argocd namespace are running:

kubectl wait --for=condition=ready pod --all -n argocd

kubectl will print something like this:

pod/argocd-application-controller-0 condition met
pod/argocd-applicationset-controller-69dbc8585c-6qbwr condition met
pod/argocd-dex-server-59f89468dc-xl7rg condition met
pod/argocd-notifications-controller-55565589db-gnjdh condition met
pod/argocd-redis-74cb89f466-gzk4f condition met
pod/argocd-repo-server-68444f6479-mn5gl condition met
pod/argocd-server-579f659dd5-5djb5 condition met

For more information or if you run into some error refer to the Argo CD Documentation.

2. Install the Atlas Operator

helm install atlas-operator oci://

Helm will print something like this:

Digest: sha256:4dfed310f0197827b330d2961794e7fc221aa1da1d1b95736dde65c090e6c714
NAME: atlas-operator
LAST DEPLOYED: Tue Jun 27 16:58:30 2023
NAMESPACE: default
STATUS: deployed

Wait until the atlas-operator pod is running:

kubectl wait --for=condition=ready pod -l -n default

kubectl will print something like this:

pod/atlas-operator-866dfbc56d-qkkkn condition met

For more information on the installation process refer to the Atlas Operator Documentation

Define the application manifests

1. Set up a Git repo

Argo CD works by tracking changes to a Git repository and applying them to the cluster, so let's set up a Git repository to serve as the central storage for all your application configuration.

In this example, we’re using the rotemtam/atlas-argocd-demo repository, which contains all of the Kubernetes manifests necessary to deploy our application.

2. Define the database resources

Recall that in our first sync-wave, we want to deploy the database resources to our cluster. For the purposes of this example we're deploying a simple MySQL pod to our cluster, but in a realistic scenario you will probably want to use a managed database service such as AWS RDS, GCP Cloud SQL or one of the available database operators for Kubernetes.

In your repository, create a new directory named manifests and under it create a new file named db.yaml:

apiVersion: v1
kind: Service
annotations: "0"
name: mysql
- port: 3306
app: mysql
clusterIP: None
apiVersion: apps/v1
kind: Deployment
annotations: "0"
name: mysql
app: mysql
app: mysql
- image: mysql:8
name: mysql
value: pass
value: example
port: 3306
initialDelaySeconds: 10
periodSeconds: 10
port: 3306
initialDelaySeconds: 15
periodSeconds: 15
- containerPort: 3306
name: mysql

3. Create the AtlasSchema Custom Resource

Create the AtlasSchema custom resource to define the desired schema for your database, refer to the Atlas Operator documentation and determine the specifications, such as the desired database schema, configuration options, and additional parameters.

Here we’re creating a users table in an example database and annotating it with a sync wave order number of 1. This annotation informs Argo CD to deploy them after the database has been successfully deployed.

kind: AtlasSchema
annotations: "1"
name: myapp
url: mysql://root:pass@mysql:3306/example
sql: |
create table users (
id int not null auto_increment,
name varchar(255) not null,
email varchar(255) unique not null,
short_bio varchar(255) not null,
primary key (id)

4. Create your backend application deployment

For the purpose of this guide, we will deploy a simple NGINX server to act as a placeholder for a real backend server. Notice that we annotate the backend deployment with a sync wave order number of 2. This informs Argo CD to deploy the backend application after the Atlas CR is deployed and confirmed to be in healthy.

apiVersion: apps/v1
kind: Deployment
annotations: "2"
name: nginx
app: nginx
replicas: 2
app: nginx
- name: nginx
image: nginx
- containerPort: 80

5. Create a custom health check for Atlas objects

To decide whether a SyncWave is complete and the next SyncWave can be started, Argo CD performs a health check on the resources in the current SyncWave. If the health check fails, Argo CD will not proceed with the next SyncWave.

Argo CD has built-in health assessment for standard Kubernetes types, such as Deployment and ReplicaSet, but it does not have a built-in health check for custom resources such as AtlasSchema.

To bridge this gap, Argo CD supports custom health checks written in Lua, allowing us to define our custom health assessment logic for the Atlas custom resource.

To define the custom logic for the Atlas object in Argo CD, we can add the custom health check configuration to the argocd-cm ConfigMap. This ConfigMap is a global configuration for Argo CD that should be placed in the same namespace as the rest of the Argo CD resources. Below is a custom health check for the Atlas object:

apiVersion: v1
kind: ConfigMap
name: argocd-cm
namespace: argocd
labels: argocd-cm argocd
resource.customizations: |
health.lua: |
hs = {}
if obj.status ~= nil then
if obj.status.conditions ~= nil then
for i, condition in ipairs(obj.status.conditions) do
if condition.type == "Ready" and condition.status == "False" then
hs.status = "Degraded"
hs.message = condition.message
return hs
if condition.type == "Ready" and condition.status == "True" then
hs.status = "Healthy"
hs.message = condition.message
return hs

hs.status = "Progressing"
hs.message = "Waiting for reconciliation"
return hs

6. Create the Argo CD Application manifest

Finally, create an Argo CD Application.yaml file which defines our Argo application:

kind: Application
name: atlas-argocd-demo
namespace: argocd
path: manifests
repoURL: '' # <-- replace with your repo URL
targetRevision: master # <-- replace with your mainline
namespace: default
server: 'https://kubernetes.default.svc'
project: default
prune: true
selfHeal: true
limit: 5
duration: 5s
maxDuration: 3m0s
factor: 2
- CreateNamespace=true


Make sure all of these files are pushed to your Git repository. If you want to follow along you can use the example repository for this guide.

1. Apply the custom health check

Before deploying our application, we need to apply the custom health check configuration to the Argo CD ConfigMap.

kubectl apply -f -n argocd

2. Deploy our application

With the custom health check in place, we can now deploy our application.

kubectl apply -f

Once you create an Argo CD application, Argo automatically pulls the configuration files from your Git repository and applies them to your Kubernetes cluster. As a result, the corresponding resources are created based on the manifests. This streamlined process ensures that the desired state of your application is synchronized with the actual state in the cluster.

To verify the application is successfully deployed and the resources are healthy:

kubectl get -n argocd atlas-argocd-demo -o=jsonpath='{range .status.resources[*]}{"\n"}{.kind}: {"\t"} {.name} {"\t"} ({.status}) {"\t"} ({.health}){end}'

kubectl will print something like this:

Service:       mysql   (Synced)    ({"status":"Healthy"})
Deployment: mysql (Synced) ({"status":"Healthy"})
Deployment: nginx (Synced) ({"status":"Healthy"})
AtlasSchema: myapp (Synced) ({"message":"The schema has been applied successfully. Apply response: {\"Changes\":{}}","status":"Healthy"})%

Finally, on the ArgoCD UI we can see the health and dependency and status of all the resources:



In this guide, we demonstrated how to use Argo CD to deploy an application that uses the Atlas Operator to manage the lifecycle of the database schema. We also showed how to use Argo CD's custom health check to ensure that the schema changes were successfully applied before deploying the backend application.

Using the techniques described in this guide, you can now integrate schema management into your CI/CD pipeline and ensure that your database schema is always in sync with your application code.