Update documentation for 3.1.0

CHANGELOG.md

@@ -8,10 +8,20 @@
   with `ds=<cloud>` or `tinycloud=cloud=<cloud>` (we may introduce additional
   cmdline Tiny Cloud config settings in the future).
 
-* Autodetection of `aws`, `azure`, `gcp`, and `oci` cloud providers via DMI
+* Autodetection of `aws`, `azure`, `gcp`, `hetzner`, `oci`, and (maybe)
-  information.
+  `scaleway` cloud providers via DMI information.
+
+* Current order of priority for determining cloud...
+  * `/etc/tiny-cloud.conf` _(image hardcoded)_
+  * `/var/lib/cloud/.autodetect` _(previously detected)_
+  * `/proc/cmdline` _(`ds=...` or `tinycloud=cloud=...`)_
+  * `/sys/class/dmi/id/product_serial` _(QEMU hack, same `cmdline`)_
+  * `/usr/lib/tiny-cloud/cloud/*/autodetect` scripts
+
+* Makefile improvements
+  * generalize cloud install targets
+  * ensure all user-data handlers get installed
 
-* Make sure all user-data handlers get installed.
 
 ## 2024-11-04 - Tiny Cloud v3.0.8
 

PACKAGING.md

@@ -0,0 +1,14 @@
+# PACKAGING
+
+## Alpine Linux
+
+The packaging of Tiny Cloud APKs for Alpine Linux can be found at
+https://gitlab.alpinelinux.org/alpine/aports/-/tree/master/main/tiny-cloud
+
+As of **3.1.0**, the main `tiny-cloud` APK contains all cloud and user-data
+modules, and set `CLOUD="auto"` in `/etc/tiny-cloud.conf`.  The per-cloud
+subpackages configure `/etc/tiny-cloud.conf` for that particular cloud, and the
+cloud subpackage installed _last_ is the one that "wins".
+
+Before 3.1.0, each per-cloud subpackage also provided its own cloud-specific
+libs.

README.md

@@ -25,6 +25,7 @@ Tiny Cloud is also used for Alpine Linux's experimental "auto-install" feature.
 
 The following actions will occur ***only once***, during the initial boot of an
 instance:
+* detect which cloud provider is present _(unless explicitly specified)_
 * expand the root filesystem to use all available root device space
 * set up default network interfaces, if necessary
 * enable `sshd`, if necessary
@@ -50,7 +51,7 @@ As Tiny Cloud is meant to be tiny, it has few dependencies:
 * `openssh-server`
 * `partx`
 * `sfdisk`
-* [`yx`](https://gitlab.com/tomalok/yx) (for extracting data from YAML files)
+* [`yx`](https://gitlab.com/tomalok/yx) (for extracting data from YAML or JSON files)
 
 _Tiny Cloud has been developed specifically for use with the
 [Alpine Cloud Images](
@@ -67,10 +68,14 @@ Typically, Tiny Cloud is installed and configured when building a cloud image,
 and is available on Alpine Linux as the [`tiny-cloud`](
   https://pkgs.alpinelinux.org/packages?name=tiny-cloud*) APKs...
 ```
-apk add tiny-cloud-<cloud>
+apk add tiny-cloud
 ```
 This will install the necessary init scripts, libraries, etc. plus any missing
-dependencies for Tiny Cloud to support _`<cloud>`_.
+dependencies for Tiny Cloud.  To also explicitly configure Tiny Cloud to use a
+specific supported cloud, you can install...
+```
+apk add tiny-cloud-<cloud>
+```
 
 Alternately, you can download a release tarball, and use `make` to install it.
 
@@ -87,12 +92,17 @@ By default, Tiny Cloud expects configuration at `/etc/tiny-cloud.conf`,
 The stock [`lib/tiny-cloud/tiny-cloud.conf`](lib/tiny-cloud/tiny-cloud.conf)
 file contains details of all tuneable settings.
 
-_Because Tiny Cloud does not universally do auto-detection, you may need to set
+Tiny Cloud tries to autodetect (supported) clouds as of 3.1.0.  The default
-a configuration value for `CLOUD` indicating which cloud provider will be used.
+value for `CLOUD` is `auto`.
-Current valid values are `aws`, `azure`, `gcp`, `hetzner`, `incus`, `nocloud`,
+
-`oci`, and `scaleway`.  A value of `auto` will attempt to auto-detect which
+However, if you want to explicitly set a cloud provider, you can do so in the
-cloud provider the instance is running on -- currently, only `incus` and
+conf file.  Current valid values are `aws`, `azure`, `gcp`, `hetzner`, `incus`,
-`nocloud` support auto-detection._
+`nocloud`, `oci`, and `scaleway`.
+
+Alternatively, you can add `tinycloud=cloud=<cloud>` (preferred) or `ds=<cloud>`
+(cloud-init compatible) to the kernel `/proc/cmdline` (preferred) or
+`/sys/class/dmi/id/product_serial` (QEMU hack) is another way to explicitly
+choose a cloud provider.
 
 ## Operation
 
@@ -138,7 +148,8 @@ and `/var/log/user-data.exit`.
 
 Additional final phase actions may be taken if there is a User-Data handler
 defined for its content type, and those actions are associated with the final
-phase.
+phase.  For example, a _small subset_ of `#cloud-config` is supported, and
+`#alpine-config` extends that with a couple of Alpine-specific setups.
 
 The very last action to be taken is to mark the instance's bootstrap as
 "complete", so that future reboots do not re-boostrap the instance.

TODO.md

@@ -2,16 +2,26 @@
 
 ## SOON-ish
 
-* Move things around a little for the "/usr merge" project.
+* Set up ephemeral networks early for the clouds that have network-accessible
+  IMDS, so we can get at user-data sooner than later.
 
-* Support cloud auto-detection, where it's possible to do so.
+* Support multiple network IMDS endpoints (ie. both IPv6 & IPv4).
 
 * Test improvements - each user-data handler should be tested with each cloud.
 
+* `man` pages for `imds` and `tiny-cloud`.
+
 ## FUTURE
 
+* Support `vendor-data`?  In theory this is a baseline, and and `user-data`
+  is layered on top of that.
+
 * Support additional features of `#cloud-config` as needed
 
 * Support LVM partitioning and non-`ext[234]` filesystems?
 
-* Other cloud providers?
+* Support other cloud providers...
+  * Digital Ocean
+  * IBM
+  * Openstack
+  * ???