Epic: Improve versioning and rollout of workspace images

[loujaybee]

Press Release

Gitpod has now updated all of our managed workspace images. All managed workspace images except workspace-base and workspace-full (the default) are now tied to a specific programming language to avoid unwanted breakages (e.g. workspace-java-17 and NOT workspace-java). Gitpod has deprecated all previously workspace language images that were not tied to a language version. By continuing to use a deprecated image you will no longer receive any further updates or patches. To check whether your image is deprecated, please run gp validate inside your workspace.

Will deprecated images be removed?

No, all images will remain on Dockerhub, but will no longer receive updates.

Context

We maintain a set of workspace images to help customers get up and running on Gitpod easier. Currently all new workspaces are created on the latest version of workspace-full, whilst these users are then kept on the latest versions this does mean that workspace starts can break in unpredictable ways. This epic is around improving our user consistency and strategy around workspace images + general discovery of workspace images.

Acceptance Criteria

• Ensure that all language workspace images are pinned to a version within the name
• Introduce beta + stable channels for all workspace images
• Update gp validate to encourage users to use language versioned workspace images
• Update gp validate with warning for workspaces running deprecated images
• All workspace images are documented within gitpod.io/docs (not separately in GitHub)
• Remove info from gitpod-io/workspace-images README and redirect to Gitpod docs.

Related

• RFC: Workspace Images - Release Channels
• RFC: Workspace Images - Pinned Language Versions
• Java 17 for workspace-full workspace-images#874
• Epic: Remove need to commit to git (Gitpod "Inner Loop") #7671

---

Click to toggle contents of `code`

Right now our workspace images are updated for customers but the release process / way they're updated is not clear. Users aren't always aware they're even using a base image, and get no notifications currently of any changes. We need to investigate how we can better notify users when a base image is going to be updated, and also encouraging users to either take ownership of their own base image, or be fully aware of the implications of using a managed base image from Gitpod.

Challenges:

• Onboarding - New users are often not aware of what’s in their base image, as seen in usability testing.
• Workspace image repo documentation #2187 - Could be refined for users (e.g. make it easier to point out the custom changes we are making for easier copy / paste).
• Rollout and versioning has friction #2587 - Breaking changes to workspace images are hard to communicate and can break users in mysterious ways. This relates to topics of having org or team-wide images.
• Implicit surfacing in the UX - Unless the user pins to an image, they are implicitly using an image that they can sometimes not be aware of.
• Maintenance - We should only maintain a restricted number of images, and consider the support cost. Images should align with language pages in docs.

Opportunities

• The docs restructure #2587 reduces to 5 languages, and introduces a dedicated “workspace” top-level section, we should review and update our image creation documentation following this. Database image support also needs to be discussed.

Option 1: Deprecations process for workspace images

• Epic: In Product Changelog - VS Code only #7537
• Email notifications with advanced warning of a deprecation

Option 2: Ensure users are aware of the base image and ask them to pin explicitly

• Prompt users to pin their workspace base image version, so new versions can be rolled out without breaking users
• Notify users that an update has been made, and they should update
• Eventually sunset previous versions with sufficient deprecation warning

There is a related topic here about versioning and release. However we currently don't have user-pinned versions to base images, but arguably we could.

Relates to:

CC: @atduarte / @ghuntley

[axonasif]

From what I've seen, many of the users aren't aware of all the workspace images we maintain.

[loujaybee]

@axonasif, yup.

• https://github.com/gitpod-io/website/issues/2187

Improved documentation for sure is part. There's also a product design issue here.

[david-bakin]

And please see my comment here - #11455 (comment) - where I suggest looking inside of custom dockerfiles to see if they need to be rebuilt automagically during prebuilds when the container they're based on changes.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[Siddhant-K-code]

with gp rebuild (#15490, #7671) . We could workspace-images validation also. It could come with file validation step that could check the state of workspace images deprecation/versions 🙂

Internal Conversation