Argo CD Vault Plugin: The Basics and a Quick Tutorial

What Is the Argo CD Vault Plugin? 

Argo CD is an open source project that helps manage software deployment in line with GitOps principles. The Argo CD Vault plugin extends Argo CD by integrating with the HashiCorp Vault secret management system or similar systems. This can help securely handle secrets, such as API keys and passwords, when performing continuous deployment of applications in Kubernetes environments. 

The Vault Plugin allows the direct retrieval and management of sensitive data from secret managers without embedding them into the source code or configuration files. This improves security by reducing the risk of exposing sensitive information. 

The Argo CD Vault Plugin supports various secret management backends, enabling configurations suited to different organizational needs. By managing secrets externally, Argo CD users can leverage centralized secret storage while automating deployment processes. 

How the Argo CD Vault Plugin Works 

The Argo CD Vault plugin injects secrets from a secret management system like HashiCorp Vault directly into Kubernetes manifests. This approach removes the need to hard-code sensitive data in configuration files, improving security in continuous deployment workflows.

Template-Based Secret Injection

The plugin works by processing YAML or JSON files that include placeholders where the secrets are intended to be injected. A placeholder is specified using the syntax <placeholder>, which corresponds to a specific key in the Vault. The plugin identifies these placeholders and replaces them with the actual secret values fetched from Vault.

For example, consider the following YAML manifest with a placeholder:

apiVersion: v1
kind: Secret
metadata:
  name: my-secret
  annotations:
    avp.kubernetes.io/path: "path/to/secret"
type: Opaque
data:
  password: <my-vault-key-password>

Processing and Output

Once the plugin completes the secret substitution, it outputs the processed manifest in YAML format. This manifest is then applied by Argo CD to deploy the Kubernetes resource with the injected secrets. The resulting manifest might look like this:

apiVersion: v1
kind: Secret
metadata:
  name: my-secret
  annotations:
    avp.kubernetes.io/path: "path/to/secret"
type: Opaque
data:
  password: dEFxb3dfcnQJ

Here, dEFxb3dfcnQJ represents the base64-encoded value retrieved from Vault, replacing the original placeholder.

Customizing Secret Retrieval

The Argo CD Vault Plugin offers flexibility in how secrets are fetched and injected by supporting different types of placeholders and annotations:

Generic placeholders

These are simple placeholders corresponding to keys in a secret. They are typically used with the avp.kubernetes.io/path annotation to specify where the plugin should retrieve the secret.

Inline-path placeholders

These placeholders allow for more granular control by specifying the exact path and key within the placeholder itself. For example:

data:
  db-password: <path:db/credentials#password>

This retrieves the password key from the secret located at db/credentials. Optionally, you can specify a version, like <path:db/credentials#password#2>, to fetch a specific version of the secret.

Secret versioning

The plugin supports secret versioning by allowing users to specify a version either in the placeholder or through the avp.kubernetes.io/secret-version annotation. This ensures that only the intended version of a secret is used during deployment.

Related content: Read our guide to Argo Kubernetes.

Tutorial: Getting Started with the Argo CD Vault Plugin 

This tutorial will guide you through the steps to install and configure the Argo CD Vault Plugin, so you can start managing secrets securely in your Kubernetes deployments. These instructions are adapted from the official documentation.

Step 1: Installing the Argo CD Vault Plugin

There are multiple methods to install the Argo CD Vault Plugin depending on your use case and Argo CD setup. Below, we explore two common approaches: using an argocd-cm ConfigMap or deploying the plugin as a sidecar container.

Option 1: Installation via argocd-cm ConfigMap

1. Modify the Argo CD ConfigMap: This method involves updating the argocd-cm ConfigMap to include the plugin.

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
  namespace: argocd
data:
  configManagementPlugins: |-
    - name: argocd-vault-plugin
      generate:
        command: ["argocd-vault-plugin"]
        args: ["generate", "./"]

A few important points about this configuration:

• The configManagementPlugins field registers the argocd-vault-plugin with Argo CD.
• The generate command specifies how the plugin should interact with the repository to inject secrets.
• Ensure correct indentation and YAML formatting, as misconfigurations can prevent the plugin from loading properly.
• This configuration must be applied to the argocd-cm ConfigMap in the Argo CD namespace using kubectl.

2. Create the plugin binary: You need to ensure that the plugin binary is available in the argocd-repo-server container.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: argocd-repo-server
  namespace: argocd
spec:
  template:
    spec:
      containers:
        - name: argocd-repo-server
          volumeMounts:
            - name: custom-tools
              mountPath: /usr/local/bin/argocd-vault-plugin
              subPath: argocd-vault-plugin
      initContainers:
        - name: download-tools
          image: alpine:3.8
          command: [sh, -c]
          args:
            - >-
              wget -O argocd-vault-plugin
              https://github.com/argoproj-labs/argocd-vault-plugin/releases/download/v1.16.1/argocd-vault-plugin_1.16.1_linux_amd64 &&
              chmod +x argocd-vault-plugin &&
              mv argocd-vault-plugin /custom-tools/
          volumeMounts:
            - mountPath: /custom-tools
              name: custom-tools
      Volumes:

A few important points about this configuration:

• The wget command is just one way to install the Argo CD Vault plugin. See the full installation guide.
• The initContainers section ensures the argocd-vault-plugin is downloaded and placed in the correct directory before the Argo CD repo server starts.
• The plugin binary is downloaded from the specified URL and moved to /custom-tools/.
• The volumeMounts section ensures the plugin is accessible inside the container at /usr/local/bin/.
• Any changes to the deployment require restarting the argocd-repo-server pod for them to take effect.

Option 2: Installation via a Sidecar Container

1. Define the Sidecar Plugin in a ConfigMap: This method involves creating a sidecar container that runs alongside the argocd-repo-server and manages the plugin.

apiVersion: v1
kind: ConfigMap
metadata:
  name: cmp-plugin
  namespace: argocd
data:
  avp.yaml: |
    apiVersion: argoproj.io/v1alpha1
    kind: ConfigManagementPlugin
    metadata:
      name: argocd-vault-plugin
    spec:
      generate:
        command: ["argocd-vault-plugin"]
        args: ["generate", "./"]

A few important points about this configuration:

• The ConfigManagementPlugin resource defines the sidecar configuration for running the plugin in tandem with the argocd-repo-server.
• The generate command is identical to the core plugin configuration, ensuring consistent behavior.
• This ConfigMap should be applied in the Argo CD namespace using kubectl, and referenced by the deployment.
• Any errors in the plugin’s YAML configuration can prevent it from running correctly.

2. Patch the Argo CD Deployment: Integrate the sidecar container into the Argo CD deployment.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: argocd-repo-server
  namespace: argocd
spec:
  template:
    spec:
      containers:
        - name: avp
          image: registry.access.redhat.com/ubi8
          command: ["/var/run/argocd/argocd-cmp-server"]
          volumeMounts:
            - mountPath: /usr/local/bin/argocd-vault-plugin
              subPath: argocd-vault-plugin
              name: custom-tools
      initContainers:
        - name: download-tools
          image: registry.access.redhat.com/ubi8
          command: [sh, -c]
          args:
            - >-
              curl -L https://github.com/argoproj-labs/argocd-vault-plugin/releases/download/v1.16.1/argocd-vault-plugin_1.16.1_linux_amd64 -o argocd-vault-plugin &&
              chmod +x argocd-vault-plugin &&
              mv argocd-vault-plugin /custom-tools/
          volumeMounts:
            - mountPath: /custom-tools
              name: custom-tools
      volumes:
        - name: custom-tools
          emptyDir: {}

A few important points about this configuration:

• The sidecar container is added to the argocd-repo-server pod to run the plugin independently.
• The initContainers block ensures the plugin binary is downloaded before the pod starts.
• The custom-tools volume is shared between the main container and sidecar, providing access to the plugin binary.
• Modifications to the deployment should be followed by a pod restart to apply changes.

Step 2: Configuring the Argo CD Vault Plugin

Once the plugin is installed, you need to configure it to work with your secret management backend (e.g., HashiCorp Vault). This configuration involves specifying the paths to your secrets and how they should be injected into your Kubernetes manifests.

For example, to inject a secret stored in Vault, you might use the following annotation in your manifest:

apiVersion: v1
kind: Secret
metadata:
  name: my-secret
  annotations:
    avp.kubernetes.io/path: "path/to/secret"
type: Opaque
data:
  password: <my-vault-key-password>

A few important points about this configuration:

• The avp.kubernetes.io/path annotation specifies the Vault path where the secret is stored.
• The plugin will retrieve and inject secrets from the configured backend (e.g., Vault) into the Kubernetes manifest.
• Ensure that the Vault authentication and access policies are correctly configured to avoid permission issues.
• The injected secrets must match the expected format in your Kubernetes resources for successful deployment.

Step 3: Deploying Applications with Injected Secrets

After configuring the plugin, you can deploy your applications using Argo CD as usual. The Argo CD Vault Plugin will automatically inject the necessary secrets into your manifests before deployment.

This setup ensures that your secrets are managed securely, reducing the risk of exposing sensitive information in your Kubernetes environment.

Codefresh: A Modern, Argo-Based CI/CD Platform

The Codefresh platform, powered by Argo, combines the best of the open-source with an enterprise-grade runtime allowing you to fully tap the power of Argo Workflows, Events, CD, and Rollouts. It provides teams with a unified GitOps experience to build, test, deploy, and scale their applications.

You can use Codefresh for your platform engineering initiative either as a developer portal or as the machinery that takes care of everything that happens in the developer portal. Your choice depends on how far your organization has adopted Kubernetes and micro-services

Codefresh is a next generation CI/CD platform designed for cloud-native applications, offering dynamic builds, progressive delivery, and much more.

Ready to Get Started?

Deploy more and fail less with Codefresh and Argo

Sign Up