Introducing the AppSource Controller for ArgoCD

“Automation over process

Large projects have a lot of hard yet less exciting work. We value time spent automating repetitive work more highly than toil.”

— Kuberenetes Community Values

One of the most complex challenges for enterprises today is distributing their cluster resources to their developers. Argo CD Applications are a powerful abstraction that allows users to slice cluster resources into logical groups across multiple Kubernetes clusters.

Out of the box, ArgoCD Applications are created individually by an admin. To create multiple applications at a time Argo CD offers two solutions, an app-of-apps implementation, and the ApplicationSet CRD. Both are quite popular and allow users to manage hundreds of apps in a centralized way.

However, this centralized approach does not fit all use cases. What if you need to empower dozens of teams to manage their applications independently without involving an Argo CD administrator? Some organizations have created their own custom solutions using the ArgoCD API.

We are excited to introduce the AppSource project that aims to provide a generic solution for this use case.

With the AppSource Controller and Custom Resource:

• Admins can allow namespace-restricted users to deploy ArgoCD Applications
• Users can create ArgoCD Applications without involving their admin team in charge of the ArgoCD cluster/namespace
• Admin teams with a need to delegate Application creation to their developer teams can install this controller in any cluster and get started instantly

We understand that adopting a new controller can cause friction with users, so we designed the AppSource controller installation and usage process with our users’ workflows in mind so that they can get started as quickly as possible.

Here’s a quick infographic on everything you need to know about the AppSource controller, if you’d like to learn more about everything you see here, keep reading!

The AppSource controller relies on two key resources — the AppSource instance created by underprivileged users, and an AppSource ConfigMap containing restrictions defined by the Admin team.

Everything you need to know

Installation

To install the AppSource controller into your cluster, all you need is a single kubectl command.

Set-Up

If this is your first time using the AppSource controller, you’ll need to create an ArgoCD account and give it the necessary permissions needed to create and delete ArgoCD Applications.

Here are all the necessary permissions:

• API capabilities, and optional login capabilities if you’d like to see what’s being done by the controller through the ArgoCD UI
• Ability to manage all applications, projects, repositories, and clusters that your ArgoCD instance can manage.

If you’d like some guidance on how to set up these permissions, visit the AppSource Getting Started Guide section on Creating the AppSource account.

You’ll also need to create a Kubernetes secret named argocd-appsource-secret containing the ArgoCD API token for your controller. Guidance on how to do this can also be found in the Getting Started Guide section here.

AppSource Custom Resource

A typical AppSource manifest

The AppSource manifest, typically applied from an access restricted namespace, contains information about the ArgoCD application users would like to create. Users can add an optional finalizer that will delete your ArgoCD Application if you ever decide to delete your AppSource instance.

AppSource ConfigMap

An example AppSource configmap

The AppSource configmap, created by admins, contains:

• The ArgoCD API address for the controller to make application/project creation and deletion requests.
• ArgoCD Client Options held in a single string that works exactly as they do through the ArgoCD command line interface¹
• An array of “project profiles” which are ArgoCD AppProject Specs² matched to a regex name pattern³ for the namespaces being used by underprivileged users.

Features

Finalizers

Using finalizers, you can describe how you want the AppSource controller to handle deleting your ArgoCD application.

Currently supported finalizers:

• application-finalizer.appsource.argoproj.io
• application-finalizer.appsource.argoproj.io/cascade

Both finalizers will perform a delete request through the ArgoCD API however the cascade option with perform a cascade deletion and delete all resources associated with your application as well.

Status Sub-resource

Since the users creating AppSource instances will typically not have access to the namespace restricted AppSource controller deployment logs, AppSources have a status sub-resource that can inform users about the state of their requested ArgoCD application.

Currently supported conditions:

• Application Creation Error/Success
• Application Deletion Error
• Invalid Spec Error
• Unknown Error

Demo

Here are some quick clips demonstrating the AppSource controller in use. We’ve gone ahead and already created the AppSource ConfigMap and Secret containing the ArgoCD API token.

Installation

Creating an ArgoCD Application

Creating an ArgoCD Application using the AppSource custom resource

Using the AppSource Status Sub-resource

Admins can see applications created by the controller through the ArgoCD UI

As a restricted user, you can use the AppSource Status field to see if your ArgoCD application was successfully created

Deleting your AppSource instance

If you included an AppSource finalizer in your AppSource manifest, deleting the AppSource resource will also delete your ArgoCD application

Feedback is always welcome!

Since this is our first release, we’d appreciate it if you gave AppSources a shot and let us know what your experience with it is like!

If you have any cool feature requests, bug reports, or want to contribute code let us know by opening a ticket on our project repository!

Contributors

This project was originally proposed back in June of 2021 and was developed as my Software Engineering Internship project throughout the summer of 2021. I’d like to give a huge thanks to everyone who helped this project come to life and provided me guidance during my time as an intern:

• Alexander Matyushentsev (@alexmt)
• Jesse Suen (@jessesuen)
• The team responsible for the ApplicationSet controller, their work and architecture heavily influenced the design of the AppSource controller
• The Argo Team and community for taking me in as one of their own and showing me the ropes on how ArgoCD/Kubernetes works.

The AppSource controller would not exist without the amazing people that make up our community! That includes you, the reader, thank you for helping and inspiring Argo to become better every day!

Notes

¹ For more information on the ArgoCD CLI options for the API client, visit the ArgoCD documentation website here.

² For more information on ArgoCD AppProject Specs, visit the ArgoCD documentation here.

³ The regex patterns can use a named capture group “project” if they don’t want to force the project name to be the first capture group found in a user’s namespace.