AWS CLI
Autor: Piotr Karpiuk o poniedziałek 12. Styczeń 2015
AWS CLI
Wstęp
AWS CLI to interfejs wiersza poleceń do usług chmury Amazonu (Amazon Web Services, AWS). Dzięki niemu można wykonywać działania w chmurze z poziomu skryptów wiersza poleceń (Linux Bash lub Windows PowerShell). Implementacyjnie jest to skrypt Pythona, który komunikuje się z chmurą za pomocą HTTPS na porcie 443.
Instalacja
Zainstalować można na kilka sposobów:
- z repozytorium pakietów Linuksa, np.
apt-get install awscli
w Ubuntu, lub jako instalator MSI w Windows (wersja 32- lub 64-bitowa)
- za pomocą systemu pakietów Pythona, o nazwie pip: po zainstalowaniu Pythona 2.7+ lub 3.4+ oraz pip, wydajemy (z roota) polecenie:
pip install awscli
ewentualny upgrade wykonuje się poleceniem
pip install --upgrade awscli
- wykonując polecenia (Linux):
curl "https://s3.amazonaws.com/aws-cli/awscli-bundle.zip" -o "awscli-bundle.zip" unzip awscli-bundle.zip sudo ./awscli-bundle/install -i /usr/local/aws -b /usr/local/bin/aws
Aby sprawdzić czy instalacja przebiegła poprawnie najprościej wykonać polecenie aws --version
lub aws help
.
Dodatkowo pod Linuksem można sobie uprzyjemnić pracę włączając autokompletowanie poleceń pod klawiszem TAB:
complete -C `which aws_completer` aws
Konfiguracja
Konfiguracja sprowadza się do wprowadzenia danych: Access Key ID i Secret Access Key, pobranych z konsoli administracyjnej AWS w przeglądarce. Dodatkowo określa się dwa parametry domyślne: region AWS oraz format wyniku polecenia. Można je przedefiniować w opcjach konkretnego polecenia (--region
i --output
), a region również w zmiennej środowiskowej AWS_DEFAULT_REGION
.
$ aws configure AWS Access Key ID [None]: AKIAIOSFODNN7EXAMPLE AWS Secret Access Key [None]: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY Default region name [None]: us-west-2 Default output format [None]: json
Format wynikowy to może być json
(do przetwarzania wyniku programistycznie lub za pomocą procesora jq), text
(do przetwarzania przez narzędzia typu sed
, grep
lub awk
), lub table
(czytelne dla ludzi).
Podane tu dane są przechowywane w plikach ~/.aws/credentials
(klucze) i ~/.aws/config
(domyślny region i format wynikowy).
I już możemy wykonać pierwsze polecenie AWS, opisujące nasze działające instancje w wybranym regionie:
$ aws ec2 describe-instances --output table --region us-east-1
Uwaga: Tutaj opisano konfigurację AWS CLI na komputerze znajdującym się poza chmurą (np. na prywatnym laptopie). Nieco inaczej wygląda konfiguracja na instancji EC2. Tutaj przede wszystkim instancja musi mieć przypisaną rolę z dostępem do zasobów na których chce działać (patrz dokument AWS Identity and Access Management). Po wydaniu polecenia aws configure
wprowadzamy puste pola kluczy — klucze zostaną automatycznie pobrane z metadanych instancji.
Przykład: uruchamianie nowej instancji
Po pierwsze, trzeba utworzyć grupę zabezpieczeń (ang. security group), czyli odpowiednik prostego firewalla. Dodamy do niej regułę pozwalającą na dostęp do instancji przez SSH (port 22) z dowolnego miejsca na świecie:
$ aws ec2 create-security-group --group-name devenv-sg --description "security group for development environment in EC2" $ aws ec2 authorize-security-group-ingress --group-name devenv-sg --protocol tcp --port 22 --cidr 0.0.0.0/0
Poleceniem ec2-describe-security-groups
możemy pozyskać informacje o aktualnych grupach bezpieczeństwa.
Kolejnym krokiem jest utworzenie klucza do połączenia się z instancją za pomocą SSH:
$ aws ec2 create-key-pair --key-name devenv-key --query 'KeyMaterial' --output text > devenv-key.pem $ chmod 400 devenv-key.pem
Teraz możemy już wykonać polecenie uruchomienia instancji, przy czym potrzebujemy jeszcze identyfikatora obrazu systemu operajnego (AMI). Wybierzmy obraz ami-29ebb519
(Ubuntu). Uruchomimy go na jednej z najsłabszych (i najtańszych) maszyn wirtualnych t2.micro
(listę wszystkich typów instancji możemy znaleźć np. na ec2instances.info). Polecenie run-instances
uruchamia instancję i zwraca JSONa opisującego uruchomioną instancję; parametr --query
na tym JSONie wykonać zapytanie i zwraca jego wynik(patrz JMESPath). Poniższe polecenie zwraca identyfikator uruchomionej instancji:
$ aws ec2 run-instances --image-id ami-29ebb519 --count 1 --instance-type t2.micro --key-name devenv-key \ --security-groups devenv-sg --query 'Instances[0].InstanceId' "i-ec3e1e2k"
Uruchamianie chwilę potrwa (być może parę minut). Gdy już się uruchomi, możemy użyć polecenia describe-instances
aby ustalić adres IP:
$ aws ec2 describe-instances --instance-ids i-ec3e1e2k --query 'Reservations[0].Instances[0].PublicIpAddress' "54.183.22.255"
Teraz możemy już się połączyć z instancją:
$ ssh -i devenv-key.pem ubuntu@54.183.22.255
Dla Ubuntu nazwą użytkownika będzie ubuntu
. Dla Fedory byłoby to fedora
lub ec2-user
, dla SuSe root
. Ogólnie nazwa użytkownika na który należy się łączyć zależy od dostawcy obrazu systemu operacyjnego.
Lista działających instancji typu m1.small
:
aws ec2 describe-instances --filters "Name=instance-type,Values=m1.small"
Terminacja (zwolnienie) instancji:
aws ec2 terminate-instances --instance-ids i-ec3e1e2k
Sposób użycia
Ogólna postać polecenia AWS CLI jest następująca:
$ aws [command] [subcommand] [parameters]
Na ogół command
to nazwa usługi AWS (np. ec2
w przypadku instancji, s3
dla S3, itd.), przy wprowadzaniu subcommand
warto posługiwać się klawiszem TAB, o ile włączyliśmy autokompletację (patrz wyżej).
Subcommands odpowiadają akcjom API poszczególnych usług AWS. Każda usługa ma dokumentację (ang. reference documentation), w której opisano szczegółowo wszystkie możliwe akcje wraz z parameterami, a także typy danych, możliwe komunikaty błędów itp. Patrz AWS Documentation.
Uzyskiwanie pomocy
Pomoc możemy uzyskać na trzech poziomach: głównym, usługi lub konkretnego polecenia usługi:
$ aws help $ aws ec2 help $ aws ec2 describe-instances help
Typy parametrów
W pomocy, opisie parametrów poleceń w nawiasach podawane są typy parametrów. Oprócz trywialnych typów takich jak String czy Integer mamy:
- Timestamp
- Akceptowane formaty:
2014-10-29T20:30:00.000Z 2014-10-29T12:30:00.000-08:00 2014-10-29 20141029
- List
- lista łańcuchów rozdzielonych spacjami
- Boolean
- brak takiej opcji oznacza 0, a wystąpienie 1. Na przykład opcja
--dry-run
. - Blob
- ścieżka do lokalnego pliku, np.
/tmp/image.png
- Map
- JSON, np.
'{"id": {"N": "1"}}'
lub tzw. shorthand syntax (patrz niżej).
Aby niezależnie od typu załadować wartość parametru z pliku, należy użyć URLa z przedrostkiem file://
(wspierane są skróty takie jak ~/
, ./
i ../
) lub http://
czy nawet https://
.
Dla parametrów pobierających dane binarne należy użyć prefiksu fileb://
(np. klucze do szyfrowania).
Shorthand syntax
Shorthand syntax służy do wyrażania niezagnieżdżonych struktur, np. zamiast pisać:
--option '[value1,value2,value3]'
można tak:
--option value1 value2 value3
Z kolei zamiast:
--tags '[ {"Key": "My1stTag", "Value": "Value1" }, {"Key": "My2ndTag", "Value": "Value2" }, {"Key": "My3rdTag", "Value": "Value3" } ]'
można tak:
--tags Key=My1stTag,Value=Value1 Key=My2ndTag,Value=Value2 Key=My3rdTag,Value=Value3
Szkielety
Większość poleceń AWS CLI wspiera parametry --generate-cli-skeleton
i --cli-input-json
które służą odpowiednio do zapisywania parametrów w postaci JSONa i wczytywania ich z pliku zamiast wprowadzania pojedynczych parametrów w wierszu poleceń.
Wykonaj polecenie, które wygeneruje szkielet:
$ aws ec2 run-instances --generate-cli-skeleton > ec2runinst.json
$ cat ec2runinst.json
{
"DryRun": true,
"ImageId": "",
"MinCount": 0,
"MaxCount": 0,
"KeyName": "",
"SecurityGroups": [
""
],
"SecurityGroupIds": [
""
],
"UserData": "",
"InstanceType": "",
"Placement": {
"AvailabilityZone": "",
"GroupName": "",
"Tenancy": ""
},
"KernelId": "",
"RamdiskId": "",
"BlockDeviceMappings": [
{
"VirtualName": "",
"DeviceName": "",
"Ebs": {
"SnapshotId": "",
"VolumeSize": 0,
"DeleteOnTermination": true,
"VolumeType": "",
"Iops": 0,
"Encrypted": true
},
"NoDevice": ""
}
],
"Monitoring": {
"Enabled": true
},
"SubnetId": "",
"DisableApiTermination": true,
"InstanceInitiatedShutdownBehavior": "",
"PrivateIpAddress": "",
"ClientToken": "",
"AdditionalInfo": "",
"NetworkInterfaces": [
{
"NetworkInterfaceId": "",
"DeviceIndex": 0,
"SubnetId": "",
"Description": "",
"PrivateIpAddress": "",
"Groups": [
""
],
"DeleteOnTermination": true,
"PrivateIpAddresses": [
{
"PrivateIpAddress": "",
"Primary": true
}
],
"SecondaryPrivateIpAddressCount": 0,
"AssociatePublicIpAddress": true
}
],
"IamInstanceProfile": {
"Arn": "",
"Name": ""
},
"EbsOptimized": true
}
Otwórz sobie plik ze szkieletem i dowolnie przeedytuj parametry, np. usuń te których nie potrzebujesz. Zwróć uwagę na parametr DryRun
ustawiony w szablonie na true
, który powoduje że polecenie wykona się „na sucho”. Gdy już będziesz pewien że wszystkie parametry masz prawidłowe możesz usunąć ten parametr aby ostatecznie wykonać polecenie.
Teraz można wykonać:
$ aws ec2 run-instances --cli-input-json file://ec2runinst.json