From e17ed59be68aede20841758d0a6b7a9bbea5106c Mon Sep 17 00:00:00 2001 From: Robert Helewka Date: Sat, 11 Apr 2026 08:25:51 -0400 Subject: [PATCH] docs: document terraform import for incus containers and remove korax Add comprehensive terraform import documentation for Incus resources. Includes syntax for importing containers with for_each keys, retrieving image fingerprints, and specific import commands for Uranian hosts. Covers troubleshooting for common import issues and state verification. Removes obsolete korax.helu.ca host from ansible inventory. --- ansible/inventory/host_vars/korax.helu.ca.yml | 20 ----- ansible/inventory/host_vars/portia.incus.yml | 1 - .../inventory/host_vars/prospero.incus.yml | 1 - ansible/inventory/host_vars/puck.incus.yml | 2 - .../inventory/host_vars/rosalind.incus.yml | 2 - ansible/inventory/hosts | 1 - docs/ouranos.md | 76 +++++++++++++++++++ 7 files changed, 76 insertions(+), 27 deletions(-) delete mode 100644 ansible/inventory/host_vars/korax.helu.ca.yml diff --git a/ansible/inventory/host_vars/korax.helu.ca.yml b/ansible/inventory/host_vars/korax.helu.ca.yml deleted file mode 100644 index 481fbf2..0000000 --- a/ansible/inventory/host_vars/korax.helu.ca.yml +++ /dev/null @@ -1,20 +0,0 @@ ---- -# Korax Configuration -# Services: alloy, kernos - -services: - - alloy - - kernos - -# Alloy -alloy_log_level: "warn" -# Kernos MCP Shell Server Configuration -kernos_user: harper -kernos_group: harper -kernos_directory: /srv/kernos -kernos_port: 22021 -kernos_host: "0.0.0.0" -kernos_log_level: INFO -kernos_log_format: json -kernos_environment: sandbox -kernos_allow_commands: "apt,awk,base64,bash,cat,chmod,cp,curl,cut,date,dd,df,dig,dmesg,du,echo,env,file,find,free,git,grep,gunzip,gzip,head,host,hostname,id,jq,kill,less,ln,ls,lsblk,lspci,lsusb,make,mkdir,mv,nc,node,nohup,npm,npx,ping,pip,pkill,pnpm,printenv,ps,pwd,python3,rm,rsync,run-captured,scp,sed,sleep,sort,source,ssh,ssh-keygen,ssh-keyscan,stat,sudo,tail,tar,tee,timeout,touch,tr,tree,uname,uniq,unzip,uptime,wc,wget,which,whoami,xargs,xz,zip" \ No newline at end of file diff --git a/ansible/inventory/host_vars/portia.incus.yml b/ansible/inventory/host_vars/portia.incus.yml index 240d574..f763022 100644 --- a/ansible/inventory/host_vars/portia.incus.yml +++ b/ansible/inventory/host_vars/portia.incus.yml @@ -3,7 +3,6 @@ # Services: alloy, postgresql # Note: PgAdmin moved to Prospero (PPLG stack) -ansible_user: robert services: - alloy diff --git a/ansible/inventory/host_vars/prospero.incus.yml b/ansible/inventory/host_vars/prospero.incus.yml index 37c7738..23e75a9 100644 --- a/ansible/inventory/host_vars/prospero.incus.yml +++ b/ansible/inventory/host_vars/prospero.incus.yml @@ -2,7 +2,6 @@ # Prospero Configuration - PPLG Observability & Admin Stack # Services: pplg (PgAdmin, Prometheus, Loki, Grafana + OAuth2-Proxy) -ansible_user: robert services: - alloy diff --git a/ansible/inventory/host_vars/puck.incus.yml b/ansible/inventory/host_vars/puck.incus.yml index a0cceef..6a610e8 100644 --- a/ansible/inventory/host_vars/puck.incus.yml +++ b/ansible/inventory/host_vars/puck.incus.yml @@ -2,8 +2,6 @@ # Puck Configuration - Application Runtime # Services: alloy, docker, lxqt, jupyterlab -ansible_user: robert - services: - alloy - docker diff --git a/ansible/inventory/host_vars/rosalind.incus.yml b/ansible/inventory/host_vars/rosalind.incus.yml index 3a88cfb..f29f063 100644 --- a/ansible/inventory/host_vars/rosalind.incus.yml +++ b/ansible/inventory/host_vars/rosalind.incus.yml @@ -2,8 +2,6 @@ # Rosalind Configuration - GO, Node.js, PHP Apps # Services: alloy, gitea, lobechat, nextcloud -ansible_user: robert - services: - alloy - anythingllm diff --git a/ansible/inventory/hosts b/ansible/inventory/hosts index 0516121..12700aa 100644 --- a/ansible/inventory/hosts +++ b/ansible/inventory/hosts @@ -17,7 +17,6 @@ ubuntu: rosalind.incus: sycorax.incus: titania.incus: - korax.helu.ca: # Service-specific groups for targeted deployments agent_s: diff --git a/docs/ouranos.md b/docs/ouranos.md index 349a5ef..79ec59d 100644 --- a/docs/ouranos.md +++ b/docs/ouranos.md @@ -303,6 +303,82 @@ ansible-playbook sandbox_down.yml 3. **Apply** — Provision with `terraform apply` 4. **Verify** — Check outputs and container status +### Terraform Import + +When containers or other resources are created manually (outside Terraform) or need to be re-imported after recreation, use `terraform import` to sync the Terraform state with existing infrastructure. + +#### Import Syntax + +The correct import format for Incus resources requires quoting resource addresses with `for_each` keys and using the full ID including image fingerprints: + +```bash +# Import a container with correct syntax +terraform import 'incus_instance.uranian_hosts[""]' ouranos/,image= +``` + +#### Getting Image Fingerprints + +First, get the fingerprint of the image resource from Terraform state: + +```bash +cd terraform +terraform state show incus_image.noble | grep fingerprint +# Output: fingerprint = "75cde3e755b0e657c05f67e03a42683217b233b0339448be747845747df58644" + +terraform state show incus_image.questing | grep fingerprint +# Output: fingerprint = "e78dd4a406b7fa3592ed0a6048862260b3d2e50c76e32a6169930245c0a13fdf" +``` + +#### Importing All Uranian Hosts + +Replace containers missing from state (or re-import after manual recreation): + +```bash +# Containers using noble image +terraform import 'incus_instance.uranian_hosts["ariel"]' ouranos/ariel,image=75cde3e755b0e657c05f67e03a42683217b233b0339448be747845747df58644 +terraform import 'incus_instance.uranian_hosts["miranda"]' ouranos/miranda,image=75cde3e755b0e657c05f67e03a42683217b233b0339448be747845747df58644 +terraform import 'incus_instance.uranian_hosts["oberon"]' ouranos/oberon,image=75cde3e755b0e657c05f67e03a42683217b233b0339448be747845747df58644 +terraform import 'incus_instance.uranian_hosts["portia"]' ouranos/portia,image=75cde3e755b0e657c05f67e03a42683217b233b0339448be747845747df58644 +terraform import 'incus_instance.uranian_hosts["prospero"]' ouranos/prospero,image=75cde3e755b0e657c05f67e03a42683217b233b0339448be747845747df58644 +terraform import 'incus_instance.uranian_hosts["rosalind"]' ouranos/rosalind,image=75cde3e755b0e657c05f67e03a42683217b233b0339448be747845747df58644 +terraform import 'incus_instance.uranian_hosts["sycorax"]' ouranos/sycorax,image=75cde3e755b0e657c05f67e03a42683217b233b0339448be747845747df58644 +terraform import 'incus_instance.uranian_hosts["titania"]' ouranos/titania,image=75cde3e755b0e657c05f67e03a42683217b233b0339448be747845747df58644 + +# Containers using questing image +terraform import 'incus_instance.uranian_hosts["caliban"]' ouranos/caliban,image=e78dd4a406b7fa3592ed0a6048862260b3d2e50c76e32a6169930245c0a13fdf +terraform import 'incus_instance.uranian_hosts["puck"]' ouranos/puck,image=e78dd4a406b7fa3592ed0a6048862260b3d2e50c76e32a6169930245c0a13fdf +``` + +#### Storage Bucket Import + +For storage buckets, use the `//` format: + +```bash +terraform import incus_storage_bucket. ouranos/default/ +``` + +#### Common Issues + +1. **Import ID format errors**: Use quotes around resource addresses with `for_each` keys: `'incus_instance.uranian_hosts["name"]'` + +2. **Image replacement on import**: Importing without specifying the image fingerprint will cause Terraform to replace the container on next apply. Always include `image=` in the import ID. + +3. **Tainted state**: If a resource shows "will be created" but already exists, it may be tainted. Remove from state and re-import: + ```bash + terraform state rm 'incus_instance.uranian_hosts["name"]' + terraform import 'incus_instance.uranian_hosts["name"]' ouranos/name,image= + ``` + +#### Verify Import + +After importing, verify with `terraform plan`: + +```bash +terraform plan +# Should show: Plan: 0 to add, 0 to change, 0 to destroy +# (Minor "update in-place" changes are normal for state sync of computed attributes) +``` + ### Ansible Workflow 1. **Bootstrap** — Update packages, install essentials (`apt_update.yml`)