Skip to content

docs: correct what associate_public_ip does, and four smaller README fixes - #64

Merged
tas50 merged 1 commit into
mainfrom
docs-readme-corrections
Aug 30, 2026
Merged

docs: correct what associate_public_ip does, and four smaller README fixes#64
tas50 merged 1 commit into
mainfrom
docs-readme-corrections

Conversation

@tas50

@tas50 tas50 commented Aug 30, 2026

Copy link
Copy Markdown
Member

I went through every option in the README against default_config and every
place the driver reads config[...]. The good news first: there are no options
in the code that the README leaves out, and no options in the README that the
code no longer reads. The defaults are right too, apart from one noted below.

What I did find:

associate_public_ip is documented backwards

The table said:

Acquire a public IP and set up static NAT automatically.

It does not set up static NAT. Networking#associate_public_ip calls
associateIpAddress, and Networking#create_port_forward then calls
createPortForwardingRule with privateport and publicport both set to the
one port the configured transport connects on. Static NAT
(enableStaticNat) makes the whole instance reachable through the address; a
port forwarding rule makes exactly one port reachable.

That is a meaningful difference for anyone whose test needs to reach a service
on the instance — they will read "static NAT", expect port 8080 to work, and
find that only SSH does. cloudstack_create_firewall_rule has the same
one-port scope, and the Windows section further down already describes the
behaviour correctly, so the table row was the outlier.

I have corrected the row and added a note to the advanced-networking example
pointing at cloudstack_vm_public_ip for people who want static NAT.

disable_ssl_validation was documented twice

Once under Credentials and once under Other, with two different descriptions.
Kept the Credentials one.

cloudstack_sync_time claimed a default of 0

There is no default_config for it. When it is unset the driver skips the wait
entirely rather than sleeping zero seconds. Same outcome, but "unset" is what
is actually true, and it does not imply a default that is not there.

kitchen doctor was undocumented

The driver implements doctor, and it is genuinely worth knowing about: this
driver declares no required_config, so a missing endpoint or credential is
not caught at load time and instead fails part way through a deploy. doctor
names every unset setting in one run and then makes a real API call to check
the keys. Added a short section for it.

The contributing section asked for work that is already done

Porting the driver off the removed SSHBase class would be especially
valuable.

That was done in 1.0.0 — the README's own troubleshooting entry tells people on
0.24.0 to upgrade for exactly that reason. Pointed at CONTRIBUTING.md's actual
list instead.

Testing

markdownlint-cli2 clean, which is what CI runs on **/*.md.

Conflicts

#62 touches one line of this README (the fog-cloudstack bullet under
Requirements). Nothing here goes near it.

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 <tim@mondoo.com>
@tas50
tas50 merged commit c22117a into main Aug 30, 2026
3 checks passed
@tas50
tas50 deleted the docs-readme-corrections branch August 30, 2026 02:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant