DOCSEARCHbyAlgolia
Submit Docs

argocd-lovely-plugin

repository·main·Indexed 19 days ago

https://github.com/crumbhole/argocd-lovely-plugin

A Config Management Plugin (CMP) for Argo CD that enables complex GitOps patterns by composing multiple configuration tools—including Helm, Kustomize, Helmfile, and plain YAML—into a single application deployment. It supports plugin chaining with tools like argocd-vault-replacer, dynamic patching of ApplicationSets via LOVELY_HELM_PATCH, and the ability to deploy multiple Helm charts within one Argo CD Application.

Tokens
12.7K
Snippets
34
Records
51
Agent score
66%

What's inside argocd-lovely-plugin

  1. Overview of argocd-lovely-plugin features

    main

    argocd-lovely-plugin is an Argo CD plugin designed for GitOps workflows that allows you to compose multiple configuration sources into a single Argo CD application.

    Key capabilities include:

    • Composition: Combine multiple Helm charts, Helm charts with plain YAML, or Helm charts with Kustomize into one application.
    • Helm + Kustomize Integration: Trivially use Kustomize to patch Helm output by placing a kustomization.yaml alongside a Helm chart directory.
    • Plugin Chaining: Acts as a master plugin runner that can chain other Argo CD compatible plugins together (e.g., helm | kustomize | argocd-vault-replacer).
    • Application Set Support: Works well with Argo CD Application Sets to apply minor variations to Helm values or Kustomizations per application.
    • Helmfile Support: Supports helmfile.yaml, helmfile.yaml.gotmpl, or YAML files located in helmfile.d/.
    • Plain YAML: Automatically includes all non-hidden YAML files in the directory and subdirectories, provided they are not part of a Helm chart or Kustomize configuration.

  2. Understand Versioned vs Unversioned plugin containers

    main

    When selecting a container image, you must decide between versioned and unversioned behavior:

    Versioned Containers (e.g., pluginname-ver)

    • Usage: You must explicitly specify the version in your Argo CD application configuration (e.g., pluginname-1.2).
    • Pros: Allows running multiple versions of the same plugin simultaneously in the same cluster.
    • Cons: Upgrading the plugin requires manually updating all applications to point to the new version.

    Unversioned Containers (e.g., pluginname)

    • Usage: All versions share the same identifier.
    • Pros: Upgrades are automatic; applications will use the new plugin version as soon as the sidecar image is updated.
    • Cons: You cannot run two different versions of the same plugin at once.

  3. Configuration precedence for argocd-lovely-plugin

    main

    The plugin resolves configuration parameters using a specific priority order. Once a value is found in a higher-priority source, lower-priority sources are ignored:

    1. Plugin Parameters: When used as a sidecar in ArgoCD, parameters are provided in lower case.
    2. ArgoCD Environment Variables: Variables prefixed with ARGOCD_ENV_ (e.g., variables entered into the ArgoCD application env: section).
    3. Standard Environment Variables: Unprefixed environment variables (typically used when configuring via a Kubernetes manifest).

  4. The processing lifecycle of a sub-application

    main

    Each identified sub-application undergoes a multi-stage processing pipeline:

    1. Preprocessors: Lovely executes each configured preprocessor using bash -c. The working directory is set to the sub-application directory. Preprocessors are expected to modify files on disk and must exit with code 0 to continue.
    2. Resource Generation: Lovely detects the deployment type to generate YAML:
      • If helmfile.yaml or helmfile.d is present, it runs helmfile.
      • If Chart.yaml is present, it runs helm.
      • If kustomization.yaml is present, it runs kustomize. Note that any output from helm or helmfile is automatically included as a resource in the Kustomize process.
      • If no deployment tool is detected, it reads the existing YAML from disk.
    3. Plugins: Once YAML is generated/read, Lovely executes each configured plugin using bash -c. Unlike preprocessors, plugins receive the YAML via stdin and must output the processed YAML to stdout. Plugins must exit with code 0 to continue.

  5. Use Kustomize with Helm charts

    main

    You can use the Kustomize helmchartinflationgenerator to combine Helm and Kustomize.

    When using this method, none of the Helm environment variables will have an effect because you should define them within your kustomization.yaml instead. Note that LOVELY_HELM_NAME will also have no effect in this mode. This is the recommended way to use Helm and Kustomize together via the plugin.

  6. Understand the structure of variations.txt

    main

    The variations.txt file defines how different Docker image variations are generated. Each line in the file represents a single variation and must contain exactly three space-separated fields:

    1. Name of resulting dockerfile: The identifier for the resulting image. When used in GitHub, this is pushed to ghcr.io/crumbhole/<name>:<version>.
    2. Base image: The image used as the starting point for the build. The keyword BASE is a special alias that refers to the most basic, versioned, sidecar image.
    3. Dockerfile: The specific Dockerfile used to perform the transformation from the source to the final result.

  7. How plugins and preprocessors work in Lovely

    main

    Lovely allows you to execute external programs at two distinct stages of the processing lifecycle. Both are executed via bash -c <plugin and parameters>, and the working directory is set to the location of the application source being processed. This allows for independent processing of sub-applications.

    There are two types of external calls:

    1. Preprocessors: Executed before any other processing. They are intended to modify files (like Chart.yaml or kustomization.yaml) directly within the current directory. They interact with the process solely by modifying the filesystem.
    2. Plugins: Executed after all processing is complete. They receive the resulting YAML via stdin and must output the final YAML via stdout. If no changes are made, the plugin must echo the stdin to stdout.

  8. How sub-applications are identified and separated

    main

    Lovely divides your application directory into independent 'sub-applications' to allow for different processing pipelines (via plugins and preprocessors configuration).

    A directory is marked as a sub-application and recursion stops if:

    1. Files within the directory match the LOVELY_DETECTION_REGEX.
    2. The directory contains a helmfile.d subdirectory.

    This separation allows you to manage heterogeneous setups, such as having a Helm chart in one directory and plain YAML in another, within the same repository.

  9. Ensure file idempotency with clean copies

    main

    Because Lovely's processing (especially preprocessors) can modify files and may not be idempotent, it is critical to work on an unmodified copy of the files.

    When running as an Argo CD Sidecar Plugin, Lovely automatically operates on a fresh copy of the files, ensuring that modifications do not persist back to the original source or interfere with subsequent runs.

  11. Install argocd-lovely-plugin as an Argo CD Sidecar Plugin

    main

    The recommended installation method is as an Argo CD Config Management Plugin (CMP) Sidecar.

    1. Use a pre-built container. The argocd-lovely-plugin-cmp image is specifically designed for sidecar installation and is versioned.
    2. Follow the standard Argo CD documentation for setting up sidecar plugins.
    3. Important: The plugin has no discovery rules and will not run automatically. You must explicitly reference the plugin by its name in your Argo CD Application specification.

    Example Application spec:

    apiVersion: argoproj.io/v1alpha1
kind: Application
...
spec:
  source:
    plugin:
      name: argocd-lovely-plugin-v1.0
...