You need to know a few features and peculiarities of werf to use it confidently and comfortably:
- Firstly, you need to understand the principles of working with source code and what giteminism is — they ensure that the application can be reproduced in any environment.
- Secondly, you need to understand the process for tagging images. Do you need to add tags to them manually to build and deploy an image (no, with werf, you do not need to)?
- When deploying to various environments, you will learn about the concept of a release as well as the process of debugging them.
- After some time, due to continuous application improvements and regular releases, you may face the shortage of space in the image storage, and the need to delete unneeded images. Werf provides mechanisms that simplify this task considerably.
All these issues are discussed in more detail below.
Working with source code and giterminism
Often, some settings that affect the configuration of the deployed application depend on “external” data: files that exist on the runner, some dynamic measures emanating from external resources, etc. This directly leads to the inability to guarantee the reproducibility of the application state.
To ensure reproducibility, werf, by default, considers only states that are committed to Git. In other words, Git is the primary and sufficient source of information about the application.
However, we understand that committing every code change during the development isn’t feasible for many reasons. That is why werf has a special --dev
mode to ease the development and make it more convenient. Also, in some situations, the build must depend on the external context. In these rare cases, you can configure the giterminism settings via the werf-giterminism.yaml
file.
werf-giterminism.yaml
Using this congfig file, you can eliminate some restrictions in a specific configuration (e.g., using uncommitted files, mounting directories and files during the build, passing environment variables, etc.). You can learn more about the configuration process in the documentation.
dev mode
If you run converge
(or any other command — e.g., render
) with the --dev
CLI parameter:
werf converge --repo registry.example.com/werf-guided-nodejs --dev
… then werf will build and deploy not only committed but tracked files (added via git add
) as well.
follow mode
The follow mode is another useful special-purpose werf mode. If you run the converge
or another command (e.g., run
or compose up
) with the CLI parameter --follow
:
werf converge --repo registry.example.com/werf-guided-nodejs --follow
… then the command will be automatically restarted with every new commit to Git.
If combining --follow
and --dev
parameters, the command will be restarted in response to the git add
command.
Tagging images
In the manual deployment process (i.e., without werf), you have to define the strict rules for tagging images and follow them (it is no easy task, frankly). However, you may have noticed that we use the image: {{ .Values.werf.image.basicapp }}
construct in werf charts:
- name: basicapp
command: ["node","/app/app.js"]
image: {{ .Values.werf.image.basicapp }}
werf frees you of worries about tagging rules: if there are changes in the code, it will rebuild the appropriate image, add service tags to it, push it to the registry, and insert the applicable image name into the templates. For this, werf stores metadata in the registry and tracks the file contents in the Git repository.
Helm, releases, and more
Helm-chart is a collection of files that describe a related set of Kubernetes objects. A release is created when a chart is used to deploy an application to a specific environment.
When working with releases, helm implements the 3-way merge approach. Manual changes to the cluster that conflict with the state described in Git are corrected to conform to the latter. Note that manual changes that do not conflict with the state defined in Git remain outside the control of Helm and werf.
werf manages releases on its own, but if you want to do it the hard way, you can use the werf helm <...>
commands.
How do I list the installed components?
Releases provide information about components installed in the cluster, their state, and the environment they are running in.
To browse the list of releases or find out the name of the release you need, use the werf helm list -A
CLI command.
How do I delete the unneeded component?
Use werf helm uninstall
to uninstall an application.
Debugging the installation process
Frequently, mistakes made in chart configurations lead to problems when rolling out a release. The werf render
command can help you to debug such problems.
werf render
performs all the actions related to building and generating charts, showing you the resulting charts instead of deploying the release to Kubernetes. It is a resource-intensive task that shows you the final result with all the required values filled in.
Note that werf render
only works with files committed to Git (like all other werf commands) but supports the --dev
mode.
Storage space
Over time, a lot of data can accumulate in the storage (either local or in the registry). Werf has three built-in commands related to cleaning: werf cleanup
, werf purge
, werf host purge
. They have different purposes, and we briefly discuss them below (the detailed information is available in the documentation).
Regular registry cleanup
The werf cleanup
command performs a regular and safe cleanup. It safely deletes images that are no longer needed using an advanced algorithm that takes into account Git history, registry contents, and the cluster state.
We will configure scheduled registry cleanup using the CI system’s tools in the chapter “Working with infrastructure”.
Delete all
The following two service commands allow you to free up disk space by deleting all images and other data:
werf host purge
deletes all host contents, leaving the registry intact.werf purge
(NOT SAFE) deletes all images, including those linked to applications running in the cluster!