docs(virtualization): document vm-default-images as opt-in package #538
+156
−0
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
|
|
@@ -29,6 +29,84 @@ Cozystack automatically adds prefixes to internal Kubernetes resources: | |||||
| This means if you create a VMInstance named `ubuntu`, the VirtualMachine in Kubernetes will be `vm-instance-ubuntu`. | ||||||
|
|
||||||
|
|
||||||
| ## Default Image Collection (opt-in package) | ||||||
|
|
||||||
| Cozystack ships an optional package, `vm-default-images`, that provisions a curated collection of pre-built Golden Images (Ubuntu, Rocky Linux, AlmaLinux, Debian, CentOS Stream, openSUSE, Alpine) in the `cozy-public` namespace. **The package is disabled by default and must be explicitly enabled.** | ||||||
|
|
||||||
| {{% alert title="Storage requirements" color="warning" %}} | ||||||
| The default image set requests roughly **320Gi** of storage (16 images × 20Gi each). Trim the image list or shrink per-image storage sizes to match your cluster capacity before enabling. | ||||||
| {{% /alert %}} | ||||||
|
|
||||||
| ### Enable the package | ||||||
|
|
||||||
| Add `cozystack.vm-default-images` to `bundles.enabledPackages` in the [Platform Package]({{% ref "/docs/v1.3/operations/configuration/platform-package" %}}): | ||||||
|
|
||||||
| ```bash | ||||||
| kubectl patch packages.cozystack.io cozystack.cozystack-platform --type=json \ | ||||||
| -p '[{"op": "add", "path": "/spec/components/platform/values/bundles/enabledPackages/-", "value": "cozystack.vm-default-images"}]' | ||||||
| ``` | ||||||
|
|
||||||
| Wait a minute for the platform chart to reconcile, then verify the HelmRelease and the DataVolumes: | ||||||
|
|
||||||
| ```bash | ||||||
| kubectl get helmrelease -n cozy-system vm-default-images | ||||||
| kubectl -n cozy-public get dv | ||||||
| ``` | ||||||
|
|
||||||
| DataVolumes provisioned by the package are named `vm-default-images-<image>` and are exposed to tenants as Golden Images named `<image>` (e.g. `ubuntu-24.04`, `debian-12`). | ||||||
|
Contributor
There was a problem hiding this comment. The naming convention for golden images in Cozystack typically requires the
Suggested change
|
||||||
|
|
||||||
| ### Configure the image list | ||||||
|
|
||||||
| Override the default list by editing the `cozystack.vm-default-images` Package and setting values under `spec.components.vm-default-images.values`. The schema is defined in the chart's [values.yaml](https://github.com/cozystack/cozystack/blob/{{< version-pin "cozystack_tag" >}}/packages/system/vm-default-images/values.yaml): | ||||||
|
|
||||||
| - `storageClass` — default StorageClass for all images; falls back to the cluster default when empty. | ||||||
| - `images[]` — list of Golden Image entries. Each entry has: | ||||||
| - `name` — image name as exposed to users (e.g. `ubuntu-24.04`). | ||||||
| - `url` — HTTP(S) URL of the image source. | ||||||
| - `storage` — storage size to allocate (e.g. `20Gi`). | ||||||
| - `storageClass` — per-image override of the global StorageClass. | ||||||
| - `os.family`, `os.name`, `os.version`, `architecture`, `description` — optional metadata surfaced in the UI. | ||||||
|
|
||||||
| Example: trim the default list down to two images and pin the StorageClass: | ||||||
|
|
||||||
| ```yaml | ||||||
| apiVersion: cozystack.io/v1alpha1 | ||||||
| kind: Package | ||||||
| metadata: | ||||||
| name: cozystack.vm-default-images | ||||||
| spec: | ||||||
| variant: default | ||||||
| components: | ||||||
| vm-default-images: | ||||||
| values: | ||||||
| storageClass: replicated | ||||||
| images: | ||||||
| - name: ubuntu-24.04 | ||||||
| url: https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img | ||||||
| storage: 20Gi | ||||||
| os: | ||||||
| family: Linux | ||||||
| name: Ubuntu | ||||||
| version: "24.04" | ||||||
| architecture: amd64 | ||||||
| description: "Ubuntu 24.04 LTS (Noble Numbat) cloud image" | ||||||
| - name: debian-12 | ||||||
| url: https://cloud.debian.org/images/cloud/bookworm/latest/debian-12-generic-amd64.qcow2 | ||||||
| storage: 20Gi | ||||||
| os: | ||||||
| family: Linux | ||||||
| name: Debian | ||||||
| version: "12" | ||||||
| architecture: amd64 | ||||||
| description: "Debian 12 (Bookworm) generic cloud image" | ||||||
| ``` | ||||||
|
|
||||||
| To drop an image after the package is installed, remove it from `images[]` and delete the orphaned DataVolume: | ||||||
|
|
||||||
| ```bash | ||||||
| kubectl -n cozy-public delete dv vm-default-images-<name> | ||||||
|
Contributor
There was a problem hiding this comment. Update the deletion command to use the correct prefix for the DataVolume, consistent with the standard naming convention for golden images in Cozystack.
Suggested change
|
||||||
| ``` | ||||||
|
|
||||||
| ## Creating Golden Images | ||||||
|
|
||||||
| Creating named VM images (golden images) requires an administrator account in Cozystack. | ||||||
|
|
||||||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The naming convention for golden images in Cozystack typically requires the
vm-image-prefix (as defined in the naming conventions table on line 25 and the script section on line 142) for them to be correctly identified and exposed to tenants. If thevm-default-imagespackage follows this standard, the documentation should reflect thevm-image-prefix instead ofvm-default-images-to avoid confusion.