kitchen-azurerm 1.13.6 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d35fbe96cb5105531f593d3c43343de784274f46e1efe095c399074e8cb8f8f2
-  data.tar.gz: 7c5deaf7be58a437b19244d6dfa70358c1d1e6ea218f9d8b0efda28e92ca0a8f
+  metadata.gz: '0853e2f879329c6b0664e4931574d1ca3a8b8998fc1a5e56424eab212b2f95b1'
+  data.tar.gz: e00246cb4d2f291492df022874e9755fb6dc7745067428dd2f1ac291e57fc32f
 SHA512:
-  metadata.gz: 94b15b90e66ee2d5b83ee65ca5087a5523fca00bc938d95a7d6979e3b69eb337b8b0f94aad553d348dd14df0941cc83082190dbf772fe29e923940f945893af8
-  data.tar.gz: bf15ffcb819adf6b1d71eb520391d0b39a8eb899d2df01ee4e304032fdef96858b389001de7f0d0559e71f0018eb42fddd8a2b0d766df16d7965da6220c9a41d
+  metadata.gz: c8016844395a76393d56fcf31d30b7cb4e14512566c0da7a3a73aeb5fb120f4232d6c1c678feb5ca4d7cd9b159613991b0c759764ff549245e82e5055d8a3ba3
+  data.tar.gz: ec9337480b1b58d0b0a5dc461c99e8d1abbf97e9f0b95dfc8c41b34acf3a4580b0701dfaf0323dd7660164f27602bc9ef912b29cab7cbba5e66a6a99fd7b5cbe

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

@@ -0,0 +1,198 @@
+require "json" unless defined?(JSON)
+require "uri" unless defined?(URI)
+
+require_relative "errors"
+require_relative "http"
+
+module Kitchen
+  module Driver
+    module Azure
+      # A minimal Azure Resource Manager client covering exactly the operations
+      # this driver performs.
+      #
+      # Replaces +azure_mgmt_resources2+, +azure_mgmt_network2+, +ms_rest2+ and
+      # +ms_rest_azure2+, which are forks of Microsoft's retired Azure SDK for
+      # Ruby. Responses are returned as parsed JSON, so callers see ARM's own
+      # camelCase property names rather than the SDK's generated model objects.
+      class ArmClient
+        # ARM API version used for resource group and deployment requests.
+        #
+        # @return [String]
+        RESOURCES_API_VERSION = "2025-04-01".freeze
+
+        # ARM API version used for network resource requests.
+        #
+        # @return [String]
+        NETWORK_API_VERSION = "2025-07-01".freeze
+
+        # @param subscription_id [String]
+        # @param environment [Environments::Environment]
+        # @param token_provider [TokenProvider]
+        def initialize(subscription_id:, environment:, token_provider:)
+          @subscription_id = subscription_id
+          @environment = environment
+          @token_provider = token_provider
+        end
+
+        # @return [String]
+        attr_reader :subscription_id
+
+        # @return [Environments::Environment]
+        attr_reader :environment
+
+        # @return [TokenProvider]
+        attr_reader :token_provider
+
+        # Whether a resource group exists.
+        #
+        # @param name [String] resource group name, case-insensitive.
+        # @return [Boolean]
+        def resource_group_exists?(name)
+          response = call(:head, resource_group_path(name), api_version: RESOURCES_API_VERSION, allow: [404])
+          response.status != 404
+        end
+
+        # Creates or updates a resource group.
+        #
+        # @param name [String] resource group name.
+        # @param location [String] Azure region.
+        # @param tags [Hash] resource tags.
+        # @return [Hash] the resource group as ARM returned it.
+        def create_or_update_resource_group(name, location:, tags: {})
+          call(:put, resource_group_path(name),
+            api_version: RESOURCES_API_VERSION,
+            body: { "location" => location, "tags" => tags || {} }).json
+        end
+
+        # Requests deletion of a resource group, returning as soon as ARM
+        # accepts the request rather than waiting for it to finish.
+        #
+        # @param name [String] resource group name.
+        # @return [void]
+        def delete_resource_group(name)
+          call(:delete, resource_group_path(name), api_version: RESOURCES_API_VERSION)
+          nil
+        end
+
+        # Submits a deployment, returning once ARM accepts it.
+        #
+        # @param resource_group [String]
+        # @param name [String] deployment name.
+        # @param deployment [Hash] the deployment body, as built by the driver.
+        # @return [Hash] the deployment as ARM returned it.
+        def create_deployment(resource_group, name, deployment)
+          call(:put, deployment_path(resource_group, name),
+            api_version: RESOURCES_API_VERSION,
+            body: deployment).json
+        end
+
+        # Reads a deployment.
+        #
+        # @param resource_group [String]
+        # @param name [String] deployment name.
+        # @return [Hash]
+        def deployment(resource_group, name)
+          call(:get, deployment_path(resource_group, name), api_version: RESOURCES_API_VERSION).json
+        end
+
+        # Lists every operation belonging to a deployment.
+        #
+        # @param resource_group [String]
+        # @param name [String] deployment name.
+        # @return [Array<Hash>]
+        def deployment_operations(resource_group, name)
+          payload = call(:get, "#{deployment_path(resource_group, name)}/operations",
+            api_version: RESOURCES_API_VERSION).json
+
+          payload.is_a?(Hash) ? Array(payload["value"]) : []
+        end
+
+        # Reads a public IP address resource.
+        #
+        # @param resource_group [String]
+        # @param name [String] public IP resource name.
+        # @return [Hash]
+        def public_ip(resource_group, name)
+          call(:get, network_path(resource_group, "publicIPAddresses", name),
+            api_version: NETWORK_API_VERSION).json
+        end
+
+        # Reads a network interface resource.
+        #
+        # @param resource_group [String]
+        # @param name [String] network interface name.
+        # @return [Hash]
+        def network_interface(resource_group, name)
+          call(:get, network_path(resource_group, "networkInterfaces", name),
+            api_version: NETWORK_API_VERSION).json
+        end
+
+        private
+
+        # @param name [String]
+        # @return [String]
+        def resource_group_path(name)
+          "/subscriptions/#{subscription_id}/resourcegroups/#{escape(name)}"
+        end
+
+        # @param resource_group [String]
+        # @param name [String]
+        # @return [String]
+        def deployment_path(resource_group, name)
+          "#{resource_group_path(resource_group)}/providers/Microsoft.Resources/deployments/#{escape(name)}"
+        end
+
+        # @param resource_group [String]
+        # @param type [String] e.g. +"publicIPAddresses"+.
+        # @param name [String]
+        # @return [String]
+        def network_path(resource_group, type, name)
+          "#{resource_group_path(resource_group)}/providers/Microsoft.Network/#{type}/#{escape(name)}"
+        end
+
+        # @param value [String]
+        # @return [String] path-escaped
+        def escape(value)
+          URI::DEFAULT_PARSER.escape(value.to_s)
+        end
+
+        # Performs an authenticated ARM request.
+        #
+        # @param method [Symbol]
+        # @param path [String] path below the resource manager URL.
+        # @param api_version [String]
+        # @param body [Hash, nil] request body, serialized as JSON.
+        # @param allow [Array<Integer>] non-2xx statuses to treat as success.
+        # @return [Http::Response]
+        # @raise [OperationError] when ARM returns an unexpected status.
+        def call(method, path, api_version:, body: nil, allow: [])
+          url = "#{environment.resource_manager_url.chomp("/")}#{path}?api-version=#{api_version}"
+          headers = {
+            "Authorization" => token_provider.authorization_header,
+            "Accept" => "application/json",
+            "User-Agent" => "kitchen-azurerm/#{Kitchen::Driver::AZURERM_VERSION}",
+          }
+          headers["Content-Type"] = "application/json" if body
+
+          response = Http.request(method:, url:, headers:, body: body && JSON.generate(body))
+          return response if response.success? || allow.include?(response.status)
+
+          raise OperationError.new(
+            "Azure returned HTTP #{response.status} for #{method.to_s.upcase} #{path}",
+            status: response.status,
+            body: error_body(response)
+          )
+        end
+
+        # @param response [Http::Response]
+        # @return [Hash] the parsed error body, or a synthesized one.
+        def error_body(response)
+          parsed = response.json
+          return parsed if parsed.is_a?(Hash) && parsed.key?("error")
+
+          { "error" => { "code" => "Unknown", "message" => response.body.to_s } }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,73 @@
+module Kitchen
+  module Driver
+    module Azure
+      # Endpoints for each Azure cloud the driver can target.
+      #
+      # These used to come from +MsRestAzure2::AzureEnvironments+ and
+      # +MsRestAzure2::ActiveDirectoryServiceSettings+. They are stable,
+      # published values, so carrying the table ourselves costs a few lines and
+      # removes a dependency on a retired SDK.
+      module Environments
+        # One Azure cloud's endpoints.
+        #
+        # @!attribute [r] name
+        #   @return [String] canonical cloud name, e.g. +"AzureUSGovernment"+.
+        # @!attribute [r] resource_manager_url
+        #   @return [String] base URL for Azure Resource Manager requests.
+        # @!attribute [r] authentication_endpoint
+        #   @return [String] Entra ID (Azure AD) token endpoint.
+        # @!attribute [r] token_audience
+        #   @return [String] audience/resource the access token is requested for.
+        Environment = Struct.new(:name, :resource_manager_url, :authentication_endpoint, :token_audience) do
+          # The OAuth2 token URL for a tenant in this cloud.
+          #
+          # @param tenant_id [String]
+          # @return [String]
+          def token_url(tenant_id)
+            "#{authentication_endpoint.chomp("/")}/#{tenant_id}/oauth2/token"
+          end
+        end
+
+        # Every supported cloud, keyed by its downcased name so that lookups are
+        # case-insensitive.
+        #
+        # @return [Hash{String => Environment}]
+        ALL = [
+          Environment.new("Azure",
+            "https://management.azure.com/",
+            "https://login.microsoftonline.com/",
+            "https://management.core.windows.net/"),
+          Environment.new("AzureUSGovernment",
+            "https://management.usgovcloudapi.net",
+            "https://login.microsoftonline.us/",
+            "https://management.core.usgovcloudapi.net/"),
+          Environment.new("AzureChina",
+            "https://management.chinacloudapi.cn",
+            "https://login.chinacloudapi.cn/",
+            "https://management.core.chinacloudapi.cn/"),
+          Environment.new("AzureGermanCloud",
+            "https://management.microsoftazure.de",
+            "https://login.microsoftonline.de/",
+            "https://management.core.cloudapi.de/"),
+        ].each(&:freeze).to_h { |environment| [environment.name.downcase, environment] }.freeze
+
+        # Looks a cloud up by name.
+        #
+        # @param name [String] cloud name, case-insensitive.
+        # @return [Environment]
+        # @raise [Kitchen::UserError] if the name is not a known Azure cloud.
+        def self.fetch(name)
+          ALL.fetch(name.to_s.downcase) do
+            raise Kitchen::UserError,
+              "Unknown azure_environment '#{name}'. Valid values are: #{names.join(", ")} (case-insensitive)."
+          end
+        end
+
+        # @return [Array<String>] the canonical name of every supported cloud.
+        def self.names
+          ALL.values.map(&:name)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+module Kitchen
+  module Driver
+    # Direct Azure Resource Manager access: endpoints, authentication, and the
+    # handful of REST calls this driver makes.
+    #
+    # This replaces the +azure_mgmt_*+ and +ms_rest*+ gems, which are forks of
+    # Microsoft's retired Azure SDK for Ruby.
+    module Azure
+      # Raised when Azure Resource Manager returns an error response.
+      #
+      # Replaces +MsRestAzure2::AzureOperationError+, keeping the +body+
+      # accessor the driver's rescue blocks already rely on.
+      #
+      # Note the explicit +::StandardError+: Test Kitchen defines
+      # +Kitchen::StandardError+, and this class lives inside +module Kitchen+,
+      # so a bare +StandardError+ here would resolve to that instead.
+      class OperationError < ::StandardError
+        # The parsed error body, as returned by ARM.
+        #
+        # @return [Hash] typically +{"error" => {"code" => ..., "message" => ...}}+.
+        attr_reader :body
+
+        # The HTTP status code of the failing response.
+        #
+        # @return [Integer]
+        attr_reader :status
+
+        # @param message [String] human-readable summary.
+        # @param status [Integer] HTTP status code.
+        # @param body [Hash] parsed ARM error body.
+        def initialize(message, status: nil, body: {})
+          super(message)
+          @status = status
+          @body = body
+        end
+
+        # The Azure error code, when ARM supplied one.
+        #
+        # @return [String, nil] e.g. +"DeploymentActive"+.
+        def code
+          body.is_a?(Hash) ? body.dig("error", "code") : nil
+        end
+      end
+
+      # Raised when a request could not be completed and is worth retrying:
+      # timeouts, resets, DNS failures and the like.
+      class TransientError < ::StandardError; end
+    end
+  end
+end

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

@@ -0,0 +1,120 @@
+require "json" unless defined?(JSON)
+require "net/http" unless defined?(Net::HTTP)
+require "openssl" unless defined?(OpenSSL)
+require "uri" unless defined?(URI)
+
+require_relative "errors"
+
+module Kitchen
+  module Driver
+    module Azure
+      # A very small JSON-over-HTTP helper built on the standard library.
+      #
+      # The driver makes a handful of straightforward requests, so this replaces
+      # Faraday and its middleware chain rather than depending on them.
+      module Http
+        # Network-level failures worth retrying rather than surfacing.
+        #
+        # @return [Array<Class>]
+        TRANSIENT_ERRORS = [
+          Net::OpenTimeout,
+          Net::ReadTimeout,
+          Errno::ECONNREFUSED,
+          Errno::ECONNRESET,
+          Errno::EHOSTUNREACH,
+          Errno::ENETUNREACH,
+          Errno::EPIPE,
+          EOFError,
+          SocketError,
+          OpenSSL::SSL::SSLError,
+        ].freeze
+
+        # Seconds to wait for a connection and for a response.
+        #
+        # @return [Integer]
+        OPEN_TIMEOUT = 30
+        # @return [Integer]
+        READ_TIMEOUT = 120
+
+        # One HTTP response.
+        #
+        # @!attribute [r] status
+        #   @return [Integer]
+        # @!attribute [r] body
+        #   @return [String]
+        Response = Struct.new(:status, :body) do
+          # @return [Boolean] whether the status is in the 2xx range.
+          def success?
+            status.between?(200, 299)
+          end
+
+          # The response body parsed as JSON.
+          #
+          # @return [Hash, Array, nil] nil when the body is empty or not JSON.
+          def json
+            return nil if body.nil? || body.empty?
+
+            JSON.parse(body)
+          rescue JSON::ParserError
+            nil
+          end
+        end
+
+        # Performs a request.
+        #
+        # @param method [Symbol] +:get+, +:head+, +:put+, +:post+ or +:delete+.
+        # @param url [String] absolute URL.
+        # @param headers [Hash{String => String}] request headers.
+        # @param body [String, nil] request body, already encoded.
+        # @return [Response]
+        # @raise [TransientError] on a network failure worth retrying.
+        def self.request(method:, url:, headers: {}, body: nil)
+          uri = URI.parse(url)
+          request = request_class(method).new(uri)
+          headers.each { |name, value| request[name] = value }
+          request.body = body if body
+
+          response = perform(uri, request)
+          Response.new(response.code.to_i, response.body.to_s)
+        rescue *TRANSIENT_ERRORS => e
+          raise TransientError, "#{e.class}: #{e.message}"
+        end
+
+        # Sends a request, honouring the proxy environment variables.
+        #
+        # @param uri [URI]
+        # @param request [Net::HTTPRequest]
+        # @return [Net::HTTPResponse]
+        # @api private
+        def self.perform(uri, request)
+          proxy = uri.find_proxy
+          http = if proxy
+                   Net::HTTP.new(uri.host, uri.port, proxy.host, proxy.port, proxy.user, proxy.password)
+                 else
+                   Net::HTTP.new(uri.host, uri.port)
+                 end
+
+          http.use_ssl = uri.scheme == "https"
+          http.open_timeout = OPEN_TIMEOUT
+          http.read_timeout = READ_TIMEOUT
+          http.start { |connection| connection.request(request) }
+        end
+
+        # @param method [Symbol]
+        # @return [Class] the matching +Net::HTTP+ request class.
+        # @raise [ArgumentError] for an unsupported method.
+        # @api private
+        def self.request_class(method)
+          case method
+          when :get then Net::HTTP::Get
+          when :head then Net::HTTP::Head
+          when :put then Net::HTTP::Put
+          when :post then Net::HTTP::Post
+          when :delete then Net::HTTP::Delete
+          else raise ArgumentError, "Unsupported HTTP method: #{method}"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,196 @@
+require "json" unless defined?(JSON)
+require "open3" unless defined?(Open3)
+require "time" unless defined?(Time.parse)
+require "uri" unless defined?(URI)
+
+require_relative "errors"
+require_relative "http"
+
+module Kitchen
+  module Driver
+    module Azure
+      # Acquires and caches Entra ID (Azure AD) access tokens for ARM.
+      #
+      # Replaces the +MsRestAzure2+ token providers. Each subclass knows how to
+      # fetch a token one way; the caching and expiry handling is shared.
+      class TokenProvider
+        # Seconds before actual expiry at which a cached token is considered
+        # stale, so a long deployment does not fail mid-flight.
+        #
+        # @return [Integer]
+        EXPIRY_MARGIN = 300
+
+        # @param environment [Environments::Environment] the target cloud.
+        def initialize(environment:)
+          @environment = environment
+          @token = nil
+          @expires_at = nil
+        end
+
+        # @return [Environments::Environment]
+        attr_reader :environment
+
+        # A valid access token, fetching or refreshing one if needed.
+        #
+        # @return [String]
+        def access_token
+          return @token if @token && @expires_at && Time.now.to_i < @expires_at - EXPIRY_MARGIN
+
+          @token, @expires_at = fetch_token
+          @token
+        end
+
+        # The value for the Authorization header.
+        #
+        # @return [String]
+        def authorization_header
+          "Bearer #{access_token}"
+        end
+
+        # Fetches a fresh token.
+        #
+        # @return [Array(String, Integer)] the token and its expiry, as a Unix time.
+        # @raise [NotImplementedError] subclasses must implement this.
+        def fetch_token
+          raise NotImplementedError
+        end
+
+        private
+
+        # Turns a token endpoint response into a token and expiry pair.
+        #
+        # @param response [Http::Response]
+        # @param source [String] describes the endpoint, for error messages.
+        # @return [Array(String, Integer)]
+        # @raise [OperationError] if the endpoint did not return a token.
+        def token_from(response, source)
+          payload = response.json
+          unless response.success? && payload.is_a?(Hash) && payload["access_token"]
+            raise OperationError.new(
+              "Could not acquire an Azure access token from #{source} (HTTP #{response.status}).",
+              status: response.status,
+              body: payload.is_a?(Hash) ? payload : {}
+            )
+          end
+
+          [payload["access_token"], expiry_from(payload)]
+        end
+
+        # Reads the expiry out of a token response, which spells it differently
+        # depending on the endpoint.
+        #
+        # @param payload [Hash]
+        # @return [Integer] Unix time at which the token expires.
+        def expiry_from(payload)
+          return payload["expires_on"].to_i if payload["expires_on"].to_s.match?(/\A\d+\z/)
+          return Time.now.to_i + payload["expires_in"].to_i if payload["expires_in"]
+
+          Time.now.to_i + 3600
+        end
+      end
+
+      # Authenticates as a service principal, using a client id and secret.
+      class ServicePrincipalToken < TokenProvider
+        # @param environment [Environments::Environment]
+        # @param tenant_id [String]
+        # @param client_id [String]
+        # @param client_secret [String]
+        def initialize(environment:, tenant_id:, client_id:, client_secret:)
+          super(environment:)
+          @tenant_id = tenant_id
+          @client_id = client_id
+          @client_secret = client_secret
+        end
+
+        # @return [Array(String, Integer)]
+        def fetch_token
+          response = Http.request(
+            method: :post,
+            url: environment.token_url(@tenant_id),
+            headers: { "Content-Type" => "application/x-www-form-urlencoded" },
+            body: URI.encode_www_form(
+              grant_type: "client_credentials",
+              client_id: @client_id,
+              client_secret: @client_secret,
+              resource: environment.token_audience
+            )
+          )
+
+          token_from(response, "the service principal token endpoint")
+        end
+      end
+
+      # Authenticates as a managed identity, via the Instance Metadata Service.
+      #
+      # This replaces the legacy MSI extension endpoint on port 50342 that the
+      # old SDK used; IMDS is the supported endpoint on modern Azure VMs.
+      class ManagedIdentityToken < TokenProvider
+        # @return [String] the IMDS token endpoint.
+        IMDS_URL = "http://169.254.169.254/metadata/identity/oauth2/token".freeze
+
+        # @return [String] IMDS API version.
+        API_VERSION = "2018-02-01".freeze
+
+        # @param environment [Environments::Environment]
+        # @param client_id [String, nil] the user-assigned identity to use, or
+        #   nil for the system-assigned identity.
+        def initialize(environment:, client_id: nil)
+          super(environment:)
+          @client_id = client_id
+        end
+
+        # @return [Array(String, Integer)]
+        def fetch_token
+          query = { "api-version" => API_VERSION, "resource" => environment.token_audience }
+          query["client_id"] = @client_id if @client_id
+
+          response = Http.request(
+            method: :get,
+            url: "#{IMDS_URL}?#{URI.encode_www_form(query)}",
+            headers: { "Metadata" => "true" }
+          )
+
+          token_from(response, "the instance metadata service")
+        end
+      end
+
+      # Reuses whatever the Azure CLI is already signed in as.
+      class AzureCliToken < TokenProvider
+        # @return [Array(String, Integer)]
+        # @raise [OperationError] if the CLI is missing or not signed in.
+        def fetch_token
+          stdout, stderr, status = Open3.capture3(
+            "az", "account", "get-access-token",
+            "--resource", environment.token_audience,
+            "--output", "json"
+          )
+
+          unless status.success?
+            raise OperationError.new("Could not acquire an Azure access token via `az account get-access-token`. Run `az login` first. (#{stderr.strip})")
+          end
+
+          payload = JSON.parse(stdout)
+          [payload.fetch("accessToken"), cli_expiry(payload)]
+        rescue Errno::ENOENT
+          raise OperationError.new("The Azure CLI (`az`) was not found on PATH, and no other Azure credentials were configured.")
+        rescue JSON::ParserError, KeyError
+          raise OperationError.new("Could not understand the response from `az account get-access-token`.")
+        end
+
+        private
+
+        # The CLI reports a local timestamp rather than a Unix time.
+        #
+        # @param payload [Hash]
+        # @return [Integer]
+        def cli_expiry(payload)
+          return payload["expires_on"].to_i if payload["expires_on"].to_s.match?(/\A\d+\z/)
+
+          Time.parse(payload["expiresOn"]).to_i
+        rescue ::StandardError
+          Time.now.to_i + 3600
+        end
+      end
+    end
+  end
+end