AWS CLI¶

AWS CLI jest wygodnym narzędziem do obsługi Cloud4You Object Storage S3 z poziomu terminala.

Za jego pomocą możesz między innymi:

sprawdzić połączenie z usługą,
wyświetlać i tworzyć buckety,
przesyłać i pobierać pliki,
synchronizować katalogi,
zarządzać versioningiem,
wykonywać operacje administracyjne na obiektach.

Parametry Cloud4You Object Storage S3¶

W przykładach na tej stronie używamy:

Endpoint:
https://s3.cloud4you.pl

Region:
eu-pl-1

Profil AWS CLI:
cloud4you

Instalacja AWS CLI¶

Windows¶

Po instalacji AWS CLI uruchom PowerShell lub Windows Terminal.

Sprawdź wersję:

aws --version

Przykładowy wynik:

aws-cli/2.x.x Python/3.x.x Windows/...

macOS¶

Jeżeli korzystasz z Homebrew:

brew install awscli

Następnie:

aws --version

Linux¶

Po zainstalowaniu AWS CLI sprawdź:

aws --version

Zalecamy AWS CLI v2

Jeżeli masz możliwość wyboru wersji, zalecamy korzystanie z aktualnej wersji AWS CLI v2.

Utworzenie profilu Cloud4You¶

Uruchom:

aws configure --profile cloud4you

Podaj otrzymane dane:

AWS Access Key ID:
<Access Key>

AWS Secret Access Key:
<Secret Key>

Default region name:
eu-pl-1

Default output format:
json

Po zapisaniu możesz używać profilu:

cloud4you

Sprawdzenie konfiguracji profilu¶

aws configure list --profile cloud4you

Polecenie pokaże między innymi:

źródło Access Key,
źródło Secret Key,
skonfigurowany region.

AWS CLI nie zapisuje endpointu w poleceniu aws configure

Przy korzystaniu z Cloud4You w przykładach dodajemy:

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

Pierwszy test połączenia¶

Wyświetl listę bucketów:

aws \
  --profile cloud4you \
  --endpoint-url https://s3.cloud4you.pl \
  --region eu-pl-1 \
  s3api list-buckets

Jeżeli konto nie posiada jeszcze bucketów, wynik może wyglądać tak:

{
  "Buckets": []
}

Pusta lista to poprawny wynik

Buckets: [] oznacza, że uwierzytelnienie działa, ale użytkownik nie posiada jeszcze żadnego bucketa.

Tworzenie bucketa¶

Przykład:

aws \
  --profile cloud4you \
  --endpoint-url https://s3.cloud4you.pl \
  --region eu-pl-1 \
  s3api create-bucket \
  --bucket firma-backup \
  --create-bucket-configuration LocationConstraint=eu-pl-1

Zastąp:

firma-backup

własną nazwą bucketa.

Lista bucketów¶

Wersja czytelna:

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

Wersja API zwracająca JSON:

aws \
  --profile cloud4you \
  --endpoint-url https://s3.cloud4you.pl \
  s3api list-buckets

Lista obiektów w buckecie¶

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

Rekurencyjnie:

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

Wysłanie pliku¶

aws \
  --profile cloud4you \
  --endpoint-url https://s3.cloud4you.pl \
  s3 cp plik.zip s3://firma-backup/

Możesz również wskazać nazwę obiektu:

aws \
  --profile cloud4you \
  --endpoint-url https://s3.cloud4you.pl \
  s3 cp plik.zip s3://firma-backup/archiwum/plik.zip

Pobranie pliku¶

aws \
  --profile cloud4you \
  --endpoint-url https://s3.cloud4you.pl \
  s3 cp s3://firma-backup/plik.zip .

Pobranie pod inną nazwą:

aws \
  --profile cloud4you \
  --endpoint-url https://s3.cloud4you.pl \
  s3 cp s3://firma-backup/plik.zip ./plik-pobrany.zip

Kopiowanie katalogu do S3¶

aws \
  --profile cloud4you \
  --endpoint-url https://s3.cloud4you.pl \
  s3 cp ./dane/ s3://firma-backup/dane/ --recursive

Pobieranie katalogu z S3¶

aws \
  --profile cloud4you \
  --endpoint-url https://s3.cloud4you.pl \
  s3 cp s3://firma-backup/dane/ ./dane/ --recursive

Synchronizacja katalogu do S3¶

aws \
  --profile cloud4you \
  --endpoint-url https://s3.cloud4you.pl \
  s3 sync ./dane/ s3://firma-backup/dane/

AWS CLI porówna źródło i cel i prześle brakujące lub zmienione pliki.

Synchronizacja z S3 na komputer¶

aws \
  --profile cloud4you \
  --endpoint-url https://s3.cloud4you.pl \
  s3 sync s3://firma-backup/dane/ ./dane/

Synchronizacja z opcją --delete¶

Możliwe jest usuwanie z miejsca docelowego obiektów, których nie ma już w źródle:

aws \
  --profile cloud4you \
  --endpoint-url https://s3.cloud4you.pl \
  s3 sync ./dane/ s3://firma-backup/dane/ --delete

Uważaj na --delete

Opcja --delete może usunąć dane z miejsca docelowego.

Przed jej użyciem zawsze sprawdź:

kierunek synchronizacji,
nazwę bucketa,
wskazany prefiks,
lokalny katalog źródłowy.

Test synchronizacji bez zmian¶

Przed większą synchronizacją warto użyć:

aws \
  --profile cloud4you \
  --endpoint-url https://s3.cloud4you.pl \
  s3 sync ./dane/ s3://firma-backup/dane/ --dryrun

--dryrun pokazuje planowane operacje bez ich wykonywania.

Używaj --dryrun

Szczególnie zalecamy --dryrun przed pierwszym użyciem sync oraz przed użyciem opcji --delete.

Usunięcie pojedynczego obiektu¶

aws \
  --profile cloud4you \
  --endpoint-url https://s3.cloud4you.pl \
  s3 rm s3://firma-backup/plik.zip

Usunięcie wielu obiektów¶

Przykład usunięcia całego prefiksu:

aws \
  --profile cloud4you \
  --endpoint-url https://s3.cloud4you.pl \
  s3 rm s3://firma-backup/test/ --recursive

Operacja destrukcyjna

s3 rm --recursive może usunąć dużą liczbę obiektów.

Przed wykonaniem polecenia dokładnie sprawdź ścieżkę.

Usunięcie pustego bucketa¶

aws \
  --profile cloud4you \
  --endpoint-url https://s3.cloud4you.pl \
  s3api delete-bucket \
  --bucket firma-backup

Bucket musi być pusty.

Informacje o obiekcie¶

aws \
  --profile cloud4you \
  --endpoint-url https://s3.cloud4you.pl \
  s3api head-object \
  --bucket firma-backup \
  --key plik.zip

Polecenie może zwrócić między innymi:

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

Sprawdzenie dostępu do bucketa¶

aws \
  --profile cloud4you \
  --endpoint-url https://s3.cloud4you.pl \
  s3api head-bucket \
  --bucket firma-backup

Jeżeli polecenie kończy się bez błędu, bucket istnieje i użytkownik posiada wymagany dostęp do tej operacji.

Versioning¶

Włączenie:

aws \
  --profile cloud4you \
  --endpoint-url https://s3.cloud4you.pl \
  s3api put-bucket-versioning \
  --bucket firma-backup \
  --versioning-configuration Status=Enabled

Sprawdzenie:

aws \
  --profile cloud4you \
  --endpoint-url https://s3.cloud4you.pl \
  s3api get-bucket-versioning \
  --bucket firma-backup

Lista wersji:

aws \
  --profile cloud4you \
  --endpoint-url https://s3.cloud4you.pl \
  s3api list-object-versions \
  --bucket firma-backup

Więcej informacji znajdziesz w sekcji Wersjonowanie obiektów.

Wybór formatu odpowiedzi¶

AWS CLI może zwracać dane w różnych formatach.

JSON:

aws \
  --profile cloud4you \
  --endpoint-url https://s3.cloud4you.pl \
  --output json \
  s3api list-buckets

Tabela:

aws \
  --profile cloud4you \
  --endpoint-url https://s3.cloud4you.pl \
  --output table \
  s3api list-buckets

Tekst:

aws \
  --profile cloud4you \
  --endpoint-url https://s3.cloud4you.pl \
  --output text \
  s3api list-buckets

Tryb debug¶

Jeżeli polecenie nie działa i potrzebujesz dokładniejszych informacji:

aws \
  --profile cloud4you \
  --endpoint-url https://s3.cloud4you.pl \
  s3api list-buckets \
  --debug

Logi debug mogą zawierać informacje techniczne

Przed przesłaniem pełnego logu osobie trzeciej sprawdź jego zawartość.

Nie publikuj Secret Key ani innych danych poufnych.

Najczęstsze problemy¶

InvalidAccessKeyId¶

Sprawdź:

aws configure list --profile cloud4you

Upewnij się, że korzystasz z właściwego profilu.

SignatureDoesNotMatch¶

Sprawdź:

Secret Key,
region eu-pl-1,
endpoint,
datę i godzinę systemową.

AccessDenied¶

Użytkownik może nie posiadać uprawnień do wskazanej operacji lub zasobu.

Could not connect to the endpoint URL¶

Sprawdź:

https://s3.cloud4you.pl

oraz połączenie sieciowe i DNS.

Skracanie poleceń¶

W dokumentacji celowo pokazujemy pełne polecenia zawierające:

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

Dzięki temu dokładnie widać, z którego profilu i endpointu korzysta polecenie.

W skryptach możesz przechowywać te wartości w zmiennych, ale pamiętaj, aby nie zapisywać Secret Key bezpośrednio w kodzie.

Ścieżki konfiguracji AWS CLI¶

Linux i macOS¶

Standardowo:

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

Windows¶

Standardowo pliki znajdują się w katalogu profilu użytkownika:

%UserProfile%\.aws\

Najczęściej używane polecenia¶

Lista bucketów:

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

Lista zawartości:

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

Upload:

aws \
  --profile cloud4you \
  --endpoint-url https://s3.cloud4you.pl \
  s3 cp plik.zip s3://firma-backup/

Download:

aws \
  --profile cloud4you \
  --endpoint-url https://s3.cloud4you.pl \
  s3 cp s3://firma-backup/plik.zip .

Synchronizacja:

aws \
  --profile cloud4you \
  --endpoint-url https://s3.cloud4you.pl \
  s3 sync ./dane/ s3://firma-backup/dane/

Usunięcie:

aws \
  --profile cloud4you \
  --endpoint-url https://s3.cloud4you.pl \
  s3 rm s3://firma-backup/plik.zip