Plugin Installation

The Nyl ArgoCD plugin enables ArgoCD to render Nyl manifests directly from Git repositories. This guide covers plugin installation and configuration.

If you do not need ArgoCD to render Nyl inputs at sync time, consider the simpler rendered manifest GitOps workflow first. It lets ArgoCD sync ordinary YAML without installing a CMP sidecar.

Prerequisites

ArgoCD 2.4+ installed in your cluster
Access to modify ArgoCD’s configuration
Nyl binary available in the ArgoCD repo-server

Installation Methods

Method 1: Custom ArgoCD Image (Recommended)

Build a custom ArgoCD repo-server image with Nyl included:

FROM quay.io/argoproj/argocd:v2.9.3

# Switch to root to install Nyl
USER root

# Download and install Nyl
RUN curl -L https://github.com/NiklasRosenstein/nyl/releases/download/vX.Y.Z/nyl-linux-amd64 \
    -o /usr/local/bin/nyl && \
    chmod +x /usr/local/bin/nyl

# Switch back to argocd user
USER argocd

Deploy this custom image by updating the argocd-repo-server deployment:

spec:
  template:
    spec:
      containers:
      - name: argocd-repo-server
        image: your-registry/argocd-with-nyl:v2.9.3

Method 2: Init Container

Use an init container to download Nyl into a shared volume:

spec:
  template:
    spec:
      initContainers:
      - name: install-nyl
        image: alpine:3.18
        command:
        - sh
        - -c
        - |
          apk add --no-cache curl
          curl -L https://github.com/NiklasRosenstein/nyl/releases/download/vX.Y.Z/nyl-linux-amd64 \
            -o /plugins/nyl
          chmod +x /plugins/nyl
        volumeMounts:
        - name: plugins
          mountPath: /plugins
      containers:
      - name: argocd-repo-server
        volumeMounts:
        - name: plugins
          mountPath: /usr/local/bin/nyl
          subPath: nyl
      volumes:
      - name: plugins
        emptyDir: {}

Plugin Configuration

Configure the Nyl plugin in the ArgoCD ConfigMap:

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
  namespace: argocd
data:
  configManagementPlugins: |
    - name: nyl-v2
      generate:
        command: ["/bin/sh", "-c"]
        args:
        - |
          TEMPLATE_INPUT="${ARGOCD_ENV_NYL_CMP_TEMPLATE_INPUT:-${NYL_CMP_TEMPLATE_INPUT:-}}"
          test -n "$TEMPLATE_INPUT" || { echo "NYL_CMP_TEMPLATE_INPUT is required" >&2; exit 1; }
          nyl render "$TEMPLATE_INPUT"

NYL_CMP_TEMPLATE_INPUT path semantics:

Values that start with / are treated as repository-root-relative (for example: /gitops/system/argocd.yaml).
Values without a leading / are treated as relative to spec.source.path (recommended, usually just the file name).

Verification

Test the plugin installation:

Create a test Application using the Nyl plugin:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: test-nyl
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/your-org/your-repo
    targetRevision: HEAD
    path: path/to/nyl/manifests
    plugin:
      name: nyl-v2
  destination:
    server: https://kubernetes.default.svc
    namespace: default

Check the Application status:

kubectl get application test-nyl -n argocd
argocd app get test-nyl

Verify manifest rendering:

argocd app manifests test-nyl

Passing Environment Variables

You can pass environment variables to the Nyl plugin for configuration:

source:
  plugin:
    name: nyl-v2
    env:
    - name: NYL_CMP_TEMPLATE_INPUT
      value: apps.yaml
    - name: NYL_RELEASE_NAME
      value: my-app
    - name: NYL_RELEASE_NAMESPACE
      value: production

Use apps.yaml (source-path-relative) in most cases. Use a leading / only when you intentionally need a repository-root-relative path.

Troubleshooting

Plugin Not Found

If ArgoCD reports “plugin not found”, check:

The plugin name matches exactly: nyl-v2
The argocd-cm ConfigMap is in the argocd namespace
The repo-server pods have been restarted after configuration changes

kubectl rollout restart deployment argocd-repo-server -n argocd

Command Not Found

If the plugin fails with “nyl: command not found”:

Verify Nyl binary is in the PATH: /usr/local/bin/nyl
Check file permissions (should be executable)
Test manually in the repo-server pod:

kubectl exec -it deployment/argocd-repo-server -n argocd -- nyl --version

Profile Not Found

If Nyl reports “Profile ‘default’ not found”:

Ensure your repository defines [profile.default.values] in nyl.toml
Check the profile name matches what you’re referencing
Verify nyl.toml is in the repository root or search path