kitchen-azurerm 2.1.4 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 65f0cc54a62e738484f2f5469a37e476e0323bdd0ac59ef180e99a05de3fa0c8
-  data.tar.gz: dce34ba2cec4675d575aa4607f9b00874d4e504f8d5c7ee1ce1b18d1311b4434
+  metadata.gz: fbc95dc73706d3eb94349e23d021b1747f838b1dde2ea375d3be1fe2d27b920d
+  data.tar.gz: 6719ba4591a556c5eeb6a1187d21fddd5ad2b72e4faf74b8fc5d483158c09ad1
 SHA512:
-  metadata.gz: cdf17e7f3013d461390749209072afbf0a7f8ef7969853467a66cd7b90471226b9848a36d89212c7148681cfcb27aa96bb5ac7d3e2e9e9ca38ac3d8839d7d987
-  data.tar.gz: 25d1728326d14b31470120ee867263fbf814ffe6758946705b64391c7948031fbefbbafc123baa23ea4f404089d16d30cecf3117c2bc9867a1e0dfab2fac33d3
+  metadata.gz: fbda874b618647705e59cd47b1ae9ef4f128b7bdfacebef707824eabc158f875b011ae666c33b5e6bff478553af14fc9206f7c23bcc41b0955c58f3b6b57fc70
+  data.tar.gz: 654610bdad5017605ece2dbede6907952b605e7607f5024a8e15a6f3e786af8b69ef8b19dfab78f79898afe945cf4415f5600806c1bbedf4edc8b2125b845828

data/lib/kitchen/driver/azure/arm_client.rb

@@ -25,6 +25,18 @@ module Kitchen
         # @return [String]
         NETWORK_API_VERSION = "2025-07-01".freeze
 
+        # ARM API version used for compute resource requests. Matches the
+        # version the bundled deployment templates declare for virtual
+        # machines.
+        #
+        # @return [String]
+        COMPUTE_API_VERSION = "2025-04-01".freeze
+
+        # ARM API version used to read the subscription itself.
+        #
+        # @return [String]
+        SUBSCRIPTION_API_VERSION = "2022-12-01".freeze
+
         # @param subscription_id [String]
         # @param environment [Environments::Environment]
         # @param token_provider [TokenProvider]
@@ -43,6 +55,19 @@ module Kitchen
         # @return [TokenProvider]
         attr_reader :token_provider
 
+        # Reads the subscription itself.
+        #
+        # Unlike a resource group HEAD - which answers 404 both for a
+        # subscription that does not exist and for one that merely has no such
+        # group - this distinguishes a reachable subscription from a wrong
+        # one, so it is what {Azurerm#doctor} probes with.
+        #
+        # @return [Hash]
+        def subscription
+          call(:get, "/subscriptions/#{escape(subscription_id)}",
+            api_version: SUBSCRIPTION_API_VERSION).json
+        end
+
         # Whether a resource group exists.
         #
         # @param name [String] resource group name, case-insensitive.
@@ -115,6 +140,17 @@ module Kitchen
           payload.is_a?(Hash) ? Array(payload["value"]) : []
         end
 
+        # Reads a virtual machine's instance view, which carries its current
+        # power state.
+        #
+        # @param resource_group [String]
+        # @param name [String] virtual machine name.
+        # @return [Hash]
+        def virtual_machine_instance_view(resource_group, name)
+          call(:get, "#{compute_path(resource_group, "virtualMachines", name)}/instanceView",
+            api_version: COMPUTE_API_VERSION).json
+        end
+
         # Reads a public IP address resource.
         #
         # @param resource_group [String]
@@ -158,6 +194,14 @@ module Kitchen
           "#{resource_group_path(resource_group)}/providers/Microsoft.Network/#{type}/#{escape(name)}"
         end
 
+        # @param resource_group [String]
+        # @param type [String] e.g. +"virtualMachines"+.
+        # @param name [String]
+        # @return [String]
+        def compute_path(resource_group, type, name)
+          "#{resource_group_path(resource_group)}/providers/Microsoft.Compute/#{type}/#{escape(name)}"
+        end
+
         # @param value [String]
         # @return [String] path-escaped
         def escape(value)

data/lib/kitchen/driver/azure/errors.rb

@@ -40,6 +40,17 @@ module Kitchen
         def code
           body.is_a?(Hash) ? body.dig("error", "code") : nil
         end
+
+        # Azure's own explanation, when ARM supplied one.
+        #
+        # +message+ is this class's summary of the request that failed; this
+        # is what Azure said about it, which is usually the part worth showing
+        # somebody.
+        #
+        # @return [String, nil]
+        def detail
+          body.is_a?(Hash) ? body.dig("error", "message") : nil
+        end
       end
 
       # Raised when a request could not be completed and is worth retrying:

data/lib/kitchen/driver/azurerm.rb

@@ -66,8 +66,12 @@ module Kitchen
 
       # Ubuntu 22.04 LTS, generation 2. Canonical renamed their offers after
       # 18.04, so the old "UbuntuServer" offer no longer resolves at all.
+      #
+      # @return [String]
+      DEFAULT_IMAGE_URN = "Canonical:0001-com-ubuntu-server-jammy:22_04-lts-gen2:latest".freeze
+
       default_config(:image_urn) do |_config|
-        "Canonical:0001-com-ubuntu-server-jammy:22_04-lts-gen2:latest"
+        DEFAULT_IMAGE_URN
       end
 
       default_config(:image_id) do |_config|
@@ -273,12 +277,12 @@ module Kitchen
         end
 
         begin
-          run_deployment(state, "pre-deploy", pre_deployment(config[:pre_deployment_template], config[:pre_deployment_parameters])) if File.file?(config[:pre_deployment_template])
+          run_deployment(state, "pre-deploy", pre_deployment(config[:pre_deployment_template], config[:pre_deployment_parameters])) if File.file?(config[:pre_deployment_template].to_s)
 
           run_deployment(state, "deploy", deployment(deployment_parameters))
           store_deployment_credentials(state, deployment_parameters)
 
-          run_deployment(state, "post-deploy", post_deployment(config[:post_deployment_template], config[:post_deployment_parameters])) if File.file?(config[:post_deployment_template])
+          run_deployment(state, "post-deploy", post_deployment(config[:post_deployment_template], config[:post_deployment_parameters])) if File.file?(config[:post_deployment_template].to_s)
         rescue Azure::OperationError => operation_error
           info operation_error.body["error"]
           raise operation_error
@@ -287,6 +291,78 @@ module Kitchen
         state[:hostname] = resolve_hostname(state, deployment_parameters["nicName"])
       end
 
+      # Settings the driver cannot supply a default for, and what they are.
+      #
+      # @return [Hash{Symbol => String}]
+      REQUIRED_CONFIG = {
+        subscription_id: "the Azure subscription to deploy into",
+        location: "the Azure region to deploy into, e.g. eastus",
+        machine_size: "the VM size to deploy, e.g. Standard_D2s_v3",
+      }.freeze
+
+      # Checks configuration and credentials, for +kitchen doctor+.
+      #
+      # Deployment failures are usually one of two things: a required setting
+      # nobody filled in, or credentials that do not work. Both otherwise
+      # surface as an Azure error partway through a create, once the resource
+      # group already exists, so this looks for them up front.
+      #
+      # @param state [Hash] the instance state, unused - the checks are about
+      #   configuration and credentials, which exist before any instance does.
+      # @return [Boolean] true when a problem was found, as +kitchen doctor+
+      #   expects.
+      def doctor(_state)
+        problems = missing_required_config
+        problems += unreachable_azure if problems.empty?
+        problems.each { |problem| error("kitchen-azurerm: #{problem}") }
+        problems.any?
+      end
+
+      # Required settings that were left unset.
+      #
+      # @return [Array<String>]
+      def missing_required_config
+        REQUIRED_CONFIG.select { |option, _| config[option].to_s.empty? }
+          .map { |option, purpose| "#{option} is not set. It has no default: give it #{purpose}." }
+      end
+
+      # Whether Azure answers, accepts the credentials, and knows the
+      # subscription.
+      #
+      # Reads the subscription rather than probing a resource group: ARM
+      # answers a resource group HEAD with 404 both for a subscription that
+      # does not exist and for one that merely has no such group, so it cannot
+      # tell a wrong subscription from a healthy one. Reading the subscription
+      # gives back either its details or +SubscriptionNotFound+.
+      #
+      # @return [Array<String>]
+      def unreachable_azure
+        Kitchen::Driver::AzureCredentials.new(subscription_id: config[:subscription_id],
+          environment: config[:azure_environment]).arm_client.subscription
+        []
+      rescue Azure::OperationError => operation_error
+        [azure_problem(operation_error)]
+      rescue Azure::TransientError => transient_error
+        ["Could not reach Azure (#{transient_error.message})."]
+      end
+
+      # Describes an OperationError raised while checking Azure.
+      #
+      # An error carrying no Azure error code never reached ARM - it comes
+      # from acquiring the token, and already explains itself. Announcing that
+      # Azure rejected a request that was never made only sends the reader
+      # looking in the wrong place.
+      #
+      # @param operation_error [Azure::OperationError]
+      # @return [String]
+      def azure_problem(operation_error)
+        return operation_error.message unless operation_error.code
+
+        "Azure rejected the request (#{operation_error.code}: " \
+          "#{operation_error.detail || operation_error.message}). " \
+          "Check the credentials, and that they can reach subscription #{config[:subscription_id]}."
+      end
+
       # Builds the ARM parameter values for the virtual machine deployment.
       #
       # @param state [Hash] instance state, already through {#validate_state}.
@@ -329,10 +405,23 @@ module Kitchen
       def image_parameters
         return { "imageId" => config[:image_id] } if config[:image_id].to_s != ""
 
-        publisher, offer, sku, version = config[:image_urn].split(":", 4)
+        publisher, offer, sku, version = image_urn.split(":", 4)
         { "imagePublisher" => publisher, "imageOffer" => offer, "imageSku" => sku, "imageVersion" => version }
       end
 
+      # The Marketplace image URN to deploy from.
+      #
+      # An +image_urn:+ written with no value is nil rather than "", which
+      # counts as unset here the way it does everywhere else in the driver -
+      # so it falls back to {DEFAULT_IMAGE_URN} rather than failing with a
+      # Ruby error naming neither the setting nor the file it came from.
+      #
+      # @return [String]
+      def image_urn
+        urn = config[:image_urn].to_s
+        urn.empty? ? DEFAULT_IMAGE_URN : urn
+      end
+
       # The OS disk size, as a number ARM will accept.
       #
       # YAML makes +os_disk_size_gb: 64+ an Integer and +os_disk_size_gb: "64"+
@@ -451,11 +540,20 @@ module Kitchen
 
       # Whether a state property is already populated.
       #
+      # A blank value does not count. A run that fails early still writes its
+      # state, so an empty +subscription_id+ - which is what a quoted ERB
+      # interpolation of an unset variable produces - used to be taken as
+      # authoritative from then on, shadowing the real value in config for the
+      # rest of the instance's life.
+      #
+      # +false+ is a value, so this asks whether the value is blank rather
+      # than whether it is truthy.
+      #
       # @param state [Hash] Hash of existing state values.
       # @param property [Symbol, String] the property to check.
-      # @return [Boolean] true when the key exists and its value is not nil.
+      # @return [Boolean] true when the key exists and its value is not blank.
       def existing_state_value?(state, property)
-        state.key?(property) && !state[property].nil?
+        state.key?(property) && !state[property].to_s.empty?
       end
 
       # Fills in any state values that are not already present.
@@ -605,7 +703,12 @@ module Kitchen
         KEY_GENERATION_MUTEX.synchronize do
           generate_key_pair(private_key_filename) unless File.file?(private_key_filename)
 
-          public_key_filename = instance.transport[:ssh_public_key] || "#{private_key_filename}.pub"
+          explicit = instance.transport[:ssh_public_key]
+          public_key_filename = explicit || "#{private_key_filename}.pub"
+          unless File.file?(public_key_filename)
+            raise Kitchen::UserError, missing_public_key_message(private_key_filename, public_key_filename, explicit)
+          end
+
           File.read(public_key_filename).strip
         end
       end
@@ -626,6 +729,33 @@ module Kitchen
         File.chmod(0600, "#{private_key_filename}.pub")
       end
 
+      # Explains that the public half of the transport's key could not be found.
+      #
+      # +ssh_key+ names the *private* key, so a user who keeps only that has
+      # nothing wrong with their kitchen.yml. They used to get a raw
+      # Errno::ENOENT for a ".pub" path they never wrote, with nothing to say
+      # where it came from or what to do about it.
+      #
+      # The key cannot simply be derived: sshkey only reads PEM-encoded RSA,
+      # while ssh-keygen has emitted the OpenSSH format by default since 7.8
+      # and ed25519 keys are never PEM. +ssh-keygen -y+ handles every format,
+      # so point at that instead.
+      #
+      # @param private_key_filename [String] the configured private key.
+      # @param public_key_filename [String] where the public key was looked for.
+      # @param explicit [String, nil] +ssh_public_key+, when the user set it.
+      # @return [String]
+      def missing_public_key_message(private_key_filename, public_key_filename, explicit)
+        if explicit
+          "The transport's ssh_public_key setting points at #{public_key_filename}, which does not exist. " \
+            "Correct the path, or remove the setting to use #{private_key_filename}.pub."
+        else
+          "No public key was found at #{public_key_filename}. The transport's ssh_key setting names the " \
+            "private key, and the public half of it has to go on the virtual machine. Create it with: " \
+            "ssh-keygen -y -f #{private_key_filename} > #{public_key_filename}"
+        end
+      end
+
       # Builds the pre-deployment from a caller-supplied ARM template file.
       #
       # @param pre_deployment_template_filename [String] path to an ARM template.
@@ -772,6 +902,50 @@ module Kitchen
         end
       end
 
+      # How Azure's power states map onto Test Kitchen's liveness question.
+      #
+      # Anything absent from this table is passed through as-is with +live+
+      # left nil: reporting a state we have not seen before is more use than
+      # guessing whether it counts as running.
+      #
+      # @return [Hash{String => Boolean}]
+      POWER_STATES = {
+        "running" => true,
+        "starting" => true,
+        "stopping" => true,
+        "stopped" => false,
+        "deallocating" => false,
+        "deallocated" => false,
+      }.freeze
+
+      # Reports whether the virtual machine backing this instance is running.
+      #
+      # Drives +kitchen list --live+ (and its +kitchen status+ alias). Test
+      # Kitchen rescues anything raised here and reports "unknown", but a
+      # listing should not be where an Azure outage first shows up, so the
+      # failure modes are handled explicitly and reported as data.
+      #
+      # No retries: this is a status probe behind an interactive command, and
+      # waiting out the retry budget on every unreachable instance would be
+      # worse than saying so promptly.
+      #
+      # @param state [Hash] the instance state.
+      # @return [Hash] +:live+, +:state+, +:resource_id+ and +:message+.
+      def status(state)
+        resource_group = state[:azure_resource_group_name]
+        vm_name = state[:vm_name]
+        return { live: false, state: "not_created", message: "No Azure virtual machine has been created yet." } unless
+          state[:server_id] && resource_group && vm_name
+
+        power_state_status(state, resource_group, vm_name)
+      rescue Azure::OperationError => operation_error
+        return { live: false, state: "not_created", message: "The virtual machine no longer exists in Azure." } if operation_error.status == 404
+
+        { live: nil, state: "unknown", message: "#{operation_error.code}: #{operation_error.message}" }
+      rescue Azure::TransientError => transient_error
+        { live: nil, state: "unknown", message: "Could not reach Azure (#{transient_error.message})." }
+      end
+
       # Tears down whatever {#create} built.
       #
       # @param state [Hash] the instance state, mutated in place.
@@ -779,8 +953,8 @@ module Kitchen
       # @raise [Azure::OperationError] if an Azure API call fails.
       def destroy(state)
         # TODO: We have some not so fun state issues we need to clean up
-        state[:azure_environment] = config[:azure_environment] unless state[:azure_environment]
-        state[:subscription_id] = config[:subscription_id] unless state[:subscription_id]
+        state[:azure_environment] = config[:azure_environment] unless existing_state_value?(state, :azure_environment)
+        state[:subscription_id] = config[:subscription_id] unless existing_state_value?(state, :subscription_id)
 
         @arm_client = Kitchen::Driver::AzureCredentials.new(subscription_id: state[:subscription_id],
           environment: state[:azure_environment]).arm_client
@@ -816,6 +990,53 @@ module Kitchen
         state.delete(:password)
       end
 
+      # Asks Azure for the virtual machine's power state.
+      #
+      # @param state [Hash] the instance state.
+      # @param resource_group [String]
+      # @param vm_name [String]
+      # @return [Hash] as {#status} returns.
+      def power_state_status(state, resource_group, vm_name)
+        view = status_arm_client(state).virtual_machine_instance_view(resource_group, vm_name)
+        status = Array(view["statuses"]).find { |entry| entry["code"].to_s.start_with?("PowerState/") }
+        power = status && status["code"].to_s.split("/", 2).last
+
+        {
+          live: power ? POWER_STATES[power] : nil,
+          state: power || "unknown",
+          resource_id: virtual_machine_id(status_subscription_id(state), resource_group, vm_name),
+          message: status && status["displayStatus"],
+        }
+      end
+
+      # An ARM client for a status probe, built from state the way {#destroy}
+      # builds one, so that an instance created against another subscription
+      # or cloud is still asked about in the right place.
+      #
+      # @param state [Hash] the instance state.
+      # @return [Azure::ArmClient]
+      def status_arm_client(state)
+        @arm_client ||= Kitchen::Driver::AzureCredentials.new(
+          subscription_id: status_subscription_id(state),
+          environment: state[:azure_environment] || config[:azure_environment]
+        ).arm_client
+      end
+
+      # @param state [Hash] the instance state.
+      # @return [String, nil] the subscription the instance was created in.
+      def status_subscription_id(state)
+        state[:subscription_id] || config[:subscription_id]
+      end
+
+      # @param subscription_id [String]
+      # @param resource_group [String]
+      # @param vm_name [String]
+      # @return [String] the virtual machine's ARM resource id.
+      def virtual_machine_id(subscription_id, resource_group, vm_name)
+        "/subscriptions/#{subscription_id}/resourceGroups/#{resource_group}" \
+          "/providers/Microsoft.Compute/virtualMachines/#{vm_name}"
+      end
+
       # Deletes an explicitly-named resource group when the instance itself was
       # never created but the user asked for the group to be removed.
       #
@@ -839,7 +1060,15 @@ module Kitchen
       end
 
       # Empties a resource group by deploying an empty template in Complete
-      # mode, then restores or clears the group's tags per configuration.
+      # mode, then clears the group's tags unless asked to keep them.
+      #
+      # An empty Complete-mode deployment removes the resources in the group
+      # and leaves the group's own tags alone, so keeping them means leaving
+      # the group be. Rewriting it is what used to remove them: ARM's PUT on a
+      # resource group replaces its tags rather than merging them, so putting
+      # the *configured* tags back overwrote whatever the group actually
+      # carried - which, with +resource_group_tags+ unset, meant erasing them
+      # while announcing they would be kept.
       #
       # @param state [Hash] the instance state.
       # @return [void]
@@ -850,11 +1079,11 @@ module Kitchen
 
         if config[:destroy_explicit_resource_group_tags] == false
           warn 'The "destroy_explicit_resource_group_tags" setting value is set to "false". The tags on the resource group will NOT be removed.'
-          create_resource_group(state[:azure_resource_group_name], get_resource_group)
-        else
-          warn 'The "destroy_explicit_resource_group_tags" setting value is set to "true". The tags on the resource group will be removed.'
-          create_resource_group(state[:azure_resource_group_name], get_resource_group.merge(tags: {}))
+          return
         end
+
+        warn 'The "destroy_explicit_resource_group_tags" setting value is set to "true". The tags on the resource group will be removed.'
+        create_resource_group(state[:azure_resource_group_name], get_resource_group.merge(tags: {}))
       rescue Azure::OperationError => operation_error
         error operation_error.body
         raise operation_error

data/lib/kitchen/driver/azurerm_version.rb

@@ -6,6 +6,6 @@ module Kitchen
     # driver and, with it, the whole Azure SDK.
     #
     # @return [String]
-    AZURERM_VERSION = "2.1.4".freeze
+    AZURERM_VERSION = "2.3.0".freeze
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kitchen-azurerm
 version: !ruby/object:Gem::Version
-  version: 2.1.4
+  version: 2.3.0
 platform: ruby
 authors:
 - Stuart Preston
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-23 00:00:00.000000000 Z
+date: 2026-08-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: inifile