A practical guide to migrating a service to IONOS Cloud, the European provider: a containerised API with its PostgreSQL database and its files, from the inventory to the DNS switch. All the commands have been checked against the official IONOS documentation, and you also have them in the README.md on the left.
What you’ll learn
- How to move the parts of a service (application, database and files) to their equivalents in IONOS Cloud.
- Setting up
ionosctlon Windows, checking the contract quotas and creating the virtual data centre. - Creating a Managed Kubernetes cluster connected to a managed PostgreSQL database on a private network.
- Migrating the database with
pg_dump/pg_restoreand the files to Object Storage. - Deploying, validating and switching DNS with as little downtime as possible.
Prerequisites
- An IONOS Cloud contract with access to the Data Center Designer (DCD).
- Windows with PowerShell, Scoop (to install ionosctl), kubectl, Docker Desktop and the AWS CLI (used against IONOS Object Storage).
- The service to migrate packaged in a container image (see the FastAPI guide or the Spring Boot guide) and access to its source database.
- Basic knowledge of Kubernetes (see the Kubernetes administration guide).
Step by step
1. Plan the migration
Take an inventory of what is being migrated and decide where each part goes:
| What you have today | Where it goes in IONOS Cloud |
|---|---|
| Application servers or containers | Managed Kubernetes (or Dedicated Core / vCPU servers in a VDC) |
| Container images | Private Container Registry |
| PostgreSQL database | DBaaS PostgreSQL (versions 14 to 18), on a private LAN |
| Files and documents | Object Storage, S3-compatible |
| Load balancer and certificates | Application or Network Load Balancer and Certificate Manager |
| DNS | Cloud DNS (or your current provider) |
Choose a location and don’t change it: the virtual data centre (VDC) cannot be moved afterwards. For data in Spain or the EU, for example de/fra (Frankfurt) or es/vit (Vitoria). Lower the TTL of the DNS records you are going to change well in advance, so that the final switch propagates quickly.
2. Install ionosctl and authenticate
# Install ionosctl on Windows with Scoop
scoop bucket add ionos-cloud https://github.com/ionos-cloud/scoop-bucket.git
scoop install ionos-cloud/ionosctl
# Log in and create a token for the migration (valid for one year at most)
ionosctl login
ionosctl token generate
For scripts and pipelines, use the token in the IONOS_TOKEN environment variable instead of a username and password.
3. Check locations and quotas
Each contract has limits on cores, RAM, storage, IPs and clusters. Check them before you start; if they are not enough, ask IONOS support to increase them:
ionosctl compute location list # available locations (de/fra, de/txl, es/vit…)
ionosctl compute contract get # contract limits: cores, RAM, storage, IPs, clusters…
4. Create the virtual data centre and the private network
ionosctl compute datacenter create --name "vdc-production" --location de/fra
Then, in the DCD, add a private LAN to the VDC for the database (LAN 3 in the examples). The managed database is only reachable from private networks.
5. Create the Kubernetes cluster
The node pool is connected to the private LAN so that the pods can reach the database:
# Cluster (always specify the location: the default is not in Europe)
ionosctl compute k8s cluster create --name k8s-production --location de/fra --wait
# Node pool in the VDC, also connected to the database's private LAN (LAN 3 in the example)
ionosctl compute k8s nodepool create --cluster-id CLUSTER_ID --datacenter-id DATACENTER_ID `
--name pool-a --lan-ids 3 --dhcp=true --wait
# Credentials for kubectl
ionosctl compute k8s kubeconfig get --cluster-id CLUSTER_ID > kubeconfig.yaml
$env:KUBECONFIG = "$PWD\kubeconfig.yaml"
kubectl get nodes
6. Push the image to the container registry
ionosctl container-registry registry create --name company-registry --location de/txl
ionosctl container-registry token create --registry-id REGISTRY_ID --name deploy
# The token must be given permissions (scopes) before it is used; its password is shown only once
The registry server name appears in the DCD (Containers → Container Registry). Tag and push the image:
docker login <registry-server> -u deploy
docker tag tasks-api:1.4.0 <registry-server>/tasks-api:1.4.0
docker push <registry-server>/tasks-api:1.4.0
7. Create the managed database
PostgreSQL as a service, on the private LAN and with an IP from that network. Choose the same major version as the source (or higher):
ionosctl dbaas postgres-v2 cluster create `
--datacenter-id DATACENTER_ID --lan-id 3 --cidr 192.168.1.10/24 `
--db-username admin_app --db-password "********" `
--database orders --version 17
Connections are always encrypted with TLS. The users and roles from the source database have to be created by hand in the new one: the managed service does not give superuser access.
8. Migrate the PostgreSQL data
For the final migration, stop the application’s writes at the source so you don’t lose data. Take the dump:
# On the source server: dump in custom format (-F c)
pg_dump -U app -h source.company.local -p 5432 -F c orders -f orders.dump
And restore it from a temporary pod inside the cluster, which can reach the database’s private network:
# A temporary pod with the PostgreSQL client inside the cluster (which can reach the private LAN)
kubectl run pg-client --image=postgres:17 --restart=Never -- sleep 3600
kubectl cp orders.dump pg-client:/tmp/orders.dump
# Restore into the IONOS database (with 4 parallel jobs)
kubectl exec -it pg-client -- pg_restore -U admin_app -h 192.168.1.10 -p 5432 -F c -d orders -j 4 /tmp/orders.dump
# Check and delete the temporary pod
kubectl exec -it pg-client -- psql -U admin_app -h 192.168.1.10 -d orders -c "SELECT count(*) FROM orders;"
kubectl delete pod pg-client
Compare the row counts of the main tables at the source and the target before continuing.
9. Migrate the files to Object Storage
IONOS Object Storage is S3-compatible, so the AWS CLI works as long as you specify the IONOS endpoint in every command. In the example, the de region (Frankfurt):
# Keys from DCD > Storage & Backup > Object Storage > Key management; region: de
aws configure
aws s3 mb s3://company-documents --endpoint-url https://s3.eu-central-1.ionoscloud.com
aws s3 sync .\documents s3://company-documents --endpoint-url https://s3.eu-central-1.ionoscloud.com
aws s3 ls s3://company-documents --endpoint-url https://s3.eu-central-1.ionoscloud.com
10. Deploy the service and validate it
Store the database connection in a secret, deploy and test internally before opening it to the public:
kubectl create secret generic db-orders --from-literal=DB_URL="postgresql://192.168.1.10:5432/orders?sslmode=require" `
--from-literal=DB_USER=admin_app --from-literal=DB_PASSWORD="********"
kubectl apply -f deployment.yaml
kubectl rollout status deployment/tasks-api
kubectl port-forward deploy/tasks-api 8080:80 # test at http://localhost:8080 before opening it to the public
11. Switch DNS and retire the old environment
- Expose the service (Ingress with its load balancer, or an Application Load Balancer) and its certificate.
- Change the DNS records to the new IP. With a low TTL, the change arrives within minutes.
- Monitor logs and metrics for a few days and keep the old environment switched off but available, in case you need to roll back.
- When everything is stable, retire the old environment and raise the TTL again.
12. Optional: describe the infrastructure with Terraform
To make the infrastructure reproducible, the official Terraform provider creates the same resources from code (token in the IONOS_TOKEN variable or in var.ionos_token):
terraform {
required_providers {
ionoscloud = { source = "ionos-cloud/ionoscloud", version = ">= 6.4.10" }
}
}
provider "ionoscloud" {
token = var.ionos_token
}
resource "ionoscloud_datacenter" "production" {
name = "vdc-production"
location = "de/fra"
}
resource "ionoscloud_k8s_cluster" "production" {
name = "k8s-production"
k8s_version = "1.31.2"
maintenance_window {
day_of_the_week = "Sunday"
time = "09:00:00Z"
}
}
resource "ionoscloud_k8s_node_pool" "general" {
datacenter_id = ionoscloud_datacenter.production.id
k8s_cluster_id = ionoscloud_k8s_cluster.production.id
name = "pool-a"
k8s_version = ionoscloud_k8s_cluster.production.k8s_version
availability_zone = "AUTO"
storage_type = "SSD"
node_count = 2
cores_count = 2
ram_size = 4096
storage_size = 40
server_type = "DedicatedCore"
cpu_family = "INTEL_XEON"
}
Common errors
Resources created outside Europe
Some commands have a default location that is not the one you expect (for example, cluster creation). Always specify --location and check the location of each resource.
The application cannot reach the database
The managed database is only on the private LAN. The node pool must be connected to that same LAN (--lan-ids) with DHCP, and the connection string must use its private IP.
The database network range is not accepted
Some ranges are reserved by IONOS and cannot be used for the database: 10.208.0.0/12, 10.233.0.0/18, 10.233.64.0/18 and 192.168.230.0/24.
“pg_dumpall” or restoring roles fails
A managed database has no superuser. Dump only the database with pg_dump and create the users and roles by hand at the target.
The contract quota runs out halfway through the migration
Check the limits with ionosctl compute contract get before you start and request the increase in good time: it is not immediate.
The AWS CLI connects to Amazon instead of IONOS
The command is missing --endpoint-url. With IONOS Object Storage you must always specify it, and it must match the bucket’s region.
A Service of type LoadBalancer does not get an IP
Private node pools (behind a NAT Gateway) do not support Services of type LoadBalancer. Use a public node pool for ingress or an Application Load Balancer.
Next steps
- Automate deployment to the new cluster with a pipeline (see the CI/CD with GitHub Actions guide).
- Enable backups and test a real restore of the database.
- Move the DNS records to Cloud DNS and automate them from Kubernetes with ExternalDNS.
- Define alerts on usage against the contract quotas.