[DOCS] Salt Cloud documentation overhaul

changelog/56546.deprecated.md

@@ -0,0 +1 @@
+Marked the ``softlayer`` and ``softlayer_hw`` cloud drivers as deprecated and scheduled for removal in a future Salt release. SoftLayer was acquired by IBM and rebranded as IBM Cloud Classic Infrastructure; these drivers are no longer exercised by Salt's test suite. The driver source docstrings and the *Getting Started With SoftLayer* doc page now carry ``.. deprecated::`` banners that link to issue #56546 and to recommended alternatives (Saltify, the IBM Cloud Terraform provider).

changelog/57933.fixed.md

@@ -0,0 +1 @@
+Documented the VMware cloud driver's ``customization_spec`` profile option (a name of a vCenter Customization Specification to apply at clone time) and added a Known Issues section that points at the ongoing Ubuntu hostname-not-set bug (issue #55889) and its workaround.

changelog/60679.fixed.md

@@ -0,0 +1 @@
+Documented every keyword argument accepted by the EC2 cloud ``register_image`` function (``ami_name``, ``description``, ``architecture``, ``virtualization_type``, ``root_device_name``, ``snapshot_id``, ``volume_type``, ``block_device_mapping``), including a multi-volume ``block_device_mapping`` CLI example that survives the shell parser.

changelog/64520.fixed.md

@@ -0,0 +1 @@
+Removed the misleading ``salt-cloud -p my-opennebula-profile vm_name memory=16384 cpu=2.5 vcpu=16`` example from the OpenNebula ``create()`` docstring. ``salt-cloud -p`` treats trailing positional arguments as additional VM names; the rewritten docstring explains the workaround (a dedicated profile or a cloud map) for per-VM overrides.

changelog/64629.fixed.md

@@ -0,0 +1 @@
+Documented every event tag emitted by Salt Cloud on a new reference page (``doc/topics/cloud/events.rst``). The lifecycle, power-state, reactor-hook, and per-resource (disk, snapshot, network, address, firewall, load balancer, health check, spot request, block volume) tags are now described in one place; the Salt Master Events page and the reactor tutorial cross-link to it. Resolves the inconsistency between the two pre-existing event lists noted in issues #64629 and #65063.

changelog/65063.fixed.md

@@ -0,0 +1 @@
+Documented the Azure ARM cloud driver's ``bootstrap_interface`` profile option (``public`` or ``private``) and clarified that the generic ``ssh_interface`` / ``win_interface`` options used by other drivers are **not** consulted by ``azurearm``. Added notes referencing the make-master traceback (issue #58096) and the ``list index out of range`` query error (issue #65064) so users can avoid the misconfiguration that triggers them.

changelog/65323.fixed.md

@@ -0,0 +1 @@
+Updated the *Writing Cloud Driver Modules* guide to stop describing ``script()`` as required for new drivers; ``salt.utils.cloud.bootstrap()`` already resolves the deploy script via ``os_script()``. The stale "use Linode as a libcloud example" reference has also been replaced with CloudStack and Dimension Data, and a note explains that Linode now uses the REST API directly.

doc/topics/cloud/azurearm.rst

@@ -266,6 +266,57 @@ allocate_public_ip
 Optional. Default is ``False``. If set to ``True``, a public IP will
 be created and assigned to the VM.
 
+bootstrap_interface
+-------------------
+Optional. Default is ``public``. Selects which network address the Azure ARM
+driver waits on (and uses for the Salt deploy connection) once the VM has
+been created. Valid values are:
+
+``public``
+    Use the first address from the VM's ``public_ips``. This is the default
+    and matches the historical behaviour. Requires ``allocate_public_ip:
+    True``.
+
+``private``
+    Use the first address from the VM's ``private_ips``. Use this value when
+    the Salt master can reach the VM over the VNet (for example a
+    ``make_master`` deployment or a private build agent) and you do not want
+    to allocate a public IP.
+
+.. note::
+
+    ``bootstrap_interface`` is specific to the Azure ARM driver. The
+    generic ``ssh_interface`` option (documented under other drivers such
+    as AWS, GCE and ProfitBricks) is **not** consulted by ``azurearm``;
+    use ``bootstrap_interface`` instead. ``win_interface`` is also not
+    consulted: Windows deploys use the same address selected by
+    ``bootstrap_interface``.
+
+.. note::
+
+    Creating a salt-master VM with ``make_master: True`` against Azure ARM
+    is currently affected by an upstream bug
+    (`issue #58096 <https://github.com/saltstack/salt/issues/58096>`_) that
+    raises ``ValueError: dictionary update sequence element #0 has length
+    1; 2 is required`` from ``salt.utils.cloud.master_config``. As a
+    workaround, install the salt-master with a state run against a
+    standalone VM (``make_master: False``) and accept the new minion's key
+    on that master, instead of bootstrapping the master through the cloud
+    map.
+
+.. note::
+
+    Profiles that request a Windows image with
+    ``allocate_public_ip: False`` and the default
+    ``bootstrap_interface: public`` can fail with
+    ``There was a query error: list index out of range`` once the VM has
+    been requested (see
+    `issue #65064 <https://github.com/saltstack/salt/issues/65064>`_).
+    The error originates from ``_query_node_data`` reading
+    ``data["public_ips"][0]`` against an instance that was not allocated
+    one. Set ``bootstrap_interface: private`` whenever
+    ``allocate_public_ip`` is ``False``.
+
 load_balancer
 -------------
 Optional. The load-balancer for the VM's network interface to join. If

doc/topics/cloud/cloud.rst

@@ -54,10 +54,18 @@ The most important function that does need to be manually written is the
 created by the cloud host, wait for it to become available, and then
 (optionally) log in and install Salt on it.
 
-A good example to follow for writing a cloud driver module based on libcloud
-is the module provided for Linode:
+Good examples to follow for writing a cloud driver module based on libcloud
+are the modules provided for CloudStack and Dimension Data:
 
-https://github.com/saltstack/salt/tree/|repo_primary_branch|/salt/cloud/clouds/linode.py
+https://github.com/saltstack/salt/tree/|repo_primary_branch|/salt/cloud/clouds/cloudstack.py
+
+https://github.com/saltstack/salt/tree/|repo_primary_branch|/salt/cloud/clouds/dimensiondata.py
+
+.. note::
+
+    Salt's Linode driver no longer uses libcloud. It was rewritten to use the
+    Linode REST API directly; see ``salt/cloud/clouds/linode.py`` for an
+    example of a non-libcloud driver instead.
 
 The basic flow of a ``create()`` function is as follows:
 
@@ -238,10 +246,17 @@ normally called using the ``--list-sizes`` option.
 
 The script() Function
 ---------------------
-This function builds the deploy script to be used on the remote machine.  It is
-likely to be moved into the ``salt.utils.cloud`` library in the near future, as
-it is very generic and can usually be copied wholesale from another module. An
-excellent example is in the Azure driver.
+This function used to be required by every cloud driver. It is no longer
+required: the deploy-script lookup is now handled centrally by
+``salt.utils.cloud.bootstrap()``, which reads the ``script`` value from the
+profile or provider configuration and resolves it via
+``salt.utils.cloud.os_script()``. New drivers do not need to define their
+own ``script()`` function.
+
+Existing drivers continue to ship a ``script()`` wrapper for backward
+compatibility. It is safe to copy this wrapper unchanged from another driver
+(for example ``salt/cloud/clouds/digitalocean.py``) when porting an older
+driver, but it should not be required for any new code paths.
 
 The destroy() Function
 ----------------------