Declarative Management of the Akuity Platform

On the Akuity Platform, Argo CD instances and their configuration can be defined declaratively using Kubernetes and Kubernetes-like manifests, and managed using the akuity CLI (or API).

In this tutorial, you will create an Argo CD instance on the Akuity Platform based on manifests stored in a Git repo.

info

This tutorial is accompanied by a GitHub repository: akuity/declarative-example

Create Your Environment

From the GitHub repository, you can create an environment using a devcontainer (based on the devcontainer.json in the repo). This environment will come preloaded with:

• A Kubernetes cluster using kind.
• The akuity, argocd and kubectl CLIs.

GitHub Codespace

The easiest way to get started is with GitHub Codespaces. Click the button below to launch an environment in GitHub Codespaces.

VSCode (local)

Alternatively, you can run the environment using the VS Code Dev Containers extension and Docker on your machine.

• Clone the akuity/declarative-example repo to your machine.

• Open the declarative-example repository in VSCode.

• Ensure you have installed the Dev Containers extension.

• Run the Dev Containers: Open Folder in Container... command in VSCode and select the local folder.

  • Shift + Command/Ctrl + P + Dev Containers: Open Folder in Container...

Without devcontainer (manual)

The bare minimum requirements to follow this tutorial are:

• a Kubernetes cluster with internet access (egress traffic, no port-forwarding is required).
• the akuity CLI.
• a GitHub account.

To follow along:

1. Create a Kubernetes cluster that you want to deploy resources to with Argo CD and set that to your current kubectl context.
2. Download and install theakuity CLI
3. Clone the akuity/declarative-example repo to your machine.

Sign up for the Akuity Platform

tip

Sign up for a free 14-day trial of the Akuity Platform!

If you haven't already, sign up to create your account on the Akuity Platform and create an organization.

Log into the akuity CLI

akuity login

• Open the link displayed, enter the code.

Set your organization name in the akuity config

akuity config set --organization-name=<name>

warning

Replace <name> with your organization's name.

Create the Argo CD instance on the Akuity Platform

akuity argocd apply -f akuity-platform/example

This will create an Argo CD instance based the definition in the argocd.yaml manifest, and the configurations in the argocd-cm.yaml and argocd-secret.yaml (which follow the same format as the open-source).

The cluster.yaml manifest contains the configuration for provisioning an agent that will connect a Kubernetes cluster to the Argo CD instance. In the next step, you'll install the agent into the cluster.

The Application in the bootstrap-app.yaml manifest will also be deployed. Following the App of Apps pattern, it points to a folder containing other Applications and ApplicationSets, therefore automatically bootstrapping your Argo CD instance.

The Applications deployed by the bootstrap Application may appear in an Unknown sync status due to the unavailable destination cluster at the time of creation. After completing the next step, they will eventually retry (up to 5 minutes) and sync successfully. You can speed this up by clicking refresh after the agent has become healthy on the cluster.

info

View the instance in the UI at (replacing <name> with your organization name):

https://akuity.cloud/<name>/argocd/example

tip

The akuity argocd apply -f command can apply a folder containing only Applications, ApplicationSets, and AppProjects without including an Argo CD definition by specifying the instance name with --name.

akuity argocd apply -f apps/ --name example

Connect The Clusters

Apply the agent install manifests to the cluster.

akuity argocd cluster get-agent-manifests --instance-name=example kind | kubectl apply -f -

tip

Check the progress of the agent installation with kubectl get pods -n akuity.

Log Into The argocd CLI

argocd login \
    $(akuity argocd instance get example -o json | jq -r '.id').cd.akuity.cloud \
    --username admin \
    --password akuity-argocd \
    --grpc-web

info

The second line includes a sub-command which is used to form the server URL of your Argo CD instance.

• akuity argocd instance get example -o json will retrieve the Argo CD instance named example from your organization on the Akuity Platform and output the metadata in JSON.
• The output is then piped to jq -r '.id'. We use jq here to filter the JSON output down to the .id attribute for the example Argo CD instance.
• This is all encapsulated in $(...) which allows us to use the id as the sub-domain of the FQDN <id>.cd.akuity.cloud for the server URL in the argocd login command.

tip

The admin password is set to akuity-argocd in the argocd-secret.yaml manifest.

List The Applications

argocd app list

Example output:

NAME                   CLUSTER     NAMESPACE       PROJECT  STATUS  HEALTH   SYNCPOLICY  CONDITIONS  REPO                                               PATH                    TARGET
argocd/bootstrap       in-cluster  argocd          default  Synced  Healthy  Auto-Prune  <none>      https://github.com/akuity/declarative-example      apps/                   HEAD
argocd/helm-guestbook  kind        helm-guestbook  default  Synced  Healthy  Auto-Prune  <none>      https://github.com/morey-tech/argocd-example-apps  general/helm-guestbook  HEAD
argocd/sync-waves      kind        sync-waves      default  Synced  Healthy  Auto-Prune  <none>      https://github.com/morey-tech/argocd-example-apps  general/sync-waves      HEAD

Next Steps

Congratulations! You have now have a production-ready Argo CD instance that is managed fully declaratively without any concern for the underlying infrastructure.

If you are just starting out with Argo CD, consider using your new Argo CD instance to complete our Introduction to Argo CD tutorial.

However, if you are experienced but looking to expand you skills, check out our Advanced GitOps Workshop.