Magazyn obiektowy

Podstawowe informacje

Magazyn obiektowy to rozwiązanie programowe pozwalające na składowanie danych (obiektów) zgrupowanych w buckety. Usługa udostępnia możliwość korzystania z REST API S3, które jest kompatybilne z Amazon S3 REST API. Usługa dostępna jest pod adresem https://s3.storage.task.gda.pl

Dostęp do usługi 

Aby zacząć korzystać z magazynu obiektowego niezbędne jest uzyskanie danych dostępowych. Dostępy przyznawane są w ramach umów/grantów przez operatorów usługi. Dostęp do danych będzie udzielony poprzez udostępnienie dwóch wrażliwych danych, które będą wyglądały następująco:

[default]
aws_access_key_id = ABCDEFGHIJK123456789
aws_secret_access_key = abcdefhijklmnopqrstuvwxyzAaBbC1234567890

UWAGA dostęp do magazynu obiektowego jest publiczny. Pamiętaj o odpowiednim zabezpieczeniu dostępu do bucketów i obiektów.

Sposób użycia

Zalecanym sposobem korzystania z S3 API jest użycie w tym celu kontenera Docker uruchomionym na obrazie amazon/aws-cli. Obraz ten umożliwia bezpośrednią komunikację z S3 API przy odpowiedniej konfiguracji. W celu umożliwienia korzystania zaleca się stworzenie następującej funkcji (np. poprzez dodanie do pliku .bashrc):

function docker_awscli() {
    COMMAND=${1}
    DOCKER_VOLUME=${2:-"/dev/null"}
    docker run \
        --name "docker_awscli" \
        --rm \
        --volume "${DOCKER_VOLUME}:${DOCKER_VOLUME}" \
        --env "AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID}" \
        --env "AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY}" \
        --env "AWS_DEFAULT_REGION=default" \
        "amazon/aws-cli" \
            --endpoint-url="https://s3.storage.task.gda.pl" \
            ${COMMAND}
}

powyższa funkcja wymaga istnienia w danej sesji terminala zmiennych środowiskowych AWS_ACCESS_KEY_ID oraz AWS_SECRET_ACCESS_KEY. W tym celu należy owe zmienne ustawić przed pierwszym użyciem funkcji:

export AWS_ACCESS_KEY_ID=<your_access_key>

export AWS_SECRET_ACCESS_KEY=<your_secret_key>

Zmienna DOCKER_VOLUME wskazuje na katalog z dysku lokalnego, który jest montowany do kontenera i z którego chcemy np. wysłać dane do magazynu obiektowego lub do którego chcemy je pobrać. Występuje jako drugi parametr do polecenia docker_awscli.

Przykłady użycia

Po prawidłowej konfiguracji danych dostępowych oraz funkcji uruchamiającej kontener możliwe i bardzo łatwe staje się komunikowanie z API S3. Poniżej znajdują się proste przykłady użycia:

  1. Tworzenie bucketu:

    Komenda:

    docker_awscli "s3 mb s3://my-first-bucket"

    Przykładowy output:

    make_bucket: my-first-bucket

  2. Listowanie bucketów:

    Komenda:

    docker_awscli "s3 ls"

    Przykładowy output:

    2021-01-26 07:30:23 my-first-bucket
2021-01-26 07:30:25 my-second-bucket

  3. Synchronizacja aktualnego katalogu z określoną lokalizacją w buckecie:

    Komenda:

    docker_awscli "s3 sync ${PWD} s3://my-first-bucket/katalog" ${PWD}

    Przykładowy output:

    upload: home/documentation/.git/HEAD to s3://my-first-bucket/katalog/.git/HEAD
upload: home/documentation/.git/hooks/pre-applypatch.sample to s3://my-first-bucket/katalog/.git/hooks/pre-applypatch.sample
upload: home/documentation/.git/hooks/post-update.sample to s3://my-first-bucket/katalog/.git/hooks/post-update.sample
upload: home/documentation/.git/hooks/commit-msg.sample to s3://my-first-bucket/katalog/.git/hooks/commit-msg.sample
...

  4. Listowanie (rekursywne) zawartości pojedynczego bucketu:

    Komenda:

    docker_awscli "s3 ls --recursive s3://my-first-bucket"

    Przykładowy output:

    2021-01-26 07:34:53         19 katalog/.git/COMMIT_EDITMSG
2021-01-26 07:34:53        607 katalog/.git/FETCH_HEAD
2021-01-26 07:34:53         45 katalog/.git/HEAD
2021-01-26 07:34:53         41 katalog/.git/ORIG_HEAD
...

  5. Synchronizacja określonej lokalizacji bucketu z danym podkatalogiem aktualnego katalogu:

    Komenda:

    mkdir katalog
docker_awscli "s3 sync s3://my-first-bucket/katalog ${PWD}/katalog" ${PWD}/katalog

    Przykładowy output:

    download: s3://my-first-bucket/katalog/.git/FETCH_HEAD to home/documentation/katalog/.git/FETCH_HEAD
download: s3://my-first-bucket/katalog/.git/COMMIT_EDITMSG to home/documentation/katalog/.git/COMMIT_EDITMSG
download: s3://my-first-bucket/katalog/.git/description to home/documentation/katalog/.git/description
download: s3://my-first-bucket/katalog/.git/config to home/documentation/katalog/.git/config
...

  6. Usunięcie bucketu:

    Komenda:

    docker_awscli "s3 rb s3://my-first-bucket"

    Jeśli w buckecie istnieją dane to powyższa komenda nie zadziała i prawdopodobnie otrzymamy coś takiego:

    remove_bucket failed: s3://my-first-bucket An error occurred (BucketNotEmpty) when calling the DeleteBucket operation: Unknown

    Aby usunąć bucket z danymi można użyć metody siłowej, czyli dodać do komendy parametr --force:

    docker_awscli "s3 rb --force s3://my-first-bucket"

    Przykładowy output:

    delete: s3://my-first-bucket/katalog/.git/COMMIT_EDITMSG
delete: s3://my-first-bucket/katalog/.git/FETCH_HEAD
delete: s3://my-first-bucket/katalog/.git/config
delete: s3://my-first-bucket/katalog/.git/hooks/pre-applypatch.sample
...

Jak widać korzystanie z API S3 nie musi być trudne, powyższy sposób oferuje o wiele więcej działających poleceń ale nie ma sensu ich wszystkich tutaj opisywać. Warto wspomnieć, że kontener, którego użyliśmy w tej instrukcji to po prostu moduł w Pythonie awscli, którego komendą domyślną (entrypoint) jest komenda aws.

Jeśli chcesz dowiedzeć się więcej o możliwościach tego modułu zajrzyj do jego dokumentacji Python awscli.

Jeśli nie chcesz korzystać z Dockera w celu komunikacji z Ceph po S3 API, możesz bezpośrednio zainstalować wspomniany wcześniej moduł. Na stronie z dokumentacją dowiesz się jak go zainstalować oraz używać.