Share via


How ACR Build Id's are generated

As you use ACR Build, for OS & Framework patching, native container builds, or validating a docker build without having the docker client installed, you may be wondering, what is the format for those alpha-numeric Build id's. aa12

The short answer is it's based on the region the build was executed upon, and a base 32, alpha-numeric sequence to provide independent execution, with multi-region fault tolerance.

The format is: [2 digit, base 32 region code][base 32 sequence]

For some background why we chose this solution...

Accepting failure as reality

As we build ACR, and its associated services, we accept the premise that "failure is reality". One of the base foundations of container orchestrators is to accept failure as reality, at the infrastructure level. Its not that we don't strive to make ACR and all our container services reliable. But attempting to make a service n9's reliable is a costly investment. Rather than spend 90% of our effort, getting the last n% of reliability, we invest in recovering from and accepting failure, and providing more capabilities. The end result is you achieve n9's, but you do so by accepting any number of elements may individually fail, and we avoid single points of failure.

ACR Build, Independent Execution, Multi-Region Reliability

ACR supports geo-replicated registries. Which means a single registry can span multiple regions. ACR supports multi-master changes, so any push, any delete, any meta-data update to any region is eventually consistent. Meaning, there's no guarantee for the ordering of each regions replicated arrival. However, all replicated regions will eventually have all the images and meta-data. There's no single master controller. This means any registry can go down, and the rest will continue to operate. As a practice, we have no single points of failure, other than the big rock we all reside. We have planetary replication, to replicate to Mars and other destinations on our backlog, so the sky is not the limit.

Each replicated registry should be able to build, on its own, and become eventually consistent.

Balancing Needs for a Unique ID

With a little background, we can see why we didn't just use a Count Dracula approach of 1, 2, 3... We then had to decide; how can we generate a unique id?

We came up with a few guiding principles.

  1. It must be unique, as we want to support Best practices for tagging and versioning docker images
  2. It must be short enough to be able remember as you tell someone across the room, or type into another device while looking at another screen
  3. It must be easy for a human to read, and not get confused between 1 and l. 0 and o. 2 and z.
  4. It would be nice if there was some sense of sequential ordering. Although it wasn't critical to use every digit.
  5. It didn't have to be globally unique. It could be unique to a specific registry. Meaning myregistry.azurecr.io and yourregistry.azurecr.io could have the same build id. Making it globally unique would conflict with principals 2-4.
  6. We could seed each region with it's own pre-qualifier, so each geo-replicated region of a registry could be sequential

We considered prefacing the region specific unique number with the region id. eastus-1234. Although the first private preview used this, it seemed long and could be confusing when you consider that ACR Build could load balance builds across geo-replicated regions. By using generic numbers, there's no guarantee the preface characters really meant a specific thing.

Where we landed:

  • To keep it short, human readable, we went with a base 32 alpha-numeric sequence. All digits will be lower case, including the numbers. (what's the point of doing this if we can't laugh at the details)  0123456789abcdefghjkmnpqrstuvwxy
  • Each region will get a sequential two digit preface. Rather than do an elaborate zip code model, we'll take a simplistic agile approach. Every region we'll add, will simply get the next sequential two digit seed.
    An insider secret. You'll know the order we roll out build regions by its preface characters.
Region Seed
East US aa
West Europe ab
The next region ac
  • Each region will track its next id.
  • If a build fails, the build id is associated with the failed build, and the next sequential number is used for the next build.
  • Quick builds az acr build -t ., will also get sequential build ids.
  • Build Ids are assigned as the build is queued. If two builds are queued at the same time, that started at 1pm, that took 2 minutes will have a lower number than the build that started at 1:01 pm, and only took 30 seconds.
  • The preface characters are not tied to the closest registry from where the command is executed. As customers adopt base image updates, we expect huge bursts of automated builds as popular OS and run times update. As we scale ACR Build, we will stage the events, globally, just as Windows Update does today. If a region is at capacity, we may utilize any geo-replicated regions of a registry to load balance builds. If a registry is replicated between East US and West Europe, a build initiated on the east coast, may be bounced to West Europe based on capacity. ACR Geo-replication will kick in, and the Build ID will start with ab, the seed from West Europe.

We're excited to participate in building reliable systems, based on the reality that failure is a thing. We also strive on building systems that are easy to maintain as all too often, failures are triggered by complexity of simple things: quick-6-six-unit-conversion-disasters

Steve