Build-time Secrets with Docker BuildKit

1. O Problema: Como os Segredos Vazam Durante o Build

Antes de saltarmos para a solução, é crucial entender por que as abordagens tradicionais são perigosas. Como desenvolvedor experiente, você pode pensar em usar argumentos de build (ARG) ou simplesmente copiar um arquivo de segredo (COPY) e depois removê-lo. Vamos ver por que essas estratégias são falhas.

O vídeo a seguir demonstra de forma clara e prática o problema de usar ARG.

Como o vídeo mostra, o comando docker history revela o segredo em texto plano. Isso ocorre porque cada instrução RUN em um Dockerfile cria uma nova camada na imagem. Mesmo que uma instrução posterior remova o segredo (com rm), a camada anterior que o continha ainda existe e pode ser inspecionada.

Para satisfazer sua curiosidade sobre "como isso funciona" internamente, o artigo a seguir mostra como qualquer pessoa com acesso à imagem pode extrair esses segredos camada por camada.

Essa exploração prática deixa claro que precisamos de um mecanismo que disponibilize os segredos para uma etapa de build sem nunca os gravar no sistema de arquivos da imagem.

2. A Solução: Docker BuildKit e Secret Mounts

A solução para este problema é o BuildKit, o engine de build de nova geração do Docker. Ele é o padrão nas versões recentes do Docker e introduz uma maneira completamente nova e segura de lidar com segredos de build.

Em vez de passar dados para a imagem, o BuildKit permite que uma etapa RUN monte temporariamente um arquivo de segredo de sua máquina host. Esse arquivo existe apenas em memória, apenas durante a execução daquela instrução RUN, e nunca é salvo em nenhuma camada da imagem.

O processo envolve duas partes:

1. No docker build: Usar o flag --secret para informar ao Docker sobre o segredo e sua origem (um arquivo local ou uma variável de ambiente).
2. No Dockerfile: Usar a opção --mount=type=secret em uma instrução RUN para montar o segredo e usá-lo.

O vídeo a seguir demonstra o fluxo completo.

Resumindo a sintaxe:

Dockerfile:

# syntax=docker/dockerfile:1
FROM mcr.microsoft.com/dotnet/sdk:8.0

# O segredo só estará disponível dentro desta instrução RUN
RUN --mount=type=secret,id=my_nuget_token \
    SECRET_VALUE=$(cat /run/secrets/my_nuget_token) && \
    echo "O token secreto é: $SECRET_VALUE"

• --mount=type=secret: Especifica que estamos montando um segredo.
• id=my_nuget_token: Define um identificador para o segredo. Este id será usado para referenciá-lo no comando build.

Comando de Build (passando de um arquivo):

# Crie um arquivo local com seu segredo
echo "my-super-secret-nuget-token" > .secret-file

# Construa a imagem, apontando para o arquivo
docker build --secret id=my_nuget_token,src=.secret-file -t my-app .

• --secret id=my_nuget_token,src=.secret-file: Informa ao BuildKit para usar o conteúdo do arquivo .secret-file para o segredo com o ID my_nuget_token.

Comando de Build (passando de uma variável de ambiente):

# Exporte o segredo como uma variável de ambiente
export NUGET_TOKEN="my-super-secret-nuget-token"

# Construa a imagem
docker build --secret id=my_nuget_token,env=NUGET_TOKEN -t my-app .

• --secret id=my_nuget_token,env=NUGET_TOKEN: Informa ao BuildKit para usar o valor da variável de ambiente NUGET_TOKEN para o segredo.

3. Cenários de Uso e Melhores Práticas

Agora que você entende o mecanismo, vamos ver como aplicá-lo em cenários realistas, especialmente em conjunto com multi-stage builds.

Usando Segredos com Multi-Stage Builds

A combinação de build secrets e multi-stage builds é a prática recomendada para máxima segurança e otimização de imagem. A ideia é usar o segredo apenas no estágio de build para buscar dependências ou compilar código, e depois copiar apenas os artefatos necessários para um estágio final limpo.

Aqui está um exemplo relevante para você, como um desenvolvedor .NET, que usa um token para restaurar pacotes de um feed NuGet privado.

# syntax=docker/dockerfile:1

# ====== Estágio de Build ======
# Usa o SDK completo e terá acesso ao segredo
FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /src

# Copie os arquivos de projeto primeiro
COPY ["MyApi/MyApi.csproj", "MyApi/"]
COPY ["nuget.config", "./"]

# Monte o segredo do NuGet e configure o feed privado
RUN --mount=type=secret,id=nuget_password \
    dotnet nuget add source "https://pkgs.dev.azure.com/my-org/_packaging/MyFeed/nuget/v3/index.json" \
    --name "MyFeed" \
    --username "user" \
    --password $(cat /run/secrets/nuget_password) \
    --store-password-in-clear-text \
    --configfile "nuget.config"

# Restaure as dependências
RUN dotnet restore "MyApi/MyApi.csproj"

# Copie o resto do código e publique
COPY . .
WORKDIR "/src/MyApi"
RUN dotnet publish "MyApi.csproj" -c Release -o /app/publish

# ====== Estágio Final ======
# Usa a imagem de runtime mais leve, sem SDK e sem segredos
FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS final
WORKDIR /app
COPY --from=build /app/publish .
ENTRYPOINT ["dotnet", "MyApi.dll"]

Neste exemplo:

• O segredo nuget_password só é montado no estágio build.
• Ele é usado para autenticar com o feed privado durante o dotnet nuget add source.
• O estágio final apenas copia os artefatos compilados (/app/publish). Ele não contém o SDK .NET, o nuget.config com credenciais, nem tem qualquer vestígio do segredo.

# syntax=docker/dockerfile:1
FROM alpine/git as cloner
WORKDIR /app

# Modifique a linha abaixo
RUN git clone git@github.com:my-org/private-repo.git .

# syntax=docker/dockerfile:1
FROM alpine/git as cloner
WORKDIR /app

# A montagem do tipo 'ssh' dá acesso temporário ao agente SSH do host
RUN --mount=type=ssh git clone git@github.com:my-org/private-repo.git .

# Assumindo que sua chave já está carregada no agente SSH (ssh-add)
docker build --ssh default -t my-app .

# Ou, para especificar uma chave
docker build --ssh git_key=$HOME/.ssh/id_rsa_git -t my-app .
# (Neste caso, o Dockerfile precisaria ser `RUN --mount=type=ssh,id=git_key ...`)

4. Integração com Docker Compose

Naturalmente, você vai querer gerenciar isso dentro dos seus projetos com docker-compose.yml. O Docker Compose se integra perfeitamente com os segredos de build.

Você define os segredos na seção build do seu serviço.

Aqui está um exemplo de como o docker-compose.yml ficaria para o nosso cenário de NuGet:

# docker-compose.yml
version: '3.8'

services:
  my-api:
    build:
      context: .
      dockerfile: MyApi.Dockerfile
      secrets:
        # Disponibiliza o segredo 'nuget_password' para o build deste serviço
        - nuget_password
    ports:
      - "8080:80"

# Definição de nível superior dos segredos
secrets:
  nuget_password:
    # A fonte do segredo é o arquivo local ./.secrets/nuget_token
    file: ./.secrets/nuget_token

Com esta configuração, você só precisa executar docker-compose build, e o Compose cuidará de passar o segredo para o BuildKit da maneira correta.

Conclusão

Parabéns! Você agora domina a técnica moderna e segura para gerenciar credenciais durante o processo de build de imagens Docker. Isso não apenas protege seus segredos, mas também leva a imagens finais mais limpas, menores e mais seguras.

Principais Pontos:

• Nunca use ARG ou COPY para injetar segredos de build, pois eles persistem nas camadas da imagem.
• Use o Docker BuildKit com RUN --mount=type=secret para montar segredos temporariamente em memória.
• Passe segredos para o comando de build com o flag --secret, especificando um arquivo (src) ou variável de ambiente (env) como fonte.
• Combine sempre os segredos de build com multi-stage builds para garantir que a imagem final não contenha nem os segredos nem as ferramentas que os utilizaram.
• Integre o gerenciamento de segredos de build em seus fluxos de trabalho de desenvolvimento usando a seção build.secrets no seu docker-compose.yml.

Na próxima lição, começaremos nossa jornada no .NET Aspire. Você verá como o Aspire abstrai e simplifica muito do que aprendemos sobre a orquestração de contêineres, redes e configurações, proporcionando uma experiência de desenvolvimento de aplicações nativas para a nuvem muito mais fluida.