github.com/GoogleContainerTools/skaffold/v2@v2.13.2/docs-v2/design_proposals/digest-tagger.md (about)

     1  1# Improve taggers
     2  
     3  * Author(s): David Gageot (@dgageot)
     4  * Date: 4 September 2019
     5  
     6  ## Background
     7  
     8  So far, Skaffold supports multiple taggers or tag policies:
     9  
    10   + the `git` tagger uses git commits/references to tag images.
    11   + the `sha256` tagger uses `latest` or the tag specified on the artifact's image name.
    12   + the `envTemplate` tagger uses environment variables to tag images.
    13   + the `datetime` tagger uses current date and time, with a configurable pattern.
    14  
    15  The default tagger, if none is specified in the `skaffold.yaml`, is the `git` tagger.
    16  
    17  Here are some rules about how tagging currently works:
    18  
    19   + **Image tags are computed before the images are built**. In early versions of Skaffold, we tried
    20     to compute tags after the build. It made the process super complex with a lot of retagging.
    21     It also produced images that were tagged with their own digest or imageID which is superfluous
    22     since those can be used to reference the images directly.
    23   + **No matter the tagger, Skaffold always uses immutable references in Kubernetes manifests**.
    24     Which reference is used depends on whether the images are pushed or not:
    25       + **When images are pushed**, their immutable digest is available. Skaffold then references
    26         images both by tag and digest. Something like `image:tag@sha256:abacabac...`.
    27         Using both the tag and the digest seems superfluous but it guarantees immutability
    28         and helps users quickly see which version of the image is used.
    29       + **When images are not pushed**, digests are not available. We have the tags and the
    30         imageIDs. Since imageIDs can't be used in Kubernetes manifests, Skaffold creates
    31         an additional immutable tag with the same name as the imageID and uses that in manifests.
    32         Something like `image:abecfabecfabecf...`.
    33   + **Skaffold never references images just by their tags** because those tags are mutable and
    34     can lead to cases where Kubernetes will use an outdated version of the image.
    35  
    36  ## Issues
    37  
    38   + the `git` tagger requires users to install `git`. It also requires the project to be
    39     a git project, which is typically not the case when users just try to get started.
    40     **So the `git` tagger seems like a wrong choice for a default tagger**.
    41   + `sha256` is a misleading name. It is named like that because, in the end, when Skaffold
    42     deploys to a remote cluster, the image's sha256 digest is used as the immutable tag.
    43     **Users are confused with this name and behavior**.
    44   + the `sha256` used to be able to use the image tags provided in the artifact definition,
    45     instead of `latest`. This was not documented and is not possible anymore because artifact
    46     definitions are now considered invalid if images names have a tag.
    47     **The new way to achieve that goal is to use the `envTemplate` tagger**
    48   + the `envTemplate` tagger used to be able to replace `{{.DIGEST}}` with the image's imageID
    49     or digest. **This was buggy and is not possible anymore since tags are computed before the
    50     images are built and those digest are only available after the image is built or pushed.**
    51   + users have asked for a tagger that uses the inputs' digest as a tag. **They think that's
    52     what the `sha256` tagger should do.**
    53     
    54  ## Proposal
    55  
    56   + we introduce a `latest` tagger that tags images with `:latest`.
    57   + the `latest` tagger is used by default instead of the `git` tagger.
    58   + `sha256` tagger is deprecated.
    59   + `datetime` tagger is kept as is.
    60   + `git` tagger is kept as is but is no longer the default.
    61   + An `inputDigest` is added. It uses the digest of the artifact's inputs as the tag.
    62     [#2301](https://github.com/GoogleContainerTools/skaffold/pull/2301) tried to implement
    63     such tagger by computing the digest of the whole workspace. We should instead compute
    64     the digest of the artifact's dependencies, including the artifact's configuration. This
    65     is exactly what the caching mechanism currently does.
    66   + An `userGenerated` is added. This is for special cases where the user can pass command 
    67     that will execute and output the tag for a given image. It will make some room for integration
    68     with maven, gradel, bazel (and probably other build tools) that can fallow more precisely 
    69     dependency graph of a given executable. With time these plugins could become integrated 
    70     into a skaffold code base. Or at least be officially supported. It is also important to note 
    71     that this is a more complicated case. If a plugin model is to be adopted the tagger configuration 
    72     can't happen on a global level. Because different images will use different plugins. Even a simple
    73     projects will have (as an example) react and java docker images. And those will use different 
    74     methods for tag generation. So, the artifact object has be extended, to allow overriding of the 
    75     global tagger with a custom one. For now, it will be a bash command that can only output a 
    76     singe string that will becomes image's tag.
    77   + `envTemplate` learns how to replace `{{.DIGEST}}` with a digest of the artifact's
    78      inputs as computed by the `inputDigest` tagger.
    79   + **No matter the tagger, Skaffold will keep on using immutable references in manifests**.
    80     + by tag and digest, when images are pushed.
    81     + by imageID (used as a tag), when images are not pushed.
    82  
    83  ## Open Issues/Questions
    84  
    85   + How do we handle users who didn't configure a tagger and were happy with the default
    86     being the `git` tagger?
    87   + How do we handle users who were happy with `sha256` tagger?
    88  
    89  When no `tagPolicy` is used or when a deprecated tagger is used, we will have to
    90  show a warning to the user.
    91  
    92  For all the above changes we need clear communication in the release notes.