Quarkus ArgoCD

Generate Argo CD Application or Project as part of the Quarkus build or using the Quarkus CLI.

Features

Generate the Argo CD Application or AppProject Kubernetes custom resources for the Quarkus application
Command Line interface to install / uninstall and list Argo CD Application(s)
Integration with Quarkus Helm
DevServices able to install Argo CD on kubernetes cluster: kind or k3s

Requirements

Project added under a version control system and pushed on a repository (e.g. GitHub, etc.)
A Kubernetes cluster with Argo CD installed and supporting argoproj.io/v1alpha1.

Compatibility

The following table lists, for each release of the extension, the main versions it was built with:

Quarkus ArgoCD	Quarkus	Fabric8 Kubernetes Client	Sundrio	Argo CD CRDs
`999-SNAPSHOT` (next release)	3.33.3	8.0.0	0.400.1	v3.5.5
0.5.0	3.33.3	7.7.0	0.103.1	v2.11
0.4.0	3.20.1	7.6.1	0.103.1	v2.11
0.3.0	3.19.2	7.1.0	0.103.1	v2.11
0.2.0	3.18.1	7.1.0	0.103.1	v2.11
0.1.0	3.17.3	6.13.1	0.103.1	v2.11
0.0.1 - 0.0.3	3.14.4	6.13.1	0.103.1	v2.11

The Argo CD CRDs column is the Argo CD version of the Application and AppProject CRDs the model (io.quarkiverse.argocd.v1alpha1.*) is generated from. Fields introduced by more recent Argo CD versions are not part of the model, and reading such resources from a cluster can fail.

Breaking changes in the next release (after 0.5.0)

The Argo CD model (io.quarkiverse.argocd.v1alpha1.) is generated with Sundrio. The upgrade of Sundrio from 0.103.1 to 0.400.1 (#153) changed the names of the end() methods of the nested builders: they are no longer prefixed with the name of the parent type.

This only affects code that uses the generated model builders directly (e.g. ApplicationBuilder). The extension configuration (quarkus.argocd.*), the CLI and the generated resources are unchanged.

Before (0.5.0 and older) After

Before (0.5.0 and older)	After
`endApplicationspecSource()`	`endSource()`
`endApplicationspecHelm()`	`endHelm()`
`endSyncpolicyRetry()`	`endRetry()`
`endSyncpolicyBackoff()`	`endBackoff()`

endApplicationspecSource()

endSource()

endApplicationspecHelm()

endHelm()

endSyncpolicyRetry()

endRetry()

endSyncpolicyBackoff()

endBackoff()

The other nested builders of the model whose end*() method was prefixed follow the same pattern: remove the parent type prefix from the method name.

Example:

new ApplicationBuilder()
    .withNewSpec()
        .withNewSource()
            .withNewHelm()
                .withValueFiles("values.yaml")
            .endHelm()        // was: endApplicationspecHelm()
        .endSource()          // was: endApplicationspecSource()
        .withNewSyncPolicy()
            .withNewRetry()
                .withNewBackoff()
                    .withDuration("5s")
                .endBackoff() // was: endSyncpolicyBackoff()
            .endRetry()       // was: endSyncpolicyRetry()
        .endSyncPolicy()
    .endSpec()
    .build();

Building

To build the extension use the following command:

mvn clean install

Usage

To get the Argo CD custom resources generated, it is needed to add the quarkus-argocd extension to a Quarkus project.

Add the extension to your project

To add the extension to the project, manually edit the pom.xml or build.gradle file.

Manually editing the `pom.xml` file

<dependency>
    <groupId>io.quarkiverse.argocd</groupId>
    <artifactId>quarkus-argocd</artifactId>
    <version>0.5.0</version>
</dependency>

Manually editing the `build.gradle` file

dependencies {
    implementation 'io.quarkiverse.argocd:quarkus-argocd:0.5.0'
}

After this step the Argo CD yaml files will be generated under the .argocd directory within the project root as part of the build.

Generated resources

The extension generates, under the .argocd directory of the Git repository root, one file per resource:

appproject-<project-name>.yaml: the AppProject. It is not generated when quarkus.argocd.app-project.name is set to default, as this project already exists in Argo CD.
application-<application-name>.yaml: the Application.

Nothing is generated when the project is not in a Git repository with a remote, as the repository URL is required.

Example of an Application generated for a project named my-app:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
  namespace: argocd
spec:
  destination:
    server: https://kubernetes.default.svc
  project: my-app
  source:
    helm:
      valueFiles:
      - values.yaml
    path: .helm/kubernetes/my-app
    repoURL: https://github.com/<owner>/<repository>.git
    targetRevision: HEAD
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    retry:
      backoff:
        duration: 5s
        factor: 2
        maxDuration: 10m
    syncOptions:
    - CreateNamespace=true
    - RespectIgnoreDifferences=true
    - ApplyOutOfSyncOnly=true

The values are computed as follows:

Field Value

Field	Value
`metadata.namespace`	`quarkus.argocd.application.namespace`, or the Argo CD control plane namespace: `argocd`, or `openshift-gitops` when the OpenShift deployment target is enabled
`spec.project`	`quarkus.argocd.app-project.name`, or the application name
`spec.destination`	`quarkus.argocd.server` and `quarkus.argocd.destination-namespace`
`spec.source.repoURL`	The URL of the Git remote of the project
`spec.source.targetRevision`	`quarkus.argocd.target-revision` (default: `HEAD`)
`spec.source.path`	The Helm chart generated for the application. See Integration with Quarkus Helm

metadata.namespace

quarkus.argocd.application.namespace, or the Argo CD control plane namespace: argocd, or openshift-gitops when the OpenShift deployment target is enabled

spec.project

quarkus.argocd.app-project.name, or the application name

spec.destination

quarkus.argocd.server and quarkus.argocd.destination-namespace

spec.source.repoURL

The URL of the Git remote of the project

spec.source.targetRevision

quarkus.argocd.target-revision (default: HEAD)

spec.source.path

The Helm chart generated for the application. See Integration with Quarkus Helm

The AppProject is created in the Argo CD control plane namespace and allows the same destination and the Git repository of the project as source. When quarkus.argocd.application.namespace is set, this namespace is also added to its sourceNamespaces.

Integration with Quarkus Helm

The extension depends on Quarkus Helm, which generates a Helm chart for the application from the Kubernetes resources produced by the Quarkus Kubernetes extensions.

The generated Application deploys this chart with its values.yaml file. Its spec.source.path is .helm/<deployment-target>/<application-name>, relative to the Git repository root, where <deployment-target> is openshift when the OpenShift extension is used and kubernetes otherwise.

By default, Quarkus Helm generates the chart under the build output directory (target/helm), which is not pushed. To generate it where the Application expects it and commit it, configure:

quarkus.helm.output-directory=../.helm

Using the CLI

The project provides a companion CLI that can be used to generate, install / uninstall and list the Argo CD Applications. The CLI can be added with the following command:

quarkus plug add io.quarkiverse.argocd:quarkus-argocd-cli:0.5.0

Regenerating the files:

To re-trigger the file generation:

quarkus argocd project generate

Note: Several parameters can be used to configure the generated CR. Use quarkus argocd project generate -h to display the usage.

The generate, install and uninstall commands also accept --dry-run, which lists the Argo CD resources that would be processed without writing any file or changing the cluster:

quarkus argocd project install --dry-run

To install the generated Application and AppProject (optional) custom resources to the currently connected Kubernetes cluster:

quarkus argocd project install

Note: In case of un-committed or un-pushed changes, or when the path of the Application (see Integration with Quarkus Helm) is not committed in the Git repository, the command will prompt users to decide if they want to proceed with the installation.

The currently connected Kubernetes cluster is the one that is configured in the ~/.kube/config file. It can be overridden by setting in application.properties a different API server URL and token. See the quarkus-kubernetes-client extension for more details.

To uninstall:

quarkus argocd project uninstall

Listing installed applications

To list all Applications installed

quarkus argocd project list

CLI options

The generate, install and uninstall commands accept the following options. Each of them overrides the corresponding configuration property of the extension:

Option Property Description

Option	Property	Description
`--server`	`quarkus.argocd.server`	The Kubernetes API Server URL
`--appproject-namespace`	`quarkus.argocd.app-project.namespace`	The Argo CD control plane namespace where the `AppProject` is installed
`--application-namespace`	`quarkus.argocd.application.namespace`	The namespace where the `Application` is installed
`--destination-namespace`	`quarkus.argocd.destination-namespace`	The namespace where the resources of the application are deployed
`-p`, `--project-name`	`quarkus.argocd.app-project.name`	The name of the `AppProject`
`--target-revision`	`quarkus.argocd.target-revision`	The revision of the Git repository (branch, tag or commit) that Argo CD syncs

--server

quarkus.argocd.server

The Kubernetes API Server URL

--appproject-namespace

quarkus.argocd.app-project.namespace

The Argo CD control plane namespace where the AppProject is installed

--application-namespace

quarkus.argocd.application.namespace

The namespace where the Application is installed

--destination-namespace

quarkus.argocd.destination-namespace

The namespace where the resources of the application are deployed

-p, --project-name

quarkus.argocd.app-project.name

The name of the AppProject

--target-revision

quarkus.argocd.target-revision

The revision of the Git repository (branch, tag or commit) that Argo CD syncs

Example:

quarkus argocd project generate --destination-namespace=my-app --target-revision=develop

Dev Services

In dev and test mode, the extension starts a Kubernetes cluster with Kubernetes Dev Services and installs Argo CD on it. A container runtime (Docker or Podman) is required.

The Dev Service:

starts a cluster of type quarkus.argocd.devservices.cluster-type (default: kind)
installs the NGINX ingress controller (see Ingress controllers)
installs Argo CD quarkus.argocd.devservices.version (default: v3.5.5) in the quarkus.argocd.devservices.control-plane-namespace namespace (default: argocd), without the Dex and notifications components
creates an ingress for the Argo CD server using the host quarkus.argocd.devservices.host-name (default: argocd.localtest.me)
forwards the Argo CD server port to quarkus.argocd.devservices.host-port (default: 8443) on the host, unless quarkus.argocd.devservices.ingress.port-forward-enabled is false

When the port forward is enabled, the Argo CD UI is available at http://<host-name>:<host-port>; (default: http://argocd.localtest.me:8443) and a link to it is shown in the Dev UI card, together with the installed Argo CD version. It can be accessed with the user admin. Its password is printed in the application logs.

To disable the Dev Service:

quarkus.argocd.devservices.enabled=false

See the quarkus.argocd.devservices.* properties in the configuration reference for all the options.

Installation

If you want to use this extension, you need to add the io.quarkiverse.argocd:quarkus-argocd extension first to your build file.

For instance, with Maven, add the following dependency to your POM file:

<dependency>
    <groupId>io.quarkiverse.argocd</groupId>
    <artifactId>quarkus-argocd</artifactId>
    <version>0.5.0</version>
</dependency>

Extension Configuration Reference

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property	Type	Default
`quarkus.argocd.server` The Kubernetes API Server URL. Environment variable: `QUARKUS_ARGOCD_SERVER`	string	`https://kubernetes.default.svc`
`quarkus.argocd.destination-namespace` The target/destination namespace where the resources of the runtime should be installed from the Helm chart, kustomize, etc Environment variable: `QUARKUS_ARGOCD_DESTINATION_NAMESPACE`	string
`quarkus.argocd.target-revision` The target revision of the repository fetched by ArgoCd from the url Defaults to HEAD. Environment variable: `QUARKUS_ARGOCD_TARGET_REVISION`	string	`HEAD`
`quarkus.argocd.app-project.name` The name of the ArgoCD AppProject CR. A AppProject CR exists by default with full permissions - https://argo-cd.readthedocs.io/en/stable/user-guide/projects/#the-default-project and is named "default" Environment variable: `QUARKUS_ARGOCD_APP_PROJECT_NAME`	string
`quarkus.argocd.app-project.namespace` The AppProject CR namespace. This namespace refers to the Argocd control plane namespace. The value is either 'argocd' or 'openshift-gitops' and is calculated by the extension according to the DeploymentTarget platform: kubernetes or openshift. Remark: It is then not needed for a user to define it Environment variable: `QUARKUS_ARGOCD_APP_PROJECT_NAMESPACE`	string
`quarkus.argocd.application.namespace` The namespace. The ApplicationCR should be installed under the Argocd control plan namespace like the AppProject CR Remark: It is nevertheless possible to install it in another namespace if "Application in any namespaces is enabled: https://argo-cd.readthedocs.io/en/stable/operator-manual/app-any-namespace/" Environment variable: `QUARKUS_ARGOCD_APPLICATION_NAMESPACE`	string
`quarkus.argocd.devservices.enabled` Enable the ArgoCD DevService. Environment variable: `QUARKUS_ARGOCD_DEVSERVICES_ENABLED`	boolean	`true`
`quarkus.argocd.devservices.debug-enabled` Enable the debugging level. Environment variable: `QUARKUS_ARGOCD_DEVSERVICES_DEBUG_ENABLED`	boolean	`false`
`quarkus.argocd.devservices.show-logs` If logs should be shown from the Argocd container. Environment variable: `QUARKUS_ARGOCD_DEVSERVICES_SHOW_LOGS`	boolean	`false`
`quarkus.argocd.devservices.version` The version of Argocd to be installed from the GitHub repository It can be: "latest" or a tagged release expressed as such: "v3.5.5" Environment variable: `QUARKUS_ARGOCD_DEVSERVICES_VERSION`	string	`v3.5.5`
`quarkus.argocd.devservices.control-plane-namespace` The Argocd control plane namespace where AppProject or Application CR are deployed The default namespace is: argocd Environment variable: `QUARKUS_ARGOCD_DEVSERVICES_CONTROL_PLANE_NAMESPACE`	string	`argocd`
`quarkus.argocd.devservices.time-out` Time to wait till a resource is ready: pod, etc The default value is: 180 seconds Environment variable: `QUARKUS_ARGOCD_DEVSERVICES_TIME_OUT`	long	`180`
`quarkus.argocd.devservices.cluster-type` The cluster type to be used: kind or k3s The default value is: kind Environment variable: `QUARKUS_ARGOCD_DEVSERVICES_CLUSTER_TYPE`	string	`kind`
`quarkus.argocd.devservices.host-name` The hostname of the argocd ingress route Environment variable: `QUARKUS_ARGOCD_DEVSERVICES_HOST_NAME`	string	`argocd.localtest.me`
`quarkus.argocd.devservices.host-port` The host port to be used on the host machine Environment variable: `QUARKUS_ARGOCD_DEVSERVICES_HOST_PORT`	string	`8443`
`quarkus.argocd.devservices.ingress.version` The version of the Ingress controller to be installed from the GitHub repository If not specified, it will use the resources published on main branch The version to be used should be specified using the tagged release: v1.12.0, etc Environment variable: `QUARKUS_ARGOCD_DEVSERVICES_INGRESS_VERSION`	string	`latest`
`quarkus.argocd.devservices.ingress.port-forward-enabled` Enable to forward the ingress traffic from the container to the local host Environment variable: `QUARKUS_ARGOCD_DEVSERVICES_INGRESS_PORT_FORWARD_ENABLED`	boolean	`true`

Configuration property

Type

Default

quarkus.argocd.server

The Kubernetes API Server URL.

Environment variable: QUARKUS_ARGOCD_SERVER

string

https://kubernetes.default.svc

quarkus.argocd.destination-namespace

The target/destination namespace where the resources of the runtime should be installed from the Helm chart, kustomize, etc

Environment variable: QUARKUS_ARGOCD_DESTINATION_NAMESPACE

string

quarkus.argocd.target-revision

The target revision of the repository fetched by ArgoCd from the url Defaults to HEAD.

Environment variable: QUARKUS_ARGOCD_TARGET_REVISION

string

HEAD

quarkus.argocd.app-project.name

The name of the ArgoCD AppProject CR. A AppProject CR exists by default with full permissions - https://argo-cd.readthedocs.io/en/stable/user-guide/projects/#the-default-project and is named "default"

Environment variable: QUARKUS_ARGOCD_APP_PROJECT_NAME

string

quarkus.argocd.app-project.namespace

The AppProject CR namespace. This namespace refers to the Argocd control plane namespace. The value is either 'argocd' or 'openshift-gitops' and is calculated by the extension according to the DeploymentTarget platform: kubernetes or openshift. Remark: It is then not needed for a user to define it

Environment variable: QUARKUS_ARGOCD_APP_PROJECT_NAMESPACE

string

quarkus.argocd.application.namespace

The namespace. The ApplicationCR should be installed under the Argocd control plan namespace like the AppProject CR Remark: It is nevertheless possible to install it in another namespace if "Application in any namespaces is enabled: https://argo-cd.readthedocs.io/en/stable/operator-manual/app-any-namespace/"

Environment variable: QUARKUS_ARGOCD_APPLICATION_NAMESPACE

string

quarkus.argocd.devservices.enabled

Enable the ArgoCD DevService.

Environment variable: QUARKUS_ARGOCD_DEVSERVICES_ENABLED

boolean

true

quarkus.argocd.devservices.debug-enabled

Enable the debugging level.

Environment variable: QUARKUS_ARGOCD_DEVSERVICES_DEBUG_ENABLED

boolean

false

quarkus.argocd.devservices.show-logs

If logs should be shown from the Argocd container.

Environment variable: QUARKUS_ARGOCD_DEVSERVICES_SHOW_LOGS

boolean

false

quarkus.argocd.devservices.version

The version of Argocd to be installed from the GitHub repository It can be: "latest" or a tagged release expressed as such: "v3.5.5"

Environment variable: QUARKUS_ARGOCD_DEVSERVICES_VERSION

string

v3.5.5

quarkus.argocd.devservices.control-plane-namespace

The Argocd control plane namespace where AppProject or Application CR are deployed The default namespace is: argocd

Environment variable: QUARKUS_ARGOCD_DEVSERVICES_CONTROL_PLANE_NAMESPACE

string

argocd

quarkus.argocd.devservices.time-out

Time to wait till a resource is ready: pod, etc The default value is: 180 seconds

Environment variable: QUARKUS_ARGOCD_DEVSERVICES_TIME_OUT

long

180

quarkus.argocd.devservices.cluster-type

The cluster type to be used: kind or k3s The default value is: kind

Environment variable: QUARKUS_ARGOCD_DEVSERVICES_CLUSTER_TYPE

string

kind

quarkus.argocd.devservices.host-name

The hostname of the argocd ingress route

Environment variable: QUARKUS_ARGOCD_DEVSERVICES_HOST_NAME

string

argocd.localtest.me

quarkus.argocd.devservices.host-port

The host port to be used on the host machine

Environment variable: QUARKUS_ARGOCD_DEVSERVICES_HOST_PORT

string

8443

quarkus.argocd.devservices.ingress.version

The version of the Ingress controller to be installed from the GitHub repository If not specified, it will use the resources published on main branch The version to be used should be specified using the tagged release: v1.12.0, etc

Environment variable: QUARKUS_ARGOCD_DEVSERVICES_INGRESS_VERSION

string

latest

quarkus.argocd.devservices.ingress.port-forward-enabled

Enable to forward the ingress traffic from the container to the local host

Environment variable: QUARKUS_ARGOCD_DEVSERVICES_INGRESS_PORT_FORWARD_ENABLED

boolean

true

Quarkus ArgoCD

Features

Requirements

Compatibility

Breaking changes in the next release (after 0.5.0)

Building

Usage

Add the extension to your project

Manually editing the pom.xml file

Manually editing the build.gradle file

Generated resources

Integration with Quarkus Helm

Using the CLI

Regenerating the files:

Listing installed applications

CLI options

Dev Services

Installation

Extension Configuration Reference

Manually editing the `pom.xml` file

Manually editing the `build.gradle` file