docs: rework flavor, cname and related terms after ADR0034 and ADR0035 and add links to feature references#153
docs: rework flavor, cname and related terms after ADR0034 and ADR0035 and add links to feature references#153yeoldegrove wants to merge 3 commits into
Conversation
yeoldegrove
force-pushed
the
docs/flavor_cname
branch
from
434bb9e to
bb1c5c1
Compare
yeoldegrove
force-pushed
the
docs/flavor_cname
branch
from
bb1c5c1 to
1042785
Compare
Signed-off-by: Eike Waldt <waldt@b1-systems.de> On-behalf-of: SAP <eike.waldt@sap.com>
yeoldegrove
force-pushed
the
docs/flavor_cname
branch
from
1042785 to
5cec9a9
Compare
|
📚 Documentation Preview PR: gardenlinux/docs-ng#99 A PR has been created/updated to preview the documentation changes from this PR. |
Signed-off-by: Eike Waldt <waldt@b1-systems.de> On-behalf-of: SAP <eike.waldt@sap.com>
yeoldegrove
force-pushed
the
docs/flavor_cname
branch
from
5cec9a9 to
310efc1
Compare
|
|
||
| The build command takes a *flavor name* as its argument. A flavor name directly encodes what | ||
| will be built: | ||
| The `./build` script takes a **flavor** (`{cname}-{arch}`) as its argument. The version is not supplied on the command line — it is derived automatically by calling `./get_version`, which reads the `VERSION` file in the repository root: |
There was a problem hiding this comment.
the bulid command can take either of cname, flavour, or versioned flavour. so the version can be provided on the command line. e.g. ./build aws-amd64-2142.0.0 would work, it would pick the repo of 2142.0.0 with whatever commit is currently checked out locally.
There was a problem hiding this comment.
Missed that. Will extend the section to document both variants.
| 1. Start with the explicitly requested features | ||
| 2. Recursively include all features listed in each feature's `features.include` list | ||
| 3. Remove any features listed in `features.exclude` lists (but only if they were transitively included) | ||
| 4. Validate that the result forms a valid DAG (no cycles, no conflicts) |
There was a problem hiding this comment.
is this done last? I think the DAG validation is actually the first step before any recursion is done at all.
There was a problem hiding this comment.
Good catch!
This should be corrected to:
1. Validate that all available features form a valid DAG (no cycles) — this check runs on the full, unfiltered feature graph before any resolution begins
2. Start with the explicitly requested features
3. Recursively include all features listed in each feature's `features.include` list
4. Remove any features listed in `features.exclude` lists (but only if they were transitively included); attempting to exclude a feature that was explicitly requested is a hard build error
| | `--kms` | *(none)* | Off | Forwards AWS credential environment variables (`AWS_DEFAULT_REGION`, `AWS_REGION`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`) into the build. Required when Secure Boot key operations during the build use AWS Key Management Service. | | ||
| | `--allow-frankenstein` | *(none)* | Off | Disables the [single-platform enforcement](/reference/adr/0020-enforce-single-platform-by-default-in-builder) by passing `ALLOW_FRANKENSTEIN=1` to the build. Allows composing a flavor from multiple platform features. See [ADR 0020](/reference/adr/0020-enforce-single-platform-by-default-in-builder) for the rationale. | | ||
| | `--resolve-cname` | *(none)* | Off | Resolves the given flavor argument to its full canonical name (CNAME) including the 8-character commit hash, prints it to stdout, and exits. Requires exactly one flavor argument. Useful for generating reproducible artifact names in scripts. | | ||
| | `--resolve-cname` | *(none)* | Off | Resolves the given flavor argument to the artifact base name (`{cname}-{arch}-{version}-{short_commit}`), prints it to stdout, and exits. Requires exactly one flavor argument. Useful for generating reproducible artifact names in scripts. | |
There was a problem hiding this comment.
I guess we then either need to change the name of this flag or what it does 🤔 but I guess it does correctly document what it currently does, so fine for now, we'll just need to remember this as part of #156
There was a problem hiding this comment.
Yes, it should be updated/renamed once the actual flag is changed.
I will add a WARNING section that links the issues to make this more obvious.
|
|
||
| | Key | Content | | ||
| |---|---| | ||
| | `GARDENLINUX_CNAME` | The cname — feature encoding only (e.g. `aws-gardener_prod`) | |
There was a problem hiding this comment.
in contrast to https://github.com/gardenlinux/builder/pull/153/changes#r3544051495 I guess this now already describes the state it should be, not the current is state, right? cause the is state until #156 and gardenlinux/gardenlinux#5004 are addressed is still that this actually writes the versioned flavour
There was a problem hiding this comment.
I will add a WARNING section that links the issues to make this more obvious.
Signed-off-by: Eike Waldt <waldt@b1-systems.de> On-behalf-of: SAP <eike.waldt@sap.com>
yeoldegrove
force-pushed
the
docs/flavor_cname
branch
from
4243f08 to
c9a8489
Compare
3 participants
What this PR does / why we need it:
Which issue(s) this PR fixes:
Fixes gardenlinux/gardenlinux#4600