The standard usage of the docker tag command is:
docker tag <image> <username>/<repository>:<tag>
So for example: docker tag friendlyhello john/get-started:part1.
Coming from Java-land, I'm used to Maven/Gradle-style coordinates of group:artifact:version, so to me, it makes sense for the image and the repository to be one in the same:
The image is the artifact you're producing, and in Java-land there's usually a 1:1 relationsip between the generated artifact and the source repo its code lives inside of. So to me, it makes more sense for the command to be just:
docker tag <username>/<repository>:<tag>
So for example: docker tag john/get-started:part1, where john is the username/group, get-started is the artifact/repo and part1 is the tag/version.
TO BE CLEAR: I am not asking what the difference is between an image and a repository! I understand that a repository is a location where images are stored, and I understand that an image is a Docker executable consisting of your Dockerized app and its dependencies. But from a naming standpoint, I'm confused as to why/when they should ever be different from each another.
So I ask: what is the difference between an image and a repository from a naming convention standpoint? For example if I wanted to make my own MySQL Docker image, I'd chose to make the image named "myapp-db", and that would also be the name of the repository where it lived (smeeb/myapp-db:v1, smeeb/myapp-db:v2, etc.).
So under what circumstances are/should image and repository names be different?
First a prerequisite: a tag is a pointer to an image, and an image is a sha256 reference to a manifest of configuration and layers that docker uses to make containers. What that means is that friendlyhello is not the name of an image, it's a tag that points to an image. The image is the id, something like c75bebcdd211.....
Next, each image can have zero, one, or multiple tags all pointing to it. When it doesn't have any tags pointing to it, that's referred to as a dangling image. That can happen if you build an image with a tag, and then rebuild it. The previous image is now untagged because the tag is pointing to the new image. Similarly you can have the tags image:latest, image:v1, image:1.0.1, and myrepo:5000/image:1.0 all pointing to the same image id.
Tags have a dual use. They can be for convenience. But they are also used by docker push and docker pull to lookup where to send or retrieve the package. If you don't do a push or a pull, then you can name it whatever you want and no one will know the difference. But if you do want to store it on a registry, the tag needs to identify which registry, or the default docker hub. And that tag also needs to identify the path on the registry, called the repository, and the versioning after the colon.
One confusing bit is that the short name at the end of the repository name is often called an "image name", and the versioning after the colon is often called a "tag", and I think this is much easier to understand if you forget those terms were ever overloaded like that.
Now with all that background (sorry, that was a lot), here are a few corrections to the question:
Instead of:
docker tag <image> <username>/<repository>:<tag>
Think of the syntax as:
docker tag <source> <tag>
Where <source> can be an image id, or another tag name. This means the following command won't make sense:
docker tag <username>/<repository>:<tag>
Because docker tag needs a source to tag, and it has no sense of context for what image you are currently working with.
Lastly, why would you use a name other than your repository name for an image, here are a few reasons I've encountered:
The image won't be pushed to a repository. It could be for local testing, or an intermediate step in a workflow, or you build and run your images on the same system.
You may have multiple names for the same image. registry/repo/image:v1 and registry/repo/image:v1.0.1 is a common example. I'll also tag the current image in a specific environment with registry/repo/image:STAGE to note that it made it through dev and CI and is now in the staging environment.
You may be moving images between registries. We pull images from hub.docker.com and retag them locally with a local registry. That gives us both a local cache and also a way to control when we update our base images to the next version. That's preferable to having an update image update in the middle of a production rollout.
I've also used tags to override upstream images. So instead of changing all my build scripts for an issue I have with an upstream image, I can just make my change and tag it with the upstream name. Then as long as I don't run a pull on that docker host, the builds will run using my modified base image.
One situation where you can have an image with a different tag than the repository name is if you have an image in use that is outdated.
For instance you download and run a MySQL:5 image. This container is still running when you pull a newer version of the MySQL:5 image. At that point the old image will be untagged (identifiable only by its hash), but not deleted, because it is still in use by the running MySQL container.
Another situation is that you can have intermediate images while building a new image. Basically each line gets committed as a new image, but they are not named with the name you specify as the final image name.
When using docker tag you don't even have to use the image name as the first parameter. You can even use the hash of the image that you want to tag as the first parameter, so it's more flexible than just namespace/repository:tag.
The difference between an image and repository must be stated:
An image is a tagged repository. That's the only difference. The <username> is part of the repository name.
From the overview of the Docker Registry Distribution API:
Classically, repository names have always been two path components
where each path component is less than 30 characters. The V2 registry
API does not enforce this. The rules for a repository name are as
follows:
A repository name is broken up into path components. A component of a
repository name must be at least one lowercase, alpha-numeric
characters, optionally separated by periods, dashes or underscores.
More strictly, it must match the regular expression
[a-z0-9]+(?:[._-][a-z0-9]+)*. If a repository name has two or more
path components, they must be separated by a forward slash ("/"). The
total length of a repository name, including slashes, must be less
than 256 characters.
Just use meaningful names for your images and tags. You could have smeeb/myapp and smeeb/myapp-db. For tags, the convention is to use versioned tags and a latest one.
Related
I have a k8s deployment that pulls an image based on the digest rather than the tag.
Why? I have multiple lower k8s namespaces which all pull from the same Docker repo. I don't want a bug fix for ns-dv to accidentally replace with an image pushed for ns-qa. So I'd like to keep both images around, even if they share a tag.
And since imagePullPolicy is always, new dynamic pods in ns-qa may use the latest, incorrect image.
imagePullPolicy: Always
Thus, in my Docker repo (Mirantis) I'd like to keep multiple images per tag, one per digest.
Is this possible?
A digest uniquely identifies an image. A tag points to a digest. So, you cannot have multiple images that have the same tag. The difference is, a tag may be updated to point to a different digest. Two different tags can point to the same digest.
So you either have to use the digests, or different tags for each namespace (app-dev, app-qa, etc.). The different tags may point to the same image, or they may point to different images.
When you promote a dev image to qa, for instance, you can simply tag the dev image as qa, so both app-dev and app-qa tags pull the same image. Then you can make updates to the dev image, and tag that as app-dev, so dev namespace updates, but qa namespace stays the same.
I am going through a books and came across this line:
Whereas a tag can only be applied to a single image in a repository, a single image can have several tags. For example, the Java repository on Docker Hub maintains the following tags: 7, 7-jdk, 7u71, 7u71-jdk, openjdk-7, and openjdk-7u71. All these tags are applied to the same image.
My question is: why will a single image have several tags? What is the purpose of tagging the same image with different tags?
In my opinion there are mainly two reasons.
First of all, it is for convenience, so you may give multiple aliases to the same images.
But you can give other (special) tags to images in order to push it to a different registry.
Suppose (for example) you are using microk8s and you enabled the registry service. To push a local image of yours, you have to apply it with a tag formerly named localhost:32000/my-image:my-tag.
In that scenario your image will have two tags my-image:my-tag and localhost:32000/my-image:my-tag. So, to push it to microk8s registry the only thing you will have to do is to issue the command git push localhost:32000/my-image:my-tag (the image tag will be parsed to get the URI of the registry to push to).
The above concept, obviously, can be applied to any other remote registry.
You can use multiple tags for all sorts of purposes. The most popular one is to have a "latest" image, for example.
Imagine you're pulling the latest ubuntu image.
That would be "docker pull ubuntu:latest". Try pulling ubuntu:20.04 - you'll find out you have already pulled the image.
NOTE: After a while, ubuntu:latest won't be the same a ubuntu:20.04 anymore, but to the newest tag. However, you'll always have a pointer to the latest version of the ubuntu image and wherever you're using it, you won't need to change the tags.
For all the Dockerfiles I've come across thus (which admittedly is not many), all of them have used a FROM clause to base off an existing image, even if it's FROM scratch.
Is this clause required? Is it possible to have a Dockerfile with no FROM clause? Will this container created thus be able to do anything?
EDIT
I read
A Dockerfile with no FROM directive has no parent image, and is called
a base image.
https://docs.docker.com/glossary/?term=parent%20image
But I think this may be an error.
Based on the official documentation it's required:
The FROM instruction initializes a new build stage and sets the Base
Image for subsequent instructions. As such, a valid Dockerfile MUST
start with a FROM instruction. The image can be any valid image – it
is especially easy to start by pulling an image from the Public
Repositories.
https://docs.docker.com/engine/reference/builder/#from
Short answer is yes, the FROM clause is required. But it's easier to come to this conclusion if you think of the image building process a bit.
Dockerfile is just a way to describe a sequence of commands to be executed by Docker build subsystem to create an image. And an image is just a bunch of regular files, most notably, user land files of a particular Linux distribution, but possibly with some extra files on top of it. Every Docker image is based on the parent image and adds its own files to the parent's set. Every image has to start FROM something, i.e. specify its parent. And the parent of all parents is a scratch image defined as noop, i.e. an empty set of files.
Take a look at busybox image:
FROM scratch
ADD busybox.tar.xz /
CMD ["sh"]
It starts from scratch, i.e. an empty set of files, and adds (i.e. copies) to this set a bunch of files from busybox.tar.xz archive.
Now, if you want to create your own image, you can start from busybox image and describe what files (and how) you are going to add:
FROM busybox:latest
ADD myfile.txt /
But every time a new image has to start FROM something.
Yes, it is. It defines the layers on which the image you are building is based on.
If you want to start an image from scratch docker offers an image called scratch
The documentation also says:
A parent image is the image that your image is based on
also
A base image has FROM scratch in its Dockerfile.
Refer to base images documentation
I don't know if this is intended behavior or bug in GCR.
Basically I tried do it like that:
Create image from local files using Docker on Windows (Linux based image).
Before creating image I delete all local images with the same name/tag.
Image is tagged like repostiory/project/name:v1
When testing locally image have correct versions of executables (docker run imageID).
Before pushing image to GCR I delete all images from GCR with the same tag/name.
When Trying to pull new image from GCR to example kubernetes it pull the first (ever) image uploaded under particular tag.
I want to reuse the same tag to not change config file with every test and I don't really need to store previous versions of images.
It sounds like you're hitting the problem described in kubernetes/kubernetes#42171.
tl;dr, the default pull policy of kubernetes is broken by design such that you cannot reuse tags (other than latest). I believe the guidance from the k8s community is to use "immutable tags", which is a bit of an oxymoron.
You have a few options:
Switch to using the latest tag, since kubernetes has hardcoded this in their default pull policy logic (I believe in an attempt to mitigate the problem you're having).
Never reuse a tag.
Switch to explicitly using the PullAlways ImagePullPolicy. If you do this, you will incur a small overhead, since your node will have to check with the registry that the tag has not changed.
Switch to deploying by image digest with the PullIfNotPresent ImagePullPolicy. A more detailed explanation is in the PR I linked, but this gets you the best of both worlds.
I'm creating some very simple Docker containers. I understand that after each step a new container is created. However, when using other Dockerfiles from the Hub I don't wind up with untagged images. So where do they come from? After browsing around online I have found out how to remove them but I want to gain a better understanding where they come from. Ideally I would like to prevent them from ever being created.
From their documentation
This will display untagged images, that are the leaves of the images
tree (not intermediary layers). These images occur when a new build of
an image takes the repo:tag away from the IMAGE ID, leaving it
untagged. A warning will be issued if trying to remove an image when a
container is presently using it. By having this flag it allows for
batch cleanup.
I don't quite understand this. Why are builds taking the repo:tag away from the IMAGE ID?
Whenever you assign a tag that is already in use to a new image (say, by building image foo, making a change in its Dockerfile, and then building foo again), the old image will lose that tag but will still stay around, even if all of its tags are deleted. These older versions of your images are the untagged entries in the output of docker images, and you can safely delete them with docker rmi <IMAGE HASH> (though the deletion will be refused if there's an extant container still using that image).
Docker uses a file system called AUFS, which stands for Augmented File System. Pretty much each line of a Docker file will create a new image and when you stack or augment them all on top of each other you'll get your final docker image. This is essentially a way of caching, so if you change only the 9th line of your Docker file it wont rebuild the entire image set. (Well depends on what commands you have on your Docker file, if you have a COPY or ADD nothing after that point is cached for ex)
The final image will get tagged with whatever label it has, but all these intermediary images are necessary in order to create the final image so it doesn't make sense to delete them or prevent them from being created. Hope that makes sense.