kitchen-vra 3.3.3 → 3.3.4

data/README.md

@@ -1,63 +1,292 @@
 # kitchen-vra
 
-A driver to allow Test Kitchen to consume vRealize Automation (vRA) resources to perform testing.
+[![Gem Version](https://badge.fury.io/rb/kitchen-vra.svg)](https://badge.fury.io/rb/kitchen-vra)
+
+A [Test Kitchen](https://kitchen.ci/) driver that provisions and destroys machines through [VMware vRealize Automation](https://www.vmware.com/products/vrealize-automation.html) (vRA, now Aria Automation), so you can test your cookbooks and infrastructure code against instances from your own vRA catalog.
+
+Rather than talking to a hypervisor directly, this driver submits a catalog request to vRA and waits for the resulting deployment, so test instances follow the same blueprints, approvals, and policies as the rest of your estate.
+
+> This documentation uses [Cinc Workstation](https://cinc.sh/) and the `cinc` commands throughout. Everything here works identically with Chef Workstation — see [Using with Chef](#using-with-chef).
+
+## Requirements
+
+- Ruby 3.1 or later (already satisfied if you use Cinc Workstation)
+- Access to a vRA 8.x appliance
+- A catalog item that provisions exactly **one** virtual machine — the driver rejects a request that returns more than one server
+- Permission to request that catalog item, and to delete the resulting deployment
 
 ## Installation
 
-Add this line to your application's Gemfile:
+This driver ships as part of [Cinc Workstation](https://cinc.sh/start/workstation/). If you have Cinc Workstation installed, there is nothing else to install.
+
+To install it into a standalone Ruby:
+
+```sh
+gem install kitchen-vra
+```
+
+Or with Bundler, add it to your `Gemfile`:
 
 ```ruby
-gem 'kitchen-vra'
+gem "kitchen-vra"
 ```
 
-And then execute:
+...then run `bundle install`.
+
+## Authentication
+
+Credentials are resolved in this order:
 
-```shell
-bundle
+1. The `username` and `password` driver options
+2. The `VRA_USER_NAME` and `VRA_USER_PASSWORD` environment variables
+3. Cached credentials, if `cache_credentials` was enabled on a previous run
+4. An interactive prompt
+
+Keep credentials out of `kitchen.yml`. The usual approach is the environment:
+
+```sh
+export VRA_USER_NAME='myuser@corp.local'
+export VRA_USER_PASSWORD='mypassword'
 ```
 
-Or install it yourself as:
+Setting `cache_credentials: true` stores the credentials after a successful run so later runs do not prompt. They are written to `.kitchen/cached_vra`, encrypted under a key derived from `base_url` and readable only by your user. Since `base_url` is not a secret, this hides the password from casual view rather than protecting it — treat the file as sensitive and avoid the option on shared machines.
 
-```shell
-gem install kitchen-vra
+## Quick Start
+
+```yaml
+---
+driver:
+  name: vra
+  base_url: https://vra.corp.local
+  domain: corp.local
+  project_id: 6ba69375-2d1e-4a5e-9e9b-1a1a3f0e6d4c
+  image_mapping: Ubuntu 22.04
+  flavor_mapping: Small
+  catalog_name: Ubuntu Server
+  verify_ssl: true
+
+provisioner:
+  name: cinc_infra
+
+verifier:
+  name: cinc_auditor
+
+platforms:
+  - name: ubuntu-22.04
+
+suites:
+  - name: default
+    run_list:
+      - recipe[my_cookbook::default]
 ```
 
-Or even better, install it via ChefDK:
+Then run the full test cycle:
 
-```shell
-chef gem install kitchen-vra
+```sh
+cinc kitchen test
+```
+
+Or step through it:
+
+```sh
+cinc kitchen create    # submit the catalog request and wait for the deployment
+cinc kitchen converge  # apply your cookbook
+cinc kitchen verify    # run your tests
+cinc kitchen destroy   # destroy the vRA deployment
 ```
 
 ## Configuration
 
-See the [kitchen.ci kitchen-vra docs](https://kitchen.ci/docs/drivers/vra/) for a complete list of configuration options.
+All options below are set under the `driver:` key in `kitchen.yml`.
 
-## License and Authors
+### Required
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `base_url` | *none* | Base URL of the vRA appliance, e.g. `https://vra.corp.local`. Required. |
+| `domain` | *none* | Authentication domain, e.g. `corp.local`. Required. |
+| `project_id` | *none* | ID of the vRA project the deployment is created under. Required. |
+| `image_mapping` | *none* | Name of the vRA image mapping to deploy, e.g. `Ubuntu 22.04`. Required. |
+| `flavor_mapping` | *none* | Name of the vRA flavor mapping, which determines CPU and memory, e.g. `Small`. Required. |
+
+You must also identify the catalog item with either `catalog_id` or `catalog_name`.
+
+### Catalog item
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `catalog_id` | `nil` | ID of the catalog item to request. |
+| `catalog_name` | `nil` | Name of the catalog item to request, resolved to an ID. Use instead of `catalog_id`. |
+| `version` | `nil` | Version of the catalog item to request. Uses the latest if unset. |
+| `extra_parameters` | `{}` | Additional catalog request parameters, keyed by parameter name. See [Extra parameters](#extra-parameters). |
+
+### Credentials
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `username` | `$VRA_USER_NAME` | vRA username. Prompted for if not set anywhere. |
+| `password` | `$VRA_USER_PASSWORD` | vRA password. Prompted for if not set anywhere. |
+| `cache_credentials` | `false` | Cache credentials to disk after a successful run so later runs do not prompt. |
+| `verify_ssl` | `true` | Verify the appliance's TLS certificate. Only disable against a lab with a self-signed certificate. |
+| `tenant` | `nil` | **Deprecated.** Not used for authentication in vRA 8.x. Use `domain` instead. |
+
+### Deployment
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `deployment_name` | the platform name | Name given to the vRA deployment. Ignored when `unique_name` is enabled. |
+| `unique_name` | `false` | Name the deployment `deployment_<request id>` instead of using `deployment_name`, so concurrent runs do not collide. |
 
-Author:: Chef Partner Engineering (<partnereng@chef.io>)
+### Connectivity
 
-Copyright:: Copyright (c) 2022 Chef Software, Inc.
+| Option | Default | Description |
+| --- | --- | --- |
+| `use_dns` | `false` | Connect using the server's DNS name instead of its IP address. Needed when vRA does not report a reachable IP. |
+| `dns_suffix` | `nil` | Suffix appended to the server name when `use_dns` is enabled, e.g. `corp.local`. |
+| `private_key_path` | `~/.ssh/id_rsa` or `~/.ssh/id_dsa` | SSH private key used to connect. The first of those two files that exists is used. |
 
-License:: Apache License, Version 2.0
+### Timing
 
-Licensed under the Apache License, Version 2.0 (the "License"); you may not use
-this file except in compliance with the License. You may obtain a copy of the License at
+| Option | Default | Description |
+| --- | --- | --- |
+| `request_timeout` | `600` | Seconds to wait for the catalog request to complete. |
+| `request_refresh_rate` | `2` | Seconds between polls while waiting for the request. |
+| `server_ready_retries` | `1` | Number of times to retry when the server is reported ready but is not yet reachable. Increase this on slow environments. |
 
-```text
-http://www.apache.org/licenses/LICENSE-2.0
+## Extra parameters
+
+`extra_parameters` passes additional inputs to the catalog request. Each entry is
+keyed by the vRA parameter name, and gives the value along with its type:
+
+```yaml
+driver:
+  name: vra
+  base_url: https://vra.corp.local
+  domain: corp.local
+  project_id: 6ba69375-2d1e-4a5e-9e9b-1a1a3f0e6d4c
+  image_mapping: Ubuntu 22.04
+  flavor_mapping: Small
+  catalog_name: Ubuntu Server
+  extra_parameters:
+    environment:
+      type: string
+      value: test
+    disk_size:
+      type: integer
+      value: 40
+```
+
+## Examples
+
+### Selecting the catalog item by ID
+
+```yaml
+driver:
+  name: vra
+  base_url: https://vra.corp.local
+  domain: corp.local
+  project_id: 6ba69375-2d1e-4a5e-9e9b-1a1a3f0e6d4c
+  image_mapping: Ubuntu 22.04
+  flavor_mapping: Small
+  catalog_id: 9f4d4a7e-1234-4b8b-9c2f-77b6c9f0e111
+  version: "2"
+```
+
+### Running several suites at once
+
+Without `unique_name`, concurrent deployments share a name derived from the
+platform, which is confusing in the vRA UI and can collide.
+
+```yaml
+driver:
+  name: vra
+  base_url: https://vra.corp.local
+  domain: corp.local
+  project_id: 6ba69375-2d1e-4a5e-9e9b-1a1a3f0e6d4c
+  image_mapping: Ubuntu 22.04
+  flavor_mapping: Small
+  catalog_name: Ubuntu Server
+  unique_name: true
+```
+
+### Connecting by DNS name
+
+```yaml
+driver:
+  name: vra
+  base_url: https://vra.corp.local
+  domain: corp.local
+  project_id: 6ba69375-2d1e-4a5e-9e9b-1a1a3f0e6d4c
+  image_mapping: Ubuntu 22.04
+  flavor_mapping: Small
+  catalog_name: Ubuntu Server
+  use_dns: true
+  dns_suffix: corp.local
+```
+
+### A slow environment
+
+```yaml
+driver:
+  name: vra
+  base_url: https://vra.corp.local
+  domain: corp.local
+  project_id: 6ba69375-2d1e-4a5e-9e9b-1a1a3f0e6d4c
+  image_mapping: Ubuntu 22.04
+  flavor_mapping: Small
+  catalog_name: Ubuntu Server
+  request_timeout: 1800
+  request_refresh_rate: 10
+  server_ready_retries: 5
 ```
 
-Unless required by applicable law or agreed to in writing, software distributed under the
-License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
-either express or implied. See the License for the specific language governing permissions
-and limitations under the License.
+### Lab appliance with a self-signed certificate
+
+```yaml
+driver:
+  name: vra
+  base_url: https://vra.lab.local
+  domain: lab.local
+  project_id: 6ba69375-2d1e-4a5e-9e9b-1a1a3f0e6d4c
+  image_mapping: Ubuntu 22.04
+  flavor_mapping: Small
+  catalog_name: Ubuntu Server
+  verify_ssl: false
+```
+
+## Troubleshooting
+
+**"The vRA request created more than one server."** The driver requires a catalog
+item that provisions exactly one VM. Point it at a single-machine blueprint.
+
+**The request succeeds but Test Kitchen cannot connect.** vRA often reports a
+deployment as ready slightly before the guest accepts connections. Raise
+`server_ready_retries`. If vRA reports an unreachable IP, set `use_dns: true`
+along with `dns_suffix`.
+
+**Authentication fails on vRA 8.x.** Use `domain`, not `tenant`. The `tenant`
+option is deprecated and is not used for authentication in 8.x.
+
+## Using with Chef
+
+This driver is not tied to Cinc. The examples above use Cinc Workstation and the `cinc_infra` provisioner, but the driver works exactly the same with [Chef Workstation](https://www.chef.io/downloads/tools/workstation) — run `kitchen` instead of `cinc kitchen`, and use `chef_infra` instead of `cinc_infra`:
+
+```yaml
+provisioner:
+  name: chef_infra
+
+verifier:
+  name: inspec
+```
+
+No driver configuration changes are needed.
 
 ## Contributing
 
-We'd love to hear from you if this doesn't work in your vRA environment. Please log a GitHub issue, or even better, submit a Pull Request with a fix!
+We'd love to hear from you if this doesn't work in your vRA environment. Bug reports and pull requests are welcome on [GitHub](https://github.com/test-kitchen/kitchen-vra). See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, how to run the tests, and the release process.
+
+## License and Authors
+
+Author: Chef Partner Engineering (<partnereng@chef.io>)
 
-1. Fork it ( <https://github.com/chef-partners/kitchen-vra/fork> )
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create a new Pull Request
+Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for details.

data/Rakefile

@@ -3,13 +3,31 @@ require "rspec/core/rake_task"
 RSpec::Core::RakeTask.new(:test)
 
 begin
-  require "chefstyle"
+  require "cookstyle/chefstyle"
   require "rubocop/rake_task"
   RuboCop::RakeTask.new(:style) do |task|
     task.options += ["--display-cop-names", "--no-color"]
   end
 rescue LoadError
-  puts "chefstyle is not available. (sudo) gem install chefstyle to do style checking."
+  puts "cookstyle/chefstyle is not available. (sudo) gem install cookstyle to do style checking."
 end
 
 task default: %i{test style}
+
+begin
+  require "yard"
+
+  # Options and the file list live in .yardopts so that a bare `yard` from the
+  # command line produces exactly what `rake doc` does.
+  YARD::Rake::YardocTask.new(:doc)
+
+  desc "List anything in lib/ that is still undocumented"
+  task :doc_coverage do
+    sh "yard stats --list-undoc"
+  end
+rescue LoadError
+  desc "Generate YARD documentation (not installed)"
+  task :doc do
+    abort "YARD is not installed. Run: bundle install"
+  end
+end

data/kitchen-vra.gemspec

@@ -7,7 +7,7 @@ require "kitchen/driver/vra_version"
 Gem::Specification.new do |spec|
   spec.name          = "kitchen-vra"
   spec.version       = Kitchen::Driver::VRA_VERSION
-  spec.authors       = ["Chef Commmunity Tools Team"]
+  spec.authors       = ["Chef Community Tools Team"]
   spec.email         = ["oss@chef.io"]
   spec.summary       = "A Test Kitchen driver for VMware vRealize Automation (vRA)"
   spec.description   = spec.summary
@@ -16,7 +16,6 @@ Gem::Specification.new do |spec|
 
   spec.files         = `git ls-files -z`.split("\x0")
   spec.executables   = []
-  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 
   spec.required_ruby_version = ">= 3.1"

data/lib/kitchen/driver/vra.rb

@@ -22,16 +22,42 @@ require "kitchen"
 require "highline/import"
 require "openssl" unless defined?(OpenSSL)
 require "base64" unless defined?(Base64)
-require "digest/sha1" unless defined?(Digest::SHA1)
+require "digest" unless defined?(Digest)
+require "fileutils" unless defined?(FileUtils)
 require "vra"
 require_relative "vra_version"
 
 module Kitchen
+  # Test Kitchen's driver plugins.
   module Driver
+    # Test Kitchen driver for VMware vRealize Automation (vRA) 8.x.
+    #
+    # Unlike a cloud driver that creates a machine directly, this driver
+    # submits a request against a vRA catalog item and waits for vRA's own
+    # automation to build a deployment. The blueprint behind that catalog item
+    # decides what gets built; this driver only supplies the image, flavor,
+    # and project, then waits for a single VM to come back.
+    #
+    # The blueprint must return exactly one VM. A blueprint returning several,
+    # or none, fails the +create+ rather than guessing which one to test.
+    #
+    # @see https://www.vmware.com/products/vrealize-automation.html vRealize Automation
     class Vra < Kitchen::Driver::Base # rubocop:disable Metrics/ClassLength
       kitchen_driver_api_version 2
       plugin_version Kitchen::Driver::VRA_VERSION
 
+      # Location of the credential cache, relative to the working directory.
+      CREDENTIALS_CACHE_FILE = ".kitchen/cached_vra"
+
+      # Cipher used for the credential cache. GCM is authenticated, so a cache
+      # written for a different +base_url+, or one that has been altered on
+      # disk, fails to decrypt rather than yielding garbage credentials.
+      CREDENTIALS_CIPHER = "aes-256-gcm"
+
+      # Marker for the cache file layout, so a later format change can reject
+      # old files instead of misreading them.
+      CREDENTIALS_CACHE_VERSION = "v1"
+
       default_config :username, nil
       default_config :password, nil
       required_config :base_url
@@ -68,10 +94,20 @@ module Kitchen
         In vRA 8.x, the 'tenant' configuration is no longer relevant for authentication.
         Please use the 'domain' configuration in its place.".dup)
 
+      # @return [String] the driver's display name in `kitchen list`
       def name
         "vRA"
       end
 
+      # Resolves the vRA username and password, prompting if necessary.
+      #
+      # Sources are tried in order: explicit config, then the +VRA_USER_NAME+
+      # and +VRA_USER_PASSWORD+ environment variables, then the credential
+      # cache, then an interactive prompt.
+      #
+      # @param force_change [Boolean] prompt even if credentials already
+      #   resolved, used to re-ask after an authentication failure
+      # @return [void]
       def check_config(force_change = false)
         config[:username] = config[:username] || ENV["VRA_USER_NAME"]
         config[:password] = config[:password] || ENV["VRA_USER_PASSWORD"]
@@ -82,43 +118,104 @@ module Kitchen
         c_save if config[:cache_credentials]
       end
 
+      # Writes the resolved credentials to {CREDENTIALS_CACHE_FILE}.
+      #
+      # The file is obfuscated rather than secured: the key is derived from
+      # +base_url+, which is not a secret, so anyone holding both the file and
+      # the kitchen config can recover the credentials. It keeps passwords out
+      # of plain sight on disk; it is not a substitute for a secret store.
+      #
+      # @return [void]
       def c_save
-        cipher = OpenSSL::Cipher.new("cip-her-aes")
-        cipher.encrypt
-        cipher.key = Digest::SHA1.hexdigest(config[:base_url])
-        iv_user = cipher.random_iv
-        cipher.iv = iv_user
-        username = cipher.update(config[:username]) + cipher.final
-        iv_pwd = cipher.random_iv
-        cipher.iv = iv_pwd
-        password = cipher.update(config[:password]) + cipher.final
-        output = "#{Base64.encode64(iv_user).strip!}:#{Base64.encode64(username).strip!}:#{Base64.encode64(iv_pwd).strip!}:#{Base64.encode64(password).strip!}"
-        file = File.open(".kitchen/cached_vra", "w")
-        file.write(output)
-        file.close
-      rescue
-        puts "Unable to save credentials"
+        FileUtils.mkdir_p(File.dirname(CREDENTIALS_CACHE_FILE))
+        fields = [config[:username], config[:password]].flat_map { |value| encrypt_credential(value) }
+
+        File.open(CREDENTIALS_CACHE_FILE, File::WRONLY | File::CREAT | File::TRUNC, 0o600) do |file|
+          file.write(([CREDENTIALS_CACHE_VERSION] + fields).join(":"))
+        end
+        # The mode above only applies when the file is created, so narrow the
+        # permissions of a cache left behind by an earlier run as well.
+        File.chmod(0o600, CREDENTIALS_CACHE_FILE)
+      rescue => e
+        warn("Unable to save credentials to #{CREDENTIALS_CACHE_FILE}: #{e.message}")
       end
 
+      # Reads credentials back from {CREDENTIALS_CACHE_FILE}.
+      #
+      # A cache that cannot be decrypted -- a different +base_url+, a truncated
+      # or edited file, an older layout -- is reported and ignored, leaving the
+      # credentials unset so the caller falls through to prompting.
+      #
+      # @return [void]
       def c_load
-        if File.exist? ".kitchen/cached_vra"
-          encrypted = File.read(".kitchen/cached_vra")
-          iv_user = Base64.decode64(encrypted.split(":")[0] + '\n')
-          username = Base64.decode64(encrypted.split(":")[1] + "\n")
-          iv_pwd = Base64.decode64(encrypted.split(":")[2] + "\n")
-          password = Base64.decode64(encrypted.split(":")[3] + "\n")
-          cipher = OpenSSL::Cipher.new("cip-her-aes")
-          cipher.decrypt
-          cipher.key = Digest::SHA1.hexdigest(config[:base_url])
-          cipher.iv = iv_user
-          config[:username] = cipher.update(username) + cipher.final
-          cipher.iv = iv_pwd
-          config[:password] = cipher.update(password) + cipher.final
-        end
-      rescue
-        puts "Failed to load cached credentials"
+        return unless File.exist?(CREDENTIALS_CACHE_FILE)
+
+        version, *fields = File.read(CREDENTIALS_CACHE_FILE).strip.split(":")
+        raise "unrecognized cache format" unless version == CREDENTIALS_CACHE_VERSION && fields.length == 6
+
+        # Decrypt both before assigning either, so a partially readable cache
+        # cannot leave half the credentials set.
+        username = decrypt_credential(*fields[0, 3])
+        password = decrypt_credential(*fields[3, 3])
+
+        config[:username] = username
+        config[:password] = password
+      rescue => e
+        warn("Failed to load cached credentials from #{CREDENTIALS_CACHE_FILE}: #{e.message}")
+      end
+
+      # Encrypts one credential for the cache file.
+      #
+      # @param value [String] the credential to encrypt
+      # @return [Array<String>] Base64-encoded IV, authentication tag, and
+      #   ciphertext, in that order
+      def encrypt_credential(value)
+        cipher = OpenSSL::Cipher.new(CREDENTIALS_CIPHER)
+        cipher.encrypt
+        cipher.key = credentials_key
+        iv = cipher.random_iv
+        encrypted = cipher.update(value.to_s) + cipher.final
+
+        [iv, cipher.auth_tag, encrypted].map { |part| Base64.strict_encode64(part) }
+      end
+
+      # Decrypts one credential from the cache file.
+      #
+      # @param iv [String] Base64-encoded initialization vector
+      # @param auth_tag [String] Base64-encoded GCM authentication tag
+      # @param encrypted [String] Base64-encoded ciphertext
+      # @return [String] the decrypted credential
+      # @raise [OpenSSL::Cipher::CipherError] if the key or tag does not match
+      def decrypt_credential(iv, auth_tag, encrypted)
+        cipher = OpenSSL::Cipher.new(CREDENTIALS_CIPHER)
+        cipher.decrypt
+        cipher.key = credentials_key
+        cipher.iv = Base64.strict_decode64(iv)
+        cipher.auth_tag = Base64.strict_decode64(auth_tag)
+
+        cipher.update(Base64.strict_decode64(encrypted)) + cipher.final
+      end
+
+      # Derives the cache key from +base_url+.
+      #
+      # SHA-256 is used for its digest length: {CREDENTIALS_CIPHER} requires a
+      # 32-byte key, which +Digest::SHA256.digest+ returns exactly.
+      #
+      # @return [String] a 32-byte key
+      def credentials_key
+        Digest::SHA256.digest(config[:base_url].to_s)
       end
 
+      # Requests a deployment from vRA and waits until it can be logged into.
+      #
+      # Returns immediately if the state already names a deployment, so a
+      # re-run does not build a second one.
+      #
+      # @param state [Hash] mutable instance state; gains +deployment_id+,
+      #   +hostname+, and +ssh_key+
+      # @return [void]
+      # @raise [RuntimeError] if the vRA request fails or does not yield
+      #   exactly one VM
       def create(state)
         return if state[:deployment_id]
 
@@ -131,6 +228,15 @@ module Kitchen
         info("Server #{server.deployment_id} (#{server.name}) ready.")
       end
 
+      # Works out the address Test Kitchen should connect to.
+      #
+      # With +use_dns+ set, the server's name is used, optionally suffixed with
+      # +dns_suffix+. Otherwise the IP address is preferred, falling back to
+      # the name with a warning when vRA reports no address.
+      #
+      # @param server [Vra::Resource] the VM vRA built
+      # @return [String] a hostname or IP address
+      # @raise [RuntimeError] if +use_dns+ is set but vRA returned no name
       def hostname_for(server)
         if config[:use_dns]
           raise "No server name returned for the vRA request" if server.name.nil?
@@ -147,6 +253,11 @@ module Kitchen
         end
       end
 
+      # Submits the catalog request and waits for vRA to finish building it.
+      #
+      # @return [Vra::Resource] the single VM the blueprint produced
+      # @raise [RuntimeError] if the request failed, or produced zero or more
+      #   than one VM
       def request_server
         info("Building vRA catalog request...")
 
@@ -167,6 +278,16 @@ module Kitchen
         servers.first
       end
 
+      # Waits for the transport to accept a connection, retrying on failure.
+      #
+      # Backs off in five-second steps up to thirty seconds between attempts.
+      # Once +server_ready_retries+ is exceeded the deployment is destroyed
+      # before the error is re-raised, so a machine that never comes up is not
+      # left running and billable.
+      #
+      # @param state [Hash] instance state describing how to connect
+      # @param server [Vra::Resource] the VM being waited on
+      # @return [void]
       def wait_for_server(state, server)
         info("Server #{server.id} (#{server.name}) created. Waiting until ready...")
 
@@ -193,6 +314,14 @@ module Kitchen
         end
       end
 
+      # Destroys the vRA deployment, if one exists.
+      #
+      # A deployment that vRA no longer knows about, or that offers no destroy
+      # action, is treated as already gone rather than an error. The cached
+      # credentials file is removed afterwards.
+      #
+      # @param state [Hash] instance state naming the deployment
+      # @return [void]
       def destroy(state)
         return if state[:deployment_id].nil?
 
@@ -217,6 +346,14 @@ module Kitchen
         info("Removed cached file")
       end
 
+      # Builds the vRA catalog request for the configured blueprint.
+      #
+      # When +catalog_name+ is given it is resolved to a catalog ID first.
+      # A deployment name is only sent when +unique_name+ is false; otherwise
+      # vRA is left to name the deployment after its request ID.
+      #
+      # @return [Vra::CatalogRequest] a request ready to submit
+      # @raise [Kitchen::InstanceFailure] if no catalog could be resolved
       def catalog_request # rubocop:disable Metrics/MethodLength
         unless config[:catalog_name].nil?
           info("Fetching Catalog ID by Catalog Name")
@@ -251,6 +388,12 @@ module Kitchen
         catalog_request
       end
 
+      # The vRA API client, built from the resolved credentials.
+      #
+      # On any failure the credentials are re-prompted, on the assumption that
+      # what failed was authentication.
+      #
+      # @return [Vra::Client]
       def vra_client
         check_config config[:cache_credentials]
         @client ||= ::Vra::Client.new(
@@ -264,6 +407,14 @@ module Kitchen
         check_config true
       end
 
+      # Polls a vRA request until it completes or times out.
+      #
+      # Polls every +request_refresh_rate+ seconds, logging each change of
+      # status, and gives up after +request_timeout+ seconds.
+      #
+      # @param request [Vra::Request] the request to poll
+      # @return [void]
+      # @raise [Timeout::Error] if the request does not complete in time
       def wait_for_request(request)
         # config = check_config config