Add the puppet module/type/provider/device

MANIFEST.in

@@ -9,6 +9,7 @@ include examples/elasticsearch/servers.py.example
 include examples/elasticsearch/kibana-dashboard.json
 include examples/firmwareupdater/hpilo_firmware_update
 include examples/ca/hpilo_ca
+recursive-include examples/puppet *.rb *.pp *.erb
 include ilo.conf.example
 include COPYING
 include CHANGES

docs/index.rst

@@ -106,6 +106,7 @@ dependencies.
    ca
    elasticsearch
    autofirmware
+   puppet
 
 Development information
 =======================

docs/puppet.rst

@@ -0,0 +1,287 @@
+Managing iLO's with puppet
+==========================
+
+Instead of writing your own code to manage iLO interfaces with python-hpilo,
+you can also use a puppet module. While it doesn't support all the
+functionality of hpilo.py or hpilo_cli, it does support the more common
+functions (and more can be added, just file a bug!)
+
+It uses the same network device management framework as the existing tools to
+manage cisco devices or F5 loadbalancers, so you don't need to install anything
+special on each server and no custom iLO code is required.
+
+To install the module, simply copy the `modules/ilo` directory into your puppet
+tree and follow the instructions below to create recipes.
+
+Caching
+-------
+This module heavily caches iLO output, most for more than a day. The cache is
+invalidated if settings etc. are changed by this module, but if you make
+changes manually, you will need to remove the cached information yourself. The
+cache lives in the per-device directories in `/var/lib/puppet/devices`.
+
+Because of this caching, applying the catalog takes only a few seconds instead
+of several minutes if there are no changes.
+
+Configuring puppet
+------------------
+Please configure `hpilo_cli` itself first, including username and password. The
+puppet `ilo` module works by using this tool. Once it works for you, you can
+configure puppet.
+
+To use `puppet device` to manage iLO's, the iLO devices must be added to
+`/etc/puppet/device.conf` on the server you want to use for managing them.
+
+The ilo module can be used in two ways: to manage an iLO remotely via HTTP and
+to manage an iLO locally via hpilo. With the former you can manage many iLOs
+from a single server, with the latter you can manage iLOs that are not (yet)
+reachable via the network.
+
+To manage the local iLO, you can put something this in `device.conf`::
+
+    [server-001.ilo.kaarsemaker.net]
+    type ilo
+    url ilo://server-001.ilo.kaarsemaker.net
+
+Note that the scheme is `ilo://`, this makes the ilo module use `hpilo_cli` in
+local mode. You must still use the ilo's FQDN though, as each node needs a
+unique name in puppet.
+
+I personally prefer the network method and configuring DHCP properly so all
+iLOs are reachable via the network. For this, `device.conf` looks like the
+following::
+
+    [server-001.ilo.kaarsemaker.net]
+    type ilo
+    url http://server-001.ilo.kaarsemaker.net
+
+    [server-002.ilo.kaarsemaker.net]
+    type ilo
+    url http://server-002.ilo.kaarsemaker.net
+
+    [server-003.ilo.kaarsemaker.net]
+    type ilo
+    url http://server-003.ilo.kaarsemaker.net
+
+In fact, it's generated by the iLO module. The management server has this
+snippet in its recipe:
+
+.. code-block:: puppet
+
+    class s_mgmt {
+        class{'ilo::proxy':
+            devices => [
+                "http://server-001.ilo.kaarsemaker.net",
+                "http://server-002.ilo.kaarsemaker.net",
+                "http://server-003.ilo.kaarsemaker.net",
+            ]
+        }
+    }
+
+Of course you can generate this however you want.
+
+Facts
+-----
+Several facts are available for use in your recipes.
+
+* `$devicetype` is set to `ilo`
+* `$users` contains a list of all users
+* `$firmware_version`, `$firmware_date`, `$management_processor`, and
+  `$license_type` are set to what `get_fw_version` provides
+* `$oa_encl`, `$oa_rack`, `$oa_ipaddress`, `$oa_location`, `$oa_macaddress`,
+  `$oa_uidstatus` and `$oa_system_health` are set to what `get_oa_info`
+  provides. These are only available on blade servers.
+
+Managing users
+--------------
+You can use this module to create, modify and delete users. Unfortunately the
+normal `user` type cannot be used, so there's a special `ilo_user` type.
+
+.. code-block:: puppet
+
+    ilo_user {
+        "Administrator":
+            admin_priv => true;
+        "jack":
+            ensure => absent;
+        "dkaarsemaker":
+            ensure => present,
+            display_name => 'Dennis Kaarsemaker',
+            password_atcreate => 'P4ssw0rd',
+            reset_server_priv => false;
+        "linda":
+            ensure => present,
+            password => 'hunter2'
+            display_name => 'Linda',
+            admin_priv => false,
+            config_ilo_priv => false,
+            reset_server_priv => true;
+    }
+
+These example users show the features of this type:
+
+* You can create (`ensure => present`) or delete (`ensure => absent`) users.
+* You can manage their permissions (`admin_priv`, `config_ilo_priv`,
+  `remote_cons_priv`, `reset_server_priv` and `virtual_media_priv`)
+* You can manage display names and passwords. Note that for users you want this
+  module to create, these are mandatory attributes.
+
+Because user passwords cannot be queried, this module has to check the password
+every time by doing an http request. This can take a while and goes against the
+aggressive caching. To prevent these constant checks, you can use the
+`password_atcreate` parameter instead of the `password` parameter. This is only
+used when creating the user and is not checked subsequently. Should you want to
+change the user's password you can temporarily also add a `password` parameter
+until all devices have been updated.
+
+Managing iLO firmware
+---------------------
+The `ilo_firmware` type can be used to manage firmware on your iLOs.
+
+.. code-block:: puppet
+
+    ilo_firmware { $management_processor:
+        ensure => "latest",
+        http_proxy => "http://webproxy:3128"
+    }
+
+The name of the resource must be the same as the iLO type, you can use a fact
+to make sure it is. `ensure` accepts any version number or the string `latest`,
+which will always upgrade to the latest version.
+
+`http_proxy` is optional and can be used to specify a proxy via which to
+download the firmware config and firmware.
+
+Managing settings
+-----------------
+This module also includes an `ilo_settings` type. This is a relatively thin
+wrapper around functions like `mod_global_settings` to configure any of the
+following settings: global (`mod_global_settings`), network
+(`mod_network_settings`), snmp (`mod_snmp_im_settings`) and directory
+authentication (`mod_dir_config`). As with the above types, an example should
+make it clear.
+
+.. code-block:: puppet
+
+    ilo_settings {
+        "global":
+            settings => {
+                "remote_console_port" => 23,
+                "enforce_aes"         => true,
+                "f8_login_required"   => true,
+            };
+        "network":
+            settings => {
+                "prim_dns_server"     => "10.42.1.31",
+                "sec_dns_server"      => "10.42.1.32",
+            };
+    }
+
+As you can see, the individual settings are not all parameters, instead there's
+only one settings parameter. Any setting that is not managed by puppet is
+completely left alone by this module, there are no defaults.
+
+Installing licenses
+-------------------
+The last functionality (for now) is the `ilo_license` type, which you can use
+to install licenses.
+
+.. code-block:: puppet
+
+    ilo_license { "iLO 3 Advanced":
+        key => "12345-67890-ABCDE-FGHIJ-KLMNO"
+    }
+
+Note that the spelling of the license name is important. If it's not exactly
+the same as what `get_all_licenses` shows, puppet will try to activate the
+license again and again.
+
+Complete example
+----------------
+And here's a complete example to put all the above together.
+
+`/etc/puppet/device.conf`::
+
+    [server-001.ilo.kaarsemaker.net]
+    type ilo
+    url http://server-001.ilo.kaarsemaker.net
+
+`/etc/puppet/manifests/nodes.pp`
+
+.. code-block:: puppet
+
+    node 'management-server.kaarsemaker.net' {
+        include s_mgmt
+    }
+
+    node 'server-001.ilo.kaarsemaker.net' {
+        include s_ilo
+    }
+
+    node 'server-002.ilo.kaarsemaker.net' {
+        include s_ilo
+    }
+
+    node 'server-003.ilo.kaarsemaker.net' {
+        include s_ilo
+    }
+
+`/etc/puppet/modules/s_mgmt/manifests/init.pp`
+
+.. code-block:: puppet
+
+    class s_mgmt {
+        class{'ilo::proxy':
+            devices => [
+                "http://server-001.ilo.kaarsemaker.net",
+                "http://server-002.ilo.kaarsemaker.net",
+                "http://server-003.ilo.kaarsemaker.net",
+            ]
+        }
+    }
+
+`/etc/puppet/modules/s_ilo/manifests/init.pp`
+
+.. code-block:: puppet
+
+    class s_ilo {
+
+        # Always upgrade firmware
+        ilo_firmware { $management_processor:
+            ensure => "latest",
+            http_proxy => "http://webproxy:3128"
+        }
+
+        # We only have iLO 3's in this setup, so one license will do
+        ilo_license { "iLO 3 Advanced":
+            key => "12345-67890-ABCDE-FGHIJ-KLMNO"
+        }
+
+        ilo_settings {
+            "global":
+                settings => {
+                    "remote_console_port" => 23,
+                    "enforce_aes"         => true,
+                    "f8_login_required"   => true,
+                };
+            "network":
+                settings => {
+                    "prim_dns_server"     => "10.42.1.31",
+                    "sec_dns_server"      => "10.42.1.32",
+                };
+        }
+
+        ilo_user {
+            "Administrator":
+                # Temporary until changed everywhere
+                password => 'P4ssw0rd',
+            "dennis":
+                ensure => present,
+                display_name => 'Dennis Kaarsemaker',
+                password_atcreate => 'MyPass!',
+                reset_server_priv => false;
+            # Remove leavers
+            ["jack", "bob"]:
+                ensure => absent,
+        }
+    }

examples/puppet/modules/ilo/lib/puppet/provider/ilo.rb

@@ -0,0 +1,20 @@
+require 'puppet/util/network_device/ilo/device'
+require 'puppet/provider/network_device'
+
+class Puppet::Provider::Ilo < Puppet::Provider::NetworkDevice
+    attr_writer :device
+
+    def self.device(url)
+        @device = Puppet::Util::NetworkDevice::Ilo::Device.new(url)
+        @device
+    end
+
+    def self.mkcommands
+        @commands ||= {}
+        commands :python => "python", :hpilo_cli => "hpilo_cli";
+    end
+
+    def mkcommands
+        self.class.mkcommands
+    end
+end

examples/puppet/modules/ilo/lib/puppet/provider/ilo_firmware/ilo_firmware.rb

@@ -0,0 +1,42 @@
+require 'puppet/provider/ilo'
+
+Puppet::Type.type(:ilo_firmware).provide(:ilo_firmware, :parent => Puppet::Provider::Ilo) do
+    @doc = "Manages iLO firmware"
+
+    def firmware_version() @property_hash[:firmware_version] end
+
+    def self.lookup(device, id)
+        version = device.transport.get('get_fw_version')
+        {
+            :name                 => version['management_processor'],
+            :management_processor => version['management_processor'],
+            :firmware_version     => version['firmware_version'],
+            :firmware_date        => version['firmware_date']
+        }
+    end
+
+    def fw_config
+        old_https_proxy = ENV['https_proxy']
+        old_http_proxy = ENV['http_proxy']
+        begin
+            ENV['http_proxy'] = ENV['https_proxy'] = resource[:http_proxy]
+            device.transport.fw_config
+        ensure
+            ENV['https_proxy'] = old_https_proxy
+            ENV['http_proxy'] = old_http_proxy
+        end
+
+    end
+
+    def install
+        Puppet::debug("Installing firmware version #{@resource[:ensure]}")
+        old_https_proxy = ENV['https_proxy']
+        old_http_proxy = ENV['http_proxy']
+        begin
+            device.transport.call('update_rib_firmware', "version=#{@resource[:ensure]}")
+        ensure
+            ENV['https_proxy'] = old_https_proxy
+            ENV['http_proxy'] = old_http_proxy
+        end
+    end
+end

examples/puppet/modules/ilo/lib/puppet/provider/ilo_license/ilo_license.rb

@@ -0,0 +1,24 @@
+require 'puppet/provider/ilo'
+
+Puppet::Type.type(:ilo_license).provide(:ilo_license, :parent => Puppet::Provider::Ilo) do
+    @doc = "Manages iLO settings"
+
+    mk_resource_methods
+
+    def self.lookup(device, id)
+        instance = nil
+        device.transport.get('get_all_licenses').each do |license|
+            if license['license_type'] == id
+                instance = {
+                    :name => license['license_type'],
+                    :key  => license['license_key'],
+                }
+            end
+        end
+        instance
+    end
+
+    def flush
+        device.transport.call('activate_license', "key=#{properties[:key]}")
+    end
+end