Skip to content

Commit 8f3f95b

Browse files
Matthieuclaude
andcommitted
fix(vm-import): fix adoption workflow to properly integrate imported VMs
The vm-adoption-controller had several architectural issues preventing imported VMs from appearing in the Cozystack dashboard: - Helm created a duplicate VM instead of adopting the existing one. Fixed by passing fullnameOverride and pre-annotating the Forklift VM with Helm ownership metadata (meta.helm.sh/release-name). - Disk lookup failed because vm-instance expected vm-disk-<name> but Forklift DVs have arbitrary names. Added dvName field for direct DataVolume references. - Multus networks were lost (subnets always empty). Now extracted from the existing VM spec. - Used deprecated running boolean instead of runStrategy enum. - cloudInitSeed changed firmware UUID, risking cloud-init re-execution. Also fixes: PackageSource wrong API, controller missing from IaaS bundle, default adoption=true on Plan lookup failure, DISK_COUNT crash in adopt-vm.sh, and cleans up AI-generated documentation. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]> Signed-off-by: Matthieu <[email protected]>
1 parent eaa5532 commit 8f3f95b

9 files changed

Lines changed: 248 additions & 557 deletions

File tree

Lines changed: 58 additions & 205 deletions
Original file line numberDiff line numberDiff line change
@@ -1,260 +1,113 @@
11
# VM Import Adoption Design
22

3-
## Contexte
3+
## Context
44

5-
Forklift importe des VMs depuis VMware et crée des objets `VirtualMachine` KubeVirt natifs.
6-
Cozystack gère les VMs via des applications Helm (`vm-instance`, `vm-disk`).
5+
Forklift imports VMs from VMware and creates native KubeVirt `VirtualMachine` resources.
6+
Cozystack manages VMs via Helm applications (`vm-instance`, `vm-disk`).
77

8-
**Problème** : Les VMs importées ne sont pas visibles/gérables via le dashboard Cozystack car elles ne sont pas créées via les applications Helm standard.
8+
**Problem**: Imported VMs are not visible/manageable through the Cozystack dashboard because they are not created through standard Helm applications.
99

10-
## Solution proposée
10+
## Solution
1111

12-
### 1. Lifecycle des ressources
12+
### 1. Resource Lifecycle
1313

14-
#### Ressources Helm (gérées par vm-import)
15-
- `Provider` (source et destination)
14+
#### Helm Resources (managed by vm-import)
15+
- `Provider` (source and destination)
1616
- `NetworkMap`
1717
- `StorageMap`
1818
- `Plan`
1919
- `Migration`
2020

21-
**Comportement à la suppression de vm-import** :
22-
- Les `Providers` sont conservés avec `helm.sh/resource-policy: keep` (peuvent être réutilisés)
23-
- Les autres ressources (Plan, Migration, Maps) sont supprimées (objets temporaires de migration)
21+
**On vm-import deletion**:
22+
- `Providers` are kept with `helm.sh/resource-policy: keep` (reusable for future imports)
23+
- Other resources (Plan, Migration, Maps) are deleted (temporary migration objects)
2424

25-
#### Ressources créées par Forklift (NON gérées par Helm)
25+
#### Resources created by Forklift (NOT managed by Helm)
2626
- `VirtualMachine` (KubeVirt)
2727
- `DataVolume` (CDI)
2828
- `PersistentVolumeClaim`
2929

30-
**Comportement à la suppression de vm-import** :
31-
- **JAMAIS supprimées** car elles ne font pas partie de la release Helm
32-
- Les VMs restent opérationnelles et gérables via `kubectl`
30+
**On vm-import deletion**:
31+
- **NEVER deleted** as they are not part of the Helm release
32+
- VMs remain operational and manageable via `kubectl`
3333

34-
### 2. Mécanisme d'adoption
34+
### 2. Adoption Mechanism
3535

36-
#### Phase 1 : Labels automatiques (via Forklift)
36+
#### Phase 1: Forklift Labels (automatic)
3737

38-
Les VMs créées par Forklift ont déjà des labels :
38+
VMs created by Forklift already have labels:
3939
```yaml
4040
metadata:
4141
labels:
4242
forklift.konveyor.io/plan: <plan-name>
4343
forklift.konveyor.io/vm-name: <vm-name>
4444
```
4545
46-
On ajoute via annotations sur le Plan :
46+
The Plan gets adoption annotations when `enableAdoption: true`:
4747
```yaml
4848
metadata:
4949
annotations:
5050
vm-import.cozystack.io/adoption-enabled: "true"
5151
vm-import.cozystack.io/target-namespace: {{ .Release.Namespace }}
5252
```
5353

54-
#### Phase 2 : Controller d'adoption (nouveau composant)
54+
#### Phase 2: VM Adoption Controller
5555

56-
Un controller léger (`vm-import-adoption-controller`) :
56+
A dedicated controller (`vm-adoption-controller`) deployed as a platform package:
5757

58-
1. **Surveille** les VMs avec label `forklift.konveyor.io/plan`
59-
2. **Détecte** l'annotation `vm-import.cozystack.io/adoption-enabled` sur le Plan correspondant
60-
3. **Adopte** la VM en ajoutant des labels Cozystack :
58+
1. **Watches** VMs with label `forklift.konveyor.io/plan`
59+
2. **Checks** the Plan annotation `vm-import.cozystack.io/adoption-enabled`
60+
3. **Creates** a `VMInstance` CRD via the Cozystack aggregated API
61+
4. **Labels** the original VM as adopted:
6162
```yaml
6263
labels:
6364
cozystack.io/adopted: "true"
64-
cozystack.io/source: "vm-import"
65-
cozystack.io/original-plan: <plan-name>
66-
app.kubernetes.io/managed-by: "cozystack"
65+
cozystack.io/adopted-by: "<vminstance-name>"
6766
```
6867

69-
4. **Crée** des objets ConfigMap pour le tracking :
70-
```yaml
71-
apiVersion: v1
72-
kind: ConfigMap
73-
metadata:
74-
name: vm-adopted-<vm-name>
75-
namespace: <namespace>
76-
labels:
77-
cozystack.io/type: "adopted-vm"
78-
data:
79-
vmName: <vm-name>
80-
sourcePlan: <plan-name>
81-
sourceType: "vmware"
82-
adoptedAt: <timestamp>
83-
managementEndpoint: "kubectl"
84-
```
85-
86-
#### Phase 3 : Visibilité dans le dashboard
68+
The `VMInstance` creation triggers the standard Cozystack controller flow:
69+
- `cozystack-controller` creates a `HelmRelease` for the VMInstance
70+
- The VM becomes visible and manageable in the Cozystack dashboard
8771

88-
Le dashboard Cozystack affiche les VMs avec le label `cozystack.io/adopted: "true"` dans une section "Imported VMs".
72+
#### Phase 3: Dashboard Visibility
8973

90-
Options de gestion :
91-
- **View only** : Afficher l'état, les métriques
92-
- **Basic operations** : Start/Stop via KubeVirt API
93-
- **Advanced** : Créer une release `vm-instance` pour adoption complète (gestion Helm)
74+
Adopted VMs appear in the dashboard as regular VM Instances with full management capabilities:
75+
- Start/stop/restart
76+
- Console access
77+
- Resource modification
78+
- Disk management
79+
- Network configuration
9480

95-
### 3. Adoption complète (optionnelle)
81+
### 3. Manual Adoption (fallback)
9682

97-
Un utilisateur peut "fully adopt" une VM en créant manuellement une release `vm-instance` qui référence la VM existante.
83+
If automatic adoption is disabled or fails, users can manually adopt a VM using:
9884

99-
**Script helper fourni** : `adopt-vm.sh`
10085
```bash
101-
#!/bin/bash
102-
# adopt-vm.sh <vm-name> <namespace>
103-
# Crée une HelmRelease vm-instance qui adopte une VM existante
104-
105-
VM_NAME=$1
106-
NAMESPACE=$2
107-
108-
# Extrait les specs de la VM existante
109-
kubectl get vm "$VM_NAME" -n "$NAMESPACE" -o yaml > /tmp/vm-spec.yaml
110-
111-
# Génère values.yaml pour vm-instance
112-
# (mapping des specs existantes vers le format vm-instance)
113-
114-
# Crée la HelmRelease avec adoption
115-
cat <<EOF | kubectl apply -f -
116-
apiVersion: helm.toolkit.fluxcd.io/v2beta1
117-
kind: HelmRelease
118-
metadata:
119-
name: $VM_NAME
120-
namespace: $NAMESPACE
121-
spec:
122-
chart:
123-
spec:
124-
chart: vm-instance
125-
sourceRef:
126-
kind: HelmRepository
127-
name: cozystack
128-
install:
129-
createNamespace: false
130-
# N'essaie pas de créer la VM (elle existe déjà)
131-
disableWait: true
132-
upgrade:
133-
# Ne modifie pas la VM existante
134-
force: false
135-
values:
136-
# Valeurs extraites de la VM existante
137-
...
138-
EOF
139-
```
140-
141-
### 4. Implémentation
142-
143-
#### Fichiers à modifier
144-
145-
1. **packages/apps/vm-import/templates/plan.yaml**
146-
```yaml
147-
metadata:
148-
annotations:
149-
vm-import.cozystack.io/adoption-enabled: "true"
150-
vm-import.cozystack.io/target-namespace: {{ .Release.Namespace }}
151-
```
152-
153-
2. **packages/apps/vm-import/templates/provider.yaml**
154-
```yaml
155-
metadata:
156-
annotations:
157-
helm.sh/resource-policy: keep # Providers conservés
158-
```
159-
160-
3. **packages/apps/vm-import/values.yaml**
161-
```yaml
162-
## @param {bool} enableAdoption - Automatically label imported VMs for Cozystack adoption.
163-
enableAdoption: true
164-
```
165-
166-
#### Nouveau package : vm-import-adoption-controller
167-
168-
Structure :
169-
```
170-
packages/system/vm-import-adoption-controller/
171-
├── Chart.yaml
172-
├── templates/
173-
│ ├── deployment.yaml # Controller deployment
174-
│ ├── serviceaccount.yaml
175-
│ ├── role.yaml # RBAC: watch VMs, Plans; create ConfigMaps
176-
│ └── rolebinding.yaml
177-
└── images/
178-
└── Dockerfile # Controller image
179-
└── main.go # Controller logic
180-
```
181-
182-
Controller logic (pseudo-code) :
183-
```go
184-
// Watch VirtualMachines with label "forklift.konveyor.io/plan"
185-
// For each VM:
186-
// 1. Get the Plan referenced
187-
// 2. Check if Plan has annotation "vm-import.cozystack.io/adoption-enabled"
188-
// 3. If yes, add Cozystack labels to VM
189-
// 4. Create adoption ConfigMap
86+
./docs/scripts/adopt-vm.sh <vm-name> <namespace> [instance-type] [profile]
19087
```
19188

192-
### 5. Documentation
193-
194-
#### README.md amélioré
195-
196-
```markdown
197-
## VM Lifecycle
198-
199-
### Import Phase
200-
When you create a `vm-import` application:
201-
1. Forklift migrates VMs from VMware to KubeVirt
202-
2. VMs are created as native KubeVirt `VirtualMachine` resources
203-
3. If `enableAdoption: true` (default), VMs are automatically labeled for Cozystack tracking
204-
205-
### Post-Import
206-
Imported VMs are:
207-
- ✅ **Visible** in the Cozystack dashboard (as "Imported VMs")
208-
- ✅ **Manageable** via `kubectl` and KubeVirt APIs
209-
- ✅ **Persistent** - they are NOT deleted when you remove the `vm-import` application
210-
211-
### Adoption Options
89+
This generates a values file for creating a `VMInstance` Helm release.
21290

213-
#### Option 1: Dashboard Management (Automatic)
214-
VMs are automatically labeled and appear in the dashboard. Basic operations (view, start, stop) available.
91+
## Architecture
21592

216-
#### Option 2: Full Helm Management (Manual)
217-
Create a `vm-instance` application referencing the existing VM:
218-
```bash
219-
./adopt-vm.sh my-imported-vm my-namespace
22093
```
221-
222-
### Cleanup
223-
To delete a `vm-import` application:
224-
```bash
225-
kubectl delete vmimport my-import -n my-namespace
226-
```
227-
228-
**What gets deleted**:
229-
- ❌ Migration Plan
230-
- ❌ Network/Storage Maps
231-
- ✅ Providers (kept for reuse)
232-
233-
**What is preserved**:
234-
- ✅ All imported VMs
235-
- ✅ All DataVolumes and disks
236-
- ✅ Adoption tracking ConfigMaps
94+
Forklift imports VM
95+
↓
96+
VirtualMachine (KubeVirt) created
97+
↓
98+
vm-adoption-controller detects it
99+
↓
100+
VMInstance (Cozystack CRD) created
101+
↓
102+
cozystack-controller creates HelmRelease
103+
↓
104+
VM visible in dashboard
237105
```
238106
239-
## Avantages de cette approche
240-
241-
1. **Non-destructif** : Suppression de vm-import ne supprime jamais les VMs
242-
2. **Flexible** : Les utilisateurs choisissent le niveau d'adoption (basic vs full Helm)
243-
3. **Traçable** : ConfigMaps gardent l'historique d'import
244-
4. **Évolutif** : Le controller peut être enrichi progressivement
245-
5. **Compatible** : Les VMs restent des objets KubeVirt standard
246-
247-
## Migration Path
248-
249-
### Court terme (MVP)
250-
1. Ajouter annotations sur Plan/Provider
251-
2. Documenter clairement le lifecycle
252-
3. Fournir script `adopt-vm.sh`
253-
254-
### Moyen terme
255-
1. Implémenter controller d'adoption
256-
2. Intégrer dans le dashboard
107+
## Advantages
257108
258-
### Long terme
259-
1. Adoption Helm automatique (optionnelle)
260-
2. Synchronisation bidirectionnelle VM <-> Helm
109+
1. **Non-destructive**: Deleting vm-import never deletes VMs
110+
2. **Automatic**: VMs appear in dashboard within ~30 seconds
111+
3. **Traceable**: Labels and annotations track the import source
112+
4. **Standard**: Uses the same VMInstance CRD as manually created VMs
113+
5. **Compatible**: VMs remain standard KubeVirt objects

0 commit comments

Comments
 (0)