kitchen-oci 1.26.0 → 1.27.0

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

@@ -22,7 +22,9 @@ module Kitchen
   module Driver
     class Oci
       module Models
-        # Compute instance model
+        # Compute instance model.
+        #
+        # @author Justin Steele <justin.steele@oracle.com>
         class Compute < Instance # rubocop:disable Metrics/ClassLength
           include ComputeLaunchDetails
 
@@ -31,13 +33,14 @@ module Kitchen
             @launch_details = OCI::Core::Models::LaunchInstanceDetails.new
           end
 
-          #
-          # The details model that describes a compute instance
+          # The details model that describes a compute instance.
           #
           # @return [OCI::Core::Models::LaunchInstanceDetails]
-          #
           attr_accessor :launch_details
 
+          # Launches a compute instance.
+          #
+          # @return [Hash] the finalized state after the instance has been launched and is running.
           def launch
             process_windows_options
             response = api.compute.launch_instance(launch_instance_details)
@@ -46,11 +49,13 @@ module Kitchen
             final_state(state, instance_id)
           end
 
+          # Terminates a compute instance.
           def terminate
             api.compute.terminate_instance(state[:server_id])
             api.compute.get_instance(state[:server_id]).wait_until(:lifecycle_state, OCI::Core::Models::Instance::LIFECYCLE_STATE_TERMINATING)
           end
 
+          # Reboots a compute instance.
           def reboot
             api.compute.instance_action(state[:server_id], "SOFTRESET")
             api.compute.get_instance(state[:server_id]).wait_until(:lifecycle_state, OCI::Core::Models::Instance::LIFECYCLE_STATE_RUNNING)
@@ -58,6 +63,10 @@ module Kitchen
 
           private
 
+          # The ocid of the image to be used when creating the instance.
+          # * If <b>image_id</b> is specified in the kitchen.yml, that will be returned.
+          # * If <b>image_name</b> is specified in the kitchen.yml, lookup with the Compute API to find the ocid of the image by name.
+          # @raise [StandardError] if neither <b>image_id</b> nor <b>image_name</b> are specified OR the image lookup by name fails to find a match.
           def image_id
             return config[:image_id] if config[:image_id]
 
@@ -66,6 +75,9 @@ module Kitchen
             image_id_by_name
           end
 
+          # Looks up the image ocid by name by recursively querying the list of images with the Compute API.
+          #
+          # @return [String] the ocid of the image.
           def image_id_by_name
             image_name = image_name_conversion
             image_list = images.select { |i| i.display_name.match(/#{image_name}/) }
@@ -77,22 +89,35 @@ module Kitchen
             latest_image_id(image_list)
           end
 
+          # Automatically append aarch64 to a specified image name if an ARM shape is specified.
+          #
+          # @return [String] the modified image name.
           def image_name_conversion
             image_name = config[:image_name].gsub(" ", "-")
-            if config[:shape] =~ /^VM\.Standard\.A\d+\.Flex$/ && !config[:image_name].include?("aarch64")
-              image_name = "#{image_name}-aarch64"
-            end
+            image_name = "#{image_name}-aarch64" if config[:shape] =~ /^VM\.Standard\.A\d+\.Flex$/ && !config[:image_name].include?("aarch64")
             image_name
           end
 
+          # Filter images by name.
+          #
+          # @param image_list [Array] a list of the display names of all available images.
+          # @param image_name [String] the image name or regular expression provided in the config.
+          # @return [Array] all display names that match the image_name.
           def filter_image_list(image_list, image_name)
             image_list.select { |i| i.display_name.match(/#{image_name}-[0-9]{4}\.[0-9]{2}\.[0-9]{2}/) }
           end
 
+          # Finds the ocid of the most recent image by time created.
+          #
+          # @param image_list [Array] a list of all of the display names that matched the search string.
+          # @return [String] the ocid of the latest matching image.
           def latest_image_id(image_list)
             image_list.sort_by! { |o| ((DateTime.parse(Time.now.utc.to_s) - o.time_created) * 24 * 60 * 60).to_i }.first.id
           end
 
+          # Pages through all of the images in the compartment. This has to be a recursive process because the list_images API only returns 99 entries at a time.
+          #
+          # @return [Array] An array of OCI::Core::Models::Image.
           def images(image_list = [], page = nil)
             current_images = api.compute.list_images(oci.compartment, page: page)
             next_page = current_images.next_page
@@ -101,6 +126,9 @@ module Kitchen
             image_list.flatten
           end
 
+          # Clone the specified boot volume and return the new ocid.
+          #
+          # @return [String]
           def clone_boot_volume
             logger.info("Cloning boot volume...")
             cbv = api.blockstorage.create_boot_volume(clone_boot_volume_details)
@@ -109,6 +137,9 @@ module Kitchen
             cbv.data.id
           end
 
+          # Create a new instance of OCI::Core::Models::CreateBootVolumeDetails.
+          #
+          # @return [OCI::Core::Models::CreateBootVolumeDetails]
           def clone_boot_volume_details
             OCI::Core::Models::CreateBootVolumeDetails.new(
               source_details: OCI::Core::Models::BootVolumeSourceFromBootVolumeDetails.new(
@@ -120,10 +151,17 @@ module Kitchen
             )
           end
 
+          # Create the display name of the cloned boot volume.
+          #
+          # @return [String]
           def boot_volume_display_name
             "#{api.blockstorage.get_boot_volume(config[:boot_volume_id]).data.display_name} (Clone)"
           end
 
+          # Get the IP address of the instance from the vnic.
+          #
+          # @param instance_id [String] the ocid of the instance.
+          # @return [String]
           def instance_ip(instance_id)
             vnic = vnics(instance_id).select(&:is_primary).first
             if public_ip_allowed?
@@ -133,10 +171,18 @@ module Kitchen
             end
           end
 
+          # Get a list of all vnics attached to the instance.
+          #
+          # @param instance_id [String] the ocid of the instance.
+          # @return [Array] a list of OCI::Core::Models::Vnic.
           def vnics(instance_id)
             vnic_attachments(instance_id).map { |att| api.network.get_vnic(att.vnic_id).data }
           end
 
+          # Get a list of all vnic attachments associated with the instance.
+          #
+          # @param instance_id [String] the ocid of the instance.
+          # @return [Array] a list of OCI::Core::Models::VnicAttachment.
           def vnic_attachments(instance_id)
             att = api.compute.list_vnic_attachments(oci.compartment, instance_id: instance_id).data
             raise "Could not find any VNIC attachments" unless att.any?
@@ -144,10 +190,16 @@ module Kitchen
             att
           end
 
+          # Generate a hostname that includes some randomness.
+          #
+          # @return [String]
           def hostname
             %W{#{config[:hostname_prefix]} #{config[:instance_name]} #{random_string(6)}}.uniq.compact.join("-")
           end
 
+          # Create the details of the vnic that will be created.
+          #
+          # @param name [String] the display name of the instance being created.
           def create_vnic_details(name)
             OCI::Core::Models::CreateVnicDetails.new(
               assign_public_ip: public_ip_allowed?,
@@ -158,6 +210,9 @@ module Kitchen
             )
           end
 
+          # Read in the public ssh key.
+          #
+          # @return [String]
           def pubkey
             if config[:ssh_keygen]
               logger.info("Generating public/private rsa key pair")
@@ -166,6 +221,7 @@ module Kitchen
             File.readlines(public_key_file).first.chomp
           end
 
+          # Add our special sauce to the instance metadata to be executed by cloud-init.
           def metadata
             md = {}
             inject_powershell
@@ -175,6 +231,7 @@ module Kitchen
             md
           end
 
+          # Piece together options that a required for Windows instances.
           def process_windows_options
             return unless windows_state?
 
@@ -182,20 +239,32 @@ module Kitchen
             state.store(:password, config[:winrm_password] || random_password(%w{@ - ( ) .}))
           end
 
+          # Do the windows-y things exist in the kitchen config or the state?
+          #
+          # @return [Boolean]
           def windows_state?
             config[:setup_winrm] && config[:password].nil? && state[:password].nil?
           end
 
+          # Has custom user_data been provided in the config?
+          #
+          # @return [Boolean]
           def user_data?
             config[:user_data] && !config[:user_data].empty?
           end
 
+          # Read in and bind our winrm setup script.
+          #
+          # @return [String]
           def winrm_ps1
             filename = File.join(__dir__, %w{.. .. .. .. .. tpl setup_winrm.ps1.erb})
             tpl = ERB.new(File.read(filename))
             tpl.result(binding)
           end
 
+          # Inject all of the winrm setup stuff into cloud-init.
+          #
+          # @return [Hash] the user_data config hash with the winrm stuff injected.
           def inject_powershell
             return unless config[:setup_winrm]
 

data/lib/kitchen/driver/oci/models/dbaas.rb

@@ -22,8 +22,10 @@ module Kitchen
   module Driver
     class Oci
       module Models
-        # dbaas model
-        class Dbaas < Instance # rubocop:disable Metrics/ClassLength
+        # Database system model.
+        #
+        # @author Justin Steele <justin.steele@oracle.com>
+        class Dbaas < Instance
           include DbaasLaunchDetails
 
           def initialize(opts = {})
@@ -33,27 +35,24 @@ module Kitchen
             @db_home_details = OCI::Database::Models::CreateDbHomeDetails.new
           end
 
-          #
-          # The details model that describes the db system
+          # The details model that describes the db system.
           #
           # @return [OCI::Database::Models::LaunchDbSystemDetails]
-          #
           attr_accessor :launch_details
 
-          #
-          # The details model that describes the database
+          # The details model that describes the database.
           #
           # @return [OCI::Database::Models::CreateDatabaseDetails]
-          #
           attr_accessor :database_details
 
-          #
-          # The details model that describes the database home
+          # The details model that describes the database home.
           #
           # @return [OCI::Database::Models::CreateDbHomeDetails]
-          #
           attr_accessor :db_home_details
 
+          # Launches a database system.
+          #
+          # @return [Hash] the finalized state after the instance has been launched and is running.
           def launch
             response = api.dbaas.launch_db_system(launch_instance_details)
             instance_id = response.data.id
@@ -63,12 +62,14 @@ module Kitchen
             final_state(state, instance_id)
           end
 
+          # Terminates a DBaaS system.
           def terminate
             api.dbaas.terminate_db_system(state[:server_id])
             api.dbaas.get_db_system(state[:server_id]).wait_until(:lifecycle_state, OCI::Database::Models::DbSystem::LIFECYCLE_STATE_TERMINATING,
                                                                   max_interval_seconds: 900, max_wait_seconds: 21_600)
           end
 
+          # Reboots a DBaaS node.
           def reboot
             db_node_id = dbaas_node(state[:server_id]).first.id
             api.dbaas.db_node_action(db_node_id, "SOFTRESET")
@@ -77,6 +78,10 @@ module Kitchen
 
           private
 
+          # Get the IP address of the instance from the vnic.
+          #
+          # @param instance_id [String] the ocid of the instance.
+          # @return [String]
           def instance_ip(instance_id)
             vnic = dbaas_node(instance_id).select(&:vnic_id).first.vnic_id
             if public_ip_allowed?
@@ -86,18 +91,30 @@ module Kitchen
             end
           end
 
+          # Get the ocid of the database node associated with the database system.
+          #
+          # @param instance_id [String] the ocid of the database system.
           def dbaas_node(instance_id)
             api.dbaas.list_db_nodes(oci.compartment, db_system_id: instance_id).data
           end
 
+          # Sets the hostname_prefix as defined in the kitchen config.
+          #
+          # @return [String]
           def hostname_prefix
             config[:hostname_prefix]
           end
 
+          # Generates a random suffix to the hostname prefix.
+          #
+          # @return [String]
           def long_hostname_suffix
             [random_string(25 - hostname_prefix.length), random_string(3)].compact.join("-")
           end
 
+          # Read in the public ssh key.
+          #
+          # @return [String]
           def read_public_key
             if config[:ssh_keygen]
               logger.info("Generating public/private rsa key pair")

data/lib/kitchen/driver/oci/models/iscsi.rb

@@ -21,20 +21,26 @@ module Kitchen
   module Driver
     class Oci
       module Models
-        # iscsi volume attachment model
+        # iSCSI volume model.
+        #
+        # @author Justin Steele <justin.steele@oracle.com>
         class Iscsi < Blockstorage
           def initialize(opts = {})
             super
             @attachment_type = "iscsi"
           end
 
-          #
-          # The type of attachment being created
+          # The type of attachment being created.
           #
           # @return [String]
-          #
           attr_reader :attachment_type
 
+          # Creates the attachment details for an iSCSI volume.
+          #
+          # @param volume_details [OCI::Core::Models::Volume]
+          # @param server_id [String] the ocid of the compute instance to which the volume will be attached.
+          # @param volume_config [Hash] the state of the current volume being processed as specified in the kitchen.yml.
+          # @return [OCI::Core::Models::AttachIScsiVolumeDetails]
           def attachment_details(volume_details, server_id, volume_config)
             device = volume_config[:device] unless server_os(server_id).downcase =~ /windows/
             OCI::Core::Models::AttachIScsiVolumeDetails.new(
@@ -45,6 +51,10 @@ module Kitchen
             )
           end
 
+          # Adds the volume attachment info into the state.
+          #
+          # @param response [OCI::Core::Models::VolumeAttachment]
+          # @return [Hash]
           def final_volume_attachment_state(response)
             volume_attachment_state.store(:id, response.id)
             volume_attachment_state.store(:display_name, response.display_name)

data/lib/kitchen/driver/oci/models/paravirtual.rb

@@ -21,20 +21,26 @@ module Kitchen
   module Driver
     class Oci
       module Models
-        # paravirtual attachment model
+        # Paravirtual volume model.
+        #
+        # @author Justin Steele <justin.steele@oracle.com>
         class Paravirtual < Blockstorage
           def initialize(opts = {})
             super
             @attachment_type = "paravirtual"
           end
 
-          #
-          # The type of attachment being created
+          # The type of attachment being created.
           #
           # @return [String]
-          #
           attr_reader :attachment_type
 
+          # Creates the attachment details for a Paravirtual volume.
+          #
+          # @param volume_details [OCI::Core::Models::Volume]
+          # @param server_id [String] the ocid of the compute instance to which the volume will be attached.
+          # @param volume_config [Hash] the state of the current volume being processed as specified in the kitchen.yml.
+          # @return [OCI::Core::Models::AttachParavirtualizedVolumeDetails]
           def attachment_details(volume_details, server_id, volume_config)
             device = volume_config[:device] unless server_os(server_id).downcase =~ /windows/
             OCI::Core::Models::AttachParavirtualizedVolumeDetails.new(
@@ -45,6 +51,10 @@ module Kitchen
             )
           end
 
+          # Adds the volume attachment info into the state.
+          #
+          # @param response [OCI::Core::Models::VolumeAttachment]
+          # @return [Hash]
           def final_volume_attachment_state(response)
             volume_attachment_state.store(:id, response.id)
             volume_attachment_state.store(:display_name, response.display_name)

data/lib/kitchen/driver/oci.rb

@@ -32,10 +32,11 @@ module Kitchen
     # Oracle OCI driver for Kitchen.
     #
     # @author Stephen Pearson <stephen.pearson@oracle.com>
-    class Oci < Kitchen::Driver::Base # rubocop:disable Metrics/ClassLength
+    class Oci < Kitchen::Driver::Base
       require_relative "oci_version"
-      require_relative "oci/models"
-      require_relative "oci/volumes"
+      require_relative "oci/mixin/actions"
+      require_relative "oci/mixin/models"
+      require_relative "oci/mixin/volumes"
 
       plugin_version Kitchen::Driver::OCI_VERSION
       kitchen_driver_api_version 2
@@ -115,9 +116,10 @@ module Kitchen
         raise UserError, "#{driver.class}<#{driver.instance.name}>#config#{message}"
       end
 
-      include Kitchen::Driver::Oci::Models
-      include Kitchen::Driver::Oci::Volumes
-
+      # Creates an instance.
+      # (see Kitchen::Driver::Base#create)
+      #
+      # @param state [Hash] (see Kitchen::StateFile)
       def create(state)
         return if state[:server_id]
 
@@ -126,10 +128,14 @@ module Kitchen
         inst = instance_class(config, state, oci, api, __method__)
         launch(state, inst)
         create_and_attach_volumes(config, state, oci, api)
-        process_post_script(state)
+        execute_post_create_script(state)
         reboot(state, inst)
       end
 
+      # Destorys an instance.
+      # (see Kitchen::Driver::Base#destroy)
+      #
+      # @param state [Hash] (see Kitchen::StateFile)
       def destroy(state)
         return unless state[:server_id]
 
@@ -141,51 +147,20 @@ module Kitchen
 
       private
 
+      include Kitchen::Driver::Oci::Mixin::Actions
+      include Kitchen::Driver::Oci::Mixin::Models
+      include Kitchen::Driver::Oci::Mixin::Volumes
+
+      # Creates the OCI config and API clients.
+      #
+      # @param action [Symbol] the name of the method that called this method.
+      # @return [Oci::Config, Oci::Api]
       def auth(action)
         oci = Oci::Config.new(config)
         api = Oci::Api.new(oci.config, config)
         oci.compartment if action == :create
         [oci, api]
       end
-
-      def launch(state, inst)
-        state_details = inst.launch
-        state.merge!(state_details)
-        instance.transport.connection(state).wait_until_ready
-      end
-
-      def process_post_script(state)
-        return if config[:post_create_script].nil?
-
-        info("Running post create script")
-        script = config[:post_create_script]
-        instance.transport.connection(state).execute(script)
-      end
-
-      def reboot(state, inst)
-        return unless config[:post_create_reboot]
-
-        instance.transport.connection(state).close
-        inst.reboot
-        instance.transport.connection(state).wait_until_ready
-      end
-
-      def detatch_and_delete_volumes(state, oci, api)
-        return unless state[:volumes]
-
-        bls = Blockstorage.new(config: config, state: state, oci: oci, api: api, action: :destroy, logger: instance.logger)
-        state[:volume_attachments].each { |att| bls.detatch_volume(att) }
-        state[:volumes].each { |vol| bls.delete_volume(vol) }
-      end
-
-      def terminate(state, inst)
-        instance.transport.connection(state).close
-        inst.terminate
-        if state[:ssh_key]
-          FileUtils.rm_f(state[:ssh_key])
-          FileUtils.rm_f("#{state[:ssh_key]}.pub")
-        end
-      end
     end
   end
 end

data/lib/kitchen/driver/oci_version.rb

@@ -20,6 +20,8 @@
 module Kitchen
   module Driver
     # Version string for Oracle OCI Kitchen driver
-    OCI_VERSION = "1.26.0"
+    #
+    # @author Stephen Pearson (<stephen.pearson@oracle.com>)
+    OCI_VERSION = "1.27.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kitchen-oci
 version: !ruby/object:Gem::Version
-  version: 1.26.0
+  version: 1.27.0
 platform: ruby
 authors:
 - Stephen Pearson
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2025-01-17 00:00:00.000000000 Z
+date: 2025-02-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: oci
@@ -109,6 +109,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: A Test Kitchen Driver for Oracle Cloud Infrastructure
 email:
 - stephen.pearson@oracle.com
@@ -128,18 +142,25 @@ files:
 - lib/kitchen/driver/oci/instance/database.rb
 - lib/kitchen/driver/oci/instance/db_home.rb
 - lib/kitchen/driver/oci/instance/dbaas.rb
-- lib/kitchen/driver/oci/models.rb
+- lib/kitchen/driver/oci/mixin/actions.rb
+- lib/kitchen/driver/oci/mixin/models.rb
+- lib/kitchen/driver/oci/mixin/volumes.rb
 - lib/kitchen/driver/oci/models/compute.rb
 - lib/kitchen/driver/oci/models/dbaas.rb
 - lib/kitchen/driver/oci/models/iscsi.rb
 - lib/kitchen/driver/oci/models/paravirtual.rb
-- lib/kitchen/driver/oci/volumes.rb
 - lib/kitchen/driver/oci_version.rb
 - tpl/setup_winrm.ps1.erb
 homepage: https://github.com/stephenpearson/kitchen-oci
 licenses:
 - Apache-2.0
-metadata: {}
+metadata:
+  bug_tracker_uri: https://github.com/stephenpearson/kitchen-oci/issues
+  changelog_uri: https://github.com/stephenpearson/kitchen-oci/blob/master/CHANGELOG.md
+  documentation_uri: https://github.com/stephenpearson/kitchen-oci/blob/master/README.md
+  homepage_uri: https://github.com/stephenpearson/kitchen-oci
+  source_code_uri: https://github.com/stephenpearson/kitchen-oci
+  rubygems_mfa_required: 'true'
 post_install_message: 
 rdoc_options: []
 require_paths:

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

@@ -1,48 +0,0 @@
-# frozen_string_literal: true
-
-#
-# Author:: Justin Steele (<justin.steele@oracle.com>)
-#
-# Copyright (C) 2024, Stephen Pearson
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#    http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-
-module Kitchen
-  module Driver
-    class Oci
-      # models definitions
-      module Models
-        require_relative "instance"
-        require_relative "blockstorage"
-
-        def instance_class(config, state, oci, api, action)
-          Oci::Models.const_get(config[:instance_type].capitalize).new(config: config, state: state, oci: oci, api: api, action: action, logger: instance.logger)
-        end
-
-        def volume_class(type, config, state, oci, api)
-          Oci::Models.const_get(volume_attachment_type(type)).new(config: config, state: state, oci: oci, api: api, logger: instance.logger)
-        end
-
-        private
-
-        def volume_attachment_type(type)
-          if type.nil?
-            "Paravirtual"
-          else
-            type.capitalize
-          end
-        end
-      end
-    end
-  end
-end