Using Oracle Database for Puppet Stored Configuration

Puppet is an open source data center automation and configuration management framework. Puppet provides system administrators with a simplified platform that allows for consistent, transparent, and flexible systems management. Puppet lets System Administrators spend less time on mundane tasks and instead focus on managing their infrastructure strategically.

Last year I had the privilege of attending the first annual Puppet Camp in San Francisco. At the time, I was starting to play with Puppet's stored configuration functionality and was disappointed to find it didn't support storage in Oracle. So, I resolved to resolve that issue by writing Oracle support into Puppet. I'm pleased to report that the current version of Puppet (2.6) now supports Oracle as a storage option.

Oracle support would not have been possible without the amazing work of Raimonds Simanovskis and the rest of the team responsible for the activerecord-oracle_enhanced-adapter. Also, a huge thank you to Christopher Jones at Oracle for helping to debug a CLOB-related bug in the adapter and helping to get it fixed.

This blog post describes the process of configuring your Puppet Master to enable stored configuration in Oracle.

Pre-requisites

Installing Oracle Instant Client

The Oracle Instant Client is a streamlined set of client libraries for connecting to an Oracle database. You only need to install the Instant Client on a server that is not already running Oracle Database. If you're using Oracle Enterprise Linux, the Instant Client packages can be found by subscribing to the el5_oracle channel in Unbreakable Linux Network. To install via ULN, run:

# up2date -i oracle-instantclient11.2-basic oracle-instantclient11.2-devel

Otherwise, you can install the Instant Client by downloading the Instant Client Package - Basic and Instant Client Package - SDK packages from the Oracle Technology Network.

Once you have installed the Instant Client, you need to ensure that the LD_LIBRARY_PATH environment variable includes the path to your Oracle Instant Client libraries. On Enterprise Linux, this can be achieved by creating an /etc/ld.so.conf.d/instantclient-11.2-x86_64.conf with the following line:

/usr/lib/oracle/11.2/client64/lib/

Then, recreate ld.so.cache by running the following command:

# ldconfig -v

If you are not running Enterprise Linux, you will need to ensure that the LD_LIBRARY_PATH environment variable for all users includes the Oracle Instant Client libraries otherwise the next steps will not complete successfully.

Installing ruby_oci8

Download ruby-oci8-2.0.4.tar.gz from Rubyforge. Scroll down to find the 2.0.4 packages.

In order to successfully compile ruby_oci8, ensure you have the Ruby development package (ruby-devel RPM) installed, as well as the entire "Development Tools" group.

# tar zxvf ruby-oci8-2.0.4.tar.gz
# cd ruby-oci8-2.0.4
# make
# make install

Installing Puppet-required Gems

There are great instructions on the Puppet Wiki on how to enable Stored Configurations. The only step we have to follow for this process is to ensure that the Rails gem is installed:

# gem install rails

(Installs rake, activesupport, activerecord, rack, actionpack, actionmailer, activeresource, rails)

Installing ActiveRecord-oracle_enhanced

Once Rails is installed, we need to install the Oracle Enhanced adapter for ActiveRecord. This uses the ruby_oci8 software we installed before to connect to our Oracle database.

# gem install activerecord-oracle_enhanced-adapte

Configuration

Installing Oracle Express Edition and Creating the Oracle user

In most organisations, an Oracle DBA is responsible for day-to-day management and maintenance of Oracle databases. If your organisation
has an existing Oracle database footprint and DBA, you should ask the DBA to create an appropriate Puppet schema for you on an existing
Oracle database and provide you with the hostname, service name, username and password for that schema. Once you have these details, you can skip directly to the "Configuring Stored Configuration" section a little lower down.

If you are just starting out with Oracle or want to play with it for development purposes, I recommend downloading a copy of Oracle Database 10g Release 2 Express Edition. Oracle Database 10g Express Edition (Oracle Database XE) is an entry-level, small-footprint database based on the Oracle Database 10g Release 2 code base that's free to develop, deploy, and distribute; fast to download; and simple to administer.

In this example, I've downloaded the RPM installer for Oracle Database XE and installed it onto my Puppet Master using the yum tool:

# yum localinstall --nogpgcheck oracle-xe-10.2.0.1-1.0.i386.rpm

Using yum ensures that any dependencies required by Oracle XE are automatically installed at the same time.

Once Oracle XE has been installed, you must run /etc/init.d/oracle-xe configure as the root user to configure the database:

# /etc/init.d/oracle-xe configure

I recommend accepting the default settings, i.e. port 8080 for Oracle Application Express and port 1521 for the database listener. You
are also prompted for a password for the built-in SYS and SYSTEM database accounts. Finally, you are asked if Oracle XE should be started on boot. Once the configuration process is completed, Oracle XE will have been configured and started automatically. The web-based administration tool has also been started, but by default it is only accessible from the local machine. In order to allow access to APEX from a remote workstation, the following process is required:

First, change to the Oracle user:

# su - oracle

Next, use the provided oracle_env.sh script to ensure all the appropriate environment variables are initialized:

$ . /usr/lib/oracle/xe/app/oracle/product/10.2.0/server/bin/oracle_env.sh

Tip: add this to .bashrc or .bash_profile for the oracle user to set these variables automatically.

Start SQL*Plus and log in as SYSTEM:

$ sqlplus system

Enter password: SYSTEM_password

At the SQL prompt, enter the following command:

SQL> EXEC DBMS_XDB.SETLISTENERLOCALACCESS(FALSE);

Once this is complete, you should be able to open http://servername:8080/apex in a browser and login as the SYS user using the password you provided during the configuration step. If you are unable to connect, check to see if iptables is running on your server and ensure that port 8080 is open.

You can use SQL*Plus to create a user for puppet using the following commands:

CREATE  USER "PUPPET"  PROFILE "DEFAULT"  IDENTIFIED BY "password" DEFAULT TABLESPACE "PUPPET" TEMPORARY TABLESPACE "TEMP" ACCOUNT UNLOCK
GRANT "CONNECT" TO "PUPPET"
GRANT "RESOURCE" TO "PUPPET"

Alternatively, once you have logged into the web interface, you will see the following screen:

Click the down arrow on the "Administration" button and navigate the menu to create a new user by going to "Databae Users", "Create User":

On the User Creation screen, enter a username of "PUPPET" and provide a password. Ensure that the "CONNECT" and "RESOURCE" roles are
checked:

Once the user has been created successfully, you should receive the following screen, which shows the newly created "PUPPET" user:

Once you have successfully created the PUPPET user, you are ready to configure Puppet itself.

Enabling Stored Configuration in Puppet

Finally, we need to configure Puppet to enable storeconfigs. Edit /etc/puppet/puppet.conf and add the following settings:

[master]
storeconfigs = true
dbadapter = oracle_enhanced
dbname = //localhost/XE
dbuser = PUPPET
dbpassword = Password

These settings tell Puppet to enable storeconfigs and provides the appropriate configuration to connect to Oracle. The dbname parameter uses the Oracle Instant Client Connection Strings format. In this example, I'm using a SQL Connect URL string. Once you have changed the configuration, you need to restart your Puppet Master. The next time a Puppet client connects to your Puppet Master, it should create the appropriate tables in your Oracle Database and start storing configuration data. A good way to troubleshoot any issues is to run the Puppet Master in the foreground with verbose logging:

# puppet master --no-daemonize --verbose

You will then be able to see any errors that are generated when the client connects to the master.

Using Stored Configurations

Now that you have stored configurations working, head over to the Puppet Wiki to learn more about exporting and collecting resources.