Noções Básicas de Implantação

10 exemplos para você começar com Deploy & K8s - 7 básicos e 3 intermediários.

Pré-requisitos

• Instale o Go 1.26.x ou posterior em go.dev/dl.
• Instale o Docker para compilação de imagens e um cluster Kubernetes local (kind, minikube ou Docker Desktop Kubernetes).
• Instale kubectl e verifique o acesso ao cluster: kubectl cluster-info.
• Crie um módulo: mkdir deploylab && cd deploylab && go mod init example.com/deploylab.

Exemplos Básicos

1. Binário de Lançamento com go build

Produza um binário Linux otimizado a partir da raiz do seu módulo.

CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath \
  -ldflags="-s -w" -o bin/api ./cmd/api

• CGO_ENABLED=0 gera um binário estático adequado para imagens scratch/distroless.
• -trimpath remove caminhos do sistema de arquivos local dos binários para compilações reproduzíveis.
• -ldflags="-s -w" remove símbolos de depuração para encolher o tamanho do artefato.

Relacionado: Implantando Go: Binário Único como Superpoder - por que um arquivo muda as operações

2. Incorpore Metadados de Versão no Momento da Compilação

Carimbe a versão do git no binário para depuração de produção.

package main
 
import "fmt"
 
var (
    version = "dev"
    commit  = "none"
)
 
func main() {
    fmt.Printf("api %s (%s)\n", version, commit)
}

go build -ldflags="-X main.version=1.2.3 -X main.commit=$(git rev-parse --short HEAD)" -o bin/api .

• -X define variáveis de string em main no momento do link.
• Registre a versão na inicialização para que os incidentes sejam mapeados para os números de compilação do CI.
• Mantenha compilações de depuração não removidas no armazenamento de artefatos para simbolização.

Relacionado: Pipelines de CI/CD para Serviços Go - automatize o carimbo de versão no CI

3. Servidor HTTP Mínimo para Contêineres

Vincule à PORT do ambiente, o padrão para PaaS e Kubernetes.

package main
 
import (
    "fmt"
    "log"
    "net/http"
    "os"
)
 
func main() {
    port := os.Getenv("PORT")
    if port == "" {
        port = "8080"
    }
    http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprintln(w, "hello")
    })
    log.Fatal(http.ListenAndServe(":"+port, nil))
}

• Contêineres devem escutar em todas as interfaces (:8080), não 127.0.0.1.
• Leia PORT do env para que as plataformas possam atribuir portas efêmeras.
• Adicione timeouts explícitos antes da produção; os padrões são inseguros atrás de balanceadores de carga.

Relacionado: Builds Docker de Múltiplos Estágios para Go - empacote este servidor em uma imagem mínima

4. Endpoint de Saúde Liveness-Ready

Exponha um endpoint barato que as sondas do Kubernetes possam chamar.

http.HandleFunc("/healthz", func(w http.ResponseWriter, r *http.Request) {
    w.WriteHeader(http.StatusOK)
    w.Write([]byte("ok"))
})

• Liveness deve responder "o processo está ativo?" sem acessar bancos de dados.
• Readiness pode verificar dependências; mantenha-o rápido para evitar instabilidade durante rollouts.
• Retorne não-200 quando o processo dever parar de receber tráfego.

Relacionado: Sondas, HPA e Orçamentos de Interrupção de Pod - ajuste de sondas e escalonamento automático

5. Dockerfile de Estágio Único (Caminho de Aprendizagem)

Uma imagem de tempo de execução simples de duas linhas para experimentos locais.

FROM golang:1.26-bookworm AS build
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -o /api ./cmd/api
 
FROM debian:bookworm-slim
COPY --from=build /api /api
EXPOSE 8080
ENTRYPOINT ["/api"]

• Múltiplos estágios mantêm as ferramentas de compilação fora da camada de tempo de execução.
• Mesmo os Dockerfiles de aprendizagem devem definir CGO_ENABLED=0 para binários Linux portáteis.
• Equipes de produção migram para distroless; este estágio debian-slim é mais fácil de depurar localmente.

Relacionado: Builds Docker de Múltiplos Estágios para Go - distroless e certificados CA

6. Compile e Execute a Imagem Localmente

Marque com um semver ou SHA do git, nunca apenas latest em ambientes compartilhados.

docker build -t deploylab/api:0.1.0 .
docker run --rm -p 8080:8080 -e PORT=8080 deploylab/api:0.1.0
curl -s localhost:8080/healthz

• Tags imutáveis vinculam contêineres em execução a artefatos de CI.
• Mapeie a porta do host 8080 para a PORT do contêiner para testes rápidos.
• Envie a mesma tag que seu manifesto Kubernetes referencia.

Relacionado: Melhores Práticas de Implantação - tags semver e disciplina de rollback

7. Implantação Mínima no Kubernetes

Execute uma réplica com solicitações de recursos para que o agendador possa posicionar o pod.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
spec:
  replicas: 1
  selector:
    matchLabels:
      app: api
  template:
    metadata:
      labels:
        app: api
    spec:
      containers:
        - name: api
          image: deploylab/api:0.1.0
          ports:
            - containerPort: 8080
          env:
            - name: PORT
              value: "8080"
          resources:
            requests:
              cpu: 100m
              memory: 64Mi
            limits:
              memory: 128Mi

kubectl apply -f deployment.yaml
kubectl rollout status deployment/api

• resources.requests ajudam o agendador e as linhas de base do HPA.
• Fixe image em uma tag ou digest específico, não em um latest flutuante.
• Observe o status do rollout antes de declarar a implantação como concluída.

Relacionado: Implantações, Serviços e Ingress do Kubernetes - Serviços, Ingress e limites

Exemplos Intermediários

8. Serviço ClusterIP e Encaminhamento de Porta

Exponha a Implantação dentro do cluster e teste sem Ingress.

apiVersion: v1
kind: Service
metadata:
  name: api
spec:
  selector:
    app: api
  ports:
    - port: 80
      targetPort: 8080

kubectl apply -f service.yaml
kubectl port-forward svc/api 8080:80
curl -s localhost:8080/healthz

• Serviços roteiam DNS estável (api.default.svc.cluster.local) para IPs de pod.
• targetPort deve corresponder à porta de escuta do contêiner.
• Port-forward é para desenvolvimento; produção usa Ingress ou Serviços LoadBalancer.

Relacionado: Implantações, Serviços e Ingress do Kubernetes - regras de Ingress e TLS

9. Sondas HTTP na Implantação

Conecte sondas liveness e readiness a /healthz.

livenessProbe:
  httpGet:
    path: /healthz
    port: 8080
  initialDelaySeconds: 3
  periodSeconds: 10
readinessProbe:
  httpGet:
    path: /healthz
    port: 8080
  periodSeconds: 5

• initialDelaySeconds evita matar pods que ainda estão vinculando portas.
• Falha na Readiness remove o pod dos endpoints do Serviço durante a inicialização.
• Ajuste periodSeconds e timeoutSeconds para seu SLO e tempo de inicialização a frio.

Relacionado: Sondas, HPA e Orçamentos de Interrupção de Pod - PDBs e escalonamento automático

10. Desligamento Gracioso em SIGTERM

O Kubernetes envia SIGTERM antes de SIGKILL; drene requisições em andamento.

package main
 
import (
    "context"
    "log"
    "net/http"
    "os"
    "os/signal"
    "syscall"
    "time"
)
 
func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("/healthz", func(w http.ResponseWriter, r *http.Request) {
        w.Write([]byte("ok"))
    })
    srv := &http.Server{Addr: ":8080", Handler: mux}
 
    go func() {
        if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
            log.Fatal(err)
        }
    }()
 
    stop := make(chan os.Signal, 1)
    signal.Notify(stop, syscall.SIGTERM, syscall.SIGINT)
    <-stop
 
    ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
    defer cancel()
    if err := srv.Shutdown(ctx); err != nil {
        log.Fatal(err)
    }
}

• Shutdown para de aceitar novas conexões e aguarda requisições ativas.
• Corresponda ao período de graça de término na especificação do pod ao seu timeout de desligamento.
• Durante rollouts, falha na Readiness mais drenagem graciosa evita requisições perdidas.

Relacionado: Hooks de Engenharia de Caos para Microserviços Go - valide o comportamento sob falha

Versões da Pilha: Esta página foi escrita para Go 1.26.x (padrão Green Tea GC, go fix modernizers - verifique o patch na compilação), chi (mais recente - verifique na compilação), gin (mais recente - verifique na compilação), echo (mais recente - verifique na compilação), google.golang.org/grpc (mais recente - verifique na compilação), sigs.k8s.io/controller-runtime (mais recente - verifique na compilação), kubebuilder (mais recente - verifique na compilação), tinygo (mais recente - verifique os alvos de placa na compilação), wazero (mais recente - verifique na compilação) e golangci-lint (mais recente - verifique o conjunto de linters na compilação).

pbqrthvqrf.vb|ptvb406|202607