kitchen-oci 1.26.0 → 1.27.0

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

@@ -23,69 +23,85 @@ module Kitchen
   module Driver
     class Oci
       class Instance
-        # setter methods that populate the details of OCI::Database::Models::LaunchDbSystemDetails
+        # Setter methods that populate the details of OCI::Database::Models::LaunchDbSystemDetails.
+        #
+        # @author Justin Steele <justin.steele@oracle.com>
         module DbaasLaunchDetails
           include DatabaseDetails
           include DbHomeDetails
           #
           # TODO: add support for the #domain property
           #
+
+          # Adds the db_home property to the launch_details.
           def db_home
             launch_details.db_home = db_home_details
           end
 
+          # Adds the subnet_id property to the launch_details.
           def subnet_id
             launch_details.subnet_id = config[:subnet_id]
           end
 
+          # Adds the nsg_ids property to the launch_details.
           def nsg_ids
             launch_details.nsg_ids = config[:nsg_ids]
           end
 
+          # Adds the hostname property to the launch_details.
+          # The hostname must begin with an alphabetic character, and can contain alphanumeric characters and hyphens (-).
+          # The maximum length of the hostname is 16 characters.
           def hostname
-            # The hostname must begin with an alphabetic character, and can contain alphanumeric characters and hyphens (-).
-            # The maximum length of the hostname is 16 characters
             long_name = [hostname_prefix, long_hostname_suffix].compact.join("-")
             trimmed_name = [hostname_prefix[0, 12], random_string(3)].compact.join("-")
             launch_details.hostname = [long_name, trimmed_name].min { |l, t| l.size <=> t.size }
           end
 
+          # Adds the display_name property to the launch details.
+          # The user-friendly name for the DB system. The name does not have to be unique.
           def display_name
-            # The user-friendly name for the DB system. The name does not have to be unique.
             launch_details.display_name = [config[:hostname_prefix], random_string(4), random_number(2)].compact.join("-")
           end
 
+          # Adds the node_count property to the launch_details.
           def node_count
             launch_details.node_count = 1
           end
 
+          # Adds the ssh_public_keys property to the launch_details.
           def pubkey
             result = []
             result << read_public_key
             launch_details.ssh_public_keys = result
           end
 
+          # Adds the cpu_core_count property to the launch_details.
           def cpu_core_count
             launch_details.cpu_core_count = config[:dbaas][:cpu_core_count] ||= 2
           end
 
+          # Adds the license_model property to the launch_details.
           def license_model
             license = config[:dbaas][:license_model] ||= OCI::Database::Models::DbSystem::LICENSE_MODEL_BRING_YOUR_OWN_LICENSE
             launch_details.license_model = license
           end
 
+          # Adds the initial_data_size_in_gb property to the launch_details.
           def initial_data_storage_size_in_gb
             launch_details.initial_data_storage_size_in_gb = config[:dbaas][:initial_data_storage_size_in_gb] ||= 256
           end
 
+          # Adds the database_edition property to the launch_details.
           def database_edition
             db_edition = config[:dbaas][:database_edition] ||= OCI::Database::Models::DbSystem::DATABASE_EDITION_ENTERPRISE_EDITION
             launch_details.database_edition = db_edition
           end
 
+          # Adds the cluster_name property to the launch_details.
+          # 11 character limit for cluster_name in DBaaS.
           def cluster_name
             prefix = config[:hostname_prefix].split("-")[0]
-            # 11 character limit for cluster_name in DBaaS
+
             cn = if prefix.length >= 11
                    prefix[0, 11]
                  else
@@ -98,4 +114,3 @@ module Kitchen
     end
   end
 end
-

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

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-#
 # Author:: Justin Steele (<justin.steele@oracle.com>)
 #
 # Copyright (C) 2024, Stephen Pearson
@@ -20,7 +19,9 @@
 module Kitchen
   module Driver
     class Oci
-      # generic class for instance models
+      # Base class for instance models.
+      #
+      # @author Justin Steele <justin.steele@oracle.com>
       class Instance < Oci # rubocop:disable Metrics/ClassLength
         require_relative "api"
         require_relative "config"
@@ -39,41 +40,35 @@ module Kitchen
           @logger = opts[:logger]
         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 instance of Kitchen::Logger in use by the active Kitchen::Instance
+        # The instance of Kitchen::Logger in use by the active Kitchen::Instance.
         #
         # @return [Kitchen::Logger]
-        #
         attr_accessor :logger
 
+        # Adds the instance info into the state.
+        #
+        # @param state [Hash] The state from kitchen.
+        # @return [Hash]
         def final_state(state, instance_id)
           state.store(:server_id, instance_id)
           state.store(:hostname, instance_ip(instance_id))
@@ -82,6 +77,9 @@ module Kitchen
 
         private
 
+        # Calls all of the setter methods for the self.
+        #
+        # @return [OCI::Core::Models::LaunchInstanceDetails, OCI::Database::Models::LaunchDbSystemDetails] the fully populated launch details for the specific instance type.
         def launch_instance_details
           launch_methods = []
           self.class.ancestors.reverse.select { |m| m.is_a?(Module) && m.name.start_with?("#{self.class.superclass}::") }.each do |klass|
@@ -91,11 +89,17 @@ module Kitchen
           launch_details
         end
 
+        # Checks if public IP addresses are allowed in the specified subnet.
+        #
+        # @return [Boolean]
         def public_ip_allowed?
           subnet = api.network.get_subnet(config[:subnet_id]).data
           !subnet.prohibit_public_ip_on_vnic
         end
 
+        # Returns the location of the public ssh key.
+        #
+        # @return [String]
         def public_key_file
           if config[:ssh_keygen]
             "#{config[:kitchen_root]}/.kitchen/.ssh/#{config[:instance_name]}_rsa.pub"
@@ -104,10 +108,14 @@ module Kitchen
           end
         end
 
+        # Returns the name of the private key file.
+        #
+        # @return [String]
         def private_key_file
           public_key_file.gsub(".pub", "")
         end
 
+        # Generates an RSA key pair to be used to SSH to the instance and updates the state with the full path to the private key.
         def gen_key_pair
           FileUtils.mkdir_p("#{config[:kitchen_root]}/.kitchen/.ssh")
           rsa_key = OpenSSL::PKey::RSA.new(4096)
@@ -116,16 +124,25 @@ module Kitchen
           state.store(:ssh_key, private_key_file)
         end
 
+        # Writes the private key.
+        #
+        # @param rsa_key [OpenSSL::PKey::RSA] the generated RSA key.
         def write_private_key(rsa_key)
           File.open(private_key_file, "wb") { |k| k.write(rsa_key.to_pem) }
           File.chmod(0600, private_key_file)
         end
 
+        # Writes the encoded private key as a public key.
+        #
+        # @param rsa_key [OpenSSL::PKey::RSA] the generated RSA key.
         def write_public_key(rsa_key)
           File.open(public_key_file, "wb") { |k| k.write("ssh-rsa #{encode_private_key(rsa_key)} #{config[:instance_name]}") }
           File.chmod(0600, public_key_file)
         end
 
+        # Encodes the private key.
+        #
+        # @param rsa_key [OpenSSL::PKey::RSA] the generated RSA key.
         def encode_private_key(rsa_key)
           prefix = "#{[7].pack("N")}ssh-rsa"
           exponent = rsa_key.e.to_s(0)
@@ -133,6 +150,10 @@ module Kitchen
           ["#{prefix}#{exponent}#{modulus}"].pack("m0")
         end
 
+        # Generates a random password.
+        #
+        # @param special_chars [Array] an array of special characters to include in the random password.
+        # @return [String]
         def random_password(special_chars)
           (Array.new(5) { special_chars.sample } +
             Array.new(5) { ("a".."z").to_a.sample } +
@@ -140,14 +161,25 @@ module Kitchen
             Array.new(5) { ("0".."9").to_a.sample }).shuffle.join
         end
 
+        # Generates a random string of letters.
+        #
+        # @param length [Integer] how many characters to randomize.
+        # @return [String]
         def random_string(length)
           Array.new(length) { ("a".."z").to_a.sample }.join
         end
 
+        # Generates a random string of numbers.
+        #
+        # @param length [Integer] how many numbers to randomize.
+        # @return [String]
         def random_number(length)
           Array.new(length) { ("0".."9").to_a.sample }.join
         end
 
+        # Parses freeform tags to be added to the instance by the setter method.
+        #
+        # @return [Hash]
         def process_freeform_tags
           tags = %w{run_list policyfile}
           fft = config[:freeform_tags]
@@ -161,6 +193,9 @@ module Kitchen
           fft
         end
 
+        # Encodes specified user_data to be added to cloud-init.
+        #
+        # @return [Base64]
         def user_data
           case config[:user_data]
           when Array
@@ -170,6 +205,9 @@ module Kitchen
           end
         end
 
+        # GZips processed user_data prior to being encoded to allow for multi-part inclusions.
+        #
+        # @return [Zlib::GzipWriter]
         def multi_part_user_data
           boundary = "MIMEBOUNDARY_#{random_string(20)}"
           msg = ["Content-Type: multipart/mixed; boundary=\"#{boundary}\"",
@@ -180,6 +218,10 @@ module Kitchen
           gzip << txt
         end
 
+        # Joins all of the bits provided by each itema in user_data with the provided boundary and content headers.
+        #
+        # @param boundary [String]
+        # @return [Array]
         def mime_parts(boundary)
           msg = []
           config[:user_data].each do |m|
@@ -193,6 +235,10 @@ module Kitchen
           msg
         end
 
+        # Reads either the specified file or the text provided inline.
+        #
+        # @param part [Hash] the current item in the user_data hash being processed.
+        # @return [Array]
         def read_part(part)
           if part[:path]
             content = File.read part[:path]

data/lib/kitchen/driver/oci/mixin/actions.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+#
+# Author:: Justin Steele (<justin.steele@oracle.com>)
+#
+# Copyright (C) 2025, 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
+      module Mixin
+        # Actions that can be performed on an instance.
+        #
+        # @author Justin Steele <justin.steele@oracle.com>
+        module Actions
+          # Launches an instance.
+          #
+          # @param state [Hash] (see Kitchen::StateFile)
+          # @param inst [Class] the specific class of instance being launched.
+          def launch(state, inst)
+            state_details = inst.launch
+            state.merge!(state_details)
+            instance.transport.connection(state).wait_until_ready
+          end
+
+          # Executes the post script on the instance.
+          #
+          # @param state [Hash] (see Kitchen::StateFile)
+          def execute_post_create_script(state)
+            return if config[:post_create_script].nil?
+
+            if config[:post_create_script].is_a?(String)
+              execute_post_create_string(state)
+            elsif config[:post_create_script].is_a?(Array)
+              execute_post_create_file(state)
+            end
+          end
+
+          # Executes the post create script from a String.
+          #
+          # @param state [Hash] (see Kitchen::StateFile)
+          def execute_post_create_string(state)
+            info("Running post create script")
+            script = config[:post_create_script]
+            instance.transport.connection(state).execute(script)
+          end
+
+          # Reads the specified file and executes as a post create script.
+          #
+          # @param state [Hash] (see Kitchen::StateFile)
+          def execute_post_create_file(state)
+            config[:post_create_script].each do |script|
+              info("Running post create script #{File.basename(script)}")
+              script = File.read script
+              instance.transport.connection(state).execute(script)
+            end
+          end
+
+          # Reboots an instance.
+          #
+          # @param state [Hash] (see Kitchen::StateFile)
+          # @param inst [Class] the specific class of instance being rebooted.
+          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
+
+          # Terminates an instance.
+          #
+          # @param state [Hash] (see Kitchen::StateFile)
+          # @param inst [Class] the specific class of instance being launched.
+          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
+  end
+end

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

@@ -0,0 +1,70 @@
+# 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
+      module Mixin
+        # Instantiates the class of the specified model.
+        #
+        # @author Justin Steele <justin.steele@oracle.com>
+        module Models
+          require_relative "../instance"
+          require_relative "../blockstorage"
+
+          # Instantiates an instance model.
+          #
+          # @param config [Kitchen::LazyHash] The config provided by the driver.
+          # @param state [Hash] (see Kitchen::StateFile)
+          # @param oci [Kitchen::Driver::Oci::Config] a populated OCI config class.
+          # @param api [Kitchen::Driver::Oci::Api] an authenticated API class.
+          # @return [Class] the instantiated model class.
+          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
+
+          # Instantiates a blockstorage volume model.
+          #
+          # @param type [String] The type of volume that will be created.
+          # @param state [Hash] (see Kitchen::StateFile)
+          # @param oci [Kitchen::Driver::Oci::Config] a populated OCI config class.
+          # @param api [Kitchen::Driver::Oci::Api] an authenticated API class.
+          # @return [Class] the instantiated model class.
+          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
+
+          # Returns the class name of the attachment type.
+          #
+          # @param type [String, nil]
+          # @return [String]
+          def volume_attachment_type(type)
+            if type.nil?
+              "Paravirtual"
+            else
+              type.capitalize
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/kitchen/driver/oci/mixin/volumes.rb

@@ -0,0 +1,88 @@
+# 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
+      module Mixin
+        # Mixins for working with volumes and attachments.
+        #
+        # @author Justin Steele <justin.steele@oracle.com>
+        module Volumes
+          # Create and attach volumes.
+          #
+          # @param config [Kitchen::LazyHash] The config provided by the driver.
+          # @param state [Hash] (see Kitchen::StateFile)
+          # @param oci [Kitchen::Driver::Oci::Config] a populated OCI config class.
+          # @param api [Kitchen::Driver::Oci::Api] an authenticated API class.
+          def create_and_attach_volumes(config, state, oci, api)
+            return if config[:volumes].empty?
+
+            volume_state = process_volumes(config, state, oci, api)
+            state.merge!(volume_state)
+          end
+
+          # Detatch and delete volumes.
+          #
+          # @param state [Hash] (see Kitchen::StateFile)
+          # @param oci [Kitchen::Driver::Oci::Config] a populated OCI config class.
+          # @param api [Kitchen::Driver::Oci::Api] an authenticated API class.
+          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
+
+          # Process volumes specified in the kitchen config.
+          #
+          # @param config [Kitchen::LazyHash] The config provided by the driver.
+          # @param state [Hash] (see Kitchen::StateFile)
+          # @param oci [Kitchen::Driver::Oci::Config] a populated OCI config class.
+          # @param api [Kitchen::Driver::Oci::Api] an authenticated API class.
+          # @return [Hash] the finalized state after the volume(s) have been created and attached.
+          def process_volumes(config, state, oci, api)
+            volume_state = { volumes: [], volume_attachments: [] }
+            config[:volumes].each do |volume|
+              vol = volume_class(volume[:type], config, state, oci, api)
+              volume_details, vol_state = create_volume(vol, volume)
+              attach_state = vol.attach_volume(volume_details, state[:server_id], volume)
+              volume_state[:volumes] << vol_state
+              volume_state[:volume_attachments] << attach_state
+            end
+            volume_state
+          end
+
+          # Creates or clones the volume.
+          #
+          # @param vol [OCI::Core::Models::Volume] the volume that has been created.
+          # @param volume [Hash] the state of the current volume being cloned.
+          def create_volume(vol, volume)
+            if volume.key?(:volume_id)
+              vol.create_clone_volume(volume)
+            else
+              vol.create_volume(volume)
+            end
+          end
+        end
+      end
+    end
+  end
+end