diff --git a/.github/ISSUE_TEMPLATE/bug-report.yml b/.github/ISSUE_TEMPLATE/bug-report.yml new file mode 100644 index 0000000..c0699a7 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug-report.yml @@ -0,0 +1,73 @@ +name: Report a bug +description: Report an issue with Fedora CoreOS +labels: ["kind/bug"] +assignees: [] +body: + - type: textarea + id: bug-description + attributes: + label: Describe the bug + description: A clear and concise description of what the bug is. + placeholder: I'm using foo on bar and it fails with foobar. + validations: + required: true + + - type: textarea + id: bug-reproduction + attributes: + label: Reproduction steps + description: Steps to reproduce the behavior. + placeholder: | + 1. + 2. + 3. + validations: + required: true + + - type: textarea + id: bug-expected + attributes: + label: Expected behavior + description: A clear and concise description of what you expected to happen. + placeholder: Foo should succeed without errors. + validations: + required: true + + - type: textarea + id: bug-actual + attributes: + label: Actual behavior + description: A clear and concise description of what actually happened. + placeholder: Foo failed with ... + validations: + required: true + + - type: textarea + id: bug-system + attributes: + label: System details + description: Version (`rpm-ostree status -b`) and platform (Bare Metal/QEMU/AWS/GCP/etc.) where you've seen the issue. + placeholder: | + - Bare Metal/QEMU/AWS/GCP/etc. + - Fedora CoreOS version + validations: + required: true + + - type: textarea + id: bug-config + attributes: + label: Butane or Ignition config + description: The Butane config or Ignition config used to provision your system. Be sure to sanitize any private data. If not using Butane to generate your Ignition config, ensure the Ignition config passes validation using [ignition-validate](https://coreos.github.io/ignition/getting-started/#config-validation). + # Might be Butane YAML or Ignition JSON, which is upward-compatible + # with YAML + render: yaml + validations: + required: false + + - type: textarea + id: bug-additional + attributes: + label: Additional information + description: Add any other information about the problem here. + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/enhancement.yml b/.github/ISSUE_TEMPLATE/enhancement.yml new file mode 100644 index 0000000..47a4bb0 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/enhancement.yml @@ -0,0 +1,32 @@ +name: Request an enhancement +description: Request a new feature in Fedora CoreOS +labels: ["kind/enhancement"] +assignees: [] +body: + - type: textarea + id: enhancement-description + attributes: + label: Describe the enhancement + description: A clear and concise description of the desired feature. + placeholder: I want to use foo with bar on Fedora CoreOS. + validations: + required: true + + - type: textarea + id: enhancement-system + attributes: + label: System details + description: Platform (Bare Metal/QEMU/AWS/GCP/etc.) where you'd want to see this feature. Version you've tried that does not have it. + placeholder: | + - Bare Metal/QEMU/AWS/GCP/etc. + - Fedora CoreOS version + validations: + required: false + + - type: textarea + id: enhancement-additional + attributes: + label: Additional information + description: Add any other information about the problem here. + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/implementing-new-emerging-platform.md b/.github/ISSUE_TEMPLATE/implementing-new-emerging-platform.md new file mode 100644 index 0000000..de334f4 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/implementing-new-emerging-platform.md @@ -0,0 +1,41 @@ +# Implementing a new emerging platform + +This template is a simplified version of the +[full template](https://github.com/coreos/fedora-coreos-tracker/blob/main/.github/ISSUE_TEMPLATE/implementing-new-platform.md) +that only includes what is strictly needed to get initial support for a new +platform in Fedora CoreOS. This simplified version notably does not include the +steps needed to add new boot images to the release process. + +Platforms added via this process are labelled "emerging" and users will have to +get boot images for them by converting existing images in the right format and +changing the `ignition.platform.id=` command line parameter. + +This process will be documented using `guestfish` as an example. + +## During Development + +Create PRs addressing the following: + +- [ ] [Ignition](https://github.com/coreos/ignition/) ([example PR](https://github.com/coreos/ignition/pull/918)) + - [ ] Add userdata fetch + - [ ] If the platform supports it (unlikely), add userdata deletion +- [ ] [Afterburn](https://github.com/coreos/afterburn/) ([example PR](https://github.com/coreos/afterburn/pull/451)) + - [ ] (Cloud Only) Add relevant attributes + - [ ] (Cloud Only) Add SSH key support if available + - [ ] (Cloud Only) Add hostname support if available + - [ ] (Cloud Only) Add check-in if needed (unlikely) +- [ ] [fedora-coreos-docs](https://github.com/coreos/fedora-coreos-docs) ([example PR](https://github.com/coreos/fedora-coreos-docs/pull/377)) + - [ ] Add a `provisioning-.adoc` that walks through how to setup the new platform + - [ ] Add an entry in the `modules/ROOT/nav.adoc` that points to new documentation +- [ ] (Optional but recommended) Add support for the platform to [kola](https://github.com/coreos/coreos-assembler) to simplify testing +- Create or ask for a new upstream releases for: + - [ ] Ignition + - [ ] Afterburn +- Wait for new images with updated Ignition and Afterburn to reach stable then + merge documentation with `guestfish` commands: + - [ ] fedora-coreos-docs + +## At Release + +There are no "At Release" steps as we do not produce new boot images for +emerging platforms/ diff --git a/.github/ISSUE_TEMPLATE/implementing-new-platform.md b/.github/ISSUE_TEMPLATE/implementing-new-platform.md new file mode 100644 index 0000000..4ede3f2 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/implementing-new-platform.md @@ -0,0 +1,63 @@ +# Implementing a new supported platform + +## During Development + +Create PRs addressing the following: + +- [ ] [Ignition](https://github.com/coreos/ignition/) ([example PR](https://github.com/coreos/ignition/pull/918)) + - [ ] Add userdata fetch + - [ ] If the platform supports it (unlikely), add userdata deletion +- [ ] [Afterburn](https://github.com/coreos/afterburn/) ([example PR](https://github.com/coreos/afterburn/pull/451)) + - [ ] (Cloud Only) Add relevant attributes + - [ ] (Cloud Only) Add SSH key support if available + - [ ] (Cloud Only) Add hostname support if available + - [ ] (Cloud Only) Add check-in if needed (unlikely) +- [ ] [stream-metadata-go](https://github.com/coreos/stream-metadata-go) ([example PR](https://github.com/coreos/stream-metadata-go/pull/45/)) + - [ ] Add platform to the `Media` struct in `release/release.go` + - [ ] Add supporting code for new platform to `toStreamArch` func in `release/translate.go` + - [ ] (Cloud Only) Cloud Images need to have an `Images` field +- [ ] (Cloud Only) [stream-metadata-rust](https://github.com/coreos/stream-metadata-rust/) ([example PR](https://github.com/coreos/stream-metadata-rust/pull/16)) +- [ ] [fedora-coreos-tracker](https://github.com/coreos/fedora-coreos-tracker/) ([example PR](https://github.com/coreos/fedora-coreos-tracker/pull/1213)) + - [ ] Update the metadata for the new platform +- [ ] [coreos-assembler](https://github.com/coreos/coreos-assembler) ([example PR](https://github.com/coreos/coreos-assembler/pull/2489)) + - [ ] Updated `cmd-generate-release-meta` + - [ ] `cosa osbuild ` works +- [ ] [fedora-coreos-config](https://github.com/coreos/fedora-coreos-config/) + - [ ] Add a stanza to `platforms.yaml` if the system should use a serial console, or both serial and graphical consoles +- [ ] [fedora-websites-3.0](https://gitlab.com/fedora/websites-apps/fedora-websites/fedora-websites-3.0/) + - [ ] Add friendly name for platform to `components/utilities/FpDownloadItem.vue` + - [ ] Add artifact to `pages/coreos/download.vue` + - [ ] Possibly add logo to `content/editions/coreos/home.yml` +- [ ] [fedora-coreos-browser](https://github.com/coreos/fedora-coreos-browser) ([example PR](https://github.com/coreos/fedora-coreos-browser/pull/35)) + - [ ] Add a list element for new platform in `browser/index.html` +- [ ] [build pipeline](https://github.com/coreos/fedora-coreos-pipeline) ([example PR](https://github.com/coreos/fedora-coreos-pipeline/pull/815)) + - [ ] Add platform to the list found in `config.yaml` for building the new artifact +- [ ] [fedora-coreos-docs](https://github.com/coreos/fedora-coreos-docs) ([example PR](https://github.com/coreos/fedora-coreos-docs/pull/377)) + - [ ] Add a `provisioning-.adoc` that walks through how to setup the new platform + - [ ] Add an entry in the `modules/ROOT/nav.adoc` that points to new documentation + +## At Release + +1. Merge upstream changes and put out a release: + - [ ] Ignition + - [ ] Afterburn +1. Merge metadata changes: + - [ ] stream-metadata-go + - [ ] stream-metadata-rust + - [ ] fedora-coreos-tracker + - [ ] fedora website + - [ ] fedora-coreos-browser +1. Release updated components + - [ ] Create and follow release checklist for [stream-metadata-go](https://github.com/coreos/stream-metadata-go/blob/main/docs/development.md#release-process) + - [ ] Ensure that Dependabot has PRed stream-metadata-go into fedora-coreos-stream-generator and coreos-assembler. Merge the update PRs. + - This can be triggered manually by navigating to [fedora-coreos-stream-generator's Dependabot](https://github.com/coreos/fedora-coreos-stream-generator/network/updates/) and [coreos-assembler's Dependabot](https://github.com/coreos/coreos-assembler/network/updates) respectively, then clicking "Check for updates". + - This might need to be done a few times, as Dependabot might not pick up tag changes for a few attempts after initial tagging. + - [ ] Create and follow release checklist for [fedora-coreos-stream-generator](https://github.com/coreos/fedora-coreos-stream-generator/blob/main/docs/development.md#release-process) +1. Merge the following changes: + - [ ] coreos-assembler +1. Wait for updates made to coreos-assembler to be propagated to latest container + - [ ] Download latest version of coreos-assembler container. Verify platform support functionality. +1. Merge changes for: + - [ ] Build pipeline +1. Wait for new images to reach stable then merge documentation. + - [ ] fedora-coreos-docs merged diff --git a/.github/ISSUE_TEMPLATE/new-feature.md b/.github/ISSUE_TEMPLATE/new-feature.md new file mode 100644 index 0000000..808e7b6 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/new-feature.md @@ -0,0 +1,59 @@ +--- +name: Implement a feature +about: Propose a design for a new feature +--- + +# Feature proposal + +## Description + + + +## Implementation PRs + + + +## Did you consider? + + + +- Storage + - [ ] Disk space usage + - [ ] Behavior on 4Kn disks + - [ ] Compatibility with multiple ESPs (Butane `boot_device.mirror`) +- First boot + - [ ] Behavior on first boot vs. second boot + - [ ] initrd networking requirements + - [ ] Reprovisioned systems that reused existing storage devices +- OS update + - [ ] Behavior after an OS rollback + - [ ] Compatibility with old bootloaders +- Architectures + - aarch64 + - [ ] Compatibility with non-UEFI boot + - ppc64le + - [ ] Whether new GRUB directives are supported by petitboot + - s390x + - [ ] Endianness issues + - [ ] Need to rerun `zipl` to update kernel or kargs + - [ ] ECKD/MBR lack of partition labels + - [ ] ECKD maximum partition count +- Implementation + - [ ] How interlocking PRs will be ratcheted into repos + +## Implementation steps + +- [ ] Create tracker ticket with initial design (above) +- [ ] Initial discussion and refinement in the ticket +- [ ] Add `meeting` label +- [ ] Discuss at community meeting +- [ ] Further refinement + - [ ] Post draft [fedora-coreos-docs](https://github.com/coreos/fedora-coreos-docs/) PR, ideally before doing any implementation, to help identify design problems. +- [ ] Update issue description with final proposal and post a comment saying that you did +- [ ] Verify that rough consensus exists +- [ ] Implement. Post PR links in the section above. In the description of each PR, link to this issue and specify the prerequisites for merging. + - [ ] Add kola test(s) for new feature +- [ ] Land implementation PRs, in order +- [ ] Wait for the functionality to reach FCOS stable +- [ ] Land docs PR +- [ ] Remove any ratcheting glue (e.g. workarounds in coreos-assembler) diff --git a/.github/ISSUE_TEMPLATE/new-package.yml b/.github/ISSUE_TEMPLATE/new-package.yml new file mode 100644 index 0000000..f545e01 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/new-package.yml @@ -0,0 +1,84 @@ +name: Request a new package +description: Ask for a new package to be added to Fedora CoreOS +title: "New Package Request: " +labels: ["kind/enhancement"] +assignees: [] +body: + - type: markdown + attributes: + value: | + Please try to answer the following questions about the package you are requesting. + + - type: textarea + id: newpackage-dependencies + attributes: + label: What, if any, are the additional dependencies on the package? (i.e. does it pull in Python, Perl, etc) + description: Paste here the output of `rpm-ostree install --dry-run ` from a fresh Fedora CoreOS node. + validations: + required: true + + - type: textarea + id: newpackage-size + attributes: + label: What is the size of the package and its dependencies? + description: Paste here the output of `rpm -qi ` for each package mentioned above. + validations: + required: true + + - type: textarea + id: newpackage-solution + attributes: + label: What problem are you trying to solve with this package? Or what functionality does the package provide? + validations: + required: true + + - type: textarea + id: newpackage-container + attributes: + label: Can the software provided by the package be run from a container? Explain why or why not. + validations: + required: true + + - type: textarea + id: newpackage-debug-container + attributes: + label: Can the tool(s) provided by the package be helpful in debugging container runtime issues? + validations: + required: true + + - type: textarea + id: newpackage-debug-network + attributes: + label: Can the tool(s) provided by the package be helpful in debugging networking issues? + validations: + required: true + + - type: textarea + id: newpackage-day2 + attributes: + label: Is it possible to layer the package onto the base OS as a day 2 operation? Explain why or why not. + description: Can the package be installed on first boot or later with `rpm-ostree install `? + validations: + required: true + + - type: textarea + id: newpackage-service + attributes: + label: In the case of packages providing services and binaries, can the packaging be adjusted to just deliver binaries? + validations: + required: true + + - type: textarea + id: newpackage-interpreter + attributes: + label: Can the tool(s) provided by the package be used to do things we’d rather users not be able to do in FCOS? + description: E.g. can it be abused as a Turing complete interpreter? + validations: + required: true + + - type: textarea + id: newpackage- + attributes: + label: Does the software provided by the package have a history of CVEs? + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/new-platform.yml b/.github/ISSUE_TEMPLATE/new-platform.yml new file mode 100644 index 0000000..35ad0ac --- /dev/null +++ b/.github/ISSUE_TEMPLATE/new-platform.yml @@ -0,0 +1,87 @@ +name: Request a new platform +description: Ask for Fedora CoreOS to support a new cloud environment +title: "Platform Request: " +labels: ["area/platforms", "kind/enhancement"] +assignees: [] +body: + - type: markdown + attributes: + value: | + In order to implement support for a new cloud platform in Fedora CoreOS, we need to know several things about the platform. Please try to answer as many questions as you can. + + - type: textarea + id: newplatform-user + attributes: + label: Why is the platform important? Who uses it? + validations: + required: false + + - type: textarea + id: newplatform-name + attributes: + label: What is the official name of the platform? Is there a short name that's commonly used in client API implementations? + validations: + required: false + + - type: textarea + id: newplatform-userdata + attributes: + label: How can the OS retrieve instance userdata? What happens if no userdata is provided? + validations: + required: false + + - type: textarea + id: newplatform-sshkeys + attributes: + label: Does the platform provide a way to configure SSH keys for the instance? How can the OS retrieve them? What happens if none are provided? + validations: + required: false + + - type: textarea + id: newplatform-network + attributes: + label: How can the OS retrieve network configuration? Is DHCP sufficient, or is there some other network-accessible metadata service? + validations: + required: false + + - type: textarea + id: newplatform-hostname + attributes: + label: In particular, how can the OS retrieve the system hostname? + validations: + required: false + + - type: textarea + id: newplatform-console + attributes: + label: Does the platform require the OS to have a specific console configuration? + validations: + required: false + + - type: textarea + id: newplatform-boot-success + attributes: + label: Is there a mechanism for the OS to report to the platform that it has successfully booted? Is the mechanism required? + validations: + required: false + + - type: textarea + id: newplatform-agent + attributes: + label: Does the platform have an agent that runs inside the instance? Is it required? What does it do? What language is it implemented in, and where is the source code repository? + validations: + required: false + + - type: textarea + id: newplatform-image-upload + attributes: + label: How are VM images uploaded to the platform and published to other users? Is there an API? What disk image format is expected? + validations: + required: false + + - type: textarea + id: newplatform-quirks + attributes: + label: Are there any other platform quirks we should know about? + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/rebase.md b/.github/ISSUE_TEMPLATE/rebase.md new file mode 100644 index 0000000..64ad4b4 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/rebase.md @@ -0,0 +1,226 @@ +# Rebase to a new version of Fedora (N) + +## At previous Fedora major release + +### Open tickets to track related work for this release + +- [ ] Fedora Changes Considerations ([example](https://github.com/coreos/fedora-coreos-tracker/issues/1222)) +- [ ] Package Additions/Removals ([example](https://github.com/coreos/fedora-coreos-tracker/issues/1221)) +- [ ] Test Week ([template](https://github.com/coreos/fedora-coreos-tracker/issues/new?template=test-week.md&title=tracker:+FN+Test+Week)) +- [ ] Communications Tracker ([example](https://github.com/coreos/fedora-coreos-tracker/issues/1655)) + +## At the first change checkpoint + +### Untag old packages + +`koji untag` N-2 packages from the pool (at some point we'll have GC in place to do this for us, but for now we must remember to do this manually or otherwise distRepo will fail once the signed packages are GC'ed). For example the following snippet finds all RPMs signed by the Fedora 32 key and untags them. Use this process: + +- [ ] Find the key short hash. Usually found [here](https://pagure.io/fedora-infra/ansible/blob/main/f/roles/bodhi2/backend/templates/pungi.rpm.conf.j2). Then: + +``` +f32key=12c944d0 +key=$f32key +echo > untaglist # create or empty out file +for build in $(koji list-tagged --quiet coreos-pool | cut -f1 -d' '); do + if koji buildinfo $build | grep -i $key 1>/dev/null; then + echo "Adding $build to untag list" + echo "${build}" >> untaglist + fi +done +``` + +Now we have a list of builds to untag. But we need a few more sanity checks. + +- [ ] Make sure none of the builds are used in `N` based FCOS. Check by running: + +``` +f32key=12c944d0 +key=$f32key +podman run -it --rm quay.io/fedora/fedora-coreos:testing-devel rpm -qai | grep -i -B 9 $key +podman rmi quay.io/fedora/fedora-coreos:testing-devel +``` + +If there are any RPMs signed by the old key they'll need to be investigated. Maybe they shouldn't be used any longer. Or maybe they're still needed. One example of this is the shim RPM where the same build could be used for many Fedora releases. In this case you'll need to untag the RPM from `coreos-pool`, run a `koji distrepo`, which will remove that RPM from the repo metadata, and then re-tag it into the pool. The RPM in the repo will now be signed with a newer signing key. + + + +- [ ] After verifying the list looks good, untag: + +``` +# use xargs so we don't exhaust bash string limit +cat untaglist | xargs -L50 koji untag-build -v coreos-pool +``` + +- [ ] Now that untagging is done, give a heads up to rpm-ostree developers that N-2 packages have been untagged and that they may need to update their CI compose tests to freeze on a newer FCOS commit. + +- [ ] Remove the N-2 signing key from the tag info for the coreos-pool tag. The following commands view the current settings and then update the list to the 33/34/35 keys. You'll most likely have to get someone from releng to run the second command (`edit-tag`). + - `koji taginfo coreos-pool` + - `koji edit-tag coreos-pool -x tag2distrepo.keys="9570ff31 45719a39 9867c58f"` + +## At Branching + +Branching is when a new stream is "branched" off of `rawhide`. This eventually becomes the next major Fedora (N). + +### Release engineering changes + +- [ ] Verify that a few tags were created when branching occurred: + +- `f${N+1}-coreos-signing-pending` +- `f${N+1}-coreos-continuous` + +- [ ] Add and tag a package (any package) which is in the stable repos into the continuous tag. This will create the initial yum repo that's used as input for building the COSA container. + +- `koji add-pkg --owner ${FAS_USERNAME} f${N+1}-coreos-continuous $PKG` + - example: `koji add-pkg --owner dustymabe f36-coreos-continuous fedora-release` + - This example uses the [`fedora-release`](https://src.fedoraproject.org/rpms/fedora-release) RPM, but it could be any other. +- `koji tag-build f${N+1}-coreos-continuous $BUILD` + - example: `koji tag-build f36-coreos-continuous fedora-release-36-0.16` + +- [ ] Add the N+1 signing key short hash (usually found [here](https://pagure.io/fedora-infra/ansible/blob/main/f/roles/bodhi2/backend/templates/pungi.rpm.conf.j2)) to the tag info for the coreos-pool tag. The following commands view the current settings and then update the list to the 32/33/34/35 keys. You'll most likely have to get someone from releng to run the second command (`edit-tag`). An example request looks [like this](https://pagure.io/releng/issue/10635). + - `koji taginfo coreos-pool` + - `koji edit-tag coreos-pool -x tag2distrepo.keys="12c944d0 9570ff31 45719a39 9867c58f"` + +### coreos-installer changes + +- [ ] Update coreos-installer to know about the signing key used for the future new major version of Fedora (N+1). + - The current set of trusted signing keys is available at https://fedoraproject.org/security/. + - If the Fedora (N+1) signing key isn't available yet at that site, you can also get it from https://src.fedoraproject.org/rpms/fedora-repos/tree/rawhide. +- [ ] Drop the signing key for the obsolete stable release (N-2). + +Example PR: https://github.com/coreos/coreos-installer/pull/1113 + +### Update `rawhide` stream + +- [ ] Update `VERSION`, `MUTATE_OS_RELEASE`, `BUILDER_IMG` in [build-args.conf](https://github.com/coreos/fedora-coreos-config/blob/rawhide/build-args.conf) ([example PR](https://github.com/coreos/fedora-coreos-config/pull/4003)) + +### Enable `branched` stream + +- [ ] Update `VERSION`, `MUTATE_OS_RELEASE`, `BUILDER_IMG` in [build-args.conf](https://github.com/coreos/fedora-coreos-config/blob/branched/build-args.conf) ([example PR](https://github.com/coreos/fedora-coreos-config/pull/4005)) +- [ ] Update [config.yaml](https://github.com/coreos/fedora-coreos-pipeline/blob/main/config.yaml) to un-comment out the `branched` stream definition ([example PR](https://github.com/coreos/fedora-coreos-pipeline/pull/904)) + +## At Fedora (N) Beta + +### Update [fedora-coreos-config](https://github.com/coreos/fedora-coreos-config/) `next-devel` + +- [ ] Bump `VERSION`, `MUTATE_OS_RELEASE`, `BUILDER_IMG` in `build-args.conf` +- [ ] Add the `fedora-candidate-compose` repo in `manifest.yaml` ([example PR](https://github.com/coreos/fedora-coreos-config/pull/2706)) +- [ ] Update the repos in `manifest.yaml` if needed +- [ ] Run `cosa fetch --dry-run --update-lockfile` + - this updates the x86_64 lockfile - the others will get updated when `bump-lockfile` runs. + - in the future we may support [this](https://github.com/coreos/coreos-assembler/issues/3088) in `cosa fetch` directly +- [ ] PR the result + +- [ ] Re-enable `next-devel` if needed ([docs](https://github.com/coreos/fedora-coreos-pipeline/tree/main/next-devel)) +- [ ] Disable `branched` stream since it is no longer needed. + - Update [config.yaml](https://github.com/coreos/fedora-coreos-pipeline/blob/main/config.yaml) to comment out the `branched` stream definition. + +### Prepare Fedora CoreOS (N) Beta announcement + +- [ ] Draft an announcement that contains information found in the "Communications Tracker", created in a step above, to inform users of Fedora CoreOS of upcoming changes in the Fedora (N) version. [(example)](https://lists.fedoraproject.org/archives/list/coreos@lists.fedoraproject.org/thread/GK4RMQ3UFMLJGKMBUVTTWGNFVFNNSH5E/) + +### Ship rebased `next` + +- [ ] Ship `next` +- [ ] Set a new update barrier for the final release of N-1 on `next`. In the barrier entry set a link to [the docs](https://docs.fedoraproject.org/en-US/fedora-coreos/update-barrier-signing-keys/). See [discussion](https://github.com/coreos/fedora-coreos-tracker/issues/480#issuecomment-1247314065) + + +## Preparing for Fedora (N) GA + +Do these steps as soon as we have a Go confirmation for GA, usually the Thursday of the week before GA. + +### Ship a final `next` release + +If the packages in `next-devel` don't exactly match the last `next` release that was done, we need to do a release with the final GA content. This ensures that what we'll promote to `testing` has the exact content in GA (plus version fast-tracks). This usually happens on the Thursday of the announcement of Go. + +- [ ] Ensure final `next` release has GA content + +### Build rebased `testing` and final `stable` release on N-1 + +- [ ] Build `stable`; promote it from the `testing` branch, which should still be on N-1. Don't release it yet (i.e. don't run the `release` job). +- [ ] Build `testing`; promote it from the `next` branch instead of `testing-devel`. Don't release it yet (i.e. don't run the `release` job). + +### Update [fedora-coreos-config](https://github.com/coreos/fedora-coreos-config/) `testing-devel` + +- [ ] Bump `VERSION`, `MUTATE_OS_RELEASE`, `BUILDER_IMG` in `build-args.conf` +- [ ] Update the repos in `manifest.yaml` if needed +- [ ] Sync the lockfiles for all arches from `next-devel` +- [ ] Bump the base Fedora version in `ci/buildroot/Dockerfile` +- [ ] Bump the Fedora version for the test containers in `tests/kola/data/commonlib.sh` +- [ ] PR the result + + +## At Fedora (N) GA + +Do these steps on GA day. + +### Release rebased `testing` and final `stable` release on N-1 + +- [ ] Run the `release` job for the staged `testing` and `stable` builds and start rollout. +- [ ] Set a new update barrier for the final release of N-1 on `testing`. In the barrier entry set a link to [the docs](https://docs.fedoraproject.org/en-US/fedora-coreos/update-barrier-signing-keys/). See [discussion](https://github.com/coreos/fedora-coreos-tracker/issues/480#issuecomment-1247314065) + +### Disable `next-devel` stream if not needed + +We prefer to disable `next-devel` when there is no difference between `testing-devel` and `next-devel`. This allows us to prevent wasting a bunch of resources (bandwidth, storage, compute) for no reason. After the switch to N if `next-devel` and `testing-devel` are in lockstep, then disable `next-devel`. + +- [ ] Follow the instructions [here](https://github.com/coreos/fedora-coreos-pipeline/tree/main/next-devel) to disable `next-devel` + +### Switch upstream packages to shipping release binaries from Fedora (N) + +- [ ] Update [repo-templates](https://github.com/coreos/repo-templates) [config.yaml](https://github.com/coreos/repo-templates/blob/main/config.yaml) with the version number and GPG key ID for Fedora (N). + +### Disable the `fedora-candidate-compose` repo + +- [ ] Remove from the `manifest.yaml` of `next-devel` the `fedora-candidate-compose` repo + +## After Fedora (N) GA + +### Ship rebased `stable` + +- [ ] Ship `stable` +- [ ] Set a new update barrier for the final release of N-1 on `stable`. In the barrier entry set a link to [the docs](https://docs.fedoraproject.org/en-US/fedora-coreos/update-barrier-signing-keys/). See [discussion](https://github.com/coreos/fedora-coreos-tracker/issues/480#issuecomment-1247314065) + +### Open ticket for the next Fedora rebase + +- [ ] Create a new ticket from the [rebase template](https://github.com/coreos/fedora-coreos-tracker/issues/new?assignees=&labels=area%2Fplatforms%2C+kind%2Fenhancement&template=rebase.md&title=tracker:+Rebase+onto+Fedora+N) + - label with `FN` label where `N` is the Fedora version. + +### Update the FCOS Meeting-Action Template + +Now that Fedora N is GA, we need to start tracking the release schedule of Fedora N+1 during the weekly [Fedora CoreOS Community Meeting](https://github.com/coreos/fedora-coreos-tracker/blob/main/README.md#meetings). + +- [ ] Update the "Review Fedora N Release Schedule" topic and link to point to Fedora N+1 in the [FCOS meeting-action template](https://github.com/coreos/fcos-meeting-action/blob/main/static/meeting-template.md) + + +## Miscellaneous container updates + +These are various containers in use throughout our ecosystem. We should update or open a ticket to track updating them once a new Fedora release is out. If you open a ticket instead of doing the update add a link to the ticket as comment. + +- [ ] Update coreos-assembler or open ticket to update: + - [Dockerfile](https://github.com/coreos/coreos-assembler/blob/main/Dockerfile) + - [Dockerfiles for kola test containers](https://github.com/coreos/coreos-assembler/tree/main/tests/containers) + - [Dockerfile for the OpenShift CI buildroot image](https://github.com/openshift/release/blob/master/ci-operator/config/coreos/coreos-assembler/coreos-coreos-assembler-main.yaml) +- [ ] Update coreos-installer + - [Dockerfile](https://github.com/coreos/coreos-installer/blob/main/Dockerfile) +- [ ] Update Ignition + - [Dockerfile.validate](https://github.com/coreos/ignition/blob/main/Dockerfile.validate) +- [ ] Update Butane + - [Dockerfile](https://github.com/coreos/butane/blob/main/Dockerfile) +- [ ] Update fedora-coreos-cincinnati + - [Dockerfile](https://github.com/coreos/fedora-coreos-cincinnati/blob/main/dist/fedora-infra/Dockerfile) + - [ImageStream](https://pagure.io/fedora-infra/ansible/blob/main/f/roles/openshift-apps/coreos-cincinnati/templates/imagestream.yml) + - [BuildConfig](https://pagure.io/fedora-infra/ansible/blob/main/f/roles/openshift-apps/coreos-cincinnati/templates/buildconfig.yml) + - [Git Hash Variables (Optional)](https://pagure.io/fedora-infra/ansible/blob/main/f/roles/openshift-apps/coreos-cincinnati/vars) +- [ ] Update config-bot + - [Dockerfile](https://github.com/coreos/fedora-coreos-releng-automation/blob/main/config-bot/Dockerfile) +- [ ] Update coreos-koji-tagger + - [Dockerfile](https://github.com/coreos/fedora-coreos-releng-automation/blob/main/coreos-koji-tagger/Dockerfile) + - [ImageStream](https://pagure.io/fedora-infra/ansible/blob/main/f/roles/openshift-apps/coreos-koji-tagger/templates/imagestream.yml) + - [BuildConfig](https://pagure.io/fedora-infra/ansible/blob/main/f/roles/openshift-apps/coreos-koji-tagger/templates/buildconfig.yml) +- [ ] Update coreos-ostree-importer + - [Dockerfile](https://github.com/coreos/fedora-coreos-releng-automation/blob/main/coreos-ostree-importer/Dockerfile) + - [ImageStream](https://pagure.io/fedora-infra/ansible/blob/main/f/roles/openshift-apps/coreos-ostree-importer/templates/imagestream.yml) + - [BuildConfig](https://pagure.io/fedora-infra/ansible/blob/main/f/roles/openshift-apps/coreos-ostree-importer/templates/buildconfig.yml) +- [ ] Update fedora-ostree-pruner + - [Dockerfile](https://github.com/coreos/fedora-coreos-releng-automation/blob/main/fedora-ostree-pruner/Dockerfile) + - [ImageStream](https://pagure.io/fedora-infra/ansible/blob/main/f/roles/openshift-apps/fedora-ostree-pruner/templates/imagestream.yml) + - [BuildConfig](https://pagure.io/fedora-infra/ansible/blob/main/f/roles/openshift-apps/fedora-ostree-pruner/templates/buildconfig.yml) diff --git a/.github/ISSUE_TEMPLATE/test-week.md b/.github/ISSUE_TEMPLATE/test-week.md new file mode 100644 index 0000000..b5001b9 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/test-week.md @@ -0,0 +1,56 @@ +--- +name: Schedule a Fedora Test Week +about: Schedule a Fedora Test Week for a new Fedora major release +title: '' +labels: 'community', 'meeting' +assignees: '' +--- + +## Initial Tasks (to be done at least one week before test week) + +- [ ] Open this ticket in the `fedora-coreos-tracker` repo +- [ ] Open a ticket with [Fedora QA](https://pagure.io/fedora-qa/issues). + - [F36 example](https://pagure.io/fedora-qa/issue/695) + +To be done after the Fedora QA folks have taken action on the QA ticket: + +- [ ] Confirm the Test Day page is created on the Fedora Wiki. + - For example: +- [ ] Confirm the Test Day results app is created. + - For example: +- [ ] Choose a day during the Test Week to host a video session for live debug help +- [ ] Setup a Google Meet or other video conference session +- [ ] Create a HackMD doc for capturing notes during live video session +- [ ] Find volunteers to enumerate new documentation + test cases required for Test Week + - Best done via dedicated video session +- [ ] File an issue on `fedora-coreos-tracker` with TODO items. + - For example: +- [ ] File a ticket requesting a Fedora badge is created + - For example: + +## Announcing Test Week + +Should be completed after the Initial Tasks are done + +- [ ] Draft an email to announcing the Test Week + - [ ] Include a link to the Fedora Wiki + - [ ] Include a link to the Test Day results app + - [ ] Include a link to `fedora-coreos-tracker` for Test Week + - [ ] Include a link to the video conference + - [ ] Include a link to the HackMD doc +- [ ] Cross-post announcement email to discussion.fedoraproject.org with `#coreos` tag + +- Example format: + +## During Test Week + +- Monitor `fedora-coreos-tracker` for new issues reported as part of Test Week +- Monitor #fedora-coreos on IRC for new issues reported as part of Test Week +- Ensure there is one or more representatives of Fedora CoreOS team present for live video session + +## After Test Week + +- [ ] Update `fedora-coreos-tracker` ticket with any issues found +- [ ] Update `fedora-coreos-tracker` ticket with any documentation updates made +- [ ] Review Test Day results app and follow-up on any errors reported, if possible +- [ ] Follow up with the Fedora Badges ticket with Fedora Account System (FAS) usernames that participated in Test Week diff --git a/.github/workflows/checks.yml b/.github/workflows/checks.yml new file mode 100644 index 0000000..0439425 --- /dev/null +++ b/.github/workflows/checks.yml @@ -0,0 +1,18 @@ +--- +name: Checks + +on: + push: + branches: [main] + pull_request: + branches: [main] + +jobs: + checks: + name: Checks + runs-on: ubuntu-latest + steps: + - name: Check out repository + uses: actions/checkout@v3 + - name: Verify meeting-people.txt is sorted + run: awk '!/^$/ {if (name) print} /^exit 0$/ { name = 1 }' meeting-people.txt | sort -c diff --git a/Design.md b/Design.md index 9604ede..6b83bb1 100644 --- a/Design.md +++ b/Design.md @@ -8,12 +8,17 @@ conclusion should be summarized here with a link to the issue. - [Disk Layout](#disk-layout) - [Approach towards shipping Python](#approach-towards-shipping-Python) - [Identification in `/etc/os-release`](#identification-in-etcos-release) +- [Firewall management](#firewall-management) - [Cloud Agents](#cloud-agents) - [Supported Ignition Versions](#supported-ignition-versions) +- [Configuration Language and Transpiler](#configuration-language-and-transpiler) +- [Security policies](#security-policies) +- [Bucket layout](#bucket-layout) +- [Version numbers](#version-numbers) ## OSTree Delivery Format -- Originally discussed in issue [#23](https://github.com/coreos/fedora-coreos-tracker/issues/23). +- Originally discussed in issue [#23](https://github.com/coreos/fedora-coreos-tracker/issues/23). ### Summary: @@ -24,7 +29,7 @@ end user systems: repo) on a server and fetched via HTTP requests. - rojig: uses a special rojig RPM and re-assembles OSTree commit from RPMs already on mirrors. -- OCI: OSTree commits are packaged up in OCI container images and delivered +- OCI: OSTree commits are packaged up in OCI container images and delivered via a container registry. Currently the plan in Fedora CoreOS is to deliver content via a plain @@ -41,9 +46,7 @@ Fedora CoreOS will have several refs for use on production machines. At any giv - `testing`: Periodic snapshot of the current Fedora release plus Bodhi `updates`. - `stable`: Promotion of a `testing` release, including any needed fixes. -- `next`: - 1. After Bodhi is enabled for the upcoming Fedora release, tracks that release; before then, tracks `testing`. - 2. After the upcoming kernel release has reached rc6 and before it goes final, tracks the rawhide kernel. After the kernel goes final and before it is included in the tracked Fedora release, tracks the kernel from Bodhi `updates-testing`. +- `next`: The `next` stream represents the future. It will often be used to experiment with new features and also test out rebases of our platform on top of the next major version of Fedora. See [Major Fedora Version Rebases](#major-fedora-version-rebases) for more info. All of these refs will be unversioned, in the sense that their names will not include the current Fedora major version. The stream cadences are not contractual, but will initially have two weeks between releases. The stream maintenance policies are also not contractual and may evolve from those described above, but changes will preserve the use cases and intended stability of each stream. @@ -51,26 +54,47 @@ Users will be encouraged to run most of their production systems on `stable`, an ### Development Refs -There will also be some additional unversioned refs for the convenience of Fedora CoreOS developers. These will be public, but won't be exposed to users in the same way as production refs: they might be in a different repo, or in the same repo but not listed in the summary file. None of these are contractual; they might go away if we don't find them useful. +Development for the next `testing` and `next` releases will occur in development refs. These refs will be public, but will be stored in a different ostree repo from production refs. + +- `testing-devel`: Nightly build of the package set that will be snapshotted for the next `testing` release. +- `next-devel`: Nightly build of the package set that will be snapshotted for the next `next` release. + +### Mechanical Refs + +There will also be some additional unversioned refs for the convenience of Fedora CoreOS developers. These will be public and stored in the same ostree repo as development refs. Unlike production and development refs, mechanical refs are not curated; they're simply a snapshot of the corresponding Bodhi repos, with no package pinning and no backports of fixes. None of these refs are contractual; they might go away if we don't find them useful. - `rawhide`: Nightly snapshot of rawhide. -- `bodhi-updates`: Nightly snapshot of Bodhi `updates` for the Fedora release currently tracked by `testing`. -- `bodhi-updates-testing`: Nightly snapshot of Bodhi `updates-testing` for the Fedora release currently tracked by `testing`. +- `branched`: Nightly snapshot of the upcoming Fedora release after it is branched. ### Out-of-Cycle Releases Due to the promotion structure described above, `stable` can contain packages that are as much as four weeks out of date. Sometimes, however, there will be an important bugfix or security fix that cannot wait a month to reach `stable` (or two weeks to reach `next` or `testing`). In that case, the fix will be incorporated into out-of-cycle releases on affected streams. These releases will not affect the regular promotion schedules; for example, a fix might sit in `testing` for only a few days before it is promoted to `stable`. -A fix can take one of two forms: +If a fix is important enough for an out-of-cycle `stable` release, other affected release streams should be updated as well. + +In some cases it may make sense to apply a fix to `testing` but not issue an out-of-cycle release, allowing the fix to be picked up automatically when `testing` promotes to `stable`. -1. An updated package taken directly from Fedora -2. A minimal fix applied to the package version already present in the affected stream +### Major Fedora Version Rebases -We'll need infrastructure for both approaches, and the ability to choose between them on a case-by-case basis. Option 1 is cleaner and easier, but may not always be safe. Option 2 is especially useful for the kernel, where we'll want to fix individual bugs without pushing an entire stable kernel update directly to the `stable` stream. +The release process integrates with Fedora's release milestones in the following ways: -If a fix is important enough for an out-of-cycle `stable` release, other affected release streams should be updated as well. +- Fedora Beta Release + - The `next` stream is switched over to the new release. +- Fedora Final Freeze + - The `next` stream switches to weekly releases to closely track the GA content set. +- Fedora General Availability + - Fedora CoreOS re-orients its release schedule in the following way: + - Week -1 (Fedora "Go" Decision): `next` release: + - `next` release with final Fedora GA content + - Week 0 (GA release): triple release: + - `stable` release promoted from previous `testing` (on N-1) + - `testing` release promoted from previous `next` + - `next` release contains latest Fedora N content, including Bodhi updates + - Week 2: triple release: + - `stable` release promoted from previous `testing`, now fully rebased to Fedora N + - `testing` and `next` are now in sync -In some cases it may make sense to apply a fix to `testing` but not issue an out-of-cycle release, allowing the fix to be picked up automatically when `testing` promotes to `stable`. +We have [a checklist](https://github.com/coreos/fedora-coreos-tracker/blob/main/.github/ISSUE_TEMPLATE/rebase.md) to track the exact steps followed during a rebase. ### Deprecation @@ -78,7 +102,7 @@ Because production refs are unversioned, users will seamlessly upgrade between F ## Disk Layout -- Originally discussed in issue [#18](https://github.com/coreos/fedora-coreos-tracker/issues/18). +- Originally discussed in issue [#18](https://github.com/coreos/fedora-coreos-tracker/issues/18). See also [dustymabe's comment](https://github.com/coreos/fedora-coreos-tracker/issues/18#issuecomment-409668929) summarizing the discussion in the FCOS meeting. - Filesystem details were discussed in [#33](https://github.com/coreos/fedora-coreos-tracker/issues/33). @@ -97,18 +121,7 @@ Because production refs are unversioned, users will seamlessly upgrade between F FCOS should have a fixed partition layout that Ignition can modify on first boot. The installer will be similar to the Container Linux installer; the core of it will be dd'ing an image to the disk. -The partition layout is still undecided, but initial proposals look something like: - - Number Type Purpose - ----------------------------------- - 1 fat32 Boot partition/ESP - 2 N/A Bios Boot partition - 3 XFS Root - 4 XFS /var - -We also want to support moving the root partition to new locations by recreating the OSTree at the new location. This -would involve downloading the OSTree repo contents and doing the deploy between the Ignition disks and files stage if -the root filesystem has changed. This is currently untested. +The partition layout will support "dual EFI/BIOS" on x86_64, and will have a single root partition as XFS by default. We will support changing the root filesystem storage (but not `/boot`) via Ignition. ### Open Questions: @@ -162,6 +175,18 @@ Originally discussed in [#21](https://github.com/coreos/fedora-coreos-tracker/is We will identify a Fedora CoreOS server using the `ID=fedora` and `VARIANT_ID=coreos` fields in the `/etc/os-release` file. +## Firewall management + +Originally discussed in [#26](https://github.com/coreos/fedora-coreos-tracker/issues/26). + +### Summary: + + - FCOS will ship without any ad-hoc filtering rules. By default, nodes will boot without firewall. + - Components for both iptables and nft filtering will be provided (namely `iptables`, `nftables`, and `iptables-nft` packages, plus related kernel modules). + - It will be possible to set up static rules (i.e. meant to be valid and unchanged for the whole node lifetime) via Ignition. + - Dynamic rules (i.e. mutable at runtime) are out of scope for FCOS own toolings. + Container runtimes and orchestrators take ownership of those via their own (containerized) rules managers. + ## Cloud Agents Originally discussed in [#12](https://github.com/coreos/fedora-coreos-tracker/issues/12). @@ -174,6 +199,37 @@ Originally discussed in [#12](https://github.com/coreos/fedora-coreos-tracker/is - For the short term, if we need to include an agent we will bake it into the image. We will not have any specific mechanism for including agents. +### AWS: + +Originally discussed in [#66](https://github.com/coreos/fedora-coreos-tracker/issues/66). + +- AWS does not require a cloud agent but does require NVME EBS udev rules +- The udev rules and script will be packaged in an RPM and included in FCOS with work being tracked in [#104](https://github.com/coreos/fedora-coreos-tracker/issues/104) + +### Azure: + +Originally discussed in [#65](https://github.com/coreos/fedora-coreos-tracker/issues/65). + +- We've identified one major gap with not shipping the [Microsoft Azure Linux Agent](https://github.com/Azure/WALinuxAgent): the machine will not check-in and will eventually be culled by Azure for being stuck in the creation process. +- This gap will be covered by work done in [coreos-metadata](https://github.com/coreos/coreos-metadata/issues/120). +- One additional gap which will __not__ be covered is a lack of ephemeral disk support. We plan to ship udev rules but will not have a service which formats the disk unless we receive feature requests in the future. This was discussed in [#97](https://github.com/coreos/fedora-coreos-tracker/issues/97). +- As a cosmetic issue, we should also ship a rule to [ignore SR-IOV interfaces](https://github.com/coreos/fedora-coreos-tracker/issues/115). + +### DigitalOcean: + +Originally discussed in [#71](https://github.com/coreos/fedora-coreos-tracker/issues/71). + +- DigitalOcean has an [agent](https://github.com/digitalocean/do-agent) that provides instance metrics back to DO. We will not ship it. +- DigitalOcean does not generally offer DHCP. Network configuration is obtained from an HTTP metadata service on a link-local address. On other platforms this is handled by cloud-init. +- Networking should be configured by coreos-metadata running in the initramfs, but coreos-metadata [may need to learn to configure NetworkManager or nm-state](https://github.com/coreos/fedora-coreos-tracker/issues/111) depending on the outcome of [#24](https://github.com/coreos/fedora-coreos-tracker/issues/24). + +### OpenStack: + +Originally discussed in [#68](https://github.com/coreos/fedora-coreos-tracker/issues/68). + +- OpenStack environments do not require a cloud agent +- We will provide any base level of functionality with ignition and coreos-metadata + ### Open questions: - What do we do about VMware, which has a very involved and intrusive "agent"? @@ -187,3 +243,117 @@ Originally discussed in [#31](https://github.com/coreos/fedora-coreos-tracker/is - FCOS will only support Ignition spec 3.0.0 and up. - Ignition spec 3.0.0 will break compatibilty with spec 2.x.y, although most configs will only require minor changes. - Tooling should exist to aid converting 2.x.y configs to 3.0.0 configs, although perfect automated translation will not be possible. + +## Configuration Language and Transpiler + +- Originally discussed in issue [#129](https://github.com/coreos/fedora-coreos-tracker/issues/129). +- Versioning discussed in issue [#89](https://github.com/coreos/fedora-coreos-tracker/issues/89) + +### Summary: + +Fedora CoreOS will have a configuration language similar to the [Container Linux Configuration Language](https://coreos.com/os/docs/latest/configuration.html) named the Fedora CoreOS Configuration Language (FCCL). There will be a tool, the Fedora CoreOS Configuration Transpiler (FCCT) to convert Fedora CoreOS Configs (FCCs) to Ignition configs. + +The FCCL will be versioned using semver, similar to how the Ignition spec is versioned. FCCT will accept all versions of the FCCL. Each FCCL version will target exactly one Ignition spec version. +This means: +- Old FCCs will continue to work with new versions of FCCT without modification. +- Each FCCL version will always emit the same version of Ignition config, regardless of what version of FCCT was used to transpile it. +- Since FCOS will accept old (down to 3.0.0) versions of Ignition configs, old FCCs will continue to work with new FCOS releases without modification. +- To use new features in new FCCT releases, users must update their configs to use the new FCCL spec. + +## Security policies + +### No autologin by default + +Originally discussed in [#114](https://github.com/coreos/fedora-coreos-tracker/issues/114). + +We will not enable autologin on serial or VGA consoles by default, even on platforms (e.g. Azure, DigitalOcean, GCP) which provide authenticated console access. Doing so would provide an access vector that could surprise users unfamiliar with their platform's console access mechanism and access control policy. For users who wish to use the console for debugging, we will provide documentation for using Ignition to enable autologin or to set a user password. + +### Automatically disable SMT when needed to address vulnerabilities + +Originally discussed in [#181](https://github.com/coreos/fedora-coreos-tracker/issues/181). + +There have been multiple rounds of CPU vulnerabilities (L1TF and MDS) which cannot be completely mitigated without disabling Simultaneous Multi-Threading on affected processors. Disabling SMT has a cost: it reduces system performance and changes the apparent number of processors on the system. However, enabling SMT on affected systems would be an insecure default. + +By default, Fedora CoreOS will configure the kernel to disable SMT on vulnerable machines. This conditional approach avoids incurring the performance cost on systems that aren't vulnerable. However, it fails to protect systems affected by undisclosed SMT vulnerabilities, and it allows future OS updates to disable SMT without notice if new vulnerabilities become known. + +We will document this policy and its consequences, and provide instructions for unconditionally enabling or disabling SMT for users who prefer a different policy. + +## Bucket Layout + +Originally discussed in [#189](https://github.com/coreos/fedora-coreos-tracker/issues/189). + +The `fcos-builds` bucket, fronted by http://builds.coreos.fedoraproject.org/ will be structured as follows: + +``` +/ + prod/ + streams/ + stable/ + releases.json + builds/ + builds.json + 30.1234-5/ + release.json + x86_64/ + meta.json + commitmeta.json + fedora-coreos-30.8-qemu.x86_64.qcow2.gz + ostree-commit-object + ostree-commit.tar + ... + ppc64le/ + ... + ... + testing/ + next/ + ... + streams/ + stable.json + testing.json + ... +``` + +The artifacts under e.g. `30.1234-5/x86_64/` come directly from [coreos-assembler](https://github.com/coreos/coreos-assembler). The `/streams/*.json`, `release.json`, and `releases.json` are higher-level generated metadata objects. See [#98](https://github.com/coreos/fedora-coreos-tracker/issues/98) and [#207](https://github.com/coreos/fedora-coreos-tracker/pull/207) for more information about those. + +The stream metadata format (under `/streams`) is intended to be stable, and stream metadata objects will contain links to artifacts in the release bucket. *Everything else about the bucket layout, including its directory structure and the formats of other metadata objects, is subject to change without notice. Third-party tooling should not rely on this structure, and should instead read metadata and artifact URLs directly from stream metadata at the officially documented URL*. + +## Version numbers + +Originally discussed in [#81](https://github.com/coreos/fedora-coreos-tracker/issues/81) and [#211](https://github.com/coreos/fedora-coreos-tracker/issues/211). + +Fedora CoreOS versions will have the form `X.Y.Z.A`: + +- X is the Fedora major version, e.g. `31`. +- Y is the datestamp that the package set was snapshotted from Fedora, e.g. `20191014`. For mechanical streams, this is the build date. For development and production streams, it's the date of the snapshot that was promoted. +- For official builds, Z is a code number corresponding to the stream: + +Stream | Z version +-- | -- +next | 1 +testing | 2 +stable | 3 +next-devel | 10 +testing-devel | 20 +rawhide | 91 +branched | 92 + +For developer builds (those not produced by the official pipeline), Z is always `dev`. + +These Z codes were chosen to make production versions short and simple, development versions clearly related to production versions, and mechanical versions clearly separated into a distinct group. + +- A is a revision number, which starts at 0 and is incremented for each new build with the same X.Y.Z parameters as an existing build. + +Some examples: + +Stream | Version | Comment +-- | -- | -- +next | 32.20191018.1.0 | F32-based, first release from this snapshot +testing | 31.20191018.2.1 | F31-based, second release from this snapshot +stable | 31.20191001.3.1 | Second stable release from the 20191001 snapshot +next-devel | 31.20191018.10.10 | 11th build of the day +testing-devel | 31.20191018.20.0 | +rawhide | 33.20191018.91.0 | F33-based, first build of the day +branched | 32.20191018.92.0 | +(any developer build) | 31.20191018.dev.2 | Third build of the day + +We are not committing to this version scheme indefinitely, and may change it in future if it proves unworkable. A new Fedora major release (X bump) would be a good time to make such a change. We don't intend Fedora CoreOS version numbers to be parsed by machine; they're meant to help humans quickly determine the salient properties of a release. diff --git a/PRD.txt b/PRD.txt index 7bcce17..a09dd46 100644 --- a/PRD.txt +++ b/PRD.txt @@ -1,4 +1,4 @@ -The source for this document lives at https://github.com/coreos/fedora-coreos-tracker/blob/master/PRD.txt +The source for this document lives at https://github.com/coreos/fedora-coreos-tracker/blob/main/PRD.txt The rendered document lives on the Fedora wiki at https://fedoraproject.org/wiki/CoreOS/PRD @@ -117,7 +117,7 @@ All artifacts will be downloadable from the getfedora.org website. Similarly, fo === Delivery Format === -Artifacts will be delivered as cloud images on Amazon EC2, Azure, DigitalOcean, Google Compute Engine, and Packet; as downloadable images for OpenStack, QEMU, VirtualBox, and VMware; and as ISO images, netboot images, and installable raw images for bare metal systems. We may add other public cloud images and downloadable formats to meet demand or anticipated need. +Artifacts will be delivered as cloud images on Amazon EC2, Azure, DigitalOcean, and Google Compute Engine; as downloadable images for OpenStack, QEMU, VirtualBox, and VMware; and as ISO images, netboot images, and installable raw images for bare metal systems. We may add other public cloud images and downloadable formats to meet demand or anticipated need. === Architectures === diff --git a/README.md b/README.md index 1f0c2ab..decca97 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,3 @@ - Welcome to the Fedora CoreOS issue tracker. This tracker will be used to discuss new features for Fedora CoreOS and also important bugs that are affecting the project. Tickets with the `meeting` label will be @@ -22,66 +21,114 @@ technologies and produce Fedora CoreOS. # Get Fedora CoreOS -Future Link to download page +[Download Fedora CoreOS.](https://getfedora.org/coreos/download/) # Communication channels for Fedora CoreOS -- main mailing list: [coreos@lists.fedoraproject.org](https://lists.fedoraproject.org/archives/list/coreos@lists.fedoraproject.org/) -- status mailing list: [coreos-status@lists.fedoraproject.org](https://lists.fedoraproject.org/archives/list/coreos-status@lists.fedoraproject.org/) (announcements/important messages) -- `#fedora-coreos` on IRC (Freenode) -- forum at [https://discussion.fedoraproject.org/c/coreos](https://discussion.fedoraproject.org/c/server/coreos) -- feature planning and important issue tracking at [github.com/coreos/fedora-coreos-tracker](https://github.com/coreos/fedora-coreos-tracker) -- website at [https://coreos.fedoraproject.org/](https://coreos.fedoraproject.org/) -- Twitter: [@coreos](https://twitter.com/coreos) (specific to CoreOS and containers) and [@fedora](https://twitter.com/fedora) (all Fedora and other relevant news) +- Main mailing list: [coreos@lists.fedoraproject.org](https://lists.fedoraproject.org/archives/list/coreos@lists.fedoraproject.org/) +- Status mailing list: [coreos-status@lists.fedoraproject.org](https://lists.fedoraproject.org/archives/list/coreos-status@lists.fedoraproject.org/) (announcements/important messages) +- Chat room: [`#coreos:fedoraproject.org` on Matrix](https://chat.fedoraproject.org/#/room/#coreos:fedoraproject.org) +- Forum at [https://discussion.fedoraproject.org/tag/coreos-wg](https://discussion.fedoraproject.org/tag/coreos-wg) +- Feature planning and important issue tracking at [github.com/coreos/fedora-coreos-tracker](https://github.com/coreos/fedora-coreos-tracker) +- Website at [https://getfedora.org/coreos/](https://getfedora.org/coreos/) +- Documentation at [https://docs.fedoraproject.org/en-US/fedora-coreos/](https://docs.fedoraproject.org/en-US/fedora-coreos/) +- Twitter: [@fedoracoreos](https://twitter.com/fedoracoreos) + +# Roadmap/Plans + +Fedora CoreOS is available for general use and no longer in preview. We're +continuing to add more platforms and functionality, fix bugs, and write +documentation. Please try out Fedora CoreOS and give us feedback! + +# Adding Packages to Fedora CoreOS + +We often find people asking for a particular package to be added to the base set of +packages included in Fedora CoreOS. One of the goals of Fedora CoreOS is to +remain as lean as possible, without impacting overall usability for our users. +Thus, new package requests are carefully scrutinized to weigh the benefits and +drawbacks of adding an additional package. + +If you would like to propose the inclusion of a new package in the base set of packages, +please file a [new package request](https://github.com/coreos/fedora-coreos-tracker/issues/new/choose). + +# Releases + +See [RELEASES.md](RELEASES.md). # Meetings The Fedora CoreOS Working Group has a weekly meeting. The meeting usually -happens in `#fedora-meeting-1` on irc.freenode.net and the schedule for the -meeting can be found here: https://apps.fedoraproject.org/calendar/CoreOS -Currently, meetings are at `16:30 UTC` on Wednesdays. +happens in +[#meeting-1:fedoraproject.org](https://matrix.to/#/#meeting-1:fedoraproject.org) +on Matrix and the schedule for the meeting can be found here: +https://calendar.fedoraproject.org/CoreOS/ Currently, meetings are at +[`15:30 UTC`](https://time.is/15:30+UTC) on Wednesdays. + +As the +[Matrix bridge to Libera Chat is shutdown](https://matrix.org/blog/2023/11/28/shutting-down-bridge-to-libera-chat/), +you can not attend the meeting from IRC and you have to join using Matrix. ## Steps to run the meeting -- Navigate to `#fedora-meeting-1` on freenode -- Type `#startmeeting fedora_coreos_meeting` -- `#topic roll call` +The fedora meeting host can follow the guide which is curated by the [fcos-meeting-action](https://github.com/coreos/fcos-meeting-action) repo. +Every Wednesday a new checklist will be available in the form of a issue in the fcos-meeting-action repo, which can be used to run the meeting. + +If the action meeting repo is not available for some reason, the host can follow the below steps to run the meeting. + +
+Legacy Meeting steps + +- `cd` to a local checkout of this repo and `git pull` +- Ping [meeting people](https://github.com/coreos/fedora-coreos-tracker/blob/main/meeting-people.txt) in `#fedora-coreos` on libera.chat + - `bash meeting-people.txt` + - copy lines of output and paste into + [`#coreos:fedoraproject.org`](https://chat.fedoraproject.org/#/room/#coreos:fedoraproject.org) + on Matrix +- Navigate to + [`#meeting-1:fedoraproject.org`](https://matrix.to/#/#meeting-1:fedoraproject.org) + on Matrix +- Type: + - `!startmeeting fedora_coreos_meeting` + - `!topic roll call` Wait for 2-4 minutes for people to check in for the roll call. -- `#chair` all the people present for the meeting -- `#topic Action items from last meeting` +- `!topic Action items from last meeting` -Find the last meeting log from -[meetbot](https://meetbot-raw.fedoraproject.org/teams/fedora_coreos_meeting) -and post the action items in the meeting for people to -update the status of. +Find the last meeting log from [meetbot](https://meetbot.fedoraproject.org/) +and post the action items in the meeting for people to update the status of. - After they are done move to each `meeting` ticket from [this tracker](https://github.com/coreos/fedora-coreos-tracker/labels/meeting) Do the following for each ticket -- `#topic` Ticket subject -- `#link` link\_to\_the\_ticket +- `!topic` Ticket subject +- `!link ` During the meeting, you can give people action items for them to complete: -- `#action ` description of what needs to be done +- `!action ` description of what needs to be done -When all the tickets are over, go for Open floor +When all topics are over, go for open floor: -- `#topic` Open Floor +- `!topic Open Floor` After open floor, end the meeting. -- `#endmeeting` +- `!endmeeting` -When convenient, send an email to `coreos@lists.fedoraproject.org` with the -details of the meeting from [meetbot page](https://meetbot.fedoraproject.org/sresults/?group_id=fedora_coreos_meeting&type=team). -Minutes in textual format are directly available using `.txt` as URL extension. +Then, when convenient: + +- Remove `meeting` labels from [tickets that were discussed](https://github.com/coreos/fedora-coreos-tracker/labels/meeting) -The usual format follows: +- Send an email to [coreos@lists.fedoraproject.org](mailto:coreos@lists.fedoraproject.org) with the +details of the meeting from [meetbot page](https://meetbot.fedoraproject.org/). +Minutes in textual format are directly available using `.txt` as URL extension. +It's easiest to get the Minutes/Minutes (text)/Log URLs by copying the +footer that Meetbot prints after `#endmeeting`. You can see examples in the +[archives](https://lists.fedoraproject.org/archives/list/coreos@lists.fedoraproject.org/); +the usual format follows: ``` Subject: Fedora CoreOS Meeting Minutes year-mm-dd @@ -94,8 +141,7 @@ Log: ``` - -You can see examples in the [archives](https://lists.fedoraproject.org/archives/list/coreos@lists.fedoraproject.org/) +
# Voting @@ -130,4 +176,24 @@ Working days: non-holiday weekdays. Relevant holidays are the national holidays # Working Group Members and Points of Contact -TBD +Please see [meeting-people.txt](https://github.com/coreos/fedora-coreos-tracker/blob/main/meeting-people.txt). + +# Metrics + +To view CountME stats you can use a tool called +[sqlitevis](https://sqliteviz.com/) to view the +CountME database and make graphs. This can easily be done with a +single URL but due to [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS) +you have to run your browser in a specific mode to allow the +application to download the database and the inquiries file: + +``` +chromium-browser --disable-web-security --user-data-dir=~/chrome-disable-web-security/ +# OR +google-chrome-stable --disable-web-security --user-data-dir=~/chrome-disable-web-security/ +``` + +Now navigate to +[this](https://sqliteviz.com/app/#/load?data_url=https%3A%2F%2Fdata-analysis.fedoraproject.org%2Fcsv-reports%2Fcountme%2Ftotals-countme.db&data_format=sqlite&inquiry_url=https%3A%2F%2Fraw.githubusercontent.com%2Fcoreos%2Ffedora-coreos-tracker%2Frefs%2Fheads%2Fmain%2Fmetrics%2Ffcos-sqlitevis.json) +URL in the browser and it should autoload the database and the inquiries. This +URL was generated from the [sqlitevis docs](https://sqliteviz.com/docs/sharing/). diff --git a/RELEASES.md b/RELEASES.md new file mode 100644 index 0000000..b04a7bc --- /dev/null +++ b/RELEASES.md @@ -0,0 +1,36 @@ +# Fedora CoreOS Releases + +FCOS releases normally happen every 2 weeks. In addition, +there may be asynchronous releases for e.g. CVEs or bug +fixes. + +For more details, see +[the design doc](Design.md#release-streams). + +## Streams + +There are 3 primary streams: `stable`, `testing`, and +`next`. The `next` stream either tracks `testing` or the +next major version of Fedora. Content in `testing` is +promoted to `stable` after 2 weeks. + +For more details, see +[the design doc](Design.md#release-streams). + +## Versioning + +FCOS versions are of the form `X.Y.Z.A`, where `X` is the +Fedora major version, `Y` is the date of the Fedora RPM +snapshot, `Z` is a stream identifier, and `A` is a revision +number. + +Since `stable` releases are promoted from `testing`, their +`Y` dates will usually be 2 weeks behind `testing`. + +For more details, see +[the design doc](Design.md#version-numbers). + +## Schedule + +The release schedule and release owners are tracked in a +[HackMD document](https://hackmd.io/WCA8XqAoRvafnja01JG_YA). diff --git a/docs/20210204_fcos_official_edition.md b/docs/20210204_fcos_official_edition.md new file mode 100644 index 0000000..164c423 --- /dev/null +++ b/docs/20210204_fcos_official_edition.md @@ -0,0 +1,64 @@ +# Fedora CoreOS Meetup - Fedora CoreOS as an Official Edition + +recording : https://www.youtube.com/watch?v=t5VAw8NRXNc + +Fedora Change : https://fedoraproject.org/wiki/Changes/FedoraCoreOS + +Key concepts : +* There is no Fedora CoreOS 33 or 34, I don't think we want to align with the 6 months release cadence of other Fedora Editions. +* How can we integrate within Fedora's process, keeping our fortnigthly release cycle. + + +General Feedback was how do we integrate with the Fedora process + +Fedora's [Edition promotion policy](https://docs.fedoraproject.org/en-US/council/policy/edition-promotion-policy/) +* Development and how we integrate with Fedora's change proposal process ? (Review, Propose Changes) +* Go/No Go process ? Release Blockers +* Release Criteria ? +* When do we switch streams to the latest Fedora base (F33 -> F34, etc...)? +* How do we coordinate with other teams + * Docs + * Marketing + * Translation + * Magazine + * Web +* How much effort do we want to put into making FCOS an edition ? What are the benefits ? +* Have you asked anyone who has gone through this process if it was useful to them? + +## Notes + +- [miabbott/cverna] Short introduction +- [mattdm] how does "we don't have releases" work with the release blocker process? +- [bgilbert] we ship the stable stream later than major Fedora releases for this reason; may not be desirable in all cases. if there is a blocker that only affects FCOS, we may not want to hold the other releases. +- [mattdm] publicity is a factor of concern here +- [bcotton] user perspective on release day is problematic; "why am i getting older Fedora bits?" +- [walters] we think we can address all these concerns over time. i.e. ubuntu has similar issues with software upater/apt - https://www.reddit.com/r/Ubuntu/comments/aofv57/software_updater_lags_behind_apt/ +- [sumantro] Blocker Bugs for Fedora tracked in BZ; FCOS tracks issues in GH +- [bgilbert] FCOS is an appliance, uses automatic updates. Breaking updates incentivizes users to turn off auto-updates. Streams exist towards this goal. +- [mattdm] automatic updates are a selling point; we should use it to our advantage +- [travier/bcotton/mattdm] +- [jligon] e.g. If I want to remove Docker from FCOS, do I submit a change to FCOS only, Fedora proper, somewhere on GH? +- [mattdm] feels like a self-contained change; would be discussed by stakeholders and publicized appropriately (picked up by LWN, Phoronix, etc) +- [mattdm] FCOS changes being part of existing Fedora change process is desirable +- [walters] bootupd should have been a change request; but sometimes we need to ship something downstream faster than Fedora allows +- [bgilbert] prefer not stacking big changes around major release; easier for change management +- [bcotton] window between self-contained change proposal and GA is only 3months +- [cglombek] there are still usecases where Fedora Server is better suited (firewall, RPM modules, etc) +- [mattdm] FCOS will likely sit alongside Fedora Server for a while +- [walters] I don't think it's a good idea overall to chain FCOS Edition status into Server's edition status +- [mattdm] should develop an async process for ??? +- [cverna] promoting between streams is gated on testing; what does the formalized process look like +- [cglombek] https://github.com/coreos/enhancements that are going to affect the rest of Fedora, we should "upstream" those enhancements to proper Fedora Change Requests. conversely, Fedora Chagne Requests that affect FCOS should get better review by FCOS +- [walters] we could use an arbitrary component in BZ to capture problems for FCOS +- [dmabe] there is an FCOS component, but it directs folks to use GH issue tracker +- [sumantro] get some basic criteria around stream promotion; can't catch everything in CI; https://fedoraproject.org/wiki/Fedora_Release_Criteria +- [walters] A good example of not-CI currently for us is multi-arch +- [bgilbert] our decision process so far has been case-by-case and consensus-driven +- [jlebon] we should be doing more talking/communication on Fedora devel around change requests that affect FCOS +- [jligon] is there a tradeoff where becoming an official top-level edition where some decision making is surrendered? +- [bcotton] there is some latitude for editions for change proposals; there is marketing/UX benefits to be closer to the rest of Fedora. tl;dr - case by case basis +- [travier] our release criteria exists in CI; we do evaluate each update that we ship is safe to use. when issues are found, we have more options to prevent those issues from being released (i.e downgrades, pinned packages, etc) +- [bgilbert] we snapshot bodhi stable that gets promoted into the testing stream; pkgs are not pinned for an extended amount of time. we do more post-processing than most of Fedora. +- [mattdm] it would be beneficial to check in with mindshare team regularly +- **[sumantro] would like to volunteer to be mindshare rep for FCOS** + diff --git a/docs/20210204_growing_fcos_community.md b/docs/20210204_growing_fcos_community.md new file mode 100644 index 0000000..4955ff3 --- /dev/null +++ b/docs/20210204_growing_fcos_community.md @@ -0,0 +1,78 @@ +# 20210204_Growing-FCOS-Community + +recording: https://www.youtube.com/watch?v=HSuBWeosAvQ + +- Execution + - Stability: we might lose users if we have instability and "manual intervention" + - Availability in more cloud providers + +- Freely available information/resources + - Publishing release notes + - https://github.com/coreos/fedora-coreos-tracker/issues/194 + - More comprehensive documentation + +- Outreach + - Community event coordination + - especially at conferences we don’t normally have representation + - but also making sure we are present at our regular conferences + - Working with more upstream projects that integrate Fedora CoreOS + - Typhoon has picked us up on their own + - Have others tried and had trouble? + - GSoC/Outreachy FCOS projects + +- Staying in the conversation + - More articles/posts about Fedora CoreOS + - Fedora Magazine, opensource.com, personal blogs, etc + - Podcasts, etc.. + - Boosting our Twitter presence + +- Indirect Progress + - Promoting containerized workflows + - Helping to containerize the world + - If it's not easy to run XYZ workflow in containers people can't use FCOS + +## Running Notes + +Recurring Fedora Events: +- Nest with Fedora/Flock to Fedora +- Release Parties (2 per year) +- Fedora Women's Day +- Video Council Meetings +- Social Hours + +Fedora Content outlets: +- Community Blog: https://communityblog.fedoraproject.org/writing-community-blog-article/ +- Fedora Magazine: https://docs.fedoraproject.org/en-US/fedora-magazine/contributing/ +- Fedora Planet: http://fedoraplanet.org/ +- Podcast: https://x3mboy.fedorapeople.org/podcast/ +- Fedora Classroom: https://fedoraproject.org/wiki/Classroom +- Fedora Youtube: https://www.youtube.com/channel/UCnIfca4LPFVn8-FjpPVc1ow + + +Fedora Resources: +- Request swag: https://docs.fedoraproject.org/en-US/mindshare-committee/procedures/swag/ +- HopIn is accessible to Fedora. A formal process is currently being documented by Mindshare. You can request this resource here: https://pagure.io/mindshare/issues +- Community surveys are accessible to Fedora. There is a drop down template in the Mindshare repo for this request. https://pagure.io/mindshare/issues +- IRL Events (someday): https://docs.fedoraproject.org/en-US/mindshare-committee/small-events/ +- Design requests: https://pagure.io/design/issues +- Fedora Badges: https://badges.fedoraproject.org/ + - https://pagure.io/fedora-badges/issues +- How Do You Fedora? interviews: https://fedoramagazine.org/series/how-do-you-fedora/ + + + +[cverna] What is our messaging to other conferences? +[jbrooks] We can produce a slide deck that can be reused/customized for talks/presentation +[walters] Fedora very RPM-centric; would love to push us towards more pure containers +[travier] tried to run Fedora images for containerizing Matrix and hit issues; having trusted container images outside Dockerhub would be great +[cglombek] not producing enough Fedora containers; maintaining containers in Fedora has high requirements (i.e. must be packagers). also facing problem of where to publish community operators in OKD space. +[jbrooks/dmabe] identified a problem that we don't have the applications people want in our sphere of control (i.e don't have trusted containers for all apps). how can we improve the Fedora container story? +[cverna] need to have a better idea of who we are targeting with our content +[mperez] have connections with linux unplugged, can get FCOS discussed there; interested in producing more video content for communities (i.e. https://ceph.io/community/meetings/). working on templates for hosting this style of content. +[mnordin] FCOS has access to all the Fedora community tools above; willing to help move tickets along in various community resources +[sumantro] Fedora Classrooms would be a good outreach point +[sumantro] Adding FCOS to https://whatcanidoforfedora.org/ will be great. +[vipul] A bit different thing: opening a few GSoC/Outreachy projects can also bring a lot of eyes on the project. They are often not the best but it can help and also identify close all gaps in "How can I get started with FCOS" documentation +[dmabe/mperez] measuring stats for MLs, forums, GH tracker may be informative +[mnordin] would recommend starting with a user survey to gather a baseline from where to start from +[mperez] example survey - https://tracker.ceph.com/attachments/download/5323/Ceph%20User%20Survey%202020%20(3).pdf diff --git a/docs/ci-and-builds.md b/docs/ci-and-builds.md new file mode 100644 index 0000000..aeffbf0 --- /dev/null +++ b/docs/ci-and-builds.md @@ -0,0 +1,65 @@ +# CoreOS CI+build systems overview + +Fedora CoreOS is tied/related to 3 major things: + + - Upstream git repositores like github.com/coreos/ignition, github.com/coreos/rpm-ostree, github.com/coreos/fedora-coreos-config, etc. + - Actual releases of Fedora CoreOS via [the pipeline](https://github.com/coreos/fedora-coreos-pipeline) + - Downstream [RHEL CoreOS](https://github.com/openshift/os) + +## Infrastructure + +- Github (specifically [the coreos namespace](https://github.com/coreos/)) +- [quay.io](https://quay.io), specifically the [coreos-assembler](https://quay.io/coreos/coreos-assembler) namespace +- [CoreOS CI Jenkins](https://github.com/coreos/coreos-ci) +- [Fedora infrastructure](https://fedoraproject.org/wiki/Infrastructure) +- [OpenShift Prow](https://docs.ci.openshift.org/) + +--- + +## Upstream CI + +Most active repositories in the `coreos/` project are hooked up to at least one of 3 CI systems, being CoreOS CI Jenkins, Github Actions, or OpenShift Prow. These 3 are the ones we are focusing on. + +### CoreOS CI Jenkins + +It is what we use on various repositories, and is how FCOS is released today via [the pipeline](https://github.com/coreos/fedora-coreos-pipeline). +We have a lot of institutional knowledge around this and it gives us a place where we can easily control the end-to-end interactions. Jenkins is a well understood tool. + +This is deployed in [CentOS CI](https://wiki.centos.org/QaWiki/CI) which is a bare metal OpenShift cluster where nested virt is enabled. + +Also of key relevance is the [coreos-ci-lib](https://github.com/coreos/coreos-ci-lib) repository. + +### OpenShift Prow + +Prow is heavily oriented towards testing OpenShift *container* components. However, as of recently we enabled nested virt on the `build02` GCP cluster, which means we can create "container native" flows that still test the OS with [coreos-assembler](https://github.com/coreos/coreos-assembler/). + +A specific reason to include Prow is that it contains tight integration with OpenShift which we need for RHCOS, and it is also maintained and staffed by a team that e.g. also contains a budget and secrets for running infrastructure in public clouds. + +Examples can be found in the [openshift/release coreos/ folder](https://github.com/openshift/release/tree/main/ci-operator/config/coreos). + +### GitHub Actions + +Free for small scale, nice to use. This is a good option for per-repository specific things that don't need centralization. + +A good use case is e.g. validating rustfmt. + +Examples: + + - https://github.com/coreos/rpm-ostree/blob/main/.github/workflows/rust-lints.yml + +--- + +## quay.io/coreos-assembler namespace + +A key aspect of Fedora CoreOS as well as RHEL CoreOS is [coreos-assembler](https://github.com/coreos/coreos-assembler). As of today, we build it in quay.io and deliver it that way in the `quay.io/coreos-assembler` namespace. The list of administrators for this namespace is managed independently of anything else. If you think you need administrator access, file a ticket or ask on [`#coreos:fedoraproject.org` on Matrix](https://chat.fedoraproject.org/#/room/#coreos:fedoraproject.org). + +### The buildroot container: quay.io/coreos-assembler/fcos-buildroot:testing-devel + +Since [this pull request](https://github.com/coreos/fedora-coreos-config/pull/740), there is also a FCOS-oriented "buildroot" container that can be used in all CI systems. + +## Fedora Infrastructure + +Maintained by a distinct team. FCOS and our container images include most content derived from Koji/Bodhi etc. + +It would potentially make sense to have some of our containers built in Fedora too, such as coreos-assembler. That would give us e.g. multi-arch. But that is not being pursued currently. + diff --git a/docs/fedora-coreos-kernel-bisect.md b/docs/fedora-coreos-kernel-bisect.md new file mode 100644 index 0000000..0742cfc --- /dev/null +++ b/docs/fedora-coreos-kernel-bisect.md @@ -0,0 +1,229 @@ + +# Kernel regressions need bisecting + +Sometimes we encounter kernel regressions and it is valuable to +identify the exact commit where a regression was introduced. An example +of this would be +[this issue for nodes booting in AWS](https://github.com/coreos/fedora-coreos-tracker/issues/1066#issuecomment-1019560658). + +There are various strategies for how to determine the exact kernel +commit where a regression was introduced. Which strategy is most +efficient depends on the problem. Here they are: + +1. directly building and installing the kernel from kernel source git repo +2. directly building and creating an RPM from the kernel source git repo + +For `1.`, it only works if you can reproduce the problem on the +traditional `yum`/`dnf` based Fedora (like Fedora Cloud). If, however, +the problem only presents itself on Fedora CoreOS or is much easier to +reproduce on Fedora CoreOS (i.e. a `kola` test) then you'll want to +build the `rpm` (`2.`) and consume it that way. + +## Kernel Source git Repos + +There are a few kernel source git repositories to know about: + +- `git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git` + - Where the latest upstream development happens +- `git://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/` + - Where stable/LTS tags are handled (backports to stable branches happen here) +- `https://gitlab.com/cki-project/kernel-ark.git` + - The `kernel-ark` repo where Red Hat patches/branches are maintained + +The `kernel-ark` repo contains various branches used for feeding into +the [Fedora dist-git repo](https://src.fedoraproject.org/rpms/kernel). +Here's a summary of what those branches are used for: + + +- `os-build` + - The latest bits that track the under development yet to be release kernel. +- `fedora-6.3` + - Follows a particular released kernel stream. This is where things are + merged before they are fed into dist-git. If you want a commit reverted + this is where it will land first. +- `ark-infa` + - This branch contains all the Red Hat bits and nothing else. It can be merged + on top of any other branch and then a SRPM can be created (`make dist-srpm`) + for building using `rpmbuild --rebuild /path/to/srpm`. + +## Creating a Kernel Build Environment + +If running the kernel builds on a Fedora Cloud base machine where you +can install the kernel directly then you can set up the kernel build +environment directly in the VM. If not you'll probably want to use a +container for your kernel builds. Here's how to start up a container: + +``` +podman run -it --name=kbuild -v /path/to/kernel/git/:/path/to/kernel/git/ registry.fedoraproject.org/fedora:38 +``` + +NOTE: try to use the same Fedora Cloud or Fedora container version as + the version of Fedora you are targetting. + +Once inside the VM or container we need to install some software to build the kernel: + +``` +sudo dnf update -y && \ +sudo dnf install -y make rpm-build rsync 'dnf-command(builddep)' && \ +sudo dnf builddep -y kernel +# reboot here if in a VM +``` + +We can now make changes to the git repo (revert commits, etc) and run a few +commands to build the kernel. Before building we need to copy down the config +from the kernel dist-git repo and disable making a DEBUG kernel if it was enabled, +which makes very large files: + +``` +cd /path/to/kernel/git/ +RELEASE=f38 # or RELEASE=rawhide +curl "https://src.fedoraproject.org/rpms/kernel/raw/${RELEASE}/f/kernel-x86_64-fedora.config" > .config.fedora +cp .config.fedora .config +sed -i 's/CONFIG_DEBUG_KERNEL=y/CONFIG_DEBUG_KERNEL=n/' .config +``` + +## 1. Directly Building and Installing the Kernel from Kernel Source git repo + +To build and install the kernel directly on the system (i.e. on Fedora Cloud Base) +you can run the following: + +``` +# Set make target. See https://src.fedoraproject.org/rpms/kernel/blob/rawhide/f/kernel.spec +make_target=bzImage # for x86_64 or vmlinux(ppc64le) or vmlinuz.efi(aarch64) +make olddefconfig +make -j$(nproc) $make_target +make -j$(nproc) modules +sudo make modules_install +sudo make install +``` + +On a Fedora Cloud base system the /boot partition is low on extra +space. In order to iterate (i.e. when running a `git bisect`) you can +restore the system back to it's old state before continuing. First, +modify the Makefile and set `EXTRAVERSION = bisect` and also +take a backup of the grub config: + +``` +sudo cp /boot/grub2/grub.cfg /boot/grub2/grub.cfg.bak +``` + +Then run the following script to build and install the kernel: + +``` +cat build.sh +#!/bin/bash +set -eux -o pipefail +cp .config.fedora .config +sed -i 's/CONFIG_DEBUG_KERNEL=y/CONFIG_DEBUG_KERNEL=n/' .config +# Set make target. See https://src.fedoraproject.org/rpms/kernel/blob/rawhide/f/kernel.spec +make_target=bzImage # for x86_64 or vmlinux(ppc64le) or vmlinuz.efi(aarch64) +make olddefconfig +make -j$(nproc) $make_target +make -j$(nproc) modules +sudo make modules_install +sudo make install +``` + +After testing and before running the next build I would restore and +free space with this clean script: + +``` +cat clean.sh +#!/bin/bash +set -eux -o pipefail +sudo cp /boot/grub2/grub.cfg.bak /boot/grub2/grub.cfg +sudo rm -vf /boot/initramfs*bisect* /boot/vmlinuz-*bisect* /boot/System.map-*bisect* +sudo rm -rf /lib/modules/*bisect* +``` + +Then you can automate with: + +``` +bash clean.sh && bash build.sh +``` + +## 2. Directly Building and Creating an RPM from the Kernel Source git repo + +In this scenario we're creating an RPM that can either then be package +layered on an existing FCOS system or used as input to a `cosa build`. + +The commands here are: + +``` +make olddefconfig +make -j$(nproc) binrpm-pkg +``` + +### Package Layering the Kernel RPM + +After copying the built kernel to the target machine you can install it with an override. +Example: + +``` +sudo rpm-ostree override replace ./kernel-5.17.0_rc8-1.x86_64.rpm --remove=kernel-core --remove=kernel-modules +``` + +### Doing a Build with COSA + +Then copy the built RPM into the `overrides/rpm` folder under the COSA build directory. +After that you should be able to `cosa fetch --with-cosa-overrides && cosa build` like normal. + +While iterating you should be able to skip the `cosa fetch` step. Just delete the old +RPM out of `overrides/rpm`, put the new one in place and then `cosa build`. + + +## Performing a Kernel Bisect + +Now that we know how to build and use a kernel in various ways the bisect is +the easy part. Just follow the +[upstream kernel documentation](https://www.kernel.org/doc/html/latest/admin-guide/bug-bisect.html) +for doing a `git bisect` and repeat the build/test steps in between each step. + +## Reporting issues upstream + +Unfortunately the kernel doesn't have any git forge structure. It's +mostly email and mailing lists. If you want to report an issue +upstream you can run a command to give you what people/lists to email: + +``` +commit=abcdef +git format-patch --stdout "${commit}^..${commit}" | \ + ./scripts/get_maintainer.pl --norolestats +``` + +example: + +``` +$ commit=a09b314 +$ git format-patch --stdout "${commit}^..${commit}" | ./scripts/get_maintainer.pl --norolestats +Jens Axboe +linux-block@vger.kernel.org +linux-kernel@vger.kernel.org +``` + +## Testing out fixes with Fedora's kernel + +Once you have a proposed fix/patch you can easily build a Fedora kernel RPM by +adding your patch to the [`linux-kernel-test.patch` file](https://docs.fedoraproject.org/en-US/quick-docs/kernel/testing-patches/#_applying_the_patch) +in the [kernel distgit repo](https://src.fedoraproject.org/rpms/kernel). + +After adding your patch you can then use `fedpkg` to build a new +kernel for your target architecture. For example: + +``` +fedpkg scratch-build --srpm --arch=x86_64 +``` + +Once the build is complete you can grab the RPMs using the `koji` CLI: + +``` +koji download-task +``` + +Placing these RPMs into the `overrides/rpm` directory and do a new COSA build +will give you a CoreOS build with the patched kernel. + +After the tested patch looks good you can then open a PR to the `fedora-X.Y` +branch in the `kernel-ark` repo. See the above +[Kernel Source git Repos](#kernel-source-git-repos) +section for more details. diff --git a/docs/fedora-coreos-systemd-bisect.md b/docs/fedora-coreos-systemd-bisect.md new file mode 100644 index 0000000..673804a --- /dev/null +++ b/docs/fedora-coreos-systemd-bisect.md @@ -0,0 +1,66 @@ + +# Systemd regressions need bisecting + +Similar to the kernel, systemd is often a core component of our +stack that has regressions that aren't easy to identify just by +inspecting a changelog. + +## Systemd Source git Repos + +There are a few kernel source git repositories to know about: + +- `https://github.com/systemd/systemd.git` + - Where the latest upstream development happens +- `https://github.com/systemd/systemd-stable.git` + - Where stable/LTS tags are handled (backports to stable branches happen here) + +There is also the [Fedora dist-git repo](https://src.fedoraproject.org/rpms/systemd). + +## Creating a Kernel Build Environment + +You can use a container to build systemd from upstream. + +``` +SHARED=/path/to/shared/directory/ +RELEASE=38 +podman run -it --name=systemdbuild -v "${SHARED}:${SHARED}" "registry.fedoraproject.org/fedora:${RELEASE}" +``` + +``` +sudo dnf update -y && \ +sudo dnf install -y make rpm-build rsync 'dnf-command(builddep)' && \ +sudo dnf builddep -y systemd +``` + +We can now make changes to the git repo (revert commits, etc) and run a few +commands to build systemd. If doing a +[`git` bisect](https://www.kernel.org/doc/html/latest/admin-guide/bug-bisect.html) +run the commands needed to start the bisect. + +## Doing the systemd build/test + +To build systemd you can run the following commands. These commands +were adapted from the notes in the +[Systemd README](https://github.com/systemd/systemd/blob/579fbe5b789cbee10546f6274c39be311e71e49c/README#L233-L247). + + +``` +meson setup build/ +``` + +And then the following can be iterated upon for each commit to test: + +``` +export DESTDIR=/path/to/shared/directory/fcos/overrides/rootfs/ +ninja -C build && ninja -C build install +``` + +NOTE: If you run into `permission denied` errors when copying the files around check for SELinux denails. + +Now you can run COSA to build/test. From the COSA directory: + +``` +cosa build && cosa kola run mytest +``` + +Now you can iterate until you find the problematic commit. diff --git a/docs/testing-project-documentation-changes.md b/docs/testing-project-documentation-changes.md new file mode 100644 index 0000000..946b0ae --- /dev/null +++ b/docs/testing-project-documentation-changes.md @@ -0,0 +1,52 @@ +# Testing changes for GitHub Pages hosted project documentation + +The first option makes it easy to link to rendered changes for code review but +is slower for rapid changes or iteration where the second option is faster. + +## Option 1: Deploying to your own GitHub Pages sub domain + +- Replace `coreos` with your GitHub username in `docs/_config.yml` on top of + your other changes: + ``` + docs/_config.yml | 2 +- + 1 file changed, 1 insertion(+), 1 deletion(-) + + diff --git a/docs/_config.yml b/docs/_config.yml + index 3ab720a0..801cbb9d 100644 + --- a/docs/_config.yml + +++ b/docs/_config.yml + @@ -1,7 +1,7 @@ + title: coreos/coreos-installer + description: CoreOS Installer documentation + baseurl: "/coreos-installer" + -url: "https://coreos.github.io" + +url: "https://your_github_username.github.io" + # Comment above and use below for local development + # url: "http://localhost:4000" + permalink: /:title/ + ``` +- Push the full changes to the main branch of your GitHub repo fork +- Enable GitHub Pages for the main branch, using `/` as root +- Wait for approximately 1 min for the changes to be deployed +- Access the rendered pages under your username as domain: + + +## Option 2: Local testing + +- In `docs/_config.yml`, replace the line + ``` + url: "https://coreos.github.io" + ``` + by + ``` + url: "http://localhost:4000" + ``` +- Use the following commands to install the Ruby gems and start a local + development server: + ``` + export JEKYLL_ENV="production" + bundle install --path=./vendor/gems/ + bundle exec jekyll serve --livereload --strict_front_matter + ``` +- Access the documentaion by pointing your browser to + diff --git a/internals/README-initramfs.md b/internals/README-initramfs.md new file mode 100644 index 0000000..962763b --- /dev/null +++ b/internals/README-initramfs.md @@ -0,0 +1,91 @@ +# The initramfs + +For CoreOS the initramfs is critical; a key technological pillar of CoreOS is [Ignition](https://github.com/coreos/ignition/) which e.g. handles partitioning disks that happen on the first boot. One way to think about this is that Ignition handles a lot of the roles that a traditional "installer" program might - our initramfs contains `sgdisk`, most others don't. + +# Initramfs history + +See the upstream Linux kernel document: ["what is initramfs"](https://www.kernel.org/doc/html/latest/filesystems/ramfs-rootfs-initramfs.html?highlight=initramfs#what-is-initramfs). + +It's basically a small filesystem that gets passed to the kernel by the bootloader, and the kernel unpacks and runs it. + +The high level goal of the initramfs is to mount the root filesystem (conventionally at `/sysroot`) and switch root into it, i.e. turning `/sysroot` into `/`. + +# Initramfs technologies + +We use [dracut](https://github.com/dracutdevs/dracut/) the same as a number of other (but not all) distributions. It basically gathers binaries/configuration from the real root and generates an initramfs from them. + +Modern systemd has a very clean design for both the initramfs and the real boot. See the ["man bootup"](https://www.freedesktop.org/software/systemd/man/bootup.html) documentation. The software involved implements these abstract `.target` units. + +There are 3 important pieces of software involved in the initramfs: +- [30ignition](https://github.com/coreos/ignition/tree/main/dracut/30ignition) (Part of Ignition) +- [ostree-prepare-root](https://github.com/ostreedev/ostree/blob/main/src/switchroot/ostree-prepare-root.c) (Part of OSTree) +- [40ignition-ostree dracut module](https://github.com/coreos/fedora-coreos-config/tree/testing-devel/overlay.d/05core/usr/lib/dracut/modules.d/40ignition-ostree) (fedora-coreos-config) + +Note that Ignition and OSTree are both independent projects consumed by other distributions in addition to Fedora CoreOS. This means that we want to support using each independently. The `40ignition-ostree` dracut module *ties those two together* - it's the place where you will find systemd units that have direct ordering relationship around the two projects. + +# First boot versus subsequent boot + +Ignition runs only on the first boot. To account for this, ignition-dracut ships two targets: + +`ignition-complete.target`: Enabled on first boot +`ignition-subsequent.target`: Enabled on every boot **except** the first + +`-complete` will pull in a lot of units, such as `ignition-fetch.service` and `ignition-disks.service` + +We implement`ignition-subsequent.target` today by hooking in `ignition-ostree-mount-subsequent-sysroot.service` which basically just waits for a filesystem with `LABEL=root` and mounts it - very simple! But see below around the root filesystem. + +# Images and finding filesystems + +An important part of the CoreOS philosophy is to make bare metal as close to cloud workflows as possible. This follows from moving all support for e.g. filesystem provisioning into Ignition. + +[coreos-assembler](https://github.com/coreos/coreos-assembler) generates a disk image with `boot` (`/boot`) and `root` (`/`) labels. Various components of the initramfs (as well as our default GRUB config) use the `label=boot` to find the boot partition. The label `root` is used by `ignition-ostree-mount-firstboot-sysroot.service`. + +# Live versus diskful + +We also ship a "Live" ISO/PXE image which uses a different filesystem (squashfs). This caused us to introduce a separate `ignition-diskful.target` which only runs on cases where we're booted from writable persistent storage (i.e. not ISO/PXE). + +To implement the "live" or "run in RAM" aspects, the `live-generator` sets up an `overlayfs` for `/etc` and a `tmpfs` for `/var`. Everything else is part of the `squashfs` which is read-only. + +The Live OS setup differs currently between the ISO and PXE: https://github.com/coreos/fedora-coreos-tracker/issues/390 + +Currently when generating the ISO image we inject a label onto the root filesystem, and a `coreos.liveiso` kernel argument matching it. The initramfs knows to look for that kernel argument, which it then uses to mount the squashfs which contains the root filesystem. + +In contrast for PXE the squashfs is in the `live-initramfs` directly. + +# /boot in the initramfs + +There are multiple services which access the `/boot` partition in the initramfs. They are (in running order): +- `coreos-ignition-setup-user.service`: mounts `/boot` read-only to look for a user Ignition config. This is the first Ignition-related service to run. +- `coreos-copy-firstboot-network.service`: mounts `/boot` read-only to look for NetworkManager keyfiles. This unit runs after Ignition's `ignition-fetch-offline.service` but before networking is optionally brought up as part of `dracut-initqueue.service`. +- (on RHCOS) `rhcos-fips.service`: mounts `/boot` read-write to append `fips=1` to the BLS configs and reboot if FIPS mode is requested. This unit runs after `ignition-fetch.service` but before `ignition-disks.service`. +- `coreos-boot-edit.service`: mounts `/boot` read-write late in the initramfs process after `ignition-files.service` to make final edits (e.g. remove firstboot networking configuration files if necessary, append rootmap kargs to the BLS configs). + +# Multipath handling + +Currently, the way multipath is supported is to add `rd.multipath=default` and `root=/dev/disk/by-label/dm-mpath-root` to the kernel command-line. They can be added day-1 or day-2, but the former is recommended. These kargs play different roles. The `root` karg ensures that systemd-fstab-generator will wait until multipathd has assembled the device and the symlink shows up (rather than trying to mount a single path). The `rd.multipath=default` karg will cause [the multipath dracut module to generate a default configuration](https://github.com/dracutdevs/dracut/blob/ab798f6785513c33f9a71371ceea65bd782973d5/modules.d/90multipath/multipathd-configure.service#L10) that `multipathd` will then act on. + +Crucially, `rd.multipath` on first boot also makes us assume that the `boot` filesystem is multipathed and wait for `/dev/disk/by-label/dm-mpath-boot` to show up. As seen in the previous section, many things need access to the bootfs on first boot. But we can't do any I/O to the boot device if it's multipathed because it's undefined which of the single paths will win the `by-label/boot` race, and it may be a path that is non-optimized (see [this PR](https://github.com/coreos/fedora-coreos-config/pull/1011) and linked RHBZ for details). Instead of trying to automatically determine if the bootfs is on multipath and whether we should wait for `multipathd` to assemble it (which is subject to race conditions), we decide on whether `rd.multipath` is provided (see also [this discussion](https://github.com/coreos/fedora-coreos-config/pull/1022#discussion_r634631063)). + +The `dm-mpath-$label` symlinks are created by [a udev rule we ship](https://github.com/coreos/fedora-coreos-config/blob/8fc657ebb9617a1ab9f1b513123d19ea7775ac68/overlay.d/05core/usr/lib/udev/rules.d/90-coreos-device-mapper.rules#L24). + +# SELinux in the initramfs + +SELinux policy is loaded in the real root. This means that every file we create in the initramfs must be relabeled. See this code: https://github.com/coreos/fedora-coreos-config/blob/testing-devel/overlay.d/05core/usr/lib/dracut/modules.d/40ignition-ostree/coreos-relabel + +# Networking + +By default, the initramfs does not try to enable networking if it's not needed. This is important in the live ISO case. Software may request networking if they require it. For example, if Ignition detects a config which requires the network, it writes a stamp file at `/run/ignition/neednet` which we then detect and translate into `rd.neednet=1` via `coreos-enable-network.service`. For any other situation in which FCOS needs networking, we should add a triggering condition to that service. In the future if more cases are added, we may provide a cleaner API which does not require continuously expanding this list. + +Network *enablement* is separate from network *configuration*. Afterburn handles rendering of network kernel arguments via [`afterburn-network-kargs.service`](https://github.com/coreos/afterburn/blob/e0c46db33ece0e003d278be73f2c83e237b315d0/dracut/30afterburn/afterburn-network-kargs.service). On some platforms, it may use a backchannel to fetch the network kargs. By default, it will use `AFTERBURN_NETWORK_KARGS_DEFAULT`, which is defined in [the fedora-coreos-config repo](https://github.com/coreos/fedora-coreos-config/blob/82f22f92620b60b009e94872a7b44fade8e782e1/overlay.d/05core/usr/lib/dracut/modules.d/35coreos-network/50-afterburn-network-kargs-default.conf) to be `ip=auto`. + +For more details of the design, see https://github.com/coreos/fedora-coreos-tracker/issues/460 as well as the project [documentation](https://docs.fedoraproject.org/en-US/fedora-coreos/sysconfig-network-configuration/). + +# Reprovisioning the root + +A big recent effort is [reprovisioning the root filesystem](https://github.com/coreos/fedora-coreos-tracker/issues/94). This will make the "subsequent" boot path work differently based on configuration. + +# Debugging the initramfs + +- https://fedoraproject.org/wiki/How_to_debug_Dracut_problems is generally useful +- Use `cosa buildinitramfs-fast` for fast iteration: https://github.com/coreos/coreos-assembler/pull/1433 +- ignition-dracut contains code to dump the journal to a virtio channel: https://github.com/coreos/ignition-dracut/pull/146 - This is used by parts of coreos-assembler diff --git a/internals/README-internals.md b/internals/README-internals.md new file mode 100644 index 0000000..05fe7ee --- /dev/null +++ b/internals/README-internals.md @@ -0,0 +1,125 @@ +# CoreOS Internals docs + +This document intends to be a dumping ground to briefly describe various problem domains we've hit around building/delivering/testing CoreOS style systems. + +Other important links: + + - https://github.com/coreos/coreos-assembler/ + - https://github.com/coreos/fedora-coreos-config + +# Initramfs + +This topic is big enough to have its own document: [README-initramfs.md](README-initramfs.md). + +# CPU microcode + +rpm-ostree runs dracut on the server side, and dracut knows how to pick up CPU microcode and prepend it to the initramfs. Relevant bugs: + +- https://bugzilla.redhat.com/show_bug.cgi?id=1199582 +- https://bugzilla.redhat.com/show_bug.cgi?id=1803883 + +# Entropy + +As of recently we enable `CONFIG_RANDOM_TRUST_CPU` which covers modern `x86_64` systems for example. + +- https://bugzilla.redhat.com/show_bug.cgi?id=1830280 +- https://github.com/openshift/machine-config-operator/issues/854 + +# Networking + +In [this tracker issue](https://github.com/coreos/fedora-coreos-tracker/issues/24) a decision was made to use NetworkManager. As of recently we use NetworkManager in the initramfs. And even more recently, things have been reworked so that [afterburn can control initramfs networking](https://github.com/coreos/afterburn/pull/404) on specific clouds. + +# Time synchronization + +We use chrony, with some [additional custom logic for specific clouds](https://github.com/coreos/fedora-coreos-config/blob/faf387eac89d14924a1e2021d2093d0cdb8af8b3/overlay.d/20platform-chrony/usr/lib/systemd/system-generators/coreos-platform-chrony). +See also DHCP propagation: https://github.com/coreos/fedora-coreos-config/pull/412 + +# Aleph version + +`rpm-ostree status` will show admins the state of the ostree, but a few things live outside that and are not subject to in place updates. For example, the on-disk filesystem (default `xfs`) and its specific layout, as well as the bootloader. + +See [this pull request](https://github.com/coreos/coreos-assembler/pull/768/commits/2701e91838e18d3eac0694fd0a5f003befcfb218) which added `/sysroot/.coreos-aleph-version.json` that can be used to track the version of that data. + +# ignition.platform.id + +See https://docs.fedoraproject.org/en-US/fedora-coreos/platforms/ + +The design we have today is that each CoreOS system is the same OS content - the same OSTree commit, +and beyond that the exact same bootloader version, etc. + +There are differences per platform on the image formats (VHD versus qcow2 vs raw, etc). However, +what's *inside* the disk image for each platform is almost the same. + +A key difference between each image is the `ignition.platform.id` kernel argument. From the +moment the system boots and the kernel loads the initramfs, our userspace code uses this +to reliably know its target platform. As could be guessed from the name, [https://github.com/coreos/ignition/](ignition) +uses this, and it runs early on. + +But there's other code which dynamically dispatches on the platform ID: + +- https://github.com/coreos/afterburn/ +- [The time sync setup code](https://github.com/coreos/fedora-coreos-config/blob/d87b52bc6a90b53e1afeab2731b52612d5e3bbc0/tests/kola/chrony/coreos-platform-chrony-generator#L9) +- [network requirement detection](https://github.com/coreos/fedora-coreos-config/blob/d87b52bc6a90b53e1afeab2731b52612d5e3bbc0/overlay.d/05core/usr/lib/dracut/modules.d/35coreos-network/coreos-enable-network.service#L13) + +Notice in particular how the time synchronization code ends up reconfiguring chrony dynamically. +For other operating systems which do "per cloud" disk images, it would have been more +natural to just change `/etc/chrony.conf` per platform. But that would mean we have a different +ostree commit checksum per platform, breaking our "image based" update model. + +# Multipath + +Multipath differs from other storage configurations by a major aspect: it is usually not +configured by Ignition. If we mount an individual path for e.g. `/sysroot`, multipathd will +not be able to take ownership afterwards. Furthermore, directly accessing individual paths +before `multipathd` takes over is unsafe (e.g. it could be a non-optimized path). And since +we need to mount `/boot` very early on, this naturally pushes multipath configuration into +kernel arguments (and ideally soon, initramfs overlays). + +What we ended up with is adding an `rd.multipath=default` kernel argument which +triggers dracut to do "basic" automatic multipath setup in the stock initramfs: +https://github.com/dracutdevs/dracut/pull/780 + +By the nature of multipath, a tricky aspect is that e.g. the `by-label/root` symlink is +valid both *before* and *after* multipathd takes ownership. In order to safely wait for the +multipathed rootfs to show up, we have these udev rules which create, for example, +`by-label/dm-mpath-root`: + +https://github.com/coreos/fedora-coreos-config/blob/94e0daa567a658f023d48ac5929c72ed910792bd/overlay.d/05core/usr/lib/udev/rules.d/90-coreos-device-mapper.rules#L1 + +This is why we require the `root=/dev/disk/by-label/dm-mpath-root` kernel argument; so that +the mount generated by `systemd-fstab-generator` waits for the the multipath version to show +up and doesn't just mount an individual path. + +Firstboot (day-1) support is usually done at coreos-installer time by doing: + +``` +coreos-installer install \ + --append-karg rd.multipath=default \ + --append-karg root=/dev/disk/by-label/dm-mpath-root \ + --append-karg rw + ... +``` + +The `rw` bit is necessary because `systemd-fstab-generator` will create a read-only mount by +default (usually, `rw` is injected by `rdcore rootmap` for subsequent boots, but this does +not happen if there is already a `root` karg). + +That said, turning on multipath on a subsequent (day-2) boot is still supported if the +multipath setup itself is compatible with this. This is done by appending the same kargs as +above using e.g. `rpm-ostree kargs`. (Appending the kargs can also be done via +`ignition-kargs`, though this still counts as "day-2" since on first boot we'd still access +the boot partition directly.) + +We don't yet document multipath for FCOS, but we do document this setup for +OpenShift that has a kola test: + +- https://github.com/coreos/coreos-assembler/blob/f5d003d2ebb81283c3e071ce2ac268884aa7232b/mantle/kola/tests/misc/multipath.go + +We also support multipath on an individual non-root partition. See the test above for how +this works. + +More links: + +- https://github.com/coreos/ignition-dracut/issues/154 +- https://bugzilla.redhat.com/show_bug.cgi?id=1944660 +- https://github.com/coreos/fedora-coreos-config/pull/1011 diff --git a/meeting-people.txt b/meeting-people.txt new file mode 100644 index 0000000..967e3cf --- /dev/null +++ b/meeting-people.txt @@ -0,0 +1,25 @@ +# List of people to ping before the Fedora CoreOS community meetings. +# Please keep this list in alphabetical order. +@aaradhak:matrix.org +@apiaseck:matrix.org +@bipinbn:fedora.im +@bri:transfem.dev +@davdunc:fedora.im +@dustymabe:matrix.org +@guidon:guidon.ems.host +@gurssing:matrix.org +@jaimelm:fedora.im +@jbrooks:matrix.org +@jbtrystram:matrix.org +@jdoss:fedora.im +@jlebon:fedora.im +@jmarrero:matrix.org +@marmijo:fedora.im +@miabbott:fedora.im +@quentin9696:matrix.org +@rapneset:matrix.org +@ravanelli:fedora.im +@tlbueno:fedora.im +@walters:fedora.im +@ydesouza:fedora.im +@yves:siegrist.io diff --git a/metadata/README.md b/metadata/README.md new file mode 100644 index 0000000..8fd7f1d --- /dev/null +++ b/metadata/README.md @@ -0,0 +1,82 @@ +# Fedora CoreOS metadata + +Fedora CoreOS artifacts and streams are described by metadata objects, in the form of JSON documents. +This allows the general audience to consume releases and updates in a machine-friendly way. + +The following types of metadata exist: + * stream metadata + * updates metadata + * release index + * release metadata + * coreos-assembler builds + +## Stream metadata + +This document contains details about latest available artifacts, on each stream. + + * URL: `https://builds.coreos.fedoraproject.org/streams/${stream}.json` + * Usage: Primary entrypoint for users. Documented at https://docs.fedoraproject.org/en-US/fedora-coreos/getting-started/ + and e.g. consumed by the [getfedora.org download page](https://getfedora.org/en/coreos/download/) + * (TODO) stream metadata JSON schema + * [stream metadata sample][stream-sample] + * [comments and rationale][stream-rationale] + +[stream-sample]: ./stream/sample.json +[stream-rationale]: ./stream/rationale.yaml + +Projects/Code: + + - https://github.com/coreos/stream-metadata-go + - https://github.com/coreos/fedora-coreos-stream-generator/ + +## Updates metadata + +This document contains details about updates and rollouts, on each stream. + + * URL: `https://builds.coreos.fedoraproject.org/updates/${stream}.json` + * Usage: consumed by Cincinnati to discover valid update-paths + * [JSON document specifications][updates-specs] + * [updates metadata JSON schema][updates-schema] + * [updates metadata sample][updates-sample] + +[updates-schema]: ./updates/fcos-updates-schema.json +[updates-sample]: ./updates/sample.json +[updates-specs]: ./updates/specifications.md + +## Release-index + +This piece of metadata is meant to list all existing releases, on each stream. + + * URL: `https://builds.coreos.fedoraproject.org/prod/streams/${stream}/releases.json` + * Usage: consumed by Cincinnati to discover valid releases + * [JSON document specifications][release-index-specs] + * [release-index JSON schema][release-index-schema] + * [release-index sample][release-index-sample] + +[release-index-schema]: ./release-index/fcos-release-index-schema.json +[release-index-sample]: ./release-index/sample.json +[release-index-specs]: ./release-index/specifications.md + +Projects/Code: + + - https://github.com/coreos/coreos-assembler/blob/main/mantle/cmd/plume/release.go + +## Release metadata + +This document contains details about artifacts belonging to each release. + + * URL: dynamic for each release, provided by the release-index + * Usage: internal tooling, artifacts mirroring, auditing + * (TODO) release metadata JSON schema + * [release metadata sample][release-sample] + +[release-sample]: ./release/sample.json + +## CoreOS Assembler builds + +This is the primary artifact of coreos-assembler, which turns +RPMs and our configuration into images and ostree commits. + +Projects: + + - https://github.com/coreos/coreos-assembler diff --git a/metadata/release-index/fcos-release-index-schema.json b/metadata/release-index/fcos-release-index-schema.json new file mode 100644 index 0000000..22d9108 --- /dev/null +++ b/metadata/release-index/fcos-release-index-schema.json @@ -0,0 +1,87 @@ +{ + "definitions": {}, + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "title": "release-index", + "description": "FCOS release-index JSON document.", + "required": [ + "releases", + "metadata", + "stream" + ], + "properties": { + "note": { + "type": "string", + "description": "human-friendly documentation text" + }, + "releases": { + "type": "array", + "description": "Each entry MUST have a unique non-empty version field. The list MUST be sorted in ascending order, from oldest to latest release.", + "items": { + "type": "object", + "description": "Release entry.", + "required": [ + "commits", + "version", + "metadata" + ], + "properties": { + "commits": { + "type": "array", + "title": "OSTree commits", + "description": "Release entries. Each entry MUST have a unique non-empty architecture field.", + "items": { + "type": "object", + "title": "commit entry", + "required": [ + "architecture", + "checksum" + ], + "properties": { + "architecture": { + "type": "string", + "title": "architecture", + "description": "Relevant base-architecture for this commit." + }, + "checksum": { + "type": "string", + "title": "checksum", + "description": "OSTree commit identifier." + } + } + } + }, + "version": { + "type": "string", + "title": "release version", + "description": "Release version." + }, + "metadata": { + "type": "string", + "title": "metadata URL", + "description": "URL to the release metadata document for this version." + } + } + } + }, + "metadata": { + "type": "object", + "title": "document metadata", + "description": "Metadata for this JSON document.", + "required": [ + "last-modified" + ], + "properties": { + "last-modified": { + "type": "string", + "title": "last change timestamp", + "description": "UTC timestamp for the last change, in ISO 8601 format." + } + } + }, + "stream": { + "type": "string", + "description": "Name of the release stream." + } + } +} diff --git a/metadata/release-index/sample.json b/metadata/release-index/sample.json new file mode 100644 index 0000000..06766e6 --- /dev/null +++ b/metadata/release-index/sample.json @@ -0,0 +1,29 @@ +{ + "note": "For use only by Fedora CoreOS internal tooling. All other applications should obtain release info from stream metadata endpoints.", + "releases": [ + { + "commits": [ + { + "architecture": "x86_64", + "checksum": "a9c8d66d3628d1b9b4c4690777e8b730d08329b4359410cb410a2003296af1ca" + } + ], + "version": "30.20190801.0", + "metadata": "https://builds.coreos.fedoraproject.org/prod/streams/testing/builds/30.20190801.0/release.json" + }, + { + "commits": [ + { + "architecture": "x86_64", + "checksum": "b4beca154dab3696fd04f32ddab818102caa9247ec3192403adb9aaecc991bd9" + } + ], + "version": "30.20190905.0", + "metadata": "https://builds.coreos.fedoraproject.org/prod/streams/testing/builds/30.20190905.0/release.json" + } + ], + "metadata": { + "last-modified": "2019-09-06T15:56:00Z" + }, + "stream": "testing" +} diff --git a/metadata/release-index/specifications.md b/metadata/release-index/specifications.md new file mode 100644 index 0000000..52e143b --- /dev/null +++ b/metadata/release-index/specifications.md @@ -0,0 +1,14 @@ +# Release-index specifications + +The release-index is a JSON document with a single object containing the following fields: + +- `note` (optional, string): a human-friendly documentation text. +- `stream` (mandatory, string): name of the release stream. +- `metadata` (mandatory, object): metadata attributes for this JSON document. + - `last-modified` (mandatory, string): UTC timestamp for the last change, in ISO 8601 format. +- `releases` (mandatory, list of objects): per-release details. Each entry MUST have a unique non-empty `version` field. The list MUST be sorted in ascending order, from oldest to latest release. + - `version` (mandatory, string): release version identifier. + - `metadata` (mandatory, string): URL to the release metadata document for this version. + - `commits` (mandatory, list of objects): per-architecture OSTree commits. Each entry MUST have a unique non-empty `architecture` field. + - `architecture` (mandatory, string): relevant base-architecture for this commit. + - `checksum` (mandatory, string): OSTree commit identifier. diff --git a/metadata/release/sample.json b/metadata/release/sample.json new file mode 100644 index 0000000..23818b4 --- /dev/null +++ b/metadata/release/sample.json @@ -0,0 +1,287 @@ +{ + "release": "30.20190801.0", + "stream": "testing", + "architectures": { + "x86_64": { + "media": { + "aliyun": { + "artifacts": { + "qcow2.xz": { + "disk": { + "location": "https://builds.coreos.fedoraproject.org/prod/streams/testing/builds/30.20190801.0/x86_64/fedora-coreos-30.20190801.0-aliyun.qcow2.xz", + "signature": "https://builds.coreos.fedoraproject.org/prod/streams/testing/builds/30.20190801.0/x86_64/fedora-coreos-30.20190801.0-aliyun.qcow2.xz.sig", + "sha256": "8f1492f1e9e94ec3f3ecef188c4a2da52348c4b830f6365181bd03e1d969f161" + } + } + }, + "images": { + "us-east-1": { + "image": "m-6wedcb2rfmhkcl2bsbz5" + } + } + }, + "aws": { + "artifacts": { + "vmdk.xz": { + "disk": { + "location": "https://builds.coreos.fedoraproject.org/prod/streams/testing/builds/30.20190801.0/x86_64/fedora-coreos-30.20190801.0-aws.vmdk.xz", + "signature": "https://builds.coreos.fedoraproject.org/prod/streams/testing/builds/30.20190801.0/x86_64/fedora-coreos-30.20190801.0-aws.vmdk.xz.sig", + "sha256": "7afd8ebdd61ccb6da45dfb19ccc71c47f43e1189c1fb7eb75df6f23d7c8f87dc" + } + } + }, + "images": { + "us-east-1": { + "image": "ami-0506465824cb1b578" + } + } + }, + "applehv": { + "artifacts": { + "raw.gz": { + "disk": { + "location": "https://builds.coreos.fedoraproject.org/prod/streams/testing/builds/30.20190801.0/x86_64/fedora-coreos-30.20190801.0-applehv.raw.gz", + "signature": "https://builds.coreos.fedoraproject.org/prod/streams/testing/builds/30.20190801.0/x86_64/fedora-coreos-30.20190801.0-applehv.raw.gz.sig", + "sha256": "a889159d661339e635372b807f0a98bb93c64aabfaf89a801b2f03491488f0ef" + } + } + } + }, + "azure": { + "artifacts": { + "vhd.xz": { + "disk": { + "location": "https://builds.coreos.fedoraproject.org/prod/streams/testing/builds/30.20190801.0/x86_64/fedora-coreos-30.20190801.0-azure.vhd.xz", + "signature": "https://builds.coreos.fedoraproject.org/prod/streams/testing/builds/30.20190801.0/x86_64/fedora-coreos-30.20190801.0-azure.vhd.xz.sig", + "sha256": "4bb0e1595f66f344c1cc084e163c4352235b2accf3a1385b9eb4b3e4ca5b1d24" + } + } + } + }, + "azurestack": { + "artifacts": { + "vhd.xz": { + "disk": { + "location": "https://builds.coreos.fedoraproject.org/prod/streams/testing/builds/30.20190801.0/x86_64/fedora-coreos-30.20190801.0-azurestack.vhd.xz", + "signature": "https://builds.coreos.fedoraproject.org/prod/streams/testing/builds/30.20190801.0/x86_64/fedora-coreos-30.20190801.0-azurestack.vhd.xz.sig", + "sha256": "344c1cc084e163c4352235b2accf34d24bb0e1595f66fa1385b9eb4b3e4ca5b1" + } + } + } + }, + "digitalocean": { + "artifacts": { + "qcow2.gz": { + "disk": { + "location": "https://builds.coreos.fedoraproject.org/prod/streams/testing/builds/30.20190801.0/x86_64/fedora-coreos-30.20190801.0-digitalocean.qcow2.gz", + "signature": "https://builds.coreos.fedoraproject.org/prod/streams/testing/builds/30.20190801.0/x86_64/fedora-coreos-30.20190801.0-digitalocean.qcow2.gz.sig", + "sha256": "435224bb0e1595f344c1cc05b1d2484e163c66f35b2accf3a1385b9eb4b3e4ca" + } + } + } + }, + "exoscale": { + "artifacts": { + "qcow2.xz": { + "disk": { + "location": "https://builds.coreos.fedoraproject.org/prod/streams/testing/builds/30.20190801.0/x86_64/fedora-coreos-30.20190801.0-exoscale.qcow2.xz", + "signature": "https://builds.coreos.fedoraproject.org/prod/streams/testing/builds/30.20190801.0/x86_64/fedora-coreos-30.20190801.0-exoscale.qcow2.xz.sig", + "sha256": "435224bb0e1595f344c1cc05b1d2484e163c66f35b2accf3a1385b9eb4b3e4ca" + } + } + } + }, + "gcp": { + "artifacts": { + "tar.gz": { + "disk": { + "location": "https://builds.coreos.fedoraproject.org/prod/streams/testing/builds/30.20190801.0/x86_64/fedora-coreos-30.20190801.0-gcp.tar.gz", + "signature": "https://builds.coreos.fedoraproject.org/prod/streams/testing/builds/30.20190801.0/x86_64/fedora-coreos-30.20190801.0-gcp.tar.gz.sig", + "sha256": "344c1cc05b1d2484e163c66f35b2accf3a1385b9eb435224bb0e1595f4b3e4ca" + } + } + } + }, + "hetzner": { + "artifacts": { + "raw.xz": { + "disk": { + "location": "https://builds.coreos.fedoraproject.org/prod/streams/testing/builds/30.20190801.0/x86_64/fedora-coreos-30.20190801.0-hetzner.raw.xz", + "signature": "https://builds.coreos.fedoraproject.org/prod/streams/testing/builds/30.20190801.0/x86_64/fedora-coreos-30.20190801.0-hetzner.raw.xz.sig", + "sha256": "a889159d661339e635372b807f0a98bb93c64aabfaf89a801b2f03491488f0ef" + } + } + } + }, + "hyperv": { + "artifacts": { + "vhdx.zip": { + "disk": { + "location": "https://builds.coreos.fedoraproject.org/prod/streams/testing/builds/30.20190801.0/x86_64/fedora-coreos-30.20190801.0-hyperv.vhdx.zip", + "signature": "https://builds.coreos.fedoraproject.org/prod/streams/testing/builds/30.20190801.0/x86_64/fedora-coreos-30.20190801.0-hyperv.vhdx.zip.sig", + "sha256": "a889159d661339e635372b807f0a98bb93c64aabfaf89a801b2f03491488f0ef" + } + } + } + }, + "ibmcloud": { + "artifacts": { + "qcow2.xz": { + "disk": { + "location": "https://builds.coreos.fedoraproject.org/prod/streams/testing/builds/30.20190801.0/x86_64/fedora-coreos-30.20190801.0-ibmcloud.qcow2.xz", + "signature": "https://builds.coreos.fedoraproject.org/prod/streams/testing/builds/30.20190801.0/x86_64/fedora-coreos-30.20190801.0-ibmcloud.qcow2.xz.sig", + "sha256": "344c1cc05b1d2484e163c66f35b2accf3a1385b9eb435224bb0e1595f4b3e4ca" + } + } + } + }, + "kubevirt": { + "artifacts": { + "ociarchive": { + "disk": { + "location": "https://builds.coreos.fedoraproject.org/prod/streams/testing/builds/30.20190801.0/x86_64/fedora-coreos-30.20190801.0-kubevirt.ociarchive", + "signature": "https://builds.coreos.fedoraproject.org/prod/streams/testing/builds/30.20190801.0/x86_64/fedora-coreos-30.20190801.0-kubevirt.ociarchive.sig", + "sha256": "2accf3a1385b9eb435224bb0e1595f4b3e4344c1cc05b1d2484e163c66f35bca" + } + } + } + }, + "metal": { + "artifacts": { + "raw.xz": { + "disk": { + "location": "https://builds.coreos.fedoraproject.org/prod/streams/testing/builds/30.20190801.0/x86_64/fedora-coreos-30.20190801.0-metal.raw.xz", + "signature": "https://builds.coreos.fedoraproject.org/prod/streams/testing/builds/30.20190801.0/x86_64/fedora-coreos-30.20190801.0-metal.raw.xz.sig", + "sha256": "881178a4794816e623b02012a84b11d59a96dd59035508a0986a5b6c6be074ed" + } + }, + "iso": { + "disk": { + "location": "https://builds.coreos.fedoraproject.org/prod/streams/testing/builds/30.20190801.0/x86_64/fedora-coreos-30.20190801.0-live.iso", + "signature": "https://builds.coreos.fedoraproject.org/prod/streams/testing/builds/30.20190801.0/x86_64/fedora-coreos-30.20190801.0-live.iso.sig", + "sha256": "aab20fcafc240fa03f7e43370f8be8c14b99b045eca156a0f5e77286b2e9e8c4" + } + }, + "pxe": { + "kernel": { + "location": "https://builds.coreos.fedoraproject.org/prod/streams/testing/builds/30.20190801.0/x86_64/fedora-coreos-30.20190801.0-live-kernel", + "signature": "https://builds.coreos.fedoraproject.org/prod/streams/testing/builds/30.20190801.0/x86_64/fedora-coreos-30.20190801.0-live-kernel.sig", + "sha256": "bb493370b3716a009628197b7fce41107f1f5349f1a7ef67a8ecc7eebb3d2183" + }, + "initramfs": { + "location": "https://builds.coreos.fedoraproject.org/prod/streams/testing/builds/30.20190801.0/x86_64/fedora-coreos-30.20190801.0-live-initramfs.img", + "signature": "https://builds.coreos.fedoraproject.org/prod/streams/testing/builds/30.20190801.0/x86_64/fedora-coreos-30.20190801.0-live-initramfs.img.sig", + "sha256": "04dde273b9e5d1b361beb44fde337f915509ad8e128fb408f793fdd0ae84c17d" + }, + "rootfs": { + "location": "https://builds.coreos.fedoraproject.org/prod/streams/testing/builds/30.20190801.0/x86_64/fedora-coreos-30.20190801.0-live-rootfs.img", + "signature": "https://builds.coreos.fedoraproject.org/prod/streams/testing/builds/30.20190801.0/x86_64/fedora-coreos-30.20190801.0-live-rootfs.img.sig", + "sha256": "509ad8e128fb408f793fdd0ae84c17d04dde273b9e5d1b361beb44fde337f915" + } + } + } + }, + "nutanix": { + "artifacts": { + "qcow2": { + "disk": { + "location": "https://builds.coreos.fedoraproject.org/prod/streams/testing/builds/30.20190801.0/x86_64/fedora-coreos-30.20190801.0-nutanix.qcow2", + "signature": "https://builds.coreos.fedoraproject.org/prod/streams/testing/builds/30.20190801.0/x86_64/fedora-coreos-30.20190801.0-nutanix.qcow2.sig", + "sha256": "1b3e4ca5b1d2463c4352235b2accf95f66f344c1cc084e3a1385b9eb4bb0e154" + } + } + } + }, + "openstack": { + "artifacts": { + "qcow2.xz": { + "disk": { + "location": "https://builds.coreos.fedoraproject.org/prod/streams/testing/builds/30.20190801.0/x86_64/fedora-coreos-30.20190801.0-openstack.qcow2.xz", + "signature": "https://builds.coreos.fedoraproject.org/prod/streams/testing/builds/30.20190801.0/x86_64/fedora-coreos-30.20190801.0-openstack.qcow2.xz.sig", + "sha256": "b2cab76cb2038826cb8de99f34d192bda4e805a4eb51be2979ba984424e72501" + } + } + } + }, + "oraclecloud": { + "artifacts": { + "qcow2.xz": { + "disk": { + "location": "https://builds.coreos.fedoraproject.org/prod/streams/testing/builds/30.20190801.0/x86_64/fedora-coreos-30.20190801.0-oraclecloud.qcow2.xz", + "signature": "https://builds.coreos.fedoraproject.org/prod/streams/testing/builds/30.20190801.0/x86_64/fedora-coreos-30.20190801.0-oracecloud.qcow2.xz.sig", + "sha256": "868da197ae9179aded982ea6445d7d5e30acf8d03cdcdc32acfe2003d2c65491" + } + } + } + }, + "proxmoxve": { + "artifacts": { + "raw.xz": { + "disk": { + "location": "https://builds.coreos.fedoraproject.org/prod/streams/testing/builds/30.20190801.0/x86_64/fedora-coreos-30.20190801.0-proxmoxve.qcow2.xz", + "signature": "https://builds.coreos.fedoraproject.org/prod/streams/testing/builds/30.20190801.0/x86_64/fedora-coreos-30.20190801.0-proxmoxve.qcow2.xz.sig", + "sha256": "394cd6431b19c82a46a7215ebead15960faf9814092203456d56960a1b4d8777" + } + } + } + }, + "qemu": { + "artifacts": { + "qcow2.xz": { + "disk": { + "location": "https://builds.coreos.fedoraproject.org/prod/streams/testing/builds/30.20190801.0/x86_64/fedora-coreos-30.20190801.0-qemu.qcow2.xz", + "signature": "https://builds.coreos.fedoraproject.org/prod/streams/testing/builds/30.20190801.0/x86_64/fedora-coreos-30.20190801.0-qemu.qcow2.xz.sig", + "sha256": "4dcc04bd43f48bc74a16bd7d20b47829591a2a2fbe3ee8d59fedef2b1ddd1264" + } + } + } + }, + "qemu-secex": { + "artifacts": { + "qcow2.xz": { + "disk": { + "location": "https://builds.coreos.fedoraproject.org/prod/streams/testing/builds/30.20190801.0/x86_64/fedora-coreos-30.20190801.0-qemu-secex.qcow2.xz", + "signature": "https://builds.coreos.fedoraproject.org/prod/streams/testing/builds/30.20190801.0/x86_64/fedora-coreos-30.20190801.0-qemu-secex.qcow2.xz.sig", + "sha256": "2afbb0ac4a19f58a55db35db0a690d488f065664e9bcba1b802966f0ae6aad57" + } + } + } + }, + "virtualbox": { + "artifacts": { + "ova": { + "disk": { + "location": "https://builds.coreos.fedoraproject.org/prod/streams/testing/builds/30.20190801.0/x86_64/fedora-coreos-30.20190801.0-virtualbox.ova", + "signature": "https://builds.coreos.fedoraproject.org/prod/streams/testing/builds/30.20190801.0/x86_64/fedora-coreos-30.20190801.0-virtualbox.ova.sig", + "sha256": "54729f458c1552c19aa2f2b905860fadbe0a714df45d1d49731725038895094c" + } + } + } + }, + "vmware": { + "artifacts": { + "ova": { + "disk": { + "location": "https://builds.coreos.fedoraproject.org/prod/streams/testing/builds/30.20190801.0/x86_64/fedora-coreos-30.20190801.0-vmware.ova", + "signature": "https://builds.coreos.fedoraproject.org/prod/streams/testing/builds/30.20190801.0/x86_64/fedora-coreos-30.20190801.0-vmware.ova.sig", + "sha256": "b905860fadbe0a754729f458c1552c19aa2f214df45d1d49731725038895094c" + } + } + } + }, + "vultr": { + "artifacts": { + "raw.xz": { + "disk": { + "location": "https://builds.coreos.fedoraproject.org/prod/streams/testing/builds/30.20190801.0/x86_64/fedora-coreos-30.20190801.0-vultr.raw.xz", + "signature": "https://builds.coreos.fedoraproject.org/prod/streams/testing/builds/30.20190801.0/x86_64/fedora-coreos-30.20190801.0-vultr.raw.xz.sig", + "sha256": "d7d20b47829591a2a2fbe3ee8d59fe4dcc04bd43f48bc74a16bdef2b1ddd1264" + } + } + } + } + }, + "commit": "a9c8d66d3628d1b9b4c4690777e8b730d08329b4359410cb410a2003296af1ca" + } + } +} diff --git a/metadata/stream/rationale.yaml b/metadata/stream/rationale.yaml new file mode 100644 index 0000000..4072f34 --- /dev/null +++ b/metadata/stream/rationale.yaml @@ -0,0 +1,276 @@ +# Note: the actual document will be JSON + +# Include stream name so the document is self-contained +stream: stable +metadata: + last-modified: "2019-06-04T16:18:34Z" + generator: "fedora-coreos-stream-generator v0.1.0" +architectures: + x86_64: + artifacts: + # Some of these will be useful for many users, such as qemu or + # openstack. Some will likely only be useful for cloud operators, + # such as digitalocean. Some, such as aws, are useful for users + # in special situations. + aliyun: + release: 30.1.2.3 + formats: + "qcow2.xz": + disk: + location: https://artifacts.example.com/g0xah6aenvaaVosh.qcow2.xz + signature: https://artifacts.example.com/g0xah6aenvaaVosh.qcow2.xz.sig + sha256: 149afbf4c8996fb92427ae3b0c44298fc1ce41e4649b934ca495991b7852b855 + uncompressed-sha256: d02d5ac0f2a2789602e9df950c38acb15380d2799b4bdb59394e4eeabdd3a662 + applehv: + release: 30.1.2.3 + formats: + "raw.gz": + disk: + location: https://artifacts.example.com/quohgh8ei0uzaD5a.raw.gz + signature: https://artifacts.example.com/quohgh8ei0uzaD5a.raw.gz.sig + sha256: 4c8996fb92427ae41e4649b934ca4e3b0c44298fc1c149afbf95991b7852b855 + aws: + release: 30.1.2.3 + formats: + # Generally one format per platform, but allow for future expansion + # without obscuring the platform ID (as on Container Linux) + "vmdk.xz": + # Generally only one artifact, but not always + disk: + location: https://artifacts.example.com/dsB2fnzP7KhqzQ5a.vmdk.xz + signature: https://artifacts.example.com/dsB2fnzP7KhqzQ5a.vmdk.xz.sig + sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 + uncompressed-sha256: 38acb15d02d5ac0f2a2789602e9df950c380d2799b4bdb59394e4eeabdd3a662 + azure: + release: 30.1.2.3 + formats: + "vhd.xz": + disk: + location: https://artifacts.example.com/6vaaVoshaeng0xah.vhd.xz + signature: https://artifacts.example.com/6vaaVoshaeng0xah.vhd.xz.sig + sha256: f4c8996fb92427ae41e4e3b0c44298fc1c149afb649b934ca495991b7852b855 + uncompressed-sha256: 38acb15d02d5ac0f2a2789602e9df950c380d2799b4bdb59394e4eeabdd3a662 + azurestack: + release: 30.1.2.3 + formats: + "vhd.xz": + disk: + location: https://artifacts.example.com/ng0xahos6aevaaVh.vhd.xz + signature: https://artifacts.example.com/ng0xahos6aevaaVh.vhd.xz.sig + sha256: ae41e4649b934ca495991b7852b855e3b0c44298fc1c149afbf4c8996fb92427 + uncompressed-sha256: 38acb15d02d5ac0f2a2789602e9df950c380d2799b4bdb59394e4eeabdd3a662 + digitalocean: + release: 30.1.2.3 + formats: + "qcow2.gz": + disk: + location: https://artifacts.example.com/ichaloomuHax9ahR.qcow2.gz + signature: https://artifacts.example.com/ichaloomuHax9ahR.qcow2.gz.sig + sha256: 427ae41e4649b934ca495991b7852b855e3b0c44298fc1c149afbf4c8996fb92 + uncompressed-sha256: 38acb15d02d5ac0f2a2789602e9df950c380d2799b4bdb59394e4eeabdd3a662 + exoscale: + release: 30.1.2.3 + formats: + "qcow2.xz": + disk: + location: https://artifacts.example.com/aeng0xah6vaaVosh.qcow2.xz + signature: https://artifacts.example.com/aeng0xah6vaaVosh.qcow2.xz.sig + sha256: 49afbf4c8996fb92427ae41e464e3b0c44298fc1c19b934ca495991b7852b855 + uncompressed-sha256: f2a2789602e9df950c380d2738acb15d02d5ac099b4bdb59394e4eeabdd3a662 + gcp: + release: 30.1.2.3 + formats: + "tar.gz": + disk: + location: https://artifacts.example.com/ais7tah1aa7Ahvei.tar.gz + signature: https://artifacts.example.com/ais7tah1aa7Ahvei.tar.gz.sig + sha256: 96fb92427ae41e4649b934ca495991b7852b85e3b0c44298fc1c149afbf4c895 + uncompressed-sha256: 38acb15d02d5ac0f2a2789602e9df950c380d2799b4bdb59394e4eeabdd3a662 + hetzner: + release: 30.1.2.3 + formats: + "raw.xz": + disk: + location: https://artifacts.example.com/quohgh8ei0uzaD5a.raw.xz + signature: https://artifacts.example.com/quohgh8ei0uzaD5a.raw.xz.sig + sha256: 4c8996fb92427ae41e4649b934ca4e3b0c44298fc1c149afbf95991b7852b855 + hyperv: + release: 30.1.2.3 + formats: + "vhdx.zip": + disk: + location: https://artifacts.example.com/quohgh8ei0uzaD5a.vhdx.zip + signature: https://artifacts.example.com/quohgh8ei0uzaD5a.vhdx.zip.sig + sha256: 4c8996fb92427ae41e4649b934ca4e3b0c44298fc1c149afbf95991b7852b855 + ibmcloud: + release: 30.1.2.3 + formats: + "qcow2.xz": + disk: + location: https://artifacts.example.com/0xah6vaaenVoshga.qcow2.xz + signature: https://artifacts.example.com/0xah6vaaenVoshga.qcow2.xz.sig + sha256: ae3b0c44298fc1ce41e4649b149afbf4c8996fb92427934ca495991b7852b855 + uncompressed-sha256: 02e9df950c38acb1538d02d5ac0f2a278960d2799b4bdb59394e4eeabdd3a662 + kubevirt: + release: 30.1.2.3 + formats: + "ociarchive": + disk: + location: https://artifacts.example.com/Kiejeeb6ohpu8Eel.ociarchive + signature: https://artifacts.example.com/Kiejeeb6ohpu8Eel.ociarchive.sig + sha256: 2427ae41e4649b934ca495991b7852b85e3b0c44298fc1c149afbf4c8996fb95 + metal: + release: 30.1.2.3 + formats: + "raw.xz": + disk: + location: https://artifacts.example.com/xTqYJZKCPNvoNs6B.raw.xz + signature: https://artifacts.example.com/xTqYJZKCPNvoNs6B.raw.xz.sig + sha256: 6fb92427ae41e4649b934ca49e3b0c44298fc1c149afbf4c8995991b7852b855 + uncompressed-sha256: 38acb15d02d5ac0f2a2789602e9df950c380d2799b4bdb59394e4eeabdd3a662 + iso: + disk: + location: https://artifacts.example.com/ADE5GO3bjAXeDcLO.iso + signature: https://artifacts.example.com/ADE5GO3bjAXeDcLO.iso.sig + sha256: 8996fb92427ae41e4649b934ca495991b78e3b0c44298fc1c149afbf4c52b855 + pxe: + kernel: + location: https://artifacts.example.com/hkIj8FkCydT3lV9h + signature: https://artifacts.example.com/hkIj8FkCydT3lV9h.sig + sha256: 27ae41e4649b934ca495991b7852be3b0c44298fc1c149afbf4c8996fb924855 + initramfs: + location: https://artifacts.example.com/a9ytS8yB4cGZpca1.img + signature: https://artifacts.example.com/a9ytS8yB4cGZpca1.img.sig + sha256: ae41e4649b934ca495991b7852be3b0c44298fc1c149afbf4c8996fb92427855 + rootfs: + location: https://artifacts.example.com/Seb8em4QU9p6wEFr.img + signature: https://artifacts.example.com/Seb8em4QU9p6wEFr.img.sig + sha256: fb92427ae41e4649b93e3b0c44298fc1c149afbf4c89964ca495991b7852b855 + nutanix: + release: 30.1.2.3 + formats: + "qcow2": + disk: + location: https://artifacts.example.com/xah6vaaVaeng0osh.qcow2 + signature: https://artifacts.example.com/xah6vaaVaeng0osh.qcow2.sig + sha256: 991b7852b85b0c44298fc1c149afbfe36fb92427ae41e4649b934ca4954c8995 + openstack: + release: 30.1.2.3 + formats: + "qcow2.xz": + disk: + location: https://artifacts.example.com/oKooheogobofai8l.qcow2.xz + signature: https://artifacts.example.com/oKooheogobofai8l.qcow2.xz.sig + sha256: ae41e4649b934ca495991b785e3b0c44298fc1c149afbf4c8996fb924272b855 + uncompressed-sha256: 38acb15d02d5ac0f2a2789602e9df950c380d2799b4bdb59394e4eeabdd3a662 + oraclecloud: + release: 30.1.2.3 + formats: + "qcow2.xz": + disk: + location: https://artifacts.example.com/oKooheogobofai8l.qcow2.xz + signature: https://artifacts.example.com/oKooheogobofai8l.qcow2.xz.sig + sha256: 868da197ae9179aded982ea6445d7d5e30acf8d03cdcdc32acfe2003d2c65491" + uncompressed-sha256: 75a5c30bf84a605cc9fa617e856d9523d8d4c50607837a7d33e4d81e9809891a + proxmoxve: + release: 30.1.2.3 + formats: + "qcow2.xz": + disk: + location: https://artifacts.example.com/TieshohWah0aewai/.qcow2.xz + signature: https://artifacts.example.com/TieshohWah0aewai/.qcow2.xz.sig + sha256: 394cd6431b19c82a46a7215ebead15960faf9814092203456d56960a1b4d8777 + qemu: + release: 30.1.2.3 + formats: + "qcow2.xz": + disk: + location: https://artifacts.example.com/Siejeeb6ohpu8Eel.qcow2.xz + signature: https://artifacts.example.com/Siejeeb6ohpu8Eel.qcow2.xz.sig + sha256: b0c44298fc1c149afbf4c8996fb9242e37ae41e4649991b7852b855b934ca495 + uncompressed-sha256: 38acb15d02d5ac0f2a2789602e9df950c380d2799b4bdb59394e4eeabdd3a662 + qemu-secex: + release: 30.1.2.3 + formats: + "qcow2.xz": + disk: + location: https://artifacts.example.com/6d5814250381013f.qcow2.xz + signature: https://artifacts.example.com/6d5814250381013f.qcow2.xz.sig + sha256: 2afbb0ac4a19f58a55db35db0a690d488f065664e9bcba1b802966f0ae6aad57 + uncompressed-sha256: 2b1cb667f3468ef7b462e5ec8395fcd2982e424d1727336e95f74c611d8bbd53 + virtualbox: + release: 30.1.2.3 + formats: + ova: + disk: + location: https://artifacts.example.com/quohgh8ei0uzaD5a.ova + signature: https://artifacts.example.com/quohgh8ei0uzaD5a.ova.sig + sha256: 4c8996fb92427ae41e4649b934ca4e3b0c44298fc1c149afbf95991b7852b855 + vmware: + release: 30.1.2.3 + formats: + ova: + disk: + location: https://artifacts.example.com/quohgh8ei0uzaD5a.ova + signature: https://artifacts.example.com/quohgh8ei0uzaD5a.ova.sig + sha256: 96fb92427ae41e4649b934cae3b0c44298fc1c149afbf4c89495991b7852b855 + vultr: + release: 30.1.2.3 + formats: + "raw.xz": + disk: + location: https://artifacts.example.com/ah6vaaVaeng0xosh.raw.xz + signature: https://artifacts.example.com/ah6vaaVaeng0xosh.raw.xz.sig + sha256: ae3b0c44298fc1ce41e4649b149afbf4c8996fb92427934ca495991b7852b855 + uncompressed-sha256: 02e9df950c38acb1538d02d5ac0f2a278960d2799b4bdb59394e4eeabdd3a662 + + images: + # Cloud images to be launched directly by users. These are in a + # separate section because they might not always in sync with the + # release artifacts above. + aliyun: + regions: + ap-northeast-1: + release: 30.1.2.3 + image: m-cb2rfmhkcl2b6wedsbz5 + ap-south-1: + release: 30.1.2.3 + image: m-ef3e19la2d35aftwxz5p + aws: + regions: + us-east-1: + release: 30.1.2.3 + image: ami-0123456789abcdef + us-east-2: + release: 30.1.2.3 + image: ami-0123456789abcdef + azure: + # We could give a specific image URN here, but we probably want + # users to always use a Marketplace URN. So this is a static + # string, and represents advice rather than a value we might + # change. + image: Fedora:CoreOS:stable:latest + digitalocean: + # We don't control platform ingest, so an image slug is probably + # the best we can do. + image: fedora-coreos-stable + exoscale: + image: Linux Fedora CoreOS 64-bit + gcp: + # Ideally users use the project + family. These are static strings, + # and represent advice rather than a value we might change. + project: fedora-coreos-cloud + family: fedora-coreos-stable + # As an alternative, we also list the currently recommended image + # and its release. + release: 30.1.2.3 + name: fedora-coreos-30-1-2-3-gcp-x86-64 + kubevirt: + # ContainerDisk in a container registry + # Ideally users use this pull spec, which specifies a floating tag. + # This value is expected to be stable over time. + image: exampleregistry.io/fcos/fcos:stable + # As an alternative, we also list a digest-based pull spec for the + # currently recommended image, and its release. + release: 30.1.2.3 + digest-ref: exampleregistry.io/fcos/fcos@sha256:67a81539946ec0397196c145394553b8e0241acf27b14ae9de43bc56e167f773 diff --git a/metadata/stream/sample.json b/metadata/stream/sample.json new file mode 100644 index 0000000..134ebb0 --- /dev/null +++ b/metadata/stream/sample.json @@ -0,0 +1,417 @@ +{ + "stream": "stable", + "metadata": { + "last-modified": "2021-04-28T13:46:31Z", + "generator": "fedora-coreos-stream-generator v0.1.0" + }, + "architectures": { + "x86_64": { + "artifacts": { + "aliyun": { + "release": "33.20210412.3.0", + "formats": { + "qcow2.xz": { + "disk": { + "location": "https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/33.20210412.3.0/x86_64/fedora-coreos-33.20210412.3.0-aliyun.x86_64.qcow2.xz", + "signature": "https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/33.20210412.3.0/x86_64/fedora-coreos-33.20210412.3.0-aliyun.x86_64.qcow2.xz.sig", + "sha256": "35e80ce08915e58459537b46e75236f4eec7c2974933d9a32de6922fbce84eea", + "uncompressed-sha256": "e23666a4e8c15bb80d2cbe2eff254037df0052d486c3841892c50025d40547a7" + } + } + } + }, + "applehv": { + "release": "33.20210412.3.0", + "formats": { + "raw.gz": { + "disk": { + "location": "https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/33.20210412.3.0/x86_64/fedora-coreos-33.20210412.3.0-applehv.x86_64.raw.gz", + "signature": "https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/33.20210412.3.0/x86_64/fedora-coreos-33.20210412.3.0-applehv.x86_64.raw.gz.sig", + "sha256": "728e876d87ec71de27fc1d882840e6877346423433339a2b8606fa28e57413fd" + } + } + } + }, + "aws": { + "release": "33.20210412.3.0", + "formats": { + "vmdk.xz": { + "disk": { + "location": "https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/33.20210412.3.0/x86_64/fedora-coreos-33.20210412.3.0-aws.x86_64.vmdk.xz", + "signature": "https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/33.20210412.3.0/x86_64/fedora-coreos-33.20210412.3.0-aws.x86_64.vmdk.xz.sig", + "sha256": "2dc2bd028edd52213c9a3a2ecc818307c2c5a0a13165747cbfeead4b8391e25b", + "uncompressed-sha256": "cc7f0061511bb9949e81aa4d8678ad8eed2b0a3ced956fa64b851502be7dfbbd" + } + } + } + }, + "azure": { + "release": "33.20210412.3.0", + "formats": { + "vhd.xz": { + "disk": { + "location": "https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/33.20210412.3.0/x86_64/fedora-coreos-33.20210412.3.0-azure.x86_64.vhd.xz", + "signature": "https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/33.20210412.3.0/x86_64/fedora-coreos-33.20210412.3.0-azure.x86_64.vhd.xz.sig", + "sha256": "9eaa0504ba6c33bd5baf21335ada861b5e01e8628ba40bc04050a436b3626a05", + "uncompressed-sha256": "2593ac3d4e152fbbde9d7a5b1f0f69746a807148e1dbf64aa4f657da170dcece" + } + } + } + }, + "azurestack": { + "release": "33.20210412.3.0", + "formats": { + "vhd.xz": { + "disk": { + "location": "https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/33.20210412.3.0/x86_64/fedora-coreos-33.20210412.3.0-azurestack.x86_64.vhd.xz", + "signature": "https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/33.20210412.3.0/x86_64/fedora-coreos-33.20210412.3.0-azurestack.x86_64.vhd.xz.sig", + "sha256": "3bd5baf21335ada861b5e01e8628ba40bc04050a436b9eaa0504ba6c33626a05", + "uncompressed-sha256": "de9d7a5b1f0f69746a807148e1dbf64aa2593ac3d4e152fbb4f657da170dcece" + } + } + } + }, + "digitalocean": { + "release": "33.20210412.3.0", + "formats": { + "qcow2.gz": { + "disk": { + "location": "https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/33.20210412.3.0/x86_64/fedora-coreos-33.20210412.3.0-digitalocean.x86_64.qcow2.gz", + "signature": "https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/33.20210412.3.0/x86_64/fedora-coreos-33.20210412.3.0-digitalocean.x86_64.qcow2.gz.sig", + "sha256": "2b0c7a697005f00bd99edd2c3bae80f258287843de6dc4e5d79b6ec1b6afb863" + } + } + } + }, + "exoscale": { + "release": "33.20210412.3.0", + "formats": { + "qcow2.xz": { + "disk": { + "location": "https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/33.20210412.3.0/x86_64/fedora-coreos-33.20210412.3.0-exoscale.x86_64.qcow2.xz", + "signature": "https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/33.20210412.3.0/x86_64/fedora-coreos-33.20210412.3.0-exoscale.x86_64.qcow2.xz.sig", + "sha256": "4acb935fb4ef51c971172f4c71c81ba5fdf659aaad25be6fee83b83a6387cc32", + "uncompressed-sha256": "459ace6388d56fc90281de7ee97dd4cc4cfa61143a894d24d3cf0ccf235ff07e" + } + } + } + }, + "gcp": { + "release": "33.20210412.3.0", + "formats": { + "tar.gz": { + "disk": { + "location": "https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/33.20210412.3.0/x86_64/fedora-coreos-33.20210412.3.0-gcp.x86_64.tar.gz", + "signature": "https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/33.20210412.3.0/x86_64/fedora-coreos-33.20210412.3.0-gcp.x86_64.tar.gz.sig", + "sha256": "76fcc10bbba4517678217a81f95095702e83dc8ed3a2bc2d10062de214b55396" + } + } + } + }, + "hetzner": { + "release": "33.20210412.3.0", + "formats": { + "raw.xz": { + "disk": { + "location": "https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/33.20210412.3.0/x86_64/fedora-coreos-33.20210412.3.0-hetzner.x86_64.raw.xz", + "signature": "https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/33.20210412.3.0/x86_64/fedora-coreos-33.20210412.3.0-hetzner.x86_64.raw.xz.sig", + "sha256": "728e876d87ec71de27fc1d882840e6877346423433339a2b8606fa28e57413fd" + } + } + } + }, + "hyperv": { + "release": "33.20210412.3.0", + "formats": { + "vhdx.zip": { + "disk": { + "location": "https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/33.20210412.3.0/x86_64/fedora-coreos-33.20210412.3.0-hyperv.x86_64.vhdx.zip", + "signature": "https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/33.20210412.3.0/x86_64/fedora-coreos-33.20210412.3.0-hyperv.x86_64.vhdx.zip.sig", + "sha256": "728e876d87ec71de27fc1d882840e6877346423433339a2b8606fa28e57413fd" + } + } + } + }, + "ibmcloud": { + "release": "33.20210412.3.0", + "formats": { + "qcow2.xz": { + "disk": { + "location": "https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/33.20210412.3.0/x86_64/fedora-coreos-33.20210412.3.0-ibmcloud.x86_64.qcow2.xz", + "signature": "https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/33.20210412.3.0/x86_64/fedora-coreos-33.20210412.3.0-ibmcloud.x86_64.qcow2.xz.sig", + "sha256": "aa1db0898fb88aae956343b99ca70975bd821050f274a79f63d18a2e2a489e26", + "uncompressed-sha256": "cd7d5b979e15336e4c9b44f25cf86927fe4780b5775c2d02fe4f71827d820d4c" + } + } + } + }, + "kubevirt": { + "release": "33.20210412.3.0", + "formats": { + "ociarchive": { + "disk": { + "location": "https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/33.20210412.3.0/x86_64/fedora-coreos-33.20210412.3.0-kubevirt.x86_64.ociarchive", + "signature": "https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/33.20210412.3.0/x86_64/fedora-coreos-33.20210412.3.0-kubevirt.x86_64.ociarchive.sig", + "sha256": "6343b99ca70975bd821050f274aa1db0898fb88aae95a79f63d18a2e2a489e26" + } + } + } + }, + "metal": { + "release": "33.20210412.3.0", + "formats": { + "4k.raw.xz": { + "disk": { + "location": "https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/33.20210412.3.0/x86_64/fedora-coreos-33.20210412.3.0-metal4k.x86_64.raw.xz", + "signature": "https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/33.20210412.3.0/x86_64/fedora-coreos-33.20210412.3.0-metal4k.x86_64.raw.xz.sig", + "sha256": "c99e07bbdcb72615830985ddd1d63ab21779b874248952f15fd937ade5593c1c", + "uncompressed-sha256": "8d6508b36095b78c6d306b0857a4a6272f5c25515a5c2f591f434290d63d88e1" + } + }, + "iso": { + "disk": { + "location": "https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/33.20210412.3.0/x86_64/fedora-coreos-33.20210412.3.0-live.x86_64.iso", + "signature": "https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/33.20210412.3.0/x86_64/fedora-coreos-33.20210412.3.0-live.x86_64.iso.sig", + "sha256": "97b7aed0086509c2187a4a9f91199aba7c430a5f9aface4e7b06cbcc664a0b4d" + } + }, + "pxe": { + "kernel": { + "location": "https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/33.20210412.3.0/x86_64/fedora-coreos-33.20210412.3.0-live-kernel-x86_64", + "signature": "https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/33.20210412.3.0/x86_64/fedora-coreos-33.20210412.3.0-live-kernel-x86_64.sig", + "sha256": "28314d6a50610dd342684d6edd19f386b8b8ee150f924775d81408be1987c3d8" + }, + "initramfs": { + "location": "https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/33.20210412.3.0/x86_64/fedora-coreos-33.20210412.3.0-live-initramfs.x86_64.img", + "signature": "https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/33.20210412.3.0/x86_64/fedora-coreos-33.20210412.3.0-live-initramfs.x86_64.img.sig", + "sha256": "5c7c0cc0a8c5d7a1894599ea1d1f5311a1cba0c8530decf9481d7e6cfc1873b7" + }, + "rootfs": { + "location": "https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/33.20210412.3.0/x86_64/fedora-coreos-33.20210412.3.0-live-rootfs.x86_64.img", + "signature": "https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/33.20210412.3.0/x86_64/fedora-coreos-33.20210412.3.0-live-rootfs.x86_64.img.sig", + "sha256": "50e63eddc657b24b86d53fbc267441d5e7e7c43eaac58ad9998dadd6141dc0b6" + } + }, + "raw.xz": { + "disk": { + "location": "https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/33.20210412.3.0/x86_64/fedora-coreos-33.20210412.3.0-metal.x86_64.raw.xz", + "signature": "https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/33.20210412.3.0/x86_64/fedora-coreos-33.20210412.3.0-metal.x86_64.raw.xz.sig", + "sha256": "6d18380dad77b8670767bb082bb6f55ae4381b2b1d4a7405d8a9cdb6e6678263", + "uncompressed-sha256": "c8335d11257d33f7c68ce9720fd35ce0dfd008695348b58c7882d504eed974ed" + } + } + } + }, + "nutanix": { + "release": "33.20210412.3.0", + "formats": { + "qcow2": { + "disk": { + "location": "https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/33.20210412.3.0/x86_64/fedora-coreos-33.20210412.3.0-nutanix.x86_64.qcow2", + "signature": "https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/33.20210412.3.0/x86_64/fedora-coreos-33.20210412.3.0-nutanix.x86_64.qcow2.sig", + "sha256": "650bb496c94c3fc815126daaa6beb2270ae870cb036df5b43c348da00e788dab" + } + } + } + }, + "openstack": { + "release": "33.20210412.3.0", + "formats": { + "qcow2.xz": { + "disk": { + "location": "https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/33.20210412.3.0/x86_64/fedora-coreos-33.20210412.3.0-openstack.x86_64.qcow2.xz", + "signature": "https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/33.20210412.3.0/x86_64/fedora-coreos-33.20210412.3.0-openstack.x86_64.qcow2.xz.sig", + "sha256": "2270ae870cb036d650bb496c94c3fc815126daaa6bebf5b43c348da00e788dab", + "uncompressed-sha256": "5c7e9e072ed6adc4f70ee78deaf5bde76426afcc35f620dad31d8b3eb697e16d" + } + } + } + }, + "oraclecloud": { + "release": "33.20210412.3.0", + "formats": { + "qcow2.xz": { + "disk": { + "location": "https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/33.20210412.3.0/x86_64/fedora-coreos-33.20210412.3.0-oraclecloud.x86_64.qcow2.xz", + "signature": "https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/33.20210412.3.0/x86_64/fedora-coreos-33.20210412.3.0-oraclecloud.x86_64.qcow2.xz.sig", + "sha256": "868da197ae9179aded982ea6445d7d5e30acf8d03cdcdc32acfe2003d2c65491", + "uncompressed-sha256": "75a5c30bf84a605cc9fa617e856d9523d8d4c50607837a7d33e4d81e9809891a" + } + } + } + }, + "proxmoxve": { + "release": "33.20210412.3.0", + "formats": { + "qcow2.xz": { + "disk": { + "location": "https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/33.20210412.3.0/x86_64/fedora-coreos-33.20210412.3.0-proxmoxve.x86_64.qcow2.xz", + "signature": "https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/33.20210412.3.0/x86_64/fedora-coreos-33.20210412.3.0-proxmoxve.x86_64.qcow2.xz.sig", + "sha256": "394cd6431b19c82a46a7215ebead15960faf9814092203456d56960a1b4d8777" + } + } + } + }, + "qemu": { + "release": "33.20210412.3.0", + "formats": { + "qcow2.xz": { + "disk": { + "location": "https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/33.20210412.3.0/x86_64/fedora-coreos-33.20210412.3.0-qemu.x86_64.qcow2.xz", + "signature": "https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/33.20210412.3.0/x86_64/fedora-coreos-33.20210412.3.0-qemu.x86_64.qcow2.xz.sig", + "sha256": "8dce159f743c777fe9c429648e8a16928b55d0c1bc8e599a82ba71870fdc5e5a", + "uncompressed-sha256": "a21be448bb0ceee7a373cae232c4cadd979c3db844521d3c10888e42c405c684" + } + } + } + }, + "qemu-secex": { + "release": "33.20210412.3.0", + "formats": { + "qcow2.xz": { + "disk": { + "location": "https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/33.20210412.3.0/x86_64/fedora-coreos-33.20210412.3.0-qemu-secex.x86_64.qcow2.xz", + "signature": "https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/33.20210412.3.0/x86_64/fedora-coreos-33.20210412.3.0-qemu-secex.x86_64.qcow2.xz.sig", + "sha256": "2afbb0ac4a19f58a55db35db0a690d488f065664e9bcba1b802966f0ae6aad57", + "uncompressed-sha256": "2b1cb667f3468ef7b462e5ec8395fcd2982e424d1727336e95f74c611d8bbd53" + } + } + } + }, + "virtualbox": { + "release": "33.20210412.3.0", + "formats": { + "ova": { + "disk": { + "location": "https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/33.20210412.3.0/x86_64/fedora-coreos-33.20210412.3.0-virtualbox.x86_64.ova", + "signature": "https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/33.20210412.3.0/x86_64/fedora-coreos-33.20210412.3.0-virtualbox.x86_64.ova.sig", + "sha256": "a54f52901817165c74b9d265d8ccf0a6c622006e2a13444fc1145970b8c9135d" + } + } + } + }, + "vmware": { + "release": "33.20210412.3.0", + "formats": { + "ova": { + "disk": { + "location": "https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/33.20210412.3.0/x86_64/fedora-coreos-33.20210412.3.0-vmware.x86_64.ova", + "signature": "https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/33.20210412.3.0/x86_64/fedora-coreos-33.20210412.3.0-vmware.x86_64.ova.sig", + "sha256": "0a6c622006e2a13444fc1145970b8a54f52901817165c74b9d265d8ccfc9135d" + } + } + } + }, + "vultr": { + "release": "33.20210412.3.0", + "formats": { + "raw.xz": { + "disk": { + "location": "https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/33.20210412.3.0/x86_64/fedora-coreos-33.20210412.3.0-vultr.x86_64.raw.xz", + "signature": "https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/33.20210412.3.0/x86_64/fedora-coreos-33.20210412.3.0-vultr.x86_64.raw.xz.sig", + "sha256": "6c6a42c8399881e1ecb0ba088b389b4e20a394dacc3dab91f221fe18e5006557", + "uncompressed-sha256": "835f97b63f18031f0eb830ee8766c6be8fec1e52f689156e761a92cd3573f4bb" + } + } + } + } + }, + "images": { + "aws": { + "regions": { + "af-south-1": { + "release": "33.20210412.3.0", + "image": "ami-09d422b66ac91ab2a" + }, + "ap-east-1": { + "release": "33.20210412.3.0", + "image": "ami-05fdddb8ebfcdbbbd" + }, + "ap-northeast-1": { + "release": "33.20210412.3.0", + "image": "ami-0ecf122c9a4ec0c2f" + }, + "ap-northeast-2": { + "release": "33.20210412.3.0", + "image": "ami-08fd2b5b39b93b5ff" + }, + "ap-northeast-3": { + "release": "33.20210412.3.0", + "image": "ami-023a068f639e4d9dc" + }, + "ap-south-1": { + "release": "33.20210412.3.0", + "image": "ami-0bc108bb69dab2855" + }, + "ap-southeast-1": { + "release": "33.20210412.3.0", + "image": "ami-025fce39a4b9582a8" + }, + "ap-southeast-2": { + "release": "33.20210412.3.0", + "image": "ami-09186d20538071e92" + }, + "ca-central-1": { + "release": "33.20210412.3.0", + "image": "ami-0a186cd7e55176be2" + }, + "eu-central-1": { + "release": "33.20210412.3.0", + "image": "ami-06a0c31e4cba0c54d" + }, + "eu-north-1": { + "release": "33.20210412.3.0", + "image": "ami-01f6afff2c77bc11c" + }, + "eu-south-1": { + "release": "33.20210412.3.0", + "image": "ami-083a448ad9aff02c2" + }, + "eu-west-1": { + "release": "33.20210412.3.0", + "image": "ami-05b16c9ca91b37d57" + }, + "eu-west-2": { + "release": "33.20210412.3.0", + "image": "ami-0a5a690659a4e53bb" + }, + "eu-west-3": { + "release": "33.20210412.3.0", + "image": "ami-0ca82f640eae28513" + }, + "me-south-1": { + "release": "33.20210412.3.0", + "image": "ami-0f4a9bb1ea0c84082" + }, + "sa-east-1": { + "release": "33.20210412.3.0", + "image": "ami-0194168b04da77dfa" + }, + "us-east-1": { + "release": "33.20210412.3.0", + "image": "ami-09e2e5104f310ffb5" + }, + "us-east-2": { + "release": "33.20210412.3.0", + "image": "ami-02e593ebdf420390c" + }, + "us-west-1": { + "release": "33.20210412.3.0", + "image": "ami-0cb601c6edd617238" + }, + "us-west-2": { + "release": "33.20210412.3.0", + "image": "ami-0fcfe7120a4492fb9" + } + } + }, + "gcp": { + "release": "33.20210412.3.0", + "project": "fedora-coreos-cloud", + "family": "fedora-coreos-stable", + "name": "fedora-coreos-33-20210412-3-0-gcp-x86-64" + } + } + } + } +} diff --git a/metadata/updates/fcos-updates-schema.json b/metadata/updates/fcos-updates-schema.json new file mode 100644 index 0000000..d7d23f3 --- /dev/null +++ b/metadata/updates/fcos-updates-schema.json @@ -0,0 +1,116 @@ +{ + "definitions": {}, + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "title": "updates", + "description": "FCOS updates metadata JSON document.", + "required": [ + "releases", + "metadata", + "stream" + ], + "properties": { + "releases": { + "type": "array", + "description": "Each entry MUST have a unique non-empty version field.", + "items": { + "type": "object", + "description": "Release entry.", + "required": [ + "version", + "metadata" + ], + "properties": { + "version": { + "type": "string", + "title": "release version", + "description": "Release version." + }, + "metadata": { + "type": "object", + "title": "release updates", + "description": "Per-release updates metadata.", + "properties": { + "barrier": { + "type": "object", + "title": "barrier", + "description": "Details on a release barrier.", + "properties": { + "reason": { + "type": "string", + "title": "barrier reason", + "description": "URL to a document with the reason for this barrier." + } + }, + "required": [ + "reason" + ] + }, + "deadend": { + "type": "object", + "title": "deadend", + "description": "Details on a release dead-end.", + "properties": { + "reason": { + "type": "string", + "title": "deadend reason", + "description": "URL to a document with the reason for this deadend." + } + }, + "required": [ + "reason" + ] + }, + "rollout": { + "type": "object", + "title": "rollout", + "description": "Details on a release rollout.", + "properties": { + "start_epoch": { + "type": "integer", + "title": "rollout start timestamp", + "description": "UNIX epoch timestamp for the start of this rollout. Default: 0.", + "default": 0 + }, + "start_percentage": { + "type": "number", + "title": "rollout starting percentage", + "description": "Starting point of this rollout, as decimal fraction ranging from 0.0 to 1.0. Default: 0.0.", + "default": 0.0, + "minimum": 0.0, + "maximum": 1.0 + }, + "duration_minutes": { + "type": "integer", + "title": "rollout duration", + "description": "Duration in minutes for the rollout to progress till reaching 100% completion. Default: 0 (i.e. no progress).", + "default": 0 + } + } + } + } + } + } + } + }, + "metadata": { + "type": "object", + "title": "document metadata", + "description": "Metadata for this JSON document.", + "required": [ + "last-modified" + ], + "properties": { + "last-modified": { + "type": "string", + "title": "last change timestamp", + "description": "UTC timestamp for the last change, in ISO 8601 format." + } + } + }, + "stream": { + "type": "string", + "description": "Name of the release stream." + } + } +} diff --git a/metadata/updates/sample.json b/metadata/updates/sample.json new file mode 100644 index 0000000..8673871 --- /dev/null +++ b/metadata/updates/sample.json @@ -0,0 +1,26 @@ +{ + "stream": "testing", + "metadata": { + "last-modified": "2019-09-10T13:49:17+00:00" + }, + "releases": [ + { + "version": "30.20190716.1", + "metadata": { + "deadend": { + "reason": "https://github.com/coreos/fedora-coreos-tracker/issues/215" + } + } + }, + { + "version": "30.20190905.0", + "metadata": { + "rollout": { + "start_epoch": 1568125800, + "start_percentage": 0.3, + "duration_minutes": 1440 + } + } + } + ] +} diff --git a/metadata/updates/specifications.md b/metadata/updates/specifications.md new file mode 100644 index 0000000..e9287e1 --- /dev/null +++ b/metadata/updates/specifications.md @@ -0,0 +1,24 @@ +# Updates metadata specifications + +The updates metadata is a JSON document with a single object containing the following fields: + +- `stream` (mandatory, string): name of the update stream. +- `metadata` (mandatory, object): metadata attributes for this JSON document. + - `last-modified` (mandatory, string): UTC timestamp for the last change, in ISO 8601 format. +- `releases` (mandatory, list of objects): per-release updates details. Each entry MUST have a unique non-empty `version` attribute. + - `version` (mandatory, string): release version identifier. + - `metadata` (mandatory, object): updates details. + - `barrier` (optional, object): if present, the corresponding release is marked as an update barrier. + - `reason` (mandatory, string): URL to a resource explaining the reason for this barrier. + - `deadend` (optional, object): if present, the corresponding release is marked as an update dead-end. + - `reason` (mandatory, string): URL to a resource explaining the reason for this dead-end. + - `rollout` (optional, object): if present, the corresponding release is marked as an in-progress update rollout. + - `start_epoch` (optional, signed integer): UNIX epoch timestamp for the start of this rollout. Default: `0`. + - `start_percentage` (optional, float): starting point of this rollout, as decimal fraction ranging from `0.0` to `1.0`. Default: `0.0`. + - `duration_minutes` (optional, unsigned integer): duration in minutes for the rollout to progress till reaching 100% completion. Default: `0` (i.e. no progress). + +# Glossary + +- **barrier**: a release which is a forced chokepoint for auto-updates. Releases older than a certain barrier must first update to it before proceding to more recent updates. +- **dead-end**: a release which cannot further auto-update. Manual intervention is required to update out of it. +- **rollout**: a release which can be used as a valid target for auto-updates. Multiple rollouts can exist and progress in parallel. diff --git a/metrics/README.md b/metrics/README.md new file mode 100644 index 0000000..24a4941 --- /dev/null +++ b/metrics/README.md @@ -0,0 +1,2 @@ + +See [README.md](../README.md#metrics). diff --git a/metrics/fcos-sqlitevis.json b/metrics/fcos-sqlitevis.json new file mode 100644 index 0000000..1c3c311 --- /dev/null +++ b/metrics/fcos-sqlitevis.json @@ -0,0 +1,711 @@ +{ + "version": 2, + "inquiries": [ + { + "id": "WUPD4gZdu-j4mFgxjHG0P", + "query": "SELECT os_variant FROM countme_totals \n WHERE weeknum = (SELECT MAX(weeknum) FROM countme_totals)\n AND os_variant REGEXP ''\n GROUP BY os_variant;", + "viewType": "chart", + "viewOptions": { + "data": [], + "layout": { + "autosize": true, + "xaxis": { + "range": [ + -1, + 6 + ], + "autorange": true + }, + "yaxis": { + "range": [ + -1, + 4 + ], + "autorange": true + } + }, + "frames": [] + }, + "name": "All OS Variants", + "createdAt": "2025-05-12T20:54:27.120Z" + }, + { + "id": "tcIRiJz5gn5ci4DJyHgqU", + "query": "SELECT date(julianday('1970-01-05')+weeknum*7 + 6) AS date, weeknum, os_variant, repo_arch, SUM(hits) FROM countme_totals \n WHERE os_variant IS 'coreos'\n AND repo_tag REGEXP 'updates-released-f[3-4][0-9]' \n AND weeknum = (SELECT MAX(weeknum) FROM countme_totals)\n GROUP BY repo_arch;", + "viewType": "chart", + "viewOptions": { + "data": [ + { + "type": "pie", + "mode": "markers", + "values": null, + "valuessrc": "SUM(hits)", + "meta": { + "columnNames": { + "values": "SUM(hits)", + "labels": "repo_arch", + "text": "" + } + }, + "labels": null, + "labelssrc": "repo_arch", + "opacity": 1, + "textinfo": "label+value+percent", + "textfont": { + "size": 26, + "family": "sans-serif" + }, + "hoverinfo": "percent+label+value", + "hoverlabel": { + "align": "auto" + }, + "direction": "counterclockwise", + "rotation": 0, + "hole": 0.52, + "pull": 0, + "marker": { + "line": { + "width": 1 + } + }, + "insidetextorientation": "radial" + } + ], + "layout": { + "xaxis": { + "range": [ + -1, + 6 + ], + "autorange": true + }, + "yaxis": { + "range": [ + -1, + 4 + ], + "autorange": true + }, + "autosize": true, + "mapbox": { + "style": "open-street-map" + }, + "title": { + "text": "Fedora CoreOS Node Architecture Breakdown Week of 2025-05-04", + "font": { + "size": 25 + } + }, + "hiddenlabels": [ + "ppc64le", + "s390x" + ], + "legend": { + "x": 0.7407924239291469, + "y": 0.8257272143643333, + "font": { + "size": 20 + }, + "yanchor": "middle" + }, + "annotations": [], + "meta": [ + "2023-10-08", + "2023-10-08", + "2023-10-08", + "2023-10-08" + ], + "metasrc": "date", + "extendpiecolors": true + }, + "frames": [] + }, + "name": "FCOS Architectures", + "createdAt": "2025-05-12T20:55:12.622Z" + }, + { + "id": "wEj338NrufIRE-3UBDXPK", + "query": "SELECT date(julianday('1970-01-05')+weeknum*7 + 6) AS date, weeknum, SUM(transient_hits), SUM(static_hits), SUM(transient_hits + static_hits) FROM (\n SELECT weeknum, SUM(hits) AS transient_hits, 0 AS static_hits FROM countme_totals WHERE os_variant IS 'coreos' AND repo_tag REGEXP 'updates-released-f[3-4][0-9]' AND sys_age = 1 GROUP BY weeknum\n UNION\n SELECT weeknum, 0 AS transient_hits, SUM(hits) AS static_hits FROM countme_totals WHERE os_variant IS 'coreos' AND repo_tag REGEXP 'updates-released-f[3-4][0-9]' AND sys_age > 1 GROUP BY weeknum\n) WHERE date > '2020-01-01' GROUP BY weeknum", + "viewType": "chart", + "viewOptions": { + "data": [ + { + "type": "scatter", + "mode": "lines", + "x": null, + "xsrc": "date", + "meta": { + "columnNames": { + "x": "date", + "y": "SUM(static_hits)" + } + }, + "y": null, + "ysrc": "SUM(static_hits)", + "stackgroup": 1, + "name": "Static Nodes", + "hoveron": "points" + }, + { + "type": "scatter", + "mode": "lines", + "x": null, + "xsrc": "date", + "meta": { + "columnNames": { + "x": "date", + "y": "SUM(transient_hits)" + } + }, + "y": null, + "ysrc": "SUM(transient_hits)", + "stackgroup": 1, + "name": "Transient Nodes", + "fillcolor": "rgba(205, 96, 52, 0.5)", + "line": { + "color": "rgb(180, 38, 5)" + } + }, + { + "type": "scatter", + "mode": "lines", + "x": null, + "xsrc": "date", + "meta": { + "columnNames": { + "x": "date", + "y": "SUM(transient_hits + static_hits)", + "text": "" + } + }, + "y": null, + "ysrc": "SUM(transient_hits + static_hits)", + "name": "Total Nodes", + "line": { + "width": 3, + "color": "rgb(95, 100, 96)" + }, + "hovertemplate": "", + "error_x": { + "_template": null, + "visible": false, + "type": "percent", + "symmetric": true, + "value": 10, + "color": "rgb(95, 100, 96)", + "thickness": 2, + "width": 4 + } + } + ], + "layout": { + "xaxis": { + "range": [ + "2021-09-19 23:38:29.3717", + "2025-05-22 01:49:05.1712" + ], + "autorange": false, + "rangeselector": { + "visible": false, + "buttons": [ + {} + ] + }, + "showspikes": false, + "rangeslider": { + "visible": false, + "yaxis": {}, + "autorange": true, + "range": [ + "2020-05-03", + "2023-11-28 23:10:02.9513" + ] + }, + "type": "date", + "tickfont": { + "size": 28 + }, + "title": { + "font": { + "size": 17 + } + } + }, + "yaxis": { + "range": [ + -1419.2166576673771, + 123989.902612791 + ], + "autorange": false, + "ticks": "", + "showspikes": false, + "showline": false, + "zeroline": true, + "type": "linear", + "tickfont": { + "size": 28 + } + }, + "autosize": true, + "mapbox": { + "style": "open-street-map" + }, + "dragmode": "pan", + "title": { + "text": "Fedora CoreOS Node Count", + "font": { + "size": 33 + } + }, + "legend": { + "font": { + "size": 28 + }, + "orientation": "h", + "x": 0.2471859552265083, + "y": 0.9623782823483056 + } + }, + "frames": [] + }, + "name": "FCOS Node Count", + "createdAt": "2025-05-12T20:55:20.874Z" + }, + { + "id": "rcnNNlpFRfhIaX27ownZa", + "query": "SELECT date(julianday('1970-01-05')+weeknum*7 + 6) AS date, upper(trim(repo_tag, 'updates-releaseed-')) as repo_tag, os_variant, SUM(hits) FROM countme_totals\n WHERE os_variant IS 'coreos'\n AND repo_tag REGEXP 'updates-released-f[3-4][0-9]'\n AND weeknum = (SELECT MAX(weeknum) FROM countme_totals)\n GROUP BY repo_tag;", + "viewType": "chart", + "viewOptions": { + "data": [ + { + "type": "pie", + "mode": "markers", + "values": null, + "valuessrc": "SUM(hits)", + "meta": { + "columnNames": { + "values": "SUM(hits)", + "labels": "repo_tag" + } + }, + "labels": null, + "labelssrc": "repo_tag", + "hole": 0.5, + "pull": 0, + "marker": { + "line": { + "width": 2 + } + }, + "textinfo": "label", + "textfont": { + "size": 25 + }, + "sort": false, + "direction": "clockwise", + "rotation": -90, + "legendgroup": 1, + "showlegend": true, + "hoverinfo": "percent+label+value", + "opacity": 1, + "textposition": "inside" + } + ], + "layout": { + "xaxis": { + "range": [ + -1, + 6 + ], + "autorange": true + }, + "yaxis": { + "range": [ + -1, + 4 + ], + "autorange": true + }, + "autosize": true, + "mapbox": { + "style": "open-street-map" + }, + "title": { + "text": "Fedora CoreOS Release Breakdown", + "x": 0.5, + "font": { + "size": 31 + } + }, + "showlegend": true, + "legend": { + "font": { + "family": "monospace", + "size": 22 + }, + "title": { + "text": "
", + "font": { + "size": 34 + } + }, + "y": 0.04329087951849141, + "x": 0.20084040421902638, + "yanchor": "bottom", + "orientation": "v" + }, + "hiddenlabels": [], + "hoverlabel": { + "align": "auto" + }, + "uniformtext": { + "mode": false + }, + "modebar": { + "orientation": "h" + }, + "margin": { + "pad": 0, + "r": 80 + }, + "extendpiecolors": true, + "piecolorway": [ + "#1b9e77", + "#d95f02", + "#7570b3", + "#e7298a", + "#66a61e", + "#e6ab02", + "#a6761d", + "#666666" + ] + }, + "frames": [] + }, + "name": "FCOS Release Breakdown", + "createdAt": "2025-05-12T20:55:31.761Z" + }, + { + "id": "BZlflOgPAYGoaKwjBpIe8", + "query": "SELECT date(julianday('1970-01-05')+weeknum*7 + 6) AS date, weeknum, SUM(coreos_hits), SUM(cloud_hits), SUM(server_hits) FROM (\n SELECT weeknum, 0 AS server_hits, 0 AS cloud_hits, SUM(hits) AS coreos_hits FROM countme_totals WHERE os_variant IS 'coreos' AND repo_tag REGEXP 'updates-released-f[3-4][0-9]' AND sys_age > 1 GROUP BY weeknum\n UNION\n SELECT weeknum, 0 AS server_hits, SUM(hits) AS cloud_hits, 0 AS coreos_hits FROM countme_totals WHERE os_variant IS 'cloud' AND repo_tag REGEXP 'updates-released-f[3-4][0-9]' AND sys_age > 1 GROUP BY weeknum\n UNION\n SELECT weeknum, SUM(hits) AS server_hits, 0 AS cloud_hits, 0 AS coreos_hits FROM countme_totals WHERE os_variant IS 'server' AND repo_tag REGEXP 'updates-released-f[3-4][0-9]' AND sys_age > 1 GROUP BY weeknum\n) WHERE date > '2022-01-01' GROUP BY weeknum", + "viewType": "chart", + "viewOptions": { + "data": [ + { + "type": "scatter", + "mode": "lines", + "stackgroup": null, + "x": null, + "xsrc": "date", + "meta": { + "columnNames": { + "x": "date", + "y": "SUM(cloud_hits)" + } + }, + "y": null, + "ysrc": "SUM(cloud_hits)", + "name": "Cloud", + "line": { + "width": 5 + } + }, + { + "type": "scatter", + "mode": "lines", + "x": null, + "xsrc": "date", + "meta": { + "columnNames": { + "x": "date", + "y": "SUM(coreos_hits)" + } + }, + "y": null, + "ysrc": "SUM(coreos_hits)", + "name": "CoreOS", + "line": { + "width": 5 + } + }, + { + "type": "scatter", + "mode": "lines", + "stackgroup": null, + "x": null, + "xsrc": "date", + "meta": { + "columnNames": { + "x": "date", + "y": "SUM(server_hits)" + } + }, + "y": null, + "ysrc": "SUM(server_hits)", + "name": "Server", + "line": { + "width": 5 + } + } + ], + "layout": { + "xaxis": { + "range": [ + "2023-05-18 21:13:31.5607", + "2025-05-04" + ], + "autorange": false, + "type": "date", + "tickfont": { + "size": 22 + } + }, + "yaxis": { + "range": [ + -4149.444444444446, + 85743.15981948335 + ], + "autorange": false, + "type": "linear", + "tickfont": { + "size": 22 + } + }, + "autosize": true, + "mapbox": { + "style": "open-street-map" + }, + "title": { + "text": "Static Node Count for Fedora Cloud/CoreOS/Server" + }, + "dragmode": "zoom", + "legend": { + "font": { + "size": 28 + }, + "orientation": "h", + "x": 0.4185161699429296, + "y": 0.988780487804878 + } + }, + "frames": [] + }, + "name": "Static Node Count By Edition", + "createdAt": "2025-05-12T20:56:19.303Z" + }, + { + "id": "r6KJ-g1sxjbqtOYuWRJoK", + "query": "SELECT date(julianday('1970-01-05')+weeknum*7 + 6) AS date, weeknum, SUM(coreos_hits), SUM(cloud_hits), SUM(server_hits) FROM (\n SELECT weeknum, 0 AS server_hits, 0 AS cloud_hits, SUM(hits) AS coreos_hits FROM countme_totals WHERE os_variant IS 'coreos' AND repo_tag REGEXP 'updates-released-f[3-4][0-9]' AND sys_age = 1 GROUP BY weeknum\n UNION\n SELECT weeknum, 0 AS server_hits, SUM(hits) AS cloud_hits, 0 AS coreos_hits FROM countme_totals WHERE os_variant IS 'cloud' AND repo_tag REGEXP 'updates-released-f[3-4][0-9]' AND sys_age = 1 GROUP BY weeknum\n UNION\n SELECT weeknum, SUM(hits) AS server_hits, 0 AS cloud_hits, 0 AS coreos_hits FROM countme_totals WHERE os_variant IS 'server' AND repo_tag REGEXP 'updates-released-f[3-4][0-9]' AND sys_age = 1 GROUP BY weeknum\n) WHERE date > '2022-01-01' GROUP BY weeknum", + "viewType": "chart", + "viewOptions": { + "data": [ + { + "type": "scatter", + "mode": "lines", + "meta": { + "columnNames": { + "x": "date", + "y": "SUM(cloud_hits)" + } + }, + "x": null, + "xsrc": "date", + "name": "Cloud", + "y": null, + "ysrc": "SUM(cloud_hits)", + "line": { + "width": 5 + } + }, + { + "type": "scatter", + "mode": "lines", + "meta": { + "columnNames": { + "x": "date", + "y": "SUM(coreos_hits)" + } + }, + "x": null, + "xsrc": "date", + "y": null, + "ysrc": "SUM(coreos_hits)", + "name": "CoreOS", + "line": { + "width": 5 + } + }, + { + "type": "scatter", + "mode": "lines", + "stackgroup": null, + "meta": { + "columnNames": { + "x": "date", + "y": "SUM(server_hits)" + } + }, + "y": null, + "ysrc": "SUM(server_hits)", + "x": null, + "xsrc": "date", + "name": "Server", + "line": { + "width": 5 + } + } + ], + "layout": { + "xaxis": { + "range": [ + "2023-05-14 20:40:13.8728", + "2025-05-04" + ], + "autorange": false, + "type": "date", + "tickfont": { + "size": 22 + } + }, + "yaxis": { + "range": [ + -7660.833333333334, + 155839.15818339647 + ], + "autorange": false, + "type": "linear", + "tickfont": { + "size": 22 + } + }, + "autosize": true, + "mapbox": { + "style": "open-street-map" + }, + "title": { + "text": "Transient Node Count for Fedora Cloud/CoreOS/Server" + }, + "dragmode": "zoom", + "legend": { + "font": { + "size": 28 + }, + "orientation": "h", + "x": 0.388712745719721, + "y": 1.0030674846625767 + } + }, + "frames": [] + }, + "name": "Transient Node Count By Edition", + "createdAt": "2025-05-12T20:56:34.411Z" + }, + { + "id": "8C93FoFqg3Zpw4wcxyS2e", + "query": "SELECT date(julianday('1970-01-05')+weeknum*7 + 6) AS date, weeknum, SUM(coreos_hits), SUM(cloud_hits), SUM(server_hits) FROM (\n SELECT weeknum, 0 AS server_hits, 0 AS cloud_hits, SUM(hits) AS coreos_hits FROM countme_totals WHERE os_variant IS 'coreos' AND repo_tag REGEXP 'updates-released-f[3-4][0-9]' GROUP BY weeknum\n UNION\n SELECT weeknum, 0 AS server_hits, SUM(hits) AS cloud_hits, 0 AS coreos_hits FROM countme_totals WHERE os_variant IS 'cloud' AND repo_tag REGEXP 'updates-released-f[3-4][0-9]' GROUP BY weeknum\n UNION\n SELECT weeknum, SUM(hits) AS server_hits, 0 AS cloud_hits, 0 AS coreos_hits FROM countme_totals WHERE os_variant IS 'server' AND repo_tag REGEXP 'updates-released-f[3-4][0-9]' GROUP BY weeknum\n) WHERE date > '2022-01-01' GROUP BY weeknum", + "viewType": "chart", + "viewOptions": { + "data": [ + { + "type": "scatter", + "mode": "lines", + "x": null, + "xsrc": "date", + "meta": { + "columnNames": { + "x": "date", + "y": "SUM(cloud_hits)" + } + }, + "y": null, + "ysrc": "SUM(cloud_hits)", + "name": "Cloud", + "line": { + "width": 5 + } + }, + { + "type": "scatter", + "mode": "lines", + "stackgroup": null, + "x": null, + "xsrc": "date", + "meta": { + "columnNames": { + "x": "date", + "y": "SUM(coreos_hits)" + } + }, + "y": null, + "ysrc": "SUM(coreos_hits)", + "name": "CoreOS", + "line": { + "width": 5 + } + }, + { + "type": "scatter", + "mode": "lines", + "stackgroup": null, + "x": null, + "xsrc": "date", + "meta": { + "columnNames": { + "x": "date", + "y": "SUM(server_hits)" + } + }, + "y": null, + "ysrc": "SUM(server_hits)", + "name": "Server", + "line": { + "width": 5 + } + } + ], + "layout": { + "xaxis": { + "range": [ + "2023-05-17 21:05:12.1387", + "2025-05-04" + ], + "autorange": false, + "type": "date", + "tickfont": { + "size": 22 + } + }, + "yaxis": { + "range": [ + -10802.38888888889, + 229205.70535714284 + ], + "autorange": false, + "type": "linear", + "tickfont": { + "size": 22 + } + }, + "autosize": true, + "mapbox": { + "style": "open-street-map" + }, + "title": { + "text": "Total Node Count for Fedora Cloud/CoreOS/Server" + }, + "legend": { + "orientation": "h", + "x": 0.4578313253012048, + "y": 0.9863986313088109, + "font": { + "size": 28 + } + } + }, + "frames": [] + }, + "name": "Total Node Count for Fedora Cloud/CoreOS/Server", + "createdAt": "2025-05-12T20:56:53.783Z" + } + ] +} \ No newline at end of file diff --git a/stream-tooling.md b/stream-tooling.md new file mode 100644 index 0000000..f8455b8 --- /dev/null +++ b/stream-tooling.md @@ -0,0 +1,86 @@ +# Stream tooling + +## Introduction + +FCOS will have multiple streams: + +| Type | Name (SCM branch and ostree ref) | ostree repo | +| -- | -- | -- | +| Production | next | prod | +| Production | testing | prod | +| Production | stable | prod | +| Development | testing-devel | annex | +| Development | next-devel | annex | +| Mechanical | rawhide | annex | +| Mechanical | branched | annex | + +Development and mechanical streams are subject to change. + +We need a way to both (1) fix the content set for a particular stream release, and (2) integrate new content into development streams. + +## Current tools at our disposal +- git +- rpm-ostree treefiles: manifest fed to rpm-ostree that contains the list of packages to use during a compose. [Example](https://github.com/coreos/fedora-coreos-config/blob/main/fedora-coreos-base.yaml). +- rpm-ostree treefile locks: [pending rpm-ostree patch]( https://github.com/projectatomic/rpm-ostree/pull/1745) adding "lockfile" functionality similar to Cargo.lock/Gopkg.lock. This essentially means that the rpm-ostree compose is guaranteed to use specific package versions (or fail) as described in the lockfile. (To be clear, all of the below could probably be done without a lock file, since the treefile supports fully specifying the NEVRA, but having a separate lockfile allows for more sophisticated tooling and a cleaner treefile.) +- Koji tags: a way to track packages built in Koji. Koji is capable of creating yum repos from such tags. RPM builds may be "tagged" in so that the next repo regeneration includes it. +- [dist-git](http://src.fedoraproject.org/): git where RPM spec files are kept and Koji builds source from. + +## Proposal + +**Mechanical** streams are not curated; they're automated nightly snapshots of the underlying repos. They source their RPMs from the regular Fedora repos (using 30 here to mean `$currentrelease`): +1. **rawhide** <- f32 +2. **branched** <- f31 when a branch exists, otherwise tracks **rawhide** + +**Production** streams are intended for production use. They source their RPMs from a _single_ Koji tag, `coreos-pool`, from which we create a yum repo: +1. **next** <- coreos-pool +2. **testing** <- coreos-pool +3. **stable** <- coreos-pool + +**Development** streams are nightly snapshots of content headed for the production streams. There's one development stream at the base of each promotion path; thus, **stable** doesn't have one because it promotes from **testing** instead. **next-devel** will only be maintained in the periods where **next** is independent of **testing**. Development streams source their RPMs from a _single_ Koji tag, `coreos-pool`, from which we create a yum repo: +1. **next-devel** <- coreos-pool +2. **testing-devel** <- coreos-pool + +The Koji tag ensures that (1) packages are not automatically garbage collected, (2) stream builds are reproducible (up to the GC retention policy we agree upon), and (3) packages are added to the pool (and thus into the production streams) in a controlled manner. + +There is also a second Koji tag, `coreos-release`, for packages which have been included in a production build. Packages in `coreos-release` have a longer TTL than `coreos-pool`, increasing the time that official builds can be reproduced by others. + +### How will the package list be maintained? + +We maintain a git repository containing the rpm-ostree treefile and lockfiles. This could be [fedora-coreos-config](https://github.com/coreos/fedora-coreos-config). We have one branch for each stream, and no main branch. + +For the mechanical streams, a nightly job will run the compose from the corresponding yum repos and SCM refs. This job will output a lockfile for each CPU architecture. Those lockfiles will be committed to Git to preserve a record of the build's contents, and the builds will be pushed to the corresponding ostree refs. The branched lockfile will also be PR'd to the {testing-devel, next-devel} branch, the latter only during the part of the cycle where next-devel is maintained. We want to keep the development branches ready to release, so those PRs are not merged unless green. + +The lockfiles produced from the automatic snapshot will never be hand-modified, and in the next/testing/stable branches will never be modified at all except during promotions. Instead, pins (to older NEVRAs) and updates (to newer ones) will be hand-maintained in the Git branches in a separate lockfile that overrides the autogenerated ones. These overrides will be the major distinction between the mechanical refs and the "curated" (development/production) refs. Each curated branch will have one override file, which can carry both CPU-architecture-independent and architecture-specific overrides. + +### How will releases happen? + +When it's time to cut e.g. a promoted testing release, we push a merge commit to the testing branch which takes the testing-devel branch's tree in entirety. (That is, we use the Git "theirs" merge strategy, which, helpfully, doesn't exist.) We then tag the Git commit on the testing branch and do an official build and CI run. In the absence of flakes (ha!) this will pass because the commit is known to be green. If the build is bad, we abandon the release and iterate. Otherwise, we proceed with releasing artifacts. + +If we need to update an existing testing release, there's no need for another merge commit; we just commit changes to the testing branch and tag the release from there. + +### How do packages get added to the koji tags? + +When a lockfile update is merged, this triggers a process which watches for pushes to the curated branches, and adds all the builds from the updated lockfile to `coreos-pool`. + +During production builds, the pipeline tags packages from the lockfile into `coreos-release`. + +### Adding/removing packages to the OS + +Update the development treefile as usual. On the next bot push, the lockfile will be updated to include that package entry. + +To focus development effort, there will be one base treefile shared across all branches, whose canonical copy will live in the testing-devel branch. Changes will automatically be mirrored to next-devel and to the mechanical branches. To address divergence across Fedora releases, each branch will also have an overlay treefile (possibly empty): + +- **testing-devel** +- **next-devel** -> automatically mirrored to branched +- **rawhide** + +### Dealing with backports + +There are two cases: +1. Backporting an already built Fedora package into a prod release: + - We bump the override file entry for that specific package + - The package automatically gets koji-tagged on push +2. Backporting a patch which isn't in a Fedora package (or the package was already updated too far): + - We build the RPM from a dist-git branch + - We add the RPM to the koji tag (though the build target destination tag could already be set to remove this manual tagging step) + - We bump the override file entry for that specific package