# Migrar un servicio a IONOS Cloud

Guía de Bitflow Solutions. Versión web: https://bitflow-solutions.com/guias-tecnicas/migrar-servicio-ionos-cloud/

## ¿Qué vas a aprender?

- Cómo trasladar las piezas de un servicio (aplicación, base de datos y archivos) a sus equivalentes en IONOS Cloud.
- Preparar `ionosctl` en Windows, revisar las cuotas del contrato y crear el centro de datos virtual.
- Crear un clúster de Managed Kubernetes conectado a una base de datos PostgreSQL gestionada en red privada.
- Migrar la base de datos con `pg_dump` / `pg_restore` y los archivos a Object Storage.
- Desplegar, validar y hacer el cambio de DNS con el menor corte posible.

## Requisitos previos

- Un contrato de **IONOS Cloud** con acceso al Data Center Designer (DCD).
- **Windows** con PowerShell, **Scoop** (para instalar ionosctl), **kubectl**, **Docker Desktop** y la **AWS CLI** (se usa contra el Object Storage de IONOS).
- El servicio a migrar empaquetado en una imagen de contenedor (ver la guía de FastAPI o la de Spring Boot) y acceso a su base de datos de origen.
- Conocer lo básico de Kubernetes (ver la guía de administración de Kubernetes).

## Paso a paso

### Equivalencias

| Hoy | IONOS Cloud |
|---|---|
| Aplicación | Managed Kubernetes (o servidores en un VDC) |
| Imágenes | Private Container Registry |
| PostgreSQL | DBaaS PostgreSQL (14-18) en LAN privada |
| Archivos | Object Storage (S3) |
| Balanceo y certificados | ALB / NLB y Certificate Manager |
| DNS | Cloud DNS |

### ionosctl

```powershell
# Instalar ionosctl en Windows con Scoop
scoop bucket add ionos-cloud https://github.com/ionos-cloud/scoop-bucket.git
scoop install ionos-cloud/ionosctl

# Iniciar sesión y crear un token para la migración (válido como máximo un año)
ionosctl login
ionosctl token generate
```

### Ubicaciones y cuotas

```powershell
ionosctl compute location list    # ubicaciones disponibles (de/fra, de/txl, es/vit…)
ionosctl compute contract get     # límites del contrato: cores, RAM, almacenamiento, IPs, clústeres…
```

### Centro de datos virtual

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

### Kubernetes

```powershell
# Clúster (indica siempre la ubicación: por defecto no es europea)
ionosctl compute k8s cluster create --name k8s-produccion --location de/fra --wait

# Node pool en el VDC, conectado también a la LAN privada de la base de datos (LAN 3 en el ejemplo)
ionosctl compute k8s nodepool create --cluster-id CLUSTER_ID --datacenter-id DATACENTER_ID `
  --name pool-a --lan-ids 3 --dhcp=true --wait

# Credenciales para kubectl
ionosctl compute k8s kubeconfig get --cluster-id CLUSTER_ID > kubeconfig.yaml
$env:KUBECONFIG = "$PWD\kubeconfig.yaml"
kubectl get nodes
```

### Registro de contenedores

```powershell
ionosctl container-registry registry create --name empresa-registro --location de/txl
ionosctl container-registry token create --registry-id REGISTRY_ID --name despliegue
# Al token hay que darle permisos (scopes) antes de usarlo; su contraseña se muestra una sola vez
```

### Subir la imagen

```powershell
docker login <servidor-del-registro> -u despliegue
docker tag api-tareas:1.4.0 <servidor-del-registro>/api-tareas:1.4.0
docker push <servidor-del-registro>/api-tareas:1.4.0
```

### Base de datos

```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 pedidos --version 17
```

### Volcado en origen

```powershell
# En el servidor de origen: volcado en formato personalizado (-F c)
pg_dump -U app -h origen.empresa.local -p 5432 -F c pedidos -f pedidos.dump
```

### Restauración

```powershell
# Un pod temporal con el cliente de PostgreSQL dentro del clúster (que llega a la LAN privada)
kubectl run pg-cliente --image=postgres:17 --restart=Never -- sleep 3600
kubectl cp pedidos.dump pg-cliente:/tmp/pedidos.dump

# Restaurar en la base de datos de IONOS (con 4 procesos en paralelo)
kubectl exec -it pg-cliente -- pg_restore -U admin_app -h 192.168.1.10 -p 5432 -F c -d pedidos -j 4 /tmp/pedidos.dump

# Comprobar y borrar el pod temporal
kubectl exec -it pg-cliente -- psql -U admin_app -h 192.168.1.10 -d pedidos -c "SELECT count(*) FROM pedido;"
kubectl delete pod pg-cliente
```

### Archivos a Object Storage

```powershell
# Claves de DCD > Storage & Backup > Object Storage > Key management; región: de
aws configure

aws s3 mb s3://empresa-documentos --endpoint-url https://s3.eu-central-1.ionoscloud.com
aws s3 sync .\documentos s3://empresa-documentos --endpoint-url https://s3.eu-central-1.ionoscloud.com
aws s3 ls s3://empresa-documentos --endpoint-url https://s3.eu-central-1.ionoscloud.com
```

### Desplegar y validar

```powershell
kubectl create secret generic bd-pedidos --from-literal=DB_URL="postgresql://192.168.1.10:5432/pedidos?sslmode=require" `
  --from-literal=DB_USER=admin_app --from-literal=DB_PASSWORD="********"
kubectl apply -f deployment.yaml
kubectl rollout status deployment/api-tareas
kubectl port-forward deploy/api-tareas 8080:80   # probar en http://localhost:8080 antes de abrirlo al público
```

### DNS

- Bajar el TTL con antelación
- Cambiar los registros a la nueva IP
- Mantener el entorno antiguo disponible unos días

### Terraform (opcional)

```hcl
terraform {
  required_providers {
    ionoscloud = { source = "ionos-cloud/ionoscloud", version = ">= 6.4.10" }
  }
}

provider "ionoscloud" {
  token = var.ionos_token
}

resource "ionoscloud_datacenter" "produccion" {
  name     = "vdc-produccion"
  location = "de/fra"
}

resource "ionoscloud_k8s_cluster" "produccion" {
  name        = "k8s-produccion"
  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.produccion.id
  k8s_cluster_id    = ionoscloud_k8s_cluster.produccion.id
  name              = "pool-a"
  k8s_version       = ionoscloud_k8s_cluster.produccion.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"
}
```

## Errores habituales

- **Recursos creados fuera de Europa**: Algunos comandos tienen una ubicación por defecto que no es la que esperas (por ejemplo, la creación del clúster). Indica siempre `--location` y revisa la ubicación de cada recurso.
- **La aplicación no llega a la base de datos**: La base de datos gestionada solo está en la LAN privada. El node pool debe estar conectado a esa misma LAN (`--lan-ids`) con DHCP, y la cadena de conexión debe usar su IP privada.
- **El rango de red de la base de datos no se acepta**: Hay rangos reservados por IONOS que no se pueden usar para la base de datos: `10.208.0.0/12`, `10.233.0.0/18`, `10.233.64.0/18` y `192.168.230.0/24`.
- **«pg_dumpall» o la restauración de roles falla**: En una base de datos gestionada no hay superusuario. Vuelca solo la base de datos con `pg_dump` y crea a mano los usuarios y roles en destino.
- **Se acaba la cuota del contrato a mitad de la migración**: Revisa los límites con `ionosctl compute contract get` antes de empezar y pide la ampliación con tiempo: no es inmediata.
- **La AWS CLI se conecta a Amazon en lugar de a IONOS**: Falta `--endpoint-url` en el comando. Con el Object Storage de IONOS hay que indicarlo siempre, y debe corresponder a la región del bucket.
- **Un Service de tipo LoadBalancer no obtiene IP**: Los node pools privados (detrás de un NAT Gateway) no admiten Services de tipo LoadBalancer. Usa un node pool público para la entrada o un Application Load Balancer.

## Siguientes pasos

- Automatizar el despliegue en el nuevo clúster con un pipeline (ver la guía de CI/CD con GitHub Actions).
- Activar las copias de seguridad y comprobar una restauración real de la base de datos.
- Llevar los registros DNS a Cloud DNS y automatizarlos desde Kubernetes con ExternalDNS.
- Definir alertas sobre el consumo frente a las cuotas del contrato.
