Cloud4You OCS – AWS CLI i S3 API¶

Cloud4You OCS udostępnia przestrzeń obiektową zgodną z API Amazon S3.

Oznacza to, że do obsługi OCS można używać popularnych narzędzi i aplikacji obsługujących S3, między innymi:

AWS CLI,
rclone,
Veeam,
bibliotek AWS SDK,
aplikacji korzystających z S3 API.

Ta strona pokazuje obsługę Cloud4You OCS za pomocą AWS CLI oraz podstawowe operacje dostępne przez S3 API.

Jeżeli chcesz zarządzać plikami z przeglądarki, możesz użyć OCS Browser:

Najważniejsze dane¶

Do połączenia potrzebujesz:

Parametr	Wartość
Endpoint	`https://s3.cloud4you.pl`
Region	`eu-pl-1`
Access Key ID	Twój klucz dostępowy
Secret Access Key	Twój klucz tajny
API	S3-compatible
Podpisywanie żądań	AWS Signature Version 4

Zalecamy korzystanie z głównego endpointu:

https://s3.cloud4you.pl

Nie wpisuj adresu panelu WWW jako endpointu S3.

To:

https://ocs.cloud4you.pl

jest panelem do obsługi przez przeglądarkę.

To:

https://s3.cloud4you.pl

jest endpointem S3 dla aplikacji, AWS CLI i SDK.

Co oznacza zgodność z S3¶

Cloud4You OCS korzysta z Ceph Object Gateway – RGW.

RGW udostępnia API zgodne z dużą częścią Amazon S3 API.

W praktyce oznacza to, że standardowe operacje takie jak:

tworzenie bucketa
wysyłanie obiektu
pobieranie obiektu
usuwanie obiektu
kopiowanie obiektu
multipart upload
versioning
Object Lock
retention
Legal Hold
CORS
tagi
lifecycle
bucket policy

mogą być wykonywane za pomocą standardowych poleceń AWS CLI.

Cloud4You OCS nie jest usługą Amazon AWS.

Nie należy zakładać, że każda nowa funkcja dostępna w Amazon S3 będzie dostępna w OCS.

Jeżeli dokumentacja AWS pokazuje funkcję specyficzną dla:

S3 Express
Directory Buckets
AWS Organizations
AWS Billing
AWS Access Points
AWS Outposts

nie oznacza to automatycznie, że funkcja jest dostępna w Cloud4You OCS.

AWS CLI i s3api – jaka jest różnica¶

AWS CLI udostępnia dwa podstawowe zestawy poleceń do S3.

`aws s3`¶

To prostsze polecenia do codziennej pracy.

Przykłady:

aws s3 ls
aws s3 cp
aws s3 sync
aws s3 mv
aws s3 rm
aws s3 mb
aws s3 rb

Jeżeli chcesz po prostu:

wysłać plik,
pobrać plik,
zobaczyć zawartość bucketa,
zsynchronizować katalog,

używaj:

aws s3

`aws s3api`¶

To polecenia niższego poziomu, odpowiadające konkretnym operacjom S3 API.

Przykłady:

aws s3api list-buckets
aws s3api create-bucket
aws s3api put-bucket-versioning
aws s3api get-bucket-cors
aws s3api put-object-retention

Jeżeli chcesz zarządzać:

versioningiem,
CORS,
Object Lock,
retencją,
tagami,
lifecycle,
bucket policy,

używaj:

aws s3api

Instalacja AWS CLI¶

Do pracy zalecamy AWS CLI w wersji 2.

Sprawdź najpierw, czy program nie jest już zainstalowany:

aws --version

Jeżeli zobaczysz wynik podobny do:

aws-cli/2.x.x

możesz przejść do konfiguracji.

Windows¶

Uruchom PowerShell lub Command Prompt jako Administrator.

Wpisz:

msiexec.exe /i https://awscli.amazonaws.com/AWSCLIV2.msi

Po instalacji zamknij terminal i otwórz go ponownie.

Sprawdź:

aws --version

Linux¶

Najprostsza instalacja dla całego systemu:

curl -fsSL https://awscli.amazonaws.com/v2/install.sh | sudo bash -s -- --system

Sprawdź:

aws --version

Jeżeli nie masz sudo, możesz zainstalować AWS CLI tylko dla swojego użytkownika:

curl -fsSL https://awscli.amazonaws.com/v2/install.sh | bash

Następnie otwórz nową sesję terminala i sprawdź:

aws --version

macOS¶

Instalacja dla bieżącego użytkownika:

curl -fsSL https://awscli.amazonaws.com/v2/install.sh | bash

Sprawdź:

aws --version

AWS udostępnia również instalator graficzny .pkg.

Konfiguracja danych dostępowych¶

Zalecamy utworzenie osobnego profilu:

cloud4you

Dzięki temu konfiguracja OCS nie miesza się z innymi kontami AWS lub S3.

Uruchom:

aws configure --profile cloud4you

Program zapyta o:

AWS Access Key ID [None]:
AWS Secret Access Key [None]:
Default region name [None]:
Default output format [None]:

Wpisz:

AWS Access Key ID:        TWÓJ_ACCESS_KEY
AWS Secret Access Key:    TWÓJ_SECRET_KEY
Default region name:      eu-pl-1
Default output format:    json

Przykład:

AWS Access Key ID [None]: ABCDEFGHIJKLMNOP
AWS Secret Access Key [None]: ********************************
Default region name [None]: eu-pl-1
Default output format [None]: json

Nigdy nie publikuj prawdziwego Secret Access Key.

Gdzie zapisują się klucze¶

Linux i macOS:

~/.aws/credentials
~/.aws/config

Windows:

%USERPROFILE%\.aws\credentials
%USERPROFILE%\.aws\config

Plik credentials wygląda podobnie do:

[cloud4you]
aws_access_key_id = TWÓJ_ACCESS_KEY
aws_secret_access_key = TWÓJ_SECRET_KEY

Plik zawiera dane dostępowe.

Nie:

wysyłaj go mailem,
wklejaj go do zgłoszenia,
wrzucaj go do Git,
pokazuj go na zrzucie ekranu.

Stałe ustawienie endpointu Cloud4You¶

AWS CLI domyślnie próbuje łączyć się z serwerami Amazon.

Dlatego musimy powiedzieć mu, że profil cloud4you ma korzystać z:

https://s3.cloud4you.pl

Otwórz plik:

Linux / macOS:

~/.aws/config

Windows:

%USERPROFILE%\.aws\config

Ustaw:

[profile cloud4you]
region = eu-pl-1
output = json
services = cloud4you-ocs

s3 =
  addressing_style = path

[services cloud4you-ocs]
s3 =
  endpoint_url = https://s3.cloud4you.pl

Po tej konfiguracji nie trzeba dodawać do każdego polecenia:

--endpoint-url https://s3.cloud4you.pl

W dalszej części dokumentacji zakładamy, że endpoint został zapisany w profilu.

Dlaczego używamy `addressing_style = path`¶

S3 może adresować bucket na dwa sposoby.

Virtual-hosted style:

https://moj-bucket.s3.example.com/plik.txt

Path style:

https://s3.example.com/moj-bucket/plik.txt

W dokumentacji Cloud4You używamy:

addressing_style = path

Dzięki temu klient zawsze korzysta z głównego endpointu:

https://s3.cloud4you.pl

Test konfiguracji¶

Najprostszy test:

aws s3 ls --profile cloud4you

Jeżeli wszystko działa, zobaczysz listę bucketów.

Przykład:

2026-08-28 10:15:00 backup-firma
2026-08-28 11:02:31 dokumenty

Jeżeli nie masz jeszcze żadnego bucketa, wynik może być pusty.

To nie musi oznaczać błędu.

Sprawdzenie profilu¶

Lista skonfigurowanych profili:

aws configure list-profiles

Sprawdzenie profilu Cloud4You:

aws configure list --profile cloud4you

Secret Access Key powinien zostać zamaskowany.

Podstawowe polecenia `aws s3`¶

Lista bucketów¶

aws s3 ls --profile cloud4you

Utworzenie bucketu¶

aws s3 mb s3://moj-bucket \
  --profile cloud4you \
  --region eu-pl-1

Przykład:

aws s3 mb s3://backup-firma-01 \
  --profile cloud4you \
  --region eu-pl-1

Nazwy bucketów najlepiej tworzyć z:

małych liter,
cyfr,
myślników.

Przykład:

backup-firma-01

Lista plików w buckecie¶

aws s3 ls s3://backup-firma-01/ \
  --profile cloud4you

Lista wszystkich plików również w podfolderach¶

aws s3 ls s3://backup-firma-01/ \
  --recursive \
  --profile cloud4you

Wysłanie jednego pliku¶

Lokalny plik:

faktura.pdf

wysyłamy poleceniem:

aws s3 cp faktura.pdf s3://backup-firma-01/ \
  --profile cloud4you

Wysłanie pliku pod inną nazwą¶

aws s3 cp faktura.pdf s3://backup-firma-01/faktura-2026-08.pdf \
  --profile cloud4you

Wysłanie pliku do folderu¶

aws s3 cp faktura.pdf s3://backup-firma-01/faktury/faktura.pdf \
  --profile cloud4you

W S3 „folder” jest tak naprawdę częścią nazwy obiektu.

Dla użytkownika wygląda jednak normalnie:

backup-firma-01
└── faktury
    └── faktura.pdf

Wysłanie całego katalogu¶

aws s3 cp ./dokumenty/ s3://backup-firma-01/dokumenty/ \
  --recursive \
  --profile cloud4you

Synchronizacja katalogu¶

aws s3 sync ./dokumenty/ s3://backup-firma-01/dokumenty/ \
  --profile cloud4you

sync przesyła nowe i zmienione pliki.

Domyślnie nie usuwa z bucketa plików, których nie ma już lokalnie.

Synchronizacja z usuwaniem¶

Można wymusić usuwanie plików po stronie docelowej:

aws s3 sync ./dokumenty/ s3://backup-firma-01/dokumenty/ \
  --delete \
  --profile cloud4you

Uwaga na --delete.

Jeżeli pliku nie ma w katalogu źródłowym, może zostać usunięty z lokalizacji docelowej.

Najpierw możesz sprawdzić operację:

aws s3 sync ./dokumenty/ s3://backup-firma-01/dokumenty/ \
  --delete \
  --dryrun \
  --profile cloud4you

--dryrun pokazuje, co zostałoby wykonane, ale niczego nie zmienia.

Pobranie jednego pliku¶

aws s3 cp s3://backup-firma-01/faktura.pdf ./faktura.pdf \
  --profile cloud4you

Pobranie całego katalogu¶

aws s3 cp s3://backup-firma-01/dokumenty/ ./dokumenty/ \
  --recursive \
  --profile cloud4you

Kopiowanie obiektu między bucketami¶

aws s3 cp \
  s3://bucket-a/faktura.pdf \
  s3://bucket-b/faktura.pdf \
  --profile cloud4you

Przenoszenie obiektu¶

aws s3 mv \
  s3://bucket-a/faktura.pdf \
  s3://bucket-b/faktura.pdf \
  --profile cloud4you

Ważne:

mv nie jest magicznym „przesunięciem pliku”.

AWS CLI wykonuje w praktyce:

kopiowanie
+
usunięcie źródła

Przy ważnych danych najpierw wykonaj cp, sprawdź plik w miejscu docelowym i dopiero potem usuń źródło.

Usunięcie jednego obiektu¶

aws s3 rm s3://backup-firma-01/faktura.pdf \
  --profile cloud4you

Usunięcie całej ścieżki¶

aws s3 rm s3://backup-firma-01/stare-dane/ \
  --recursive \
  --profile cloud4you

--recursive może usunąć bardzo dużo danych.

Przed wykonaniem polecenia sprawdź:

nazwę bucketa,
ścieżkę,
czy na pewno chcesz usunąć całą zawartość.

Usunięcie pustego bucketa¶

aws s3 rb s3://backup-firma-01 \
  --profile cloud4you

Bucket musi być pusty.

Wygenerowanie czasowego linku¶

Link ważny przez godzinę:

aws s3 presign s3://backup-firma-01/faktura.pdf \
  --expires-in 3600 \
  --profile cloud4you \
  --region eu-pl-1

Polecenie zwróci adres URL.

Każda osoba posiadająca aktywny link może pobrać wskazany obiekt.

Domyślny czas ważności to:

3600 sekund = 1 godzina

Maksymalny czas obsługiwany przez AWS CLI dla presign to:

604800 sekund = 7 dni

Polecenia `aws s3api`¶

Lista bucketów przez API¶

aws s3api list-buckets \
  --profile cloud4you

Utworzenie bucketu przez API¶

aws s3api create-bucket \
  --bucket backup-firma-01 \
  --region eu-pl-1 \
  --create-bucket-configuration LocationConstraint=eu-pl-1 \
  --profile cloud4you

Sprawdzenie, czy bucket istnieje i jest dostępny¶

aws s3api head-bucket \
  --bucket backup-firma-01 \
  --profile cloud4you

Jeżeli polecenie kończy się bez błędu, bucket jest dostępny dla użytych danych logowania.

Lista obiektów przez API¶

aws s3api list-objects-v2 \
  --bucket backup-firma-01 \
  --profile cloud4you

Tylko obiekty zaczynające się od konkretnego prefiksu:

aws s3api list-objects-v2 \
  --bucket backup-firma-01 \
  --prefix dokumenty/ \
  --profile cloud4you

Informacje o obiekcie¶

aws s3api head-object \
  --bucket backup-firma-01 \
  --key dokumenty/faktura.pdf \
  --profile cloud4you

Możesz zobaczyć między innymi:

rozmiar,
Content-Type,
ETag,
datę modyfikacji,
metadata.

Wysłanie obiektu przez `s3api`¶

aws s3api put-object \
  --bucket backup-firma-01 \
  --key dokumenty/faktura.pdf \
  --body faktura.pdf \
  --profile cloud4you

Do zwykłego uploadu wygodniejsze jest jednak:

aws s3 cp

Pobranie obiektu przez `s3api`¶

aws s3api get-object \
  --bucket backup-firma-01 \
  --key dokumenty/faktura.pdf \
  --profile cloud4you \
  faktura.pdf

Usunięcie obiektu przez API¶

aws s3api delete-object \
  --bucket backup-firma-01 \
  --key dokumenty/faktura.pdf \
  --profile cloud4you

Kopiowanie obiektu przez API¶

aws s3api copy-object \
  --bucket bucket-b \
  --key faktura.pdf \
  --copy-source bucket-a/faktura.pdf \
  --profile cloud4you

Versioning¶

Co robi versioning¶

Versioning pozwala przechowywać wiele wersji tego samego obiektu.

Bez versioningu:

raport.pdf

zostaje nadpisany.

Z versioningiem mogą istnieć:

raport.pdf – wersja A
raport.pdf – wersja B
raport.pdf – wersja C

Każda wersja ma własny VersionId.

Sprawdzenie versioningu¶

aws s3api get-bucket-versioning \
  --bucket backup-firma-01 \
  --profile cloud4you

Włączony:

{
  "Status": "Enabled"
}

Jeżeli versioning nigdy nie był ustawiony, odpowiedź może nie zawierać Status.

Włączenie versioningu¶

aws s3api put-bucket-versioning \
  --bucket backup-firma-01 \
  --versioning-configuration Status=Enabled \
  --profile cloud4you

Wstrzymanie versioningu¶

aws s3api put-bucket-versioning \
  --bucket backup-firma-01 \
  --versioning-configuration Status=Suspended \
  --profile cloud4you

Suspended nie usuwa wcześniejszych wersji.

Po prostu nowe obiekty nie są wersjonowane w taki sam sposób jak przy Enabled.

Lista wersji obiektów¶

aws s3api list-object-versions \
  --bucket backup-firma-01 \
  --profile cloud4you

Usunięcie konkretnej wersji¶

Najpierw znajdź VersionId:

aws s3api list-object-versions \
  --bucket backup-firma-01 \
  --prefix dokumenty/faktura.pdf \
  --profile cloud4you

Następnie:

aws s3api delete-object \
  --bucket backup-firma-01 \
  --key dokumenty/faktura.pdf \
  --version-id VERSION_ID \
  --profile cloud4you

Sprawdź VersionId przed usunięciem.

CORS¶

Co robi CORS¶

CORS steruje dostępem wykonywanym przez przeglądarki internetowe.

Jest potrzebny między innymi wtedy, gdy przeglądarka ma bezpośrednio wysyłać lub pobierać dane z S3.

CORS nie jest wymagany dla standardowych klientów takich jak:

AWS CLI
Veeam
rclone
SDK

Sprawdzenie CORS¶

aws s3api get-bucket-cors \
  --bucket backup-firma-01 \
  --profile cloud4you

Jeżeli bucket nie ma konfiguracji CORS, otrzymasz informację o braku konfiguracji.

Konfiguracja CORS dla OCS Browser¶

Utwórz plik:

cors.json

Zawartość:

{
  "CORSRules": [
    {
      "AllowedOrigins": [
        "https://ocs.cloud4you.pl"
      ],
      "AllowedMethods": [
        "GET",
        "PUT",
        "POST",
        "DELETE",
        "HEAD"
      ],
      "AllowedHeaders": [
        "*"
      ],
      "ExposeHeaders": [
        "ETag"
      ],
      "MaxAgeSeconds": 3600
    }
  ]
}

Zapisz konfigurację:

aws s3api put-bucket-cors \
  --bucket backup-firma-01 \
  --cors-configuration file://cors.json \
  --profile cloud4you

Sprawdź:

aws s3api get-bucket-cors \
  --bucket backup-firma-01 \
  --profile cloud4you

Usunięcie konfiguracji CORS¶

aws s3api delete-bucket-cors \
  --bucket backup-firma-01 \
  --profile cloud4you

Object Lock¶

Co robi Object Lock¶

Object Lock chroni obiekty przed usunięciem lub zmianą przez określony czas.

Najczęściej używa się go dla:

backupów,
danych immutable,
danych wymagających retencji.

W Cloud4You OCS funkcja jest realizowana przez Ceph RGW.

Ważne przed utworzeniem bucketa¶

W używanej przez OCS implementacji Ceph RGW Object Lock należy włączyć podczas tworzenia bucketa.

Nie twórz więc zwykłego bucketa, jeżeli wiesz, że ma być używany jako immutable.

Utwórz go od razu z Object Lock.

Utworzenie bucketa z Object Lock¶

aws s3api create-bucket \
  --bucket immutable-backup \
  --region eu-pl-1 \
  --create-bucket-configuration LocationConstraint=eu-pl-1 \
  --object-lock-enabled-for-bucket \
  --profile cloud4you

Sprawdź versioning:

aws s3api get-bucket-versioning \
  --bucket immutable-backup \
  --profile cloud4you

Jeżeli jest potrzebne, włącz:

aws s3api put-bucket-versioning \
  --bucket immutable-backup \
  --versioning-configuration Status=Enabled \
  --profile cloud4you

Sprawdzenie Object Lock¶

aws s3api get-object-lock-configuration \
  --bucket immutable-backup \
  --profile cloud4you

Domyślna retencja Object Lock¶

Domyślna retencja oznacza:

każdy nowy obiekt dodany do bucketa automatycznie otrzymuje ochronę.

Utwórz plik:

object-lock.json

Przykład retencji 30 dni:

{
  "ObjectLockEnabled": "Enabled",
  "Rule": {
    "DefaultRetention": {
      "Mode": "COMPLIANCE",
      "Days": 30
    }
  }
}

Zastosuj:

aws s3api put-object-lock-configuration \
  --bucket immutable-backup \
  --object-lock-configuration file://object-lock.json \
  --profile cloud4you

Sprawdź:

aws s3api get-object-lock-configuration \
  --bucket immutable-backup \
  --profile cloud4you

GOVERNANCE a COMPLIANCE¶

GOVERNANCE¶

Tryb mniej restrykcyjny.

Użytkownik posiadający odpowiednie uprawnienie może ominąć retencję.

COMPLIANCE¶

Tryb bardziej restrykcyjny.

Obiekt nie powinien zostać usunięty przed zakończeniem retencji.

Nie ustawiaj COMPLIANCE „na próbę” na ważnym buckecie.

Jeżeli ustawisz:

COMPLIANCE + 365 dni

musisz zakładać, że danych nie będzie można normalnie usunąć przez 365 dni.

Retencja konkretnego obiektu¶

Object Lock może być ustawiony również dla konkretnego obiektu.

Przykład:

aws s3api put-object-retention \
  --bucket immutable-backup \
  --key backup01.vbk \
  --retention Mode=GOVERNANCE,RetainUntilDate=2026-12-31T23:59:59Z \
  --profile cloud4you

Sprawdzenie:

aws s3api get-object-retention \
  --bucket immutable-backup \
  --key backup01.vbk \
  --profile cloud4you

Jeżeli używasz versioningu, możesz wskazać konkretną wersję:

--version-id VERSION_ID

Legal Hold¶

Legal Hold blokuje usunięcie obiektu niezależnie od daty retencji.

Włączenie:

aws s3api put-object-legal-hold \
  --bucket immutable-backup \
  --key backup01.vbk \
  --legal-hold Status=ON \
  --profile cloud4you

Sprawdzenie:

aws s3api get-object-legal-hold \
  --bucket immutable-backup \
  --key backup01.vbk \
  --profile cloud4you

Wyłączenie:

aws s3api put-object-legal-hold \
  --bucket immutable-backup \
  --key backup01.vbk \
  --legal-hold Status=OFF \
  --profile cloud4you

Tagi bucketa¶

Dodanie tagów¶

Utwórz plik:

bucket-tags.json

Zawartość:

{
  "TagSet": [
    {
      "Key": "project",
      "Value": "backup"
    },
    {
      "Key": "environment",
      "Value": "production"
    }
  ]
}

Zapisz:

aws s3api put-bucket-tagging \
  --bucket backup-firma-01 \
  --tagging file://bucket-tags.json \
  --profile cloud4you

Odczyt tagów bucketa¶

aws s3api get-bucket-tagging \
  --bucket backup-firma-01 \
  --profile cloud4you

Usunięcie tagów bucketa¶

aws s3api delete-bucket-tagging \
  --bucket backup-firma-01 \
  --profile cloud4you

Tagi obiektu¶

Dodanie tagów do pliku¶

aws s3api put-object-tagging \
  --bucket backup-firma-01 \
  --key dokumenty/faktura.pdf \
  --tagging 'TagSet=[{Key=typ,Value=faktura},{Key=rok,Value=2026}]' \
  --profile cloud4you

Odczyt tagów obiektu¶

aws s3api get-object-tagging \
  --bucket backup-firma-01 \
  --key dokumenty/faktura.pdf \
  --profile cloud4you

Usunięcie tagów obiektu¶

aws s3api delete-object-tagging \
  --bucket backup-firma-01 \
  --key dokumenty/faktura.pdf \
  --profile cloud4you

Lifecycle¶

Lifecycle pozwala automatycznie wykonywać operacje na obiektach po określonym czasie.

Przykład:

usuń zawartość tmp/ po 30 dniach

Przykład reguły¶

Utwórz:

lifecycle.json

Zawartość:

{
  "Rules": [
    {
      "ID": "delete-temp-after-30-days",
      "Status": "Enabled",
      "Filter": {
        "Prefix": "tmp/"
      },
      "Expiration": {
        "Days": 30
      }
    }
  ]
}

Zapisz:

aws s3api put-bucket-lifecycle-configuration \
  --bucket backup-firma-01 \
  --lifecycle-configuration file://lifecycle.json \
  --profile cloud4you

Sprawdzenie lifecycle¶

aws s3api get-bucket-lifecycle-configuration \
  --bucket backup-firma-01 \
  --profile cloud4you

Usunięcie lifecycle¶

aws s3api delete-bucket-lifecycle \
  --bucket backup-firma-01 \
  --profile cloud4you

Lifecycle wykonuje operacje automatycznie.

Nie ustawiaj reguł usuwających dane bez sprawdzenia:

bucketa,
prefiksu,
liczby dni,
wpływu na versioning.

Bucket Policy¶

Bucket Policy pozwala definiować reguły dostępu do bucketa i obiektów.

Ceph RGW Squid obsługuje podzbiór języka Amazon S3 Bucket Policy.

Oznacza to:

nie kopiuj losowej polityki z dokumentacji AWS i nie zakładaj, że wszystkie elementy będą działały identycznie.

Odczyt Bucket Policy¶

aws s3api get-bucket-policy \
  --bucket backup-firma-01 \
  --profile cloud4you

Zapis Bucket Policy¶

Załóżmy, że prawidłowa polityka znajduje się w:

policy.json

Zastosuj:

aws s3api put-bucket-policy \
  --bucket backup-firma-01 \
  --policy file://policy.json \
  --profile cloud4you

Usunięcie Bucket Policy¶

aws s3api delete-bucket-policy \
  --bucket backup-firma-01 \
  --profile cloud4you

Ważne przy Bucket Policy¶

Błędna polityka może:

zablokować dostęp do danych,
nadać zbyt szeroki dostęp,
udostępnić dane użytkownikowi, który nie powinien ich widzieć.

Jeżeli nie wiesz, co robi dany dokument JSON:

nie stosuj go metodą prób i błędów na produkcyjnym buckecie.

Multipart Upload¶

Multipart Upload dzieli duży plik na części.

Jest używany po to, aby:

sprawniej wysyłać duże pliki,
wysyłać części równolegle,
ponowić tylko część transferu zamiast całego pliku.

Ceph RGW obsługuje S3 Multipart Upload.

Czy trzeba robić multipart ręcznie¶

Najczęściej:

nie.

Polecenia:

aws s3 cp
aws s3 sync

same obsługują multipart dla większych plików.

Ręczne używanie s3api jest potrzebne głównie przy własnych aplikacjach lub diagnostyce.

Lista niedokończonych multipart uploadów¶

aws s3api list-multipart-uploads \
  --bucket backup-firma-01 \
  --profile cloud4you

Przerwanie niedokończonego multipart uploadu¶

Najpierw pobierz UploadId:

aws s3api list-multipart-uploads \
  --bucket backup-firma-01 \
  --profile cloud4you

Następnie:

aws s3api abort-multipart-upload \
  --bucket backup-firma-01 \
  --key duzy-plik.bin \
  --upload-id UPLOAD_ID \
  --profile cloud4you

Przerwanie multipart uploadu usuwa niedokończony upload, a nie prawidłowo ukończony obiekt.

Wydajność transferów¶

AWS CLI pozwala zmieniać ustawienia transferu.

W większości przypadków:

najpierw użyj ustawień domyślnych.

Nie zmieniaj parametrów tylko dlatego, że „większa liczba wygląda szybciej”.

Liczba równoległych requestów¶

Przykład:

aws configure set s3.max_concurrent_requests 20 \
  --profile cloud4you

Więcej równoległych requestów może zwiększyć wydajność, ale może też:

zwiększyć obciążenie komputera,
zwiększyć wykorzystanie łącza,
pogorszyć pracę na wolnym połączeniu.

Próg multipart¶

Przykład:

aws configure set s3.multipart_threshold 64MB \
  --profile cloud4you

Rozmiar części multipart¶

aws configure set s3.multipart_chunksize 16MB \
  --profile cloud4you

Ograniczenie przepustowości¶

Przykład ograniczenia do około 50 MB/s:

aws configure set s3.max_bandwidth 50MB/s \
  --profile cloud4you

Filtrowanie plików¶

AWS CLI obsługuje:

--exclude
--include

Przykład wysłania tylko plików .jpg:

aws s3 cp ./zdjecia/ s3://backup-firma-01/zdjecia/ \
  --recursive \
  --exclude "*" \
  --include "*.jpg" \
  --profile cloud4you

Najpierw wykluczamy wszystko:

--exclude "*"

a następnie dodajemy interesujący nas typ:

--include "*.jpg"

Używanie AWS CLI w skryptach¶

Profil można ustawić zmienną środowiskową.

Linux / macOS:

export AWS_PROFILE=cloud4you

PowerShell:

$Env:AWS_PROFILE="cloud4you"

Wtedy zamiast:

aws s3 ls --profile cloud4you

możesz użyć:

aws s3 ls

Endpoint jako zmienna środowiskowa¶

AWS CLI obsługuje również zmienną:

Linux / macOS:

export AWS_ENDPOINT_URL_S3=https://s3.cloud4you.pl

PowerShell:

$Env:AWS_ENDPOINT_URL_S3="https://s3.cloud4you.pl"

Jeżeli endpoint jest już zapisany w profilu, nie musisz tego robić.

Podstawy S3 REST API¶

AWS CLI jest tylko klientem API.

Pod spodem wykonywane są zapytania HTTP do:

https://s3.cloud4you.pl

Przykładowe operacje S3 wyglądają logicznie tak:

Operacja	Metoda
lista bucketów	`GET /`
utworzenie bucketa	`PUT /bucket`
usunięcie bucketa	`DELETE /bucket`
lista obiektów	`GET /bucket?list-type=2`
upload obiektu	`PUT /bucket/obiekt`
pobranie obiektu	`GET /bucket/obiekt`
informacje o obiekcie	`HEAD /bucket/obiekt`
usunięcie obiektu	`DELETE /bucket/obiekt`

Żądania prywatne muszą być podpisane.

Cloud4You OCS obsługuje standardowe podpisy AWS używane przez klientów S3, w tym AWS Signature Version 4.

Nie zalecamy ręcznego budowania podpisu SigV4.

W aplikacji użyj:

AWS SDK,
biblioteki zgodnej z S3,
AWS CLI.

Parametry dla aplikacji S3¶

Jeżeli aplikacja pyta o konfigurację S3, najczęściej wpisz:

Endpoint:
https://s3.cloud4you.pl

Region:
eu-pl-1

Access Key ID:
TWÓJ_ACCESS_KEY

Secret Access Key:
TWÓJ_SECRET_KEY

Jeżeli aplikacja pyta o styl adresowania, wybierz:

Path Style

lub:

Force Path Style = Enabled

Nazwy tej opcji różnią się między aplikacjami.

Najczęstsze błędy¶

`InvalidAccessKeyId`¶

Najczęściej:

błędny Access Key ID

Sprawdź profil:

aws configure list --profile cloud4you

`SignatureDoesNotMatch`¶

Najczęstsze przyczyny:

błędny Secret Access Key,
błędny region,
niewłaściwy endpoint,
zła data lub godzina na komputerze.

Sprawdź:

Endpoint: https://s3.cloud4you.pl
Region:   eu-pl-1

Na Linuxie:

timedatectl

`AccessDenied`¶

Połączenie działa, ale klucz nie ma uprawnień do wykonania operacji.

Przykład:

możesz czytać pliki
ale nie możesz tworzyć bucketów

To nie jest problem z AWS CLI.

To problem z uprawnieniami użytego klucza.

`NoSuchBucket`¶

Wskazany bucket nie istnieje albo używasz złej nazwy.

Sprawdź:

aws s3 ls --profile cloud4you

`NoSuchKey`¶

Bucket istnieje, ale wskazany obiekt nie istnieje.

Sprawdź:

aws s3 ls s3://NAZWA-BUCKETA/ \
  --recursive \
  --profile cloud4you

`BucketAlreadyExists`¶

Bucket o tej nazwie już istnieje.

Wybierz inną nazwę.

`BucketNotEmpty`¶

Próbujesz usunąć bucket, który nadal zawiera obiekty lub wersje.

Sprawdź:

aws s3 ls s3://NAZWA-BUCKETA/ \
  --recursive \
  --profile cloud4you

Jeżeli bucket ma versioning, sprawdź również:

aws s3api list-object-versions \
  --bucket NAZWA-BUCKETA \
  --profile cloud4you

`InvalidBucketState`¶

Może pojawić się przy zmianach związanych z Object Lock.

W Cloud4You OCS Object Lock powinien być przewidziany przy tworzeniu bucketa.

AWS CLI próbuje używać endpointu Amazon¶

Sprawdź:

~/.aws/config

lub na Windows:

%USERPROFILE%\.aws\config

Profil powinien zawierać konfigurację usługi:

[profile cloud4you]
region = eu-pl-1
output = json
services = cloud4you-ocs

s3 =
  addressing_style = path

[services cloud4you-ocs]
s3 =
  endpoint_url = https://s3.cloud4you.pl

Polecenie działa tylko z `--endpoint-url`¶

Jeżeli:

aws s3 ls \
  --endpoint-url https://s3.cloud4you.pl \
  --profile cloud4you

działa, ale:

aws s3 ls --profile cloud4you

nie działa, oznacza to najczęściej, że endpoint nie został poprawnie zapisany w pliku config.

Diagnostyka¶

Włączenie debugowania¶

aws s3 ls \
  --profile cloud4you \
  --debug

AWS CLI pokaże dużo informacji diagnostycznych.

Uwaga: przed wysłaniem logu do pomocy technicznej sprawdź, czy nie zawiera danych, których nie chcesz udostępniać.

Zapis debugowania do pliku¶

Linux / macOS:

aws s3 ls \
  --profile cloud4you \
  --debug 2> aws-debug.txt

Bezpieczeństwo¶

Secret Access Key¶

Secret Access Key traktuj jak hasło.

Nie:

wysyłaj go mailem
wklejaj do ticketu
umieszczaj na screenie
wrzucaj do Git
zapisuj w publicznym skrypcie

Pre-signed URL¶

Pre-signed URL nie pokazuje Secret Access Key.

Pozwala jednak uzyskać dostęp do obiektu przez określony czas.

Dlatego:

aktywny pre-signed URL traktuj jak tymczasowy dostęp do pliku.

Operacje usuwające¶

Szczególnie uważaj na:

aws s3 rm --recursive
aws s3 sync --delete
aws s3 rb
aws s3api delete-object
aws s3api delete-bucket

Przed wykonaniem sprawdź polecenie.

Jeżeli jest dostępne --dryrun, użyj go przed operacją masową.

Object Lock¶

Object Lock jest specjalnie zaprojektowany tak, żeby utrudnić usunięcie danych.

To jego zadanie.

Jeżeli ustawisz długą retencję w trybie COMPLIANCE, nie zakładaj, że administrator „po prostu ją zdejmie”.

Ściąga¶

Sprawdzenie połączenia¶

aws s3 ls --profile cloud4you

Utworzenie bucketa¶

aws s3 mb s3://NAZWA-BUCKETA \
  --region eu-pl-1 \
  --profile cloud4you

Lista plików¶

aws s3 ls s3://NAZWA-BUCKETA/ \
  --profile cloud4you

Upload¶

aws s3 cp plik.txt s3://NAZWA-BUCKETA/ \
  --profile cloud4you

Download¶

aws s3 cp s3://NAZWA-BUCKETA/plik.txt ./plik.txt \
  --profile cloud4you

Synchronizacja¶

aws s3 sync ./dane/ s3://NAZWA-BUCKETA/dane/ \
  --profile cloud4you

Usunięcie pliku¶

aws s3 rm s3://NAZWA-BUCKETA/plik.txt \
  --profile cloud4you

Versioning¶

aws s3api put-bucket-versioning \
  --bucket NAZWA-BUCKETA \
  --versioning-configuration Status=Enabled \
  --profile cloud4you

CORS¶

aws s3api get-bucket-cors \
  --bucket NAZWA-BUCKETA \
  --profile cloud4you

Object Lock¶

aws s3api get-object-lock-configuration \
  --bucket NAZWA-BUCKETA \
  --profile cloud4you

Pre-signed URL¶

aws s3 presign s3://NAZWA-BUCKETA/plik.txt \
  --expires-in 3600 \
  --region eu-pl-1 \
  --profile cloud4you

Pomoc¶

Dokumentacja Cloud4You:

Otwórz dokumentację

Portal pomocy:

Otwórz Support

Cloud4You OCS – AWS CLI i S3 API¶

Najważniejsze dane¶

Co oznacza zgodność z S3¶

AWS CLI i s3api – jaka jest różnica¶

aws s3¶

aws s3api¶

Instalacja AWS CLI¶

Windows¶

Linux¶

macOS¶

Konfiguracja danych dostępowych¶

Gdzie zapisują się klucze¶

Stałe ustawienie endpointu Cloud4You¶

Dlaczego używamy addressing_style = path¶

Test konfiguracji¶

Sprawdzenie profilu¶

Podstawowe polecenia aws s3¶

Lista bucketów¶

Utworzenie bucketu¶

Lista plików w buckecie¶

Lista wszystkich plików również w podfolderach¶

Wysłanie jednego pliku¶

Wysłanie pliku pod inną nazwą¶

Wysłanie pliku do folderu¶

Wysłanie całego katalogu¶

Synchronizacja katalogu¶

Synchronizacja z usuwaniem¶

Pobranie jednego pliku¶

Pobranie całego katalogu¶

Kopiowanie obiektu między bucketami¶

Przenoszenie obiektu¶

Usunięcie jednego obiektu¶

Usunięcie całej ścieżki¶

Usunięcie pustego bucketa¶

Wygenerowanie czasowego linku¶

Polecenia aws s3api¶

Lista bucketów przez API¶

Utworzenie bucketu przez API¶

Sprawdzenie, czy bucket istnieje i jest dostępny¶

Lista obiektów przez API¶

Informacje o obiekcie¶

Wysłanie obiektu przez s3api¶

Pobranie obiektu przez s3api¶

Usunięcie obiektu przez API¶

Kopiowanie obiektu przez API¶

Versioning¶

Co robi versioning¶

Sprawdzenie versioningu¶

Włączenie versioningu¶

Wstrzymanie versioningu¶

Lista wersji obiektów¶

Usunięcie konkretnej wersji¶

CORS¶

Co robi CORS¶

Sprawdzenie CORS¶

Konfiguracja CORS dla OCS Browser¶

Usunięcie konfiguracji CORS¶

Object Lock¶

Co robi Object Lock¶

Ważne przed utworzeniem bucketa¶

Utworzenie bucketa z Object Lock¶

Sprawdzenie Object Lock¶

Domyślna retencja Object Lock¶

GOVERNANCE a COMPLIANCE¶

GOVERNANCE¶

COMPLIANCE¶

Retencja konkretnego obiektu¶

Legal Hold¶

Tagi bucketa¶

Dodanie tagów¶

Odczyt tagów bucketa¶

Usunięcie tagów bucketa¶

Tagi obiektu¶

Dodanie tagów do pliku¶

Odczyt tagów obiektu¶

Usunięcie tagów obiektu¶

Lifecycle¶

Przykład reguły¶

Sprawdzenie lifecycle¶

Usunięcie lifecycle¶

`aws s3`¶

`aws s3api`¶

Dlaczego używamy `addressing_style = path`¶

Podstawowe polecenia `aws s3`¶

Polecenia `aws s3api`¶

Wysłanie obiektu przez `s3api`¶

Pobranie obiektu przez `s3api`¶

`InvalidAccessKeyId`¶

`SignatureDoesNotMatch`¶

`AccessDenied`¶

`NoSuchBucket`¶

`NoSuchKey`¶

`BucketAlreadyExists`¶

`BucketNotEmpty`¶

`InvalidBucketState`¶

Polecenie działa tylko z `--endpoint-url`¶