kitchen-vra 3.3.2 → 3.3.4

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
 

data/lib/kitchen/driver/vra_version.rb

@@ -18,8 +18,11 @@
 # limitations under the License.
 #
 
+# Test Kitchen's top-level namespace.
 module Kitchen
+  # Test Kitchen's driver plugins.
   module Driver
-    VRA_VERSION = "3.3.2"
+    # The version of the kitchen-vra gem.
+    VRA_VERSION = "3.3.4"
   end
 end

data/release-please-config.json

@@ -0,0 +1,12 @@
+{
+  "packages": {
+    ".": {
+      "package-name": "kitchen-vra",
+      "changelog-path": "CHANGELOG.md",
+      "release-type": "ruby",
+      "include-component-in-tag": false,
+      "version-file": "lib/kitchen/driver/vra_version.rb"
+    }
+  },
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json"
+}

data/renovate.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": [
+    "config:recommended",
+    ":disableDependencyDashboard",
+    "schedule:automergeEarlyMondays"
+  ]
+}

data/spec/vra_spec.rb

@@ -19,6 +19,8 @@
 #
 
 require "spec_helper"
+require "tmpdir"
+require "fileutils"
 require "kitchen/driver/vra"
 require "kitchen/provisioner/dummy"
 require "kitchen/transport/dummy"
@@ -447,7 +449,7 @@ describe Kitchen::Driver::Vra do
         }
       end
 
-      it "sets extra parmeters" do
+      it "sets extra parameters" do
         expect(catalog_request).to receive(:set_parameters).with("key1", { type: "string", value: "value1" })
         expect(catalog_request).to receive(:set_parameters).with("key2", { type: "integer", value: 123 })
         driver.catalog_request
@@ -510,4 +512,99 @@ describe Kitchen::Driver::Vra do
       end
     end
   end
+
+  describe "credential caching" do
+    let(:cache_dir)  { Dir.mktmpdir("kitchen-vra-spec") }
+    let(:cache_file) { File.join(cache_dir, ".kitchen", "cached_vra") }
+
+    # c_save/c_load address the cache by a path relative to the working
+    # directory, so each example runs inside a throwaway directory.
+    around do |example|
+      Dir.chdir(cache_dir) { example.run }
+    end
+
+    after { FileUtils.remove_entry(cache_dir) }
+
+    describe "#c_save" do
+      it "creates the cache file" do
+        driver.c_save
+        expect(File.exist?(cache_file)).to be true
+      end
+
+      it "creates the .kitchen directory when it does not exist" do
+        expect { driver.c_save }.to change { Dir.exist?(File.join(cache_dir, ".kitchen")) }.from(false).to(true)
+      end
+
+      it "writes the file readable only by its owner" do
+        driver.c_save
+        expect(File.stat(cache_file).mode & 0o777).to eq(0o600)
+      end
+
+      it "does not write the password in the clear" do
+        driver.c_save
+        expect(File.read(cache_file)).not_to include("mypassword")
+      end
+    end
+
+    describe "#c_load" do
+      it "restores credentials written by #c_save" do
+        driver.c_save
+
+        reader = Kitchen::Driver::Vra.new(config.reject { |k, _v| %i{username password}.include?(k) })
+        allow(reader).to receive(:instance).and_return(instance)
+        reader.c_load
+
+        expect(reader[:username]).to eq("myuser")
+        expect(reader[:password]).to eq("mypassword")
+      end
+
+      it "does nothing when no cache file exists" do
+        driver.c_load
+        expect(driver[:username]).to eq("myuser")
+      end
+
+      it "refuses a cache written against a different base_url" do
+        driver.c_save
+
+        other = Kitchen::Driver::Vra.new(config.merge(base_url: "https://other.corp.local")
+                                               .reject { |k, _v| %i{username password}.include?(k) })
+        allow(other).to receive(:instance).and_return(instance)
+        expect(other).to receive(:warn).with(/Failed to load cached credentials/)
+        other.c_load
+
+        expect(other[:username]).to be_nil
+        expect(other[:password]).to be_nil
+      end
+
+      it "refuses a corrupted cache rather than returning garbage" do
+        driver.c_save
+        File.write(cache_file, File.read(cache_file).succ)
+
+        loader = Kitchen::Driver::Vra.new(config.reject { |k, _v| %i{username password}.include?(k) })
+        allow(loader).to receive(:instance).and_return(instance)
+        expect(loader).to receive(:warn).with(/Failed to load cached credentials/)
+        loader.c_load
+
+        expect(loader[:username]).to be_nil
+      end
+    end
+
+    describe "#check_config" do
+      it "uses the cache instead of prompting" do
+        driver.c_save
+
+        reader = Kitchen::Driver::Vra.new(config.reject { |k, _v| %i{username password}.include?(k) })
+        allow(reader).to receive(:instance).and_return(instance)
+        allow(ENV).to receive(:[]).and_call_original
+        allow(ENV).to receive(:[]).with("VRA_USER_NAME").and_return(nil)
+        allow(ENV).to receive(:[]).with("VRA_USER_PASSWORD").and_return(nil)
+        expect(reader).not_to receive(:ask)
+
+        reader.check_config
+
+        expect(reader[:username]).to eq("myuser")
+        expect(reader[:password]).to eq("mypassword")
+      end
+    end
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kitchen-vra
 version: !ruby/object:Gem::Version
-  version: 3.3.2
+  version: 3.3.4
 platform: ruby
 authors:
-- Chef Commmunity Tools Team
+- Chef Community Tools Team
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-07-05 00:00:00.000000000 Z
+date: 2026-08-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: test-kitchen
@@ -87,7 +87,7 @@ dependencies:
         version: 2.2.3
     - - "<"
       - !ruby/object:Gem::Version
-        version: 2.5.0
+        version: 3.1.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -97,77 +97,7 @@ dependencies:
         version: 2.2.3
     - - "<"
       - !ruby/object:Gem::Version
-        version: 2.5.0
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '13.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '13.0'
-- !ruby/object:Gem::Dependency
-  name: rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.2'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.2'
-- !ruby/object:Gem::Dependency
-  name: simplecov
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.10'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.10'
-- !ruby/object:Gem::Dependency
-  name: webmock
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.14'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.14'
-- !ruby/object:Gem::Dependency
-  name: chefstyle
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 2.2.1
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 2.2.1
+        version: 3.1.0
 description: A Test Kitchen driver for VMware vRealize Automation (vRA)
 email:
 - oss@chef.io
@@ -176,15 +106,16 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".github/CODEOWNERS"
-- ".github/dependabot.yml"
 - ".github/workflows/linters.yml"
-- ".github/workflows/please-release.yml"
 - ".github/workflows/publish.yml"
 - ".gitignore"
 - ".markdownlint.yaml"
-- ".mdlrc"
+- ".release-please-manifest.json"
 - ".rubocop.yml"
+- ".yamllint"
+- ".yardopts"
 - CHANGELOG.md
+- CONTRIBUTING.md
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -192,6 +123,8 @@ files:
 - kitchen-vra.gemspec
 - lib/kitchen/driver/vra.rb
 - lib/kitchen/driver/vra_version.rb
+- release-please-config.json
+- renovate.json
 - spec/spec_helper.rb
 - spec/vra_spec.rb
 homepage: https://github.com/test-kitchen/kitchen-vra
@@ -206,17 +139,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.7'
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.3
+rubygems_version: 3.5.9
 signing_key:
 specification_version: 4
 summary: A Test Kitchen driver for VMware vRealize Automation (vRA)
-test_files:
-- spec/spec_helper.rb
-- spec/vra_spec.rb
+test_files: []

data/.github/dependabot.yml

@@ -1,8 +0,0 @@
----
-version: 2
-updates:
-  - package-ecosystem: bundler
-    directory: "/"
-    schedule:
-      interval: daily
-    open-pull-requests-limit: 10

data/.github/workflows/please-release.yml

@@ -1,16 +0,0 @@
----
-'on':
-  push:
-    branches:
-      - main
-
-name: release-please
-jobs:
-  release-please:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: google-github-actions/release-please-action@v3
-        with:
-          release-type: ruby
-          package-name: kitchen-vra
-          version-file: lib/kitchen/driver/vra_version.rb

data/.mdlrc

@@ -1 +0,0 @@
-rules "~MD036", "~MD013", "~MD024", "~MD029"