Add a rootfs EVE-OS image to your ZEDEDA Cloud enterprise

This guide describes how to get a new EVE-OS rootfs image and how to add it to your ZEDEDA Cloud enterprise.

Before you read ahead, please familiarize yourself with our EVE-OS images overview.

After you obtain your EVE-OS rootfs image, you’ll find instructions for the two ways that you can add it to your enterprise: 

• Uploading refers to copying an EVE-OS rootfs image from your local machine to one of your datastores. In other words, placing the physical image file into your datastore.
• Uplinking refers to associating an EVE-OS image entry in an enterprise with an EVE-OS rootfs image that is already stored in a datastore. (You're basically registering the metadata for the image, such as its name, version, architecture, location, and SHA256 checksum with the ZEDEDA Cloud, so it knows where to find the image.)

No matter which procedure you follow, you’ll end up with a new EVE-OS rootfs image available to you in your enterprise.

Prerequisites

• ZCLI is running. 
• You must have Docker running.
• You have already created a data store or you have a ZEDEDA-managed datastore. 

Considerations

Available approaches

Note: At this time, uploading of EVE-OS images must be performed using the ZEDEDA Command Line Interface (ZCLI), as this functionality is not currently available through the ZEDEDA GUI.

Limitations of uploading

For security and reliability purposes, uploading is supported only for ZEDEDA-managed datastores. This support is provided as a convenience to ease onboarding.

If you try to upload an image to a non-ZEDEDA-managed datastore, you’ll see an error similar to the following:

Image upload to datastore of type DATASTORE_TYPE_SOMEVENDOR not supported.

Warning: Do not use ZEDEDA-managed datastores in production environments. ZEDEDA can’t guarantee the availability of your artifacts if you do so.

Get a new rootfs EVE-OS images

Follow the procedure below to complete the uploading and uplinking process. When you upload or uplink an EVE-OS image, you must use a rootfs image, and cannot use an installer image, (such as what you would use during a standard EVE-OS install procedure). Both templated and specific example commands are given in the procedure below. 

To get a rootfs version of EVE-OS, follow the steps below:

1. Choose the version that you want to add to your enterprise. For a list of current LTS versions of EVE-OS, check our guide on EVE-OS LTS releases.
2. Open your terminal and navigate to your preferred working directory. This directory will contain your EVE-OS rootfs image when you’re done.
3. Get the full version name. This is the version name that you need to match.
   

   docker run lfedge/eve:EVE_VERSION version

   e.g.: docker run lfedge/eve:14.5-stable-amd64 version

   Output displays as follows:

   0.0.0-14.5-stable-29901325-kvm-amd64

4. Use the output in the commands that follow.  
5. Pull and generate a new EVE-OS rootfs image. The following example uses 11.0.5-lts-kvm-amd64. 

   docker run --rm lfedge/eve:EVE_VERSION rootfs > IMAGE_FILE_NAME.img

   e.g.: docker run --rm lfedge/eve:11.0.5-lts-kvm-amd64 rootfs > 11.0.5-lts-kvm-amd64-rootfs.img

Upload a rootfs EVE-OS image

Upload a rootfs image from your local machine to your ZEDEDA-managed datastore. To upload an EVE-OS rootfs image, follow these steps. ZCLI example commands are provided below, and uploading via the GUI is not currently supported.

1. Log in to ZCLI.
2. Create an EVE-OS image entry in your enterprise. Warning: The IMAGE_NAME value must match the version that you specified when you downloaded the image in the previous procedure. In this case, for example, 11.0.5-lts-kvm-amd64. Additionally, the image format for rootfs images should always be RAW.

   zcli image create IMAGE_NAME --arch=AMD64_OR_ARM64 --datastore-name=DATASTORE_NAME --type=Eve --image-format=RAW --title=IMAGE_NAME

   e.g.: zcli image create 11.0.5-lts-kvm-amd64 --arch=AMD64 --datastore-name=Zededa-AWS-Image --type=Eve --image-format=RAW --title=11.0.5-lts-kvm-amd64

3. Upload your EVE-OS rootfs image.

   zcli image upload IMAGE_NAME --chunked --path=PATH/TO/IMAGE_NAME

   e.g.: zcli image upload 11.0.5-lts-kvm-amd64 --chunked --path=./11.0.5-lts-kvm-amd64-rootfs.img

4. Verify that you can see your new image entry in your enterprise. Look for “Status: Ready” in the output.

   zcli image show IMAGE_NAME

   e.g.: zcli image show 11.0.5-lts-kvm-amd64

Uplink a rootfs EVE-OS image

Uplink to associate an EVE-OS image entry with an EVE-OS rootfs image that is in your datastore. To uplink an EVE-OS rootfs image, follow these steps. ZCLI example commands are provided below, and uploading via the GUI is not currently supported.

1. Log in to ZCLI.
2. Create an EVE-OS image entry in your enterprise.  Note that the image format for rootfs images should always be RAW.

   zcli image create IMAGE_NAME --arch=AMD64_OR_ARM64 --datastore-name=DATASTORE_NAME --type=Eve --image-format=RAW --title=IMAGE_NAME

   e.g.: zcli image create 11.0.5-lts-kvm-amd64 --arch=AMD64 --datastore-name=Zededa-AWS-Image --type=Eve --image-format=RAW --title=11.0.5-lts-kvm-amd64

3. Uplink your rootfs image. To get the values for sha and size, you'll use commands similar to the following (based on your OS) within the directory where you stored your image: shasum -a 256 11.0.5-lts-kvm-amd64.img and stat -f %z 11.0.5-lts-kvm-amd64.img

   zcli image uplink IMAGE_NAME --datastore-name=DATASTORE_NAME --image-sha=SHA_256_VALUE --image-size=IMAGE_SIZE_IN_BYTES

   e.g.: zcli image uplink 11.0.5-lts-kvm-amd64 --datastore-name=Zededa-AWS-Image --image-sha=629595dda5afec054c5d5fad485da3e6068994a7001534a4eaee5170696aa8f4 --image-size=232476160

4. Verify that you can see your new image entry in your enterprise. Look for “Status: Ready” in the output.

   zcli image show IMAGE_NAME

   e.g.: zcli image show 11.0.5-lts-kvm-amd64

Next steps

To update your edge nodes with your new rootfs EVE-OS image, first check out marking an EVE-OS rootfs image as default. Then, move on to updating edge nodes with a latest image.