14 min read

Learning Objectives

By the end of this module, you will be able to:

  • Provision a Managed Kubernetes cluster and node pool with `ionoscloud_k8s_cluster` and `ionoscloud_k8s_node_pool`, and retrieve the kubeconfig
  • Deploy TaskBoard's API, frontend and worker with Deployments, Services, ConfigMaps and Secrets that pull from the Private Container Registry
  • Configure ingress for TaskBoard with a NodePort ingress controller behind a separately provisioned Application Load Balancer
  • Scale and upgrade node pools without downtime, using multiple pools for workload isolation
  • Debug failing pods with `kubectl` and know where cluster logs go on IONOS CLOUD

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, kubectl and Helm installed locally
  • The registry, images and k8s-pull.pass from 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 no ImagePullBackOff
  • [ ] The ALB health check reports the targets as healthy
  • [ ] /api/health answers 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:

  1. Expecting a load balancer from a manifest

    • Problem: You apply a type: LoadBalancer Service 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: Local with the IP bound to the node that runs the ingress controller.
  2. ImagePullBackOff on every pod

    • Problem: kubectl describe pod shows 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-registry secret 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.
  3. Changing an immutable node pool argument

    • Problem: You raise ram_size and the plan shows a destroy and recreate of the pool.
    • Why it happens: cores_count, ram_size, storage_size and 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.

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_replace recreates the pool with downtime
  • A LoadBalancer Service on MKS is a static IP on one node, not an ALB or NLB
  • Every pod that pulls from the registry needs an imagePullSecrets entry
  • 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 kubectl uses
  • Ingress node: The worker node that holds the static IP of a LoadBalancer Service
  • 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: