werf — Consistent Delivery Tool for Kubernetes

Introduction

werf is a CLI tool that combines container image building, Helm-based deployment, and artifact lifecycle management into a single consistent workflow for Kubernetes. It is designed to integrate into any CI/CD system and enforce reproducible, content-addressed builds with automatic registry cleanup.

What werf Does

• Builds container images using Dockerfiles or its own Stapel builder with layered caching
• Deploys to Kubernetes using Helm-compatible charts with enhanced tracking and rollback
• Tags images by content digest rather than Git branch or commit SHA for deterministic deploys
• Cleans unused images from the container registry based on configurable retention policies
• Integrates with GitLab CI, GitHub Actions, Jenkins, and other CI systems out of the box

Architecture Overview

werf reads a werf.yaml configuration that declares images, build instructions, and the Helm chart location. During the converge phase, werf builds images (using Buildah under the hood), pushes them to a registry with content-based tags, and runs a Helm-compatible release with enhanced resource tracking. It monitors Kubernetes resource readiness and can roll back automatically on failure. A built-in cleanup command scans the registry and removes images that are no longer referenced by Git history.

Self-Hosting & Configuration

• Install via the official install script, Homebrew, or as a standalone binary
• Define images and build instructions in werf.yaml at the project root
• Place Helm chart templates in .helm/templates/ alongside werf.yaml
• Configure registry credentials via Docker config or environment variables
• Set cleanup policies in werf.yaml to control image retention by branch, tag, or age

Key Features

• Content-based image tagging that guarantees the same source produces the same tag
• Enhanced Helm deployments with real-time resource tracking and failure detection
• Built-in registry cleanup that removes orphaned images automatically
• Stapel builder for advanced multi-stage builds with Ansible provisioning
• Giterminism mode that ensures builds are fully reproducible from Git state

Comparison with Similar Tools

• Helm — package manager for Kubernetes charts; werf adds image building, content tagging, and cleanup on top of Helm
• Skaffold — development workflow tool by Google; werf targets production CI/CD with stricter reproducibility
• Flux/Argo CD — GitOps controllers that sync manifests; werf handles the build-push-deploy pipeline before GitOps takes over
• Kaniko — in-cluster image builder; werf provides a complete delivery pipeline beyond just building images
• Tilt — inner-loop Kubernetes development; werf focuses on outer-loop CI/CD delivery

FAQ

Q: Does werf replace Helm? A: Not entirely. werf uses Helm internally for templating and release management but adds image building, content-based tagging, and cleanup that Helm does not provide.

Q: Can I use standard Dockerfiles with werf? A: Yes. werf supports both standard Dockerfiles and its own Stapel syntax for image definitions.

Q: What is giterminism? A: Giterminism is werf's mode that restricts builds to only use files committed to Git, ensuring fully reproducible builds regardless of local workstation state.

Q: Does werf work outside of CI/CD? A: Yes. You can run werf converge from a local machine, but it is designed primarily for automated CI/CD pipelines.

Sources

• https://github.com/werf/werf
• https://werf.io