DEV Community: Hebert Freitas

Simulando um cluster k8s localmente com Kind

Hebert Freitas — Tue, 22 Apr 2025 02:41:06 +0000

Kubernetes é uma realidade bem difundida atualmente. Os principais cloud providers oferecem soluções built-in como o EKS na AWS ou o AKS na Azure.
Do ponto de vista do desenvolvedor tradicional, suas aplicações devem ser construídas e preparadas para executar em containers, e em algum momento (geralmente em uma pipeline de CI/CD) o container desta aplicação será implantado em um cluster k8s.

No entanto, seja por necessidade de conhecer melhor a infraestrutura do k8s (o que recomendo que todo desenvolvedor conheça profundamente se trabalha com aplicações dentro dele), ou seja porque você precisa simular ou testar algum recurso, pode ser necessário efetivamente fazer o deploy do container no ambiente com pods, deployments, services, e toda a estrutura necessária para rodar em um cluster kubernetes.
Além disso, nem sempre existe a possibilidade de você fazer o deploy de fato em um ambiente em cloud para simular uma situação específica, ou as vezes você só quer fazer um teste de algo rápido.

Já a alguns anos existem projetos que simulam um cluster k8s em sua máquina local, hoje vou apresentar um que atende muito bem os meus requisitos que é o Kind

Kind

O kind é uma ferramenta que executa um cluster kubernetes na sua máquina com o uso de docker.
Basicamente ela cria um cluster k8s com os nodes e control plane sendo executados em containers docker.
Para executar o kind você precisa das seguintes ferramentas instaladas e funcionando:

docker
kubectl (para iteragir com o cluster)

Instalação

Recomendo seguir as instruções oficiais para instalação do kind.
Ele pode ser instalado como um pacote do golang.
Em um mac pode ser instalado via brew executando:

brew install kind

Criando clusters

Você pode criar um cluster k8s simplesmente executando:

kind create cluster

Por padrão, este comando criará um cluster com um único nós, mas se você quiser criar um cluster com múltiplos nós você pode usar um arquivo yaml como este:

#kind-multinode-cluster.yaml
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
- role: worker
- role: worker

e então executar o comando:

kind create cluster --config kind-multinode-cluster.yaml

Quando você cria um cluster no kind ele também já adiciona um contexto no seu arquivo de configuração do kubectl (geralmente em ~/.kube/config) apontando para as configurações do seu cluster local, portanto logo depois da criação do cluster basta executar comandos do kubectl tradicionais, por exemplo:

kubectl cluster-info #exibe as informações do cluster
kubectl get nodes #exibe as informações dos nodes do cluster

Load Balancers no Kind

Quando você precisa expor um determinado serviço no kubernetes é comum criar um Service do tipo Load Balancer.
Quando você está usando uma solução de kubernetes em um cloud provider como AWS ou Azure, automaticamente ao criar este Load Balancer um IP é fornecido e você consegue acessar o serviço pelo IP e porta.
Ocorre que no kind, você está rodando localmente em sua máquina, portanto é preciso que alguma outra ferramenta faça este papel, para isso existe o Kubernetes Cloud Provider for KIND
Recomendo fortemente que você instale ele para que seja possível expor serviços em um IP e porta para teste.
Lembrando que após a instalação você precisa executar o binário do provider enquanto estiver provisionando serviços no cluster k8s.

Fazendo o deploy de um serviço no cluster

A partir deste ponto, você já pode fazer o deploy de qualquer serviço no seu cluster k8s localmente, para exemplificar segue um arquivo yaml contendo deployment, especificação de pods e service do tipo Load Balancer para uma api de teste em python fast-api

O código desta api está disponível neste projeto e a mesma possui uma pipeline de CI/CD no github actions que faz o push de uma imagem docker para o docker hub.

#simple-api-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: pokemon-api
spec:
  selector:
    matchLabels:
      app: pokemon-api
  replicas: 2
  template:
    metadata:
      labels:
        app: pokemon-api
    spec:
      containers:
      - name: pokemon-api
        image: hebertrfreitas/fastapi-example:latest
        ports:
        - containerPort: 80
        livenessProbe:
          httpGet:
            path: /health
            port: 80
          initialDelaySeconds: 10
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /health
            port: 80
          initialDelaySeconds: 5
          periodSeconds: 10
---
kind: Service
apiVersion: v1
metadata:
  name: pokemon-api-deployment
spec:
  type: LoadBalancer
  selector:
    app: pokemon-api
  ports:
  - port: 80
    targetPort: 80

Para aplicar no cluster basta executar:

kubectl apply -f simple-api-deployment.yaml

Em seguida para chamar e testar o serviço use os seguintes comandos:

#obtem o IP do load balancer
POKEMON_API_IP=$(kubectl get svc pokemon-api-deployment -o jsonpath='{.status.loadBalancer.ingress[0].ip}')

#faz uma chamada na rota /pokemon da aplicação, que chama uma API externa e faz um request para trazer os dados de um pokemon aleatório
curl http://$POKEMON_API_IP/pokemon

Projeto no github

Se quiser testar todos os comandos e códigos que usei neste post, eles estão disponíveis neste repositorio no github:
https://github.com/hebertrfreitas/kind-labs

Montando um ambiente local para testar LLM's OpenSource

Hebert Freitas — Wed, 19 Feb 2025 02:38:06 +0000

Estou iniciando uma série de artigos para compartilhar a minha experiência como engenheiro de software atuando focado com tecnologias de Generative AI, fique atento aos próximos posts para aprender um pouco mais sobre este tópico.

Ao pesquisar um pouco sobre o mundo de Large Language Models é natural que você se depare com os grandes fornecedores de modelos como OpenAI, Anthropic, etc. Estas empresas fornecem seus modelos proprietários no formato SaaS através de um serviço que pode ser acessado por uma API desde que você tenha uma conta e pague um valor pelo seu uso.

No entanto, nem só de modelos proprietários vive o universo de LLM's, muitos modelos são disponibilizados de forma open source, o que significa que você pode baixá-los e executá-los como quiser.

Apesar de parece simples, detalhes como arquitetura do modelo, configurações e requisitos de hardware podem tornar a tarefa significativamente árdua para um desenvolvedor que simplesmente quer testar diferentes modelos.

Para atender essa demanda, existem algumas iniciativas que tornam este trabalho mais simples, uma delas é o ollama

Ollama

O ollama é um projeto open source que tem como objetivo facilitar a nossa experiência para obter e rodar LLM's.
Ele pode ser instalado na sua máquina e fornece um cli através do qual baixar e executar uma LLM é tão simples quanto executar este comando

ollama run llama3.2

Imediatamente após a execução desde comando, caso você ainda não tenha este modelo localmente ele irá fazer o download do mesmo e logo em seguida fornecer uma iteração com o modelo via linha comando.

Você também pode optar por executar o ollama dentro de um container docker, desde que você já tenha o docker instalado basta executar:

docker run -it -v ollama:/root/.ollama -p 11434:11434 --name ollama ollama/ollama

Em seguida para executar o modelo:

docker exec -it ollama ollama run llama3.2

Nos exemplos acima, estamos executando o modelo llama3.2, para saber a lista de modelos disponíveis, consulte o catálogo do ollama

Esta solução já atende grande parte das necessidades, mas ela pode melhorar.
O serviço do ollama também disponibiliza uma API para comunicação com o modelo, e devido a isso podemos tanto fazer requisições http como também podemos projetar um interface gráfica para facilitar nosso dia a dia, e neste ponto entra a nossa próxima ferramenta que irá nos ajudar, a OpenWebUI.

OpenWebUI

O OpenWebUI é um projeto opensource que fornece uma interface padronizada de chat conversacional para testar LLM's, pode ser usada em conjunto com o ollama que assume o papel de servir as LLM's localmente.

Você pode instalar o OpenWebUI via pip com o comando (recomendamos que você crie um ambiente virtual antes de instalar

pip install open-webui

Em seguida rodar o servidor web com

open-webui serve

Acessando o endereço http://localhost:8080 você verá uma tela parecida com esta.

O OpenWebUI também pode ser executado via docker e tem compatibilidade total com o ollama, caso queira consumir os modelos do ollama, execute o comando abaixo (considerando que você já tem um container docker de nome ollama sendo executado)

docker run -d -p 3000:8080 --add-host=host.docker.internal:host-gateway -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:main

Neste caso, após a execução, basta esperar alguns segundos (o servidor do OpenWebUI pode demorar um pouco para subir) e acessar o endereço http://localhost:3000

Os modelos servidos pelo ollama estarão disponíveis e você poderá conversar com eles, semelhante ao exemplo à seguir:

Bônus, executando tudo com um comando

Para quem achar muito trabalhoso, eu disponibilizei um projeto no github por onde você pode subir todo este ambiente e os serviços com apenas um comando.
O projeto está disponível aqui: https://github.com/hebertrfreitas/generative-ai-labs/tree/main/examples/ollama

Murmurhash -criando um rollout progressivo via backend

Hebert Freitas — Fri, 21 Apr 2023 21:32:15 +0000

Ao ler o título deste post o desenvolvedor mais experiente provavelmente vai se perguntar: "Mas já não existem várias formas de se liberar uma nova funcionalidade para usuários progressivamente ?"

E a resposta é sim, de fato existem algumas maneiras.
Por exemplo, se você estiver em um ambiente com k8s e istio pode por exemplo usar um Virtual Service para isso, você ainda pode fazer isso fora mesmo do k8s com um simples proxy reverso na frente de instâncias diferentes da sua aplicação (uma com a nova feature, e outra sem) além de várias outras.

Porem aqui neste artigo, vou lhe apresentar uma forma de atingir o mesmo objetivo usando um algoritmo de hash bem conhecido, o Murmurhash que pode ser bem útil dependendo do seu cenário.

Murmurhash

O murmurhash é um algoritmo de hash não criptográfico.

Ser um algoritmo de hash significa que dado um input ele converte isso para um output encriptado.
Quer um exemplo simples no nosso dia a dia ?
Se você estiver em um linux ou mac pode usar o sha256 da seguinte maneira:

echo -n teste de mensagem sha256 | shasum -a 256
8785c54a5c506d0c4f031a76b7170c35b2bde862a2bbd7ab2d0485570b75bc06

Já a parte do não criptográfico se refere ao fato de muitas funções hash terem como principal característica tornar impossível a reversão da saída de volta no texto original, o que é especialmente útil se você estiver trabalhando com segurança onde isto é uma premissa. Este não é o caso do murmurhash que não se preocupa tanto com esta característica em detrimento de outras.

Ao contrário da família de algoritmos criptográficos, o murmurhash foi criado para ser rápido devido a sua otimização, com uma boa resistência a colisões e outras características interessantes.
O algoritmo Murmurhash foi criado por Austin Appleby e a implementação de referência em C++ pode ser encontrada no github.

Para demonstrar um pouco do que o algoritmo pode fazer, vamos olhar um simples código em java:

    public static void main(String[] args) {
        String input = "hebert freitas";
        byte[] inputBytes = input.getBytes(Charset.forName("UTF8"));
        HashCode hashCode = Hashing.murmur3_128().hashBytes(inputBytes);
        byte[] outputBytes = hashCode.asBytes();
    }

Neste simples código estamos aplicando o murmurhash e fazendo o hash de um array de bytes que foi gerado a partir de uma simples string com o meu nome.
Optei por usar uma implementação do murmurhash disponível dentro da lib guava mas nada lhe impede de usar outra implementação.

O algoritmo do murmurhash é também determinístico, de maneira que para uma mesma entrada sempre haverá uma mesma saída.

Neste exemplo, estamos optando por pegar o resultado do hash também como um array de bytes, mas seria possível também pegar o resultado como um inteiro ou long.

Todas estas características fazem com que o murmurhash seja usado em cenários interessantes, vamos ver a seguir um possível cenário.

Aplicabilidade

Você sabia que quando usa a lib para interagir com o kafka na sua aplicação o murmurhash é usado por debaixo dos panos para definir em qual partição de um tópico a mensagem será postada com base na sua key ?
A referencia pode ser vista aqui e basicamente o que é feito é usar o murmurhash aplicado a key da mensagem e busca o resto da divisão sobre o total de partições.
Lembram-se também do fato de que o kafka consegue garantir a ordenão de mensagem apenas dentro de uma partição de um tópico mas não dentro de todas as partições ?
Eis outro benefício do murmurhash neste cenário, como sempre teremos o mesmo valor de saída para a mesma entrada mensagens com a mesma key sempre serão direcionadas para a mesma partição.
O murmurhash também é muito eficaz no chamado efeito avalanche que nada mais é do que uma característica onde caso modifiquemos minimamente o input teremos um resultado totalmente diferente, e devido a isso, também é eficaz em distribuir uniformemente entre as partições de um tópico mensagens com keys distintas.

A seguir vamos ver como algumas destas características podem ser aplicadas em um cenário real.

Criando um rollout progressivo com o murmurhash

Imagine que você está diante do seguinte cenário:
"Uma determinada aplicação possui uma base de usuários relativamente grande e você deseja liberar uma nova funcionalidade que foi implementada de forma progressiva para estes usuários, primeiro para 10% da base, depois 20%, e assim sucessivamente até atingir todos os usuários"

Uma das melhores formas de fazer isso é implementar uma feature toogle que permite ligar ou desligar a nova feature na sua aplicação, mas neste caso, não pode ser uma toogle estática que representa o mesmo valor para todos os usuário da aplicação, ela teria que identificar se um determinado cliente entraria ou não nela naquele determinado momento baseado em alguma lógica.
Uma outra alternativa que você pode pensar é marcar os seus usuários na base de dados dizendo quem entra e quem não, atualizando isso aos poucos conforme você vai expandindo o fluxo, mas esta solução não parece ser muito eficiente e de difícil manutenção.

Para atender essa demanda podemos aplicar o murmurhash, usando como input alguma coisa que sempre seja única e nunca mude para um usuário ( id, cpf, etc)
Vamos ver um simples exemplo:

private static double calculatePercentage(String userId){
        HashCode hashCode = Hashing.murmur3_32_fixed().hashBytes(userId.getBytes(Charset.forName("UTF8")));
        long hashedValueInLong = Integer.toUnsignedLong(hashCode.asInt());
        var percentual = hashedValueInLong  / Math.pow(2,32);
        System.out.println("Percentual: " + percentual);
        return percentual;
    }

Detalhando cada um dos passos:

Aplicamos o murmurhash a uma string de input da mesma maneira que fizemos ateriormente.
Pegamos o resultado do murmurhash como um inteiro e convertermos para um unsigned long (vamos aprofundar este detalhe a seguir)
Dividimos o numero resultado do murmurhash por 2 elevado a 32 porque este é o valor máximo que pode ser atingido.
O resultado é um percentual, um valor em 0.1 e 1.0 aplicado a um usuário.

Neste exemplo, estamos usando a versão de 32 bits do murmurhash, que pode gerar um hash de até 32 bits.
Na linha 3 do código convertermos um int para um long usando porque valores inteiros podem ser negativos e esta é uma forma simples de se obter o valor sem sinal, para mais detalhes veja a documentação do método Integer.toUnsignedLong
Se você executar este método com o input 836d473d-56be-4ef9-9b13-1fc8f36ef98e terá como resultado o valor 0.913....
Com este valor basta comparar com o percentual máximo que você deseja disponibilizar a nova feature. Neste exemplo, se estivermos liberando para 20% da base com certeza este usuário não entraria, mas se já estivermos liberando para 95% da base este usuário entraria porque seu percentual é 91%.

É possível ter exatidão máxima com este método ?

Considerando as características do algoritmo murmurhash ele funciona melhor conforme o publico alvo vai aumentando, ou neste caso, conforme maior é sua base de usuários.

Projeto de exemplo

Para exemplificar tudo o que discutimos criei um projeto de exemplo, onde a partir de uma lista fictícia de 10.000 usuários e um valor predeterminado de 10% classificamos esta lista para demonstrar que o algoritmo consegue distribuir uniformemente os hashs e filtrar um valor muito próximo de 10% de usuários mesmo sem conhecer toda a base.

O projeto está disponível neste link = https://github.com/hebertrfreitas/murmurhash-example

DynamoDB local - Um mock funcional para o DynamoDB

Hebert Freitas — Sun, 13 Feb 2022 19:11:38 +0000

Recentemente escrevi um post sobre o localstack, que fornece um mock funcional para os principais serviços da aws.

Localstack - Um mock funcional para os serviços da aws

Hebert Freitas ・ Nov 20 '21

#docker #aws #localstack #braziliandevs

Porém, caso você esteja trabalhando especificamente com o DynamoDB a aws fornece oficialmente uma ferramenta chamada DynamoDB local que é recomendada para testes e desenvolvimento da aplicação sem se conectar aos serviços reais da aws.
Neste artigo vamos entender um pouco como funciona esta ferramenta 😀

Índice

Como Usar
Usando via Docker
Aplicação de exemplo

Como usar

O DynamoDB local convenientemente é fornecido de três formas:

Como um programa java executável (arquivo .jar)
Através de uma imagem docker
Através de uma dependência do maven

A página de documentação dá detalhes sobre o uso de cada uma destas opções. Neste post utilizaremos a opção via imagem docker.

Utilizando o DynamoDB local via docker

Se você apenas executar o comando à seguir no seu terminal(assumindo que você tem o docker instalado corretamente) já terá o dynamodb local rodando na porta 8000



docker run -p 8000:8000 amazon/dynamodb-local

E sim, você já consegue apontar a sua aplicação para ele 😁, vamos demonstrar isso no no tópico em que construímos uma aplicação de exemplo.

Por padrão o entrypoint executado pela imagem docker oficial irá utilizar a propriedade -inMemory que significa que o dynamo irá manter todos os dados em memória, logo ao finalizar o container automaticamente os dados são perdidos.

Eventualmente vamos querer manter os arquivos e dados do banco de dados criados via container docker mesmo após a finalização do mesmo, para isso segue o conteúdo de um arquivo docker compose que explora um pouco mais as opções disponíveis.



version: '3.8'

services:
  dynamodb-local:
    working_dir: /home/dynamodblocal
    command: "-jar DynamoDBLocal.jar -sharedDb -dbPath ./data"
    image: "amazon/dynamodb-local:latest"
    container_name: dynamodb-local
    ports:
      - "8000:8000"
    volumes:
      - ".dynamodbdata:/home/dynamodblocal/data"

Para utilizar estas instruções, salve o conteúdo em um arquivo chamado docker-compose.yaml e em seguida execute o comando docker-compose up.

Algumas observações sobre a configuração realizar no docker compose:

sobrescrevemos o comando inicial executado ao subir o container na linha command:, observe que não colocamos o comando java porque ele já é especificado no entrypoint default da imagem docker fornecida pela aws.
utilizamos o parâmetro -sharedDb para informar ao dynamo que desejamos criar um único arquivo para armazenar os bancos de dados.
o parâmetros -dbPath ./data informa onde queremos que o arquivo de banco de dados seja salvo. Como o workdir foi definido para /home/dynamodblocal o banco de dados será salvo no caminho absoluto /home/dynamodblocal/data dentro do container.
Criamos um volume apontando o caminho .dynamodbdata da máquina host para /home/dynamodblocal/data dentro do container, logo todos os arquivos de banco de dados gerados pelo dynamo serão mapeados para lá.

Ao executar o comando docker-compose up na pasta com o arquivo de conteúdo exemplificado acima podemos observar que será criada a pasta .dynamodbdata a princípio vazia.

Caso você tenha o aws-cli instalado na sua máquina, é perfeitamente possível executar comandos apontando para o dynamodb local, basta inserir o parâmetro --endpoint-url=http://localhost:8000.

Por exemplo, para listar as tabelas existentes:



aws --endpoint-url http://localhost:8000 dynamodb list-tables

Aplicação de exemplo

Para demonstrar o uso do dynamodb local construi uma pequena api usando spring boot e kotlin, o código está disponível no github.

Nesta aplicação estamos usando a biblioteca dynamodb-enhanced que faz parte do AWS sdk for java (v2) e fornece uma maneira bem intuitiva de mapear as tabelas dynamo na sua aplicação via anotações.

Para que a aplicação possa se comunicar com o dynamo é necessário criar um objeto do tipo software.amazon.awssdk.services.dynamodb.DynamoDbClient na aplicação fizemos isso provisionando um bean do spring da seguinte maneira:



    @Bean
    fun dynamoDBClient():DynamoDbClient{
        return DynamoDbClient.builder()
            .region(awsProperties.regionAsAwsEnum())
            .apply { 
                if(! awsProperties.endpoint.isNullOrEmpty()) 
                    endpointOverride(URI(awsProperties.endpoint)) //awsProperties.endpoint = http://localhost:8000 
            }
            .credentialsProvider(DefaultCredentialsProvider.builder().build())
            .build()
    }

Observe que chamamos no builder o método endpointOverride apenas se awsProperties.endpoint for diferente de nulo.
A ideia aqui é passar nessa propriedade o valor http://localhost:8000 exatamente como fizemos no aws-cli, apontando para onde está rodando o DynamoDB local na sua máquina.
Se você não passar essa propriedade o builder não executara este ponto e apontará para o serviço real da aws.

Nesta api estamos fazendo um simples crud de um cenário hipotético onde queremos cadastrar pintores famosos e suas pinturas.

A estrutura básica pensada para o modelo de dados pode ser representada da seguinte maneira em json



{
    "id": "123",
    "name": "Leonardo da Vinci",
    "birthdate": "1452-04-15",
    "paintings":[
        {
            "name": "Mona Lisa (La Gioconda)",
            "location": "Louvre, Paris"
        },
        {
            "name": "The Last Supper",
            "location": "Santa Maria delle Grazie, Milan"
        }
    ]
}

Esta estrutura pode ser facilmente mapeada para classes através da anotações, segue exemplo de como fizemos isso no código



/**
 * Important note: using `var` because the AWS SDK needs default `setters` in order to detect an attribute
 */
@DynamoDbBean
class Painter(
    @get:DynamoDbPartitionKey var id: String? = null,
    var name: String? = null,
    @field:JsonFormat(pattern="yyyy-MM-dd")
    var birthdate: LocalDate? = null,
    var paintings:List<Paint> = mutableListOf()
){
    constructor():this(null, null, null)
}



@DynamoDbBean
class Paint(var name:String?, var location:String?){
    constructor():this(null, null)
}

OBS: Os contrutores default aceitando nulo e o uso de var são devido a requisitos do AWS SDK que necessita de classes com getters e setters padrão para que seja possível mapear as mesmas para o dynamo

Para executar o projeto baixe o mesmo do github, em seguida na raiz execute



docker-compose up --build

Isso irá subir um docker-compose
contendo o dynamodb-local e também um container com o aws-cli que fará a criação da tabela inicial.

Em seguida execute



./gradlew bootRun

Este segundo comando irá subir a aplicação na porta 8080.

OBS: O java 11 instalado é requisito para que você consiga executar o projeto.

A api está documentada com swagger então é possível acessar o mesmo no endereço http://localhost:8080/swagger-ui.html

Para testar, seguem alguns comandos que podem ser executados via curl

Criando um pintor



curl --location --request POST 'localhost:8080/painters' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id": "123",
    "name": "Leonardo da Vinci",
    "birthdate": "1452-04-15",
    "paintings":[
        {
            "name": "Mona Lisa (La Gioconda)",
            "location": "Louvre, Paris"
        },
        {
            "name": "The Last Supper",
            "location": "Santa Maria delle Grazie, Milan"
        }
    ]
}'

Bucando um pintor pelo id



curl --location --request GET 'localhost:8080/painters/123'

Deletando um pintor



curl --location --request DELETE 'localhost:8080/painters/123'

Localstack - Um mock funcional para os serviços da aws

Hebert Freitas — Sat, 20 Nov 2021 19:36:10 +0000

Atualmente é bem comum trabalhar em projetos que se comuniquem com alguns serviços da aws, seja uma fila SQS, um bucket S3 para armazenar arquivos ou até mesmo um banco de dados DynamoDB.

Durante o desenvolvimento deste software você irá precisar fazer a comunicação com estes serviços em nuvem da aws para testar o seu produto, simular cenários ou até mesmo executar alguns testes de integração.

No entanto, nem sempre você terá disponível um ambiente na aws onde você possa alterar livremente de maneira que atenda os requisitos do desenvolvimento, ou mesmo que tenha, pode ser complexo fazer a comunicação em um primeiro momento.

Para resolver estes problemas, existe o projeto localstack, que fornece um mock dos principais servicos da AWS como SQS, SNS, S3 entre outros.

Como usar o localstack

A forma mais conveniente de executar o projeto é através de uma imagem docker oficial disponível neste link: dockerhub localstack, segue um exemplo de um arquivo do docker-compose:

version: "3.8"

services:
  localstack:
    container_name: "localstack"
    image: localstack/localstack:0.12.11
    ports:
      - "4566:4566"
      - "4571:4571"
    environment:
      - SERVICES=sqs,s3

Para executar este arquivo crie um arquivo yaml chamado docker-compose.yaml com o conteúdo acima e execute o comando docker-compose up na mesma pasta do arquivo criado.

Alguns pontos importantes a se destacar:

neste exemplo estamos usando a versão 0.12.11 mas você pode e deve checar qual versão mais atualizada está disponível no docker hub do projeto.
a variável de ambiente SERVICES aceita uma lista de nomes dos serviços que desejamos provisionar, neste exemplo estamos pedindo ao localstack para disponibilizar uma api do SQS e uma do S3.

Interagindo com os serviços da aws no localstack

Uma das formas oficiais de se comunicar com os serviços da aws é o AWS CLI

Você pode ter o awscli instalado na sua máquina e apontar para os serviços da aws mockados no localstack.
Para fazer isso basta inserir em todos os comando o seguinte parâmetro: --endpoint-url=http://localstack:4566

Exemplo de criação de uma queue no SQS:

aws --endpoint-url=http://localhost:4566 sqs create-queue --queue-name teste

No entanto, caso você não queria ou não precise ter o awscli instalado no seu computador, o localstack já disponibiliza um wrapper do awscli chamado awslocal que já vem pré-configurado para interagir localmente com os serviços mockados da aws.

Considerando que você esteja executando o projeto via docker é possível fazer o mesmo exemplo citado acima da seguinte maneira:

#para entrar no container (considerando que o nome do seu container é localstack)
docker exec -it localstack sh
#comando equivalente ao apresentado acima para criar uma fila 
awslocal sqs create-queue --queue-name teste

Observe que não precisamos adicionar o parâmetro --endpoint-url pois o awslocal já está configurado assumindo que desejo me comunicar com os serviços localmente.

⚠ Porque localhost:4566 ?

O projeto localstack disponibiliza o mock dos serviços da aws na porta 4566.

Considerando que você está executando o projeto via docker é importante que você mapeie a porta 4566 do container para a 4566(ou outra a seu critério) da sua máquina local, foi isso que fizemos no arquivo de exemplo do docker-compose.

Como executar comandos no startup do container

Caso você queira executar comandos após o startup do container como criar um bucket no s3 ou inicializar uma fila sqs basta criar um arquivo .sh com a lista de comandos e montá-lo como volume na pasta /docker-entrypoint-initaws.d dentro do container.

Ao iniciar, o localstack irá executar todos os scripts existentes neste caminho.
Sendo assim nosso docker-compose ficaria com a seguinte configuração:

services:
    localstack:
      container_name: "localstack"
      image: localstack/localstack:0.12.11
      ports:
        - "4566:4566"
        - "4571:4571"
      environment:
        - SERVICES=sqs,s3
      volumes: 
        - ./init-scripts:/docker-entrypoint-initaws.d #mapeamento do volume

Agora podemos criar a pasta init-scripts na raiz do projeto e um arquivo shell script startup.sh dentro dela com alguns comandos por exemplo:

echo 'creating test bucket'
awslocal s3api create-bucket --bucket test-bucket

echo 'listing buckets'
awslocal s3api list-buckets

A estrutura do projeto deverá ficar da seguinte maneira:

 .
├── docker-compose.yaml
└── init-scripts
    └── startup.sh

Se executar o comando docker-compose up após o startup inicial você verá as mensagens do script sendo executado.

O conteúdo deste post está disponível no github no endereço: https://github.com/hebertrfreitas/localstack-docker