diff --git a/content/en/docs/next/virtualization/vm-image.md b/content/en/docs/next/virtualization/vm-image.md index 97b80062..085f1226 100644 --- a/content/en/docs/next/virtualization/vm-image.md +++ b/content/en/docs/next/virtualization/vm-image.md @@ -22,18 +22,48 @@ Cozystack automatically adds prefixes to internal Kubernetes resources: | User-visible name | Resource Kind | Actual resource name | |-------------------|---------------|----------------------| -| `` | DataVolume in `cozy-public` (golden image) | `vm-image-` | +| `` | DataVolume in `cozy-public` (golden image) | `vm-default-images-` | | `` | DataVolume created from VMDisk | `vm-disk-` | | `` | VirtualMachine created from VMInstance | `vm-instance-` | This means if you create a VMInstance named `ubuntu`, the VirtualMachine in Kubernetes will be `vm-instance-ubuntu`. +## Default Image Collection + +Cozystack ships with the **`vm-default-images`** system package that automatically provisions a curated collection of OS images in the `cozy-public` namespace. +No manual setup is required — images become available as soon as the package is installed. + +The default collection includes: + +| Image name | Description | +|---|---| +| `ubuntu-20.04` | Ubuntu 20.04 LTS (Focal Fossa) | +| `ubuntu-22.04` | Ubuntu 22.04 LTS (Jammy Jellyfish) | +| `ubuntu-24.04` | Ubuntu 24.04 LTS (Noble Numbat) | +| `debian-12` | Debian 12 (Bookworm) | +| `debian-13` | Debian 13 (Trixie) | +| `rocky-8` | Rocky Linux 8 | +| `rocky-9` | Rocky Linux 9 | +| `rocky-10` | Rocky Linux 10 | +| `almalinux-8` | AlmaLinux 8 | +| `almalinux-9` | AlmaLinux 9 | +| `almalinux-10` | AlmaLinux 10 | +| `centos-stream-9` | CentOS Stream 9 | +| `centos-stream-10` | CentOS Stream 10 | +| `opensuse-leap-15.6` | openSUSE Leap 15.6 | +| `opensuse-leap-16.0` | openSUSE Leap 16.0 | +| `alpine-3.21` | Alpine Linux 3.21 | + +You can list all available images with: +```bash +kubectl -n cozy-public get dv -l app.kubernetes.io/managed-by=cozystack +``` -## Creating Golden Images +## Adding Custom Golden Images -Creating named VM images (golden images) requires an administrator account in Cozystack. +Creating additional named VM images requires an administrator account in Cozystack. -The simplest way to create named VM images is by using the CLI script. +The simplest way to add a custom image is by using the CLI script. The [`cdi_golden_image_create.sh`](https://github.com/cozystack/cozystack/blob/{{< version-pin "cozystack_tag" >}}/hack/cdi_golden_image_create.sh) script can be downloaded from the Cozystack {{< version-pin "cozystack_tag" >}} release tag: ```bash @@ -44,43 +74,33 @@ chmod +x cdi_golden_image_create.sh This script uses your `kubectl` configuration. Before running it, ensure that your configuration points to the target Cozystack cluster. -To create a named image, or to download one of the default images, run the script with the image name and its URL: +To add a custom image, run the script with the image name and its URL: ```bash cdi_golden_image_create.sh '' 'https://' ``` -For example, all five default images, available with the `virtual-machine` application, can be downloaded for faster use: +For example, to add a Talos image: ```bash -cdi_golden_image_create.sh 'ubuntu' 'https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img' -cdi_golden_image_create.sh 'fedora' 'https://download.fedoraproject.org/pub/fedora/linux/releases/40/Cloud/x86_64/images/Fedora-Cloud-Base-Generic.x86_64-40-1.14.qcow2' -cdi_golden_image_create.sh 'cirros' 'https://download.cirros-cloud.net/0.6.2/cirros-0.6.2-x86_64-disk.img' -cdi_golden_image_create.sh 'alpine' 'https://dl-cdn.alpinelinux.org/alpine/v3.20/releases/cloud/nocloud_alpine-3.20.2-x86_64-bios-tiny-r0.qcow2' cdi_golden_image_create.sh 'talos' 'https://github.com/siderolabs/talos/releases/download/v1.7.6/nocloud-amd64.raw.xz' ``` -Internally, the script creates Kubernetes resources of `kind: DataVolume` in the `cozy-public` namespace. -The resource name is the disk’s name prefixed with `vm-image-`. -For example, the resource `vm-image-ubuntu` creates a saved image named `ubuntu`. +Internally, the script creates a Kubernetes resource of `kind: DataVolume` in the `cozy-public` namespace. +The resource name is the image name prefixed with `vm-default-images-`. +For example, the resource `vm-default-images-talos` creates an image accessible as `talos`. -You can track the process by running the following commands: +You can track progress with: ```bash kubectl -n cozy-public get dv -kubectl -n cozy-public describe dv vm-image-ubuntu +kubectl -n cozy-public describe dv vm-default-images-talos ``` ## Using Golden Images -### Simple Virtual Machine - -Simple virtual machines (deployed with the `virtual-machine` application in Cozystack) already include a set of predefined named disk images. -By default, users can choose from `ubuntu`, `fedora`, `cirros`, `alpine`, and `talos`. +### Creating a VMDisk from a Golden Image -These images are named but, in the default configuration, they are downloaded each time a VM is created. -Using golden images allows these files to be downloaded once and stored locally, significantly speeding up VM deployment. - -The next step is to create a VMDisk, which we will later attach to our future VM: +To use a golden image as the source for a VM disk, create a VMDisk with `source.image.name` referencing the image name: ```bash kubectl -n tenant-root create -f- <` | DataVolume in `cozy-public` (golden image) | `vm-image-` | +| `` | DataVolume in `cozy-public` (golden image) | `vm-default-images-` | | `` | DataVolume created from VMDisk | `vm-disk-` | | `` | VirtualMachine created from VMInstance | `vm-instance-` | This means if you create a VMInstance named `ubuntu`, the VirtualMachine in Kubernetes will be `vm-instance-ubuntu`. +## Default Image Collection + +Cozystack ships with the **`vm-default-images`** system package that automatically provisions a curated collection of OS images in the `cozy-public` namespace. +No manual setup is required — images become available as soon as the package is installed. + +The default collection includes: + +| Image name | Description | +|---|---| +| `ubuntu-20.04` | Ubuntu 20.04 LTS (Focal Fossa) | +| `ubuntu-22.04` | Ubuntu 22.04 LTS (Jammy Jellyfish) | +| `ubuntu-24.04` | Ubuntu 24.04 LTS (Noble Numbat) | +| `debian-12` | Debian 12 (Bookworm) | +| `debian-13` | Debian 13 (Trixie) | +| `rocky-8` | Rocky Linux 8 | +| `rocky-9` | Rocky Linux 9 | +| `rocky-10` | Rocky Linux 10 | +| `almalinux-8` | AlmaLinux 8 | +| `almalinux-9` | AlmaLinux 9 | +| `almalinux-10` | AlmaLinux 10 | +| `centos-stream-9` | CentOS Stream 9 | +| `centos-stream-10` | CentOS Stream 10 | +| `opensuse-leap-15.6` | openSUSE Leap 15.6 | +| `opensuse-leap-16.0` | openSUSE Leap 16.0 | +| `alpine-3.21` | Alpine Linux 3.21 | + +You can list all available images with: +```bash +kubectl -n cozy-public get dv -l app.kubernetes.io/managed-by=cozystack +``` -## Creating Golden Images +## Adding Custom Golden Images -Creating named VM images (golden images) requires an administrator account in Cozystack. +Creating additional named VM images requires an administrator account in Cozystack. -The simplest way to create named VM images is by using the CLI script. +The simplest way to add a custom image is by using the CLI script. The [`cdi_golden_image_create.sh`](https://github.com/cozystack/cozystack/blob/{{< version-pin "cozystack_tag" >}}/hack/cdi_golden_image_create.sh) script can be downloaded from the Cozystack {{< version-pin "cozystack_tag" >}} release tag: ```bash @@ -44,43 +74,33 @@ chmod +x cdi_golden_image_create.sh This script uses your `kubectl` configuration. Before running it, ensure that your configuration points to the target Cozystack cluster. -To create a named image, or to download one of the default images, run the script with the image name and its URL: +To add a custom image, run the script with the image name and its URL: ```bash cdi_golden_image_create.sh '' 'https://' ``` -For example, all five default images, available with the `virtual-machine` application, can be downloaded for faster use: +For example, to add a Talos image: ```bash -cdi_golden_image_create.sh 'ubuntu' 'https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img' -cdi_golden_image_create.sh 'fedora' 'https://download.fedoraproject.org/pub/fedora/linux/releases/40/Cloud/x86_64/images/Fedora-Cloud-Base-Generic.x86_64-40-1.14.qcow2' -cdi_golden_image_create.sh 'cirros' 'https://download.cirros-cloud.net/0.6.2/cirros-0.6.2-x86_64-disk.img' -cdi_golden_image_create.sh 'alpine' 'https://dl-cdn.alpinelinux.org/alpine/v3.20/releases/cloud/nocloud_alpine-3.20.2-x86_64-bios-tiny-r0.qcow2' cdi_golden_image_create.sh 'talos' 'https://github.com/siderolabs/talos/releases/download/v1.7.6/nocloud-amd64.raw.xz' ``` -Internally, the script creates Kubernetes resources of `kind: DataVolume` in the `cozy-public` namespace. -The resource name is the disk’s name prefixed with `vm-image-`. -For example, the resource `vm-image-ubuntu` creates a saved image named `ubuntu`. +Internally, the script creates a Kubernetes resource of `kind: DataVolume` in the `cozy-public` namespace. +The resource name is the image name prefixed with `vm-default-images-`. +For example, the resource `vm-default-images-talos` creates an image accessible as `talos`. -You can track the process by running the following commands: +You can track progress with: ```bash kubectl -n cozy-public get dv -kubectl -n cozy-public describe dv vm-image-ubuntu +kubectl -n cozy-public describe dv vm-default-images-talos ``` ## Using Golden Images -### Simple Virtual Machine - -Simple virtual machines (deployed with the `virtual-machine` application in Cozystack) already include a set of predefined named disk images. -By default, users can choose from `ubuntu`, `fedora`, `cirros`, `alpine`, and `talos`. +### Creating a VMDisk from a Golden Image -These images are named but, in the default configuration, they are downloaded each time a VM is created. -Using golden images allows these files to be downloaded once and stored locally, significantly speeding up VM deployment. - -The next step is to create a VMDisk, which we will later attach to our future VM: +To use a golden image as the source for a VM disk, create a VMDisk with `source.image.name` referencing the image name: ```bash kubectl -n tenant-root create -f- <