Add howtoguide for pro on multiple machines #3380
Conversation
|
|
||
| - `QEMU`_ | ||
| - `LXD`_ | ||
| - `Ansible`_ |
There was a problem hiding this comment.
Cloud-init does not have any MAAS related document nor does MAAS have any pro related docs. All there is on MAAS with pro is this: https://maas.io/docs/how-to-deploy-a-real-time-kernel
Which might not be relevant
There was a problem hiding this comment.
I think it's ok to start with this page as an initial version. We can always expand it later with more content if/when necessary :)
|
|
||
| This guide will show you how to roll out your pro token across multiple machines using cloud-init for configuration. | ||
|
|
||
| Configure using Cloud-init |
There was a problem hiding this comment.
Can probably frame this better. Any suggestions?
There was a problem hiding this comment.
I'll probably have more suggestions once all the content is in place - let's leave this as a working title for now
| - `LXD`_ | ||
| - `Ansible`_ | ||
|
|
||
| Verifying deployment |
There was a problem hiding this comment.
Don't know if we need this here or something more extensive 😅
There was a problem hiding this comment.
I think we should include the expected output so that the user knows if they're seeing the right thing or not.
docs/howtoguides/attach_index.rst
Outdated
| How to attach <how_to_attach> | ||
| Simulate attaching <how_to_simulate_attach> | ||
| Attach with a configuration file <how_to_attach_with_config_file> | ||
| Configure Ubuntu Pro across multiple machines <how_to_roll_out_across_multiple_machines> |
There was a problem hiding this comment.
It's generally better to try and use the same title where possible on the page + in the navigation, or at least something very close. I think changing the title to something like "Attach multiple machines" might work better? "Configure" and "roll out" feel a bit like they're not quite describing the same thing, so it might be confusing for users to equate the two.
There was a problem hiding this comment.
Yeah, attach multiple machines sounds much better.
| @@ -0,0 +1,48 @@ | |||
| .. _roll_out_multiple_machines: | |||
|
|
|||
| How to roll out your pro token across multiple machines | |||
There was a problem hiding this comment.
Again I'd switch this to something more like "Attach multiple machines" - this is more aligned with the sort of search queries people will use when they are trying to find out how to attach multiple machines at once
| How to roll out your pro token across multiple machines | ||
| ======================================================= | ||
|
|
||
| This guide will show you how to roll out your pro token across multiple machines using cloud-init for configuration. |
There was a problem hiding this comment.
I think a natural question here might be "why cloud-init?". It's worth expanding this intro paragraph to mention the alternatives (scripting, API), and the specific situation(s) that might lead you to use cloud-init (e.g., VMs/containers, etc). We should also link to the cloud-init docs here as well - not every user is likely to be familiar with it.
There was a problem hiding this comment.
Yeah, that's a good catch
|
|
||
| - `QEMU`_ | ||
| - `LXD`_ | ||
| - `Ansible`_ |
There was a problem hiding this comment.
I think it's ok to start with this page as an initial version. We can always expand it later with more content if/when necessary :)
| token: <YOUR_PRO_TOKEN> | ||
|
|
||
|
|
||
| Replace <YOUR_PRO_TOKEN> with the pro token you received from the Ubuntu Pro Dashboard. |
There was a problem hiding this comment.
Obtaining the token from the dashboard should be step 1 - might need more detail here about that
|
|
||
| This guide will show you how to roll out your pro token across multiple machines using cloud-init for configuration. | ||
|
|
||
| Configure using Cloud-init |
There was a problem hiding this comment.
I'll probably have more suggestions once all the content is in place - let's leave this as a working title for now
|
|
||
| Replace <YOUR_PRO_TOKEN> with the pro token you received from the Ubuntu Pro Dashboard. | ||
|
|
||
| For more information on how to configure the pro token with cloud-init, take a look at the guide here: `Configure Pro in cloud-init <CLOUD_INIT_PRO_>`_. |
There was a problem hiding this comment.
You're not actually configuring the pro token, so this reads as a bit misleading. I'm not sure what you intended to say, so I can't really suggest an alternative.
There was a problem hiding this comment.
We can probably say something like "Configuring Pro using Cloud-init"?
The cloud-init link mentions configuring pro services.
|
|
||
| The next step is to usea cloud-init to configure your machines with the pro token. | ||
|
|
||
| To do this, a cloud-init configuratioin file is required. Create a cloud-init.yaml file with the following content: |
There was a problem hiding this comment.
This is probably step 2 - I wouldn't phrase it as "create a cloud-init.yaml file", because the typical reader of our docs is unlikely to know what that is. Better to tell them to create a file called cloud-init.yaml, then to copy and paste the contents of the code block.
|
|
||
| For more information on how to configure the pro token with cloud-init, take a look at the guide here: `Configure Pro in cloud-init <CLOUD_INIT_PRO_>`_. | ||
|
|
||
| Cloud-init also has comprehensive guides on configuring cloud-init for different platforms: |
There was a problem hiding this comment.
This is step 3 - launching the machine with the configuration we want to apply. Since this can vary platform by platform I think it makes sense to provide multiple links as you have done. If we want to restrict these instructions to VMs/containers, we may also want to add Multipass and WSL.
| - `LXD`_ | ||
| - `Ansible`_ | ||
|
|
||
| Verifying deployment |
There was a problem hiding this comment.
I think we should include the expected output so that the user knows if they're seeing the right thing or not.
|
Updated @s-makin |
Why is this needed?
This PR solves all of our problems because it adds a how to guide for rolling out the pro subscription across multiple machines as per SD-1924
Test Steps