Datasource docs update, include boot status #4670
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
holmanb
added a commit
to holmanb/cloud-init
that referenced
this pull request
Dec 6, 2023
Some technical and logistical expectations were implied. Be clear about expectations for new datasource inclusions. Also reorganize content for clarity.
holmanb
added a commit
to holmanb/cloud-init
that referenced
this pull request
Dec 6, 2023
holmanb
force-pushed
the
holmanb/datasource-docs-update
branch
from
6b4d5fb to
eb6012c
Compare
holmanb
force-pushed
the
holmanb/datasource-docs-update
branch
from
eb6012c to
ce72c69
Compare
holmanb
added a commit
to holmanb/cloud-init
that referenced
this pull request
Dec 6, 2023
Some technical and logistical expectations were implied. Be clear about expectations for new datasource inclusions. Also reorganize content for clarity.
holmanb
added a commit
to holmanb/cloud-init
that referenced
this pull request
Dec 6, 2023
holmanb
force-pushed
the
holmanb/datasource-docs-update
branch
from
ce72c69 to
780e7ca
Compare
holmanb
added a commit
to holmanb/cloud-init
that referenced
this pull request
Dec 6, 2023
holmanb
force-pushed
the
holmanb/datasource-docs-update
branch
2 times, most recently
from
021a847 to
68aa412
Compare
holmanb
added a commit
to holmanb/cloud-init
that referenced
this pull request
Dec 7, 2023
If links succeed locally but fail in GH actions, what else can one do? Increment link failure, since linkcheck doesn't understand GH markdown page anchors.
holmanb
added a commit
to holmanb/cloud-init
that referenced
this pull request
Dec 7, 2023
If links succeed locally but fail in GH actions, what else can one do? Increment link failure, since linkcheck doesn't understand GH markdown page anchors.
holmanb
added a commit
to holmanb/cloud-init
that referenced
this pull request
Dec 7, 2023
Some technical and logistical expectations were implied. Be clear about expectations for new datasource inclusions. Also reorganize content for clarity.
holmanb
force-pushed
the
holmanb/datasource-docs-update
branch
from
68aa412 to
717cc98
Compare
holmanb
added a commit
to holmanb/cloud-init
that referenced
this pull request
Dec 7, 2023
|
@TheRealFalcon Commit 717cc98 is a continuation of the conversation from #4578, since boot status was otherwise undocumented. Would you mind reviewing this PR? This PR includes a couple of other miscellaneous commits. I also added some content for requirements for new datasources, including a section about reusing existing datasources (i.e. libvirt, proxmox), more logistical expectations for new datasources (access to testing, an informal maintainer), as well as a short section describing the benefits of upstreaming your datasource. This includes a bump to the link count that linkcheck can't follow in Github Actions for some reason, as well as prints the list of broken links in the job log. |
TheRealFalcon
approved these changes
Dec 8, 2023
holmanb
added a commit
to holmanb/cloud-init
that referenced
this pull request
Dec 8, 2023
holmanb
added a commit
to holmanb/cloud-init
that referenced
this pull request
Dec 9, 2023
s-makin
reviewed
Dec 11, 2023
Comment on lines
12
to
13
| In order to use cloud-init with a new platform, a couple of approaches | ||
| are possible: |
There was a problem hiding this comment.
This sounds a bit passive. I'd say "To add cloud-init support for a new platform, there are two possible approaches".
| 2. Add a new datasource definition to upstream cloud-init. This provides | ||
| tighter integration, a better debugging experience, and more control | ||
| and flexibility of cloud-init's interaction with the datasource. This | ||
| option is more sensible for clouds that have an unique architecture. |
There was a problem hiding this comment.
Suggested change
| option is more sensible for clouds that have an unique architecture. | |
| option is more sensible for clouds that have a unique architecture. |
| Platform requirements | ||
| ===================== | ||
|
|
||
| There are some technical and logistical requisites that must be met for |
There was a problem hiding this comment.
Suggested change
| There are some technical and logistical requisites that must be met for | |
| There are some technical and logistical prerequisites that must be met for |
| There are some technical and logistical requisites that must be met for | ||
| cloud-init support. | ||
|
|
||
| Technical Requirements |
There was a problem hiding this comment.
Suggested change
| Technical Requirements | |
| Technical requirements |
Comment on lines
32
to
34
| Cloud-init requires that a cloud be able to identify itself to cloud-init at | ||
| runtime, and that the cloud be able to provide configuration to the | ||
| instance. |
There was a problem hiding this comment.
Suggested change
| Cloud-init requires that a cloud be able to identify itself to cloud-init at | |
| runtime, and that the cloud be able to provide configuration to the | |
| instance. | |
| A cloud needs to be able to identify itself to cloud-init at | |
| runtime, and be able to provide configuration to the | |
| instance. |
Comment on lines
69
to
72
| A platform that isn't available for testing is a platform which cannot be | ||
| independently validated. Please provide some means for community members and | ||
| upstream developers to test and verify this platform. Code that cannot be used | ||
| is not code that can be supported. |
There was a problem hiding this comment.
Suggested change
| A platform that isn't available for testing is a platform which cannot be | |
| independently validated. Please provide some means for community members and | |
| upstream developers to test and verify this platform. Code that cannot be used | |
| is not code that can be supported. | |
| A platform that isn't available for testing cannot be independently | |
| validated. You will need to provide some means for community members and | |
| upstream developers to test and verify this platform. Code that cannot be used | |
| cannot be supported. |
Comment on lines
77
to
82
| At times a point of contact is required to answer questions and occasionally | ||
| provide testing or maintenance support. Maintainership is relatively informal, | ||
| but please note that there is expectation that from time to time upstream may | ||
| need to contact a the maintainer with inquiries. Datasources which are believed | ||
| to be unmaintained and unused may at some point in the future be considered for | ||
| removal. |
There was a problem hiding this comment.
Suggested change
| At times a point of contact is required to answer questions and occasionally | |
| provide testing or maintenance support. Maintainership is relatively informal, | |
| but please note that there is expectation that from time to time upstream may | |
| need to contact a the maintainer with inquiries. Datasources which are believed | |
| to be unmaintained and unused may at some point in the future be considered for | |
| removal. | |
| A point of contact is required who can answer questions and occasionally | |
| provide testing or maintenance support. Maintainership is relatively informal, | |
| but there is an expectation that from time to time upstream may | |
| need to contact the maintainer with inquiries. Datasources that appear | |
| to be unmaintained and/or unused may be considered for eventual | |
| removal. |
| Benefits of including your datasource in upstream cloud-init | ||
| ============================================================ | ||
|
|
||
| Datasources which are included in upstream cloud-init benefit from ongoing |
There was a problem hiding this comment.
Suggested change
| Datasources which are included in upstream cloud-init benefit from ongoing | |
| Datasources included in upstream cloud-init benefit from ongoing |
doc/rtd/howto/status.rst
Outdated
| Cloud-init enablement status | ||
| ---------------------------- | ||
|
|
||
| Separate from the current running status described above, cloud-init can also |
There was a problem hiding this comment.
Suggested change
| Separate from the current running status described above, cloud-init can also | |
| Separately from the current running status described above, cloud-init can also |
doc/rtd/howto/status.rst
Outdated
Comment on lines
69
to
83
| - ``'unknown'``: ``ds-identify`` hasen't run yet to determine if cloud-init should | ||
| be run during this boot | ||
| - ``'disabled-by-marker-file'``: /etc/cloud/cloud-init.disabled exists | ||
| which prevents cloud-init from ever running | ||
| - ``'disabled-by-generator'``: ``ds-identify`` determined no applicable cloud-init | ||
| datasources | ||
| - ``'disabled-by-kernel-cmdline'``: kernel cmdline contained | ||
| cloud-init=disabled | ||
| - ``'disabled-by-environment-variable'``: environment variable KERNEL_CMDLINE | ||
| contained cloud-init=disabled | ||
| - ``'enabled-by-kernel-cmdline'``: kernel cmdline contained | ||
| cloud-init=enabled | ||
| - ``'enabled-by-generator'``: ``ds-identify`` detected possible cloud-init | ||
| datasources | ||
| - ``'enabled-by-sysvinit'``: enabled by default in SysV init environment |
There was a problem hiding this comment.
Suggested change
| - ``'unknown'``: ``ds-identify`` hasen't run yet to determine if cloud-init should | |
| be run during this boot | |
| - ``'disabled-by-marker-file'``: /etc/cloud/cloud-init.disabled exists | |
| which prevents cloud-init from ever running | |
| - ``'disabled-by-generator'``: ``ds-identify`` determined no applicable cloud-init | |
| datasources | |
| - ``'disabled-by-kernel-cmdline'``: kernel cmdline contained | |
| cloud-init=disabled | |
| - ``'disabled-by-environment-variable'``: environment variable KERNEL_CMDLINE | |
| contained cloud-init=disabled | |
| - ``'enabled-by-kernel-cmdline'``: kernel cmdline contained | |
| cloud-init=enabled | |
| - ``'enabled-by-generator'``: ``ds-identify`` detected possible cloud-init | |
| datasources | |
| - ``'enabled-by-sysvinit'``: enabled by default in SysV init environment | |
| - ``'unknown'``: ``ds-identify`` has not run yet to determine if cloud-init should | |
| be run during this boot | |
| - ``'disabled-by-marker-file'``: :file:`/etc/cloud/cloud-init.disabled` exists | |
| which prevents cloud-init from ever running | |
| - ``'disabled-by-generator'``: ``ds-identify`` determined no applicable cloud-init | |
| datasources | |
| - ``'disabled-by-kernel-cmdline'``: environment variable ``KERNEL_CMDLINE`` contained | |
| ``cloud-init=disabled`` | |
| - ``'disabled-by-environment-variable'``: environment variable ``KERNEL_CMDLINE`` | |
| contained ``cloud-init=disabled`` | |
| - ``'enabled-by-kernel-cmdline'``: ``KERNEL_CMDLINE`` contained | |
| ``cloud-init=enabled`` | |
| - ``'enabled-by-generator'``: ``ds-identify`` detected possible cloud-init | |
| datasources | |
| - ``'enabled-by-sysvinit'``: enabled by default in SysV init environment |
There was a problem hiding this comment.
One exception here: "KERNEL_CMDLINE contained cloud-init=enabled" is not right. In this case we are talking literally about the kernel command line. The line above is referring to an environment variable with the name "KERNEL_CMDLINE". The kernel commandline itself can be read via cat /proc/cmdline and is different from the aforementioned environment variable with a similar name.
There was a problem hiding this comment.
Thanks for the context - I saw the discrepancy and figured they were all meant to be the same.
There was a problem hiding this comment.
(to disambiguate, I would probably propose changing cmdline to command line, but I leave that to your discretion - happy to approve either way)
There was a problem hiding this comment.
agreed, looks like we can drop commandline from the spelling list too
holmanb
added a commit
to holmanb/cloud-init
that referenced
this pull request
Dec 11, 2023
holmanb
added a commit
to holmanb/cloud-init
that referenced
this pull request
Dec 11, 2023
|
Thanks for the reviews @TheRealFalcon and @s-makin. Great suggestions all around :-) |
holmanb
added a commit
to holmanb/cloud-init
that referenced
this pull request
Dec 11, 2023
If links succeed locally but fail in GH actions, what else can one do? Increment link failure, since linkcheck doesn't understand GH markdown page anchors.
Some technical and logistical expectations were implied. Be clear about expectations for new datasource inclusions. Also reorganize content for clarity.
holmanb
force-pushed
the
holmanb/datasource-docs-update
branch
from
d0ac924 to
6fc10ed
Compare
holmanb
added a commit
to holmanb/cloud-init
that referenced
this pull request
Dec 11, 2023
s-makin
approved these changes
Dec 12, 2023
holmanb
force-pushed
the
holmanb/datasource-docs-update
branch
from
6fc10ed to
2788c3b
Compare
holmanb
added a commit
that referenced
this pull request
Dec 13, 2023
If links succeed locally but fail in GH actions, what else can one do? Increment link failure, since linkcheck doesn't understand GH markdown page anchors.
holmanb
added a commit
that referenced
this pull request
Dec 13, 2023
Some technical and logistical expectations were implied. Be clear about expectations for new datasource inclusions. Also reorganize content for clarity.
holmanb
added a commit
that referenced
this pull request
Dec 13, 2023
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Additional Context
Blocked by #4578, separate PR because that one is already too big.
Merge type