Awesome
Argo CD in a nutshell
Zero-conf, repeatable Argo CD environments for demoing, development purposes or troubleshooting (i.e. to reproduce an issue on a clean environment) using Vagrant and k3s in a single-node setup.
Please be aware that this is work in progress, and mainly serves for my own purposes. I thought it could be useful enough to share, however, so here it is.
Getting started
You will need
Vagrant
and
VirtualBox
installed on your system. Also, this box will set-up a private network with
CIDR range 192.168.56.0/24
, so make sure you don't have this already
setup on your host, or have a route to an already existing net or host in
that range.
Then:
git clone https://github.com/jannfis/argocd-nutshell
cd argocd-nutshell
vagrant up
This will fire up a VM with the default variant of Argo CD up & running. This can take a couple of minutes, depending on your network speed and general computer performance specs.
To make sure everything is up & running, ssh
into the box and check the pods
status:
$ vagrant ssh
vagrant@argocd-nutshell:~$ kubectl get pods -n argocd
NAME READY STATUS RESTARTS AGE
argocd-redis-6fb68d9df5-sx7xh 1/1 Running 0 4m30s
argocd-dex-server-748c65b578-kqlpp 1/1 Running 0 4m30s
argocd-application-controller-0 1/1 Running 0 4m30s
argocd-repo-server-64f4ddf469-mbdzn 1/1 Running 0 4m30s
argocd-server-846cf6844-9dvcl 1/1 Running 0 4m30s
If all pods are running correctly, you can then access the web UI by visiting
https://192.168.56.100
The default username is admin
, and the default password is admin
as well.
Teardown
When you had enough testing, simply run
vagrant destroy -f
within the directory that contains the Vagrantfile
.
What's in it?
On top of the already mentioned K3s cluster and a default installation of Argo CD with minor customisation (i.e. service of type LoadBalancer and an admin password set), the following is currently included after the box has been provisioned:
kubectl
pre-configured and with shell completion set-upkubectx
andkubens
too, also with shell completion set-up- a
kustomize
binary in/usr/local/bin
(version 3.9.1) - The latest released
argocd
CLI, ready to use logged into the Argo CD instance
Versions
By default, the most recent stable versions of Argo CD and K3S will be installed in the box.
You can override (pin) the versions installed by the default
variant by
setting some environment variables before running vagrant up
:
-
ARGOCD_VERSION
: This lets you specify another version of the manifests to install. This can be either a tag name (such asv1.8.2
orstable
), or useHEAD
to use the latest manifests frommaster
branch. -
ARGOCD_CLI_VERSION
: Lets you specify the release tag of the Argo CD CLI to install. The special valuelatest
(which is also the default) will look up the latest released version of the CLI from GitHub and install it. -
ARGOCD_IMAGE
: Lets you override the Argo CD container image to use with the manifests. This must be the full path and tag to the image, e.g.quay.io/argoproj/argocd:v1.8.2
. By default, the images as defined in the manifests will be used. -
K3S_VERSION
: The fully qualified version of K3S to install, e.g.v1.20.0+k3s2
. Look at the K3s releases for valid versions. Pre-releases are not supported by the installer.
For example, if you want to install Argo CD v1.7.11 with accompanying CLI on a Kubernetes 1.18.6 cluster, create the box as follows:
ARGOCD_VERSION=v1.7.11 ARGOCD_CLI_VERSION=v1.7.11 K3S_VERSION=v1.18.6+k3s1 vagrant up
Git repository with test data
In order to have some test cases ready to use with the new Argo CD environment,
you can have the script automatically setup a Git repository server which
serves a configurable repository clone. It can be activated by setting the
following environment variable before running vagrant up
:
GIT_ENABLED=true
The following environment variables control what is set up:
-
GIT_CLONE_REPO
- the URL to a repository to clone. Defaults to the Argo CD example apps repositoryhttps://github.com/argoproj/argocd-example-apps
-
GIT_CHECKOUT
- if set totrue
, will checkout the repository from the environment's own repository server (not the upstream repository) in the home directory of thevagrant
user. You can then modify, commit and push from that local checkout without modifying upstream (to keep results initially predictable). Defaults totrue
. -
GIT_CONNECT
- if set to true, will connect the repository within Argo CD, so it's readily available to use. Defaults totrue
.
Variants
Variants are certain pre-configured installations of Argo CD that
argocd-nutshell
can provision for you.
A variant is specified by launching your box with ARGOCD_VARIANT
set to
the name of the variant you want to launch.
Single-Sign-On with GitHub
The variant sso
sets up Argo CD pre-configured to do SSO with a GitHub org.
You will need to setup a GitHub oauth app for this, that needs to match the
following configuration:
The client ID, client secret and GitHub org name must be passed to the Vagrant provisioner like follows:
DEX_CLIENT_ID=<client_id> \
DEX_CLIENT_SECRET=<client_secret> \
DEX_GH_ORG_NAME=<name of your GH org> \
ARGOCD_VARIANT=sso vagrant up
Customization
You can provision custom boxes by doing the following:
-
Create a new YAML configuration in the
config
directory. Have a look atconfig/default.yaml
. Consider all variables mandatory. Be sure to changeargocd.variant
variable to the name of your new variant, for examplemyvariant
. -
The Argo CD manifests are rendered via Kustomize. Have a look at the
variants/default
directory for the default variant that is installed. It contains Kustomize resources to build the Argo CD manifests. You can copy its contents to a new folder with the same name as your new variant. Be aware that the Kustomize resources will be templated by Ansible, and cannot be rendered usingkustomize
as-is. To troubleshoot, usevagrant provision
on changes, and find the final resources on the box within the/kustomize
directory. -
Set
ARGOCD_VARIANT
to the name of the new variant before runningvagrant up
, i.e.ARGOCD_VARIANT=myvariant vagrant up
And then hope it will work out.
Status
This has just been born, and is not ready for general consumption. Feel free to use it in the default configuration. Expect to hack on it. It has lots and lots of rough edges and pitfalls.
YMMV.