Localstack awslocal komutu

Giriş

Açıklaması şöyle

When interacting with LocalStack to emulate AWS services it’s important to configure your AWS CLI or SDK to point to the LocalStack endpoint URL. This allows you to interact with LocalStack easily without having to specify the --endpoint-url option every time you run a command.

Another option is installing a tool called “awslocal” which is a wrapper around the AWS CLI for LocalStack. It automatically configures the CLI to use the LocalStack endpoint URL, saving you from the manual step of specifying the --endpoint-url option.

Açıklaması şöyle

awslocal is a thin wrapper and a drop-in replacement for the aws command that runs commands directly against LocalStack

1. awslocal Olmadan

Örnek

Şöyle yaparız

# create s3 bucket
aws --endpoint-url=http://localhost:4566 s3api create-bucket --bucket testbucket

# list s3 buckets
aws --endpoint-url=http://localhost:4566 s3api list-buckets

# copy test file to the created bucket.
aws --endpoint-url=http://localhost:4566 s3 cp test.txt s3://testbucket

# check files
aws --endpoint-url=http://localhost:4566 s3api list-objects --bucket testbucket

Örnek

bucket_policy.json içinde şöyle yaparız

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "PublicReadGetObject",
      "Effect": "Allow",
      "Principal": "*",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::testbucket/*"
    }
  ]
}

Şöyle yaparız

# sync the website folder that contains our files to the S3 bucket 
aws --endpoint-url=http://localhost:4566 s3 sync .\website\ s3://testbucket

# enable static website hosting on the bucket and configure the index and error documents:
aws --endpoint-url=http://localhost:4566 s3 website s3://testbucket/ \
  --index-document index.html 
  --error-document error.html

2. Bash Başlatmak

Localstack içinden awslocal çıkıyor. Container'a bash açmak yeterli. Şöyle yaparız

docker exec -it <container_id> /bin/bash

sqs seçeneği

Örnek

Şöyle yaparız

$awslocal sqs create-queue --queue-name test-queue

$awslocal sqs list-queues

{
  "QueueUrls" : [
    http:/localhost:4566:/000000/test-queue"
  ]
}

s3 seçeneği

Örnek - High Level Command

Şöyle yaparız. Yeni bir bucket yaratır

awslocal s3 mb s3://my-test-bucket

Örnek -  - Low Level Command

Şöyle yaparız. Yeni bir bucket yaratır

awslocal s3api create-bucket \
--bucket mybucket \
--create-bucket-configuration LocationConstraint=eu-central-1

Localstack Nedir

Giriş

Açıklaması şöyle. Yani AWS servisleri için bir  emülatör

LocalStack is a cloud service emulator that runs in a single container on your laptop or in your CI environment. With LocalStack, you can run your AWS applications or Lambdas entirely on your local machine without connecting to a remote cloud provider! Whether you are testing complex CDK applications or Terraform configurations, or just beginning to learn about AWS services, LocalStack helps speed up and simplify your testing and development workflow.

Açıklaması şöyle

LocalStack is a cloud service emulator that runs AWS services solely on your laptop without connecting to a remote cloud provider .

Kurulum

Açıklaması şöyle

There are several ways to install LocalStack (LocalStack CLI, LocalStack Cockpit, Docker, Docker-Compose, Helm).

Docker

Örnek

Şöyle yaparız

docker run --rm -it 
  -p 4566:4566 
  -p 4510-4559:4510-4559 
 localstack/localstack

Docker Compose ve Localstack

Örnek

Şöyle yaparız

version: '3.9'
services:
  aws-local:
    container_name: aws-local
    image: localstack/localstack:1.3
    ports:
      - "4566:4566"
      - "8283:8080"
    environment:
      - "SERVICES=sqs,sns,secretsmanager"

Örnek - volume

Şöyle yaparız

version: "3.8"

services:
  localstack:
    container_name: "${LOCALSTACK_DOCKER_NAME-localstack_main}"
    image: localstack/localstack:0.14.2
    network_mode: bridge
    ports:
      - "127.0.0.1:4566:4566"            # LocalStack Gateway
      - "127.0.0.1:53:53"                #
      - "127.0.0.1:53:53/udp"            #
      - "127.0.0.1:443:443"              #
      - "127.0.0.1:4510-4530:4510-4530"  # ext services port range
      - "127.0.0.1:4571:4571"            #
    environment:
      - DEBUG=${DEBUG-}
      - SERVICES=${SERVICES-}
      - DATA_DIR=${DATA_DIR-}
      - LAMBDA_EXECUTOR=local
      - LOCALSTACK_API_KEY=${LOCALSTACK_API_KEY-}
      - HOST_TMP_FOLDER=${TMPDIR:-/tmp/}localstack
      - DOCKER_HOST=unix:///var/run/docker.sock
      - DISABLE_CORS_CHECKS=1
    volumes:
      - "${TMPDIR:-/tmp}/localstack:/tmp/localstack"
      - "/var/run/docker.sock:/var/run/docker.sock"

Hangi servislerin çalıştığını görmek için şöyle yaparız

http://localhost:4566/health 

Çıktı şöyle. Örneğin S3 çalışıyor

{
  "features": {
    "initScripts": "initialized"
  },
  "services": {
    "acm": "available",
    "apigateway": "available",
    "cloudformation": "available",
    "cloudwatch": "available",
    "config": "available",
    "dynamodb": "available",
    "dynamodbstreams": "available",
    "ec2": "available",
    "es": "available",
    "events": "available",
    "firehose": "available",
    "iam": "available",
    "kinesis": "available",
    "kms": "available",
    "lambda": "available",
    "logs": "available",
    "opensearch": "available",
    "redshift": "available",
    "resource-groups": "available",
    "resourcegroupstaggingapi": "available",
    "route53": "available",
    "route53resolver": "available",
    "s3": "available",
    "s3control": "available",
    "secretsmanager": "available",
    "ses": "available",
    "sns": "available",
    "sqs": "running",
    "ssm": "available",
    "stepfunctions": "available",
    "sts": "available",
    "support": "available",
    "swf": "available",
    "transcribe": "available"
  },
  "version": "1.1.1.dev"
}

Örnek

Şöyle yaparız. Burada dynamo db için bazı başlangıç scriptleri veriliyor

version: '3.9'

networks:
  tasks-network:
    driver: bridge

services:
  ...
  tasks-localstack:
    image: localstack/localstack:latest
    container_name: tasks-localstack
    environment:
      - DEBUG=0
      - SERVICES=dynamodb
      - EAGER_SERVICE_LOADING=1
      - DYNAMODB_SHARE_DB=1
      - AWS_DEFAULT_REGION=ap-southeast-2
      - AWS_ACCESS_KEY_ID=DUMMY
      - AWS_SECRET_ACCESS_KEY=DUMMY
      - DOCKER_HOST=unix:///var/run/docker.sock
    ports:
      - "4566:4566"
    volumes:
      - ./utils/docker-volume/localstack:/var/lib/localstack"
      - ./utils/docker-volume/dynamodb/items/devices.json:/var/lib/localstack/devices.json
      - ./utils/docker-volume/dynamodb/scripts/create-resources.sh:/etc/localstack/init/ready.d/create-resources.sh
      - /var/run/docker.sock:/var/run/docker.sock
    networks:
      - tasks-network

devices.json şöyle

{
  "id": {"S": "123"},
  "name": {"S": "Device name"},
  "description": {"S": "Device description"},
  "status": {"S": "OFF"}
}

create-resources.sh şöyle

#!/bin/bash

echo "CREATING DEVICES TABLE..."
awslocal dynamodb create-table                                \
  --table-name Devices                                        \
  --attribute-definitions AttributeName=id,AttributeType=S    \
  --key-schema AttributeName=id,KeyType=HASH                  \
  --billing-mode PAY_PER_REQUEST
echo "DONE!"

echo ""
echo "PUTTING DEVICE ITEM..."
awslocal dynamodb put-item                                    \
    --table-name Devices                                      \
    --item file:///var/lib/localstack/devices.json
echo "DONE!"

init script

Açıklaması şöyle

The volume section specifies a directory on a PC mapped to a directory inside the container. On the container startup the Localstack checks this directory for bash files, and if it finds executes them. It is useful to create resources, configs, etc. This way you write commands once in the bash file and Localstack executes them automatically on a startup, so you don’t need to type the command manually each time you spin up a container.

Örnek

Şöyle yaparız

version: '3.8'

services:
  localstack:
    image: localstack/localstack
    ports:
      - '4566:4566' # LocalStack endpoint

    environment:
      - DOCKER_HOST=unix:///var/run/docker.sock
    volumes:
      - ./localstack-script:/etc/localstack/init/ready.d
      - '/var/run/docker.sock:/var/run/docker.sock'

Örnek

Şöyle yaparız. Burada bir s3 bucket yaratılıyor

version: "3.8"

services:
  localstack:
    container_name: localstack_main
    image: localstack/localstack:latest
    ports:
      - "127.0.0.1:4566:4566"            # LocalStack Gateway
      - "127.0.0.1:4510-4559:4510-4559"  # external services port range
    environment:
      - DEBUG=1
      - AWS_ACCESS_KEY_ID=test
      - AWS_SECRET_ACCESS_KEY=test          
      - AWS_DEFAULT_REGION=eu-west-1 # Region where your localstack mocks to be running
      - DOCKER_HOST=unix:///var/run/docker.sock
    volumes:
      - "${LOCALSTACK_VOLUME_DIR:-./volume}:/var/lib/localstack"
      - "/var/run/docker.sock:/var/run/docker.sock"
      - ./aws/init-aws.sh:/etc/localstack/init/ready.d/init-aws.sh

Docker Compose dosyası ile aynı dizinde bulunan aws/init-aws.sh dosyası şöyledir

#!/bin/bash
awslocal s3 mb s3://my-test-bucket

Örnek

Şöyle yaparız. Burada init-scripts dizini localstack'e gösteriliyor. 

version: '3.8'
services:
  localstack:
    container_name: localstack
    image: localstack/localstack:0.11.6
    ports:
      - "4566-4599:4566-4599"
    environment:
      - SERVICES=sqs
    volumes:
      - ./init-scripts:/docker-entrypoint-initaws.d

init-scripts dizinindeki bir dosya şöyle olsun

#!/bin/bash
echo "########### Setting up localstack profile ###########"
aws configure set aws_access_key_id access_key --profile=localstack
aws configure set aws_secret_access_key secret_key --profile=localstack
aws configure set region sa-east-1 --profile=localstack

echo "########### Setting default profile ###########"
export AWS_DEFAULT_PROFILE=localstack

echo "########### Setting SQS names as env variables ###########"
export SOURCE_SQS=source-sqs
export DLQ_SQS=dlq-sqs

echo "########### Creating DLQ ###########"
aws --endpoint-url=http://localstack:4566 sqs create-queue --queue-name $DLQ_SQS

echo "########### ARN for DLQ ###########"
DLQ_SQS_ARN=$(aws --endpoint-url=http://localstack:4566 sqs get-queue-attributes\
                  --attribute-name QueueArn --queue-url=http://localhost:4566/000000000000/"$DLQ_SQS"\
                  |  sed 's/"QueueArn"/\n"QueueArn"/g' | grep '"QueueArn"' | awk -F '"QueueArn":' '{print $2}' | tr -d '"' | xargs)

echo "########### Creating Source queue ###########"
aws --profile=localstack --endpoint-url=http://localstack:4566 sqs create-queue --queue-name $SOURCE_SQS \
     --attributes '{
                   "RedrivePolicy": "{\"deadLetterTargetArn\":\"'"$DLQ_SQS_ARN"'\",\"maxReceiveCount\":\"2\"}",
                   "VisibilityTimeout": "10"
                   }'

echo "########### Listing queues ###########"
aws --endpoint-url=http://localhost:4566 sqs list-queues

echo "########### Listing Source SQS Attributes ###########"
aws --endpoint-url=http://localstack:4566 sqs get-queue-attributes\
                  --attribute-name All --queue-url=http://localhost:4566/000000000000/"$SOURCE_SQS"

Açıklaması şöyle

This file has a couple of commands, that will be executed sequentially.

1. Localstack profile is created

2. DLQ is created

3. ARN for DLQ is obtained

4. Source SQS is created with redrive policy. In the redrive policy ARN for DLQ is specified and maxReciveCount wich tells Source SQS how many times client can receive message before it will be transferred to DLQ. A visibility timeout is set to 10 seconds. More option with explanations can be found here.

5. A list of the created queues is returned.

6. A list of attributes of a Source queue is returned. It confirms that Source SQS has attributes specified in the creation command.