|
1 | 1 | # VM Import Adoption Design |
2 | 2 |
|
3 | | -## Contexte |
| 3 | +## Context |
4 | 4 |
|
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`). |
7 | 7 |
|
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. |
9 | 9 |
|
10 | | -## Solution proposée |
| 10 | +## Solution |
11 | 11 |
|
12 | | -### 1. Lifecycle des ressources |
| 12 | +### 1. Resource Lifecycle |
13 | 13 |
|
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) |
16 | 16 | - `NetworkMap` |
17 | 17 | - `StorageMap` |
18 | 18 | - `Plan` |
19 | 19 | - `Migration` |
20 | 20 |
|
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) |
24 | 24 |
|
25 | | -#### Ressources créées par Forklift (NON gérées par Helm) |
| 25 | +#### Resources created by Forklift (NOT managed by Helm) |
26 | 26 | - `VirtualMachine` (KubeVirt) |
27 | 27 | - `DataVolume` (CDI) |
28 | 28 | - `PersistentVolumeClaim` |
29 | 29 |
|
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` |
33 | 33 |
|
34 | | -### 2. Mécanisme d'adoption |
| 34 | +### 2. Adoption Mechanism |
35 | 35 |
|
36 | | -#### Phase 1 : Labels automatiques (via Forklift) |
| 36 | +#### Phase 1: Forklift Labels (automatic) |
37 | 37 |
|
38 | | -Les VMs créées par Forklift ont déjà des labels : |
| 38 | +VMs created by Forklift already have labels: |
39 | 39 | ```yaml |
40 | 40 | metadata: |
41 | 41 | labels: |
42 | 42 | forklift.konveyor.io/plan: <plan-name> |
43 | 43 | forklift.konveyor.io/vm-name: <vm-name> |
44 | 44 | ``` |
45 | 45 |
|
46 | | -On ajoute via annotations sur le Plan : |
| 46 | +The Plan gets adoption annotations when `enableAdoption: true`: |
47 | 47 | ```yaml |
48 | 48 | metadata: |
49 | 49 | annotations: |
50 | 50 | vm-import.cozystack.io/adoption-enabled: "true" |
51 | 51 | vm-import.cozystack.io/target-namespace: {{ .Release.Namespace }} |
52 | 52 | ``` |
53 | 53 |
|
54 | | -#### Phase 2 : Controller d'adoption (nouveau composant) |
| 54 | +#### Phase 2: VM Adoption Controller |
55 | 55 |
|
56 | | -Un controller léger (`vm-import-adoption-controller`) : |
| 56 | +A dedicated controller (`vm-adoption-controller`) deployed as a platform package: |
57 | 57 |
|
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: |
61 | 62 | ```yaml |
62 | 63 | labels: |
63 | 64 | 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>" |
67 | 66 | ``` |
68 | 67 |
|
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 |
87 | 71 |
|
88 | | -Le dashboard Cozystack affiche les VMs avec le label `cozystack.io/adopted: "true"` dans une section "Imported VMs". |
| 72 | +#### Phase 3: Dashboard Visibility |
89 | 73 |
|
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 |
94 | 80 |
|
95 | | -### 3. Adoption complète (optionnelle) |
| 81 | +### 3. Manual Adoption (fallback) |
96 | 82 |
|
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: |
98 | 84 |
|
99 | | -**Script helper fourni** : `adopt-vm.sh` |
100 | 85 | ```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] |
190 | 87 | ``` |
191 | 88 |
|
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. |
212 | 90 |
|
213 | | -#### Option 1: Dashboard Management (Automatic) |
214 | | -VMs are automatically labeled and appear in the dashboard. Basic operations (view, start, stop) available. |
| 91 | +## Architecture |
215 | 92 |
|
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 |
220 | 93 | ``` |
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 |
237 | 105 | ``` |
238 | 106 |
|
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 |
257 | 108 |
|
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