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