docs: autoinstall tutorial

[dbungert]

I think much of this content should be moved into other sections, but as a start I'm bringing in the existing autoinstall doc into rst format. I couldn't help with some editorial improvements along the way, if that becomes a problem I'll resplit.

Deviations from existing autoinstall doc:

• quick start page not listed yet, we don't have that in rst yet
• reference to autoinstall-generator dropped - that project needs some help
• Interactions between Autoinstall and Cloud-init section rewritten
• possible future direction section dropped, we should consider a proper roadmap but it surely doesn't need to be in a tutorial

Note that the docs are written assuming that they are housing all ubuntu install documentation, but is only starting with autoinstall. I don't know if that will be awkward when we cut over.

[mwhudson]

Looks like a good start

[ogayot]

nice work!

[ogayot]

I'm a bit torn on providing examples without the #cloud-config + autoinstall key when we explicitly suggest to use the cloud-init approach. I know it's boilerplate so we probably don't want to repeat the same thing over and over in the examples.

Maybe a little reminder before or after the examples for people tempted to copy-paste? Something like:

/!\ Remember to add the #cloud-config header and place the configuration within an autoinstall section if you are using the cloud-init approach.

#cloud-config
autoinstall:
  < place the autoinstall configuration here >

[dbungert]

A goal I have for the doc overhaul is to reduce people sending autoinstall as cloud-config, so I think something like this would help reduce it. I'm not sure I want the "Remember to add" part all the time, but to just have 99% of the autoinstall snippets (pretty much all of them except the case showing the non-cloud-init path in this document) just always include

#cloud-config
autoinstall:

might well help reduce that confusion.

[dbungert]

So yes, I like the suggestion very much, but think I want to skip the reminder part and just include the above 2 lines in yaml samples.

[ogayot]

Thanks!

[s-makin]

I think having a warning at the top where you introduce the #cloud-config and autoinstall lines would achieve the same thing (see my comment around line 64) - any user who wants to use that method will have their attention drawn to the fact that these lines are necessary - but having the lines also included in the examples is a great idea in case users try to copy/paste directly. A tutorial should be foolproof, so if we give them examples to try they shouldn't be able to fail with them if they follow the instructions.

[dbungert]

Yes, I'm erring on the side of foolproof. We have adequate user evidence that there is a lot of user confusion on this point. I'd normally prefer the shorter code sample.

Something I've debated doing is to allow direct specification of the autoinstall.yaml file to be in Cloud config data format - if autoinstall is the only top level directive, then this is simply handled subiquity side. But what if there are other cloud-config top level keys? I think Subiquity should warn or error in that case, as those aren't going to be processed.

If we did that, then 100% of the time it would be possible to just copy-paste the code sample in Cloud config data format and get a working result, regardless of if providing the data with the help of cloud-init or with modified install media.

[ogayot]

Nothing to do here but I wish we'd stop the install if the user types "no". Right now, it keeps asking the same question again until you type "yes" (at least in dry-run)

[s-makin]

Overall it's a really good basis. I would definitely recommend having a separate tutorial for each of the suggested methods; using this page as the introduction, you could then divert users early on towards the tutorial they need in order to avoid confusion that might arise from the two being presented together.

[s-makin]

I think having a warning at the top where you introduce the #cloud-config and autoinstall lines would achieve the same thing (see my comment around line 64) - any user who wants to use that method will have their attention drawn to the fact that these lines are necessary - but having the lines also included in the examples is a great idea in case users try to copy/paste directly. A tutorial should be foolproof, so if we give them examples to try they shouldn't be able to fail with them if they follow the instructions.

[blackboxsw]

@dbungert this looks really good. I think the only thing I'd like to see is a bit more explicit content describing that cloud-init runs in both ephmeral and at first boot and a pointer to the honored cloud-init cloud-conifg module schema directives

Given that this is a tutorial, do you plan on having a section in a later pull request that actually walks someone through the cmdline to download live ISO, launch python3 -m http.server with nocloud user-data containing autoinstall: #cloud-config directives via kernel cmdline? Maybe that's the quickstart you referred to as a followup (out of scope for this PR).

[dbungert]

Given that this is a tutorial, do you plan on having a section in a later pull request that actually walks someone through the cmdline to download live ISO, launch python3 -m http.server with nocloud user-data containing autoinstall: #cloud-config directives via kernel cmdline? Maybe that's the quickstart you referred to as a followup (out of scope for this PR).

Yes, I see what you mention as a proper tutorial and what I'm referring to as a quickstart above.

When I sat down to bring https://ubuntu.com/server/docs/install/autoinstall into rtd/diataxis, I read the entire doc attempting to view it like a first time reader, and realized that much of it didn't really fit an introduction or tutorial in the diataxis sense. I was a bit paralyzed wondering what to do about it.

To split the problem a bit, I first wanted to just get the document kind-of as-is into rtd/diataxis, and sort out the tutorial versus other 3 categories problem later. Also, if we can cut over the existing docs to diataxis, it will be mentally easier to add new content.

So I really wanted to import the introduction, with most of the warts in place, rather than trying to build out a tutorial I liked better and deal with moving all the rest of the content to their proper locations.

I started the reference document largely as an exercise in learning how the ref links work.

[blackboxsw]

LGTM! thanks for the text and context around this iteration of the refactor. +1

[s-makin]

Good changes! Found a few teeny nits, but otherwise LGTM :)