Helmsnap

About

Helmsnap is a tool for generating and checking helmfile snapshots. Example:

Generate snapshots (uses helmfile template under the hood):

helmsnap generate

Generate snapshots in a temporary directory and check (diff) them against existing snapshots in helm/snapshots directory:

helmsnap check

Just build dependencies for each release in a helmfile:

helmsnap dependencies # or `helmsnap deps`

Get the full description of possible arguments:

helmsnap --help

The typical usage flow:

1. You generate some snapshots using helmsnap generate command and check them into your git repo.
2. You add helmsnap check command to your CI (or run it manually on every commit).
3. In case snapshots differ, you should carefully check the updates and either fix your chart or update the snapshots using helmsnap generate.

This tool can also be useful when you are developing a new chart or updating an existing one: you can generate snapshots and see what is rendered without need to deploy the chart in your cluster.

Configuration

By default, helmsnap will render your helmfile using default environment and will place snapshots in helm/snapshots directory. If you want to configure that, or you need to provide credentials for access to private helm repos, you can create a .helmsnap.yaml file and put there configuration that looks like this:

envs: [staging, production] # `[default]` by default
snapshotsPath: somedir/snapshots # `helm/snapshots` by default
credentials: # [] by default
- repo: https://example.com/some/path/to/repo
  username: someuser
  password: somepassword

Credentials will be matched by prefix, so if your repo URL is https://example.com/some/path/to/repo, you can also put values like https://example.com/some/path or https://example.com in credentials.[].repo.

You can also override configuration file location using --config option.

Dependencies

The Docker runtime pins Helm 4.3.0 and Helmfile 1.8.1 by version and immutable multi-architecture image digest. For example, helm version --short reports v4.3.0 and helmsnap --version reports the packaged library version. Runtime builds copy only the gem specification, library, executable and public documentation; they do not depend on Git metadata or include checkout credentials and local dependency caches.

Helm 4.3 supports Kubernetes 1.34–1.37 according to Helm's version policy. Rendering local chart snapshots does not establish compatibility with an older live API server. The upgrade sequence must supply its separately verified compatible client and cluster-version gate before live operations on earlier versions.

The Docker build refreshes Alpine packages before adding runtime dependencies. The Docker workflow checks packaged tool versions and scans the loaded image with Trivy 0.75.0 against the current vulnerability database before publication. HIGH and CRITICAL findings, including those without a published fix, fail the job; lower severities remain visible but do not block it. Branches and pull requests run the checks, and only a push to master publishes the workflow image. The separate release workflow preserves versioned gem/image publication. bundle exec rake checks the library, packaging from a source tree without Git, and Ruby style.

• Ruby 3.3+.
• Helmfile, which in turn relies on Helm.
• Colordiff or diff utility.

Features

Helm dependency management

Helmsnap will automatically rebuild your chart dependencies on every snapshot generation or check. In case your dependency is using url to some local helm repo and you don't have a proper repo added, it will add it automatically which is useful in CI. It also will detect local dependencies (those that start with file://) and rebuild their dependencies as well.

Timestamp replacement

Helmsnap will automatically replace all occurencies of patterns that look like timestamps (format like 2022-01-01 00:00:00.000) in your templates. This is useful in case you have some annotations like releaseTime that would break your snapshots checks otherwise.

Installation

Just install the gem and use the provided helmsnap binary.

gem install helmsnap

Alaternatively, you can use the Docker image with Ruby, helm and helmsnap gem preinstalled. This is useful for CIs or if you don't want to install Ruby and Helmfile on your machine. Here is an example docker command that can be used to generate snapshots:

docker run --rm -it -w /wd -v $PWD:/wd ghcr.io/tycooon/helmsnap helmsnap generate

CI example

Example job for Gitlab CI:

check-snapshots:
  stage: test
  image: ghcr.io/tycooon/helmsnap:latest
  script: helmsnap check

Contributing

Bug reports and pull requests are welcome.

License

The gem is available as open source under the terms of the MIT License.