coder · johnstcn · Jan 6, 2023 · Jan 6, 2023
diff --git a/assets/images/decommission-image-tag.png b/assets/images/decommission-image-tag.png
diff --git a/images/deprecating.md b/images/deprecating.md
@@ -1,10 +1,24 @@
 ---
-title: "Deprecate"
-description: Learn how to deprecate an image.
+title: "Deprecate and Decommission"
+description: Learn how to deprecate an image and decommission a tag.
 ---
 
+At a certain point, you may wish to deprecate a specific workspace image in
+favor of a newer one. Coder provides two mechanisms to control workspace image
+lifecycles:
+
+## Deprecate an Image
+
+Deprecation controls whether an entire image repository (and all tags) can be
+used to create new workspaces.
+
 You can mark images as deprecated to prevent them from being used to create new
-workspaces.
+workspaces. For example, if you have an existing workspace image based on an
+older OS release, and you create a new workspace image based on a newer OS
+release, you can **Deprecate** the old workspace image to ensure that new
+workspace images use the newer OS release.
+
+To mark an image as **deprecated**:
 
 1. Go to **Images** and find the image to mark as deprecated.
 1. Click **Edit**.
@@ -16,3 +30,28 @@ workspaces.
 > Users cannot create new workspaces using deprecated images. However, they can
 > continue to use _existing_ workspaces created with the now-deprecated images
 > and edit the resources allocated to that workspace.
+
+## Decommission an Image Tag
+
+Decommissioning controls whether an **individual** image tag can be used to
+create new workspaces. This may be useful in an environment where image tags are
+considered _immutable_.
+
+You can **decommission** an existing image tag to prevent them from being used
+to create new workspaces. Additionally, existing workspaces using this tag will
+be updated to use the **default image tag** upon their next rebuild.
+
+> ⚠️ You cannot decommission the default image tag. If you need to do so, update
+> the default tag and then decommission the previous default tag.
+
+To **decommission** an image tag:
+
+1. Go to **Images** and find the image whose tag you wish to decommission.
+1. Under **Available Tags**, find the tag you wish to decommission.
+1. Click the three-dot menu to the right in the table, and select
+   **Decommission**. A dialog will appear asking you to confirm your decision.
+
+![Decommissioning an image tag](../assets/images/decommission-image-tag.png)
+
+To reverse this process, repeat the above steps but select **Recommission**
+instead.
diff --git a/images/tags.md b/images/tags.md
@@ -25,6 +25,9 @@ Each image has a default tag. The default tag appears at the top of the list and
 is indicated by an asterisk. Coder automatically selects the default tag when
 you create a workspace.
 
+Additionally, if the current workspace image tag has been **decommissioned**,
+Coder will automatically update it to the default tag when it is next rebuilt.
+
 > For information about how Coder handles image tags, see
 > [Image Tag Names](../guides/admin/image-tag-names.md).
 
@@ -43,3 +46,9 @@ To use an existing tag as the default tag, click the **vertical ellipsis** for a
 tag and select **Make default**.
 
 ![Set existing tag as default](../assets/images/existing-tag-as-default.png)
+
+### Decommission a tag
+
+A **decommissioned** image tag cannot be used to create new workspaces.
+
+See [Deprecate and Decommission](./deprecating.md#decommission-an-image-tag)