Unit 3.2: Kubernetes Deployment and Operations
Introduction
TaskBoard's images are in the registry from Unit 3.1. Now they need a place to run. Managed Kubernetes runs the control plane; you manage node pools and workloads with code.
Some parts work differently from other Kubernetes platforms. A Service of type LoadBalancer attaches a static IP to one node instead of creating a load balancer, and nodes are replaced during maintenance.
In this unit you provision the cluster with Terraform, connect kubectl, deploy TaskBoard's workloads, put the ALB from Unit 2.3 in front of an ingress controller, and operate node pools. In the Code Lab you take TaskBoard from terraform apply to a working endpoint behind the ALB.
1. Provisioning MKS with Terraform
1.1 The Cluster
resource "ionoscloud_k8s_cluster" "taskboard" {
name = "taskboard-dev"
k8s_version = var.k8s_version
maintenance_window {
day_of_the_week = "Sunday"
time = "02:00:00Z"
}
api_subnet_allow_list = ["203.0.113.0/24"]
s3_buckets {
name = "taskboard-k8s-audit-7f3a"
}
}
Only name is required. api_subnet_allow_list restricts access to the Kubernetes API server to these CIDRs; cluster-internal traffic is not affected, and without a list, access is not restricted. s3_buckets names an existing IONOS Cloud Object Storage bucket for the Kubernetes API audit logs. The maintenance window opens at the time you set and stays open for four hours.
Read the current default version from the API and pass it in, instead of copying an old version from an example:
curl --silent "https://api.ionos.com/cloudapi/v6/k8s/versions/default" \
--header "Authorization: Bearer $IONOS_TOKEN"
export TF_VAR_k8s_version="<version from the response>"
The supported minor versions are 1.32, 1.33, 1.34 and 1.35. Version 1.32 reaches its IONOS CLOUD end of life on December 1, 2026, and new node pools cannot be created for a cluster on an EOL version. Downgrades are not supported.
1.2 The Node Pool
# In the existing ionoscloud_lan.app and ionoscloud_lan.db from Unit 2.2, add:
# lifecycle {
# create_before_destroy = true
# }
resource "ionoscloud_k8s_node_pool" "general" {
datacenter_id = ionoscloud_datacenter.taskboard.id
k8s_cluster_id = ionoscloud_k8s_cluster.taskboard.id
name = "general"
k8s_version = ionoscloud_k8s_cluster.taskboard.k8s_version
server_type = "VCPU"
availability_zone = "AUTO"
storage_type = "SSD"
node_count = 2
cores_count = 2
ram_size = 4096
storage_size = 20
lans {
id = ionoscloud_lan.app.id
dhcp = true
}
lans {
id = ionoscloud_lan.db.id
dhcp = true
}
maintenance_window {
day_of_the_week = "Sunday"
time = "03:00:00Z"
}
}
The lans blocks connect every node to the private app LAN from Unit 2.2, where the ALB reaches them in Section 4, and to the DB LAN, where the pods reach PostgreSQL, In-Memory DB and Kafka (Unit 2.5). Node pools get their IP addresses in a private LAN through DHCP. The provider recommends create_before_destroy on the LANs so that the node pool is updated before a LAN is destroyed.
These arguments are immutable: name, cpu_family, availability_zone, cores_count, ram_size, storage_size and storage_type. allow_replace = true changes them by destroying and recreating the pool, which causes downtime for all pods on it. server_type accepts DedicatedCore or VCPU, and you can switch an existing pool between them. One provisioned core equals 2 Managed Kubernetes CPUs.
1.3 Retrieving the Kubeconfig
data "ionoscloud_k8s_cluster" "taskboard" {
id = ionoscloud_k8s_cluster.taskboard.id
depends_on = [ionoscloud_k8s_node_pool.general]
}
resource "local_file" "kubeconfig" {
sensitive_content = yamlencode(jsondecode(data.ionoscloud_k8s_cluster.taskboard.kube_config))
filename = "kubeconfig.yaml"
}
The data source returns kube_config, and its whole config node is marked as sensitive. Writing the kubeconfig to a file is a security risk: keep it out of Git. Outside Terraform you get the same file from the API or the CLI:
curl --silent "https://api.ionos.com/cloudapi/v6/k8s/$CLUSTER_ID/kubeconfig" \
--header "Authorization: Bearer $IONOS_TOKEN" > kubeconfig.yaml
ionosctl k8s kubeconfig get --cluster-id "$CLUSTER_ID"
The API returns YAML by default, or JSON when the Accept header asks for it. Only administrators can retrieve the kubeconfig of a cluster without a node pool; all other users must create a node pool first.
2. Connecting to the Cluster
export KUBECONFIG="$PWD/kubeconfig.yaml"
kubectl config get-contexts
kubectl get nodes -o wide
kubectl create namespace taskboard
kubectl config set-context --current --namespace=taskboard
Use the downloaded kubeconfig for setup, not for daily deployments.
2.1 RBAC for Deployments
For the CI pipeline in Unit 3.3, create a service account that can only manage TaskBoard's namespace:
apiVersion: v1
kind: ServiceAccount
metadata:
name: taskboard-deployer
namespace: taskboard
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
name: taskboard-deployer-edit
namespace: taskboard
subjects:
- kind: ServiceAccount
name: taskboard-deployer
namespace: taskboard
roleRef:
kind: ClusterRole
name: edit
apiGroup: rbac.authorization.k8s.io
The built-in edit ClusterRole, bound through a RoleBinding, grants rights only inside taskboard. Who may create clusters at all is an IONOS CLOUD privilege: a group needs createK8sCluster (Create Kubernetes Clusters in the DCD).
3. TaskBoard Workloads
3.1 Pulling from the Private Container Registry
kubectl create secret docker-registry taskboard-registry \
--docker-server="$CR_HOST" \
--docker-username=taskboard-k8s-pull \
--docker-password="$(cat k8s-pull.pass)" \
--namespace taskboard
The secret holds the pull-only token from Unit 3.1. Reference it in every pod spec through imagePullSecrets. Without it, pods stay in ImagePullBackOff, because the registry never allows unauthenticated pulls.
3.2 Deployment, Service, ConfigMap and Secret
apiVersion: v1
kind: ConfigMap
metadata:
name: taskboard-config
data:
LOG_LEVEL: "info"
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: taskboard-api
spec:
replicas: 2
selector:
matchLabels: { app: taskboard-api }
template:
metadata:
labels: { app: taskboard-api }
spec:
imagePullSecrets:
- name: taskboard-registry
containers:
- name: api
image: <registry-hostname>/taskboard/api:<git-sha>
ports:
- containerPort: 8000
envFrom:
- configMapRef: { name: taskboard-config }
- secretRef: { name: taskboard-db }
resources:
requests: { cpu: 250m, memory: 256Mi }
limits: { memory: 512Mi }
readinessProbe:
httpGet: { path: /api/health, port: 8000 }
---
apiVersion: v1
kind: Service
metadata:
name: taskboard-api
spec:
selector: { app: taskboard-api }
ports:
- port: 80
targetPort: 8000
The taskboard-db Secret carries the PostgreSQL connection values from Unit 2.5; create it from your secret store, never from a file in Git. The web Deployment uses port 8080, and the worker Deployment has no Service. Set requests and limits: a node that runs out of RAM can end up NotReady, busy with disk I/O.
4. Ingress: Controllers on Nodes, Load Balancers Provisioned Separately
4.1 What a LoadBalancer Service Does on MKS
apiVersion: v1
kind: Service
metadata:
name: demo
spec:
type: LoadBalancer
loadBalancerIP: 198.51.100.20 # an IP you reserved in IP Management
selector: { app: demo }
ports:
- port: 80
On a public node pool, this does not create an ALB or NLB. IONOS CLOUD assigns a pre-reserved static IP or reserves a new one, and attaches it as a secondary IP to one worker node. That node acts as the ingress node; kube-proxy forwards traffic to pods on other nodes, and that NAT step replaces the client IP. Each node provides up to 2 Gbit/s on the public interface. Without loadBalancerIP, the address is released when you delete the Service. Private node pools do not support the LoadBalancer type.
4.2 TaskBoard: Ingress Controller Behind the ALB
TaskBoard uses the Managed ALB from Unit 2.3, provisioned with Terraform, not from a manifest. The ingress controller runs on the worker nodes and is exposed as a NodePort; the ALB sends traffic to the nodes in the app LAN.
helm repo add traefik https://traefik.github.io/charts
helm install traefik traefik/traefik --namespace ingress --create-namespace \
--set service.type=NodePort --set ports.web.nodePort=30080
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: taskboard
spec:
ingressClassName: traefik
rules:
- http:
paths:
- path: /api
pathType: Prefix
backend: { service: { name: taskboard-api, port: { number: 80 } } }
- path: /
pathType: Prefix
backend: { service: { name: taskboard-web, port: { number: 80 } } }
The target group now points at the nodes' addresses in the app LAN, on the NodePort:
variable "ingress_node_ips" {
type = list(string)
}
resource "ionoscloud_target_group" "ingress" {
name = "taskboard-ingress"
algorithm = "ROUND_ROBIN"
protocol = "HTTP"
protocol_version = "HTTP1"
dynamic "targets" {
for_each = var.ingress_node_ips
content {
ip = targets.value
port = 30080
weight = 100
}
}
http_health_check {
path = "/api/health"
method = "GET"
match_type = "STATUS_CODE"
response = "200"
}
}
Point the forwarding rule from Unit 2.3 at ionoscloud_target_group.ingress.id. Read the node addresses that fall in 10.10.1.0/24 from kubectl get nodes -o wide, or from inside a node. Nodes are replaced during maintenance (Section 5), so check the target list after every node pool change.
5. Node Pool Operations and Debugging
5.1 Scaling and Multiple Pools
resource "ionoscloud_k8s_node_pool" "workers" {
# ... same required arguments as Section 1.2, name = "workers"
node_count = 1
auto_scaling {
min_node_count = 1
max_node_count = 4
}
labels = { pool = "workers" }
taints {
key = "dedicated"
value = "worker"
effect = "NoSchedule"
}
lifecycle {
ignore_changes = [node_count]
}
}
A second pool isolates TaskBoard's background worker: the taint keeps other pods off, and the worker Deployment gets a matching toleration and a nodeSelector of pool: workers. With auto_scaling, the autoscaler changes the node count, so ignore_changes stops Terraform from fighting it. The autoscaler stays between your minimum and maximum, cannot exceed the contract quota and cannot scale to 0.
| Limit | Value |
|---|---|
| Nodes per node pool | 100 maximum, 20 recommended |
| Node pools per cluster | 500 |
| Nodes per cluster | 5000 |
| Pods per node | 110 |
5.2 Upgrades and Maintenance
During node pool maintenance, all nodes of the pool are replaced, one after the other, starting with the oldest node. A new node joins first, then the old node is drained and removed. Nodes are immutable, so software updates also arrive as new nodes. Maintenance considers the four-hour window; nodes that are not replaced in time are replaced at the next maintenance.
Node pools can run an older Kubernetes version than the control plane, never a newer one, and the minor versions may differ by at most 1. To upgrade, raise k8s_version on the cluster first, then on each pool. Prepare your workloads for eviction at any time: run at least two replicas and use PodDisruptionBudgets that allow one pod to leave.
5.3 Debugging
kubectl get pods -o wide
kubectl describe pod <pod> # events: ImagePullBackOff, scheduling, probes
kubectl logs deploy/taskboard-api --since=15m
kubectl exec -it deploy/taskboard-api -- sh
kubectl get events --sort-by=.lastTimestamp
kubectl is your primary tool for workload problems. The Logging Service receives what a Fluent Bit agent ships or what you send in OTLP format, so application logs reach it only after you deploy an agent or send them over OTLP (Unit 5.1). The cluster's API audit logs go to the Object Storage bucket in s3_buckets. If a node becomes unresponsive, replace it through the API with POST /k8s/{k8sClusterId}/nodepools/{nodePoolId}/nodes/{nodeId}/replace.
API Reference Quick Card
Key API endpoints for this unit's topic:
| Method | Endpoint | Description |
|---|---|---|
GET |
/k8s/versions/default |
Default version for new clusters and node pools |
POST |
/k8s |
Create a cluster |
POST |
/k8s/{k8sClusterId}/nodepools |
Create a node pool |
GET |
/k8s/{k8sClusterId}/kubeconfig |
Download the kubeconfig (YAML by default) |
POST |
/k8s/{k8sClusterId}/nodepools/{nodePoolId}/nodes/{nodeId}/replace |
Replace an unresponsive node |
Base URL: https://api.ionos.com/cloudapi/v6
Authentication: Authorization: Bearer <token>
Code Lab
Objective: Deploy TaskBoard to Managed Kubernetes: create the cluster and node pool with Terraform, deploy the manifests with a registry pull secret, and verify the endpoint through the ALB.
Prerequisites:
- IONOS CLOUD account with an API token in
IONOS_TOKEN - Terraform,
kubectland Helm installed locally - The registry, images and
k8s-pull.passfrom Unit 3.1 - The data center, app LAN and ALB configuration from Units 2.2 and 2.3
Step 1: Add the cluster and node pool
Add the cluster (Section 1.1, without s3_buckets unless you have a bucket), the node pool (Section 1.2) and the kubeconfig file (Section 1.3) to your configuration.
export TF_VAR_k8s_version="<default version from /k8s/versions/default>"
terraform apply -target=ionoscloud_k8s_node_pool.general -target=local_file.kubeconfig
Expected output:
ionoscloud_k8s_cluster.taskboard: Creation complete after ...
ionoscloud_k8s_node_pool.general: Creation complete after ...
local_file.kubeconfig: Creation complete after ...
Step 2: Connect
export KUBECONFIG="$PWD/kubeconfig.yaml"
kubectl get nodes
Expected output:
NAME STATUS ROLES AGE VERSION
<node-1> Ready <none> ... v<version>
<node-2> Ready <none> ... v<version>
Step 3: Create the namespace and secrets
kubectl create namespace taskboard
kubectl -n taskboard create secret docker-registry taskboard-registry \
--docker-server="$CR_HOST" --docker-username=taskboard-k8s-pull \
--docker-password="$(cat k8s-pull.pass)"
kubectl -n taskboard create secret generic taskboard-db --from-literal=DATABASE_URL="$DATABASE_URL"
Expected output:
namespace/taskboard created
secret/taskboard-registry created
secret/taskboard-db created
Step 4: Deploy the workloads
kubectl -n taskboard apply -f k8s/
kubectl -n taskboard rollout status deploy/taskboard-api
Expected output:
deployment "taskboard-api" successfully rolled out
Step 5: Install the ingress controller and Ingress
helm install traefik traefik/traefik --namespace ingress --create-namespace \
--set service.type=NodePort --set ports.web.nodePort=30080
kubectl -n taskboard apply -f k8s/ingress.yaml
Expected output:
STATUS: deployed
ingress.networking.k8s.io/taskboard created
Step 6: Point the ALB at the nodes
kubectl get nodes -o wide # note each node's address in 10.10.1.0/24
export TF_VAR_ingress_node_ips='["10.10.1.x","10.10.1.y"]'
terraform apply
Expected output:
ionoscloud_target_group.ingress: Creation complete after ...
ionoscloud_application_loadbalancer_forwardingrule.http: Modifications complete after ...
Step 7: Verify the endpoint
curl --silent "http://$(terraform output -raw alb_ip)/api/health"
Expected output:
{"status": "ok"}
Validation Checklist:
- [ ] Both nodes are
Ready - [ ] All TaskBoard pods are
Running, with noImagePullBackOff - [ ] The ALB health check reports the targets as healthy
- [ ]
/api/healthanswers through the ALB IP
Cleanup:
helm uninstall traefik --namespace ingress
terraform destroy -auto-approve
rm -f kubeconfig.yaml
Common Pitfalls
Developer mistakes to avoid with this unit's topic:
-
Expecting a load balancer from a manifest
- Problem: You apply a
type: LoadBalancerService and look for a new ALB, but all traffic arrives at one node, and your logs show internal node IPs instead of client IPs. - Why it happens: On MKS the Service gets a static IP on one ingress node, and kube-proxy NAT replaces the client address.
- Fix: Provision the ALB or NLB separately with Terraform (Section 4.2), or use
externalTrafficPolicy: Localwith the IP bound to the node that runs the ingress controller.
- Problem: You apply a
-
ImagePullBackOffon every pod- Problem:
kubectl describe podshows an authorization error when pulling from the registry. - Why it happens: The pod spec has no
imagePullSecrets, the secret is in another namespace, or the token expired and was deleted. - Fix: Create the
docker-registrysecret in the workload's namespace, reference it in the pod spec, and give the pull token no expiry or rotate it before the expiry date.
- Problem:
-
Changing an immutable node pool argument
- Problem: You raise
ram_sizeand the plan shows a destroy and recreate of the pool. - Why it happens:
cores_count,ram_size,storage_sizeand the other template arguments are immutable. - Fix: Create a new pool with the new size, move workloads with labels or by draining, then delete the old pool.
- Problem: You raise
Summary
You can now run TaskBoard on Managed Kubernetes from code. Terraform creates the cluster, node pools and kubeconfig; workloads pull from the Private Container Registry with a pull secret; and an ingress controller on the nodes sits behind a separately provisioned ALB. You know how maintenance replaces nodes and where to look when a pod fails.
Key Points:
- Read the default version from
/k8s/versions/default; node pools may lag the control plane by at most one minor version - Node template arguments are immutable;
allow_replacerecreates the pool with downtime - A
LoadBalancerService on MKS is a static IP on one node, not an ALB or NLB - Every pod that pulls from the registry needs an
imagePullSecretsentry - Node pool maintenance replaces nodes one by one within a four-hour window; keep pools at 20 nodes or fewer
Important Terminology:
- Node pool: A group of nodes with the same server type, CPU, RAM and storage, managed as
ionoscloud_k8s_node_pool - Kubeconfig: The file with the API server address and credentials that
kubectluses - Ingress node: The worker node that holds the static IP of a
LoadBalancerService - NodePort: A Service type that opens a fixed port on every node, used here as the ALB target port
- imagePullSecrets: The pod spec field that references registry credentials for private images
Next Steps
Continue Learning: Unit 3.3: CI/CD Pipelines for IONOS CLOUD
Related Topics: