- based upon Riak 2.0
- configuration format moved line-by-line style
- Changed default value of
gc_max_workersfrom 5 to 2 with its name changed togc.max_workerswith migration to config format change.
- Changed webmachine's access log handler module name.
Upgrading Riak CS system involves upgrading underlying Riak and Stanchion process. Upgrade process might be complicated depending on system configuration and version combination. This document describes general instructions of upgrading the whole system to Riak CS 2.0, and notices on upgrading.
For minor use cases and more detail information, consult Riak and Riak CS's release notes.
- Riak 1.4 series release notes
- Riak 2.0 series release notes
- Riak CS 1.4 series release notes
- Riak CS 1.5 series release notes
Basho only support 2 older versions from the latest release. For Riak CS 2.0 case, only upgrades from 1.4 series and 1.5 series are supported. Basically this pattern is out of the scope of this document.
To upgrade to 2.0 from these versions prior to 1.4, operators need another extra step to upgrade the whole system to Riak CS 1.4.5 or Riak CS 1.5.4. Upgrading to 1.5.4 would rather be recommented than to 1.4.5. Thus underlying Riak would also better upgraded to 1.4 series - hopefully the latest 1.4.12.
General Instructions are to repeat this overview on every node:
- Stop Riak CS process
- Stop Riak process
- Backup all configuration files
- Uninstall old Riak CS and Riak package
- Install new Riak CS and Riak package
- Migrate Riak configuration
- Migrate Riak CS configuration
- Start Riak
- Start Riak CS
Stanchion can be updated at any time during the system upgrade theoretically. Although, we recommend updating Stanchion before all other instructions. Be careful enough not to run multiple live Stanchion nodes at once where both are referred from CS nodes.
At 2.0, Riak has introduced a new configuration style. But it also
supports old style called app.config and vm.args. So does Riak
CS 2.0. But Basho would recommend moving on to unified configuration
file called riak.conf, riak-cs.conf and stanchion.conf.
As Riak CS 2.0 only works on top of Riak 2.0 and does not work on Riak 1.x series, underlying Riak should necessarily upgraded to 2.0. Although general guides for upgrading Riak to 2.0 are in 2.0 upgrade guide, below are configuration changes for Riak cluster serving for Riak CS.
Default bucket properties have been configured in older Riak CS as follows:
{riak_core, [
...
{default_bucket_props, [{allow_mult, true}]},
...
]}.Now it is just as follows at Riak 2.0.
buckets.default.allow_mult = true
Note: this is defined in riak_kv.schema
For Riak 2.0.5 or older, Old style backend configuration same as 1.5
should be written in riak_kv section of advanced.config. See
Setting up the Proper Riak Backend
for details.
For later release than Riak 2.0.5, new configuration in Riak will be just
storage_backend = prefix_multi
cs_version = 20000
cs_version could not be removed when Riak is running under Riak. Old
style backend configuration using riak_cs_kv_multi_backend also can
be written in advanced.config.
Although
Upgrading Your Configuration System
describes general topics on upgrading from 1.4 Riak series to 2.0
Riak, here are several major configuration items which are essential
for Riak CS. erlang.distribution_buffer_size is commented out by
default.
| Riak 1.4 | Riak 2.0 |
|---|---|
+zdbbl |
erlang.distribution_buffer_size = 1MB |
-name riak@127.0.0.1 |
nodename = riak@127.0.0.1 |
-setcookie riak |
distributed_cookie = riak |
If storage calculation is required to your system, several more configurations are required.
Including CS path: add following sentence to advanced.config:
{riak_kv, [
{add_paths, ["/usr/lib/riak-cs/lib/riak_cs-2.0.0/ebin"]}
]}.Consult Configuration Mapping Table to preserve same configuration between CS 1.5 and 2.0.
If obsolete configurations like fold_objects_for_list_keys,
n_val_1_get_requests or gc_paginated_indexes are still set as
false, removing any of them from configuraiton file is strongly
recommended at Riak CS 2.0, because those configuration items are just
to preserve old and slow behaviours of Riak CS and have no inpact on
functionality.
Multibag configurations are to be moved to advanced.config for both
Riak CS and Stanchion.
Some objects changes their names after upgrade. Applications may change it's behaviour due to this bugfix.
Bucket number limitation per user had been introduced at 1.5.1. Users who have more than 100 buckets cannot create any bucket after upgrade unless the limit number extended at the system configuration.
An operational procedure to clean up incomplete multipart under deleted buckets is needed. Otherwise new buckets which used to exist in the past couldn't be created. The operation will fail with 409 Conflict.
Leeway seconds and disk space should also be carefully watched during the upgrade, because timestamp management of garbage collection had been changed since 1.5 release. Consult "Leeway seconds and disk space" section of 1.5.0 release notes for more detailed description.
Riak CS nodes not corriding in a same box with live Riak node can be upgraded at any time while corresponding remote Riak is alive. Instructions follow:
- Stop Riak CS process
- Backup configuration files
- Uninstall Riak CS package
- Install Riak CS 2.0 package
- Update configuration
- Start Riak CS
We have not yet tested downgrading from Riak CS 2.0 to Riak CS 1.4.
To downgrade Riak CS 2.0 system to Riak CS 1.5 system, repeat following instructions for each nodes:
- Stop Riak CS process
- Stop Riak process
- Uninstall Riak CS
- Uninstall Riak
- Run downgrade bitcask script for all bitcask directories
- Install Riak
- Install Riak CS
- Restore configuration files
- Start Riak Process
- Start CS Process
Bitcask file format has changed between Riak 1.4 and 2.0. It supports implicit upgrade of bitcask data files, while downgrading is not supported. This is why downgrading requires a script to translate data files.
Some important configuration changes happened between 1.5 and 2.0, Not only translating items 1:1.
Value following with = is its default value.
The file name has changed from app.config and vm.args to only
riak-cs.conf, whose path haven't changed.
Note: storage.stats.schedule.$time does not have any default
value but an example is added.
riak_cs section in app.config
| 1.5 | 2.0 |
|---|---|
{cs_ip, "127.0.0.1"} |
listener = 127.0.0.1:8080 |
{cs_port, 8080} |
|
{riak_ip, "127.0.0.1"} |
riak_host = 127.0.0.1:8087 |
{riak_pb_port, 8087} |
|
{stanchion_ip, "127.0.0.1"} |
stanchion_host = 127.0.0.1:8085 |
{stanchion_port, 8085 } |
|
{stanchion_ssl, false } |
stanchion_ssl = off |
{anonymous_user_creation, false} |
anonymous_user_creation = off |
{admin_key, "admin-key"} |
admin.key = admin-key |
{admin_secret, "admin-secret"} |
admin.secret = admin-secret |
{cs_root_host, "s3.amazonaws.com"} |
root_host = s3.amazonaws.com |
{connection_pools,[ |
|
{request_pool, {128, 0} }, |
pool.request.size = 128 |
pool.request.overflow = 0 |
|
{bucket_list_pool, {5, 0} } |
pool.list.size = 5 |
pool.list.overflow = 0 |
|
{trust_x_forwarded_for, false} |
trust_x_forwarded_for = off |
{leeway_seconds, 86400} |
gc.leeway_period = 24h |
{gc_interval, 900} |
gc.interval = 15m |
{gc_retry_interval, 21600} |
gc.retry_interval = 6h |
{access_log_flush_factor, 1} |
stats.access.flush_factor = 1 |
{access_log_flush_size, 1000000} |
stats.access.flush_size = 1000000 |
{access_archive_period, 3600} |
stats.access.archive_period = 1h |
{access_archiver_max_backlog, 2} |
stats.access.archiver.max_backlog = 2 |
| (no explicit default) | stats.access.archiver.max_workers = 2 |
{storage_schedule, []} |
stats.storage.schedule.$time = "06:00" |
{storage_archive_period, 86400} |
stats.storage.archive_period = 1d |
{usage_request_limit, 744} |
riak_cs.usage_request_limit = 31d |
{cs_version, 10300 } |
cs_version = 10300 |
{dtrace_support, false} |
dtrace = off |
webmachine section in app.config
| 1.5 | 2.0 |
|---|---|
{server_name, "Riak CS"} |
server_name = Riak CS |
{log_handlers, ....} |
log.access.dir = /var/log/riak-cs |
To disable access logging, just remove the line beginning with
log.access.dir from riak-cs.conf.
Thus all of them are undefined and disabled, except modules. rewrite_module and
auth_module will be commented out but the default value won't change from 1.5.
This is for indicating operators how to change these to OOS API.
| 1.5 | 2.0 |
|---|---|
{rewrite_module, riak_cs_s3_rewrite } |
rewrite_module |
{auth_module, riak_cs_s3_auth }, |
auth_module |
{admin_ip, "127.0.0.1"} |
admin.listener = 127.0.0.1:8000 |
{admin_port, 8000 } |
|
{ssl, [ |
|
{certfile, "./etc/cert.pem"} |
ssl.certfile |
{keyfile, "./etc/key.pem"} |
ssl.keyfile |
fold_objects_for_list_keys, n_val_1_get_requests and
gc_paginated_indexes - These items do not have corresponding item in
riak-cs.conf. If old behaviors are preferred, they must be in
riak_cs section of advanced.config.
stanchion section in app.config.
| 1.5 | 2.0 |
|---|---|
{stanchion_ip, "127.0.0.1"} |
listener = 127.0.0.1:8080 |
{stanchion_port, 8085} |
|
{riak_ip, "127.0.0.1"} |
riak_host = 127.0.0.1:8087 |
{riak_pb_port, 8087} |
|
{admin_key, "admin-key"} |
admin.key = admin-key |
{admin_secret, "admin-secret"} |
admin.secret = admin-secret |
Commented out by default and consequently undefined so as to disable SSL.
| 1.5 | 2.0 |
|---|---|
{ssl, [ |
|
{certfile, "./etc/cert.pem"} |
ssl.certfile |
{keyfile, "./etc/key.pem"} |
ssl.keyfile |
Mostly same mapping with Riak or even should be same as copy-and-pasted from Riak.