Legacy Convenience Image Deprecation

Announcements
,
1

In 2020 CircleCI introduced the next generation (next-gen) of convenience images. These new images are designed to replace the legacy convenience images that were released during the announcement of CircleCI 2.0. The next-gen CircleCI convenience images are designed from the ground up for a CI/CD environment. They are designed to be faster, more efficient, and most importantly, more reliable. You can learn more about all of the features on our blog post. As we begin to deprecate the legacy images, this document provides information on the migration process.

Moving from a legacy to next-gen image requires a change to the namespace. All legacy images have a Docker namespace of circleci, while next-gen images have a Docker namespace of cimg. For example, migrating from the legacy Ruby or Python image to the respective next-gen image can be done as follows:

circleci/ruby:2.3.0 → cimg/ruby:2.3.0
circleci/python:3.8.4 → cimg/python:3.8.4

Table of Contents

Changes

Deprecated images

Several changes are being made to existing images. The following images will be deprecated without next-gen equivalents:

  • buildpack-deps
  • JRuby
  • DynamoDB
  • MongoDB

circleci/buildpack-deps - If you are using this image, the suggestion is to use the new CircleCI Base image, cimg/base.

circleci/[jruby|dynamo|mongo] - If you are using these images, the suggestion is to use the official Docker Library image instead., jruby, dynamo, mongo. Since these images might miss a few tools, you might want to pre-install a few things before the checkout step. For example:

jobs:
  build:
    docker:
      - image: jruby:9.3
    steps:
      - run: sudo apt-get update && sudo apt-get install -y git sudo tar
      - checkout

Also, the following image will be renamed:

  • The Go image will be changed from golang to go

All Legacy to Next-Gen image changes are captured below in this table:

Legacy Image Next-Gen Image
circleci/buildpack-deps cimg/base
circleci/jruby jruby
circleci/dynamodb dynamo
circleci/golang cimg/go
circleci/mongo mongo

Browser Testing

With legacy images, there were 4 different variant tags you could use to get browser testing for a particular image. For example, if you were doing browser testing with the Python v3.7.0 image, you might have used Docker image: circleci/python:3.7.0-browsers. These 4 tags have now been consolidated into a single tag designed to be used together with the CircleCI Browser Tools orb.

Legacy Variant Tags Next-gen Variant Tags
-browsers -browsers + Browser Tools Orb
-browsers-legacy
-node-browsers
-node-browsers-legacy

The new, single browsers variant tag includes Node.js, common utilities to use in browser testing such as Selenium, but not the actual browsers. Please note the browsers are no longer pre-installed. Instead, browsers such as Google Chrome and Firefox, as well as their drivers Chromedriver and Gecko, are installed via the browsers-tools orb. This provides the flexibility to mix and match the browser versions you need in a build rather than using strictly what CircleCI provides. You can find examples of how to use this orb here.

Using Ubuntu as the Single Base OS

Legacy images had variant tags for several different base operating systems. Some images were versions of Debian and Ubuntu, while other images provided several different bases. This is no longer the case. All CircleCI next-gen images are based on the latest LTS release of Ubuntu.

With the base image, at least two LTS releases and non-EOL’d standard releases will be supported.

Latest Tag

This tag no longer exists for any image.

Image Specific Changes

Android

The tagging scheme has changed from API level based to date based. This now means that multiple API versions are available at the same time. Any one Android image tag will have at least the 5 most recent API levels.

Go

GOPATH has been changed from /go to $HOME/go. The latter will expand to the full path of /home/circleci/go. On first run, this change may affect caching and some other commands if you don’t correct the page in your config.

PHP

PHP releases from November 2021 and on no longer use apt-get to manage PHP and extensions. Instead PHP is compiled from source and extensions should be installed with a tool such a PECL. Please see the cimg/php readme.

Python

Python is installed via pyenv. Everything should work more or less the same, but the location of Python and installed pip modules will be different. Interested in Python site-packages? You can always know where this directory is located by running: python -m site --user-site

Deprecation Timeline

For all images but Clojure, MariaDB, MySQL, Redis, and MongoDB.

  • Jan 1, 2021 - Legacy Convenience Images are in Maintenance Mode only. They are rebuilt every 24 hours from upstream images.
  • Aug 9, 2021 - Legacy Convenience Images are in Maintenance Mode only. They are rebuilt every 7 days, on a Monday, from upstream images. This means upstream changes, such as new software releases, will take longer, up to 7 days, to be available.
  • Sep 20, 2021 - Legacy Convenience Images are in Maintenance Mode only. They are rebuilt every 14 days, on a Monday, from upstream images. This means upstream changes, such as new software releases, will take longer, up to 14 days, to be available.
  • Oct 18, 2021 - Legacy Convenience Images are in Maintenance Mode only. They are rebuilt once a month, on the 18th, from upstream images. This means upstream changes, such as new software releases, will take longer, up to 30 days, to be available.
  • Dec 31, 2021 - Legacy Convenience Images are no longer supported. This will be the last publishing day of these images. Existing tags will still exist on Docker Hub but will remain unchanged. There will be no support for bug or security fixes for existing tags. No new tags will be published after this day.

For only Clojure, MariaDB, MySQL, Redis, and MongoDB.

  • Jan 1, 2021 - Legacy Convenience Images are in Maintenance Mode only. They are rebuilt every 24 hours from upstream images.
  • Aug 9, 2021 - Legacy Convenience Images are in Maintenance Mode only. They are rebuilt every 7 days, on a Monday, from upstream images. This means upstream changes, such as new software releases, will take longer, up to 7 days, to be available.
  • Sep 20, 2021 - Legacy Convenience Images are in Maintenance Mode only. They are rebuilt every 14 days, on a Monday, from upstream images. This means upstream changes, such as new software releases, will take longer, up to 14 days, to be available.
  • Dec 13, 2021 - Legacy Convenience Images are in Maintenance Mode only. They are rebuilt once a month, on the 6th, from upstream images. This means upstream changes, such as new software releases, will take longer, up to 30 days, to be available.
  • Feb 7, 2022 - Legacy Convenience Images (except Clojure) are no longer supported. This will be the last publishing day of these images. Existing tags will still exist on Docker Hub but will remain unchanged. There will be no support for bug or security fixes for existing tags. No new tags will be published after this day.
  • March 7, 2022 - The Clojure Legacy Convenience Image is no longer supported. This will be the last publishing day for this image. Existing tags will still exist on Docker Hub but will remain unchanged. There will be no support for bug or security fixes for existing tags. No new tags will be published after this day.

Troubleshooting

When migrating to a next-gen image, there might be some software issues. Common issues include:

  • A library you were using now has a different version.
  • An apt package is no longer pre-installed. In this scenario simply install that package using:
sudo apt-get update && sudo apt-get install -y <the-package>

Each image has its own GitHub repository. You can find them here. These repositories are where you can learn more about an image, what makes up the image, open GitHub issues, and contribute PRs. If you are having an issue with an image, especially if it is a migration issue, you can open up a GitHub issue and ask questions. You can also open a support ticket or comment right here in this post.

If this post pertains to you, you may want to bookmark it. We will continually update this post will more information as we go.

3 Likes
2

Does this apply to all images? Because a lot of postgres tags (like -ram) lack a cimg equivalent. Configuring Databases - CircleCI needs updating as well BTW.

1 Like
3

There’s still no MySQL image as well. Either pipelines using it need to be retooled, or checks need to be made to assure MariaDB can be used in its place, and either way we need more than a month to do that in.

4

There’s been confusion as to which images the deprecation timeline applies to. I made clarifications in the top post.

In summary, this applies to all legacy images however:

  1. The few that will be dropped forever, such as buildpack-deps, just goes away.
  2. For most language images and PostgreSQL, the original timeline we posted applies.
  3. For Clojure and the rest of the databases images, there’s a different timeline with the final date being in February instead of December 31st. Since those images aren’t created yet, more time is allocated there.

The Convenience Images that haven’t been ported over yet, such as MariaDB, Clojure, MongoDB, and Redis, they will be and betas will be announced here in the forum later this month.

5

Just to make sure it’s explicit: what is the deprecation timeline and recommended upgrade path for the circleci/android images? I’m going to assume it’s something like “use cimg/jdk and install Android SDK yourself” or “use Android machine executors instead” but since it wasn’t explicitly called out in this post I wanted to be sure and ask.

6

There are the cimg/android images that supercede the legacy circleci/android images.

I think the deprecation timeline is the same as for other images as @FelicianoTech mentioned

3 Likes
7

Is there no convenience image for circleci/ruby:2.5.7-node?

1 Like
8

2.5.8-node was the first node variant released:

9

Will we have a convenience/next-gen image for mongo?

If not, what do you propose to use?

10

Maybe reach out to MongoDB and see what they recommend. I would try the Docker Library image as my first attempt: Docker Hub

11

Hey everyone,

I made two updates to my original post above.

  1. The next-gen Clojure image is now GA/stable. There is one important request we’re still tracking for the image however so the deprecation date for the legacy Clojure image has been pushed to March 7th. This has been reflected above.
  2. From a discussion on Twitter, I have added more information on what we suggest JRuby users to switch to, with a small sample config of how to install two missing packages. This has been added to the 1st post above, to the deprecation section.
12

Hi, I was about to update our CircleCI config as I saw the deprecation warning in the UI. We are using Go. We are using cache for golangci-lint. With the new image it could not be restored:

Found a cache from build 1 at golangci-lint-v1.44.2
Size: 8.3 MiB
Cached paths:
  * /go/bin/golangci-lint

Downloading cache archive...
Validating cache...

Unarchiving cache...

Failed to unarchive cache

Error untarring cache: Error extracting tarball /tmp/cache398868400 : tar: go: Cannot mkdir: Permission denied tar: go/bin/golangci-lint: Cannot open: No such file or directory tar: Exiting with failure status due to previous errors : exit status 2

Any solution, docs or recommendations for this?

We are using the curl command and installed it into $(go env GOPATH)/bin/golangci-lint

# binary will be $(go env GOPATH)/bin/golangci-lint
curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin v1.44.2

Looks like the cache key "/go/bin/golangci-lint" and therefore the Go path changed?

13

Is there any next-gen image for circleci/php:8.0-apache-node-browsers?

14

@fraenky8 Hi! The engineering team did some digging and we think have the solution:

gopath used to be /go in the old image and is now /home/circleci/go so you’re going to want to generate a new cache with that info and give it a shot again. Let me know if that still doesn’t work!

15 
Build-agent version 1.0.113967-13f62e50 (2022-03-11T17:57:45+0000)
System information:
 Server Version: 20.10.12
 Storage Driver: overlay2
  Backing Filesystem: xfs
 Cgroup Driver: cgroupfs
 Cgroup Version: 1
 Kernel Version: 5.13.0-1017-aws
 Operating System: Ubuntu 20.04.4 LTS
 OSType: linux
 Architecture: x86_64

Starting container cimg/go
Warning: No authentication provided, using CircleCI credentials for pulls from Docker Hub.
  image cache not found on this host, downloading cimg/go

Error response from daemon: manifest for cimg/go:latest not found: manifest unknown: manifest unknown

So the image name provided doesn’t work ?!?

executors:
  go_tests:
    docker:
      - image: cimg/go
        environment:
          GO111MODULE: "on"
16

Not 1:1 but close. The image cimg/php:8.0-browsers is what you want. The next-gen browsers variant should be pair with the Browser Tools Orb. What’s missing would be Apache, which you can get with a command like this:

sudo apt-get update && sudo apt-get install -y apache2

which specific Apache package(s) you install depends on your use case.

You didn’t specify a version of Go to use. - image: cimg/go is incomplete. Something like - image: cimg/go:1.17.7 would provide an actual image.

17

Hey there,

Would it be possible to add major version tags to images?
For example we were previously able to use circleci/node:14-browsers, now there are only minor-version-specific tags (eg. cimg/node:14.19-browsers).

Thanks!

18

Might be worth adding a note to the docs that a “latest” version is not provided then

1 Like
19

The legacy python images set the PYTHON_VERSION environment variable, while the next-gen images do not (last time I checked).

20

Hello folks, and thanks for providing this improvement to the images.
I have a few questions regarding older versions of Go:

  1. Is there any plan to add the Go 1.10 image?
  2. Is there a place where I can read the criteria for older versions? eg: Supported images correspond only to the last x versions.
  3. What do you recommend as an alternative for unsupported runtime versions?

I apologize before hand if these answers were provided somewhere else.

TIA,

  • Willian C.