DEV Community: Celso Nery

On-Premise Kubernetes: Setting Up a Local Docker Image Registry

Celso Nery — Thu, 30 Jul 2026 00:49:18 +0000

In on-premise Kubernetes clusters, it doesn't always make sense to rely on Docker Hub (or any public cloud registry) to store application images — whether for security reasons, limited internet connectivity, or simply to keep everything within your own infrastructure. In this article, I show how to set up a local Docker image registry, both in a simple version (for testing) and in a version with authentication (closer to a real-world scenario).

⚠️ The steps below use a registry without TLS, suitable only for testing environments. For production, configuring a certificate and TLS connection is essential — never expose a registry without encryption in production.

Initial configuration

Before starting the registry, you need to tell Docker it can trust an "insecure" registry (without TLS). This needs to be configured on the server running the registry and on every node in the cluster that will use it.

Edit the /etc/docker/daemon.json file, providing the host (IP or machine name) and the registry's port:

{
    "insecure-registries": [ "host:port" ]
}

Then restart the Docker service to apply the change:

# systemctl restart docker

Creating the registry server

The simplest way to spin up a registry is by running the official registry image as a container:

$ docker run -d -p 5000:5000 --restart=always --name=repository registry

Explaining each option:

Option	Purpose
`-d`	Runs the container in the background (daemon)
`-p 5000:5000`	Maps port 5000 of the container to port 5000 of the host
`--restart=always`	Automatically restarts the container in case of failure
`--name=repository`	Name given to the container
`registry`	Official image used to run the registry server

Testing the registry

To confirm the registry is up, just access it through the browser:

http://registry.zion.local:5000/v2/

An empty JSON response ({}) already indicates the service is working correctly.

Publishing an image to the local registry

1. List the locally available images:

$ docker image ls

2. Tag the image, pointing it to the local registry's address — in the example, the image oregontecnologia/myapp-api:

$ docker tag oregontecnologia/myapp-api registry.zion.local:5000/myapp-api

3. Push the image to the local registry:

$ docker push registry.zion.local:5000/myapp-api

Using the local registry's image in Kubernetes

With the image published, you can already create a Deployment in the cluster pointing directly to the local registry:

$ kubectl create deploy myapp-api --image=registry.zion.local:5000/myapp-api

And confirm the pod came up correctly:

$ kubectl get pods -o wide

If Kubernetes can't pull the image (ImagePullBackOff error), check whether insecure-registries was configured on all nodes of the cluster — not just on the server running the registry —, since any worker could be chosen to schedule the pod.

Leveling up: registry with authentication

The example above is functional, but with no protection whatsoever — anyone with network access can push or pull images. For a more realistic scenario, let's add authentication via htpasswd.

Creating the credentials

First, install the htpasswd utility (part of the apache2-utils package):

$ sudo apt install apache2-utils

Create a folder to store the password file:

$ mkdir ~/home-user/auth && cd $_

Create the registry.password file, adding the first user with the -c flag (which creates the file) and -B (which uses bcrypt encryption):

$ htpasswd -Bc registry.password username

To add other users afterward, don't use the -c flag again (it would overwrite the file):

$ htpasswd -B registry.password new_username

Running the authenticated registry with Docker Compose

Instead of a single docker run command, an authenticated registry is better organized as a docker-compose.yml:

$ vim docker-compose.yml

version: '3'

services:
  registry:
    image: registry:2
    ports:
    - "5000:5000"
    environment:
      REGISTRY_AUTH: htpasswd
      REGISTRY_AUTH_HTPASSWD_REALM: Registry
      REGISTRY_AUTH_HTPASSWD_PATH: /auth/registry.password
      REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY: /data
    volumes:
      - ./auth:/auth
      - ./data:/data
    restart: always

This file:

Uses the official registry:2 image;
Enables authentication via htpasswd, pointing to the password file created earlier;
Persists images in a local volume (./data), preventing data loss if the container is recreated.

Start the service:

$ docker-compose up

Testing the authenticated registry

http://server-name-or-ip:5000/v2

When trying to access it, the browser (or docker login) should prompt for a username and password — confirming that authentication is active.

Final thoughts

Having a local image registry gives more control and independence to the on-premise cluster, especially in environments without unrestricted internet access or with stricter security policies. The authenticated version via htpasswd is already a good starting point for real environments — but for production, it's worth adding TLS and, depending on scale, considering more robust solutions like Harbor, which adds features like granular access control, vulnerability scanning, and registry replication.

If your cluster needs to automatically authenticate against a private registry (public or local) when pulling images, also check out the article on configuring an imagePullSecret with regcred on Kubernetes.

Building an On-Premise Kubernetes Cluster — Part 6: Deploying, Updating, and Scaling Your Own Application

Celso Nery — Thu, 30 Jul 2026 00:30:09 +0000

🇧🇷 Leia a versão em português aqui

In Part 5 of this series, we validated the cluster end to end by deploying Nginx. Now let's go one step further: build a custom application's Docker image, publish it, get it running in the cluster, and explore day-to-day operations — version updates, rollback, and scalability (both manual and automatic).

As an example, we used a simple REST API (myapp.war), built with Spring Boot, purely for illustration — the process applies to any application packaged as a container image.

Building the application's Docker image

The first step is writing the application's Dockerfile. In this example, a lightweight base image (alpine) was used, with Java 11 installed to run the application:

FROM alpine
WORKDIR /opt/app
RUN apk update && apk add vim openjdk11-jre
COPY runapp.sh .
CMD ash runapp.sh

Building the image

docker image build -t oregontecnologia/myapp-api:1.0.0 .

Publishing the image

Before using the image in the cluster, it needs to be available in some registry — either Docker Hub or a private registry. If you'd rather host your own on-premise registry (recommended for corporate environments or those without internet access), check out the companion article on creating a local registry server.

To publish to Docker Hub:

docker login

username:
password:

docker push oregontecnologia/myapp-api:1.0.0

Deploying the application

With the image published, you can check the cluster's current state before proceeding:

kubectl get pods -o wide
kubectl get deploy -o wide

Create the Deployment directly from the command line, pointing to the published image:

kubectl create deploy myapp-deploy --image=oregontecnologia/myapp-api:1.0.0

Unlike previous examples in this series (where we used YAML files with kubectl apply -f), here the Deployment is created directly via the command line with kubectl create deploy. Both approaches are valid — YAML files are more suitable when you need to version and consistently reapply configurations.

Exposing the application externally

To make the application accessible outside the cluster, create a LoadBalancer-type Service, associating a fixed external IP:

kubectl expose deploy myapp-deploy --type=LoadBalancer --external-ip=10.0.10.100 --port=80

In on-premise environments, the LoadBalancer type usually doesn't provision a load balancer automatically (that's a native feature of cloud providers). That's why here we manually provide an external IP (--external-ip) already available on the local network.

Removing the application

If you need to remove the Deployment:

kubectl delete deploy myapp-deploy

Updating and rolling back application versions

One of Kubernetes' great advantages is managing updates in a controlled way, with no perceptible downtime (rolling update).

Updating to a new version

kubectl set image deployments/myapp-deploy myapp-api=oregontecnologia/myapp-api:1.0.2 --record

This command updates the myapp-api container's image inside the Deployment to version 1.0.2. The --record flag records the command in the Deployment's revision history, which makes it easier to later identify what changed in each rollout.

Rolling back to the previous version

If the new version causes problems, you can quickly roll back to the previous revision:

kubectl rollout undo deployments/myapp-deploy

Scaling the application

Manual scaling

To manually adjust the number of running replicas — for example, to 3:

kubectl scale deploy myapp-deploy --replicas=3

Automatic scaling (HPA)

To let Kubernetes itself automatically adjust the number of replicas based on CPU usage, you can configure a Horizontal Pod Autoscaler (HPA). In the example below, the cluster starts with 2 replicas and can scale up to 10, whenever average CPU utilization exceeds 75%:

kubectl autoscale deploy myapp-deploy --min=2 --max=10 --cpu-percent=75

Adjust the --min, --max, and --cpu-percent values according to your cluster's actual capacity and your application's expected behavior.

To check the autoscaler's current state:

kubectl get hpa

This command shows, among other things, the current CPU usage relative to the configured target, and the number of replicas currently running.

To remove the autoscaler:

kubectl delete hpa myapp-deploy

Now, let's put this entire manual process into a YAML file to make things easier.

Throughout this series, we've used several .yaml files to create Deployments, Services, and other objects in the cluster. In this article, let's take a step back and understand the basic structure of these manifests — what's mandatory in every file, how to find the correct apiVersion, and what the main object types we've already used look like in practice: Pod, ReplicaSet, Deployment, and Service.

The minimum structure of a manifest

Every Kubernetes object, regardless of type, is described by a YAML with four main fields:

apiVersion: 
kind: 
metadata: 
spec:

apiVersion: the Kubernetes API version used to create that object (e.g., v1 or apps/v1);
kind: the type of object being created (Pod, Deployment, Service, etc.);
metadata: the object's metadata — name, labels, namespace, and more;
spec: the actual specification of the object — for a Pod, for example, this is where the containers live.

How to find the correct apiVersion

Each object type (kind) belongs to a specific apiVersion, and this can vary between Kubernetes versions. To check which resources are available in your cluster and which API each one belongs to, use:

$ kubectl api-resources

This command lists all resources supported by the cluster, along with the corresponding API group (the APIVERSION column) — it's the most reliable source for knowing which apiVersion to use in each manifest, since this can change depending on the installed Kubernetes version.

Watch out for indentation

YAML is a format sensitive to indentation — unlike {} braces or [] brackets, the data hierarchy is defined purely by spacing. Because of this:

Never use TABs to indent a YAML file — always use spaces.
The recommended standard (and the one used in the examples below) is 2 spaces per indentation level.
metadata and spec are mappings (key-value pairs), not lists — meaning their internal fields (name, labels, etc.) should not start with a -.

This last point is a common mistake: it's easy to confuse lists (which use -) with simple mappings. In the Pod example below, notice that name and labels sit directly under metadata, with no dash.

Pod

The most basic Kubernetes object is the Pod — the smallest unit that can be created and managed in the cluster, containing one or more containers.

apiVersion: v1
kind: Pod
metadata:
  name: mypod
  labels:
    app: mypod-label
spec:
  containers:
    - name: myapp-api
      image: oregontecnologia/myapp-api:1.0.2

Creating the object: create vs apply

There are two main commands for applying a manifest to the cluster:

$ kubectl create -f file.yaml
$ kubectl apply -f file.yaml

The difference between them matters:

create only creates the object if it doesn't already exist — if the object was already created previously, the command returns an error.
apply creates the object if it doesn't exist, or updates the existing object if there's any change in the manifest. Because of this, apply is the most commonly used command day-to-day, since it lets you reapply the same file continuously as it evolves.

Checking the creation

$ kubectl get pods

The -o wide flag shows additional information about the running pod, such as the node it's running on and its internal IP.

To see all details of a pod or deployment (including recent events, which helps a lot when debugging issues):

$ kubectl describe pod myapp-api

Or, for a deployment:

$ kubectl describe deploy myapp-deploy

ReplicaSet

A single Pod doesn't automatically recover if it fails. That's where the ReplicaSet comes in: an object responsible for ensuring a defined number of replicas of the same Pod is always running.

apiVersion: apps/v1
kind: ReplicaSet
metadata:
  name: myreplicaset
spec:
  replicas: 5
  selector:
    matchLabels:
      app: mypod-label
  template:
    metadata:
      labels:
        app: mypod-label
    spec:
      containers:
        - name: myapp-api
          image: oregontecnologia/myapp-api:1.0.2

Notice the structure is a bit more nested than the Pod's: inside spec, we have the selector (which defines which Pods belong to this ReplicaSet, based on labels) and the template (which describes how each replica of the Pod should be created).

Checking the creation:

$ kubectl get replicaset

In practice, it's rare to create ReplicaSets directly — they're normally managed automatically by a Deployment, which we'll cover next. Still, understanding this layer helps in understanding how Kubernetes guarantees Pod availability.

Deployment

The Deployment is the most common way to run applications on Kubernetes. It manages ReplicaSets automatically, adding features like rolling updates and rollback — which we already saw in practice in Part 6 of this series.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mydeploy
spec:
  replicas: 5
  selector:
    matchLabels:
      app: mypod-label
  template:
    metadata:
      labels:
        app: mypod-label
    spec:
      containers:
        - name: myapp-api
          image: oregontecnologia/myapp-api:1.0.2

Notice the structure is practically identical to the ReplicaSet's — which makes sense, since a Deployment creates and manages ReplicaSets behind the scenes. The difference lies in the kind and the additional functionality the Deployment offers.

Checking the creation:

$ kubectl get deploy

Service

Finally, the Service is the object responsible for exposing Pods in a stable way, with a fixed address, regardless of how many times the Pods are recreated.

apiVersion: v1
kind: Service
metadata:
  name: myservice
spec:
  selector:
    app: mypod-label
  ports:
    - port: 80
  type: LoadBalancer  # ClusterIP | NodePort | LoadBalancer

The type field defines how the service will be exposed:

ClusterIP (default): exposes the service only internally, within the cluster;
NodePort: exposes the service on a fixed port across all cluster nodes (we used this type in Part 5, with Nginx);
LoadBalancer: requests an external load balancer — in the cloud, automatically provisioned by the provider; on-premise, it usually requires a manually configured IP or a solution like MetalLB.

Checking the creation:

$ kubectl get services

Summary

Object	Main function
Pod	Minimum unit of execution (one or more containers)
ReplicaSet	Guarantees a fixed number of replicas of a Pod
Deployment	Manages ReplicaSets, with support for rolling updates and rollback
Service	Exposes Pods in a stable way, with a fixed IP and name

Understanding this hierarchy — Pod → ReplicaSet → Deployment, plus the Service as the exposure layer — is the foundation for confidently reading (and writing) any Kubernetes manifest, regardless of the application's complexity.

This wraps up the more conceptual content of this series. In upcoming articles, we'll keep exploring practical, day-to-day topics of running an on-premise cluster.

Closing the operational loop

With deploying a custom application, controlled updates, rollback, and scalability (manual and automatic) covered, we've walked through the most common day-to-day operations of an on-premise Kubernetes cluster. From here, the cluster is ready not just to host applications, but to operate them resiliently as demand grows.

This concludes the more conceptual content of this series. In the upcoming articles, we will continue exploring practical topics related to the day-to-day operations of an on-premise cluster.

In the next articles of the series, we will delve into topics such as private on-premise image registries, persistent storage, and cluster observability.

Adding and removing a worker from the cluster.
Creating a registry server for your Docker images.
Renewing the Kubernetes certificate.
Useful add-ons for your Kubernetes cluster.
Metrics Server
NGINX Ingress Controller
Cert-Manager
Portainer
Prometheus
Grafana

Building an On-Premise Kubernetes Cluster — Part 5: Deploying Your First Container

Celso Nery — Thu, 30 Jul 2026 00:30:00 +0000

🇧🇷 Leia a versão em português aqui

In previous parts of this series, we built the cluster from scratch: prepared the environment (Part 1), installed containerd and Kubernetes (Part 2), initialized the control-plane (Part 3), and joined the workers (Part 4). With the cluster up and all nodes in Ready state, it's time to actually put it to work: let's deploy our first application.

In this article, we'll use Nginx as an example — a classic use case for validating that the cluster is working end to end, from pod creation to service exposure.

Organizing the files

First, create a directory to organize this deployment's manifests:

mkdir nginx
cd nginx

Keeping Kubernetes manifests organized in per-application directories is a good practice that makes maintenance and versioning (e.g., with Git) easier as the cluster grows.

Creating the Deployment

A Deployment is the Kubernetes object responsible for managing pod replicas, ensuring the desired number of instances is always running — and handling things like rolling updates and automatic recovery in case of failure.

Create the file nginx-deployment.yaml with the following content:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  labels:
    app: nginx
spec:
  replicas: 2
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.14.0
        ports:
        - containerPort: 80

This manifest defines:

2 replicas of the Nginx pod (replicas: 2), distributed across the available workers;
A selector that ties the Deployment to the pods via the app: nginx label;
The nginx:1.14.0 image, exposing container port 80.

Applying the Deployment

With the file saved, apply it to the cluster:

kubectl apply -f nginx-deployment.yaml

kubectl will create the Deployment, and from there Kubernetes takes care of scheduling the 2 pods across the available workers.

Checking the Deployment

To confirm the Deployment was created and has the desired number of replicas running:

kubectl get deployments

And, for more complete details (events, conditions, rollout strategy, etc.):

kubectl describe deployment nginx-deployment

If everything's fine, you should see all 2 replicas ready (2/2) in the availability column.

Creating the Service

The Deployment alone isn't enough to access the application from outside the cluster — pods are ephemeral and their IPs change every time they're recreated. That's what the Service is for: a stable access point that routes traffic to the correct pods, based on labels.

Create the file nginx-service.yaml:

apiVersion: v1
kind: Service
metadata:
  name: nginx-service
  labels:
    run: nginx-service
spec:
  type: NodePort
  ports:
  - port: 80
    protocol: TCP
  selector:
    app: nginx

Here, the NodePort type is used to expose the service on a port directly accessible through any node's IP in the cluster — a simple and practical option for on-premise environments, without relying on an external load balancer (unlike the LoadBalancer type, more common in cloud providers).

Applying the Service

kubectl apply -f nginx-service.yaml

Checking the Service

kubectl get service

This command shows, among other information, the external port (NodePort) automatically allocated by Kubernetes — usually in the range between 30000 and 32767.

For more details:

kubectl describe service nginx-service

With the port in hand, Nginx can now be accessed through the IP of any node in the cluster (master or workers) on the indicated port — for example: http://10.0.10.100:<nodeport>.

What we validated here

If you managed to access Nginx's default page through the NodePort, this confirms the whole cluster is working correctly end to end:

The control-plane is scheduling pods normally;
The pod network (CNI) is allowing communication between components;
kube-proxy is routing the Service's traffic to the correct pods;
The workers are running containers without issues.

Wrap-up

With this, we've covered the essentials for building and validating an on-premise Kubernetes cluster from scratch: environment preparation, component installation, control-plane initialization, worker joining, and the first real application deployment.

From here, natural next steps include topics like persistent storage (Persistent Volumes), Ingress Controllers, configuration and secrets management (ConfigMaps and Secrets), monitoring (Prometheus/Grafana), and cluster backup strategies (like etcd backups). This is left as a suggestion for a possible continuation of this series.

If you've followed all five articles up to here, you now have a functional on-premise Kubernetes cluster, built and validated from scratch — without depending on any cloud provider.

Now, in Part 6 of this series, we’ll spin up the container with our application and understand how everything works.

Continued in Part 6.

Building an On-Premise Kubernetes Cluster — Part 4: Joining the Worker Nodes

Celso Nery — Thu, 30 Jul 2026 00:29:50 +0000

🇧🇷 Leia a versão em português aqui

In previous parts, we prepared the environment (Part 1), installed containerd and Kubernetes (Part 2), and initialized the control-plane on the master server, including the pod network (Part 3). Now let's close the basic cluster lifecycle: join the worker servers to the master and confirm everything is working correctly.

Joining the worker nodes

On each worker server you want to add to the cluster, run the kubeadm join command generated at the end of the master initialization (seen in Part 3). It looks like this:

kubeadm join 10.0.10.100:6443 --token 9e0xeu.s0if3... --discovery-token-ca-cert-hash sha256:3a328e56729515d...

This command uses the token and the certificate hash to authenticate the worker with the control-plane and safely allow it to join the cluster.

What if I lost the token?

kubeadm tokens expire by default after 24 hours. If you didn't save the token (or it has already expired), no problem — you can generate a new join command at any time, from the master:

# kubeadm token create --print-join-command

This creates a new token and returns the full join command, ready to be copied and run on the workers.

Checking the cluster nodes

After running kubeadm join on all the workers, go back to the master and check whether the nodes were added correctly:

kubectl get nodes

Or, for a more detailed output (internal IP address, kernel version, container runtime, etc.):

kubectl get nodes -o wide

The -o wide flag adds extra information to the standard output.

The output should look like this:

All nodes should show up with Ready status. If any worker shows up as NotReady, it's worth checking whether the pod network (CNI) was applied correctly and whether containerd is running without errors on that node.

Dealing with unwanted taints

In some cases, a node may end up marked with a taint that prevents new pods from being scheduled on it — for example, when Kubernetes detects disk pressure (disk-pressure). This is common in lab environments with small disks or little free space.

To check whether a specific node has this taint (in the example below, node3):

kubectl --kubeconfig=/home/celso/.kube/config.bagarote describe node node3 | grep Taint

If the disk-pressure taint is present and you want to manually remove that restriction (being aware that the node might be low on disk space), run:

kubectl --kubeconfig=/home/celso/.kube/config.bagarote taint node node3 node.kubernetes.io/disk-pressure:NoSchedule-

The trailing - at the end of the command is what removes the taint — without it, the command would add a new taint instead of removing one.

⚠️ Manually removing a disk-pressure taint is a stopgap measure. The right approach is to investigate and fix the root cause (free up disk space, add more storage, etc.), since Kubernetes applies this taint as a protection against failures caused by lack of space.

Closing the loop

With the workers joined and all nodes in Ready state, the on-premise Kubernetes cluster is officially up: control-plane running, pod network active, and workers ready to receive workloads.

This wraps up the foundation of this series — environment preparation, component installation, master initialization, and worker joining. From here, the cluster is ready for the natural next steps of any Kubernetes environment: application deployments, persistent storage configuration, ingress controllers, monitoring, and more.

If you've followed this series up to this point, you now have a functional on-premise Kubernetes cluster, built from scratch, without depending on any cloud provider.

Now, in Part 5 of this series, we will spin up containers and test whether everything is working and handling the workload normally.

Continued in Part 5.

Building an On-Premise Kubernetes Cluster — Part 3: Initializing the Master

Celso Nery — Thu, 30 Jul 2026 00:29:40 +0000

🇧🇷 Leia a versão em português aqui

In previous parts of this series, we prepared the environment (Part 1) and installed containerd, kubelet, and kubeadm on all nodes (Part 2). Now it's time to finally initialize the cluster: we'll create the control-plane on the master server and get it ready to accept workers and a functional pod network.

Initializing the cluster with kubeadm

The simplest way to initialize the cluster is to run the command below on the master server:

# kubeadm init

Or, specifying important parameters manually — such as the pod network CIDR, the IP address to be advertised by the API server, and the Kubernetes version:

# kubeadm init --pod-network-cidr=10.244.0.0/16 --apiserver-advertise-address=10.0.10.100 --kubernetes-version="1.31.1"

Using a configuration file (recommended)

More recent versions of kubelet no longer accept certain options via the command line (this behavior has been deprecated). Because of this, the current recommendation is to create a configuration file for kubeadm, instead of passing everything via flags.

Create the kubelet.yaml file:

apiVersion: kubeadm.k8s.io/v1beta3
kind: InitConfiguration
---
apiVersion: kubeadm.k8s.io/v1beta3
kind: ClusterConfiguration
kubernetesVersion: "1.31.1" # Replace with your desired version
controlPlaneEndpoint: "k8s-master"
---
apiVersion: kubelet.config.k8s.io/v1beta1
kind: KubeletConfiguration

And run the initialization pointing to that file:

$ sudo kubeadm init --config kubelet.yaml

What to expect from the output

If everything goes well, the command's output will look similar to this (summarized here for readability):

[init] Using Kubernetes version: v1.31.1
[preflight] Running pre-flight checks
[preflight] Pulling images required for setting up a Kubernetes cluster
[preflight] This might take a minute or two, depending on the speed of your internet connection
[preflight] You can also perform this action in beforehand using 'kubeadm config images pull'

[kubelet-start] Writing kubelet environment file with flags to file "/var/lib/kubelet/kubeadm-flags.env"
[kubelet-start] Writing kubelet configuration to file "/var/lib/kubelet/config.yaml"
[kubelet-start] Activating the kubelet service
[certs] Using certificateDir folder "/etc/kubernetes/pki"
[certs] Generating "ca" certificate and key
[certs] Generating "apiserver-kubelet-client" certificate and key

...

[bootstraptoken] configured RBAC rules to allow certificate rotation for all node client certificates in the cluster
[bootstraptoken] creating the "cluster-info" ConfigMap in the "kube-public" namespace
[addons] Applied essential addon: CoreDNS
[addons] Applied essential addon: kube-proxy

Your Kubernetes master has initialized successfully!

To start using your cluster, you need to run the following as a regular user:

  mkdir -p $HOME/.kube
  sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
  sudo chown $(id -u):$(id -g) $HOME/.kube/config

You should now deploy a pod network to the cluster.
Run "kubectl apply -f [podnetwork].yaml" with one of the options listed at:
  https://kubernetes.io/docs/concepts/cluster-administration/addons/

Then you can join any number of worker nodes by running the following on each as root:

kubeadm join 10.0.10.100:6443 --token d1dyaj.31zxywbg93s1ywjy --discovery-token-ca-cert-hash sha256:71a91721595fde66b6382908d801266602a14de8e16bdb7a3cede21509427009

⚠️ Important: save the full kubeadm join command (with the token and certificate hash) shown at the end of the output. You'll need it to add the workers to the cluster.

Setting up kubectl access

To use kubectl as a regular user (without needing sudo every time), copy the administrator's configuration file:

mkdir -p $HOME/.kube
cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
chown $(id -u):$(id -g) $HOME/.kube/config

To check the current state of the cluster, run:

kubectl get pods --all-namespaces

At this point, it's normal for some pods to show up as Pending — that's because we haven't installed a pod network (CNI) yet, which is exactly the next step.

Output example:

Installing the pod network (CNI)

Kubernetes doesn't ship with a ready-made networking solution — you need to choose and install a network plugin (CNI), responsible for allowing communication between the cluster's pods. Some popular options are Calico, Canal, Flannel, and Weave.

Use only one of the options above — installing more than one CNI on the same cluster can cause network conflicts.

Example with Calico:

kubectl apply -f https://raw.githubusercontent.com/projectcalico/calico/v3.28.2/manifests/calico.yaml

Example with Flannel:

kubectl apply -f https://raw.githubusercontent.com/flannel-io/flannel/v0.20.2/Documentation/kube-flannel.yml

Example with Weave:

export kubever=$(kubectl version | base64 | tr -d '\n')
kubectl apply -f "https://cloud.weave.works/k8s/net?k8s-version=$kubever"

kubectl apply -f https://github.com/weaveworks/weave/releases/download/v2.8.1/weave-daemonset-k8s.yaml

After applying the chosen manifest, run again:

kubectl get pods --all-namespaces

And, within a few moments, the pods in the kube-system namespace — including CoreDNS — should switch to Running status. This confirms the pod network is working correctly.

The output must be the same as this.:

Next steps

With the control-plane initialized, kubectl configured, and the pod network installed, the cluster's master is now fully operational. Only one step remains: adding the worker servers to the cluster using the kubeadm join command we saved earlier.

In Part 4 of this series, we'll join the workers to the cluster and confirm all nodes are ready to receive workloads.

Continued in Part 4.

Building an On-Premise Kubernetes Cluster — Part 2: Installing Containerd and Kubernetes

Celso Nery — Thu, 30 Jul 2026 00:29:28 +0000

🇧🇷 Leia a versão em português aqui

In Part 1 of this series, we prepared the environment: defined the hardware, configured /etc/hosts, adjusted the firewall, and disabled SWAP on all nodes. Now that the foundation is ready, it's time to install the container runtime (containerd) and the Kubernetes packages themselves (kubelet and kubeadm).

All the steps below should be run on all servers in the cluster — master and workers — unless stated otherwise.

Loading kernel modules

Kubernetes, through containerd, depends on two Linux kernel modules: overlay (for the layered filesystem used by containers) and br_netfilter (so that bridge network traffic passes through iptables rules).

For these modules to load automatically on every boot, create the file /etc/modules-load.d/containerd.conf:

overlay
br_netfilter

And, to load them immediately (without needing a reboot), run:

$ sudo modprobe overlay
$ sudo modprobe br_netfilter

Adjusting kernel network parameters

Create the file /etc/sysctl.d/99-kubernetes-k8s.conf with the following parameters:

net.bridge.bridge-nf-call-iptables = 1
net.ipv4.ip_forward = 1
net.bridge.bridge-nf-call-ip6tables = 1

These parameters ensure that network traffic between pods and services is correctly routed and filtered by Kubernetes.

To apply the settings without restarting the server:

$ sudo sysctl --system

Installing containerd

Containerd is the container runtime used by the cluster. In this case, we'll install it through Docker's official repository, using only the containerd.io package (without installing full Docker).

1. Download the repository's GPG key:

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/docker.gpg

2. Create the repository file at /etc/apt/sources.list.d/docker.list:

deb [arch=amd64] https://download.docker.com/linux/debian bullseye stable

3. Update the package list and install containerd:

sudo apt-get update
sudo apt-get install containerd.io

4. Generate the default containerd config file:

$ sudo containerd config default > /etc/containerd/config.toml

5. Enable the systemd cgroup driver

Edit the file /etc/containerd/config.toml:

sudo vim /etc/containerd/config.toml

And change the SystemdCgroup option from false to true. This adjustment matters because the kubelet, by default, also uses systemd as its cgroup driver — keeping them aligned avoids instability in container resource management.

6. Restart containerd to apply the changes:

sudo systemctl restart containerd

Installing Kubernetes

With containerd running, the next step is installing the Kubernetes components: kubelet and kubeadm.

1. Add the Kubernetes repository GPG key:

curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.31/deb/Release.key | gpg --dearmor -o /etc/apt/trusted.gpg.d/kubernetes-gpg-keyring.gpg

2. Add the Kubernetes repository, creating the file /etc/apt/sources.list.d/kubernetes.list:

deb [signed-by=/etc/apt/trusted.gpg.d/kubernetes-gpg-keyring.gpg] http://pkgs.k8s.io/core:/stable:/v1.31/deb/ /

Note: this series uses Kubernetes version 1.31. If you want to install a different version, just swap the v1.31 in the URL above for the desired version.

3. Update the package list:

sudo apt update

4. Install Kubernetes:

sudo apt install kubelet kubeadm

5. Hold the packages' version, to prevent them from being automatically upgraded (which could break the cluster's compatibility):

sudo apt-mark hold kubelet kubeadm

6. Enable the kubelet to auto-start on boot:

sudo systemctl enable kubelet

Limiting image storage

By default, the kubelet can accumulate container images over time, consuming disk space. To prevent this, you can configure image garbage collection limits in the /var/lib/kubelet/kubeadm-flags.env file:

vim /var/lib/kubelet/kubeadm-flags.env

Add the flags:

--image-gc-high-threshold=60 --image-gc-low-threshold=50

This tells the kubelet to start removing unused images once the disk reaches 60% usage, stopping the cleanup once it drops to 50%.

Next steps

With containerd installed and configured with the correct cgroup driver, and with kubelet and kubeadm ready on all nodes, we now have everything needed to initialize the cluster.

In Part 3 of this series, we'll use kubeadm init to create the control-plane on the master server and then join the workers to the cluster.

Continued in Part 3.

Building an On-Premise Kubernetes Cluster — Part 1: Preparing the Environment

Celso Nery — Thu, 30 Jul 2026 00:29:12 +0000

🇧🇷 Leia a versão em português aqui

This is the first part of a series where I'll share, step by step, how I built my own on-premise Kubernetes cluster, without relying on any cloud provider. The goal is to document the whole process — from environment preparation to a working cluster — as a reference for anyone studying the topic or looking to replicate the same setup at home or at work.

I used VPS (Virtual Private Server) and VM (Virtual Machine) for this cluster. However, it can also be set up on physical machines (Bare Metal).

Bye the end of this series, it will be easier to understand cloud clusters on AWS (EKS), Google (GKE) and Azure (AKS).

In this first part, we'll cover everything needed before installing any Kubernetes component: hardware requirements, basic network configuration, firewall rules, and a few mandatory operating system adjustments.

Requirements

The following topology was used for this cluster:

3 servers in total
1 master server (control-plane): 2 CPUs (cores) and 2 GB of RAM
2 worker servers (slaves): 1 CPU and 1 GB of RAM each
Root access on all machines

This is a minimal setup, ideal for study, lab, or testing environments. For production, resources should be scaled according to expected load.

Configuring the hosts file

Before installing anything, it's important for the machines to resolve each other by name, not just by IP. Edit the /etc/hosts file on all servers and add the corresponding entries:

10.0.10.100  master.company.local    master
10.0.10.101  slave01.company.local   slave01
10.0.10.102  slave02.company.local   slave02

This ensures that, later on, the Kubernetes components can correctly resolve node names.

Configuring the Firewall

Kubernetes depends on specific ports being open between nodes so the control-plane can communicate with the workers (and vice versa). The ports vary depending on the server's role in the cluster.

On the master server:

Port	Protocol
6443	TCP
2379-2380	TCP
10250	TCP
10251	TCP
10252	TCP
10253	TCP

On the worker servers (slaves):

Port	Protocol
10251	TCP
10255	TCP

Make sure to open these ports in the firewall tool you're using (ufw, firewalld, iptables, etc.), according to your chosen Linux distribution.

Disabling SWAP

Kubernetes requires SWAP to be disabled on all cluster nodes. This is because the kubelet doesn't correctly manage memory when SWAP is active, which can cause unexpected behavior in pod scheduling.

First, check if SWAP is active:

# swapon -s

If it is, disable it:

# swapoff -a

However, this deactivation is temporary — it won't survive a reboot. To make the change permanent, edit the /etc/fstab file and comment out the line referring to SWAP:

#/dev/mapper/master--vg-swap_1 none swap    sw  0   0

Testing communication between nodes

With /etc/hosts configured, it's worth confirming the servers can communicate with each other before moving on:

# ping slave01
# ping slave02

If the pings succeed (round trip), the network environment is ready.

Restarting the servers

Finally, to make sure all changes (especially disabling SWAP) are properly applied, restart each server:

# shutdown -r now

or 

# reboot

Next steps

With the environment prepared — hardware defined, network configured, firewall adjusted, and SWAP disabled — we now have the foundation needed to start installing the actual Kubernetes components.

In Part 2 of this series, we'll install the container runtime and the Kubernetes packages (kubeadm, kubelet, and kubectl) on all nodes.

Continued in Part 2.

Kubernetes On-Premise: Criando um Registro de Imagens Docker Local

Celso Nery — Wed, 29 Jul 2026 19:09:43 +0000

Em clusters Kubernetes on-premise, nem sempre faz sentido depender do Docker Hub (ou de qualquer registro público na nuvem) para armazenar as imagens das aplicações — seja por questões de segurança, de conectividade limitada com a internet, ou simplesmente para manter tudo dentro da própria infraestrutura. Neste artigo, mostro como subir um registro de imagens Docker local, tanto em uma versão simples (para testes) quanto em uma versão com autenticação (mais próxima de um cenário real).

⚠️ O passo a passo abaixo usa um registro sem TLS, adequado apenas para ambientes de teste. Para produção, é essencial configurar um certificado e conexão TLS — nunca exponha um registro sem criptografia em produção.

Configuração inicial

Antes de subir o registro, é preciso avisar o Docker de que ele pode confiar em um registro "inseguro" (sem TLS). Essa configuração precisa ser feita no servidor onde o registro vai rodar e em todos os nós do cluster que forem usá-lo.

Edite o arquivo /etc/docker/daemon.json, informando o host (IP ou nome da máquina) e a porta do registro:

{
    "insecure-registries": [ "host:port" ]
}

Depois, reinicie o serviço do Docker para aplicar a mudança:

# systemctl restart docker

Criando o servidor de registro

A forma mais simples de subir um registro é rodando a imagem oficial registry como um container:

$ docker run -d -p 5000:5000 --restart=always --name=repositorio registry

Explicando cada opção:

Opção	Função
`-d`	Roda o container em background (daemon)
`-p 5000:5000`	Expõe a porta 5000 do container na porta 5000 do host
`--restart=always`	Reinicia o container automaticamente em caso de falha
`--name=repositorio`	Nome dado ao container
`registry`	Imagem oficial usada para rodar o servidor de registro

Testando o registro

Para confirmar que o registro está no ar, basta acessar pelo navegador:

http://registry.zion.local:5000/v2/

Uma resposta vazia em JSON ({}) já indica que o serviço está funcionando corretamente.

Publicando uma imagem no registro local

1. Liste as imagens disponíveis localmente:

$ docker image ls

2. Marque (tag) a imagem apontando para o endereço do registro local — no exemplo, a imagem oregontecnologia/myapp-api:

$ docker tag oregontecnologia/myapp-api registry.zion.local:5000/myapp-api

3. Envie a imagem para o registro local:

$ docker push registry.zion.local:5000/myapp-api

Usando a imagem do registro local no Kubernetes

Com a imagem publicada, já é possível criar um Deployment no cluster apontando diretamente para o registro local:

$ kubectl create deploy myapp-api --image=registry.zion.local:5000/myapp-api

E confirmar que o pod subiu corretamente:

$ kubectl get pods -o wide

Se o Kubernetes não conseguir baixar a imagem (erro de ImagePullBackOff), verifique se o insecure-registries foi configurado em todos os nós do cluster — não só no servidor onde o registro está rodando —, já que qualquer worker pode ser escolhido para agendar o pod.

Subindo o nível: registro com autenticação

O exemplo acima é funcional, mas sem nenhuma proteção — qualquer pessoa com acesso à rede pode enviar ou baixar imagens. Para um cenário mais realista, vamos adicionar autenticação via htpasswd.

Criando as credenciais

Primeiro, instale o utilitário htpasswd (parte do pacote apache2-utils):

$ sudo apt install apache2-utils

Crie uma pasta para armazenar o arquivo de senhas:

$ mkdir ~/home-user/auth && cd $_

Crie o arquivo registry.password, adicionando o primeiro usuário com a flag -c (que cria o arquivo) e -B (que usa criptografia bcrypt):

$ htpasswd -Bc registry.password nome_usuário

Para adicionar outros usuários depois, não use a flag -c novamente (ela sobrescreveria o arquivo):

$ htpasswd -B registry.password nome_do_novo_usuário

Subindo o registro autenticado com Docker Compose

Em vez de um único comando docker run, um registro autenticado fica mais organizado como um docker-compose.yml:

$ vim docker-compose.yml

version: '3'

services:
  registry:
    image: registry:2
    ports:
    - "5000:5000"
    environment:
      REGISTRY_AUTH: htpasswd
      REGISTRY_AUTH_HTPASSWD_REALM: Registry
      REGISTRY_AUTH_HTPASSWD_PATH: /auth/registry.password
      REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY: /data
    volumes:
      - ./auth:/auth
      - ./data:/data
    restart: always

Esse arquivo:

Usa a imagem oficial registry:2;
Habilita autenticação via htpasswd, apontando para o arquivo de senhas criado anteriormente;
Persiste as imagens em um volume local (./data), evitando perda de dados caso o container seja recriado.

Suba o serviço:

$ docker-compose up

Testando o registro autenticado

http://nome-ou-ip-do-servidor:5000/v2

Ao tentar acessar, o navegador (ou o docker login) deve solicitar usuário e senha — confirmando que a autenticação está ativa.

Considerações finais

Ter um registro de imagens local dá mais controle e independência ao cluster on-premise, especialmente em ambientes sem acesso irrestrito à internet ou com políticas de segurança mais rígidas. A versão com autenticação via htpasswd já é um bom ponto de partida para ambientes reais — mas, para produção, vale complementar com TLS e, dependendo da escala, considerar soluções mais robustas como o Harbor, que adiciona recursos como controle de acesso granular, scanning de vulnerabilidades e replicação entre registros.

Se o seu cluster precisar autenticar automaticamente contra um registro privado (público ou local) ao fazer o pull das imagens, veja também o artigo sobre como configurar um imagePullSecret com regcred no Kubernetes.

Montando um Cluster Kubernetes On-Premise — Parte 6: Deploy, Atualização e Escalabilidade de uma Aplicação Própria

Celso Nery — Wed, 29 Jul 2026 19:04:42 +0000

🇺🇸 English version here.

Na Parte 5 desta série, validamos o cluster de ponta a ponta fazendo o deploy do Nginx. Agora vamos um passo além: construir a imagem Docker de uma aplicação própria, publicá-la, colocá-la para rodar no cluster e explorar operações do dia a dia — atualização de versão, rollback e escalabilidade (manual e automática).

Como exemplo, foi utilizada uma API REST simples (myapp.war), feita em Spring Boot, apenas para fins didáticos — o processo se aplica a qualquer aplicação empacotada como imagem de container.

Criando a imagem Docker da aplicação

O primeiro passo é escrever o Dockerfile da aplicação. Neste exemplo, foi usada uma imagem base leve (alpine), com o Java 11 instalado para rodar a aplicação:

FROM alpine
WORKDIR /opt/app
RUN apk update && apk add vim openjdk11-jre
COPY runapp.sh .
CMD ash runapp.sh

Construindo a imagem

docker image build -t oregontecnologia/myapp-api:1.0.0 .

Publicando a imagem

Antes de usar a imagem no cluster, ela precisa estar disponível em algum registro — seja o Docker Hub, seja um registro privado. Se você optar por hospedar seu próprio registro on-premise (recomendado para ambientes corporativos ou sem acesso à internet), veja o artigo complementar sobre como criar um servidor de registro local.

Para publicar no Docker Hub:

docker login

username:
password:

docker push oregontecnologia/myapp-api:1.0.0

Fazendo o deploy da aplicação

Com a imagem publicada, é possível verificar o estado atual do cluster antes de prosseguir:

kubectl get pods -o wide
kubectl get deploy -o wide

Crie o Deployment diretamente pela linha de comando, apontando para a imagem publicada:

kubectl create deploy myapp-deploy --image=oregontecnologia/myapp-api:1.0.0

Diferente dos exemplos anteriores desta série (onde usamos arquivos YAML com kubectl apply -f), aqui o Deployment é criado diretamente via linha de comando com kubectl create deploy. Ambas as abordagens são válidas — arquivos YAML são mais indicados quando você precisa versionar e reaplicar configurações de forma consistente.

Expondo a aplicação externamente

Para tornar a aplicação acessível fora do cluster, crie um Service do tipo LoadBalancer, associando um IP externo fixo:

kubectl expose deploy myapp-deploy --type=LoadBalancer --external-ip=10.0.10.100 --port=80

Em ambientes on-premise, o tipo LoadBalancer normalmente não provisiona um balanceador automaticamente (isso é um recurso nativo de provedores de nuvem). Por isso, aqui é informado manualmente um IP externo (--external-ip) já disponível na rede local.

Removendo a aplicação

Caso precise remover o Deployment:

kubectl delete deploy myapp-deploy

Atualizando e revertendo versões da aplicação

Uma das grandes vantagens do Kubernetes é gerenciar atualizações de forma controlada, sem downtime perceptível (rolling update).

Atualizando para uma nova versão

kubectl set image deployments/myapp-deploy myapp-api=oregontecnologia/myapp-api:1.0.2 --record

Esse comando atualiza a imagem do container myapp-api dentro do Deployment para a versão 1.0.2. A flag --record registra o comando no histórico de revisões do Deployment, o que facilita identificar depois o que mudou em cada rollout.

Revertendo para a versão anterior

Se a nova versão apresentar problemas, é possível reverter rapidamente para a revisão anterior:

kubectl rollout undo deployments/myapp-deploy

Escalando a aplicação

Escalonamento manual

Para ajustar manualmente o número de réplicas em execução — por exemplo, para 3:

kubectl scale deploy myapp-deploy --replicas=3

Escalonamento automático (HPA)

Para deixar o próprio Kubernetes ajustar o número de réplicas automaticamente, com base no uso de CPU, é possível configurar um Horizontal Pod Autoscaler (HPA). No exemplo abaixo, o cluster começa com 2 réplicas e pode escalar até 10, sempre que a utilização média de CPU ultrapassar 75%:

kubectl autoscale deploy myapp-deploy --min=2 --max=10 --cpu-percent=75

Ajuste os valores de --min, --max e --cpu-percent conforme a capacidade real do seu cluster e o comportamento esperado da aplicação.

Para verificar o estado atual do autoscaler:

kubectl get hpa

Esse comando mostra, entre outras informações, o uso atual de CPU em relação ao alvo configurado, e o número de réplicas em execução no momento.

Para remover o autoscaler:

kubectl delete hpa myapp-deploy

Agora vamos colocar todo este processo manual em um arquivo YAML para facilitar as coisas.

Ao longo desta série, usamos diversos arquivos .yaml para criar Deployments, Services e outros objetos no cluster. Neste artigo, vamos dar um passo atrás e entender a estrutura básica desses manifestos — o que é obrigatório em todo arquivo, como descobrir a apiVersion correta e como ficam, na prática, os principais tipos de objeto que já usamos: Pod, ReplicaSet, Deployment e Service.

A estrutura mínima de um manifesto

Todo objeto do Kubernetes, independente do tipo, é descrito por um YAML com quatro campos principais:

apiVersion: 
kind: 
metadata: 
spec:

apiVersion: a versão da API do Kubernetes usada para criar aquele objeto (por exemplo, v1 ou apps/v1);
kind: o tipo de objeto que será criado (Pod, Deployment, Service, etc.);
metadata: os metadados do objeto — nome, labels, namespace, entre outros;
spec: a especificação propriamente dita do objeto — no caso de um Pod, por exemplo, é aqui que ficam os containers.

Como descobrir a apiVersion correta

Cada tipo de objeto (kind) pertence a uma apiVersion específica, e isso pode variar entre versões do Kubernetes. Para consultar quais recursos estão disponíveis no seu cluster e a qual API cada um pertence, use:

$ kubectl api-resources

Esse comando lista todos os recursos suportados pelo cluster, junto com o grupo de API correspondente (coluna APIVERSION) — é a fonte mais confiável para saber qual apiVersion usar em cada manifesto, já que isso pode mudar conforme a versão do Kubernetes instalada.

Atenção à indentação

YAML é um formato sensível à indentação — diferente de chaves {} ou colchetes [], a hierarquia dos dados é definida puramente pelos espaços. Por isso:

Nunca use TAB para indentar um arquivo YAML — use sempre espaços.
O padrão recomendado (e usado nos exemplos abaixo) é 2 espaços por nível de indentação.
metadata e spec são mapeamentos (chave-valor), não listas — ou seja, seus campos internos (name, labels, etc.) não devem começar com -.

Esse último ponto é um erro comum: é fácil confundir listas (que usam -) com mapeamentos simples. No exemplo de Pod abaixo, note que name e labels ficam diretamente sob metadata, sem traço.

Pod

O objeto mais básico do Kubernetes é o Pod — a menor unidade que pode ser criada e gerenciada no cluster, contendo um ou mais containers.

apiVersion: v1
kind: Pod
metadata:
  name: meupod
  labels:
    app: meupod-label
spec:
  containers:
    - name: myapp-api
      image: oregontecnologia/myapp-api:1.0.2

Criando o objeto: create vs apply

Existem dois comandos principais para aplicar um manifesto no cluster:

$ kubectl create -f arquivo.yaml
$ kubectl apply -f arquivo.yaml

A diferença entre eles é importante:

create cria o objeto apenas se ele ainda não existir — se o objeto já foi criado anteriormente, o comando retorna erro.
apply cria o objeto caso ele não exista, ou atualiza o objeto existente caso haja alguma mudança no manifesto. Por isso, apply é o comando mais usado no dia a dia, já que permite reaplicar o mesmo arquivo continuamente conforme ele evolui.

Verificando a criação

$ kubectl get pods

A flag -o wide mostra informações adicionais sobre o pod em execução, como o nó onde ele está rodando e seu IP interno.

Para ver todos os detalhes de um pod ou deployment (incluindo eventos recentes, o que ajuda bastante na hora de depurar problemas):

$ kubectl describe pod myapp-api

Ou, para um deployment:

$ kubectl describe deploy myapp-deploy

ReplicaSet

Um Pod sozinho não se recupera automaticamente se falhar. É aí que entra o ReplicaSet: um objeto responsável por garantir que um número definido de réplicas do mesmo Pod esteja sempre em execução.

apiVersion: apps/v1
kind: ReplicaSet
metadata:
  name: meureplicaset
spec:
  replicas: 5
  selector:
    matchLabels:
      app: meupod-label
  template:
    metadata:
      labels:
        app: meupod-label
    spec:
      containers:
        - name: myapp-api
          image: oregontecnologia/myapp-api:1.0.2

Repare que a estrutura é um pouco mais aninhada que a do Pod: dentro de spec, temos o selector (que define quais Pods pertencem a este ReplicaSet, com base nos labels) e o template (que descreve como cada réplica do Pod deve ser criada).

Verificando a criação:

$ kubectl get replicaset

Na prática, é raro criar ReplicaSets diretamente — normalmente eles são gerenciados automaticamente por um Deployment, que veremos a seguir. Ainda assim, entender essa camada ajuda a compreender como o Kubernetes garante a disponibilidade dos Pods.

Deployment

O Deployment é a forma mais comum de rodar aplicações no Kubernetes. Ele gerencia ReplicaSets automaticamente, adicionando recursos como rolling updates e rollback — que já vimos na prática na Parte 6 desta série.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: meudeploy
spec:
  replicas: 5
  selector:
    matchLabels:
      app: meupod-label
  template:
    metadata:
      labels:
        app: meupod-label
    spec:
      containers:
        - name: myapp-api
          image: oregontecnologia/myapp-api:1.0.2

Note que a estrutura é praticamente idêntica à do ReplicaSet — o que faz sentido, já que um Deployment cria e gerencia ReplicaSets por trás dos panos. A diferença está no kind e nas funcionalidades adicionais que o Deployment oferece.

Verificando a criação:

$ kubectl get deploy

Service

Por fim, o Service é o objeto responsável por expor Pods de forma estável, com um endereço fixo, independente de quantas vezes os Pods sejam recriados.

apiVersion: v1
kind: Service
metadata:
  name: meudservice
spec:
  selector:
    app: meupod-label
  ports:
    - port: 80
  type: LoadBalancer  # ClusterIP | NodePort | LoadBalancer

O campo type define como o serviço será exposto:

ClusterIP (padrão): expõe o serviço apenas internamente, dentro do cluster;
NodePort: expõe o serviço em uma porta fixa em todos os nós do cluster (usamos esse tipo na Parte 5, com o Nginx);
LoadBalancer: solicita um balanceador de carga externo — em nuvem, provisionado automaticamente pelo provedor; em ambientes on-premise, normalmente requer um IP configurado manualmente ou uma solução como o MetalLB.

Verificando a criação:

$ kubectl get services

Resumo

Objeto	Função principal
Pod	Unidade mínima de execução (um ou mais containers)
ReplicaSet	Garante um número fixo de réplicas de um Pod
Deployment	Gerencia ReplicaSets, com suporte a rolling update e rollback
Service	Expõe Pods de forma estável, com IP e nome fixos

Entender essa hierarquia — Pod → ReplicaSet → Deployment, mais o Service como camada de exposição — é a base para ler (e escrever) qualquer manifesto do Kubernetes com confiança, independente da complexidade da aplicação.

Fechando o ciclo operacional

Com o deploy de uma aplicação própria, atualizações controladas, rollback e escalabilidade (manual e automática), cobrimos as operações mais comuns do dia a dia de um cluster Kubernetes on-premise. A partir daqui, o cluster está pronto não só para hospedar aplicações, mas também para operá-las de forma resiliente conforme a demanda aumenta.

Isso encerra o conteúdo mais conceitual desta série. Nos próximos artigos, seguimos explorando tópicos práticos do dia a dia de um cluster on-premise.

Nos próximos artigos da série, vamos aprofundar em temas como registro de imagens privado on-premise, armazenamento persistente e observabilidade do cluster.

Montando um Cluster Kubernetes On-Premise — Parte 5: Fazendo o Deploy do Primeiro Container

Celso Nery — Wed, 29 Jul 2026 19:04:34 +0000

🇺🇸 English version here.

Nas partes anteriores desta série, construímos o cluster do zero: preparamos o ambiente (Parte 1), instalamos containerd e Kubernetes (Parte 2), inicializamos o control-plane (Parte 3) e ingressamos os workers (Parte 4). Com o cluster de pé e todos os nós no estado Ready, chegou a hora de colocá-lo para trabalhar de verdade: vamos fazer o deploy da nossa primeira aplicação.

Neste artigo, vamos usar o Nginx como exemplo — um caso clássico para validar que o cluster está funcionando de ponta a ponta, desde a criação dos pods até a exposição do serviço.

Organizando os arquivos

Antes de tudo, crie um diretório para organizar os manifestos desse deployment:

mkdir nginx
cd nginx

Costumo deixar os manifestos do Kubernetes organizados em diretórios por aplicação, considero uma boa prática que facilita a manutenção e o versionamento (por exemplo, com Git) conforme o cluster cresce.

Criando o Deployment

Um Deployment é o objeto do Kubernetes responsável por gerenciar réplicas de pods, garantindo que o número desejado de instâncias esteja sempre em execução — e cuidando de coisas como rolling updates e recuperação automática em caso de falha.

Crie o arquivo nginx-deployment.yaml com o seguinte conteúdo:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  labels:
    app: nginx
spec:
  replicas: 2
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.14.0
        ports:
        - containerPort: 80

Esse manifesto define:

2 réplicas do pod Nginx (replicas: 2), distribuídas entre os workers disponíveis;
Um selector que associa o Deployment aos pods através do label app: nginx;
A imagem nginx:1.14.0, expondo a porta 80 do container.

Aplicando o Deployment

Com o arquivo salvo, aplique-o no cluster:

kubectl apply -f nginx-deployment.yaml

O kubectl vai criar o Deployment e, a partir dele, o Kubernetes se encarrega de agendar os 2 pods nos workers disponíveis.

Verificando o Deployment

Para conferir se o Deployment foi criado e está com as réplicas desejadas em execução:

kubectl get deployments

E, para detalhes mais completos (eventos, condições, estratégia de rollout, etc.):

kubectl describe deployment nginx-deployment

Se tudo estiver certo, você deve ver as 3 réplicas prontas (2/2) na coluna de disponibilidade.

Criando o Service

Só o Deployment não é suficiente para acessar a aplicação de fora do cluster — pods são efêmeros e seus IPs mudam a cada recriação. É para isso que existe o Service: um ponto de acesso estável que direciona tráfego para os pods corretos, com base nos labels.

Crie o arquivo nginx-service.yaml:

apiVersion: v1
kind: Service
metadata:
  name: nginx-service
  labels:
    run: nginx-service
spec:
  type: NodePort
  ports:
  - port: 80
    protocol: TCP
  selector:
    app: nginx

Aqui, o tipo NodePort é usado para expor o serviço em uma porta acessível diretamente pelo IP de qualquer nó do cluster — uma opção simples e prática para ambientes on-premise, sem depender de um load balancer externo (diferente do tipo LoadBalancer, mais comum em provedores de nuvem).

Aplicando o Service

kubectl apply -f nginx-service.yaml

Verificando o Service

kubectl get service

Esse comando mostra, entre outras informações, a porta externa (NodePort) que foi alocada automaticamente pelo Kubernetes — normalmente na faixa entre 30000 e 32767.

Para mais detalhes:

kubectl describe service nginx-service

Com a porta em mãos, o Nginx já pode ser acessado através do IP de qualquer nó do cluster (master ou workers) na porta indicada — por exemplo: http://10.0.10.100:<porta-nodeport>.

O que validamos aqui

Se você conseguiu acessar a página padrão do Nginx através do NodePort, isso confirma que todo o cluster está funcionando corretamente de ponta a ponta:

O control-plane está agendando pods normalmente;
A rede de pods (CNI) está permitindo a comunicação entre os componentes;
O kube-proxy está roteando o tráfego do Service para os pods corretos;
Os workers estão executando containers sem problemas.

Considerações finais

Com isso, fechamos o essencial para montar e validar um cluster Kubernetes on-premise do zero: preparação do ambiente, instalação dos componentes, inicialização do control-plane, ingresso dos workers e o primeiro deploy de uma aplicação real.

A partir daqui, os próximos passos naturais incluem temas como armazenamento persistente (Persistent Volumes), Ingress Controllers, gerenciamento de configurações e segredos (ConfigMaps e Secrets), monitoramento (Prometheus/Grafana) e estratégias de backup do cluster (como o etcd). Fica a sugestão para uma possível continuação desta série.

Se você seguiu os cinco artigos até aqui, já tem em mãos um cluster Kubernetes on-premise funcional, construído e validado do zero — sem depender de nenhum provedor de nuvem.

Agora na Parte 6 desta série, vamos subir nosso container com nossa aplicação e endentender como tudo funciona.

Continua na Parte 6.

Montando um Cluster Kubernetes On-Premise — Parte 4: Ingressando os Nós Workers Nodes

Celso Nery — Wed, 29 Jul 2026 19:04:25 +0000

🇺🇸 English version here.

Nas partes anteriores, preparamos o ambiente (Parte 1), instalamos o containerd e o Kubernetes (Parte 2) e inicializamos o control-plane no servidor master, incluindo a rede de pods (Parte 3). Agora vamos fechar o ciclo básico do cluster: unir os servidores workers ao master e confirmar que tudo está funcionando corretamente.

Ingressando os nós workers nodes

Em cada servidor worker que você deseja adicionar ao cluster, execute o comando kubeadm join gerado no final da inicialização do master (Parte 3). Ele tem o seguinte formato:

kubeadm join 10.0.10.100:6443 --token 9e0xeu.s0if3... --discovery-token-ca-cert-hash sha256:3a328e56729515d...

Esse comando usa o token e o hash do certificado para autenticar o worker junto ao control-plane e permitir que ele se junte ao cluster com segurança.

E se perdeu o token?

Tokens do kubeadm expiram por padrão após 24 horas. Se você não guardou o token (ou ele já expirou), não tem problema — é possível gerar um novo comando de join a qualquer momento, direto no master:

# kubeadm token create --print-join-command

Esse comando cria um novo token e já retorna o comando completo, pronto para ser copiado e executado nos workers.

Verificando os nós do cluster

Depois de rodar o kubeadm join em todos os workers, volte para o master e confira se os nós foram adicionados corretamente:

kubectl get nodes

Ou, para uma saída com mais detalhes (endereço IP interno, versão do kernel, container runtime, etc.) acrescente -o wide ao final do comando:

kubectl get nodes -o wide

A opção -o wide acrescenta informações extras à saída padrão.

A saída deve ser parecida com esta:

Todos os nós devem aparecer com o status Ready. Se algum worker aparecer como NotReady, vale conferir se a rede de pods (CNI) foi aplicada corretamente e se o containerd está rodando sem erros nesse nó.

Lidando com taints indesejados

Em alguns casos, um nó pode ficar marcado com um taint que impede o agendamento de novos pods nele — por exemplo, quando o Kubernetes detecta pressão de disco (disk-pressure). Isso é comum em ambientes de laboratório com discos pequenos ou pouco espaço livre.

Para verificar se um nó específico está com esse taint (no exemplo abaixo, o node3):

kubectl --kubeconfig=/home/celso/.kube/config.bagarote describe node node3 | grep Taint

Se o taint disk-pressure estiver presente e você quiser remover essa restrição manualmente (ciente de que o nó pode estar com pouco espaço em disco), execute:

kubectl --kubeconfig=/home/celso/.kube/config.bagarote taint node node3 node.kubernetes.io/disk-pressure:NoSchedule-

O sinal de - no final do comando é o que remove o taint — sem ele, o comando adicionaria um novo taint em vez de remover.

⚠️ Remover um taint de disk-pressure manualmente é uma medida paliativa. O ideal é investigar e resolver a causa raiz (liberar espaço em disco, aumentar o armazenamento, etc.), já que o Kubernetes aplica esse taint como proteção contra falhas por falta de espaço.

Fechando o ciclo

Com os workers ingressados e todos os nós no estado Ready, o cluster Kubernetes on-premise está oficialmente de pé: control-plane funcionando, rede de pods ativa e workers prontos para receber cargas de trabalho.

Isso encerra a base desta série — preparação do ambiente, instalação dos componentes, inicialização do master e ingresso dos workers. A partir daqui, o cluster está pronto para os próximos passos naturais de qualquer ambiente Kubernetes: deploy de aplicações, configuração de armazenamento persistente, ingress controllers, monitoramento, entre outros.

Se você seguiu essa série até aqui, já tem em mãos um cluster Kubernetes on-premise funcional, construído do zero, sem depender de nenhum provedor de nuvem.

Agora na Parte 5 desta série, vamos subir containers e testar se tudo está funcioando e recebendo carga de trabalho normalmento.

Continua na Parte 5.

Montando um Cluster Kubernetes On-Premise — Parte 3: Inicializando o Master

Celso Nery — Wed, 29 Jul 2026 19:04:16 +0000

🇺🇸 English version here.

Nas partes anteriores desta série, preparamos o ambiente (Parte 1) e instalamos o containerd, o kubelet e o kubeadm em todos os nós (Parte 2). Chegou o momento de, finalmente, inicializar o cluster: vamos criar o control-plane no servidor master e deixá-lo pronto para receber os workers e uma rede de pods funcional.

Inicializando o cluster com kubeadm

A forma mais simples de inicializar o cluster é rodando o comando abaixo no servidor master:

# kubeadm init

Ou, especificando parâmetros importantes manualmente — como o CIDR da rede de pods, o endereço IP a ser anunciado pelo API server e a versão do Kubernetes:

# kubeadm init --pod-network-cidr=10.244.0.0/16 --apiserver-advertise-address=10.0.10.100 --kubernetes-version="1.31.1"

Usando um arquivo de configuração (recomendado)

Versões mais recentes do kubelet não aceitam mais determinadas opções via linha de comando (esse comportamento foi descontinuado). Por isso, o recomendado atualmente é criar um arquivo de configuração para o kubeadm, em vez de passar tudo por flags.

Crie o arquivo kubelet.yaml:

apiVersion: kubeadm.k8s.io/v1beta3
kind: InitConfiguration
---
apiVersion: kubeadm.k8s.io/v1beta3
kind: ClusterConfiguration
kubernetesVersion: "1.31.1" # Substitua pela versão desejada
controlPlaneEndpoint: "k8s-master"
---
apiVersion: kubelet.config.k8s.io/v1beta1
kind: KubeletConfiguration

E execute a inicialização apontando para esse arquivo:

$ sudo kubeadm init --config kubelet.yaml

O que esperar da saída

Se tudo correr bem, a saída do comando será parecida com esta (resumida aqui para facilitar a leitura):

[init] Using Kubernetes version: v1.31.1
[preflight] Running pre-flight checks
[preflight] Pulling images required for setting up a Kubernetes cluster
[preflight] This might take a minute or two, depending on the speed of your internet connection
[preflight] You can also perform this action in beforehand using 'kubeadm config images pull'

[kubelet-start] Writing kubelet environment file with flags to file "/var/lib/kubelet/kubeadm-flags.env"
[kubelet-start] Writing kubelet configuration to file "/var/lib/kubelet/config.yaml"
[kubelet-start] Activating the kubelet service
[certs] Using certificateDir folder "/etc/kubernetes/pki"
[certs] Generating "ca" certificate and key
[certs] Generating "apiserver-kubelet-client" certificate and key

...

[bootstraptoken] configured RBAC rules to allow certificate rotation for all node client certificates in the cluster
[bootstraptoken] creating the "cluster-info" ConfigMap in the "kube-public" namespace
[addons] Applied essential addon: CoreDNS
[addons] Applied essential addon: kube-proxy

Your Kubernetes master has initialized successfully!

To start using your cluster, you need to run the following as a regular user:

  mkdir -p $HOME/.kube
  sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
  sudo chown $(id -u):$(id -g) $HOME/.kube/config

You should now deploy a pod network to the cluster.
Run "kubectl apply -f [podnetwork].yaml" with one of the options listed at:
  https://kubernetes.io/docs/concepts/cluster-administration/addons/

Then you can join any number of worker nodes by running the following on each as root:

kubeadm join 10.0.10.100:6443 --token d1dyaj.31zxywbg93s1ywjy --discovery-token-ca-cert-hash sha256:71a91721595fde66b6382908d801266602a14de8e16bdb7a3cede21509427009

⚠️ Importante: guarde o comando kubeadm join completo (com o token e o hash do certificado) exibido no final da saída. Ele será necessário para adicionar os workers ao cluster.

Configurando o acesso via kubectl

Para conseguir usar o kubectl como usuário comum (sem precisar de sudo toda vez), copie o arquivo de configuração do administrador:

mkdir -p $HOME/.kube
cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
chown $(id -u):$(id -g) $HOME/.kube/config

Para verificar o estado atual do cluster, rode:

kubectl get pods --all-namespaces

Nesse momento, é normal que alguns pods apareçam com status Pending — isso acontece porque ainda não instalamos uma rede de pods (CNI), e é exatamente esse o próximo passo.

Exemplo de saida:

Instalando a rede de pods (CNI)

O Kubernetes não vem com uma solução de rede pronta — é preciso escolher e instalar um plugin de rede (CNI), responsável por permitir a comunicação entre os pods do cluster. Algumas opções populares são Calico, Canal, Flannel e Weave.

Use apenas uma das opções acima — instalar mais de um CNI no mesmo cluster pode causar conflitos de rede.

Exemplo com Calico:

kubectl apply -f https://raw.githubusercontent.com/projectcalico/calico/v3.28.2/manifests/calico.yaml

Exemplo com Flannel:

kubectl apply -f https://raw.githubusercontent.com/flannel-io/flannel/v0.20.2/Documentation/kube-flannel.yml

Exemplo com Weave:

export kubever=$(kubectl version | base64 | tr -d '\n')
kubectl apply -f "https://cloud.weave.works/k8s/net?k8s-version=$kubever"

kubectl apply -f https://github.com/weaveworks/weave/releases/download/v2.8.1/weave-daemonset-k8s.yaml

Depois de aplicar o manifesto escolhido, rode novamente:

kubectl get pods --all-namespaces

E, em alguns instantes, os pods do namespace kube-system — incluindo o CoreDNS — devem passar para o status Running. Isso confirma que a rede de pods está funcionando corretamente.

A saída deve ser igual a essa:

Próximos passos

Com o control-plane inicializado, o kubectl configurado e a rede de pods instalada, o master do cluster já está totalmente operacional. Falta apenas um passo: adicionar os servidores workers/nodes ao cluster usando o comando kubeadm join que guardamos anteriormente.

Na Parte 4 desta série, vamos unir os workers/nodes ao cluster e validar que todos os nós estão prontos para receber cargas de trabalho.

Continua na Parte 4.