From f7eb14f05f3143b3ea2db05a5eebc11e83a2b395 Mon Sep 17 00:00:00 2001 From: Tim Smith Date: Sat, 29 Aug 2026 19:10:26 -0700 Subject: [PATCH] docs: correct what associate_public_ip actually does The option table described associate_public_ip as setting up static NAT. It does not: it associates a public address and creates a port forwarding rule for the one port the configured transport connects on. Someone reading "static NAT" would reasonably expect the whole instance to be reachable through that address, and then find that nothing but SSH or WinRM is. Also drops the duplicate disable_ssl_validation row, which was documented twice with two different descriptions; states cloudstack_sync_time's default as unset rather than 0, since the driver has no default_config for it and skips the wait entirely; documents kitchen doctor, which this driver implements and the README never mentioned; and removes the ask to port the driver off SSHBase, which was done in 1.0.0 and which the README's own troubleshooting section already says was done. Signed-off-by: Tim Smith --- README.md | 25 +++++++++++++++++++++---- 1 file changed, 21 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index e6d571d..7c38593 100644 --- a/README.md +++ b/README.md @@ -147,7 +147,7 @@ These apply only when the service offering itself does not specify CPU or memory | --- | --- | --- | | `cloudstack_network_id` | *unset* | Network ID, for isolated or VPC networks. | | `cloudstack_security_group_id` | *unset* | Security group ID, for shared networks. | -| `associate_public_ip` | `false` | Acquire a public IP and set up static NAT automatically. | +| `associate_public_ip` | `false` | Acquire a public IP and forward the transport's port to the instance. This is a port forwarding rule for that one port, not static NAT, so nothing else on the instance is reachable through the public address. | | `cloudstack_vm_public_ip` | *unset* | Public IP to connect to, when you configure advanced networking and static NAT yourself. | | `cloudstack_create_firewall_rule` | `false` | Create a firewall rule opening the transport's port to the public IP. | | `cloudstack_firewall_cidr` | `0.0.0.0/0` | Source range the firewall rule allows. Narrow this to your own network rather than leaving it open to the internet. | @@ -161,7 +161,7 @@ These apply only when the service offering itself does not specify CPU or memory | `password` | *generated by CloudStack* | Password to connect with. By default the driver uses the password CloudStack generates. | | `cloudstack_ssh_keypair_name` | *unset* | Name of a CloudStack SSH keypair to deploy with. See [SSH keypairs](#ssh-keypairs). | | `keypair_search_directory` | *see below* | Extra directory to search for the keypair's `.pem` file. | -| `cloudstack_sync_time` | `0` | Seconds to wait before connecting, to let `cloud-set-guest-password` or `cloud-set-guest-sshkey` finish. Raise this if logins fail intermittently just after boot. | +| `cloudstack_sync_time` | *unset* | Seconds to wait before connecting, to let `cloud-set-guest-password` or `cloud-set-guest-sshkey` finish. Raise this if logins fail intermittently just after boot. | ### Naming @@ -177,7 +177,6 @@ These apply only when the service offering itself does not specify CPU or memory | `cloudstack_userdata` | *unset* | User data passed to the VM. Must be a double-quoted string, so escapes such as `\n` are interpreted. | | `cloudstack_job_poll_interval` | `10` | Seconds between checks on a running CloudStack job. | | `cloudstack_job_timeout` | `600` | Seconds to wait for a CloudStack job before giving up. Raise this if deploys legitimately take longer. | -| `disable_ssl_validation` | `false` | Skip SSL certificate validation against the API. Only for a deployment without valid certificates. | ## SSH keypairs @@ -285,6 +284,12 @@ driver: cloudstack_create_firewall_rule: true ``` +The driver forwards only the port your transport connects on — 22 for SSH, +5985 or 5986 for WinRM — and, with `cloudstack_create_firewall_rule`, opens +that same one port. If you need other ports reachable from outside, set up +static NAT yourself and point the driver at the address with +`cloudstack_vm_public_ip`. + ### Static NAT configured by hand ```yaml @@ -331,6 +336,18 @@ driver: cloudstack_expunge: true ``` +## Checking your configuration + +The driver has no required settings, so a missing endpoint or credential is not +caught when Test Kitchen loads `kitchen.yml` — it surfaces part way through a +deploy. `kitchen doctor` moves that discovery earlier. It names every setting +you have left unset in one go, and then makes a real API call to confirm that +CloudStack accepts your keys: + +```sh +bundle exec cinc kitchen doctor default-ubuntu +``` + ## Troubleshooting **`NameError: uninitialized constant Kitchen::Driver::SSHBase`.** You are running @@ -365,7 +382,7 @@ Everything else works identically. ## Contributing -Bug reports and pull requests are welcome on [GitHub](https://github.com/test-kitchen/kitchen-cloudstack). Porting the driver off the removed `SSHBase` class would be especially valuable. See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and the state of the test tooling. +Bug reports and pull requests are welcome on [GitHub](https://github.com/test-kitchen/kitchen-cloudstack). See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, the layout of the test suite, and the changes that would be most useful. ## Authors