kitchen-vra 3.3.3 → 3.4.0

data/lib/kitchen/driver/vra.rb

@@ -22,16 +22,48 @@ 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 "time" unless defined?(Time.now.iso8601)
 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
 
+      # Deployment statuses vRA reports for a deployment that is up.
+      #
+      # @return [Array<String>]
+      LIVE_STATUSES = %w{CREATE_SUCCESSFUL}.freeze
+
+      # 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 +100,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 +124,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 +234,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 +259,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 +284,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 +320,49 @@ module Kitchen
         end
       end
 
+      # Reports what vRA currently thinks of the deployment.
+      #
+      # @param state [Hash] instance state naming the deployment
+      # @return [Hash] a Test Kitchen status hash, or the base implementation's
+      #   answer when there is no deployment or vRA does not know it
+      def status(state)
+        return super unless state[:deployment_id]
+
+        deployment = lookup_deployment(state[:deployment_id])
+        return super unless deployment
+
+        deployment_status = deployment.status.to_s
+        {
+          live: LIVE_STATUSES.include?(deployment_status),
+          state: deployment_status,
+          source: "driver",
+          resource_id: state[:deployment_id],
+          message: "vRA reports the deployment as #{deployment_status}",
+          checked_at: Time.now.utc.iso8601,
+        }
+      end
+
+      # Looks a deployment up without turning an unreachable vRA into a
+      # failure. A deployment that has already been destroyed answers with
+      # NotFound, which is a real answer rather than an error.
+      #
+      # @param deployment_id [String] the vRA deployment ID
+      # @return [Vra::Deployment, nil] the deployment, or nil when vRA does not
+      #   know it or cannot be reached
+      def lookup_deployment(deployment_id)
+        vra_client.deployments.by_id(deployment_id)
+      rescue ::StandardError
+        nil
+      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 +387,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 +429,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 +448,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.3"
+    # The version of the kitchen-vra gem.
+    VRA_VERSION = "3.4.0"
   end
 end

data/renovate.json

@@ -1,6 +1,8 @@
 {
   "$schema": "https://docs.renovatebot.com/renovate-schema.json",
   "extends": [
-    "config:recommended"
+    "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"
@@ -328,6 +330,64 @@ describe Kitchen::Driver::Vra do
     end
   end
 
+  describe "#status" do
+    let(:deployments) { double("deployments") }
+    let(:vra_client)  { double("vra_client", deployments: deployments) }
+
+    before { allow(driver).to receive(:vra_client).and_return(vra_client) }
+
+    it "reports an unknown status when state names no deployment" do
+      expect(driver.status({})).to include(live: nil, state: "unknown")
+    end
+
+    it "reports an unknown status when vRA has never heard of the deployment" do
+      allow(deployments).to receive(:by_id).with("gone")
+        .and_raise(Vra::Exception::NotFound.new("nope"))
+
+      expect(driver.status(deployment_id: "gone")).to include(state: "unknown")
+    end
+
+    it "reports a successfully created deployment as live" do
+      allow(deployments).to receive(:by_id).with("dep-1")
+        .and_return(double(status: "CREATE_SUCCESSFUL"))
+
+      expect(driver.status(deployment_id: "dep-1")).to include(
+        live: true, state: "CREATE_SUCCESSFUL", source: "driver",
+        resource_id: "dep-1"
+      )
+    end
+
+    it "stamps when the check happened" do
+      allow(deployments).to receive(:by_id)
+        .and_return(double(status: "CREATE_SUCCESSFUL"))
+
+      expect(driver.status(deployment_id: "dep-1")[:checked_at])
+        .to match(/\A\d{4}-\d{2}-\d{2}T/)
+    end
+
+    it "reports a deployment still building as not live" do
+      allow(deployments).to receive(:by_id)
+        .and_return(double(status: "CREATE_INPROGRESS"))
+
+      expect(driver.status(deployment_id: "dep-1"))
+        .to include(live: false, state: "CREATE_INPROGRESS")
+    end
+
+    it "names a failed deployment rather than reporting a bare false" do
+      allow(deployments).to receive(:by_id)
+        .and_return(double(status: "CREATE_FAILED"))
+
+      expect(driver.status(deployment_id: "dep-1"))
+        .to include(live: false, state: "CREATE_FAILED")
+    end
+
+    it "reports an unknown status when vRA cannot be reached" do
+      allow(deployments).to receive(:by_id).and_raise(StandardError.new("boom"))
+
+      expect(driver.status(deployment_id: "dep-1")).to include(state: "unknown")
+    end
+  end
+
   describe "#destroy" do
     let(:deployment_id)     { "8c1a833a-5844-4100-b58c-9cab3543c958" }
     let(:state)           { { deployment_id: deployment_id } }
@@ -447,7 +507,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 +570,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.3
+  version: 3.4.0
 platform: ruby
 authors:
-- Chef Commmunity Tools Team
+- Chef Community Tools Team
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-06-27 00:00:00.000000000 Z
+date: 2026-08-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: test-kitchen
@@ -16,14 +16,20 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '3.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '3.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5'
 - !ruby/object:Gem::Dependency
   name: vmware-vra
   requirement: !ruby/object:Gem::Requirement
@@ -58,26 +64,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: rack
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '1.6'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '4.0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '1.6'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '4.0'
 - !ruby/object:Gem::Dependency
   name: ffi-yajl
   requirement: !ruby/object:Gem::Requirement
@@ -106,14 +92,16 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".github/CODEOWNERS"
-- ".github/dependabot.yml"
 - ".github/workflows/linters.yml"
 - ".github/workflows/publish.yml"
 - ".gitignore"
 - ".markdownlint.yaml"
 - ".release-please-manifest.json"
 - ".rubocop.yml"
+- ".yamllint"
+- ".yardopts"
 - CHANGELOG.md
+- CONTRIBUTING.md
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -144,10 +132,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
+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