Architecture Overview

From 10,000m altitude to 1,000m

The term "Riak CS" has two meanings depending on the context -

1. The product name, and the whole system
2. The process and package name

In the context of 1., this picture below illustrates what it is like. Riak CS is a system that exposes an AWS S3 API (and Swift API of a small portion), by chunking a large object and storing each chunk as a Riak key and value.

It consists of three packages as a software, Riak KV, Riak CS (in the context of 2.) and Stanchion. Each of them is a standalone process that is loosely coupled with each other through HTTP(S) or Protocol Buffers.

All data in Riak CS, users, CS buckets, object manifests, blocks, usage stats are stored Riak KV. Riak CS nodes serves HTTP(S) service, aka S3 API exposed to clients, by sending PB requests to Riak KV. Stanchion is a man in the middle to serialize update requests to keys that needs strong consistency (CS buckets) in Riak KV.

Riak CS S3 Storage API covers all supported API functionalities and good start point to learn how it can be used. To know what's behind Object-level operations, Object Chunking and Garbage Collection is the best document. To know what's behind Bucket-level operations, Buckets-and-Users might be the best document.

There are also administrative APIs that are not in S3. Access stats API is to know incoming and outgoing traffic via CS nodes. Storage stats API is to query storage statistics, which is a log of internal storage calculation job. This allows operators to know all users' usage of storage, and account for disk usage by describing non-visible disk usage. For their internals, see Logging-Access-Stats, Logging-Storage-Stats, Querying-Access-Stats, and Querying-Storage-Stats.

HTTP Admin API is for managing users such as create, disable/enable and update meta information. Internals are partially described in Buckets-and-Users.

As an HTTP web service, Riak CS uses Webmachine. To learn Webmachine, its wiki pages are very good guidance to start with. S3 APIs are mapped to internal Native-API with rewrite rules. Each native API implementation is in riak_cs_wm_*.erl code, where we don't have further documentation. To read through the put/get/delete paths, riak_cs_web.erl would be a good start, because it describes native API URL routing.

Other internal services in supervision tree, are listed here:

• riak_cs_access_archiver_manager - access archiver periodically flushed local access stats to Riak.
• riak_cs_storage_d - storage daemon invokes storage calculation job according to configuration. Storage calculation job is just a series of MapReduce requests to Riak, for all CS buckets (manifest buckets as Riak), all users.
• riak_cs_gc_manager - GC manager periodically checks GC schedule, or accepts manual operation through riak-cs-admin gc to spawn and to control riak_cs_gc_batch.
• riak_cs_quota_sup supervises state managers of quota system.
• and Multibag supervisor.