DOCSEARCHbyAlgolia
Submit Docs

Nelm Documentation

repository·main·Indexed 22 days ago

https://github.com/werf/nelm

Nelm is a Kubernetes deployment tool and Helm 4 alternative that manages Helm Charts and Releases. It features a two-stage deployment workflow (plan/install), built-in secrets management for encrypted values and files, and enhanced CRD management. Nelm provides advanced resource lifecycle control and deployment ordering via annotations such as werf.io/weight and werf.io/deploy-dependency, and is backward-compatible with Helm Charts and Releases.

Tokens
52.5K
Snippets
185
Records
245
Agent score
77%

What's inside Nelm

  1. Overview of nelm CLI commands

    main

    The nelm CLI is organized into several command groups to manage the lifecycle of Kubernetes charts and releases:

    Release commands

    Used for managing deployments to Kubernetes:

    • nelm release install: Deploy a chart to Kubernetes.
    • nelm release rollback: Rollback to a previously deployed release.
    • nelm release plan install: Plan a release install to Kubernetes.
    • nelm release uninstall: Uninstall a Helm Release from Kubernetes.
    • nelm release list: List all releases in a namespace.
    • nelm release history: Show release history.
    • nelm release get: Get information about a deployed release.
    • nelm release plan show: Show plan artifact planned changes.

    Chart commands

    Used for chart manipulation and distribution:

    • nelm chart lint: Lint a chart.
    • nelm chart render: Render a chart.
    • nelm chart download: Download a chart from a repository.
    • nelm chart upload: Upload a chart archive to a repository.
    • nelm chart pack: Pack a chart into an archive to distribute via a repository.

    Secret commands

    Used for managing encrypted values and files within charts:

    • nelm chart secret key create: Create a new chart secret key.
    • nelm chart secret key rotate: Reencrypt secret files with a new secret key.
    • nelm chart secret values-file edit: Interactively edit encrypted values file.
    • nelm chart secret values-file encrypt: Encrypt values file and print result to stdout.
    • nelm chart secret values-file decrypt: Decrypt values file and print result to stdout.
    • nelm chart secret file edit: Interactively edit encrypted file.
    • nelm chart secret file encrypt: Encrypt file and print result to stdout.
    • nelm chart secret file decrypt: Decrypt file and print result to stdout.

    Dependency commands

    • nelm chart dependency download: Download chart dependencies from Chart.lock.
    • nelm chart dependency update: Update Chart.lock and download chart dependencies.

    TypeScript commands

    • nelm chart ts init: Initialize the files needed to render manifests using TypeScript.
    • nelm chart ts build: Build TypeScript chart.

    Repo commands

    • nelm repo add: Set up a new chart repository.
    • nelm repo remove: Remove a chart repository.
    • nelm repo update: Update info about available charts for all chart repositories.
    • nelm repo login: Log in to an OCI registry with charts.
    • nelm repo logout: Log out from an OCI registry with charts.

    Other commands

    • nelm completion [bash|fish|powershell|zsh]: Generate autocompletion scripts.
    • nelm version: Show version.

  2. Control resource deployment order with annotations

    main

    Nelm uses a Directed Acyclic Graph (DAG) to manage resource deployment. You can enforce specific ordering using the following annotations:

    • werf.io/weight: Assigns a weight to a resource. Resources with the same weight are deployed in parallel. This works for both regular resources and Helm Hooks.
    • werf.io/deploy-dependency-<id>: Prevents the annotated resource from deploying until the resource with the specified <id> is present or ready.
    • <id>.external-dependency.werf.io/resource: Prevents deployment until an external, non-release resource (e.g., one created by a third-party operator) is ready.

  3. Nelm Kubernetes requirements and limitations

    main

    Kubernetes Requirements

    Nelm requires Server-Side Apply (SSA) to be enabled in Kubernetes:

    • Kubernetes 1.16+: Enabled by default.
    • Kubernetes 1.14-1.15: Can be enabled, but is disabled by default.
    • Kubernetes 1.13 and older: Does not support SSA; Nelm will not work.

    Deployment Behavior

    Unlike standard Helm, which may use values from a previous release to deploy a new one, Nelm follows strict Infrastructure as Code (IaC) principles. Nelm will never use values from a previous release. Everything you explicitly pass via --values and --set options is merged with chart values files and applied to the cluster exactly as specified.

  4. Manage resource lifecycles with Nelm annotations

    main

    Nelm provides advanced lifecycle management that makes standard Helm Hooks largely obsolete. You can use these annotations on regular resources:

    • werf.io/delete-policy: Controls how resources are handled during deployment.
      • before-creation: Always recreate the resource.
      • before-creation-if-immutable: Only recreate if the resource is immutable.
      • succeeded: Delete the resource on successful deployment.
      • failed: Delete the resource on failed deployment.
    • werf.io/ownership: Set to anyone to prevent the resource from being deleted when the Chart or the whole release is removed. It also prevents Nelm from checking or applying release annotations.
    • werf.io/deploy-on: Controls when a resource is rendered and deployed. Options include install, upgrade, rollback, or uninstall, combined with stages like pre, main, or post (similar to Helm Hooks).

  5. Quickstart: Deploy a Helm Chart with Nelm

    main

    Follow these steps to create a new chart, manage dependencies, and perform a two-stage deployment (plan and install).

    1. Initialize the chart directory:

      mkdir mychart
cd mychart

    2. Create Chart.yaml: Define your chart metadata and dependencies.

      apiVersion: v2
name: mychart
version: 1.0.0
dependencies:
- name: cert-manager
  version: 1.13.3
  repository: https://charts.jetstack.io

    3. Download dependencies:

      nelm chart dependency download

    4. Configure values: Create a values.yaml file.

      cert-manager:
  installCRDs: true
  startupapicheck:
    enabled: false

    5. Initial Deployment: Install the release into a namespace.

      nelm release install -n myproject -r myproject

    6. Plan an update: Use the plan command to preview changes (e.g., increasing replicas) before applying them.

      nelm release plan install -n myproject -r myproject --set cert-manager.replicaCount=2

    7. Apply the update:

      nelm release install -n myproject -r myproject --set cert-manager.replicaCount=2
    mkdir mychart
cd mychart
# ... create Chart.yaml and values.yaml ...
nelm chart dependency download
nelm release install -n myproject -r myproject
nelm release plan install -n myproject -r myproject --set cert-manager.replicaCount=2
nelm release install -n myproject -r myproject --set cert-manager.replicaCount=2

  6. View logs and events during deployment

    main

    Nelm automatically finds Pods associated with deploying resources and periodically prints their container logs to the console.

    To also print resource events, add the following annotation to your resource: werf.io/show-service-messages: "true".

    These behaviors can be further configured via CLI flags or annotations.

  7. Configure fish autocompletion for nelm

    main

    To enable autocompletion for the fish shell:

    To load completions in your current session:

    nelm completion fish | source

    To configure completions for all future sessions:

    nelm completion fish > ~/.config/fish/completions/nelm.fish

    Note: You must start a new shell for the changes to take effect.

    nelm completion fish

  8. Manage encrypted arbitrary files

    main

    Arbitrary files can be encrypted and stored in the secret/ directory of a Helm chart. They are decrypted in-memory during templating.

    Note: The NELM_SECRET_KEY environment variable must be set for any command that encrypts or decrypts secrets, including nelm chart render.

    Workflow:

    1. Create a secret key.
    2. Edit the secret file using nelm chart secret file edit secret/<filename>.
    3. Reference the file in your templates using the werf_secret_file function.
    # Create a secret key
export NELM_SECRET_KEY="$(nelm chart secret key create)"

# Create/edit an encrypted file in the secret/ directory
nelm chart secret file edit secret/config.yaml

    Template usage:

    # secret/config.yaml
user: john-doe

# template.yaml
config: {{ werf_secret_file "config.yaml" | nindent 4 }}

  10. Manage encrypted values files

    main

    You can encrypt values files (e.g., secret-values.yaml) and store them in a Helm chart or git repo. They are decrypted in-memory during templating.

    Note: The NELM_SECRET_KEY environment variable must be set for any command that encrypts or decrypts secrets, including nelm chart render.

    Workflow:

    1. Create a secret key.
    2. Edit the secret values file using nelm chart secret values-file edit <filename>.
    3. Reference the values in your templates using standard Helm syntax: {{ .Values.key.name }}.
    # Create a secret key
export NELM_SECRET_KEY="$(nelm chart secret key create)"

# Create/edit a secret-values file
nelm chart secret values-file edit secret-values.yaml

    Template usage:

    # secret-values.yaml
password: verysecurepassword123

# template.yaml
password: {{ .Values.password }}

  11. Lookup external API and library knowledge

    main

    Avoid guessing API signatures or library behaviors. Use the following hierarchy to find accurate information:

    1. Internal Source: Use lsp(operation="goToDefinition") to navigate to the actual source of a dependency.
    2. Up-to-date Documentation: Use context7_resolve-library-id followed by context7_query-docs to get current documentation.
    3. Real-world Usage: Use grep_app_searchGitHub to see how other projects implement the library.
    4. Recent/Web Information: Use websearch_web_search_exa for information post-dating your training cutoff.
    5. Specific URLs: Use webfetch to retrieve content from a specific documentation page or GitHub issue.

  12. Perform semantic code search with CodeAlive

    main

    For intent-based or behavioral queries (e.g., "how does the DAG work?"), use CodeAlive MCP tools instead of grep. grep should only be used for simple literal matching of specific strings or config keys.

    Workflow:

    1. Mandatory Setup: Always call codealive_get_data_sources before using any CodeAlive tool.
    2. Semantic Search: Use codealive_codebase_search to find code based on intent or behavior.
    3. Architectural Advice: Use codealive_codebase_consultant for high-level explanations of how packages relate or why certain architectural decisions were made.
    4. Structural Patterns: Use ast_grep_search to find code patterns based on the Abstract Syntax Tree (AST) rather than text (e.g., finding all functions with a specific signature).

    Tool Priority: codealive_codebase_search / codealive_codebase_consultant → ast_grep_search → grep / glob.

    # 1. Initialize data sources
codealive_get_data_sources

# 2. Search for intent
codealive_codebase_search(query="how does release planning work?")