search

waveclaw / puppet-subscription_manager

Handle Client Registration to RedHat Satellite 6 or Katello
https://rhn.redhat.com
Other
6 stars 34 forks source link
centos katello linux puppet redhat rspec ruby satellite6

readme

Puppet-Subscription_manager

Build Status Code Climate Test Coverage

This module provides Custom Puppet Provider to handle registration and consumption of RedHat subscriptions using subscription-manager as part of Katello or RedHat Satellite 6.

This module can be used with RedHat Subscription Access Manager (SAM) but is not primarily designed to inter-operate with SAM separate from a Katello or Satellite service.

You cannot use this module to switch between SAM and other products or to SAM from a different product because of the changes in the internal name for the CA certificates.

This module is a fork of the puppet-subscription_manager module by James Laska that was in turn derived from puppet-rhnreg_ks module by Gaël Chamoulaud. This fork provides an incompatible dedicated rhsm_config resource and separates repository management from control of the Yum overrides.

Notices

RHN

This module is not for direct use with RedHat Network. For that, either use the provided resource types directly or see the Ansible playbooks available directly from RedHat. If you really want to talk to RHN directly, see the subscription_manager::ca_package parameter for how.

Services

Since Satellite version 6.5, the goferd package has been deprecated. It is not available in current version of satellite. To use this module beyond version 5.6 with a older Satellite installation, you may want to include the service in your own Puppet code. An example is provided for the rhsmcertd case bellow.

In Satellite 6.5.x and later, the remote command execution replaces this feature. This uses the ssh service as the remove agent and does require configuration of both the user and ssh configuration. This is a topic well discussed elsewhere.

Terminology

Due to various terminology differences between RHN Satellite, the upstream Katello project and the further upstream component projects of Candlepin, The Foreman, Puppet and Dogtag the names of properties and resources may be confusing.

License

Apache License, Version 2.0. Read the LICENSE file for details of the licensing.

Requirements

Authors

See CONTRIBUTORS.

Classes and Defines

This module provides the standard install-config-service pattern. It also wraps the provided native resources with a convenience class to enable simple or complex deployment.

It is expected that any users not making use of default top-level import of the module will be interested in the native types for customization.

Facts

Some custom facts are provided.

A family of facts, similar to the rhsm_repo type, summarize the subscription state. These can return lists of data under facter 2.0.

The repo facts make use of a simple caching mechanism using the facts.d directory to limit connections to the Katello or Satellite server. Like the katello-agent these only pull data once a day.

The once-per day schedule is currently a hard-coded value. However the cache can be invalidated by finding and removing the cache files.

The cache files should appear as normal YAML format external fact files. These facts may actually linger on after removing the rhsm module itself. Beware that the location of external fact files is different between Puppet and facter for older versions of Puppet like 2 or 3 and facter 1.x.

The certificate authority is part of the rhsm_config type but is very useful for operations in involving subscription management. This differs slightly between Katelo, RedHat Satellte and RedHat SAM.

Of course, a fact exists about the identity of the client as known locally.

Examples

Setup to and register one CentOS 6 client to a Katello server using a public repository to obtain the agent.

# (Optionally) Place this code in a .pp file some where on your Puppet's modulepath
# such as a file named subscription_manager.pp in a module named repo.
# The autoloader will be triggered by the rhsm module to search for this class.
class repo::subscription_manager {
  yumrepo { 'dgoodwin-subscription-manager':
  ensure              => 'present',
  baseurl             => 'https://copr-be.cloud.fedoraproject.org/results/dgoodwin/subscription-manager/epel-6-$basearch/',
  descr               => 'Copr repo for subscription-manager owned by dgoodwin',
  enabled             => '1',
  gpgcheck            => '1',
  gpgkey              =>  'https://copr-be.cloud.fedoraproject.org/results/dgoodwin/subscription-manager/pubkey.gpg',
    skip_if_unavailable => 'True',
  }
}

# Place this this in either a raw .pp manifest, a profile-like module or
# classify the node to require subscription_manager with these parameters in
# your ENC.
# Notice the explict call for the optional package repository to include.
class { 'subscription_manager':
    repo            => 'repo::subscription_manager',
    server_hostname => 'my_katello.example.com',
    activationkey   => '1-2-3-example.com-key',
    force           => true,
    org             => 'My_Example_Org',
  }
}

Register a RedHat Enterprise 7 or CentOS 7 node to the RedHat Network with Satellite 6 using a password and username.

Note that you have to stop managing the ca\_package as you get that from RedHat as part of the OS installation.

class { 'subscription_manager':
   org           => 'My_Company_Org_in_RHN',
   username      => 'some_rhn_special_user',
   password      => 'password123',
   autosubscribe => true,
   servicelevel  => 'STANDARD',
   ca_package    => false,
}

Putting the explicit password in the code is a *bad* idea. Using hiera-gpg or
hiera-eyaml back-ends is strongly encouraged for this example.

Register a RedHat Enterprise 7 or CentOS 7 node to Satellite 6 using an activation key.

  class { 'subscription_manager':
     server_hostname => 'satellite.example.com',
     org             => 'My_Company_Org',
     activationkey   => '1234-key',
     autosubscribe   => true,
     servicelevel    => 'STANDARD',
     config_hash     => {
       server_prefix          => '/rhsm',
       rhsm_baseurl           => "https://satellite.example.com/pulp/repos",
       rhsm_repo_ca_cert      => '%(ca_cert_dir)s/katello-server-ca.pem',
     },
     service_name    =>'rhsmcertd',
     force           => true,
  }

Notice that the rhsm_repo_ca_cert must change to match the certificate provided by the katello-ca-consumer package on the Satellite server. This can be contained in the files searched by the rhsm_ca_cert fact. These are SSL certificates which do not take into account Subject Alternative Names. Only the primary name in the certificate is used to check if the client is registered to the correct server.

Register to a local RedHat SAM server. Note that rhsmcertd and goferd are optional. You will have to perform the serivice management at the top level of your puppet code.

  class { 'subscription_manager':
     server_hostname   => 'sam.example.com',
     org               => 'My_Company_Org',
     activationkey     => '1234-key',
     ca_package_prefix => 'candlepin-cert-consumer-', # note the trailing hypen
     autosubscribe     => true,
     servicelevel      => 'PREMIUM',
     config_hash       => {
       rhsm_repo_ca_cert      => '/etc/rhsm/ca/candlepin-local.pem',
     },
     service_name      =>'rhsmcertd',
     force             => true,
  } ~> Service ['rhsmcertd']

For this example one can see that the config_hash only needs customized entries so there is no need to provide every default.

Types and Providers

The module adds the following new types:

rhsm_register

Parameters

Mandatory

Either an activation key or a username and password combination is needed to register. Both cannot be provided and will cause an error.

Optional

rhsm_register Examples

Register clients to RedHat Subscription Management using an activation key:

rhsm_register { 'satellite.example.com':
  server_hostname => 'satellite.example.com',
  activationkey   => '1-myactivationkey',
}

Register clients to RedHat Subscription management using a username and password:

rhsm_register { 'subscription.rhn.example.com':
  username        => 'myusername',
  password        => 'mypassword',
  autosubscribe   => true,
  force           => true,
}

Register clients to RedHat Subscription management and attach to a specific license pool:

rhsm_register { 'subscription.rhn.example.com':
  username  => 'myusername',
  password  => 'mypassword',
  pool      => 'mypoolid',
}

rhsm_config

Please see man(5) RHSM.CONF for your locally supported options. There are quite a few and they require specific inputs.

rhsm_config cannot set values that are not available from the subscription-manager config sub-command.

For the rhsm.conf options that are not supported directly, it is recommended to use either the puppetlabs-stdlib file_line or one of the many forge.puppet.com modules for managing ini-format files.

rhsm_config options

See the documentation at RedHat Support for RedHat provided details on the /etc/rhsm/rhsm.conf file.

The most important settings are as follows. Specific support is made for them.

rhsmcertd is not the same as Katello's goferd.

Other options can be rolled into a configuration hash and fed to the module as a whole. See init.pp and the following YAML example for details.

Do know the supported options to the specific version of subscription-manager config --help on your platform.

Options that are not supported will be ignored!

rhsm_config Examples

As a resource, the format of [section] and section.key is transformed into the puppet language compatible section_key.

rhsm_config { 'katello.example.com':
    server_hostname              => 'katello.example.com',
    server_insecure              => false,
    server_port                  => 443,
    server_prefix                => '/rhsm',
    server_ssl_verify_depth      => 3,
    rhsm_baseurl                 => 'https://katello.example.com/pulp/repos',
    rhsm_ca_cert_dir             => '/etc/rhsm/ca/',
    rhsm_consumercertdir         => '/etc/pki/consumer',
    rhsm_entitlementcertdir      => '/etc/pki/entitlement',
    rhsm_full_refresh_on_yum     => true,
    rhsm_manage_repos            => true,
    rhsm_pluginconfdir           => '/etc/rhsm/pluginconf_d',
    rhsm_plugindir               => '/usr/share/rhsm-plugins',
    rhsm_productcertdir          => '/etc/pki/product',
    rhsm_repo_ca_cert            => '/etc/rhsm/ca/katello-server-ca.pem',
    rhsm_report_package_profile  => 1,
    rhsmcertd_autoattachinterval => 1440,
    server_proxy_hostname        => 'proxy.example.com',
    server_proxy_user            => 'proxy_user',
    server_proxy_password        => 'proxy_password',
    server_proxy_port            => 4443,    
}

As a hiera data source.

---
subscription_manager::config_hash:
 server_hostname: 'katello.example.com'
 server_insecure:  false
 server_prefix:  '/rhsm'
 server_port:  443
 server_ssl_verify_depth:  3
 rhsm_baseurl:  'https://katello.example.com/pulp/repos'
 rhsm_ca_cert_dir:  '/etc/rhsm/ca'
 rhsm_repo_ca_cert:  '%(ca_cert_dir)s/katello-server-ca.pem'
 rhsm_productcertdir:  '/etc/pki/product'
 rhsm_entitlementcertdir:  '/etc/pki/entitlement'
 rhsm_consumercertdir:  '/etc/pki/consumer'
 rhsm_manage_repos:  true
 rhsmcertd_certcheckinterval:  240
 rhsmcertd_autoattachinterval:  1440

Users should only need to provide the settings in config_hash that differ from any of the defaults which are used in the module.

If you are using the resource you will have to provide everything you want to set.

Note: un-setting a required default by providing a blank option will make the subscription stop working.

The default_log_level and basic module_name logging settings are available. None of the sub-modules are available. A suggestion for those would be to ship customized file-line resources to not conflict with changes created through the subscription-manager command.

rhsm_repo

rhsm_repo Parameters

If absolutely necessary the individual yum repositories can be filtered.

This cannot add new repositories, only filter existing subscribed repositories. If you require more repositories, edit your Content View(s) or Pool(s). Or just use the yumrepo native type that ships with Puppet.

rhsm_repo Examples

Example of a repository from the Server

rhsm_repo { 'rhel-6-server-java-rpms':
  ensure        => present, # equal to the enabled property
  url           => 'https://katello.example.com/pulp/repos/abc-corp/production/reg-key-1/content/dist/rhel/server/6/6Server/$basearch/java-repo/os',
  content_label => 'rhel-6-java-rpms',
  id            => 'rhel-6-java-rpms',
  name          => 'RedHat Enterprise Linux 6 Server - Java (RPMs)',
  repo_type     => channel,
}

rhsm_override

rhsm_override Example

This is returned by the Puppet resource command but it not manageable in a meaningful way through the type.

rhsm_repo { 'rhel-server6-epel':
  ensure        => present, # equal to the enabled property
  updated       => 2015-07-17T14:26:35.064+0000,
  created       => 2015-07-17T14:26:35.064+0000,
  content_label => 'rhel-server6-epel'
  repo_type     => override,
}

rhsm_pool

Subscriptions to use RHN are sold as either individual entitlements or a pools of entitlements. A given server registered to a Satellite 6 or Katello system will consume at least 1 entitlement from a Pool.

This subscription to the Pool is what enables the set of repositories to be made available on the server for further subscription.

While this type is mostly useful for exporting the registration information in detail it can also be used to force switch registrations for selected clients.

rhsm_pool Parameters

rhsm_pool Example

rhsm_pool { '1a2b3c4d5e6f1234567890abcdef12345':
  subscription_name => 'Extra Packages for Enterprise Linux',
  ensure            => present,
  provides          => 'EPEL',
  sku               => 1234536789012,
  contract          => 'Fancy Widgets, LTD',
  account           => '1234-12-3456-0001',
  serial            => 1234567890123456789,
  id                => 1a2b3c4d5e6f1234567890abcdef12345,
  active            => true,
  quantity_used     => 1,
  service_level     => 'STANDARD',
  service_type      => 'EOL',
  status_details    => 'expired',
  subscription_type => 'permanent',
  starts            => 06/01/2015,
  ends              => 05/24/2045,
  system_type       => physical,
}

Note of caution:

Installing

Release Version

For released version the module can be installed with the Puppet module tool from the Puppet Forge. Or even added as a Puppetfile source with Puppet Enterprise or r10k or Puppet Librarian.

  puppet module install waveclaw-subscription_manager

This will install waveclaw-facter_cacheable and puppetlabs-transition as dependencies.

Note that facter_cacheable, while optional, is highly recommended to reduce load on your Foreman or Katello server.

Development Version

For pre-release code the GitHub repository can be cloned.

In your puppet modules directory:

For the original module:

    git clone https://github.com/jlaska/puppet-subscription_manager.git

For this module:

    git clone https://github.com/waveclaw/puppet-subscription_manager.git

Ensure the module is present in your puppetmaster's own environment. The Puppet Master node doesn't have to use the module or Satellite itself. Ensure that the target node to register has pluginsync enabled. Run the agent on the target node to cause the custom types to be synced to the local libdir (puppet master --configprint libdir).

If you use the Puppet Development Kit, this module is PDK compatible.

Deprication Warnings

Support for Ruby 1.8.7 and older is ad-hoc at best. Modern rake and json_pure require newer releases.

The caching functions were pushed to a difference module on the forge, waveclaw-facter_cachable. Some of the tests do not run properly under Travis CI. These are commended out in the code but can be run locally.

Acceptance Tests

Acceptance tests require a working katello system, RedHat Satellite server or just a repo of pre-built dependent packages.

Customization of the spec/spec_acceptance_helper.rb and specific tests is needed to point the full tests at working servers. Otherwise some of the tests must fail.

Issues

Please file any issues or suggestions on on GitHub

Guidelines

Please follow the example42 development guidelines.

Pull requests and bug reports via GitHub are welcomed.

For Pull Requests please:

For a bug report please include or link:

None of this guarantees a solution. At the least a good bug report can warn others.