What is werf?

werf is a CLI tool for implementing a full deployment cycle for your application using Git as a single source of truth. werf can:

  • Build docker images.
  • Deploy the application into the Kubernetes cluster.
  • Make sure the application is up and running well after the deploy is complete.
  • Re-build docker images when application code changes.
  • Re-deploy the application into the Kubernetes cluster when necessary.
  • Clean up irrelevant and unused images.

How it works?

werf configuration should be stored in the application Git repository along with the application code.

Pay attention to the crucial project parameter that stores a project name since werf will be using it extensively during the converge process. Changing this name later, when your application is up and running, involves downtime, and requires re-deploying the application.

werf_image is a special template function for generating the full name of the image that was built. This function has a name parameter that corresponds to the image defined in the werf.yaml ("frontend" or "backend" in our case).

At this step, werf calculates the target image names. Image names may change or stay the same after the new commit is made depending on the changes in the Git repository. Note that each Git commit is associated with deterministic and reproducible image names.

What is converge?

Converge is the process of building docker images (and re-building them in response to changes), deploying an application into the Kubernetes cluster (and re-deploying it when necessary), and making sure that the application is up and running.

The werf converge command starts the converging process. The command can be invoked by a user, by a CI/CD system, or by an operator in response to changes in the state of an application in Git. The behavior of the werf converge command is fully deterministic and transparent from the standpoint of the Git repository (read more about giterminism here). After the converge command is complete, your application will be up and running in the state defined in the target Git commit. Typically, to roll back your application to the previous version, you only need to run the converge on the corresponding earlier commit (werf will use correct images for this commit).

Run the following command in the root of your project to converge:

werf converge --docker-repo myregistry.domain.org/example-app [--kube-config ~/.kube/config]

Generally, the converge command has only one mandatory argument: the address of the docker repository. werf will use this docker repository to store built images and use them in Kubernetes (thus, this docker repository must be accessible from within the Kubernetes cluster). Kube-config is another optional argument that defines the Kubernetes cluster to connect to. Also, there is an optional --env parameter (and the WERF_ENV environment variable) allowing you to deploy an application into various environments.

NOTE: If your application does not use custom docker images (e.g., it uses only publicly available ones), you do not have to pass --docker-repo parameter to the command and may just omit it.

What’s next?

Deploy your first demo application with this quickstart or check the guides – they cover the configuration of a wide variety of applications based on different programming languages and frameworks. We recommend finding a manual suitable for your application and follow instructions.

Refer to this article if you feel like you are ready to dig deeper into the general overview of CI/CD workflows that can be implemented with werf.