kitchen-oci 1.25.0 → 1.27.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: db93079acea4739f9970e3a00627fe554719df5effc9e3b78d45287ea14fa730
-  data.tar.gz: 7dcc0d262fe162aa8db4cd351ff588a965f7560e01d9eccb5b7a6d901098faeb
+  metadata.gz: 287b9951ec283147d4c090e18ad45ee304e5cd88afaf2d1d4adc91de0c6c55e5
+  data.tar.gz: 8f1c4c1018de62ca0c293dfa83b29182e999092fb561a36c77329643fd99e20b
 SHA512:
-  metadata.gz: 79774b7b41ea8e9ee93c70f708fd2ff4e2f64efda2037e6237445cabff246a42ea6250d548d3bea9d8e843aaded434eebc55bccae219675169e455d4f73ea314
-  data.tar.gz: 65907206e93b70b092a6a4154e5f1a3ce8490412950e41759856eb032940eed1fcf4227089db4bc4682711634276864af78eff5016915db2593f8c63793a86bc
+  metadata.gz: 5eca7e04ff35aba43ab2993e73134a6961cf665cf44a7b39f8c650051faba78aadcf841894f1887f145093557fae2d00a0ff00d4283de7f77ba17c4175bf5236
+  data.tar.gz: 435f87755bdcdcb3b5c79e9d04b66c86386d213d3ea3af5a80dea93d35d12aa00ea87ffa1889b5eff07cd21746f791302eaa5e1ecdd3294995838f82d5f815ce

data/lib/kitchen/driver/oci/api.rb

@@ -20,49 +20,66 @@
 module Kitchen
   module Driver
     class Oci
-      # Api class that defines the various API classes used to interact with OCI
+      # Defines the various API classes used to interact with OCI.
+      #
+      # @author Justin Steele <justin.steele@oracle.com>
       class Api
         def initialize(oci_config, config)
           @oci_config = oci_config
           @config = config
         end
 
-        #
-        # The config used to authenticate to OCI
+        # The config used to authenticate to OCI.
         #
         # @return [OCI::Config]
-        #
         attr_reader :oci_config
 
-        #
-        # The config provided by the driver
+        # The config provided by the driver.
         #
         # @return [Kitchen::LazyHash]
-        #
         attr_reader :config
 
+        # Creates a Compute API client.
+        #
+        # @return [OCI::Core::ComputeClient]
         def compute
           generic_api(OCI::Core::ComputeClient)
         end
 
+        # Creates a Network API client.
+        #
+        # @return [OCI::Core::VirtualNetworkClient]
         def network
           generic_api(OCI::Core::VirtualNetworkClient)
         end
 
+        # Creates a Database API client.
+        #
+        # @return [OCI::Core::DatabaseClient]
         def dbaas
           generic_api(OCI::Database::DatabaseClient)
         end
 
+        # Creates an Identity API client.
+        #
+        # @return [OCI::Core::IdentityClient]
         def identity
           generic_api(OCI::Identity::IdentityClient)
         end
 
+        # Creates a Blockstorage API client.
+        #
+        # @return [OCI::Core::BlockstorageClient]
         def blockstorage
           generic_api(OCI::Core::BlockstorageClient)
         end
 
         private
 
+        # Instantiates the specified client class.
+        #
+        # @param klass [Class] The client class to instantiate.
+        # @return [Object] an instance of <b>klass</b>.
         def generic_api(klass)
           params = {}
           params[:proxy_settings] = api_proxy if api_proxy
@@ -73,6 +90,9 @@ module Kitchen
           klass.new(**params)
         end
 
+        # Determines the signing method if one is specified.
+        #
+        # @return [OCI::Auth::Signers::InstancePrincipalsSecurityTokenSigner, OCI::Auth::Signers::SecurityTokenSigner] an instance of the specified token signer.
         def signer
           if config[:use_instance_principals]
             OCI::Auth::Signers::InstancePrincipalsSecurityTokenSigner.new
@@ -81,6 +101,9 @@ module Kitchen
           end
         end
 
+        # Creates the token signer with a provided key.
+        #
+        # @return [OCI::Auth::Signers::SecurityTokenSigner]
         def token_signer
           pkey_content = oci_config.key_content || File.read(oci_config.key_file).strip
           pkey = OpenSSL::PKey::RSA.new(pkey_content, oci_config.pass_phrase)
@@ -89,6 +112,9 @@ module Kitchen
           OCI::Auth::Signers::SecurityTokenSigner.new(token, pkey)
         end
 
+        # Parse any specified proxy from either the kitchen config or the environment.
+        #
+        # @return [URI] a parsed proxy host.
         def proxy_config
           if config[:proxy_url]
             URI.parse(config[:proxy_url])
@@ -97,6 +123,9 @@ module Kitchen
           end
         end
 
+        # Create the proxy settings for the OCI API.
+        #
+        # @return [OCI::ApiClientProxySettings]
         def api_proxy
           prx = proxy_config
           return unless prx

data/lib/kitchen/driver/oci/blockstorage.rb

@@ -19,105 +19,126 @@
 module Kitchen
   module Driver
     class Oci
-      # generic class for blockstorage
+      # Base class for blockstorage models.
+      #
+      # @author Justin Steele <justin.steele@oracle.com>
       class Blockstorage < Oci # rubocop:disable Metrics/ClassLength
         require_relative "api"
         require_relative "config"
         require_relative "models/iscsi"
         require_relative "models/paravirtual"
 
-        def initialize(config, state, oci, api, action = :create)
+        def initialize(opts = {})
           super()
-          @config = config
-          @state = state
-          @oci = oci
-          @api = api
+          @config = opts[:config]
+          @state = opts[:state]
+          @oci = opts[:oci]
+          @api = opts[:api]
+          @logger = opts[:logger]
           @volume_state = {}
           @volume_attachment_state = {}
-          oci.compartment if action == :create
+          oci.compartment if opts[:action] == :create
         end
 
-        #
-        # The config provided by the driver
+        # The config provided by the driver.
         #
         # @return [Kitchen::LazyHash]
-        #
         attr_accessor :config
 
-        #
-        # The definition of the state of the instance from the statefile
+        # The definition of the state of the instance from the statefile.
         #
         # @return [Hash]
-        #
         attr_accessor :state
 
-        #
-        # The config object that contains properties of the authentication to OCI
+        # The config object that contains properties of the authentication to OCI.
         #
         # @return [Kitchen::Driver::Oci::Config]
-        #
         attr_accessor :oci
 
-        #
-        # The API object that contains each of the authenticated clients for interfacing with OCI
+        # The API object that contains each of the authenticated clients for interfacing with OCI.
         #
         # @return [Kitchen::Driver::Oci::Api]
-        #
         attr_accessor :api
 
-        # The definition of the state of a volume
+        # The instance of Kitchen::Logger in use by the active Kitchen::Instance.
         #
-        # @return [Hash]
+        # @return [Kitchen::Logger]
+        attr_accessor :logger
+
+        # The definition of the state of a volume.
         #
+        # @return [Hash]
         attr_accessor :volume_state
 
-        # The definition of the state of a volume attachment
+        # The definition of the state of a volume attachment.
         #
         # @return [Hash]
-        #
         attr_accessor :volume_attachment_state
 
+        # Create the volume as specified in the kitchen config.
+        #
+        # @param volume [Hash] the state of the current volume being created.
+        # @return [Array(OCI::Core::Models::Volume, Hash)] returns the actual volume response from OCI for the created volume and the state hash.
         def create_volume(volume)
-          info("Creating <#{volume[:name]}>...")
+          logger.info("Creating <#{volume[:name]}>...")
           result = api.blockstorage.create_volume(volume_details(volume))
           response = volume_response(result.data.id)
-          info("Finished creating <#{volume[:name]}>.")
+          logger.info("Finished creating <#{volume[:name]}>.")
           [response, final_state(response)]
         end
 
+        # Clones the specified volume.
+        #
+        # @param volume [Hash] the state of the current volume being cloned.
+        # @return [Array(OCI::Core::Models::Volume, Hash)] returns the actual volume response from OCI for the cloned volume and the state hash.
         def create_clone_volume(volume)
           clone_volume_name = clone_volume_display_name(volume[:volume_id])
-          info("Creating <#{clone_volume_name}>...")
+          logger.info("Creating <#{clone_volume_name}>...")
           result = api.blockstorage.create_volume(volume_clone_details(volume, clone_volume_name))
           response = volume_response(result.data.id)
-          info("Finished creating <#{clone_volume_name}>.")
+          logger.info("Finished creating <#{clone_volume_name}>.")
           [response, final_state(response)]
         end
 
+        # Attaches the volume to the instance.
+        #
+        # @param volume_details [OCI::Core::Models::Volume]
+        # @param server_id [String] the ocid of the compute instance we are attaching the volume to.
+        # @return [Hash] the updated state hash.
         def attach_volume(volume_details, server_id, volume_config)
-          info("Attaching <#{volume_details.display_name}>...")
+          logger.info("Attaching <#{volume_details.display_name}>...")
           attach_volume = api.compute.attach_volume(attachment_details(volume_details, server_id, volume_config))
           response = attachment_response(attach_volume.data.id)
-          info("Finished attaching <#{volume_details.display_name}>.")
+          logger.info("Finished attaching <#{volume_details.display_name}>.")
           final_state(response)
         end
 
+        # Deletes the specified volume.
+        #
+        # @param volume [Hash] the state of the current volume being deleted from the state file.
         def delete_volume(volume)
-          info("Deleting <#{volume[:display_name]}>...")
+          logger.info("Deleting <#{volume[:display_name]}>...")
           api.blockstorage.delete_volume(volume[:id])
           api.blockstorage.get_volume(volume[:id])
             .wait_until(:lifecycle_state, OCI::Core::Models::Volume::LIFECYCLE_STATE_TERMINATED)
-          info("Finished deleting <#{volume[:display_name]}>.")
+          logger.info("Finished deleting <#{volume[:display_name]}>.")
         end
 
+        # Detaches the specified volume.
+        #
+        # @param volume_attachment [Hash] the state of the current volume being deleted from the state file.
         def detatch_volume(volume_attachment)
-          info("Detaching <#{attachment_name(volume_attachment)}>...")
+          logger.info("Detaching <#{attachment_name(volume_attachment)}>...")
           api.compute.detach_volume(volume_attachment[:id])
           api.compute.get_volume_attachment(volume_attachment[:id])
             .wait_until(:lifecycle_state, OCI::Core::Models::VolumeAttachment::LIFECYCLE_STATE_DETACHED)
-          info("Finished detaching <#{attachment_name(volume_attachment)}>.")
+          logger.info("Finished detaching <#{attachment_name(volume_attachment)}>.")
         end
 
+        # Adds the volume and attachment info into the state.
+        #
+        # @param response [OCI::Core::Models::Volume, OCI::Core::Models::VolumeAttachment] The response from volume creation or attachment.
+        # @return [Hash]
         def final_state(response)
           case response
           when OCI::Core::Models::Volume
@@ -129,16 +150,26 @@ module Kitchen
 
         private
 
+        # The response from creating a volume.
+        #
+        # @return [OCI::Core::Models::Volume]
         def volume_response(volume_id)
           api.blockstorage.get_volume(volume_id)
             .wait_until(:lifecycle_state, OCI::Core::Models::Volume::LIFECYCLE_STATE_AVAILABLE).data
         end
 
+        # The response from attaching a volume.
+        #
+        # @return [OCI::Core::Models::VolumeAttachment]
         def attachment_response(attachment_id)
           api.compute.get_volume_attachment(attachment_id)
             .wait_until(:lifecycle_state, OCI::Core::Models::VolumeAttachment::LIFECYCLE_STATE_ATTACHED).data
         end
 
+        # The details of the volume that is being created.
+        #
+        # @param volume [Hash] the state of the current volume being created.
+        # @return [OCI::Core::Models::CreateVolumeDetails]
         def volume_details(volume)
           OCI::Core::Models::CreateVolumeDetails.new(
             compartment_id: oci.compartment,
@@ -150,6 +181,11 @@ module Kitchen
           )
         end
 
+        # The details of a volume that is being created as a clone of an existing volume.
+        #
+        # @param volume [Hash] the state of the current volume being cloned.
+        # @param clone_volume_name [String] the desired name of the new volume.
+        # @return [OCI::Core::Models::CreateVolumeDetails]
         def volume_clone_details(volume, clone_volume_name)
           OCI::Core::Models::CreateVolumeDetails.new(
             compartment_id: oci.compartment,
@@ -162,21 +198,37 @@ module Kitchen
           )
         end
 
+        # Returns a somewhat prettier display name for the volume attachment.
+        #
+        # @param attachment [Hash] the state of the current volume attachment being created.
+        # @return [String]
         def attachment_name(attachment)
           attachment[:display_name].gsub(/(?:paravirtual|iscsi)-/, "")
         end
 
+        # Returns the operating system from the instance.
+        #
+        # @param server_id [String] the ocid of the compute instance.
+        # @return [String]
         def server_os(server_id)
           image_id = api.compute.get_instance(server_id).data.image_id
           api.compute.get_image(image_id).data.operating_system
         end
 
+        # Adds the ocid and display name of the volume to the state.
+        #
+        # @param response [OCI::Core::Models::Volume]
+        # @return [Hash]
         def final_volume_state(response)
           volume_state.store(:id, response.id)
           volume_state.store(:display_name, response.display_name)
           volume_state
         end
 
+        # Appends the (Clone) string to the display name of the block volume that is being cloned.
+        #
+        # @param volume_id [String] the ocid of the volume being cloned.
+        # @return [String] the display name of the cloned volume.
         def clone_volume_display_name(volume_id)
           "#{api.blockstorage.get_volume(volume_id).data.to_hash[:displayName]} (Clone)"
         end

data/lib/kitchen/driver/oci/config.rb

@@ -22,20 +22,23 @@ require_relative "api"
 module Kitchen
   module Driver
     class Oci
-      # Config class that defines the oci config that will be used for the API calls
+      # Config class that defines the oci config that will be used for the API calls.
+      #
+      # @author Justin Steele <justin.steele@oracle.com>
       class Config
         def initialize(driver_config)
           setup_driver_config(driver_config)
           @config = oci_config
         end
 
-        #
-        # The config used to authenticate to OCI
+        # The config used to authenticate to OCI.
         #
         # @return [OCI::Config]
-        #
         attr_reader :config
 
+        # Creates a new instance of OCI::Config to be used to authenticate to OCI.
+        #
+        # @return [OCI::Config]
         def oci_config
           # OCI::Config is missing this
           OCI::Config.class_eval { attr_accessor :security_token_file } if @driver_config[:use_token_auth]
@@ -46,6 +49,12 @@ module Kitchen
           conf
         end
 
+        # The ocid of the compartment where the Kitchen instance will be created.
+        # * If <b>compartment_id</b> is specified in the kitchen.yml, that will be returned.
+        # * If <b>compartment_name</b> is specified in the kitchen.yml, lookup with the Identity API to find the ocid by the compartment name.
+        #
+        # @return [String] the ocid of the compartment where instances will be created.
+        # @raise [StandardError] if neither <b>compartment_id</b> nor <b>compartment_name</b> are specified OR if lookup by name fails to find a match.
         def compartment
           @compartment ||= @compartment_id
           return @compartment if @compartment
@@ -58,12 +67,19 @@ module Kitchen
 
         private
 
+        # Sets up instance variables from the driver config (parsed kitchen.yml) and compartment.
+        #
+        # @param config [Hash] the parsed config from the kitchen.yml.
         def setup_driver_config(config)
           @driver_config = config
           @compartment_id = config[:compartment_id]
           @compartment_name = config[:compartment_name]
         end
 
+        # Creates a new instance of OCI::Config either by loading the config from a file or returning a new instance that will be set.
+        #
+        # @param opts [Hash]
+        # @return [OCI::Config]
         def config_loader(opts = {})
           # this is to accommodate old versions of ruby that do not have a compact method on a Hash
           opts.reject! { |_, v| v.nil? }
@@ -72,6 +88,9 @@ module Kitchen
           OCI::Config.new
         end
 
+        # Returns the ocid of the tenancy from either the provided ocid or from your instance principals.
+        #
+        # @return [String]
         def tenancy
           if @driver_config[:use_instance_principals]
             sign = OCI::Auth::Signers::InstancePrincipalsSecurityTokenSigner.new
@@ -81,11 +100,17 @@ module Kitchen
           end
         end
 
+        # Looks up the compartment ocid by name by recursively querying the list of compartments with the Identity API.
+        #
+        # @return [String] the ocid of the compartment.
         def compartment_id_by_name(name)
           api = Oci::Api.new(config, @driver_config).identity
           all_compartments(api, config.tenancy).select { |c| c.name == name }&.first&.id
         end
 
+        # Pages through all of the compartments in the tenancy. This has to be a recursive process because the list_compartments API only returns 99 entries at a time.
+        #
+        # @return [Array] An array of OCI::Identity::Models::Compartment
         def all_compartments(api, tenancy, compartments = [], page = nil)
           current_compartments = api.list_compartments(tenancy, page: page)
           next_page = current_compartments.next_page

data/lib/kitchen/driver/oci/instance/common.rb

@@ -20,24 +20,31 @@ module Kitchen
   module Driver
     class Oci
       class Instance
-        # setter methods that populate launch details common to all instance models
+        # Setter methods that populate launch details common to all instance models.
+        #
+        # @author Justin Steele <justin.steele@oracle.com>
         module CommonLaunchDetails
+          # Assigns the ocid of the compartment to the launch details.
           def compartment_id
             launch_details.compartment_id = oci.compartment
           end
 
+          # Assigns the availability_domain to the launch details.
           def availability_domain
             launch_details.availability_domain = config[:availability_domain]
           end
 
+          # Assigns the defined_tags to the launch details.
           def defined_tags
             launch_details.defined_tags = config[:defined_tags]
           end
 
+          # Assigns the shape to the launch_details.
           def shape
             launch_details.shape = config[:shape]
           end
 
+          # Assigns the freeform_tags to the launch_details.
           def freeform_tags
             launch_details.freeform_tags = process_freeform_tags
           end
@@ -46,4 +53,3 @@ module Kitchen
     end
   end
 end
-

data/lib/kitchen/driver/oci/instance/compute.rb

@@ -20,14 +20,20 @@ module Kitchen
   module Driver
     class Oci
       class Instance
-        # setter methods that populate the details of OCI::Core::Models::LaunchInstanceDetails
+        # Setter methods that populate the details of OCI::Core::Models::LaunchInstanceDetails.
+        #
+        # @author Justin Steele <justin.steele@oracle.com>
         module ComputeLaunchDetails
+          # Assigns the display_name and create_vnic_details to the launch_details.
+          # * display_name is either the literal display_name provided in the kitchen config or a randomly generated one.
+          # * create_vnic_details is a populated instance of OCI::Core::Models::CreateVnicDetails.
           def hostname_display_name
             display_name = config[:display_name] || hostname
             launch_details.display_name = display_name
             launch_details.create_vnic_details = create_vnic_details(display_name)
           end
 
+          # Adds the preemptible_instance_config property tot he launch_details by creating a new instance of OCI::Core::Models::PreemptibleInstanceConfigDetails.
           def preemptible_instance_config
             return unless config[:preemptible_instance]
 
@@ -39,6 +45,7 @@ module Kitchen
             )
           end
 
+          # Adds the shape_config property to the launch_details by creating a new instance of OCI::Core::Models::LaunchInstanceShapeConfigDetails.
           def shape_config
             return if config[:shape_config].empty?
 
@@ -49,10 +56,12 @@ module Kitchen
             )
           end
 
+          # Adds the capacity_reservation_id property to the launch_details if an ocid is provided.
           def capacity_reservation
             launch_details.capacity_reservation_id = config[:capacity_reservation_id]
           end
 
+          # Adds the agent_config property to the launch_details.
           def agent_config
             launch_details.agent_config = OCI::Core::Models::LaunchInstanceAgentConfigDetails.new(
               are_all_plugins_disabled: config[:all_plugins_disabled],
@@ -61,6 +70,7 @@ module Kitchen
             )
           end
 
+          # Adds the source_details property to the launch_details for an instance that is being created from an image.
           def instance_source_via_image
             return if config[:boot_volume_id]
 
@@ -71,6 +81,7 @@ module Kitchen
             )
           end
 
+          # Adds the source_details property to the launch_details for an instance that is being created from a boot volume.
           def instance_source_via_boot_volume
             return unless config[:boot_volume_id]
 
@@ -80,6 +91,7 @@ module Kitchen
             )
           end
 
+          # Adds the metadata property to the launch_details.
           def instance_metadata
             launch_details.metadata = metadata
           end

data/lib/kitchen/driver/oci/instance/database.rb

@@ -20,39 +20,49 @@ module Kitchen
   module Driver
     class Oci
       class Instance
-        # setter methods that populate the details of OCI::Database::Models::CreateDatabaseDetails
+        # Setter methods that populate the details of OCI::Database::Models::CreateDatabaseDetails.
+        #
+        # @author Justin Steele <justin.steele@oracle.com>
         module DatabaseDetails
+          # Adds the database_software_image_id property to the database_details if provided.
           def database_software_image
             return unless config[:dbaas][:db_software_image_id]
 
             database_details.database_software_image_id = config[:dbaas][:db_software_image_id]
           end
 
+          # Adds the character_set property to the database_details.
           def character_set
             database_details.character_set = config[:dbaas][:character_set] ||= "AL32UTF8"
           end
 
+          # Adds the ncharacter_set property to the database_details.
           def ncharacter_set
             database_details.ncharacter_set = config[:dbaas][:ncharacter_set] ||= "AL16UTF16"
           end
 
+          # Adds the db_workload property to the database details.
           def db_workload
             workload = config[:dbaas][:db_workload] ||= OCI::Database::Models::CreateDatabaseDetails::DB_WORKLOAD_OLTP
             database_details.db_workload = workload
           end
 
+          # Adds the admin_password property to the database details.
           def admin_password
             database_details.admin_password = config[:dbaas][:admin_password] ||= random_password(%w{# _ -})
           end
 
+          # Adds the db_name property to the database_details.
           def db_name
             database_details.db_name = config[:dbaas][:db_name] ||= "dbaas1"
           end
 
+          # Adds the pdb_name property to the database_details.
           def pdb_name
             database_details.pdb_name = config[:dbaas][:pdb_name]
           end
 
+          # Adds the db_backup_config property to the database_details by creating a new instance of OCI::Database::Models::DbBackupConfig.
           def db_backup_config
             database_details.db_backup_config = OCI::Database::Models::DbBackupConfig.new.tap do |l|
               l.auto_backup_enabled = false
@@ -60,6 +70,7 @@ module Kitchen
             database_details
           end
 
+          # Adds the defined tags property to the database_details.
           def db_defined_tags
             database_details.defined_tags = config[:defined_tags]
           end

data/lib/kitchen/driver/oci/instance/db_home.rb

@@ -20,28 +20,36 @@ module Kitchen
   module Driver
     class Oci
       class Instance
-        # setter methods that populate the details of OCI::Database::Models::CreateDbHomeDetails
+        # Setter methods that populate the details of OCI::Database::Models::CreateDbHomeDetails.
+        #
+        # @author Justin Steele <justin.steele@oracle.com>
         module DbHomeDetails
+          # Adds the database property to the db_home_details.
           def database
             db_home_details.database = database_details
           end
 
+          # Adds the db_version property to the db_home_details.
+          # @raise [StandardError] if a version has not been provided.
           def db_version
             raise "db_version cannot be nil!" if config[:dbaas][:db_version].nil?
 
             db_home_details.db_version = config[:dbaas][:db_version]
           end
 
+          # Adds the display_name property to db_home_details.
           def db_home_display_name
             db_home_details.display_name = ["dbhome", random_number(10)].compact.join
           end
 
+          # Adds the database_software_image_id to the db_home_details.
           def db_home_software_image
             return unless config[:dbaas][:db_software_image_id]
 
             db_home_details.database_software_image_id = config[:dbaas][:db_software_image_id]
           end
 
+          # Adds the defined_tags to the db_home_details.
           def db_home_defined_tags
             db_home_details.defined_tags = config[:defined_tags]
           end