Add doc for booting in a VM #22

adriannemora · 2019-12-24T22:01:24Z

This guide provides easy, step-by-step instructions to produce a basic Ignition file and use it to launch a Fedora CoreOS VM with QEMU.

Conan-Kudo · 2019-12-25T01:22:49Z

@adriannemora It looks like your Git configuration isn't set up correctly for automatically setting the correct authorship for commits.

In addition, while the pull request has a good title and description, the commit itself only says "WIP". It'd be great to have a proper title and commit description. Here's some good guidelines for commit messages.

The steps below will help you set things right:

$ cd /path/to/fedora-coreos-docs
$ git config --global user.name "Your Name"
$ git config --global user.email "yname@example.com"
$ git commit --amend --reset-author
$ git push --force

modules/ROOT/pages/installing-on-VM.adoc

- Add new page for VM boot instructions. - Link VM boot instructions page on the current "Getting started" page. - Create new page for running containers, to be linked to from all other instructions.

- Add content from running-containers.adoc to fcct-config.adoc - Modify getting-started.adoc to add instructions for launching VMs with QEMU - Move instructions for producing Ignition files to a new page (producing-ign.adoc) - Move sysctl.adoc content to fcct-config.adoc. Edits: - Add note about relative paths in QEMU section of getting-started.adoc based on Neal Gompa's advice. - Multiple edits for organization, clarity, and conciseness.

modules/ROOT/pages/fcct-config.adoc

modules/ROOT/pages/getting-started.adoc

modules/ROOT/pages/producing-ign.adoc

modules/ROOT/pages/getting-started.adoc

modules/ROOT/pages/producing-ign.adoc

dustymabe · 2020-01-09T21:23:36Z

I just stumbled upon this. Thanks @adriannemora! Should I let you do another update before digging in?

adriannemora · 2020-01-09T23:45:10Z

@dustymabe I'm working on it now. By tomorrow, you can dive in to the next PR. Thank you!

Done: - Restore running-containers.adoc and sysctl.adoc - Minor edits to pages to wrap up this PR. To do in future PRs: - Expand fcct-config.adoc - Show contents of example.ign in producing-ign.adoc - Replace fcct binary instructions with containerized workflow in producing-ign.adoc

* Modify nav.adoc with new pages * Add Ignition configuration pages * Add instructions for a bare metal install. * Add instructions for using fcct * Edits for organization and consistency of formatting/language

modules/ROOT/pages/getting-started.adoc

modules/ROOT/pages/ign-passwd.adoc

modules/ROOT/pages/ign-config-metadata.adoc

miabbott · 2020-01-14T15:10:55Z

modules/ROOT/pages/bare-metal.adoc

+. From the boot menu, press `<TAB>` (isolinux) or `e` (grub) to edit the kernel command line.
+. Add the following parameters to the kernel command line:
+* `coreos.inst.install_dev=/dev/sda`
+* `coreos.inst.stream=testing`


Probably want to change this to stable

miabbott · 2020-01-14T15:14:20Z

modules/ROOT/pages/bare-metal.adoc

+* `coreos.inst.install_dev=/dev/sda`
+* `coreos.inst.stream=testing`
+* `coreos.inst.ignition_url=http://example.com/config.ign`
+* `coreos.inst.platform_id=qemu`


If users are truly installing to bare metal, I think this should be coreos.inst.platform_id=metal

If users are testing ISO install in a VM, then qemu should be used.

I think both cases should be metal - qemu means that we're fetching Ignition from the fw_cfg, but we aren't doing that here.

coreos.inst.platform_id is kind of an obscure option. Unless the user is running the installer to install into a VM, which is an unusual case, it's not needed at all.

@bgilbert I.e. we should be able to drop this line entirely and let it default to metal, right?

miabbott · 2020-01-14T15:32:21Z

modules/ROOT/pages/bare-metal.adoc

+PROMPT 0
+LABEL pxeboot
+    KERNEL fedora-coreos-30.20191014.1-live-kernel-x86_64
+    APPEND ip=dhcp rd.neednet=1 initrd=fedora-coreos-30.20191014.1-live-initramfs.x86_64.img console=tty0 console=ttyS0 coreos.inst.install_dev=/dev/sda coreos.inst.stream=testing coreos.inst.ignition_url=http://192.168.1.101:8000/config.ign


Change the stream to stable

miabbott · 2020-01-14T15:35:42Z

modules/ROOT/pages/fcct-config.adoc

+Ignition configurations are formatted as JSON, which is quick and easy for a machine to read. However, these files are not easy for humans to read or write. The solution is a two-step configuration process that is friendly for both humans and machines:
+
+. Produce a YAML-formatted Fedora CoreOS Configuration (FCC) file.
+. Run the Fedora CoreOS Configuration Transpiler (`fcct`) to convert the YAML file into a JSON Ignition file.


Maybe link to the fcct repo here?

https://github.com/coreos/fcct

miabbott · 2020-01-14T15:36:46Z

modules/ROOT/pages/using-fcct.adoc

@@ -0,0 +1,38 @@
+:experimental:
+
+= Fedora CoreOS Configuration Transpiler (`fcct`)


Or link to the fcct repo on this page somewhere?

https://github.com/coreos/fcct

miabbott

This is an awesome improvement from where we were. Thank you so much @adriannemora for the hard work.

There are a few nits remaining, but I think overall this is good to go.

dustymabe

Nice work. A few comments!

dustymabe · 2020-01-14T16:15:16Z

modules/ROOT/nav.adoc

 * Reference pages
-** xref:platforms.adoc[Platforms]


I may have missed it, but why are we commenting this out?

dustymabe · 2020-01-14T16:22:33Z

modules/ROOT/pages/bare-metal.adoc

+
+. Download an ISO image from the https://getfedora.org/coreos/download/[FCOS download page].
+
+NOTE: You can install in either legacy boot (BIOS) mode or in UEFI mode, regardless of what mode the OS will use once installed.


Seems like this needs a bit of clarification. How about we move it under Burn the ISO to disk and boot it. and make it something like:

NOTE: You can install in either legacy boot (BIOS) mode or in UEFI mode. The bare metal disk images will appropriately handle either case.

I guess we'd need to change the NOTE in the PXE section as well. In that case maybe we change the NOTE and move it up to before the numbered list starts?

dustymabe · 2020-01-14T16:38:16Z

modules/ROOT/pages/fcct-config.adoc

+
+* `variant`: specifies `fcos` as the operating system
+* `version`: specifies the version of `fcct`
+* `ignition`: specifies a remote configuration (for convenience or for platforms that do not allow for the ingestion of large configuration files)


I think this is slightly misleading. It's more than what you describe here. The spec just describes it as metadata about the configuration itself..

If we want to include more than just that then maybe we should make it something like metadata that tells ignition how to treat the data it has been given

or maybe we just ignore the merging/replace bit and just say allows for specification of remote configuration files

dustymabe · 2020-01-14T16:47:42Z

modules/ROOT/pages/ign-config-metadata.adoc

@@ -0,0 +1,63 @@
+:experimental:
+= Ignition metadata (`ignition`)
+The optional `ignition` block defines the metadata for the Ignition configuration. It allows you to specify a remote configuration file for platforms that do not allow the direct ingestion of large configuration files. It tells Ignition to start the first boot of FCOS, at which time, Ignition will fetch the specified Ignition file from a remote server.


I think there are some clarifications that can be made here. Proposed update:

The optional ignition block defines the metadata for the Ignition configuration. It allows you to specify a remote Ignition configuration file that can either be merged into the existing Ignition configuration or be used to completely replace the existing Ignition configuration for first boot. Remote fetching of an Ignition configuration is useful as a convenience or for platforms that do not allow the direct ingestion of large configuration files. On the first boot of FCOS Ignition will fetch the specified Ignition file(s) from a remote server and merge or replace depending on the supplied directives.

dustymabe · 2020-01-14T16:51:26Z

modules/ROOT/pages/fcct-config.adoc

+
+include::ign-passwd.adoc[leveloffset=1]
+
+// https://coreos.com/ignition/docs/latest/operator-notes.html


dustymabe · 2020-01-14T16:53:38Z

modules/ROOT/pages/getting-started.adoc

+
+. Ensure the correct ownership of the file:
+
+`chown core:kvm fedora-coreos-qemu.qcow2`


is this really needed?

dustymabe · 2020-01-14T16:56:56Z

modules/ROOT/pages/getting-started.adoc

-
-        [Install]
-        WantedBy=multi-user.target
+virt-install -n fcos --vcpus 2 -r 2048 --os-variant=fedora30 --import --network bridge=virbr0 --disk=/var/lib/libvirt/images/fedora-coreos-30.20190905.0-qemu.qcow2,format=qcow2,bus=virtio --noautoconsole --qemu-commandline="-fw_cfg name=opt/com.coreos/config,file=/path/to/example.ign"


can we break this one up to multiple lines with \ like we did for the qemu invocation above?

Also if we add --graphics=none and remove --noautoconsole then you'll get given a serial console by virt-install and your comment about Once the VM has finished booting, its IP addresses will appear on the serial console will be more appropriate.

dustymabe · 2020-01-14T16:58:29Z

modules/ROOT/pages/getting-started.adoc

-Note that when using docker instead of podman, units starting docker containers will need `Requires=docker.service` and `After=docker.service` to ensure the docker daemon is running before trying to start containers.
-
-=== Running etcd
+. You can then SSH into the FCOS VM as the `core` user:


Might want to add "Assuming the provided Ignition config defined an SSH public key to be used for the core user, you can then..."

dustymabe · 2020-01-14T17:05:07Z

modules/ROOT/pages/manual-rollbacks.adoc


-In order to temporarily boot into the previous OS deployment, hold down `Shift` during OS bootup and select the relevant OS entry in the bootloader menu.
-The default boot configuration is not affected by this action, and the next reboot will select again the updated OS.
+To temporarily boot the previous OS deployment, hold down `Shift` during the OS boot process. When the bootloader menus appears, select the relevant OS entry in the menu.


Is Shift consistent? I think you can press any key (I usually use arrow keys) to interrupt grub. I'll check this in a bit

dustymabe · 2020-01-14T17:05:37Z

Thanks @adriannemora - this is looking really good!

jlebon · 2020-01-14T18:28:28Z

modules/ROOT/pages/bare-metal.adoc

@@ -0,0 +1,53 @@
+:experimental:


What do these experimental markers mean? Is it e.g. some notice to say that FCOS is experimental? I think we can drop those now. :)

jlebon · 2020-01-14T18:30:05Z

modules/ROOT/pages/bare-metal.adoc

+* `coreos.inst.install_dev=/dev/sda`
+* `coreos.inst.stream=testing`
+* `coreos.inst.ignition_url=http://example.com/config.ign`
+* `coreos.inst.platform_id=qemu`


@bgilbert I.e. we should be able to drop this line entirely and let it default to metal, right?

jlebon · 2020-01-14T18:31:50Z

modules/ROOT/pages/bare-metal.adoc

+IPAPPEND 2
+----
+
+For more details on how to use this information, see the https://dustymabe.com/2019/01/04/easy-pxe-boot-testing-with-only-http-using-ipxe-and-libvirt/[instructions] for testing a PXE installation via a local VM and `libvirt`.


Maybe "see this blog post" instead to make it clear it's an external website?

jlebon · 2020-01-14T18:37:19Z

modules/ROOT/pages/getting-started.adoc

-
-        [Install]
-        WantedBy=multi-user.target
+virt-install -n fcos --vcpus 2 -r 2048 --os-variant=fedora30 --import --network bridge=virbr0 --disk=/var/lib/libvirt/images/fedora-coreos-30.20190905.0-qemu.qcow2,format=qcow2,bus=virtio --noautoconsole --qemu-commandline="-fw_cfg name=opt/com.coreos/config,file=/path/to/example.ign"


FWIW, fedora31 should be a valid --os-variant value nowadays :)

jlebon · 2020-01-14T18:41:21Z

modules/ROOT/pages/ign-systemd.adoc

+
+The `systemd` node contains one top-level node: a list of units. For each unit, the following options are available:
+
+* `name` (string, required, must be unique): the full name of the unit the form of `thing.service`.


in the form of?

jlebon · 2020-01-14T18:45:57Z

modules/ROOT/pages/producing-ign.adoc

+
+TIP: YAML files must have consistent indentation. Although `fcct` checks for syntax errors, ensure that the indentation matches the above example. Overall, the FCC files must conform to ``fcct``'s xref:fcct-config.adoc[schema].
+
+=== Using FCCT


Hmm, this section seems redundant with using-fcct.adoc -- we can just link to that doc it seems?

dustymabe · 2020-01-14T20:15:52Z

Should we "rebase and merge" this PR since it's a good start and address all code review comments in follow ups?

adriannemora · 2020-01-14T20:22:57Z

I'm all for it!

…

On Tue, Jan 14, 2020, 15:15 Dusty Mabe ***@***.***> wrote: Should we "rebase and merge" this PR since it's a good start and address all code review comments in follow ups? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#22?email_source=notifications&email_token=ANQIABEIQCNNVH5H4DHJYH3Q5YMPTA5CNFSM4J7A53YKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEI567PI#issuecomment-574353341>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ANQIABCXDAJVEHKUE2JNNSTQ5YMPTANCNFSM4J7A53YA> .

Done: - Restore running-containers.adoc and sysctl.adoc - Minor edits to pages to wrap up this PR. To do in future PRs: - Expand fcct-config.adoc - Show contents of example.ign in producing-ign.adoc - Replace fcct binary instructions with containerized workflow in producing-ign.adoc

jlebon · 2020-01-14T22:30:52Z

Follow-ups in #25 and #26!

Conan-Kudo suggested changes Dec 28, 2019

View reviewed changes

modules/ROOT/pages/installing-on-VM.adoc Outdated Show resolved Hide resolved

Add detailed instructions to boot FCOS in a VM (qemu)

8d97326

- Add new page for VM boot instructions. - Link VM boot instructions page on the current "Getting started" page. - Create new page for running containers, to be linked to from all other instructions.

adriannemora force-pushed the master branch from 83ad855 to 8d97326 Compare December 29, 2019 20:11

lucab reviewed Jan 6, 2020

View reviewed changes

adriannemora added 2 commits January 9, 2020 20:10

Update and add documentation for producing Ignition files

9858503

* Modify nav.adoc with new pages * Add Ignition configuration pages * Add instructions for a bare metal install. * Add instructions for using fcct * Edits for organization and consistency of formatting/language

miabbott reviewed Jan 13, 2020

View reviewed changes

modules/ROOT/pages/getting-started.adoc Outdated Show resolved Hide resolved

miabbott reviewed Jan 13, 2020

View reviewed changes

modules/ROOT/pages/getting-started.adoc Outdated Show resolved Hide resolved

miabbott reviewed Jan 13, 2020

View reviewed changes

modules/ROOT/pages/ign-passwd.adoc Outdated Show resolved Hide resolved

miabbott reviewed Jan 13, 2020

View reviewed changes

modules/ROOT/pages/ign-config-metadata.adoc Outdated Show resolved Hide resolved

miabbott mentioned this pull request Jan 13, 2020

errors/warnings get sent to compiled JSON when using fcct container coreos/butane#58

Closed

Fix a few typos.

74ee845

miabbott reviewed Jan 14, 2020

View reviewed changes

miabbott approved these changes Jan 14, 2020

View reviewed changes

dustymabe reviewed Jan 14, 2020

View reviewed changes

jlebon reviewed Jan 14, 2020

View reviewed changes

dustymabe merged commit 6932463 into coreos:master Jan 14, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add doc for booting in a VM #22

Add doc for booting in a VM #22

adriannemora commented Dec 24, 2019

Conan-Kudo commented Dec 25, 2019

dustymabe commented Jan 9, 2020

adriannemora commented Jan 9, 2020 •

edited

Loading

miabbott Jan 14, 2020

miabbott Jan 14, 2020

cgwalters Jan 14, 2020

bgilbert Jan 14, 2020

jlebon Jan 14, 2020

miabbott Jan 14, 2020

miabbott Jan 14, 2020

miabbott Jan 14, 2020

miabbott left a comment

dustymabe left a comment

dustymabe Jan 14, 2020

dustymabe Jan 14, 2020

dustymabe Jan 14, 2020

dustymabe Jan 14, 2020

dustymabe Jan 14, 2020

dustymabe Jan 14, 2020

dustymabe Jan 14, 2020

dustymabe Jan 14, 2020

dustymabe Jan 14, 2020

dustymabe Jan 14, 2020

dustymabe Jan 14, 2020

dustymabe commented Jan 14, 2020

jlebon Jan 14, 2020

jlebon Jan 14, 2020

jlebon Jan 14, 2020

jlebon Jan 14, 2020

jlebon Jan 14, 2020

jlebon Jan 14, 2020

dustymabe commented Jan 14, 2020

adriannemora commented Jan 14, 2020 via email

jlebon commented Jan 14, 2020

		@@ -0,0 +1,38 @@
		:experimental:

		= Fedora CoreOS Configuration Transpiler (`fcct`)


		include::ign-passwd.adoc[leveloffset=1]

		// https://coreos.com/ignition/docs/latest/operator-notes.html


		The `systemd` node contains one top-level node: a list of units. For each unit, the following options are available:

		* `name` (string, required, must be unique): the full name of the unit the form of `thing.service`.


		TIP: YAML files must have consistent indentation. Although `fcct` checks for syntax errors, ensure that the indentation matches the above example. Overall, the FCC files must conform to ``fcct``'s xref:fcct-config.adoc[schema].

		=== Using FCCT

Add doc for booting in a VM #22

Add doc for booting in a VM #22

Conversation

adriannemora commented Dec 24, 2019

Conan-Kudo commented Dec 25, 2019

dustymabe commented Jan 9, 2020

adriannemora commented Jan 9, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

miabbott left a comment

Choose a reason for hiding this comment

dustymabe left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dustymabe commented Jan 14, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dustymabe commented Jan 14, 2020

adriannemora commented Jan 14, 2020 via email

jlebon commented Jan 14, 2020

adriannemora commented Jan 9, 2020 •

edited

Loading