Skip to content

Commit

Permalink
[docs] Reject stages cache term
Browse files Browse the repository at this point in the history
  • Loading branch information
alexey-igrychev committed May 17, 2019
1 parent 87cc0a6 commit 8e8988b
Show file tree
Hide file tree
Showing 5 changed files with 7 additions and 7 deletions.
2 changes: 1 addition & 1 deletion docs/_includes/cli/werf_build_and_publish.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ built for each tag of each image from werf.yaml. Images will be pushed into dock
names IMAGES_REPO/IMAGE_NAME:TAG. See more info about images naming:
https://werf.io/reference/registry/image_naming.html.

The result of build-and-publish command is a stages cache for images and named images pushed into
The result of build-and-publish command is stages in stages storage and named images pushed into
the docker repo.

If one or more IMAGE_NAME parameters specified, werf will build images stages and publish only
Expand Down
2 changes: 1 addition & 1 deletion docs/pages/reference/build/artifact.md
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ Read about working with _git repositories_ in the corresponding [article]({{ sit

Directives and _user stages_ remain unchanged: _beforeInstall_, _install_, _beforeSetup_ and _setup_.

If there are no dependencies on files specified in git `stageDependencies` directive for _user stages_, the image is cached after the first build and will no longer be reassembled while the _stages cache_ exists.
If there are no dependencies on files specified in git `stageDependencies` directive for _user stages_, the image is cached after the first build and will no longer be reassembled while the related _stages_ exist in _stages storage_.

> If the artifact should be rebuilt on any change in the related git repository, you should specify the _stageDependency_ `**/*` for any _user stage_, e.g., for _install stage_:
```yaml
Expand Down
2 changes: 1 addition & 1 deletion docs/pages/reference/build/as_layers.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,4 +25,4 @@ Switching between assembly mode is only governed by the _asLayers directive_. Ot

_asLayers_ directive allows caching of individual instructions. If `--introspect-error` and `--introspect-before-error` introspection options are used, users may retrieve the environment before or after execution of a problem instruction.

> It is important not to use this instruction in the course of regular assembly of images: this mode generates an excessive number of docker images and is not intended for incremental assembly (due to a longer timeout and greater size of _stages cache_).
> It is important not to use this instruction in the course of regular assembly of images: this mode generates an excessive number of docker images and is not intended for incremental assembly (due to a longer timeout and greater size of _stages_).
2 changes: 1 addition & 1 deletion docs/pages/reference/build/assembly_process.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,4 +15,4 @@ Multiple build commands can run at the same time on the same host. When building

When another build process is holding a lock for a stage, werf waits until this process releases a lock. Then werf proceeds to the next stage.

The reason is no need to build the same stage multiple times. Werf build process can wait until another process finishes build and puts _stage_ into the _stages cache_.
The reason is no need to build the same stage multiple times. Werf build process can wait until another process finishes build and puts _stage_ into the _stages storage_.
6 changes: 3 additions & 3 deletions docs/pages/reference/build/git_directive.md
Original file line number Diff line number Diff line change
Expand Up @@ -373,7 +373,7 @@ Build sequence for these commits may be represented as follows:
| Commit No. 2 is made, build at 10:05 | files as in commit No. 1 | --- | files as in commit No. 2 |
| Commit No. 3 is made, build at 10:15 | files as in commit No. 1 | --- | files as in commit No. 3 |

A space between the layers in this table is not accidental. After a while, the number of commits grows, and the patch between commit No. 1 and the current commit may become quite large, which will further increase the size of the last layer and the total size of the _stages cache_. To prevent the growth of the last layer werf provides another intermediary stage — _gitCache_.
A space between the layers in this table is not accidental. After a while, the number of commits grows, and the patch between commit No. 1 and the current commit may become quite large, which will further increase the size of the last layer and the total _stages_ size. To prevent the growth of the last layer werf provides another intermediary stage — _gitCache_.
How does werf work with these three stages? Now we are going to need more commits to illustrate this, let it be `1`, `2`, `3`, `4`, `5`, `6` and `7`.

- Build of commit No. 1. As before, files are added to a single layer based on the configuration of the _git mappings_. This is done with the help of the git archive. This is the layer of the _gitArchive_ stage.
Expand All @@ -384,7 +384,7 @@ How does werf work with these three stages? Now we are going to need more commit
- Build of commit No. 6. The size of the patch between `1` and `6` exceeds 1 MiB. Now _gitCache_ stage layer is modified.
- Build of commit No. 7. The layer of the _gitLatestPatch_ stage is modified by applying the patch between `6` and `7`.

This means that as commits are added starting from the moment the first build is done, big patches are gradually accumulated into the layer for the _gitCache_ stage, and only patches with moderate size are applied in the layer for the last _gitLatestPatch_ stage. This algorithm reduces the size of the _stages cache_.
This means that as commits are added starting from the moment the first build is done, big patches are gradually accumulated into the layer for the _gitCache_ stage, and only patches with moderate size are applied in the layer for the last _gitLatestPatch_ stage. This algorithm reduces the size of _stages_.

| | gitArchive | gitCache | gitLatestPatch |
|---|:---:|:---:|:---:|
Expand All @@ -400,7 +400,7 @@ This means that as commits are added starting from the moment the first build is

### Rebuild of gitArchive stage

For various reasons, you may want to reset the _gitArchive_ stage, for example, to decrease the size of the _stages cache_ and the image.
For various reasons, you may want to reset the _gitArchive_ stage, for example, to decrease the size of _stages_ and the image.

To illustrate the unnecessary growth of image size assume the rare case of 2GiB file in git repository. First build tranfers this file in the layer of the _gitArchive_ stage. Then some optimization occured and file is recompiled and it's size is decreased to 1.6GiB. The build of this new commit applies patch in the layer of the _gitCache_ stage. The image size become 3.6GiB of which 2GiB is a cached old version of the big file. Rebuilding from _gitArchive_ stage can reduce image size to 1.6GiB. This situation is quite rare but gives a good explanation of correlation between the layers of the _git stages_.

Expand Down

0 comments on commit 8e8988b

Please sign in to comment.