Skip to content

docs(identity): record why a new blueprint errors between pull and converge - #406

Merged
PBernaerts merged 1 commit into
mainfrom
docs/blueprint-env-transient
Aug 21, 2026
Merged

docs(identity): record why a new blueprint errors between pull and converge#406
PBernaerts merged 1 commit into
mainfrom
docs/blueprint-env-transient

Conversation

@PBernaerts

Copy link
Copy Markdown
Owner

Documentation only. Records what deploying #399 and #404 taught, because it applies to every future blueprint and not just those two, and because the failure mode actively misleads whoever sees it.

The transient

The worker re-applies a blueprint the moment the file changes, and git pull is what changes it. So the file is applied against the environment the containers were started with, seconds before deploy.yml recreates them. Any !Env naming a variable added in the same PR resolves to None, and the blueprint sits in error until the converge.

That is normal. Someone who reads the status in that window, panics, and reverts a working change has been misled by a transient. The only meaningful read is after the converge.

Two corollaries about the status line, both hit the same day

Both are why verification is a Postgres read of the objects, never the status line.

The underlying bug, and the check that now prevents it

!Env reads the container's environment, and compose.yaml does not always pass a variable through under its own name. LOGIN_URL is set as AUTHENTIK_WEB__BASE_URL, so !Env LOGIN_URL resolved to None while every other signal was green. tests/test-authentik-blueprints.sh now checks the whole chain per variable, and the second instance it found (LDAP_BASE_DN unguarded, which would let the entire directory stop syncing with nothing reporting it) is recorded too.

Status line

Updated: 6e's machinery is deployed and verified on the host, with nothing member-facing moved. Three proxy providers in forward_single, media-users bound to the apex and music and deliberately not to MTG, the embedded outpost's authentik_host now the public login URL rather than a LAN address, and all three gates still redirecting to the Authelia portal.

Gates

tests/run.sh 39 suites / 0 failures; check-doc-links.sh all links resolve. Rebased onto #403.

…nverge

Learned deploying #399 and #404, and it applies to every future blueprint
rather than just those, so it belongs in the plan and not in a chat thread.

The worker re-applies a blueprint the moment the file changes, and git pull
is what changes it - so the file is applied against the environment the
containers were STARTED with, seconds before deploy.yml recreates them. Any
!Env naming a variable added in the same PR resolves to None, and the
blueprint sits in error until the converge. That is a normal transient, and
somebody who reads the status in that window and reverts a working change
has been misled by it.

Two corollaries about the status line, both hit the same day. A blueprint
only re-applies when the FILE changes, so a converge that touched only
compose.yaml leaves a STALE status still showing the old error; touch the
file to force it. And a blueprint can read successful while an object still
differs from the file, because the role serializer only ever adds
permissions. Both are why verification is a Postgres read of the objects.

Also records the underlying bug and the check that now prevents it: !Env
reads the CONTAINER environment, compose.yaml does not always pass a
variable through under its own name, and the test that caught the second
instance (LDAP_BASE_DN unguarded, which would silently stop the whole
directory syncing).

Status line updated: 6e's machinery is deployed and verified on the host,
with nothing member-facing moved.
@PBernaerts
PBernaerts merged commit 22c5ede into main Aug 21, 2026
9 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant