Como configurar múltiplos perfis de AWS CLI por projeto

1. Fundamentos dos perfis de AWS CLI

O AWS Command Line Interface (CLI) permite gerenciar múltiplas contas e ambientes através de perfis nomeados. Um perfil é um conjunto de configurações que define qual conta AWS será acessada, em qual região e com que credenciais. A necessidade de múltiplos perfis surge naturalmente quando você trabalha com projetos distintos que utilizam contas AWS separadas — por exemplo, um perfil para desenvolvimento, outro para homologação e um terceiro para produção.

A estrutura de configuração da AWS CLI é composta por dois arquivos principais:

  • ~/.aws/config: armazena configurações como região padrão, formato de saída e perfis com roles de acesso
  • ~/.aws/credentials: contém as chaves de acesso (access key e secret key) para cada perfil

O perfil default é utilizado quando nenhum perfil é explicitamente especificado. Perfis nomeados permitem alternar entre diferentes contas e configurações sem conflitos.

2. Criando perfis manuais para projetos específicos

Para criar um perfil manualmente, edite os arquivos de configuração. Primeiro, adicione o perfil no ~/.aws/config:

[profile projeto-dev]
region = us-east-1
output = json

[profile projeto-prod]
region = sa-east-1
output = table

Em seguida, adicione as credenciais correspondentes no ~/.aws/credentials:

[projeto-dev]
aws_access_key_id = AKIAIOSFODNN7EXAMPLE
aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

[projeto-prod]
aws_access_key_id = AKIAI44QH8DHBEXAMPLE
aws_secret_access_key = je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY

Para verificar todos os perfis disponíveis, utilize:

aws configure list-profiles

Este comando retorna a lista de perfis configurados, permitindo confirmar que os perfis foram criados corretamente.

3. Usando variáveis de ambiente para alternar entre perfis

A variável de ambiente AWS_PROFILE é o método mais direto para alternar entre perfis em uma sessão de terminal:

export AWS_PROFILE=projeto-dev
aws s3 ls  # lista buckets usando o perfil projeto-dev

Para garantir compatibilidade com SDKs que utilizam a variável AWS_DEFAULT_PROFILE, configure ambas:

export AWS_PROFILE=projeto-dev
export AWS_DEFAULT_PROFILE=projeto-dev
export AWS_SDK_LOAD_CONFIG=true

A variável AWS_SDK_LOAD_CONFIG força SDKs a carregarem o arquivo ~/.aws/config, essencial para perfis que utilizam role_arn ou source_profile.

Automação com direnv

O direnv carrega automaticamente variáveis de ambiente ao entrar em um diretório. Instale-o e crie um arquivo .envrc no diretório do projeto:

export AWS_PROFILE=projeto-dev
export AWS_DEFAULT_PROFILE=projeto-dev
export AWS_REGION=us-east-1

Após criar o arquivo, execute direnv allow para autorizar o carregamento automático. Ao navegar para o diretório, o perfil é ativado automaticamente.

4. Automatizando perfis por projeto com arquivos .env e scripts

Uma abordagem alternativa ao direnv é utilizar um script shell com uma função cd customizada. Crie um arquivo .env no diretório raiz do projeto:

AWS_PROFILE=projeto-dev
AWS_DEFAULT_PROFILE=projeto-dev

Adicione a seguinte função ao seu ~/.bashrc ou ~/.zshrc:

cd() {
    builtin cd "$@"
    if [ -f .env ]; then
        source .env
        echo "Perfil AWS configurado: $AWS_PROFILE"
    fi
}

Esta função carrega automaticamente as variáveis do arquivo .env sempre que você navegar para o diretório do projeto.

Integração com direnv

O direnv oferece uma solução mais robusta. Crie o arquivo .envrc com o conteúdo desejado e utilize o comando direnv edit para editar. A grande vantagem é que o direnv descarrega as variáveis ao sair do diretório, evitando contaminação entre projetos.

5. Gerenciamento de múltiplas contas e roles (STS AssumeRole)

Para cenários onde você precisa acessar recursos em outra conta AWS, configure perfis que assumem roles. No ~/.aws/config, adicione:

[profile dev-base]
region = us-east-1

[profile dev-assumido]
region = us-east-1
role_arn = arn:aws:iam::123456789012:role/Desenvolvedor
source_profile = dev-base
mfa_serial = arn:aws:iam::987654321098:mfa/usuario

O source_profile indica qual perfil fornece as credenciais base, enquanto role_arn especifica a role a ser assumida na conta de destino. O parâmetro mfa_serial é opcional, mas recomendado para autenticação multifator.

Para obter credenciais temporárias programaticamente:

aws sts assume-role \
    --role-arn "arn:aws:iam::123456789012:role/Desenvolvedor" \
    --role-session-name "SessaoProjeto" \
    --profile dev-base

O comando retorna credenciais temporárias que podem ser exportadas como variáveis de ambiente.

6. Práticas recomendadas e segurança

Nunca versionar arquivos com credenciais. Adicione ao .gitignore do projeto:

.env
.aws/
credentials

Utilize nomes de perfis padronizados para facilitar a identificação:

projeto-dev
projeto-homolog
projeto-prod

Para rotação de chaves, crie novas chaves no console AWS e atualize o arquivo ~/.aws/credentials. Sempre prefira perfis com MFA para ambientes de produção.

7. Depuração e resolução de problemas comuns

Para verificar qual perfil está ativo:

aws sts get-caller-identity

Este comando retorna o ARN do usuário ou role associado ao perfil ativo. Para depuração detalhada, ative logs:

export AWS_DEBUG=true
aws s3 ls --debug

Erros comuns incluem:

  • Perfil não encontrado: verifique se o nome do perfil está correto em ~/.aws/config e ~/.aws/credentials
  • Credenciais expiradas: gere novas chaves no console AWS
  • Conflitos entre variáveis: desative variáveis de ambiente conflitantes com unset AWS_PROFILE

Referências