# Migrate a service to IONOS Cloud

A Bitflow Solutions guide. Web version: https://bitflow-solutions.com/en/guias-tecnicas/migrate-service-to-ionos-cloud/

## What you’ll learn

- How to move the parts of a service (application, database and files) to their equivalents in IONOS Cloud.
- Setting up `ionosctl` on 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_restore` and 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

### Equivalences

| Today | IONOS Cloud |
|---|---|
| Application | Managed Kubernetes (or servers in a VDC) |
| Images | Private Container Registry |
| PostgreSQL | DBaaS PostgreSQL (14-18) on a private LAN |
| Files | Object Storage (S3) |
| Load balancing and certificates | ALB / NLB and Certificate Manager |
| DNS | Cloud DNS |

### ionosctl

```powershell
# 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
```

### Locations and quotas

```powershell
ionosctl compute location list    # available locations (de/fra, de/txl, es/vit…)
ionosctl compute contract get     # contract limits: cores, RAM, storage, IPs, clusters…
```

### Virtual data centre

```powershell
ionosctl compute datacenter create --name "vdc-production" --location de/fra
```

### Kubernetes

```powershell
# 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
```

### Container registry

```powershell
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
```

### Push the image

```powershell
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
```

### Database

```powershell
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
```

### Dump at the source

```powershell
# 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
```

### Restore

```powershell
# 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
```

### Files to Object Storage

```powershell
# 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
```

### Deploy and validate

```powershell
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
```

### DNS

- Lower the TTL well in advance
- Change the records to the new IP
- Keep the old environment available for a few days

### Terraform (optional)

```hcl
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.
