Guide to Configuring and Using Ceph s3-tests for S3 Compatibility Verification

During the iterative development and testing of object storage, the author introduces Ceph's official compatibility testing tool s3-tests , which leverages the Python Nose framework and Boto libraries to verify S3 API compliance.

The tool can output test results to a web interface using an HTML extension, allowing users to query statistics and analyze outcomes.

To get started, clone the repository and install required packages:

# git clone https://github.com/ceph/s3-tests.git

# sudo apt-get install python-virtualenv

# cd s3-tests

Bootstrap the virtual environment and install dependencies:

# ./bootstrap

Create a config.yaml file with the necessary credentials and settings, for example:

[DEFAULT]
host = test-shyc2.s3.360.local  # optional local gateway IP
port = 80
is_secure = no

[fixtures]
bucket prefix = s3test-{random}-

[s3 main]
user_id = infra-s3
display_name = infra-s3
access_key = infra-ak
secret_key = infra-sk

[s3 alt]
user_id = infra-alt
display_name = infra-alt
email = [email protected]
access_key = infra-alt-ak
secret_key = infra-alt-sk

Run a collection of tests to verify configuration:

~ /s3-tests# S3TEST_CONF=./config.yaml ./virtualenv/bin/nosetests -v --collect-only

Install the nose-html-reporting plugin to generate HTML reports:

# ./virtualenv/bin/pip install nose-html-reporting

Verify installation:

~/s3-tests# ./virtualenv/bin/nosetests -h | grep html

Execute a single test case with a custom Jinja2 template:

~ /s3-tests# S3TEST_CONF=./config.yaml ./virtualenv/bin/nosetests s3tests.functional.test_s3:test_bucket_list_empty -v --with-html --html-report=/var/www/html/index.html --html-report-template=virtualenv/lib/python2.7/site-packages/nose_html_reporting/templates/report2.jinja2

Run the full test suite with AWS V4 authentication and HTML output:

S3_USE_SIGV4=1 S3TEST_CONF=./config.yaml ./virtualenv/bin/nosetests -a auth_aws4 -v --with-html --html-report=/var/www/html/index.html

Sample output shows many tests passing, with a few failures and skips, and confirms that the HTML report is generated at /var/www/html/index.html .

For custom S3 interfaces, new test functions can be added. An example of an HTTP Range request test is provided:

@attr(resource='object')
@attr(method='get')
@attr(operation='range')
@attr(assertion='returns correct data, 206')
def test_ranged_big_request_response_code():
    bucket = get_new_bucket()
    key = bucket.new_key('testobj')
    string = os.urandom(8 * 1024 * 1024)
    # upload object
    key.set_contents_from_string(string)
    # set Range header
    key.open('r', headers={'Range': 'bytes=3145728-5242880'})
    status = key.resp.status
    content_range = key.resp.getheader('Content-Range')
    fetched_content = ''
    for data in key:
        fetched_content += data
    key.close()
    eq(fetched_content, string[3145728:5242881])
    eq(status, 206)
    eq(content_range, 'bytes 3145728-5242880/8388608')

These steps allow developers to extend existing unit tests for custom S3 features, run comprehensive compatibility checks, and analyze results through an interactive HTML dashboard.