From 9219d3f684fe0af9b172c9d442e1288382b3a91d Mon Sep 17 00:00:00 2001 From: Branan Purvine-Riley Date: Fri, 15 Jun 2012 09:26:10 -0700 Subject: [PATCH] Documentation updates and formatting fixes * Re-fill to 80 chars * Update examples section for the current examples directory * Provide an introduction --- deployment/puppet/swift/README.markdown | 176 ------------------------ deployment/puppet/swift/README.md | 138 +++++++++++++++++++ 2 files changed, 138 insertions(+), 176 deletions(-) delete mode 100644 deployment/puppet/swift/README.markdown create mode 100644 deployment/puppet/swift/README.md diff --git a/deployment/puppet/swift/README.markdown b/deployment/puppet/swift/README.markdown deleted file mode 100644 index a4ba1caacc..0000000000 --- a/deployment/puppet/swift/README.markdown +++ /dev/null @@ -1,176 +0,0 @@ -# Disclaimer # - -This is pre-beta code that is actively being developed. - -Although the code is in a functional state, there is currently -no guarentees about the interfaces that it provides. - -I am actively seeking users who understand that this code -is in a pre-alpha state. Feel free to contact me (Dan Bode) -at dan@puppetlabs.com or bodepdfreenode. - -Any feedback greatly appreciated. - -# Use Cases # - -* Tested for a single node swift install - http://swift.openstack.org/development_saio.html - -* Tested for multi-node swift install - http://swift.openstack.org/howto_installmultinode.html - -* Only been tested with tempauth - -# Dependencies: # - -* Only tested on Ubuntu Natty -* Only tested against Puppet 2.7.10 -* Only verified with Swift 1.4.7 - -# module Dependencies # - -This is known to work with master from the following github repos: - -* https://github.com/saz/puppet-ssh -* https://github.com/puppetlabs/puppetlabs-rsync -* https://github.com/saz/puppet-memcached -* https://github.com/puppetlabs/puppetlabs-stdlib - -This module is intended to complement other openstack modules and -will eventually be a submodule of the openstack set of modules: - - https://github.com/puppetlabs/puppetlabs-openstack - -# Usage: # - -## swift: ## - -class that sets up base packages and the base -/etc/swift/swift.conf. - - class { 'swift': - # shared salt used when hashing ring mappings - swift_hash_suffix => 'shared_secret', - } - -## swift::proxy: ## - -class that installs and configures the swift -proxy server - - class { 'swift::proxy': - # specifies that account should be automatically created - # this should be set to true when tempauth is used - account_autocreate = true, - proxy_local_net_ip = $ipaddress_eth1, - #proxy_port = '11211', - # auth type defaults to tempauth - this is the - # only auth that has been tested - #auth_type = 'tempauth', - } - -## swift::storage ## - -class that sets up all of the configuration and dependencies -for swift storage server instances - - class { 'swift::storage': - # address that swift should bind to - storage_local_net_ip => $ipaddress_eth1, - devices => '/srv/node' - } - -## swift::storage::server ## - -Defined resource type that can be used to -create a swift storage server instance. In general, you do -not need to explicity specify your server instances (as the -swift::storage::class will create them for you) - -This will configure an rsync server instance -and swift storage instance to manage the all devices in -the devices directory. - - # the title for this server and the port where it - # will be hosted - swift::storage::server { '6010': - # the type of device (account/object/container) - type => 'object', - # directory where device is mounted - devices => '/srv/node', - # address to bind to - storage_local_net_ip => '127.0.0.1' - } - -## swift::storage::loopback ## - -This defined resource was created to test -swift by creating loopback devices that can be -used for testing - -It creates a partition of size [$seek] -at base_dir/[$name] using dd with [$byte_size], -formats it to be an xfs -filesystem which is mounted at /src/node/[$name] - -It then creates swift::storage::devices for each device -type using the title as the 3rd digit of -a four digit port number :60[digit][role] (object = 0, container = 1, account = 2) - - swift::storage::loopback { '1': - base_dir => '/srv/loopback-device', - mnt_base_dir => '/srv/node', - byte_size => '1024', - seek => '25000', - storage_local_net_ip => '127.0.0.1' -} - -## swift::ringbuiler ## - -class that knows how to build rings. - -Creates the initial rings, collects any exported resources, -and rebalances the ring if it is updated. - - class { 'swift::ringbuilder': - part_power => '18', - replicas => '3', - min_part_hours => '1', - } - -# Example # - -For an example of how to use this module to build out a single node -swift cluster, you can have a look at examples/all.pp - -This example can be used as follows:` - - # set up pre-reqs - puppet apply examples/pre.pp - - # install all swift components on a single node - puppet apply examples/all.pp - -For an example of how to use this module to build out a multi node -swift cluster, you can have a look at examples/multi.pp - -This example assumes that a puppetmaster already exists and is -resolvable as puppetmaster. - -This example can be used as follows:` - - # set up pre-reqs - puppet apply examples/pre.pp - - # install all swift components on a single node - puppet apply examples/all.pp --certname my_role - -# Verifying installation # - -This module also comes with a simple Ruby script that validates -rather or not your swift cluster is functional. - -The script can be run as: - - ruby /files/swift_tester.rb - diff --git a/deployment/puppet/swift/README.md b/deployment/puppet/swift/README.md new file mode 100644 index 0000000000..072bb46e48 --- /dev/null +++ b/deployment/puppet/swift/README.md @@ -0,0 +1,138 @@ +# Introduction + +This module provides a way to install and configure Swift storage clusters using +puppet. The classes documented in this file will deploy Swift using best +practices for a typical deployment. + +Both single host and clustered configurations are supported. + +## Tested Environments + * Ubuntu 12.04; puppet 2.7.16; Swift 1.4.8 + +# Dependencies + +* https://github.com/saz/puppet-ssh +* https://github.com/puppetlabs/puppetlabs-rsync +* https://github.com/saz/puppet-memcached +* https://github.com/puppetlabs/puppetlabs-stdlib + +# Usage: # + +## swift: ## + +class that sets up base packages and the base /etc/swift/swift.conf. + + class { 'swift': + # shared salt used when hashing ring mappings + swift_hash_suffix => 'shared_secret', + } + +## swift::proxy: ## + +class that installs and configures the swift proxy server + + class { 'swift::proxy': + # specifies that account should be automatically created + # this should be set to true when tempauth is used + account_autocreate = true, + proxy_local_net_ip = $ipaddress_eth1, + #proxy_port = '11211', + # auth type defaults to tempauth - this is the + # only auth that has been tested + #auth_type = 'tempauth', + } + +## swift::storage ## + +class that sets up all of the configuration and dependencies for swift storage +server instances + + class { 'swift::storage': + # address that swift should bind to + storage_local_net_ip => $ipaddress_eth1, + devices => '/srv/node' + } + +## swift::storage::server ## + +Defined resource type that can be used to create a swift storage server +instance. In general, you do not need to explicity specify your server instances +(as the swift::storage::class will create them for you) + +This will configure an rsync server instance and swift storage instance to +manage the all devices in the devices directory. + + # the title for this server and the port where it + # will be hosted + swift::storage::server { '6010': + # the type of device (account/object/container) + type => 'object', + # directory where device is mounted + devices => '/srv/node', + # address to bind to + storage_local_net_ip => '127.0.0.1' + } + +## swift::storage::loopback ## + +This defined resource was created to test swift by creating loopback devices +that can be used for testing + +It creates a partition of size [$seek] at base_dir/[$name] using dd with +[$byte_size], formats it to be an xfs filesystem which is mounted at +[$mnt_base_dir]/[$name] + +It then creates swift::storage::devices for each device type using the title as +the 3rd digit of a four digit port number :60[digit][role] (object = 0, +container = 1, account = 2) + + swift::storage::loopback { '1': + base_dir => '/srv/loopback-device', + mnt_base_dir => '/srv/node', + byte_size => '1024', + seek => '25000', + storage_local_net_ip => '127.0.0.1' +} + +## swift::ringbuiler ## + +class that knows how to build rings. + +Creates the initial rings, collects any exported resources, and rebalances the +ring if it is updated. + + class { 'swift::ringbuilder': + part_power => '18', + replicas => '3', + min_part_hours => '1', + } + +# Example # + +For an example of how to use this module to build out a single node swift +cluster, you can have a look at examples/all.pp + +This example can be used as follows: + + puppet apply examples/all.pp + +For an example of how to use this module to build out a multi node swift +cluster, you can have a look at examples/site.pp. This file assumes you have a +puppetmaster with storeconfigs enabled. + +Please note that if you create fewer than 3 storage nodes, you will need to edit +the `replicas` parameter of the swift::ringbuilder instance in the proxy node +definition. + +Once your puppetmaster is configured, you can provision your nodes with: + + puppet agent -t --certname my_role + +# Verifying installation # + +This module also comes with a simple Ruby script that validates rather or not +your swift cluster is functional. + +The script can be run as: + + ruby files/swift_tester.rb