- Normal deployment
- Deploying using custom image tags
- Deploying without access to the application’s Git repository
- Deploying without access to an application’s Git repository and container registry
- Deploying with a third-party tool
- Deploying with a third-party tool without access to the application’s Git repository
- Saving a deployment report
- Deleting a deployed application
Normal deployment
A normal deployment is carried out by the werf converge
command. It builds images and deploys the application but requires the application’s Git repository to run. Example:
werf converge --repo example.org/mycompany/myapp
You can separate the build and deployment steps as follows:
werf build --repo example.org/mycompany/myapp
werf converge --require-built-images --repo example.org/mycompany/myapp
Deploying using custom image tags
By default, built images are tagged based on their contents. The tag becomes available in Values and allows those images to be used in templates during deployment. But if you want to use a different tag for the images, you can use the --use-custom-tag
parameter, for example:
werf converge --use-custom-tag '%image%-v1.0.0' --repo example.org/mycompany/myapp
Running the command above will result in the images being assembled, tagged with <name image>-v1.0.0
, and published. The tags of those images will then become available in Values. The final Kubernetes manifests will then be generated and applied based on those tags.
The tag name set by the --use-custom-tag
parameter supports the %image%
, %image_slug%
, and %image_safe_slug%
patterns to substitute the image name and %image_content_based_tag%
to substitute the original content-based tag.
Note that when you set a custom tag, an image with a content-based tag is published as well. Later on, when
werf cleanup
is invoked, the image with the content-based tag and the images with arbitrary tags are deleted together.
You can separate the assembly and deployment steps like this:
werf build --add-custom-tag '%image%-v1.0.0' --repo example.org/mycompany/myapp
werf converge --require-built-images --use-custom-tag '%image%-v1.0.0' --repo example.org/mycompany/myapp
Deploying without access to the application’s Git repository
To deploy the application with no access to the application’s Git repository, follow these three steps:
-
Build images and publish them to the container registry.
-
Add the passed parameters and publish the main chart to the OCI repository. The chart contains references to the images published in the first step.
-
Apply the published bundle to the cluster.
The first two steps are carried out by the werf bundle publish
command from the application’s Git repository, for example:
werf bundle publish --tag latest --repo example.org/mycompany/myapp
The third step is carried out by the werf bundle apply
command, but you don’t have to be in the application’s Git repository; for example:
werf bundle apply --tag latest --release myapp --namespace myapp-production --repo example.org/mycompany/myapp
You will end up with the same result as with werf converge
.
You can separate the first and second steps as follows:
werf build --repo example.org/mycompany/myapp
werf bundle publish --require-built-images --tag latest --repo example.org/mycompany/myapp
Deploying without access to an application’s Git repository and container registry
Follow these five steps to deploy an application with no access to the application’s Git repository and the container registry:
-
Build images and publish them to the container registry of the application.
-
Add the passed parameters and publish the main chart to the OCI repository. The chart contains pointers to the images published in the first step.
-
Export the bundle and its related images to a local archive.
-
Import the archived bundle and its images into the container registry accessible from the Kubernetes cluster used for deployment.
-
Apply the bundle published in the new container registry to the cluster.
The first two steps are handled by the werf bundle publish
command running in the application’s Git repository, for example:
werf bundle publish --tag latest --repo example.org/mycompany/myapp
The third step is handled by the werf bundle copy
command (no need to be in the application’s Git repository), for example:
werf bundle copy --from example.org/mycompany/myapp:latest --to archive:myapp-latest.tar.gz
The local myapp-latest.tar.gz
archive can now easily be pushed to the container registry used for deployment to the Kubernetes cluster, and again the werf bundle copy
command comes into play, for example:
werf bundle copy --from archive:myapp-latest.tar.gz --to registry.internal/mycompany/myapp:latest
As a result, the chart and its associated images will be published to the new container registry accessible from the Kubernetes cluster. All that remains is to deploy the published bundle to the cluster using the werf bundle apply
command like this:
werf bundle apply --tag latest --release myapp --namespace myapp-production --repo registry.internal/mycompany/myapp
This step no longer requires access to either the application’s Git repository or its original container registry. The end result of deploying the bundle will be the same as when using `werf converge’.
You can separate the first and second step, if necessary:
werf build --repo example.org/mycompany/myapp
werf bundle publish --require-built-images --tag latest --repo example.org/mycompany/myapp
Deploying with a third-party tool
To apply the final application manifests with a tool other than werf (kubectl, Helm, etc.) follow the steps below:
-
Build images and publish them to the container registry.
-
Render the final manifests.
-
Deploy those manifests to a cluster using a third-party tool.
The first two steps are carried out by the werf render
command from the application’s Git repository:
werf render --output manifests.yaml --repo example.org/mycompany/myapp
You can now pass the rendered manifests to a third-party tool for deployment:
kubectl apply -f manifests.yaml
Note that some special features of werf, like the ability to reorder resource deployments based on their weight (using the
werf.io/weight
annotation), most likely won’t work when the manifests are applied by a third-party tool.
You can separate the first and second steps as follows:
werf build --repo example.org/mycompany/myapp
werf render --require-built-images --output manifests.yaml --repo example.org/mycompany/myapp
Deploying with a third-party tool without access to the application’s Git repository
To deploy the application using some third-party tool (kubectl, Helm, etc.), and there’s no access to the application’s Git repository, follow these three steps:
-
Build images and publish them to the container registry.
-
Add the passed parameters and publish the main chart to the OCI repository. The chart contains references to the images published in the first step.
-
Render the final manifests using the bundle.
-
Deploy those final manifests to a cluster using a third-party tool.
The first two steps are carried out by the werf bundle publish
command from the application’s Git repository:
werf bundle publish --tag latest --repo example.org/mycompany/myapp
The third step is carried out by the werf bundle render
command, but this time, you don’t have to be in the application’s Git repository; for example:
werf bundle render --output manifests.yaml --tag latest --release myapp --namespace myapp-production --repo example.org/mycompany/myapp
You can now pass the rendered manifests to a third-party tool for deployment, e.g.:
kubectl apply -f manifests.yaml
Note that some special features of werf, like the ability to reorder resource deployments based on their weight (using the
werf.io/weight
annotation), most likely won’t work when the manifests are applied by a third-party tool.
You can separate the first and second steps as follows:
werf build --repo example.org/mycompany/myapp
werf bundle publish --require-built-images --tag latest --repo example.org/mycompany/myapp
Saving a deployment report
The werf converge
and werf bundle apply
commands come with the -save-deploy-report
parameter. You can use it to save a report about the deployment to a file. The report contains the release name, Namespace, deployment status, and some other data. Here is a usage example:
werf converge --save-deploy-report
Running the command above will create a .werf-deploy-report.json
file containing information about the latest release once the deployment is complete.
The custom path to the deployment report can be set with the --deploy-report-path
parameter.
Deleting a deployed application
You can delete a deployed application using the werf dismiss
command run from the application’s Git repository, for example:
werf dismiss --env staging
You can explicitly specify the release name and Namespace if there is no access to the application’s Git repository:
werf dismiss --release myapp-staging --namespace myapp-staging
… or you can use a previous deployment report which contains the release name and Namespace. You can enable saving this report by using the --save-deploy-report
flag of the werf converge
or werf bundle apply
commands.
werf converge --save-deploy-report
cp .werf-deploy-report.json /anywhere
cd /anywhere
werf dismiss --use-deploy-report
The custom path to the deployment report can be set with the --deploy-report-path
parameter.