skip to content

After going back to revision 4 of five kept revisions, what does the platform's revision list look like?

level: juniorimportance: nice to knowfreq 30%

answer

  1. the list only grows
  2. append, never pop
  3. new top entry, older content
  4. bounded depth drops the oldest
  5. name the revision you want

basics

~20 s

Revision history is append-only: going back adds a new highest entry holding the older spec, and retention drops the oldest. Nothing is popped or deleted, and the bad entry stays readable until it ages out.

solid answer

~40 s

Reapplying revision 4 is an apply, so the platform appends an entry - a new highest number whose content is revision 4's spec - and makes it live. The bad entry is not removed; it stays in the list, readable, until the retained depth pushes it out. Because the depth is bounded, the append also costs you the oldest entry: with five retained, a list of 1 to 5 becomes 2 to 6. Two practical consequences follow. A revision you might want can age out of the history entirely, which is what the retained depth setting is for. And going back is not a relative step, so repeating the action after an unsuccessful rollback does not walk one further into the past - you name the entry you want.

code

yaml · 12 lines
yaml
retainedDepth: 5

before:
  revisions: [1, 2, 3, 4, 5]
  live: 5            # the bad release

action: reapply the spec stored in revision 4

after:
  revisions: [2, 3, 4, 5, 6]
  live: 6            # 6 holds a copy of revision 4's spec
                     # 5 is still readable; 1 was dropped by retention

go deeper

for a junior

Remember the shape: going back adds an entry rather than removing one, and the oldest entry falls off when the retained depth is reached.

for a middle

Explain why an append-only history is useful - the bad spec stays readable for the review, and every entry is a state the system actually ran in.

for a senior

Watch the two traps in production: the entry you need can age out of a shallow history, and repeating a rollback does not walk further back, so name the entry explicitly.

for a principal

Treat retained depth as a recovery property of the workload, sized against its apply rate, and keep known-good specs somewhere more durable than a rolling window.

## The list only grows A revision history is a record of accepted applies, and going back is an accepted apply. So the operation appends: a new entry appears at the top of the list, its content is a copy of the spec you selected, and it becomes the desired state. Nothing is popped and nothing is rewritten. That shape is deliberate, and it buys two things: - **The bad spec remains readable.** After an incident you can open the entry that caused it and see exactly what was applied, rather than reconstructing it from memory. A history that deleted the entry you rolled back would destroy the evidence at the moment it became interesting. - **Every entry is a state the system genuinely ran in.** Because entries are only ever added and are never edited, the list is an honest timeline rather than a working document. ## Retention bounds it The history cannot grow for ever, so platforms keep a fixed number of entries per workload and drop the oldest when a new one arrives. That depth is a setting. With a depth of five, a list holding 1 to 5 becomes 2 to 6 after one rollback: you gained the new top entry and lost entry 1 in the same moment. This has a consequence people meet at exactly the wrong time: 1. **The spec you want can age out.** A workload that gets several applies a day burns through a shallow history in a week, and the "last known-good" entry from before a slow-burning regression may simply not be there any more. 2. **A rollback itself consumes a slot.** Reverting, fixing forward and reverting again in one afternoon can push several older entries out of the list. 3. **An entry is a record, not an archive.** It proves what the spec was; it does not hold the image content that spec referenced, so an entry can survive while the thing it points at no longer resolves. The habit is to set the depth against how often the workload is applied, not against a round number, and to treat a shallow history as a reason to record known-good specs somewhere that is not the platform's rolling window. ## Going back twice is not going back further The second trap in the same mechanism: selecting an earlier revision is not a relative step. It targets the entry you name, against the history as it stands now - and after one rollback, the top of that history is a copy of the spec you just returned to. Repeating the same action blindly therefore does one of two unhelpful things: it re-selects the entry that is already live, and nothing changes, or it re-selects the entry that was live before, which is the bad spec you were escaping. When a rollback did not help, go back to the list, read the entries, and name the one you actually want. ## What an entry is, and what it is not It helps to be precise about what the platform is storing, because two reasonable-sounding expectations are both wrong: - **It is a stored spec, not an undo step.** There is no inverse operation recorded anywhere. The list is a sequence of complete documents, and returning to one means submitting that document again. - **It is a record, not an archive.** The entry names image content; it does not contain it. The content lives in a registry with its own lifecycle, and nothing about keeping the entry keeps the bytes. - **It is per workload.** Each workload carries its own list and its own depth, so a release that changed three workloads together leaves three independent histories, and putting that release back means naming an entry in each of them. The third point is the one that catches people during a multi-workload incident: there is no single number that describes "where the system was at noon", only one entry per workload that happened to be live at the time. ## Reading a history that contains rollbacks | What you see | What it means | |---|---| | A top entry whose spec duplicates an older one | a rollback happened; the older entry is where it came from | | Two adjacent entries differing in one field | someone kept their applies small, and this boundary is returnable | | The oldest entry is newer than last month | retention has dropped everything before it | | An entry whose content reference no longer resolves | the entry survived; the content it names did not | Reading the list this way turns it into the cheapest incident artefact you have: it tells you what was wanted, when, and in what order - which is the part nobody writes down accurately during the incident itself.

  • Does a retained entry guarantee you can actually return to it?
    No. The entry records a spec, including a reference to image content, but it holds none of that content. If the referenced content has been removed from the registry, the apply is accepted and then the replacement stalls on the fetch. A history entry proves what was wanted, not that everything it names still exists.
  • How should the retained depth be chosen?
    By apply rate rather than by habit. Count how many applies the workload takes in the window where a regression might go unnoticed, and keep more entries than that. Entries are small documents, so depth is close to free, while a history that is one entry too short is discovered only when you need the one that just fell off.

saying these in an interview costs you the question

  • Thinks going back deletes the bad revision from the history
  • Believes a second rollback steps one further into the past
  • Assumes the history is unbounded and any old entry is still there
  • Reads a retained entry as proof the referenced content still exists