artykuły

Wprowadzenie do AWS Tools for PowerShell

Brak komentarzy

Każdy zaawansowany użytkownik AWS-a zna AWS CLI. Używa go do automatyzacji pewnych zadań, czy też po prostu, aby uniknąć klikania po webowej konsoli. Jednak w momencie, gdy musimy napisać jakiś bardziej złożony skrypt, gdzie wyniki komend, trzeba przekazać jako wejście do kolejnych i nie jesteśmy ekspertami od basha lub windowsowego batcha, to zadanie może okazać się większym wyzwaniem niż powinno.

Można odnieść mylne wrażenie, że Powershell to jakaś niszowa zabawka dla windowsowych administratorów, ale szybki rzut oka na statystyki w google trends jasno pokazuje, że zaczyna on popularnością doganiać nieśmiertelnego basha.

Dodatkowym atutem Powershella jest fakt, że od wersji 6, wydanej w połowie 2018 roku, jest on multiplatformowy. Oznacza to, że nasze skrypty z powodzeniem uruchomimy zarówno na Windowsie, Macu jak i Linuxie!

Jak zainstalować AWS Tools for PowerShell?

Na stronie projektu znajdziemy kilka osobnych pakietów. Sugeruję instalację najnowszego z nich – AWS.Tools. Jego przewagą jest modularna budowa, dzięki której nasze skrypty będą mieć mniejsze zależności i będą uruchamiać się szybciej. Dodatkowym atutem jest fakt, że odpadnie nam konieczność ręcznego wywoływania Import-Module, by móc skorzystać z AWS-owych cmdletów. Pewnym utrudnieniem jest natomiast fakt, że poszczególne moduły będziemy musieli instalować osobno.

Na początek instalujemy moduł pomocniczy, który pomoże nam w dalszej instalacji poszczególnych modułów, a dodatkowo zadba o synchronizację wersji między nimi.

PS > Install-Module -Name AWS.Tools.Installer

Następnie instalujemy poszczególne moduły komendą Install-AWSToolsModule. Możemy je instalować jeden po drugim, lub kilka naraz.

PS > Install-AWSToolsModule AWS.Tools.S3
PS > Install-AWSToolsModule AWS.Tools.EC2,AWS.Tools.SimpleNotificationService,AWS.Tools.SQS

Niestety, brak jest konsekwencji w nazewnictwie modułów. Z jakiegoś powodu SQS zapisywany jest skrótowo, ale SNS to już SimpleNotificationService.

Listę wszystkich dostępnych serwisów możemy uzyskać uruchamiając komendę Get-AWSService | % Service (filtrujemy listę zwróconych obiektów, aby uzyskać listę stringów).

Przykładowe skrypty

Z pomocą Powershella wykonamy większość czynności, które możemy wykonać za pomocą webowej konsoli lub AWS CLI. Poniżej znajdziecie kilka przykładowych skryptów prezentujących możliwości i filozofię korzystania z tego SDK.

Informacje o aktualnej sesji

Get-STSCallerIdentity

Operacje na S3

# listowanie bucketów na koncie
Get-S3Bucket

# listowanie plików w buckecie
Get-S3Object -BucketName my-bucket

# pobieranie pliku do lokalnego katalogu
Get-S3Object -BucketName my-bucket -Key my-prefix/my-file.txt | Read-S3Object -Folder local-folder

# pobieranie wszystkich plików *.json do lokalnego katalogu
Get-S3Object -BucketName -my-bucket | ? { $_.Key -Like '*.json' } | Read-S3Object -Folder local-folder

Wyjątkowo przydatną cechą PowerShella jest możliwość przekierowania wyjścia komendy do kolejnej za pomocą operatora potoku |. W powyższym przykładzie najpierw pobieramy listę obiektów z bucketa, następnie filtrujemy (? to alias na komendę Where-Object), a na koniec pobieramy wszystkie obiekty z listy,

Kopiowanie parametrów w Parameter Store

$srcPath = '/my-params'
$dstPath = '/my-params-copy'

# pobierz wszystkie parametry ze ścieżki źródłowej (również zagnieżdżone dzięki -Recursive)
$parameters = Get-SSMParametersByPath -Path $srcPath -Recursive

# zmień ścieżkę w pobranych parametrach na docelową
$parameters | ForEach-Object -Process {    
    $_.Name = $_.Name -Replace("^$SrcPath", $DstPath)
}

# zapisz kopie parametrów
$parameters | Write-SSMParameter

Powyższy skrypt możemy również zapisać skrótowo, wykorzystując alias %, w zastępstwie ForEach-Object i łącząc komendy operatorem potoku:

Get-SSMParametersByPath -Path $src -Recursive | % { $_.Name = $_.Name -Replace("^$src", $dst) } | Write-SSMParameter

Jak szukać poleceń?

Do szukania nazw cmdletów służy komenda Get-AWSCmdletName. Uruchomiona bez parametrów zwraca listę wszystkich dostępnych komend, która w momencie pisania artykułu liczyła sobie prawie 7 tysięcy pozycji. Aby ułatwić sobie poszukiwania, listę warto przefiltrować po nazwie serwisu, z którego chcemy skorzystać. Szczęśliwie, w większości przypadków zadziałają zarówno pełne nazwy serwisów, jak i skrótowce.

PS > Get-AWSCmdletName -Service "Security Token"

CmdletName                      ServiceOperation           ServiceName                      ModuleName
----------                      ----------------           -----------                      ----------
Convert-STSAuthorizationMessage DecodeAuthorizationMessage AWS Security Token Service (STS) AWS.Tools.SecurityToken
Get-STSAccessKeyInfo            GetAccessKeyInfo           AWS Security Token Service (STS) AWS.Tools.SecurityToken
Get-STSCallerIdentity           GetCallerIdentity          AWS Security Token Service (STS) AWS.Tools.SecurityToken
Get-STSFederationToken          GetFederationToken         AWS Security Token Service (STS) AWS.Tools.SecurityToken
Get-STSSessionToken             GetSessionToken            AWS Security Token Service (STS) AWS.Tools.SecurityToken
Use-STSRole                     AssumeRole                 AWS Security Token Service (STS) AWS.Tools.SecurityToken
Use-STSRoleWithSAML             AssumeRoleWithSAML         AWS Security Token Service (STS) AWS.Tools.SecurityToken
Use-STSWebIdentityRole          AssumeRoleWithWebIdentity  AWS Security Token Service (STS) AWS.Tools.SecurityToken

Jeśli znamy nazwę komendy ze zwykłego AWS CLI, to nie powinniśmy mieć problemu ze znalezieniem jej powershellowego odpowiednika. Przykładowo funkcjonalność aws sts get-caller-identity, kryje się pod nazwą Get-STSCallerIdentity.

Przydatny może się również okazać mechanizm interaktywnych podpowiedzi – IntelliSense, który aktywujemy skrótem CTRL+Spacja. Z jego pomocą uzupełnimy nazwę komendy, sprawdzimy dostępne parametry i wprowadzimy ścieżki do plików.

IntelliSense w akcji

Szczegółowy opis działania komendy oraz listę przyjmowanych parametrów otrzymamy przekazując nazwę cmdletu do polecenia Get-Help.

PS > Get-Help Get-S3BucketLocation
...
DESCRIPTION
    Returns the Region the bucket resides in. You set the bucket's Region using
the LocationConstraint request parameter in a CreateBucket request. For more
information, see CreateBucket.
    To use this implementation of the operation, you must be the bucket owner.
    The following operations are related to GetBucketLocation:
     - GetObject
     - CreateBucket
...

Jak pisać multiplatformowe skrypty?

Średnio-zaawansowane skrypty, które do tej pory tworzyłem pod windowsem z powodzeniem uruchamiały się również na linuxie. Tak na prawdę jedyny problem, który napotkałem to interpretacja backslasha w ścieżkach do plików. Pod linuxem próba utworzenia pliku dane\seria.csv, powoduje utworzenie pliku o dokładnie takiej nazwie "dane\seria.csv". Rozwiązaniem, które działa również bezproblemowo na windowsie jest po prostu używanie wszędzie slasha, czyli dane/seria.csv.

Warto również wiedzieć, że Powershell dysponuje zmiennymi $IsWinodws, $IsLinux, $IsMacOS, dzięki którym bardzo łatwo można sprawdzić aktualny system operacyjny.

Przerywanie skryptu po napotkanym błędzie

Domyślnie, gdy Powershell napotka błąd podczas wykonywania skryptu, kontynuuje jego wykonywanie. We wszystkich przypadkach użycia, z którymi miałem do czynienia, nigdy nie było to pożądane zachowanie. Przykładowo jeśli cluster RDS nie istnieje, nie ma sensu robić mu snapshota, a później sprawdzać status tego zadania.

Aby zmienić to domyślne zachowanie, wystarczy ustawić na początku skryptu odpowiednią zmienną.

$ErrorActionPreference = "Stop"

Niestety powyższe ustawienie nie ma wpływu na komendy natywne. Niezależnie od tego czy zwróconą one kod 0 (sukces) czy inny, praca skryptu jest kontynuowana. Aby przerwać działanie skryptu w takim przypadku musimy sami sprawdzić jaki kod zwróciła ostatnia komenda i wyrzucić błąd w razie potrzeby.

mysqldump --host=$host --user=$user --password="$pass" --result-file=$dumpFile
if($LASTEXITCODE -ne 0){
    Write-Error "mysqldump command failed."
}

Żeby nie zaśmiecać sobie kodu, możemy to sprawdzenie przenieść do osobnej funkcji i dla czytelności uruchamiać ją w jednej linii z komendą, która jest weryfikowana.

function StopOnNativeError {
    if ($lastexitcode -ne 0) {
        Write-Error "Native command failed with a non-zero error code" -ErrorAction Stop
    }
}
...
mysqldump --host=$host --user=$user --password="$pass" --result-file=$dumpFile ; StopOnNativeError

Czy warto sprawdzić AWS Tools for PowerShell?

Powiem krótko: zdecydowanie tak! Tworzenie skryptów z ich pomocą jest dla mnie zdecydowanie przyjemniejsze, niż używanie klasycznego AWS CLI. Sam do tego stopnia je polubiłem, że zmieniłem swoją domyślną konsolę na PowerShella i wykonuję różne czynności administracyjne pisząc sprytne jednolinijkowce z palca, zamiast klikać po webowej konsoli.

Gorąco polecam! 🙂

Tags: ,

Powiązane artykuły

Dodaj komentarz

Twój adres e-mail nie zostanie opublikowany. Wymagane pola są oznaczone *

Wypełnij to pole
Wypełnij to pole
Proszę wprowadzić prawidłowy adres e-mail.
You need to agree with the terms to proceed

Menu