We use cookies to make your experience better.
Learn about image tag naming conventions and recommendations for use.
Coder uses image tags to determine the image variant to use when creating an workspace.
Image tags are expressed using the following notation:
<image>:<image-tag>
Examples include:
ubuntu:rolling
ubuntu:latest
ubuntu:20.04
mycorp/myproject:v1
This article will walk you through how Coder handles image tags and what to consider when working with image tags.
When modifying an existing image, be sure to consider whether the changes you're making will break existing workspaces built using that image. You may want to consider taking a semantic versioning view of your image tags for more critical images.
The following examples show how different tagging schemes change how Coder uses the image tag.
If you build your workspace using a ubuntu:rolling
or ubuntu:latest
tag,
Coder prompts you to rebuild for patches, security updates, and major version
releases. If you're supporting a SaaS product or working on mobile apps, you
can opt for this to ensure that your tools stay up-to-date.
If you build your workspace using a specific version tag (e.g.,
ubuntu:20.04
), Coder will alert you regarding patches and security updates
so that you rebuild your workspace (you won't get these fixes otherwise).
Coder does not, however, alert you regarding minor releases (e.g., movement
from 20.04
to 20.10
). This is a good option for those offering long-term
support of software with lengthier version cycles or those supporting multiple
versions where you expect to revert to a prior release to investigate and fix
issues.
If you build your workspace using mycorp/myproject:v1
, the image is
associated with a specific project's major version. You can apply the :v1
tag to the most recent build for the image, while you can use :v1.3
or
:v1.3.1
to pull a more specific tag version.
Use image names and tags that follow a consistent format across the organization so that users will be comfortable selecting either a versioned or a rolling tag.
To avoid pulling images from Docker Hub (or another external source), use internal registry names and tags or namespaces that are controlled by your organization.
Let's say that you have the following tag:
registry:port/company/department/software:majorversion
Here's the information that can be gleaned from the tag name:
registry:port
: By using an internal image registry name, there's no risk of
pulling an outside image with unapproved contentcompany
: If you're using an internal registry, you can omit this parameterdepartment
: Helps set the scope for who owns the image and therefore can
patch/modify the imagesoftware
: Offers information about which software systems should be
developed using the imagemajorversion
: Can correlate to a software stock; helpful in determining
which version of various dependencies and build tools are present in the imageThe above recommendations are based on assumptions that may not apply to all organizations, and their applicability may change over time. There's no "right way" to tag your images, as long as your tags are meaningful to your teams and don't cause issues with your developers' workflows.
See an opportunity to improve our docs? Make an edit.