kitchen-azurerm 1.13.6 → 1.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d35fbe96cb5105531f593d3c43343de784274f46e1efe095c399074e8cb8f8f2
-  data.tar.gz: 7c5deaf7be58a437b19244d6dfa70358c1d1e6ea218f9d8b0efda28e92ca0a8f
+  metadata.gz: 2c8f93443204a7cb375624116dbfafaa5ade3419fdd9e0538e1c701f38e60d29
+  data.tar.gz: e14d346d4cb82139aaaa49fdb9d4ef7f752059e0b535d24285e37a585c5b710b
 SHA512:
-  metadata.gz: 94b15b90e66ee2d5b83ee65ca5087a5523fca00bc938d95a7d6979e3b69eb337b8b0f94aad553d348dd14df0941cc83082190dbf772fe29e923940f945893af8
-  data.tar.gz: bf15ffcb819adf6b1d71eb520391d0b39a8eb899d2df01ee4e304032fdef96858b389001de7f0d0559e71f0018eb42fddd8a2b0d766df16d7965da6220c9a41d
+  metadata.gz: 2474a4e576e924afaa92e121fc315fee4cbce2ab159f946d64d8e208f1127d8dd50fd7d383aafc70beec2bb3dfb9194ddaf79d43c5e4cd1522787a4d38603efa
+  data.tar.gz: 9e498c0a069a4ee74e7db388c5983df082ba1bf251be06280868abdc802de616f75a93e331b62527a39b839cf55927fcab741265d732eef64f460e34130099e5

data/lib/kitchen/driver/azure_credentials.rb

@@ -1,42 +1,96 @@
 require "inifile"
 
+require "kitchen/errors"
 require "kitchen/logging"
 autoload :MsRest2, "ms_rest2"
 autoload :MsRestAzure2, "ms_rest_azure2"
 
 module Kitchen
   module Driver
+    # Resolves Azure Resource Manager credentials and endpoint settings for a
+    # single subscription.
     #
-    # AzureCredentials
+    # Credentials are sourced, in order of precedence, from environment
+    # variables (+AZURE_TENANT_ID+, +AZURE_CLIENT_ID+, +AZURE_CLIENT_SECRET+)
+    # and then from the Azure CLI credentials INI file (by default
+    # +~/.azure/credentials+, overridable with +AZURE_CONFIG_FILE+).
     #
+    # The combination of values that resolve determines which token provider is
+    # used - see {#azure_options}.
+    #
+    # @example Service principal supplied by environment
+    #   ENV["AZURE_TENANT_ID"]     = "..."
+    #   ENV["AZURE_CLIENT_ID"]     = "..."
+    #   ENV["AZURE_CLIENT_SECRET"] = "..."
+    #   options = Kitchen::Driver::AzureCredentials.new(subscription_id: "...").azure_options
     class AzureCredentials
       include Kitchen::Logging
 
-      CONFIG_PATH = "#{ENV["HOME"]}/.azure/credentials".freeze
-
+      # Path fragment, relative to the user's home directory, of the Azure CLI
+      # credentials file.
       #
       # @return [String]
+      CONFIG_FILE = File.join(".azure", "credentials").freeze
+
+      # Azure cloud names understood by {#azure_options}, mapped to the
+      # +MsRestAzure2+ constants that describe them. Keys are downcased so
+      # lookups are case-insensitive.
       #
-      attr_reader :subscription_id
+      # @return [Hash{String => Symbol}]
+      ENVIRONMENTS = {
+        "azure" => :Azure,
+        "azurechina" => :AzureChina,
+        "azuregermancloud" => :AzureGermanCloud,
+        "azureusgovernment" => :AzureUSGovernment,
+      }.freeze
 
+      # Port the Azure Instance Metadata Service listens on for MSI token requests.
+      #
+      # @return [Integer]
+      MSI_PORT = 50342
+
+      # The Azure subscription these credentials authenticate against.
       #
       # @return [String]
+      attr_reader :subscription_id
+
+      # The Azure cloud name, e.g. +"Azure"+ or +"AzureUSGovernment"+.
       #
+      # @return [String]
       attr_reader :environment
 
+      # Default path of the Azure CLI credentials file.
       #
-      # Creates and initializes a new instance of the Credentials class.
+      # Resolved lazily (rather than at load time) so that a test - or a caller
+      # that manipulates +HOME+ - sees the current home directory rather than
+      # whichever one happened to be set when this file was first required.
       #
+      # @return [String] absolute path to +~/.azure/credentials+
+      def self.default_config_path
+        File.join(Dir.home, CONFIG_FILE)
+      end
+
+      # @param subscription_id [String] the Azure subscription to authenticate against.
+      # @param environment [String] the Azure cloud name. Case-insensitive.
+      # @raise [Kitchen::UserError] if +environment+ is not a known Azure cloud.
       def initialize(subscription_id:, environment: "Azure")
         @subscription_id = subscription_id
-        @environment = environment
+        @environment = environment || "Azure"
+
+        unless ENVIRONMENTS.key?(@environment.to_s.downcase)
+          raise Kitchen::UserError,
+            "Unknown azure_environment '#{@environment}'. Valid values are: #{ENVIRONMENTS.keys.join(", ")} (case-insensitive)."
+        end
       end
 
+      # Builds the options hash accepted by every +azure_mgmt_*2+ client.
       #
-      # Retrieves an object containing options and credentials
-      #
-      # @return [Object] Object that can be supplied along with all Azure client requests.
+      # The +:credentials+ entry wraps whichever token provider matches the
+      # resolved credentials - see {#token_provider}. +:client_id+ and
+      # +:client_secret+ are only included when they resolve to a value.
       #
+      # @return [Hash] options suitable for
+      #   +Azure::Resources2::Profiles::Latest::Mgmt::Client.new+ and friends.
       def azure_options
         options = { tenant_id: tenant_id!,
                     subscription_id:,
@@ -48,16 +102,76 @@ module Kitchen
         options
       end
 
-      private
+      # Selects a token provider based on which credentials resolved.
+      #
+      # * +client_id+ + +client_secret+ + +tenant_id+ - service principal.
+      # * +client_id+ + +tenant_id+ - user-assigned managed identity.
+      # * +tenant_id+ only - system-assigned managed identity.
+      # * none of the above - falls back to the +az login+ token cache.
+      #
+      # @return [MsRestAzure2::ApplicationTokenProvider,
+      #   MsRestAzure2::MSITokenProvider, MsRestAzure2::AzureCliTokenProvider]
+      def token_provider
+        if client_id && client_secret && tenant_id
+          ::MsRestAzure2::ApplicationTokenProvider.new(tenant_id, client_id, client_secret, ad_settings)
+        elsif client_id && tenant_id
+          ::MsRestAzure2::MSITokenProvider.new(MSI_PORT, ad_settings, { client_id: })
+        elsif tenant_id
+          ::MsRestAzure2::MSITokenProvider.new(MSI_PORT, ad_settings)
+        else
+          warn("Using tenant id set through `az login`.")
+          ::MsRestAzure2::AzureCliTokenProvider.new(ad_settings)
+        end
+      end
 
-      def logger
-        Kitchen.logger
+      # Active Directory settings for the configured cloud.
+      #
+      # @return [MsRestAzure2::ActiveDirectoryServiceSettings]
+      def ad_settings
+        case environment_key
+        when :AzureUSGovernment then ::MsRestAzure2::ActiveDirectoryServiceSettings.get_azure_us_government_settings
+        when :AzureChina        then ::MsRestAzure2::ActiveDirectoryServiceSettings.get_azure_china_settings
+        when :AzureGermanCloud  then ::MsRestAzure2::ActiveDirectoryServiceSettings.get_azure_german_settings
+        else ::MsRestAzure2::ActiveDirectoryServiceSettings.get_azure_settings
+        end
+      end
+
+      # Endpoint settings (resource manager URL, storage suffixes, ...) for the
+      # configured cloud.
+      #
+      # @return [MsRestAzure2::AzureEnvironment]
+      def endpoint_settings
+        case environment_key
+        when :AzureUSGovernment then ::MsRestAzure2::AzureEnvironments::AzureUSGovernment
+        when :AzureChina        then ::MsRestAzure2::AzureEnvironments::AzureChinaCloud
+        when :AzureGermanCloud  then ::MsRestAzure2::AzureEnvironments::AzureGermanCloud
+        else ::MsRestAzure2::AzureEnvironments::AzureCloud
+        end
       end
 
+      # Path of the credentials file actually in use.
+      #
+      # @return [String] +AZURE_CONFIG_FILE+ if set, otherwise
+      #   {.default_config_path}. Always expanded.
       def config_path
-        @config_path ||= File.expand_path(ENV["AZURE_CONFIG_FILE"] || CONFIG_PATH)
+        @config_path ||= File.expand_path(ENV["AZURE_CONFIG_FILE"] || self.class.default_config_path)
+      end
+
+      private
+
+      # @return [Symbol] the {ENVIRONMENTS} key for the configured cloud.
+      def environment_key
+        ENVIRONMENTS.fetch(environment.to_s.downcase)
+      end
+
+      # @return [Kitchen::Logger] the shared Test Kitchen logger.
+      def logger
+        Kitchen.logger
       end
 
+      # Parsed credentials file, or an empty Hash when no readable file exists.
+      #
+      # @return [IniFile, Hash]
       def credentials
         @credentials ||= if File.file?(config_path)
                            IniFile.load(config_path)
@@ -67,94 +181,51 @@ module Kitchen
                          end
       end
 
+      # Reads a property from the section of the credentials file matching
+      # {#subscription_id}.
+      #
+      # @param property [String] the INI key to read.
+      # @return [String, nil]
       def credentials_property(property)
-        credentials[subscription_id]&.[](property)
+        value = credentials[subscription_id]&.[](property)
+        value unless value.to_s.empty?
       end
 
+      # Tenant ID, warning the user when one cannot be resolved.
+      #
+      # @return [String, nil]
       def tenant_id!
         tenant_id || warn("(#{config_path}) does not contain tenant_id neither is the AZURE_TENANT_ID environment variable set.")
       end
 
+      # @return [String, nil] tenant ID from the environment or credentials file.
       def tenant_id
-        ENV["AZURE_TENANT_ID"] || credentials_property("tenant_id")
+        env_or_credentials("AZURE_TENANT_ID", "tenant_id")
       end
 
+      # @return [String, nil] client ID from the environment or credentials file.
       def client_id
-        ENV["AZURE_CLIENT_ID"] || credentials_property("client_id")
+        env_or_credentials("AZURE_CLIENT_ID", "client_id")
       end
 
+      # @return [String, nil] client secret from the environment or credentials file.
       def client_secret
-        ENV["AZURE_CLIENT_SECRET"] || credentials_property("client_secret")
+        env_or_credentials("AZURE_CLIENT_SECRET", "client_secret")
       end
 
-      # Retrieve a token based upon the preferred authentication method.
+      # Reads a value from the environment, falling back to the credentials file.
       #
-      # @return [::MsRest2::TokenProvider] A new token provider object.
-      def token_provider
-        # Login with a credentials file or setting the environment variables
-        #
-        # Typically used with a service principal.
-        #
-        # SPN with client_id, client_secret and tenant_id
-        if client_id && client_secret && tenant_id
-          ::MsRestAzure2::ApplicationTokenProvider.new(tenant_id, client_id, client_secret, ad_settings)
-        # Login with a Managed Service Identity.
-        #
-        # Typically used with a Managed Service Identity when you have a particular object registered in a tenant.
-        #
-        # MSI with client_id and tenant_id (aka User Assigned Identity).
-        elsif client_id && tenant_id
-          ::MsRestAzure2::MSITokenProvider.new(50342, ad_settings, { client_id: })
-        # Default approach to inheriting existing object permissions (application or device this code is running on).
-        #
-        # Typically used when you want to inherit the permissions of the system you're running on that are in a tenant.
-        #
-        # MSI with just tenant_id (aka System Assigned Identity).
-        elsif tenant_id
-          ::MsRestAzure2::MSITokenProvider.new(50342, ad_settings)
-        # Login using the Azure CLI
-        #
-        # Typically used when you want to rely upon `az login` as your preferred authentication method.
-        else
-          warn("Using tenant id set through `az login`.")
-          ::MsRestAzure2::AzureCliTokenProvider.new(ad_settings)
-        end
-      end
-
-      #
-      # Retrieves a [MsRestAzure2::ActiveDirectoryServiceSettings] object representing the AD settings for the given cloud.
-      #
-      # @return [MsRestAzure2::ActiveDirectoryServiceSettings] Settings to be used for subsequent requests
+      # Empty environment variables are treated as unset - an exported-but-blank
+      # +AZURE_CLIENT_SECRET+ should not shadow a real value in the file.
       #
-      def ad_settings
-        case environment.downcase
-        when "azureusgovernment"
-          ::MsRestAzure2::ActiveDirectoryServiceSettings.get_azure_us_government_settings
-        when "azurechina"
-          ::MsRestAzure2::ActiveDirectoryServiceSettings.get_azure_china_settings
-        when "azuregermancloud"
-          ::MsRestAzure2::ActiveDirectoryServiceSettings.get_azure_german_settings
-        when "azure"
-          ::MsRestAzure2::ActiveDirectoryServiceSettings.get_azure_settings
-        end
-      end
+      # @param env_var [String] environment variable name.
+      # @param property [String] INI property name.
+      # @return [String, nil]
+      def env_or_credentials(env_var, property)
+        value = ENV[env_var]
+        return value unless value.to_s.empty?
 
-      #
-      # Retrieves a [MsRestAzure2::AzureEnvironment] object representing endpoint settings for the given cloud.
-      #
-      # @return [MsRestAzure2::AzureEnvironment] Settings to be used for subsequent requests
-      #
-      def endpoint_settings
-        case environment.downcase
-        when "azureusgovernment"
-          ::MsRestAzure2::AzureEnvironments::AzureUSGovernment
-        when "azurechina"
-          ::MsRestAzure2::AzureEnvironments::AzureChinaCloud
-        when "azuregermancloud"
-          ::MsRestAzure2::AzureEnvironments::AzureGermanCloud
-        when "azure"
-          ::MsRestAzure2::AzureEnvironments::AzureCloud
-        end
+        credentials_property(property)
       end
     end
   end