DEV Community: Celso Nery

Minecraft Server - Part 3: Running on Kubernetes

Celso Nery — Fri, 21 Aug 2026 14:20:55 +0000

Minecraft Server - Part 3: Running on Kubernetes

In Part 2 of this series, we got the Minecraft server running in Docker containers, with persistence via volumes and automatic restart. In this article, will bringing the same server into a Kubernetes cluster, gaining managed storage via PersistentVolumeClaim, isolation via Namespace, and the flexibility to run on any available node in the cluster.

Minecraft Bedrock on Kubernetes

---
apiVersion: v1
kind: Namespace
metadata:
  name: minecraft-br
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: minecraft-bedrock-pvc
  namespace: minecraft-br
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: minecraft-bedrock-server
  namespace: minecraft-br
spec:
  replicas: 1
  selector:
    matchLabels:
      app: minecraft-bedrock
  template:
    metadata:
      labels:
        app: minecraft-bedrock
    spec:
      containers:
        - name: minecraft-bedrock
          image: itzg/minecraft-bedrock-server:latest
          ports:
            - containerPort: 19132
              protocol: UDP
          env:
            - name: EULA
              value: "TRUE"
            - name: GAMEMODE
              value: "survival"
            - name: MAX_PLAYERS
              value: "10"
            - name: MOTD
              value: "Bedrock Minecraft Server!"
            - name: OPS
              value: "your_username"
          volumeMounts:
            - mountPath: /data
              name: minecraft-bedrock-data
      volumes:
        - name: minecraft-bedrock-data
          persistentVolumeClaim:
            claimName: minecraft-bedrock-pvc
---
apiVersion: v1
kind: Service
metadata:
  name: minecraft-bedrock-service
  namespace: minecraft-br
spec:
  selector:
    app: minecraft-bedrock
  ports:
    - name: bedrock-udp
      port: 19132
      targetPort: 19132
      protocol: UDP
  type: LoadBalancer

Notice the structure, which brings together several concepts already covered throughout the series:

Namespace (minecraft-br): isolates the Minecraft Bedrock resources from the rest of the cluster;
PersistentVolumeClaim (10Gi): ensures the saved world survives pod restarts and recreations, without it, every new pod would start with an empty world;
Deployment: runs a single replica (replicas: 1), multiple replicas of the same Minecraft world don't work, since the game wasn't designed for multiple instances accessing the same save simultaneously;
LoadBalancer-type Service, on UDP port 19132, exposing the server outside the cluster.

On on-premise clusters, the LoadBalancer type usually doesn't provision an IP automatically (that's a native cloud provider feature), you need a controller like MetalLB for the Service to actually receive a usable external IP. Without it, the Service's external IP will stay <pending> indefinitely.

Minecraft Java on Kubernetes

apiVersion: v1
kind: Namespace
metadata:
  name: minecraft-java
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: minecraft-pvc
  namespace: minecraft-java
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: minecraft-server
  namespace: minecraft-java
spec:
  replicas: 1
  selector:
    matchLabels:
      app: minecraft
  template:
    metadata:
      labels:
        app: minecraft
    spec:
      containers:
        - name: minecraft
          image: itzg/minecraft-server:latest
          ports:
            - containerPort: 25565
          env:
            - name: EULA
              value: "TRUE"
            - name: MEMORY
              value: "1G"
            - name: VERSION
              value: "latest"
            - name: MAX_PLAYERS
              value: "10"
            - name: MOTD
              value: "Welcome to the Minecraft server"
            - name: ONLINE_MODE
              value: "TRUE"
            - name: WHITELIST
              value: "false"
            - name: OPS
              value: "your_username"
          volumeMounts:
            - mountPath: /data
              name: minecraft-data
      volumes:
        - name: minecraft-data
          persistentVolumeClaim:
            claimName: minecraft-pvc
---
apiVersion: v1
kind: Service
metadata:
  name: minecraft-service
  namespace: minecraft-java
spec:
  selector:
    app: minecraft
  ports:
    - name: mc-tcp
      port: 25565
      targetPort: 25565
      protocol: TCP
  type: LoadBalancer

Unlike Bedrock, here the containerPort and Service ports use TCP (the default, when protocol isn't specified on the container, but made explicit on the Service for clarity), consistent with Minecraft Java communicating over TCP, as we saw in Part 2.

Some environment fields specific to this image:

MEMORY: sets the memory limit passed to the JVM internally by the image (equivalent to the -Xmx flag seen in the bare metal installation);
VERSION: lets you pin a specific Minecraft version (for example, "1.20.4") instead of always using the latest;
ONLINE_MODE: when set to "TRUE", requires players to be authenticated with a valid Microsoft/Mojang account, only disable this if you know exactly why you need to (usually for servers with pirated clients, which carries security and legal implications).

Applying the manifests

kubectl apply -f minecraft-bedrock.yaml
kubectl apply -f minecraft-java.yaml

Checking whether the pods came up correctly:

kubectl -n minecraft-br get pods

and

kubectl -n minecraft-java get pods

Following the startup logs (the first start downloads the server files, which can take a few minutes):

kubectl -n minecraft-java logs -f deployment/minecraft-server

and 

kubectl -n minecraft-br logs -f deployment/minecraft-bedrock-server

Series wrap-up

Throughout this series, we saw the same Minecraft server through three stages: manual bare metal installation, containerization with Docker, and finally orchestration on a Kubernetes cluster. Each stage solved a limitation of the previous one, from manual process management, through persistence and automatic restart, to managed storage and independence from a single physical host.

It's worth reinforcing an important point that applies to all three approaches: since this is a stateful game (the saved "world"), it's not possible to scale horizontally by running multiple replicas of the same server, unlike a stateless API, Minecraft needs a single, consistent instance accessing the data volume at a time.

Minecraft Server - Part 2: Running with Docker

Celso Nery — Fri, 21 Aug 2026 14:20:12 +0000

🇧🇷 Versão em português

Minecraft Server - Part 2: Running with Docker

In Part 1 of this series, we installed the Minecraft server (Bedrock and Java) directly on the operating system, manually managing the process with screen/tmux. In this article, we take a natural next step: running the same server in a Docker container, using the community-maintained images from itzg/docker-minecraft-server and itzg/docker-minecraft-bedrock-server.

Advantages over the bare metal installation:

Automatic restart on failure (restart: unless-stopped);
Isolated and explicit data persistence, via volumes;
Declarative configuration, in a single versionable file;
Isolation of the process from the rest of the system.

Prerequisite: Docker and Docker Compose must already be installed. If you haven't installed them yet, please do so. If you're not sure how, check out my "Docker for Developers" series; in Part 1, I show how to install Docker.

Running Minecraft Bedrock with Docker

version: "3.8"

services:
  minecraft-bedrock:
    image: itzg/minecraft-bedrock-server:latest
    container_name: minecraft-bedrock-server
    restart: unless-stopped
    ports:
      - "19132:19132/udp"
    environment:
      EULA: "TRUE"
      GAMEMODE: "survival"
      MAX_PLAYERS: "10"
      MOTD: "Bedrock Minecraft Server!"
      WHITELIST: "false"
      OPS: "your_username"
    volumes:
      - minecraft-bedrock-data:/data

volumes:
  minecraft-bedrock-data:
    driver: local

Important points:

ports: "19132:19132/udp": Bedrock uses UDP, unlike most network services, notice the explicit /udp suffix;
EULA: "TRUE": automatically accepts the Minecraft license, skipping the manual eula.txt step seen in Part 1;
OPS: already grants operator permission to the given user on first startup;
minecraft-bedrock-data: a named volume, ensuring the world and settings survive container updates and recreations.

Running Minecraft Java with Docker

version: "3.8"

services:
  minecraft-java:
    image: itzg/minecraft-server:latest
    container_name: minecraft-java-server
    restart: unless-stopped
    ports:
      - "25565:25565"
    environment:
      EULA: "TRUE"
      GAMEMODE: "survival"
      MAX_PLAYERS: "10"
      MOTD: "Java Minecraft Server!"
      WHITELIST: "false"
      OPS: "your_username"
    volumes:
      - minecraft-java-data:/data

volumes:
  minecraft-java-data:
    driver: local

Important: unlike Bedrock, Minecraft Java uses TCP, not UDP, the port should be mapped as "25565:25565" (TCP is Docker's default protocol when none is specified), without the /udp suffix.

Bringing up the servers

Each server can live in its own docker-compose.yaml file (recommended, so you can manage them independently) or both in the same file, as two separate services.

docker compose up -d

Following the startup logs (the first start can take a few minutes, downloading the server files):

docker compose logs -f

Managing the server via console

The itzg images include a built-in RCON tool (rcon-cli) inside the container, letting you run server commands without needing to attach directly to the process:

docker exec -it minecraft-java-server rcon-cli

Inside the RCON console, the same commands from Part 1 work normally:

whitelist add new_player
op new_player

For Bedrock, the container also accepts commands via send-command (depending on the image version) or directly through the WHITELIST and OPS environment variables in docker-compose.yaml, restarting the container to apply changes.

The itzg images have a large number of available environment variables (difficulty, world type, plugins, mods, etc.), it's worth checking each image's official documentation on Docker Hub for the complete, up-to-date list, since new options are added frequently.

Docker Hub itzg repository

Next steps

With Minecraft running in Docker containers, we now have automatic restart, persistence, and declarative configuration. But this still runs on a single host, if the machine goes down, the server goes down with it. In Part 3 of this series, we'll take the same server into a Kubernetes cluster, gaining features like managed storage via PersistentVolumeClaim and the ability to run on any available node in the cluster.

Continued in Part 3.

Minecraft Server - Part 1: Bare Metal Installation

Celso Nery — Fri, 21 Aug 2026 14:19:02 +0000

🇧🇷 Versão em português

Minecraft Server - Part 1: Bare Metal Installation

Introduction

Running your own Minecraft server gives you full control over the game, mods, rules, a persistent world, and no dependency on third-party servers. This is the first part of a series that will provide three installation options: we start here with a bare metal installation (directly on the operating system), then move on to Docker, and finally to Kubernetes.

There are two main editions of the game, with incompatible servers between them:

Bedrock Edition: cross-platform (Windows, consoles, mobile), uses the UDP protocol;
Java Edition: the "classic" PC version, with the largest ecosystem of mods and plugins, uses the TCP protocol.

I will cover the installing of both.

System requirements

Requirements vary mainly with the number of simultaneous players and whether the world uses heavy mods/plugins:

Players	Recommended RAM	CPU
1-5	2GB	2 cores
5-10	4GB	2-4 cores
10-20+	8GB+	4+ cores

The Java edition tends to consume more resources than Bedrock for the same number of players, especially with plugins like Spigot/Paper.

Installing the Minecraft Bedrock Server

Download

Download the official Bedrock server package for Linux directly from the official page:

minecraft.net/download/server/bedrock

After downloading, extract the .zip file into a dedicated directory:

mkdir -p ~/minecraft-bedrock
cd ~/minecraft-bedrock
unzip bedrock-server-*.zip
chmod +x bedrock_server

Running the server

LD_LIBRARY_PATH=. ./bedrock_server

The Bedrock server relies on shared libraries in its own directory, that's why the LD_LIBRARY_PATH=. variable is needed for it to find them correctly.

To keep the server running even after closing the terminal, use screen or tmux:

screen -S minecraft-bedrock
LD_LIBRARY_PATH=. ./bedrock_server
# Ctrl+A, D to detach without stopping the process

Configuring the server

Bedrock server options live in the server.properties file, automatically generated on first run. Full documentation for all available properties is on the official wiki:

minecraft.fandom.com/wiki/Server.properties

Some of the most commonly used:

server-name=My Bedrock Server
gamemode=survival
difficulty=normal
max-players=10
online-mode=true
white-list=false
level-name=Bedrock level

After editing the file, restart the server to apply the changes.

Installing the Minecraft Java Server

Prerequisite: Java

The Java server needs a JRE/JDK installed, the exact version depends on the Minecraft version (more recent versions require Java 17 or 21). To install on Debian:

sudo apt install openjdk-21-jre-headless
java -version

Download

Download the server.jar for the desired version from the official Minecraft Java Server download page.

www.minecraft.net/en-us/download/server

mkdir -p ~/minecraft-java
cd ~/minecraft-java
# Download the server.jar for the desired version into this directory

Accepting the EULA

On first run, Minecraft creates an eula.txt file and refuses to start until you manually accept the terms:

echo "eula=true" > eula.txt

Running the server

java -Xmx2G -Xms1G -jar server.jar nogui

-Xmx2G: maximum memory the JVM can use;
-Xms1G: initial memory allocated;
nogui: runs without the graphical interface, ideal for servers.

Just like with Bedrock, use screen or tmux to keep the process running in the background.

Managing the server

Player list (whitelist)

Restricting who can join the server is done via a whitelist.

On Bedrock, edit whitelist.json:

[
  { "name": "your_username" }
]

And enable it in server.properties: white-list=true.

On Java, use the server console (the terminal where it's running):

whitelist add your_username
whitelist on

User permissions (ops)

Granting administrator permissions (operator commands) also differs between editions.

On Bedrock, edit permissions.json:

[
  { "permission": "operator", "xuid": "your_xuid" }
]

On Bedrock, you need the player's XUID (Xbox Live account identifier), not just their username.

On Java, from the console:

op your_username

Exposing it to the internet

By default, the server is only accessible on the local network. To allow external connections:

Open the port in the machine's firewall:
- Bedrock: port 19132/UDP
- Java: port 25565/TCP
Set up port forwarding on your router, pointing the external port to the internal IP of the machine running the server.

Setting up dynamic DNS with No-IP

Most home internet connections have a dynamic public IP, it changes periodically, breaking access for anyone who saved the old IP. No-IP solves this, associating a fixed domain (for example, myserver.ddns.net) with your current IP, updated automatically.

Create a free account at noip.com;
Register a hostname (for example, my-minecraft.ddns.net);
Install the DUC (Dynamic Update Client) on your server or router (many routers already have native No-IP support in their dynamic DNS settings);
Share the hostname with your friends instead of the IP, it will keep working even when your IP changes.

Next steps

With the server running bare metal, manually managed with screen/tmux, you can already play with friends. But this model has limitations: no isolation, no automatic restart on failure, and manual configuration from scratch if you need to migrate to another machine. In Part 2 of this series, we'll run the same server in a Docker container, solving these problems with a declarative and reproducible configuration.

Continued in Part 2.

Servidor Minecraft - Parte 3: Rodando no Kubernetes

Celso Nery — Fri, 21 Aug 2026 14:17:17 +0000

🇺🇸 English version comming soon

Servidor Minecraft - Parte 3: Rodando no Kubernetes

Na Parte 2 desta série, colocamos o servidor Minecraft para rodar em containers Docker, com persistência via volumes e reinício automático. Neste artigo, vamos levar o mesmo servidor para dentro de um cluster Kubernetes, ganhando armazenamento gerenciado via PersistentVolumeClaim, isolamento por Namespace e a flexibilidade de rodar em qualquer nó disponível do cluster.

Minecraft Bedrock no Kubernetes

---
apiVersion: v1
kind: Namespace
metadata:
  name: minecraft-br
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: minecraft-bedrock-pvc
  namespace: minecraft-br
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: minecraft-bedrock-server
  namespace: minecraft-br
spec:
  replicas: 1
  selector:
    matchLabels:
      app: minecraft-bedrock
  template:
    metadata:
      labels:
        app: minecraft-bedrock
    spec:
      containers:
        - name: minecraft-bedrock
          image: itzg/minecraft-bedrock-server:latest
          ports:
            - containerPort: 19132
              protocol: UDP
          env:
            - name: EULA
              value: "TRUE"
            - name: GAMEMODE
              value: "survival"
            - name: MAX_PLAYERS
              value: "10"
            - name: MOTD
              value: "Servidor Bedrock Minecraft!"
            - name: OPS
              value: "seu_username"
          volumeMounts:
            - mountPath: /data
              name: minecraft-bedrock-data
      volumes:
        - name: minecraft-bedrock-data
          persistentVolumeClaim:
            claimName: minecraft-bedrock-pvc
---
apiVersion: v1
kind: Service
metadata:
  name: minecraft-bedrock-service
  namespace: minecraft-br
spec:
  selector:
    app: minecraft-bedrock
  ports:
    - name: bedrock-udp
      port: 19132
      targetPort: 19132
      protocol: UDP
  type: LoadBalancer

Repare na estrutura, que junta vários conceitos já vistos ao longo da série:

Namespace (minecraft-br): isola os recursos do Minecraft Bedrock do restante do cluster;
PersistentVolumeClaim (10Gi): garante que o mundo salvo sobreviva a reinicializações e recriações do pod, sem isso, cada novo pod começaria com um mundo vazio;
Deployment: roda uma única réplica (replicas: 1), múltiplas réplicas de um mesmo mundo Minecraft não funcionam, já que o jogo não foi projetado para múltiplas instâncias acessando o mesmo save simultaneamente;
Service do tipo LoadBalancer, na porta UDP 19132, expondo o servidor para fora do cluster.

Em clusters on-premise, o tipo LoadBalancer normalmente não provisiona um IP automaticamente (isso é um recurso nativo de provedores de nuvem), é necessário um controlador como o MetalLB para que o Service realmente receba um IP externo utilizável. Sem isso, o Service ficará com o IP externo em estado <pending> indefinidamente.

Minecraft Java no Kubernetes

apiVersion: v1
kind: Namespace
metadata:
  name: minecraft-java
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: minecraft-pvc
  namespace: minecraft-java
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: minecraft-server
  namespace: minecraft-java
spec:
  replicas: 1
  selector:
    matchLabels:
      app: minecraft
  template:
    metadata:
      labels:
        app: minecraft
    spec:
      containers:
        - name: minecraft
          image: itzg/minecraft-server:latest
          ports:
            - containerPort: 25565
          env:
            - name: EULA
              value: "TRUE"
            - name: MEMORY
              value: "1G"
            - name: VERSION
              value: "latest"
            - name: MAX_PLAYERS
              value: "10"
            - name: MOTD
              value: "Bem-vindo ao servidor Minecraft"
            - name: ONLINE_MODE
              value: "TRUE"
            - name: WHITELIST
              value: "false"
            - name: OPS
              value: "seu_username"
          volumeMounts:
            - mountPath: /data
              name: minecraft-data
      volumes:
        - name: minecraft-data
          persistentVolumeClaim:
            claimName: minecraft-pvc
---
apiVersion: v1
kind: Service
metadata:
  name: minecraft-service
  namespace: minecraft-java
spec:
  selector:
    app: minecraft
  ports:
    - name: mc-tcp
      port: 25565
      targetPort: 25565
      protocol: TCP
  type: LoadBalancer

Diferente do Bedrock, aqui a porta do containerPort e do Service usam TCP (o padrão, quando protocol não é especificado no container, mas explicitado no Service para clareza), coerente com o fato de o Minecraft Java se comunicar via TCP, como vimos na Parte 2.

Alguns campos de ambiente específicos dessa imagem:

MEMORY: define o limite de memória passado para a JVM internamente pela imagem (equivalente ao -Xmx visto na instalação bare metal);
VERSION: permite fixar uma versão específica do Minecraft (por exemplo, "1.20.4") em vez de sempre usar a mais recente;
ONLINE_MODE: quando "TRUE", exige que os jogadores estejam autenticados com uma conta Microsoft/Mojang válida, desative apenas se souber exatamente por que precisa (geralmente para servidores com clientes piratas, o que tem implicações de segurança e legalidade).

Aplicando os manifestos

kubectl apply -f minecraft-bedrock.yaml
kubectl apply -f minecraft-java.yaml

Verificando se os pods subiram corretamente:

kubectl -n minecraft-br get po

e

kubectl -n minecraft-java get po

Acompanhando os logs de inicialização (o primeiro start baixa os arquivos do servidor, podendo levar alguns minutos):

kubectl -n minecraft-java logs -f deploy/minecraft-server

e

kubectl -n minecraft-br logs -f deploy/minecraft-bedrock-server

Considerações finais da série

Ao longo desta série, vimos o mesmo servidor Minecraft por três estágios: instalação manual bare metal, containerização com Docker, e por fim orquestração em um cluster Kubernetes. Cada estágio resolveu uma limitação do anterior, do gerenciamento manual de processos, passando por persistência e reinício automático, até chegar em armazenamento gerenciado e independência de um único host físico.

Vale reforçar um ponto importante que se aplica às três abordagens: por se tratar de um jogo com estado (o "mundo" salvo), não é possível escalar horizontalmente rodando múltiplas réplicas do mesmo servidor, diferente de uma API stateless, o Minecraft precisa de uma única instância consistente acessando o volume de dados por vez.

Servidor Minecraft - Parte 2: Rodando com Docker

Celso Nery — Fri, 21 Aug 2026 14:16:02 +0000

🇺🇸 English version comming soon

Servidor Minecraft - Parte 2: Rodando com Docker

Na Parte 1 desta série, instalamos o servidor Minecraft (Bedrock e Java) diretamente no sistema operacional, gerenciando o processo manualmente com screen/tmux. Neste artigo, damos um passo natural adiante: rodar o mesmo servidor em um container Docker, usando as imagens mantidas pela comunidade do projeto itzg/docker-minecraft-server e itzg/docker-minecraft-bedrock-server.

As vantagens em relação à instalação bare metal:

Reinício automático em caso de falha (restart: unless-stopped);
Persistência de dados isolada e explícita, via volumes;
Configuração declarativa, em um único arquivo versionável;
Isolamento do processo do restante do sistema.

Pré-requisito: Docker e Docker Compose já instalados. Se ainda não tiver, instale. Se não souber como, veja a minha série "Docker para desenvolvedores", la mostro na parte 1 como instalar o docker.

Rodando o Minecraft Bedrock com Docker

version: "3.8"

services:
  minecraft-bedrock:
    image: itzg/minecraft-bedrock-server:latest
    container_name: minecraft-bedrock-server
    restart: unless-stopped
    ports:
      - "19132:19132/udp"
    environment:
      EULA: "TRUE"
      GAMEMODE: "survival"
      MAX_PLAYERS: "10"
      MOTD: "Servidor Bedrock Minecraft!"
      WHITELIST: "false"
      OPS: "seu_username"
    volumes:
      - minecraft-bedrock-data:/data

volumes:
  minecraft-bedrock-data:
    driver: local

Pontos importantes:

ports: "19132:19132/udp": o Bedrock usa UDP, diferente da maioria dos serviços de rede, repare no sufixo /udp explícito;
EULA: "TRUE": aceita automaticamente a licença do Minecraft, evitando a etapa manual do eula.txt vista na Parte 1;
OPS: já concede permissão de operador ao usuário informado, na primeira inicialização;
minecraft-bedrock-data: volume nomeado, garantindo que o mundo e as configurações sobrevivam a atualizações e recriações do container.

Rodando o Minecraft Java com Docker

version: "3.8"

services:
  minecraft-java:
    image: itzg/minecraft-server:latest
    container_name: minecraft-java-server
    restart: unless-stopped
    ports:
      - "25565:25565"
    environment:
      EULA: "TRUE"
      GAMEMODE: "survival"
      MAX_PLAYERS: "10"
      MOTD: "Servidor Java Minecraft!"
      WHITELIST: "false"
      OPS: "seu_username"
    volumes:
      - minecraft-java-data:/data

volumes:
  minecraft-java-data:
    driver: local

Importante: diferente do Bedrock, o Minecraft Java usa TCP, não UDP, a porta deve ser mapeada como "25565:25565" (TCP é o protocolo padrão do Docker quando nenhum é especificado), sem o sufixo /udp.

Subindo os servidores

Cada servidor pode ficar em seu próprio arquivo docker-compose.yaml (recomendado, para gerenciá-los de forma independente) ou ambos no mesmo arquivo, como dois serviços distintos.

docker compose up -d

Acompanhando os logs de inicialização (o primeiro start pode demorar alguns minutos, baixando os arquivos do servidor):

docker compose logs -f

Gerenciando o servidor via console

As imagens do itzg incluem uma ferramenta de RCON (rcon-cli) embutida no container, permitindo executar comandos do servidor sem precisar anexar ao processo diretamente:

docker exec -it minecraft-java-server rcon-cli

Dentro do RCON, os mesmos comandos vistos na Parte 1 funcionam normalmente:

whitelist add novo_jogador
op novo_jogador

Para o Bedrock, o container também aceita comandos via send-command (dependendo da versão da imagem) ou diretamente pelas variáveis de ambiente WHITELIST e OPS no docker-compose.yaml, reiniciando o container para aplicar mudanças.

As imagens do itzg têm uma quantidade grande de variáveis de ambiente disponíveis (dificuldade, tipo de mundo, plugins, mods, etc.), vale consultar a documentação oficial de cada imagem no Docker Hub para a lista completa e atualizada, já que novas opções são adicionadas com frequência.

Repositório itzg no Docker Hub

Próximos passos

Com o Minecraft rodando em containers Docker, já temos reinício automático, persistência e configuração declarativa. Mas isso ainda roda em um único host, se a máquina cair, o servidor cai junto. Na Parte 3 desta série, vamos levar o mesmo servidor para dentro de um cluster Kubernetes, ganhando recursos como armazenamento gerenciado via PersistentVolumeClaim e a possibilidade de rodar em qualquer nó disponível do cluster.

Continua na Parte 3.

Servidor Minecraft - Parte 1: Instalação Bare Metal

Celso Nery — Fri, 21 Aug 2026 14:15:05 +0000

🇺🇸 English version comming soon

Servidor Minecraft - Parte 1: Instalação Bare Metal

Introdução

Rodar seu próprio servidor de Minecraft dá controle total sobre o jogo, mods, regras, mundo persistente, e nenhuma dependência de servidores de terceiros. Esta é a primeira parte de uma série que dará 3 opções de instalação: começamos aqui com a instalação bare metal (direto no sistema operacional), depois avançamos para Docker e, por fim, para Kubernetes.

Existem duas versões principais do jogo, com servidores incompatíveis entre si:

Bedrock Edition: multiplataforma (Windows, consoles, celular), usa o protocolo UDP;
Java Edition: a versão "clássica" para PC, com o maior ecossistema de mods e plugins, usa o protocolo TCP.

Vou cobrir a instalação de ambas.

Requisitos do sistema

Os requisitos variam principalmente com o número de jogadores simultâneos e se o mundo usa mods/plugins pesados:

Jogadores	RAM recomendada	CPU
1-5	2GB	2 cores
5-10	4GB	2-4 cores
10-20+	8GB+	4+ cores

A versão Java tende a consumir mais recursos que a Bedrock para o mesmo número de jogadores, especialmente com plugins como Spigot/Paper.

Instalando o Minecraft Bedrock Server

Download

Baixe o pacote oficial do servidor Bedrock para Linux diretamente da página oficial:

minecraft.net/download/server/bedrock

Após o download, extraia o arquivo .zip em um diretório dedicado:

mkdir -p ~/minecraft-bedrock
cd ~/minecraft-bedrock
unzip bedrock-server-*.zip
chmod +x bedrock_server

Rodando o servidor

LD_LIBRARY_PATH=. ./bedrock_server

O servidor Bedrock depende de bibliotecas compartilhadas no próprio diretório, por isso a variável LD_LIBRARY_PATH=. é necessária para ele encontrá-las corretamente.

Para manter o servidor rodando mesmo após fechar o terminal, use screen ou tmux:

screen -S minecraft-bedrock
LD_LIBRARY_PATH=. ./bedrock_server
# Ctrl+A, D para sair sem encerrar o processo

Configurando o servidor

As opções do servidor Bedrock ficam no arquivo server.properties, gerado automaticamente na primeira execução. A documentação completa de todas as propriedades disponíveis está na wiki oficial:

minecraft.fandom.com/wiki/Server.properties

Algumas das mais usadas:

server-name=Meu Servidor Bedrock
gamemode=survival
difficulty=normal
max-players=10
online-mode=true
white-list=false
level-name=Bedrock level

Após alterar o arquivo, reinicie o servidor para aplicar as mudanças.

Instalando o Minecraft Java Server

Pré-requisito: Java

O servidor Java precisa de uma JRE/JDK instalada, a versão exata depende da versão do Minecraft (versões mais recentes exigem Java 17 ou 21). Para instalar no Debian:

sudo apt install openjdk-21-jre-headless
java -version

Download

Baixe o server.jar da versão desejada na página oficial de downloads do Minecraft Java Server.

www.minecraft.net/en-us/download/server

mkdir -p ~/minecraft-java
cd ~/minecraft-java
# Baixe o server.jar correspondente à versão desejada para este diretório

Aceitando a EULA

Na primeira execução, o Minecraft cria um arquivo eula.txt e recusa iniciar até que você aceite os termos manualmente:

echo "eula=true" > eula.txt

Rodando o servidor

java -Xmx2G -Xms1G -jar server.jar nogui

-Xmx2G: memória máxima que a JVM pode usar;
-Xms1G: memória inicial alocada;
nogui: roda sem a interface gráfica, ideal para servidores.

Assim como no Bedrock, use screen ou tmux para manter o processo rodando em segundo plano.

Gerenciando o servidor

Lista de usuários (whitelist)

Restringir quem pode entrar no servidor é feito via whitelist.

No Bedrock, edite whitelist.json:

[
  { "name": "seu_username" }
]

E habilite no server.properties: white-list=true.

No Java, use o console do servidor (o terminal onde ele está rodando):

whitelist add seu_username
whitelist on

Permissões de usuários (ops)

Dar permissões de administrador (comandos de operador) também difere entre as versões.

No Bedrock, edite permissions.json:

[
  { "permission": "operator", "xuid": "seu_xuid" }
]

No Bedrock, é necessário o XUID do jogador (identificador da conta Xbox Live), não apenas o nome de usuário.

No Java, pelo console:

op seu_username

Expondo para a internet

Por padrão, o servidor só é acessível na rede local. Para permitir conexões externas:

Libere a porta no firewall da própria máquina:
- Bedrock: porta 19132/UDP
- Java: porta 25565/TCP
Configure o redirecionamento de porta (port forward) no seu roteador, apontando a porta externa para o IP interno da máquina que roda o servidor.

Criando um DNS dinâmico com No-IP

A maioria das conexões residenciais tem IP público dinâmico, ele muda periodicamente, quebrando o acesso de quem salvou o IP antigo. O No-IP resolve isso, associando um domínio fixo (por exemplo, meuservidor.ddns.net) ao seu IP atual, atualizado automaticamente.

Crie uma conta gratuita em noip.com;
Registre um hostname (por exemplo, meu-minecraft.ddns.net);
Instale o cliente DUC (Dynamic Update Client) no seu servidor ou roteador (muitos roteadores já têm suporte nativo a No-IP nas configurações de DNS dinâmico);
Compartilhe o hostname com seus amigos em vez do IP, ele continuará funcionando mesmo quando seu IP mudar.

Próximos passos

Com o servidor rodando bare metal, gerenciado manualmente com screen/tmux, já é possível jogar com amigos. Mas esse modelo tem limitações: sem isolamento, sem reinício automático em caso de falha, e configuração manual do zero se precisar migrar de máquina. Na Parte 2 desta série, vamos rodar o mesmo servidor em um container Docker, resolvendo esses problemas com uma configuração declarativa e reprodutível.

Continua na Parte 2.

Building an On-Premise Kubernetes Cluster - Part 7: Essential Production Features

Celso Nery — Wed, 19 Aug 2026 14:15:12 +0000

🇧🇷 Versão em português aqui

Building an On-Premise Kubernetes Cluster - Part 7: Essential Production Features

In previous parts of this series, we built the cluster from scratch and learned the basic structure of YAML manifests. But there's a real gap between "a Deployment that works" and "a Deployment ready for production." In this article, I cover a set of features I consider essential for that second scenario: Namespaces, Secrets, private registry authentication (regcred), RollingUpdate, SecurityContext, and Requests/Limits. At the end, we bring everything together in a real, complete Deployment example.

Namespace

A Namespace is a way to logically divide a single physical cluster into multiple "virtual clusters", useful for separating environments (production, staging, development) or different applications, preventing them from growing mixed together in a single space.

Creating a namespace:

$ kubectl create namespace aplicacao-prod

or

$ kubectl create ns aplicacao-prod

Or via manifest:

apiVersion: v1
kind: Namespace
metadata:
  name: aplicacao-prod

Listing existing namespaces:

$ kubectl get namespaces

or

$ kubectl get ns

From there, practically every object created (Deployments, Services, Secrets) can, and generally should, declare which namespace it lives in, through the metadata.namespace field or using the -n flag if it using by command line. This brings important benefits:

Name isolation: two Deployments named api can coexist peacefully, as long as they're in different namespaces;
Access control (RBAC): you can restrict what a user or an application can do, scoped to a specific namespace;
Organization: commands like kubectl get pods -n aplicacao-prod make it clear what belongs to which environment or application.

If you don't specify a namespace, Kubernetes uses the default namespace, which works for quick tests, but isn't recommended for real environments where multiple applications share the cluster.

Secrets

Secrets store sensitive data: passwords, tokens, API keys, in a slightly more protected way than a regular ConfigMap (the content is base64-encoded, and access can be restricted via RBAC).

Creating a Secret via the command line, from literal values:

kubectl create secret generic aplicacao-secret \
  --namespace=aplicacao-prod \
  --from-literal=DB_PASSWORD=mypassword \
  --from-literal=API_KEY=abc123

Or via a YAML manifest:

apiVersion: v1
kind: Secret
metadata:
  name: aplicacao-secret
  namespace: aplicacao-prod
type: Opaque
data:
  DB_PASSWORD: bXlwYXNzd29yZA==
  API_KEY: YWJjMTIz

Values in the data field need to be base64-encoded (echo -n 'mypassword' | base64). This isn't encryption, it's just an encoding, so treat the Secret's YAML file with the same care you'd treat a plain-text password file. Never commit (Git) a Secret with real values without some additional layer of protection, like Sealed Secrets or a secrets vault (Vault).

Consuming the Secret in the application

The most common approach is injecting the Secret's entire content as environment variables, using envFrom:

containers:
  - name: aplicacao
    image: mycompany/api:1.0.0
    envFrom:
      - secretRef:
          name: aplicacao-secret

This way, every key in the Secret (DB_PASSWORD, API_KEY) automatically becomes an environment variable inside the container.

Querying existing secrets

Besides creating them, it's common to need to query secrets that already exist in the cluster, either to confirm they were created correctly, or to debug a configuration issue.

$ kubectl -n <namespace> get secrets

This command lists all secrets in that namespace, showing name, type (Opaque, kubernetes.io/dockerconfigjson, etc.), and age, but it does not show their content.

Describing a specific secret

$ kubectl -n <namespace> describe secret <secret_name>

describe shows more complete information about a specific secret, including which keys exist inside it (DB_PASSWORD, API_KEY, etc.) and the size of each value in bytes. By security design, however, describe does not decode or display the actual value of any key, it only confirms it exists and how large its content is.

Viewing a secret's content

To actually see the value of a specific key, you need to extract the field via jsonpath and manually decode the base64:

$ kubectl -n <namespace> get secrets <secret_name> -o jsonpath='{.data.DB_PASSWORD}' | base64 -d

Use this command with caution, especially on shared or recorded terminals (like logged screen/tmux sessions, or shell history saved in plain text). The decoded value appears in plain text directly in the terminal output.

Regcred - Credentials for a Private Registry

When an application's images are stored in a private registry, whether a self-hosted registry, or a paid plan on Docker Hub or another provider, Kubernetes needs credentials to be able to pull those images when creating pods. That's what the imagePullSecret is for, commonly created under the name regcred.

The safest approach is to use a GitLab Deploy Token (instead of your personal password), it can be scoped to read-only permission (read_registry) and restricted to a specific project or group.

Creating the secret with the Deploy Token:

There are two ways to create this secret: via the command line (faster) or via a YAML file (more suitable when you need to version or automate its creation).

Option 1: creating via command line

kubectl create secret docker-registry regcred \
  -n aplicacao-prod \
  --docker-server=registry.yourcompany.com \
  --docker-username=<deploy-token-username> \
  --docker-password=<deploy-token-password> \
  --docker-email=your-email@yourcompany.com

Where:

-n namespace: namespace where the secret will be created (the secret is scoped to that namespace);
--docker-server: private registry address;
--docker-username / --docker-password: access credentials;
--docker-email: email associated with the account (required by the command, even if not always used in practice).

Option 2: creating via YAML file

If you'd rather (or need to) version this configuration, you can manually build the secret as a YAML file.

1. Create a config.json file with the registry credentials:

{
    "auths": {
        "registry.yourcompany.com": {
      "username": "<deploy-token-username>",
      "password": "<deploy-token-password>",
      "email": "your-email@yourcompany.com"
    }
    }
}

2. Convert the file to base64, since that's how Kubernetes expects the secret content:

$ cat config.json | base64 -w 0

3. Create the regcred.yaml file, pasting the result of the command above into the .dockerconfigjson field:

apiVersion: v1
kind: Secret
metadata:
  name: regcred
  namespace: namespace
type: kubernetes.io/dockerconfigjson
data:
  .dockerconfigjson: ewoJImF1dGhzIjogewoJCSJyZWdpc3RyeS5zdWFlbXByZXNhLmNvbSI6IHsKICAgICAgInVzZXJuYW1lIjogIjxkZXBsb3ktdG9rZW4tdXNlcm5hbWU+IiwKICAgICAgInBhc3N3b3JkIjogIjxkZXBsb3ktdG9rZW4tcGFzc3dvcmQ+IiwKICAgICAgImVtYWlsIjogInNldS1lbWFpbEBzdWFlbXByZXNhLmNvbSIKICAgIH0KCX0KfQo=

Never commit (Git) a regcred.yaml file with real credentials: even though it's base64-encoded, that's not encryption, just an encoding: anyone with access to the file can decode it and recover the original password. Treat this value as a genuinely sensitive secret, using tools like Sealed Secrets, Vault, or environment variables from your CI/CD pipeline.

4. Apply the secret to the cluster:

$ kubectl apply -f regcred.yaml

Using regcred in a Deployment

Reference the secret in the Deployment through imagePullSecrets:

spec:
  imagePullSecrets:
    - name: regcred
  containers:
    - name: aplicacao
      image: registry.gitlab.com/organization/aplicacao:v1.0.0

The imagePullSecrets field points to the regcred secret created earlier, and it needs to be in the same namespace as the Pod or Deployment that will use it.

RollingUpdate

By default, a Deployment already uses the RollingUpdate strategy when updating an application's version, gradually replacing old pods with new ones, without full downtime. But the exact parameters of this process can (and should) be tuned:

spec:
  minReadySeconds: 10
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 1

maxSurge: how many pods above the desired replica count can be temporarily created during the update (here, 1 extra pod);
maxUnavailable: how many pods can be unavailable at the same time during the update (here, at most 1);
minReadySeconds: the minimum time (in seconds) a new pod needs to stay "ready" (passing health checks) before being considered available, this prevents the rollout from moving too fast with pods that came up but haven't stabilized yet.

These values should be tuned based on the application's criticality: more conservative values (maxUnavailable: 0) guarantee zero downtime during deployment, at the cost of requiring more temporary capacity in the cluster (via maxSurge).

I have encountered downtime issues with Java applications because the new replica took too long to become available.

SecurityContext

The securityContext defines security restrictions on how a Pod or container can run, reducing the attack surface in case the application is compromised. It can be set both at the Pod level (applied to all containers) and at the container level (more specific, overrides the Pod's setting).

spec:
  securityContext:
    runAsUser: 5000
    runAsGroup: 5000
  containers:
    - name: aplicacao
      securityContext:
        allowPrivilegeEscalation: false

runAsUser / runAsGroup (Pod level): forces processes to run with a specific UID/GID, instead of root, reduces potential damage if an attacker manages to execute code inside the container;
allowPrivilegeEscalation: false (container level): prevents a process inside the container from gaining more privileges than it already has (for example, through binaries with the setuid bit).

Other common options worth considering, depending on the application:

readOnlyRootFilesystem: true: makes the container's root filesystem read-only, forcing any writes to go to explicitly mounted volumes;
capabilities.drop: ["ALL"]: removes all Linux capabilities by default, adding back only the ones strictly necessary.

Requests / Limits

Without defining requests and limits, a container could, in theory, consume all resources available on the node it's running on, hurting other applications on the same cluster (or even bringing down the node itself).

resources:
  requests:
    memory: "128Mi"
    cpu: "100m"
  limits:
    memory: "512Mi"
    cpu: "1000m"

requests: the amount of resources Kubernetes reserves for the container when deciding which node to schedule it on. The scheduler only places the pod on a node that has that amount available;
limits: the maximum ceiling the container can consume. Exceeding the memory limit results in the container being killed (OOMKilled); exceeding the CPU limit results in throttling (the container is slowed down, but not killed).

100m of CPU means 100 millicores, i.e., 0.1 of a core. Setting realistic requests (based on the application's observed usage) matters, requests that are too high waste cluster capacity; requests that are too low can lead to more pods running simultaneously than a node can actually support.

Real-world application Deployment example

Bringing together everything covered in this part: a dedicated namespace, secrets, private registry authentication, a tuned rolling update, a restrictive securityContext, and defined requests/limits, plus the Service and HorizontalPodAutoscaler already covered in previous parts:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: aplicacao
  namespace: aplicacao-prod
spec:
  minReadySeconds: 10
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 1
  replicas: 2
  selector:
    matchLabels:
      app: aplicacao
  template:
    metadata:
      labels:
        app: aplicacao
    spec:
      securityContext:
        runAsUser: 5000
        runAsGroup: 5000
      containers:
      - name: aplicacao
        image: registry.yourcompany.com/organization/api:v9346
        envFrom:
          - secretRef:
              name: aplicacao-secret
        securityContext:
          allowPrivilegeEscalation: false
        resources:
          requests:
            memory: "128Mi"
            cpu: "100m"
          limits:
            memory: "512Mi"
            cpu: "1000m"
        ports:
        - containerPort: 8080
      imagePullSecrets:
        - name: regcred
---
apiVersion: v1
kind: Service
metadata:
  name: aplicacao
  namespace: aplicacao-prod
spec:
  selector:
    app: aplicacao
  ports:
  - protocol: TCP
    port: 8080
    targetPort: 8080
  type: NodePort
---
apiVersion: autoscaling/v1
kind: HorizontalPodAutoscaler
metadata:
  name: aplicacao-hpa
  namespace: aplicacao-prod
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: aplicacao
  minReplicas: 2
  maxReplicas: 5
  targetCPUUtilizationPercentage: 75

The three objects work together:

The Deployment runs the application with 2 replicas, authenticating with the private registry via regcred and injecting sensitive configuration via aplicacao-secret;
The Service exposes those replicas in a stable way on port 8080;
The HorizontalPodAutoscaler monitors those replicas' CPU usage and automatically adjusts between 2 and 5, based on demand.

Final thoughts

These features: namespaces, secrets, secure registry authentication, a tuned rollout strategy, security restrictions, and resource limits, are typically what separates a standard manifest from one ready to run a application in production. It's worth reviewing each of these points whenever you're about to promote an application from staging to production.

Montando um Cluster Kubernetes On-Premise - Parte 7: Recursos Essenciais para Produção

Celso Nery — Wed, 19 Aug 2026 14:13:17 +0000

🇺🇸 English version here.

Montando um Cluster Kubernetes On-Premise - Parte 7: Recursos Essenciais para Produção

Nas partes anteriores desta série, aprendemos a estrutura básica dos recursos do kubernetes e manifestos YAML. Mas existe uma distância entre "um Deployment que funciona" e "um Deployment para produção". Neste artigo, vou abordar recursos que considero indispensáveis nesse segundo cenário: Namespaces, Secrets, autenticação com registries privados (regcred), RollingUpdate, SecurityContext e Requests/Limits. No final, juntamos tudo em um exemplo real e completo de Deployment.

Namespace

Um Namespace é uma forma de dividir logicamente um único cluster físico em múltiplos "clusters virtuais", útil para separar ambientes (produção, homologação, desenvolvimento) ou aplicações diferentes, evitando que cresçam misturadas em um espaço só.

Criando um namespace:

$ kubectl create namespace aplicacao-prod

ou 

$ kubectl create ns aplicacao-prod

Ou via manifesto:

apiVersion: v1
kind: Namespace
metadata:
  name: aplicacao-prod

Listando os namespaces existentes:

$kubectl get namespaces

ou

$kubectl get ns

A partir daí, praticamente todo objeto criado (Deployments, Services, Secrets) pode, e geralmente deve-se declarar em qual namespace ele vive, através do campo metadata.namespace ou a flag -n se for via linha de comando. Isso traz benefícios importantes:

Isolamento de nomes: dois Deployments chamados api podem coexistir tranquilamente, desde que estejam em namespaces diferentes;
Controle de acesso (RBAC): é possível restringir o que um usuário ou uma aplicação pode fazer, escopado a um namespace específico;
Organização: comandos como kubectl get pods -n aplicacao-prod deixam claro o que pertence a qual ambiente ou aplicação.

Se você não especificar um namespace, o Kubernetes usa o namespace default, o que funciona para testes rápidos, mas não é recomendado para ambientes reais, onde múltiplas aplicações compartilham o cluster.

Secrets

Secrets armazenam dados sensíveis: senhas, tokens, chaves de API, de forma um pouco mais protegida que um ConfigMap comum (o conteúdo fica codificado em base64, e o acesso pode ser restrito via RBAC).

Criando um Secret via linha de comando, a partir de valores literais:

kubectl create secret generic aplicacao-secret \
  --namespace=aplicacao-prod \
  --from-literal=DB_PASSWORD=minhasenha \
  --from-literal=API_KEY=abc123

Ou via manifesto YAML:

apiVersion: v1
kind: Secret
metadata:
  name: aplicacao-secret
  namespace: aplicacao-prod
type: Opaque
data:
  DB_PASSWORD: bWluaGFzZW5oYQ==
  API_KEY: YWJjMTIz

Os valores no campo data precisam estar em base64 (echo -n 'minhasenha' | base64). Isso não é criptografia, é apenas uma codificação, então trate o arquivo YAML do Secret com o mesmo cuidado que trataria um arquivo de senhas em texto puro. Nunca versione (Git) um Secret com valores reais sem alguma camada adicional de proteção, como Sealed Secrets ou um cofre de segredos (Vault).

Consumindo o Secret na aplicação

A forma mais comum é injetar todo o conteúdo do Secret como variáveis de ambiente, usando envFrom:

containers:
  - name: aplicacao
    image: minhaempresa/api:1.0.0
    envFrom:
      - secretRef:
          name: aplicacao-secret

Dessa forma, cada chave do Secret (DB_PASSWORD, API_KEY) vira automaticamente uma variável de ambiente dentro do container.

Listando as secrets de um namespace

$ kubectl -n <namespace> get secrets

Esse comando lista todas as secrets existentes naquele namespace, mostrando nome, tipo (Opaque, kubernetes.io/dockerconfigjson, etc.) e idade, mas não mostra o conteúdo delas.

Detalhando uma secret específica

$ kubectl -n <namespace> describe secret <nome_da_secret>

O describe mostra informações mais completas sobre uma secret específica, incluindo quais chaves existem dentro dela (DB_PASSWORD, API_KEY, etc.) e o tamanho de cada valor em bytes. Por design de segurança, porém, o describe não decodifica nem exibe o valor real de nenhuma chave, apenas confirma que ela existe e qual o tamanho do conteúdo.

Vistualizando o conteúdo de uma secret

Para efetivamente ver o valor de uma chave específica, é preciso extrair o campo via jsonpath e decodificar o base64 manualmente:

kubectl -n <namespace> get secrets <nome_da_secret> -o jsonpath='{.data.DB_PASSWORD}' | base64 -d

Use esse comando com cautela, principalmente em terminais compartilhados ou gravados (como sessões de screen/tmux logadas, ou históricos de shell salvos em texto puro). O valor decodificado aparece em texto puro diretamente na saída do terminal.

Regcred - Credenciais para Registry Privado

Quando as imagens de uma aplicação estão armazenadas em um registro privado, seja um registro próprio, seja um plano pago do Docker Hub ou de outro provedor, Kubernetes precisa de credenciais para conseguir baixar (pull) essas imagens ao criar os pods. É para isso que existe o imagePullSecret, comumente criado com o nome regcred.

O jeito mais seguro é usar um Deploy Token do GitLab (em vez da sua senha pessoal), ele pode ser restrito a permissão somente leitura (read_registry) e escopado a um projeto ou grupo específico.

Criando o secret com o Deploy Token:

Existem duas formas de criar esse secret: via linha de comando (mais rápida) ou via arquivo YAML (mais indicada quando você precisa versionar ou automatizar essa criação).

Opção 1: criando via linha de comando

kubectl create secret docker-registry regcred \
  -n aplicacao-prod \
  --docker-server=registry.suaempresa.com \
  --docker-username=<deploy-token-username> \
  --docker-password=<deploy-token-password> \
  --docker-email=seu-email@suaempresa.com

Onde:

-n namespace: namespace onde o secret será criado (o secret fica restrito a esse namespace);
--docker-server: endereço do registro privado;
--docker-username / --docker-password: credenciais de acesso;
--docker-email: e-mail associado à conta (obrigatório pelo comando, ainda que não seja sempre usado na prática).

Opção 2: criando via arquivo YAML

Se você prefere (ou precisa) versionar essa configuração, é possível montar o secret manualmente como um arquivo YAML.

1. Crie um arquivo config.json com as credenciais do registro:

{
    "auths": {
        "registry.suaempresa.com": {
      "username": "<deploy-token-username>",
      "password": "<deploy-token-password>",
      "email": "seu-email@suaempresa.com"
    }
    }
}

2. Converta o arquivo para base64, já que é assim que o Kubernetes espera o conteúdo do secret:

$ cat config.json | base64 -w 0

3. Crie o arquivo regcred.yaml, colando o resultado do comando acima no campo .dockerconfigjson:

apiVersion: v1
kind: Secret
metadata:
  name: regcred
  namespace: namespace
type: kubernetes.io/dockerconfigjson
data:
  .dockerconfigjson: ewoJImF1dGhzIjogewoJCSJyZWdpc3RyeS5zdWFlbXByZXNhLmNvbSI6IHsKICAgICAgInVzZXJuYW1lIjogIjxkZXBsb3ktdG9rZW4tdXNlcm5hbWU+IiwKICAgICAgInBhc3N3b3JkIjogIjxkZXBsb3ktdG9rZW4tcGFzc3dvcmQ+IiwKICAgICAgImVtYWlsIjogInNldS1lbWFpbEBzdWFlbXByZXNhLmNvbSIKICAgIH0KCX0KfQo=

Nunca versione (Git) um arquivo regcred.yaml com credenciais reais - mesmo estando em base64, isso não é criptografia, apenas uma codificação: qualquer pessoa com acesso ao arquivo consegue decodificar e recuperar a senha original. Trate esse valor como um segredo sensível de verdade, usando ferramentas como Sealed Secrets, Vault ou variáveis de ambiente do seu pipeline de CI/CD.

4. Aplique o secret no cluster:

$ kubectl apply -f regcred.yaml

Usando o regcred em um Deployment

Referencie o secret no Deployment através de imagePullSecrets:

spec:
  imagePullSecrets:
    - name: regcred
  containers:
    - name: aplicacao
      image: registry.gitlab.com/organizacao/aplicacao:v1.0.0

O campo imagePullSecrets aponta para o secret regcred criado anteriormente, e ele precisa estar no mesmo namespace do Pod ou Deployment que vai usá-lo.

RollingUpdate

Por padrão, um Deployment já usa a estratégia RollingUpdate ao atualizar a versão de uma aplicação, substituindo os pods antigos pelos novos de forma gradual, sem downtime completo. Mas os parâmetros exatos desse processo podem (e devem) ser ajustados:

spec:
  minReadySeconds: 10
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 1

maxSurge: quantos pods a mais do que o número de réplicas desejado podem ser criados temporariamente durante a atualização (aqui, 1 pod extra);
maxUnavailable: quantos pods podem ficar indisponíveis simultaneamente durante a atualização (aqui, no máximo 1);
minReadySeconds: tempo mínimo (em segundos) que um novo pod precisa ficar "pronto" (passando nos health checks) antes de ser considerado disponível, isso evita que o rollout avance rápido demais com pods que subiram mas ainda não estabilizaram.

Esses valores devem ser calibrados de acordo com a criticidade da aplicação: valores mais conservadores (maxUnavailable: 0) garantem zero indisponibilidade durante o deploy, ao custo de exigir mais capacidade temporária no cluster (via maxSurge).

Já presenciei problemas com downtime em aplicações java, pelo fato da nova réplica demorar a ficar disponível.

SecurityContext

O securityContext define restrições de segurança sobre como um Pod ou container pode rodar, reduzindo a superfície de ataque caso a aplicação seja comprometida. Ele pode ser definido tanto no nível do Pod (aplicado a todos os containers) quanto no nível do container (mais específico, sobrepõe o do Pod).

spec:
  securityContext:
    runAsUser: 5000
    runAsGroup: 5000
  containers:
    - name: aplicacao
      securityContext:
        allowPrivilegeEscalation: false

runAsUser / runAsGroup (nível Pod): força os processos a rodarem com um UID/GID específico, em vez de root, reduz o dano potencial caso um invasor consiga executar código dentro do container;
allowPrivilegeEscalation: false (nível container): impede que um processo dentro do container obtenha mais privilégios do que os que já possui (por exemplo, através de binários com bit setuid).

Outras opções comuns que vale considerar, dependendo da aplicação:

readOnlyRootFilesystem: true: torna o sistema de arquivos raiz do container somente leitura, forçando qualquer escrita a ir para volumes explicitamente montados;
capabilities.drop: ["ALL"]: remove todas as capabilities do Linux por padrão, adicionando de volta apenas as estritamente necessárias.

Requests / Limits

Sem definir requests e limits, um container pode, teoricamente, consumir todos os recursos disponíveis no nó onde está rodando, prejudicando outras aplicações no mesmo cluster (ou até derrubando o próprio nó).

resources:
  requests:
    memory: "128Mi"
    cpu: "100m"
  limits:
    memory: "512Mi"
    cpu: "1000m"

requests: a quantidade de recursos que o Kubernetes reserva para o container ao decidir em qual nó agendá-lo. O scheduler só coloca o pod em um nó que tenha essa quantidade disponível;
limits: o teto máximo que o container pode consumir. Ultrapassar o limite de memória resulta no container sendo finalizado (OOMKilled); ultrapassar o limite de CPU resulta em throttling (o container é desacelerado, mas não finalizado).

100m de CPU significa 100 milicores, ou seja, 0.1 de um núcleo. Definir requests realistas (baseados no consumo observado da aplicação) é importante, requests muito altos desperdiçam capacidade do cluster, requests muito baixos podem levar a mais pods do que o nó realmente suporta rodando simultaneamente.

Exemplo de Deployment de uma aplicação real

Juntando tudo o que vimos nesta parte: namespace dedicado, secrets, autenticação com registry privado, rolling update calibrado, securityContext restritivo e requests/limits definidos, mais o Service e o HorizontalPodAutoscaler já vistos em partes anteriores:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: aplicacao
  namespace: aplicacao-prod
spec:
  minReadySeconds: 10
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 1
  replicas: 2
  selector:
    matchLabels:
      app: aplicacao
  template:
    metadata:
      labels:
        app: aplicacao
    spec:
      securityContext:
        runAsUser: 5000
        runAsGroup: 5000
      containers:
      - name: aplicacao
        image: registry.suaempresa.com.br/organizacao/api:v1234
        envFrom:
          - secretRef:
              name: aplicacao-secret
        securityContext:
          allowPrivilegeEscalation: false
        resources:
          requests:
            memory: "128Mi"
            cpu: "100m"
          limits:
            memory: "512Mi"
            cpu: "1000m"
        ports:
        - containerPort: 8080
      imagePullSecrets:
        - name: regcred
---
apiVersion: v1
kind: Service
metadata:
  name: aplicacao
  namespace: aplicacao-prod
spec:
  selector:
    app: aplicacao
  ports:
  - protocol: TCP
    port: 8080
    targetPort: 8080
  type: NodePort
---
apiVersion: autoscaling/v1
kind: HorizontalPodAutoscaler
metadata:
  name: aplicacao-hpa
  namespace: aplicacao-prod
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: aplicacao
  minReplicas: 2
  maxReplicas: 5
  targetCPUUtilizationPercentage: 75

Os três objetos trabalham juntos:

O Deployment roda a aplicação com 2 réplicas, autenticando no registry privado via regcred e injetando configurações sensíveis via aplicacao-secret;
O Service expõe essas réplicas de forma estável na porta 8080;
O HorizontalPodAutoscaler monitora o uso de CPU dessas réplicas e ajusta automaticamente entre 2 e 5, conforme a demanda.

Considerações finais

Esses recursos: namespaces, secrets, autenticação segura com registries, estratégia de rollout calibrada, restrições de segurança e limites de recursos, são o que normalmente separa um manifesto comum de um manifesto para rodar uma aplicação crítica em produção. Vale revisar cada um desses pontos sempre que for promover uma aplicação de homologação para produção.

Docker - Part 6: Automating with Docker Compose

Celso Nery — Tue, 18 Aug 2026 23:16:51 +0000

🇧🇷 Artigo em português aqui

Using Docker - Part 6: Orchestrating with Docker Compose

Throughout this series, we've covered containers, volumes, networks, and image management, always using individual commands like docker run, docker network create, docker volume create, etc. That works, but it becomes tedious (and error-prone) once an application starts depending on multiple services. That's where Docker Compose comes in: it lets you describe all of this configuration in a single declarative file, making the process cleaner, easier to repeat, and easier to version in a Git repository.

Creating your docker-compose.yaml

A minimal docker-compose.yaml

The simplest possible structure, running a single service:

services:
  web:
    image: httpd
    ports:
      - "80:80"

This is already equivalent to running docker run -p 80:80 httpd, but in a declarative, reapplyable, and easily versioned way.

Adding a volume

To persist that service's data (as we saw in Part 3 of this series), just add a volumes section:

services:
  web:
    image: httpd
    ports:
      - "80:80"
    volumes:
      - web-data:/usr/local/apache2/htdocs

volumes:
  web-data:

Notice the volume needs to be declared in two places: referenced inside the service (volumes: under web) and defined in the root-level volumes: section at the end of the file, that's where Compose actually creates the named volume.

Adding a network

Likewise, you can declare custom networks (covered in Part 4):

services:
  web:
    image: httpd
    ports:
      - "80:80"
    volumes:
      - web-data:/usr/local/apache2/htdocs
    networks:
      - app-network

volumes:
  web-data:

networks:
  app-network:

In practice, when you don't explicitly declare a network, Compose already creates a default network for the project automatically, allowing services within the same docker-compose.yaml to see each other by name. Declaring networks manually is worth it when you need more than one isolated network, or want to connect services across different Compose files.

Bringing up the containers

To create and start all the services defined in the file:

$ docker compose up

Just like with docker run, the terminal stays "stuck," showing the logs of all services. To run it in the background:

$ docker compose up -d

Tearing down the containers

To stop and remove the containers and networks, while (by default) preserving the volumes created by Compose:

$ docker compose down

By default, docker compose down does not remove volumes, this prevents accidental data loss. If you want to remove volumes too, use docker compose down -v (with caution).

Bringing multiple containers together: App + Database + Redis

Compose's real power shows up when an application depends on multiple services working together. A common example: an Nginx proxy in front, an application, a MySQL database, and a Redis cache.

services:
  nginx:
    image: nginx:latest
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
    depends_on:
      - app
    networks:
      - app-network

  app:
    image: myapp:1.0.0
    environment:
      DB_HOST: db
      DB_USER: appuser
      DB_PASSWORD: apppassword
      REDIS_HOST: redis
    depends_on:
      - db
      - redis
    networks:
      - app-network

  db:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: rootpassword
      MYSQL_DATABASE: appdb
      MYSQL_USER: appuser
      MYSQL_PASSWORD: apppassword
    volumes:
      - db-data:/var/lib/mysql
    networks:
      - app-network

  redis:
    image: redis:alpine
    networks:
      - app-network

volumes:
  db-data:

networks:
  app-network:

A few important points from this example:

depends_on: defines the startup order of the containers (app only starts after db and redis). Note this only guarantees the starting order of the container, not that the internal service (like MySQL) is already ready to accept connections, for that, the application usually needs to implement some retry logic on the database connection;
Environment variables (environment): used to configure the application and MySQL without needing to modify images or hardcode values;
db-data: a named volume ensuring MySQL's data survives container restarts and recreations;
app-network: all services share the same network, letting them communicate with each other by service name (db, redis) instead of fixed IPs.

Bringing everything up at once:

$ docker compose up -d

With a single command, Compose creates the network, the volumes, and brings up all four containers already connected and ready to talk to each other.

Series wrap-up

Throughout this series, we covered the complete day-to-day Docker lifecycle: installation, essential CLI commands, data persistence with volumes, container-to-container communication via networks, image management and publishing, and finally, orchestrating multiple services with Docker Compose. With this foundation, you now have everything you need to run containerized applications professionally, whether in a local development environment or on a production server.

For anyone looking to go beyond a single host, the natural next step is Kubernetes, which solves the same orchestration problems, but at scale, distributing containers across multiple servers.

Docker - Part 5: Managing Images

Celso Nery — Tue, 18 Aug 2026 23:15:22 +0000

🇧🇷 Artigo em português aqui

Using Docker - Part 5: Managing Images

In Part 4 of this series, we covered how containers communicate through networks. Now let's tackle the lifecycle of Docker images: how to build your own, list the ones already available locally, version them correctly, and publish them to a registry, whether Docker Hub or a private registry.

Building an image

To build an image from a Dockerfile:

$ docker build -t <image_name>:<version> -f dockerfile .

Where:

-t <image_name>:<version>: sets the name and tag (version) of the resulting image; if the version is released, a 'latest' version will be created;
-f dockerfile: specifies which Dockerfile to use (useful when you have multiple Dockerfiles in the same directory, or a non-default filename); if there is only one Dockerfile at the project root, this argument can be omitted;
.: sets the build context, the directory whose contents become available to instructions like COPY and ADD inside the Dockerfile.

Dockerfile example:

FROM nginx:alpine
RUN apk update && apk upgrade --no-cache
WORKDIR /usr/share/nginx/html
COPY ./index.html ./
EXPOSE 80
CMD [ "nginx", "-g", "daemon off;" ]

FROM: Specifies the base image to be used.
RUN: Commands to execute in order to build the application before building the image.
WORKDIR: Specifies the internal location within the image where operations are currently taking place.
COPY: Command to copy files from the local application into the Docker image.
EXPOSE: Specifies the port the container will listen on.
CMD: Command for the final execution of the application. (In this case, I am running Nginx).

Listing images

To see all images already downloaded or built locally:

$ docker image ls

Versioning images (tag)

Before publishing an image to a registry, you generally need to "tag" it with the full destination address:

$ docker tag <local_image_name>:<version> <remote_registry>/<remote_image_name>:<version>

For example, tagging a local myapp:1.0.0 image for Docker Hub, under the user celsonery:

$ docker tag myapp:1.0.0 celsonery/myapp:1.0.0

Or for a private registry:

$ docker tag myapp:1.0.0 registry.yourcompany.com/myapp:1.0.0

It's considered good practice to use semantic versioning in your tags (1.0.0, 1.0.1, 1.1.0) instead of relying solely on the latest tag, since latest doesn't indicate exactly which version is running in production.

Removing images

To remove a specific image:

$ docker image rm <image_name>:<version>

Cleaning up unused images

Intermediate images and images no longer referenced by any container tend to pile up over time, taking up disk space. To clean up:

$ docker image prune

Publishing an image (push)

To publish an image, you must first authenticate with a registry.

Docker Hub (default)

$ docker login

Private registry

When the destination isn't Docker Hub, you need to provide the server address:

$ docker login registry.yourcompany.com

Push to Docker Hub

$ docker push <image_name>:<version>

Push to a private registry

$ docker push <registry>/<image_name>:<version>

Remember: the image needs to have been tagged (previous step) with the full destination registry address before the push, otherwise, Docker will try to send it to Docker Hub by default.

Next steps

With the complete image lifecycle covered, build, tag, push, you can now distribute your own applications as versioned images. In Part 6, the last of this series, we'll bring everything we've covered together (volumes, networks, multiple containers) using Docker Compose, making it much simpler and more organized to manage applications with multiple services.

Continued in Part 6.

Docker - Part 4: Working with Networks

Celso Nery — Tue, 18 Aug 2026 23:13:48 +0000

🇧🇷 Artigo em português aqui

Using Docker - Part 4: Working with Networks

In Part 3 of this series, we covered persisting data with volumes. Now let's tackle another fundamental pillar of multi-container applications: networking. When an application depends on several services (for example, an API that needs to talk to a database), those containers need to be able to communicate with each other, and that's what Docker networks make possible.

Listing networks

Docker already creates a few default networks on installation (bridge, host, none). To list all existing networks:

$ docker network ls

Creating a network

To create a custom network, isolated from the others:

$ docker network create <network_name>

Containers connected to the same custom network can communicate with each other using the container name as the hostname, no need to discover or hardcode IP addresses manually.

Inspecting a network

To see details about a network, such as the IP range, driver used, and which containers are connected to it:

$ docker network inspect <network_name>

Running a container already connected to a network

To create a container and connect it to a specific network right at creation time:

$ docker run -it -d --rm --net <network_name> httpd

Connecting a running container to a network

If the container is already running and you want to add it to an additional network (a container can belong to multiple networks at once):

$ docker network connect --ip 192.168.100.10 <network_name> httpd

The --ip flag lets you pin a specific IP for the container within that network, useful when other applications need a predictable address to connect to.

Disconnecting a container from a network

$ docker network disconnect <network_name> httpd

Removing a network

$ docker network rm <network_name>

A network can only be removed if no container is currently connected to it.

Cleaning up unused networks

Just like with volumes, it's common to accumulate orphaned networks over time. To remove all networks not currently used by any container:

$ docker network prune

Why this matters

Running isolated containers without a custom network works fine for quick tests, but as soon as an application needs multiple services talking to each other (app + database + cache, for example), custom networks stop being optional. They provide isolation (containers from different projects can't see each other by default) and simple name-based communication, without relying on manually managed fixed IPs.

Next steps

With volumes for persistence and networks for communication between containers, we now have the two fundamental pieces needed to run multi-service applications. In Part 5 of this series, we'll cover image management: how to build, version (tag), and publish your own images to a registry.

Continued in Part 5.

Docker - Part 3: Persisting Data with Volumes

Celso Nery — Tue, 18 Aug 2026 23:12:00 +0000

🇧🇷 Artigo em português aqui

Using Docker - Part 3: Persisting Data with Volumes

In Part 2 of this series, we covered the essential commands for operating containers day to day. But there's an important detail: by default, data written inside a container is ephemeral, if the container is removed, that data disappears with it. For stateful applications (databases, user uploads, configuration files), that's a problem. That's what volumes exist to solve.

Bind mount vs. Volume

There are two main ways to persist data outside a container's lifecycle:

Bind mount: mounts a specific folder from the host (the machine running Docker) inside the container. You have full control over where the data lives on the host, but you become more dependent on that specific machine's folder structure.
Volume: managed by Docker itself, stored in an internal area (/var/lib/docker/volumes/ on Linux). This is the recommended approach for most cases, since it's more portable across environments and easier to back up, inspect, and clean up.

This article focuses on volumes, the recommended approach for professional use.

Creating a volume

To create a named volume that will store an application's data:

docker volume create vol_name

Listing volumes

To see all volumes that already exist on the system:

docker volume ls

Inspecting a volume

To see details about a specific volume, such as the actual path where the data is stored on the host:

docker volume inspect vol_name

Running a container with a volume `-v`

Using a bind mount

docker run --rm -d -it -v local_folder:remote_folder httpd

Here, local_folder is an absolute path on the host (for example, /home/celso/data), and remote_folder is the path inside the container where that data should appear (for example, /var/www/htdocs/).

Using a created volume

docker run --rm -d -it -v volume_name:remote_folder httpd

In this case, volume_name is the name of the volume created earlier with docker volume create, Docker handles where that data is physically stored.

Removing a volume

If any container is still using the volume, you'll need to remove the container first:

docker rm <container_name>

Then, to remove the volume:

docker volume rm vol_name

Cleaning up unused volumes

Over time, it's common to accumulate orphaned volumes (created by containers that have since been removed). To clean up all volumes not currently used by any container:

docker volume prune

This command permanently removes the data of any volume not referenced by an active container, confirm before running this on an environment with important data.

Using NFS volumes

In environments with multiple Docker hosts (or when you want to share data across different servers), you can create a volume pointing to an NFS share instead of local storage:

docker volume create --opt type=nfs --opt o=addr=10.0.0.35,rw,nfsvers=4 --opt device=:/home/nfsshare nfs-volume

Where:

type=nfs: sets the volume driver to NFS;
o=addr=10.0.0.35,rw,nfsvers=4: NFS server address and mount options (read/write, protocol version);
device=:/home/nfsshare: path exported by the NFS server;
nfs-volume: name given to the volume in Docker.

This is especially useful in scenarios where multiple containers (possibly on different hosts) need access to the same shared data set.

Next steps

With volumes handling data persistence, the next challenge is communication between containers, especially when an application depends on multiple services (for example, an API that needs to talk to a database). In Part 4 of this series, we'll look at how to create and manage networks in Docker.

Continued in Part 4.