puppet-couchdb

A Puppet module for deploying Couchbase Server and managing its buckets.

####Table of Contents

1. Prerequisites
2. Module Function
3. Usage
   • Examples
4. Testing
5. Reference
   • ::Couchbase
   • ::Couchbase::Bucket
   • ::Couchbase::CLI
   • ::Couchbase::StateFile
6. Limitations
7. Development
   • Known Bugs!
   • TODO

Requires

• puppetlabs/stdlib
• maestrodev/wget

Function

This module will install Couchbase, create or join a cluster and manage buckets.

Custom commands can be sent to the couchbase-cli[.exe] binary via the Couchbase::Cli resource. This is useful for handling items such as cluster settings for which there is not yet a specific class or defined type.

Usage

Define your buckets as a hash (can use Hiera) and pass them to the Couchbase class.

• Define buckets in Hiera like this:

couchbase::cluster_ramsize: 512
couchbase::buckets:
  default:
    # Remove the default bucket if present.
    #  (Newer Couchbase releases do not create a default bucket during install.)
    present: false
  prod:
    # Create bucket named 'prod', disable flush, RAM size 123MB, with password.
    present: true
    ramsize: 123
    flush: 0
    password: hunter2
  dev:
    # Create bucket named 'dev', no password, flush enabled, 100MB RAM size.
    ramsize: 100
    flush: 1
  test:
    # Create bucket named 'test', bucket type is memcached, use defaults for everything else.
    type: memcached
  legacy:
    # Remove bucket 'legacy' if it exists.
    present: false

• Or define buckets with a hash like this:

class our_profiles::my_example_profile {
  class { '::couchbase':
    cluster_ramsize  => 512,
    buckets => {
      'legacy' => { present => false },
      'prod'   => {
        ramsize  => 123,
        flush    => 0,
        password => 'hunter2',
      }
    }
  }
}

Examples for sending API calls via the Couchbase CLI:

• This will run couchbase-cli foo-bar --thing=qaz

$thing='qaz'
couchbase::cli {'do a thing':
  action      => 'foo-bar',
  parameters  => "--thing=${thing}",
}

• List buckets (This isn't a great example because it does not need $parameters and the output only goes to the Puppet agent log.)
  • Equivalent to couchbase-cli bucket-list

couchbase::cli {'bucket-list': }

• Enable email alerts.
  • Equivalent to couchbase-cli setting-alert --enable-email-alert=1

couchbase::cli {'setting-alert':
  parameters  => '--enable-email-alert=1',
}

• Pass multiple params using join() and unique $title
  • Equivalent to couchbase-cli ssl-manage --retrieve-cert=... --regenerate-cert='...'

$parameters = join([
  "--retrieve-cert=${retrieve_cert}",
  "--regenerate-cert='${regenerate_cert}'",
], ' ')

couchbase::cli {"manage certs for ${_site_name}":
  action     => 'ssl-manage',
  parameters => $parameters,
}

Testing

Unit tests:

bundle exec rake test

Acceptance tests:

bundle exec rake acceptance
bundle exec rake acceptance[centos6,onpass,yes]

Parameters to acceptance are: OS to test (see rakefile), BEAKER_destroy value, BEAKER_provision value For initial test, you'd want [OS,no,yes] For subsequent tests, you'd want [OS,no,no] For normal cases, you can just pass [OS] and it'll only tear it down if it doesn't pass

Reference

::couchbase

Deploy Couchbase

• $cluster_ramsize:
  • required
  • integer
  • Cluster's RAM size in MB as int.
• $buckets:
  • hash
  • Default is empty hash (don't manage buckets)
  • A hash of the buckets you want to manage. (see examples)
• $cluster_username:
  • string
  • Default is 'Administrator'
  • Cluster username, used in Couchbase::Cli
• $cluster_password:
  • string
  • Default is 'password'
  • Cluster password, used in Couchbase::Cli
• $cluster_port:
  • string
  • Default is '8091'
  • Cluster's port, used in Couchbase::Cli
• $cluster_host:
  • string
  • Default is 'localhost'
  • Cluster's host, used in Couchbase::Cli
• $index_path:
  • string
  • Default is automatic on CentOS:6 and Windows 2008r2
  • Full path to 'nodeindex' in Couchbase's base directory. Used by Couchbase::Hostinit.
• $data_path:
  • string
  • Default is automatic on CentOS:6 and Windows 2008r2
  • Full path to 'nodedata' in Couchbase's base directory. Used by Couchbase::Hostinit.
• $try_sleep:
  • integer
  • Default is 6.
  • Passed to Exec[] calls in Couchbase::Cli. The high default values of $try_sleep and $tries are usually only needed during Couchbase installation because it takes some extra time after the package is installed before the daemon can start accepting API calls. Feel free to set both of these to 0 at any time but understand that it may take 2 or more Puppet agent (non-idempotent) runs before reaching convergence.
• $tries:
  • integer
  • Default is 9
  • Passed to Exec[] calls in Couchbase::Cli. See also $try_sleep.
• $service_ensure:
  • string, (running|stopped)
  • Default is 'running'
  • Passed to service declaration in Couchbase::Service
• $package_file:
  • string
  • Default is automatic on CentOS:6 and Windows 2008r2
  • Name of install file, like "couchbase-foo-bar.1.2.3.rpm"
• $package_ensure:
  • string, (installed|absent)
  • Default is 'installed'
  • Passed to package declaration in Couchbase::Package
  • TODO: May be replaced with present=>'true|false'
• $package_temp_dir:
  • string
  • Default is automatically 'c:/' or '/tmp/'
  • Full path to a good temporary directory to house the install file. You should override this on Windows because 'c:/' isn't a good temporary folder.
• $package_iss_file:
  • WINDOWS
  • string
  • Default is 'couchbase400.iss'
  • Name (without path) of the response file InstallShield uses to install Couchbase headlessly.
• $package_provider:
  • string
  • Default is automatically 'windows' or 'rpm'.
  • Passed to the package declaration in Couchbase::Package.
• $package_install_options:
  • string or array
  • Default is automatic depending on OS.
  • Passed to the package declaration in Couchbase::Package
• $wget_source:
  • string
  • Default is automatic depending on OS.
  • Full URL (including file name) to get the .exe or .rpm install file.
• $file_source_base:
  • decomed

::couchbase::bucket

Define a bucket in Couchbase

• $title
  • string
  • Name of the bucket.
• $present
  • boolean (true|false)
  • Default is true
  • Whether to create or remove bucket named $title. Will delete bucket if set to false.
• $flush
  • integer (but treated as string)
  • Default is 0
  • Enable/disable flush. Passed to "--enable-flush=" parameter during bucket create.
• $replica
  • integer (but treated as string)
  • Default is 0
  • Replica count. Passed to "--bucket-replica=" parameter during bucket create.
• $enable_index_replica
  • integer (but treated as string)
  • Default is 0
  • Enables number of replicas. Passed to "--enable-index-replica=" parameter during bucket create.
• $ramsize
  • integer
  • Default is 100
  • Memory size, in MB, allocated to bucket.
• $port
  • integer
  • Default is 11211
  • "TCP port 11211 with SASL authentication, or a dedicated port with no password". Passed to "--bucket-port=" during bucket create.
• $type
  • string (couchbase|memcached)
  • Default is 'couchbase'
  • Type of bucket, passed to "--bucket-type=" during bucket create. Cannot be changed after bucket is created.
• $password
  • string
  • Default is none.
  • Bucket-specific SASL password. This is an optional parameter passed to "--bucket-password=" during bucket create.
• $couchbase_etc
  • string
  • Defaults to value of $etc_path in ::couchbase which is determined automatically based on operating system. ('/opt/couchbase/etc/'|'C:/Program Files/Couchbase/Server/etc/')
  • Full path to Couchbase's /etc/ directory.

::couchbase::cli

Run the couchbase-cli[.exe] command with arguments.

• $action
  • string
  • Default is $title
  • First argument given to cli.
• $creates
  • path
  • Passed to 'creates' in the Exec[] resource. One or more file paths that the cli command is expected to create.
• $exec_cwd
  • path
  • Default is base directory of Couchbase installation.
  • Overrides 'cwd' in the Exec[] resource.
• $exec_title
  • string
  • Default is "${title} ${action} ${parameters}"
  • Overrides $title of the Exec[] resource.
• $exec_loglevel
  • string
  • Default is 'notice'
  • Overrides 'loglevel' in the Exec[] resource.
• $onlyif
  • string
  • $action and $parameters of a Couchbase::Cli call which gets parsed and aassed to 'onlyif' of the Exec[] resource as a complete command..
• $parameters
  • string
  • Arguments to run.
• $refreshonly
  • bool
  • Default is false
  • Overrides 'refreshonly' in the Exec[] resource.
• $returns
  • integer (or array of integers)
  • Default is 0
  • Overrides 'returns' in the Exec[] resource.
• $tries
  • integer
  • Default is $::couchbase::tries
  • Overrides 'tries' in the Exec[] resource.
• $try_sleep
  • integer
  • Default is $::couchbase::try_sleep
  • Overrides 'tries' in the Exec[] resource.
• $unless
  • string
  • $action and $parameters of a Couchbase::Cli call which gets parsed and aassed to 'onlyif' of the Exec[] resource as a complete command..
• $cli
  • path
  • Default is automatically determined based on OS.
  • Full path to the couchbase-cli[.exe] command.
• $username
  • string
  • Default is $::couchbase::cluster_username,
  • Username used to authenticate in the cluster.
• $password
  • string
  • Default is $::couchbase::cluster_password,
  • Password used to authenticate in the cluster.

::couchbase::statefile

Define local trigger files to pass state information between CouchDB and Puppet.

• $title:
  • string
  • Used in name of state file.
• $content:
  • string
  • Default is ''
  • Text to put in the state file.
• $present:
  • boolean (true|false)
  • Default is true
  • Manage or remove the state file.
• $do_notify:
  • resource
  • Default is Couchbase::Cli[$title]
  • Resource to notify when state file contents change.
• $etc_path:
  • string
  • Default is automatic based on OS.
  • Full path to Couchbase's /etc/ directory (ex: '/opt/couchbase/etc/')
• $msg_prefix:
  • string
  • Default is "# Stafefile for ${title}, do not edit! \n"
  • Text added to state file before $content

Limitations

Module written and tested on these operating systems:

• CentOS 6
• Windows 2008r2

Should work on other operating systems that Couchbase supports if you override the appropriate parameters (your mileage may vary).

Development

• Closed. Not accepting issues or pull requests at this time. 2016.02-JH

Known Bugs:

1. Failed CLI calls that are generated from statefile changes lead to split-mind. For example, adding a bucket when there is no more room in the cluster will create a statefile without creating a bucket and manual detection and intervention is required.

TODO:

• Template the iss files, pass installdir
• cbepctl.pp
• settings.pp
• acceptance tests
• expand OS support to match Couchbase's supporting platforms.
  • match spec tests
• add back and integrate local source support in couchbase::package on toggle
  • $use_wget = true|false