Akuity Helm Charts

Akuity Helm Charts are a collection of simplified and opinionated Helm charts for the Argo and Argo Ecosystem projects. They are written and intended to be used in a GitOps workflow, where the Helm values.yaml and other customizations are stored in git, with last-mile modifications handled using kustomize's built-in helm chart support.

About

The goal of these charts are to remain as close as possible to the official upstream Argo install manifests (which are released and maintained as raw YAML files) and avoid the divergence that occurred with the Argoproj community maintained Helm charts. The Akuity charts also contain additional options to implement best practices as well as convenience options for common configurations.

These charts have been designed to be deployed from a git repo using Argo CD / kubectl apply, as opposed to helm install. Helm is used for packaging and templating, rather than lifecycle management of the apps.

Why this approach?

Typical Helm charts provide dozens, sometimes hundreds of parameters to handle all conceivable options which the chart authors anticipate users might want to customize for their environment. For example, it is common to parameterize resource names, resource quotas, command line parameters, annotations, affinity rules, Ingress, prometheus stats, etc. Over time, the chart becomes unmaintainable and diverges from the official supported manifests. Additionally, helm charts have no ability to add additional resources which were not part of original chart (e.g. SealedSecrets, ExternalSecrets, alternative Ingress resources), which is a common requirement.

With the realization that there is no "one size fits all" set of install options, these charts take a different approach to Helm charts. Rather than parameterize all the options for every use case, these charts choose to only parameterize the commonly used options and leave last-mile modifications to be handled using kustomize. This keeps the charts simpler to maintain, and more accurate to the upstream manifests.

Versioning Scheme

Akuity Helm Charts are versioned using the following scheme: MAJOR.MINOR.PATCH-ak.X.Y. The following table explains the meaning of the numbers:

Version Number	Meaning
MAJOR.MINOR.PATCH	Corresponds to the upstream Argo major/minor/patch version.
-ak.X	Indicates the Akuity patch made ontop of upstream container image. 0 indicates no change.
.Y	Indicates a change to the Helm chart (e.g. adding additional helm parameters).

Image Versioning

Akuity republishes Argo images under the quay.io/akuity organization. Image tags are appended with an -ak.X patch number to indicate Akuity specific patches ontop of the upstream image (e.g. quay.io/akuity/argocd:v2.5.2-ak.1). An X value of 0 indicates that there is no difference from the upstream image. An X value of 1 or higher indicates a patch was applied ontop of the upstream MAJOR.MINOR.PATCH version.

Examples:

• quay.io/akuity/argocd:v2.5.2-ak.0 - equivalent to upstream Argo CD v2.5.2 release (image retag)
• quay.io/akuity/workflow-controller:v3.4.5-ak.1 - an Akuity patch fix was made ontop of the upstream Argo Workflows v3.4.5 release.

Helm Chart Versioning

Akuity Helm Chart versioning follow the above image versioning scheme, but additionally appends a .Y patch number to indicate any Helm chart changes. This .Y value is normally 0, but is occasionally incremented when the Helm chart is modified and there were no change to the underlying image (e.g. addition of a helm parameter).

Examples:

• 2.5.2-ak.0.0 - image is quay.io/akuity/argocd:v2.5.2-ak.0, which is equivalent to upstream Argo CD v2.5.2 with no changes.
• 2.5.2-ak.1.0 - image is quay.io/akuity/argocd:v2.5.2-ak.1, which contains an Akuity patch fix to v2.5.2.
• 2.5.2-ak.0.1 - image is quay.io/akuity/argocd:v2.5.2-ak.0, which is equivalent to upstream Argo CD v2.5.2. The helm chart was somehow modified from version 2.5.2-ak.0.0.

Usage

Initial Argo CD Installation

It is recommended and encouraged to use Argo CD to manage itself using GitOps. But before Argo CD can manage itself, Argo CD itself needs to be installed. To resolve this chicken-and-egg problem for the initial Argo CD installation, you can install Argo CD using normal kubectl apply:

kustomize build --enable-helm https://github.com/akuity/helm-charts//docs/argo-cd-install | kubectl apply -n argocd -f -

The default installation will install into the argocd namespace. If you wish to change this, see the instructions in docs/argo-cd-install.

Managing Argo CD with Git

Once installed, you will likely want to customize Argo CD for your environment and use git to manage your changes. The following example install can be seen at docs/argo-cd-example. Create a directory in your own git repo with the following files:

.
├── kustomization.yaml
└── values.yaml

kustomization.yaml

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

helmCharts:
- name: argo-cd
  repo: https://charts.akuity.io
  includeCRDs: true
  namespace: argocd
  version: 2.5.2-ak.0.0     # pin to a specific version (see charts/argo-cd/Chart.yaml)
  valuesFile: values.yaml   # Helm values file in your git repo

Here might be a typical values.yaml:

values.yaml

config:
  argocd:
    url: https://cd.example.com
    dex.config: |
      connectors:
      - type: github
        id: github
        name: GitHub
        config:
          clientID: $dex.github.clientID
          clientSecret: $dex.github.clientSecret
          orgs:
          - name: example-org
          teamNameField: slug
          useLoginAsID: true
    kustomize.buildOptions: --enable-helm
  rbac:
    policy.csv: |
      g, example-org:example-team, role:admin
    policy.default: role:readonly

server:
  insecure: true
  ingress:
    enabled: true
    className: contour
    host: cd.example.com

For other available Chart parameters see: charts/argo-cd/values.yaml.

Last-mile Modifications

Since the Helm chart parameters will likely not contain all the parameterization options necessary for your environment, you will use kustomize to perform last-mile modifications to your installation.

Using this approach, you can also use kustomize's patchesStrategicMerge field and put the configuration in patches instead of values.yaml. The following example manages the configuration as separate kubernetes objects instead of inlined fields in values.yaml. Additional resources can be added using the resources field:

kustomization.yaml:

patchesStrategicMerge:
- argocd-cm.yaml

resources:
- argocd-ingress.yaml

argocd-cm.yaml:

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cmd-params-cm
data:
  url: https://cd.example.com
  kustomize.buildOptions: --enable-helm

argocd-ingress.yaml:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: argocd-server
...

For all Argo CD configuration options please refer the Argo CD documentation:

• argocd-cm.yaml
• argocd-rbac-cm.yaml
• argocd-cmd-params-cm.yaml