docs: restructure Kola README for clarity and completeness #629
Conversation
John15321
changed the title
John15321
force-pushed
the
refactor-kola-readme
branch
from
778bbc7 to
ab87592
Compare
John15321
moved this to ✅ Testing / in Review
in Flatcar tactical, release planning, and roadmap
github-project-automation
bot
moved this from ✅ Testing / in Review
to ⚒️ In Progress
in Flatcar tactical, release planning, and roadmap
kola/README.md
Outdated
| - Linux operating system | ||
| - SSH client and server | ||
| - **Sudo access for QEMU testing** (or use `qemu-unpriv` for single-node tests) | ||
| - Go 1.19+ for building from source |
There was a problem hiding this comment.
Let's change the version to 1.23 here.
kola/README.md
Outdated
| ./build kola | ||
|
|
||
| # Check Go version | ||
| go version # Should be 1.19+ |
kola/README.md
Outdated
|
|
||
| ### AWS | ||
| ```bash | ||
| # Set up credentials |
There was a problem hiding this comment.
I would suggest this one as the recommended way
| cluster.AssertCmdOutputContains(machine, "command", "expected") | ||
| ``` | ||
|
|
||
| **Implementation Details:** |
There was a problem hiding this comment.
I did not understand this. Can you elaborate here?
There was a problem hiding this comment.
Its about letting the person know how SSH works when tests are run in various environments etc. What about this description now?
Co-authored-by: Sayan Chowdhury <[email protected]>
Co-authored-by: Sayan Chowdhury <[email protected]>
There was a problem hiding this comment.
Thanks for this. Overall it looks good and it is nice to have this documentation. Some additional notes:
- we should maintain only one Kola documentation, let's merge this one: https://github.com/flatcar/mantle?tab=readme-ov-file#kola in the file you just created
- I gave an introduction to test writing a few years ago: https://archive.fosdem.org/2022/schedule/event/overview_of_flatcar_container_linux_test_framework/ it can be referenced in the README (with a warning that some parts might be outdated)
|
|
||
| # Run your specific test | ||
| sudo ./bin/kola run -p qemu \ | ||
| --qemu-image ./flatcar_production_qemu_image.img \ |
There was a problem hiding this comment.
I am not sure this will actually work. We need to provide some additional flags:
--qemu-firmware /home/tormath1/flatcar/flatcar_production_qemu_uefi_efi_code.qcow2 --qemu-ovmf-vars /home/tormath1/flatcar/flatcar_production_qemu_uefi_efi_vars.qcow2
This will just fail with:
qemu: could not load PC BIOS ...bios-256k.bin
There was a problem hiding this comment.
Are you working on WSL?
There was a problem hiding this comment.
No, I work from a Linux machine.
There was a problem hiding this comment.
I'm not sure, but I think Kola is hardcoded to look for bios-256k.bin in the current directory, which is annoying. I've had to symlink it there. QEMU generally knows where to find it and will use it by default, so I think the Kola default should be to just assume it will work.
There was a problem hiding this comment.
Yeah, I just took the habit of using the firmware that we ship, like described here: https://github.com/flatcar/mantle?tab=readme-ov-file#run-tests-for-amd64 or like we do in the vendor-testing: https://github.com/flatcar/scripts/blob/main/ci-automation/vendor-testing/qemu.sh#L83 (I find explicit flags less prone to error)
There was a problem hiding this comment.
Sure, you should always specify it for UEFI because we do interesting things with that firmware, but we never touch SeaBIOS.
Co-authored-by: Mathieu Tortuyaux <[email protected]>
Co-authored-by: Mathieu Tortuyaux <[email protected]>
I agree. Lets do that after everyone is happy with the new readme. Also what do you think about refreshing the other readmes? such that the main readme only has link to the subdirectories with their respective readmes? |
Yes, looks good in follow-up PRs. Let's first ingest some of this content like you already did: https://github.com/flatcar/mantle?tab=readme-ov-file#kola-run |
…r cloud platforms
This pull request updates the
kola/README.mdfile to significantly enhance its structure and content, making it more comprehensive and user-friendly for contributors. The changes focus on improving the documentation for the Kola testing framework, providing detailed guidance for test writers and maintainers, and introducing a new section on adding test packages.Part of: flatcar/Flatcar#651