Blog: Add "Containers: pitfalls of incomplete tar archives" #20

jeckersb · 2025-12-10T22:49:30Z

Signed-off-by: John Eckersberg jeckersb@redhat.com

gemini-code-assist

Code Review

This pull request adds a new, detailed blog post exploring the nuances of tar archives within container image layers, the current limitations in the OCI specification, and the role of overlayfs. The post is well-written and provides a deep dive into a complex topic. My review includes several suggestions to fix minor typos, correct a link, and resolve a technical inconsistency to enhance the post's overall quality and accuracy.

content/blog/2025-dec-15-blog-containers-pitfalls-of-incomplete-tar-archives.md

content/news/2025-dec-10-blog-containers-pitfalls-of-incomplete-tar-archives.md

jeckersb · 2025-12-12T14:54:34Z

A few more outstanding things in my mind before we publish:

I should probably show a brief example of computing fsverity inside of a format-version=1 container to show how it's non-deterministic due to the metadata changing.
Right now I've just put this underneath the existing News section of the site and included Blog: at the start of the title. Does it make more sense to have a dedicated Blog section instead? Probably... especially if we want to use this more in the future for more blogs. We can reserve News for meeting notes and release announcements and such.

jeckersb · 2025-12-12T15:05:11Z

Also not sure why CI is failing with:

Error: Found 2 broken external link(s)
  1. Broken link in /github/workspace/content/news/2025-dec-10-blog-containers-pitfalls-of-incomplete-tar-archives.md to https://github.com/opencontainers/image-spec/blob/main/layer.md#determining-changes : Anchor `#determining-changes` not found on page
  2. Broken link in /github/workspace/content/news/2025-dec-10-blog-containers-pitfalls-of-incomplete-tar-archives.md to https://github.com/opencontainers/image-spec/blob/main/layer.md#representing-changes : Anchor `#representing-changes` not found on page

Those are definitely valid anchors on that page 🤷

jeckersb · 2025-12-12T23:31:47Z

Also not sure why CI is failing with:

Error: Found 2 broken external link(s)
  1. Broken link in /github/workspace/content/news/2025-dec-10-blog-containers-pitfalls-of-incomplete-tar-archives.md to https://github.com/opencontainers/image-spec/blob/main/layer.md#determining-changes : Anchor `#determining-changes` not found on page
  2. Broken link in /github/workspace/content/news/2025-dec-10-blog-containers-pitfalls-of-incomplete-tar-archives.md to https://github.com/opencontainers/image-spec/blob/main/layer.md#representing-changes : Anchor `#representing-changes` not found on page

Those are definitely valid anchors on that page 🤷

Pretty sure this is because the raw page content doesn't contain those anchors but they exist inside of a big <script> json blob that gets manipulated client side 🙄

Signed-off-by: John Eckersberg <jeckersb@redhat.com>

jeckersb · 2025-12-15T17:21:49Z

Ok a few notable things here:

Added the Blog section to the site and tucked this under there.
Updated the date to today (Do we want to the filename to contain the date? Makes it annoying to edit over several days...)
I removed the anchored links that were making CI mad. Not a huge deal since I'm directly quoting it and the page in its entirety is linked before.
Added a bit more around composefs/fsverity and how this rather badly messes up measuring things.

jeckersb · 2025-12-15T17:26:30Z

Hm now CI is mad about:

1. Broken link in /github/workspace/content/_index.md to https://www.linuxfoundation.org/trademark-usage/ : Client error status code (404 Not Found) received

jeckersb · 2025-12-15T17:27:52Z

Hm now CI is mad about:

1. Broken link in /github/workspace/content/_index.md to https://www.linuxfoundation.org/trademark-usage/ : Client error status code (404 Not Found) received

Ah looks like this moved to https://www.linuxfoundation.org/legal/trademark-usage

jeckersb · 2025-12-15T17:37:15Z

@nimbinatus this is relevant to your interests too, at least as far as reorganizing the site a bit to add a Blog for community articles

jeckersb · 2025-12-15T17:43:38Z

/gemini review

gemini-code-assist

Code Review

This pull request adds a new blog section to the website, including a detailed technical post about container image layers and tar archives. The changes also include adding templates for the blog, and updating the site configuration and main page.

My review focuses on the new template files and the blog post content. I've found a critical issue with a macro used in the new templates that will cause broken links in the header. I've also identified a high-severity bug in the blog listing template related to pagination, which would prevent posts from showing up if pagination is enabled. Additionally, I've provided some suggestions to improve the grammar and readability of the blog post, and to clean up the templates.

gemini-code-assist · 2025-12-15T17:45:40Z

themes/juice/templates/blog-page.html

+
+{% block header %}
+<header class="box-shadow">
+    {{ macros::render_header() }}


The render_header macro called here appears to be coming from a buggy version in themes/juice/templates/_macros.html. It will generate broken links for the extra menu items (like 'About', 'Docs', 'Blog', etc.). This is a critical issue that breaks site navigation. The macro needs to be fixed to correctly generate the href for links. A correct implementation seems to exist in templates/_macros.html.

Hum...I have zero expertise in this stuff but my guess is that Gemini is also guessing on this stuff heuristically.

Does this zola+juice stuff actually compile and sanity check this stuff? If so we can ignore this. If not let's see about fixing that

Yeah I don't really understand how the theme stuff works.

There is some amount of checking that zola does to sanity check for broken links or other obviously broken things because I got big scary red errors on the console telling me to fix things. But I don't know how exhaustively it checks.

gemini-code-assist · 2025-12-15T17:45:40Z

themes/juice/templates/blog.html

+
+{% block header %}
+<header class="box-shadow">
+    {{ macros::render_header() }}


The render_header macro called here appears to be coming from a buggy version in themes/juice/templates/_macros.html. It will generate broken links for the extra menu items (like 'About', 'Docs', 'Blog', etc.). This is a critical issue that breaks site navigation. The macro needs to be fixed to correctly generate the href for links. A correct implementation seems to exist in templates/_macros.html.

gemini-code-assist · 2025-12-15T17:45:40Z

themes/juice/templates/blog.html

+</h1>
+<ul>
+    <!-- If you are using pagination, section.pages will be empty. You need to use the paginator object -->
+    {% for page in section.pages %}


As the comment on line 14 correctly notes, this loop will not work if pagination is enabled for the blog section, because section.pages will be empty. To fix this and make the template robust, you should use paginator.pages with a fallback to section.pages.

{% for page in paginator.pages | default(value=section.pages) %}

content/blog/2025-dec-15-blog-containers-pitfalls-of-incomplete-tar-archives.md

themes/juice/templates/blog-page.html

gemini-code-assist · 2025-12-15T17:45:41Z

themes/juice/templates/blog.html

+<ul>
+    <!-- If you are using pagination, section.pages will be empty. You need to use the paginator object -->
+    {% for page in section.pages %}
+    <li><a href="{{ page.permalink | safe }}">{{ page.date }} - {{ page.title }}</a></li>


The safe filter on page.permalink is not necessary because Zola permalinks are already marked as safe. Removing it would make the code cleaner and more consistent with other parts of the templates (e.g., the archive list in the sidebar).

<li><a href="{{ page.permalink }}">{{ page.date }} - {{ page.title }}</a></li>

Signed-off-by: John Eckersberg <jeckersb@redhat.com>

jeckersb · 2025-12-15T18:43:12Z

I don't think the remaining gemini nits are a huge deal. I just copied blog.html and blog-page.html from news.html and news-page.html respectively. Any issues noted there already exists in the news bits.

Also this seems to be incorrect:

It will generate broken links for the extra menu items (like 'About', 'Docs', 'Blog', etc.). This is a critical issue that breaks site navigation.

The links all look fine to me 🤷

cgwalters · 2025-12-15T18:43:55Z

OK let's merge and see! Worst case we revert

cgwalters · 2025-12-15T18:48:33Z

It's live and I sanity checked and LGTM

gemini-code-assist bot reviewed Dec 10, 2025

View reviewed changes

cgwalters approved these changes Dec 10, 2025

View reviewed changes

content/news/2025-dec-10-blog-containers-pitfalls-of-incomplete-tar-archives.md Outdated Show resolved Hide resolved

jeckersb force-pushed the blog branch from ec3b679 to 45a6efb Compare December 12, 2025 14:48

Add Blog section to site

64e325e

Signed-off-by: John Eckersberg <jeckersb@redhat.com>

jeckersb force-pushed the blog branch from 45a6efb to ef0f4d9 Compare December 15, 2025 17:18

jeckersb changed the title ~~WIP: Blog post about containers and tar oh my~~ Blog: Add "Containers: pitfalls of incomplete tar archives" Dec 15, 2025

jeckersb marked this pull request as ready for review December 15, 2025 17:22

gemini-code-assist bot reviewed Dec 15, 2025

View reviewed changes

jeckersb added 2 commits December 15, 2025 13:39

Blog: Add "Containers: pitfalls of incomplete tar archives"

8b6770b

Signed-off-by: John Eckersberg <jeckersb@redhat.com>

Update link for CNCF trademark usage

d89c5df

Signed-off-by: John Eckersberg <jeckersb@redhat.com>

jeckersb force-pushed the blog branch from 105c620 to d89c5df Compare December 15, 2025 18:39

cgwalters merged commit 2350a5a into bootc-dev:main Dec 15, 2025
3 of 6 checks passed

Blog: Add "Containers: pitfalls of incomplete tar archives" #20

Blog: Add "Containers: pitfalls of incomplete tar archives" #20

Uh oh!

Conversation

jeckersb commented Dec 10, 2025

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jeckersb commented Dec 12, 2025

Uh oh!

jeckersb commented Dec 12, 2025

Uh oh!

jeckersb commented Dec 12, 2025

Uh oh!

jeckersb commented Dec 15, 2025

Uh oh!

jeckersb commented Dec 15, 2025

Uh oh!

jeckersb commented Dec 15, 2025

Uh oh!

jeckersb commented Dec 15, 2025

Uh oh!

jeckersb commented Dec 15, 2025

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist bot Dec 15, 2025

Choose a reason for hiding this comment

Uh oh!

cgwalters Dec 15, 2025

Choose a reason for hiding this comment

Uh oh!

jeckersb Dec 15, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Dec 15, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Dec 15, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

gemini-code-assist bot Dec 15, 2025

Choose a reason for hiding this comment

Uh oh!

jeckersb commented Dec 15, 2025

Uh oh!

Uh oh!

cgwalters commented Dec 15, 2025

Uh oh!

cgwalters commented Dec 15, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants