Skip to main content

VMware vSphere Airgap Instructions

Overview diagram of the pre-install steps eager-load

This guide provides instructions to prepare your airgap environment for a Palette installation by completing the required preparatory steps 1 and 2 shown in the diagram. The respective installation guides for each platform cover the remaining installation process.

Prepare Airgap Installation​

Use the following steps to prepare your airgap environment for a Palette installation.

tip

Carefully review the prerequisites section before proceeding. This will save you time and frustration. Each prerequisite listed is required for a successful installation.

Prerequisites​

  • An x86 Linux jumpbox or bastion host with connectivity to the target platform where you are installing Palette.

  • 30 GB of disk space available for the airgap setup binary and temporary files. The uncompressed airgap content is approximately 20 GB.

  • An OCI registry such as Harbor or AWS ECR to store Palette images and packages. The OCI registry must be accessible from the VMware vSphere environment. We have verified the installation against Harbor and AWS ECR. Other OCI registries may work but have not been tested.

    caution

    Ensure the OCI registries are set up with HTTPS. AWS ECR is enabled with HTTPS by default. Harbor requires you to enable HTTPS. If you are using Harbor, you must enable HTTPS to authenticate with the registry. Refer to the Harbor documentation for guidance.

  • An HTTP file server to host the Palette manifest. The file server must be accessible from the target environment where Palette will be installed. Below is a list of common HTTP file servers:


    caution

    Take the necessary steps to secure your file server and ensure it can automatically recover from a failure. The file server is a critical component of the airgap installation and must be available post-install for Palette to function properly.

  • jq - Command-line JSON processor installed and available. Refer to the jq download page for guidance.

  • To interact with the OCI registry, you must have the following tools installed and available.

    • AWS CLI v2 - Required for AWS ECR.

    • Oras CLI v1.0.0 - This version is explicitly required for the setup script.

    • zip - required for the setup script.

    • unzip - or equivalent for extracting the manifest content from the airgap setup binary.

  • Palette CLI installed and available. Refer to the Palette CLI Install page for guidance.
  • Review the required vSphere permissions. Ensure you have created the proper custom roles and zone tags. Zone tagging is required for dynamic storage allocation across fault domains when provisioning workloads that require persistent storage. Refer to Zone Tagging for information.

info

Self-hosted Palette installations provide a system Private Cloud Gateway (PCG) out-of-the-box and typically do not require a separate, user-installed PCG. However, you can create additional PCGs as needed to support provisioning into remote data centers that do not have a direct incoming connection to Palette. To learn how to install a PCG on VMware, check out the VMware guide.


Instructions​

Complete the following steps before deploying the airgap Palette installation.

  1. Log in to your vCenter environment.
  1. Create a vSphere VM and Template folder with the name spectro-templates. Ensure this folder is accessible by the user account you will use to deploy the airgap Palette installation.

  1. Use the URL below to import the Operating System and Kubernetes distribution OVA required for the install. Place the OVA in the spectro-templates folder. Refer to the Import Items to a Content Library guide for information about importing an OVA in vCenter.

    https://vmwaregoldenimage-console.s3.us-east-2.amazonaws.com/u-2204-0-k-12510-0.ova

  2. Append an r_ prefix to the OVA name after the import. For example, r_u-2204-0-k-12510-0.ova. This prefix is required for the install process to identify the OVA.

  1. In your OCI registry, create a repository with the name spectro-packs and ensure the repository is private. This repository will host the Palette Packs.

    • Refer to the Create Projects guide for information about creating a repository in Harbor.
    • Refer to the Create a repository guide for information about creating a repository in AWS ECR.

  2. In your OCI registry, create another repository with the name spectro-images and ensure the repository is public. The repositry will host Palette images.

  1. Log in to the Linux environment where you will download the airgap binaries and complete the remaining steps, including the Palette installation.

  1. Authenticate with your OCI registry and acquire credentials to both repositories you created earlier. You will need these credentials when deploying the airgap Palette installation.

    Use oras to log in to your OCI registry. Replace the values below with your environment configuration values. Check out the oras login documentation for information about additional CLI flags and examples.

    oras login X.X.X.X --user 'yourUserNameHere' --password 'yourPasswordHere'

    If you are using a Harbor registry with a self-signed certificate, you will need to add the --insecure flag to the oras command. 

    oras login X.X.X.X --insecure --user 'yourUserNameHere' --password 'yourPasswordHere'
    tip

    Be aware of the timeout period for the authentication token. The process of uploading images and packages to the OCI registry can take a approximately an hour. If the authentication token expires, you will need to re-authenticate to the OCI registry and restart the upload process.

  1. The airgap setup binary requires a set of environment variables to be available and populated. Depending on what OCI registry you are using, the environment variables will be different. Select the OCI registry you are using and populate the environment variables accordingly.


    • OCI_IMAGE_REGISTRY: The IP address or domain name of the OCI registry.

    • OCI_PACK_BASE: The namespace or repository name that hosts the Palette Packs.

    • OCI_PACK_REGISTRY: The IP address or domain name of the OCI registry.

    • OCI_IMAGE_BASE: The namespace or repository name that hosts the Palette images.

      export OCI_IMAGE_REGISTRY=<harbor-endpoint> 
      export OCI_PACK_BASE=spectro-packs  
      export OCI_PACK_REGISTRY=<harbor-endpoint>
      export OCI_IMAGE_BASE=spectro-images

      Example

      export OCI_IMAGE_REGISTRY=example.internal.com
      export OCI_PACK_BASE=spectro-packs
      export OCI_PACK_REGISTRY=10.10.100.48
      export OCI_IMAGE_BASE=spectro-images

  1. Download the airgap setup binary. Our support team will provide you with the proper version and the necessary credentials. Replace the placeholder values in the commands below with the recommended version and credentials that our support team provides.

    VERSION=4.1.6
    curl --user XXXXX:YYYYYYY https://software-private.spectrocloud.com/airgap/$VERSION/airgap-v$VERSION.bin  \
    --output airgap-v$VERSION.bin

  2. Update the airgap setup binary permissions to allow execution. Replace the file name below with the name of the airgap setup binary you downloaded.

    chmod +x airgap-v$VERSION.bin

  3. Start the airgap setup binary. Replace the file name below with the name of the airgap setup binary you downloaded.

    ./airgap-v$VERSION.bin

    Upon completion, a success message will be displayed. The output in the example is condensed for brevity.

    Verifying archive integrity...  100%   MD5 checksums are OK. All good.
    Uncompressing Airgap Setup - Version 4.0.17  100%
    Setting up Packs
    - Pushing Pack cni-calico:3.25.1
    ...
    Setting up Images
    - Pushing image docker.io/kindest/kindnetd:v20230227-15197099
    - Pushing image gcr.io/cloud-provider-vsphere/cpi/release/manager:v1.22.8
    .....
    Preparing Manifests Archive
    Manifests are available in /tmp/spectro-manifests-1696971110.zip. Extract the archive to a file server to serve as a Spectro Cloud Repository
    Setup Completed
    info

    If you encounter an error during the airgap setup process, verify the required environment variables are set and populated correctly. If you are still having issues, reach out to our support team for assistance.

  1. Move the manifest file located in your temporary directory to the location of your file server. Unzip the manifest file to a folder accessible by the file server. Replace the file name below with the name of the manifest file provided to you by the airgap setup.

    unzip spectro-manifests-XXXXXXXXXXXX.zip -d /target/folder
    tip

    If you want to get started quickly with a file server, install Caddy or use Python3's http sever and issue one of the following commands in the folder where you unzipped the manifest content. Each command will start a file server on port 2015.

    caddy file-server --listen :2015 --browse
    python3 -m http.server 2015

    We do not recommend serving the manifest content over HTTP, but it is an option if you want to get started quickly. For production workloads, enable HTTPS on your file server.

  1. Review the additional packs available for download. The supplemental packs are optional and not required for a successful installation. However, to create to cluster profiles you may require several of the packs available for download. Refer to the Additional Packs resource for a list of available packs.

  1. Once you select the packs you want to install, download the pack binaries and start the binary to initiate the upload process.

    In the example below, the airgap-pack-aws-alb-2.5.1.bin binary is downloaded and started.

    chmod +x airgap-pack-aws-alb-2.5.1.bin && \
    ./airgap-pack-aws-alb-2.5.1.bin
      Verifying archive integrity...  100%   MD5 checksums are OK. All good.
      Uncompressing Airgap Pack - aws-alb Version 4.0.17  100%
      Setting up Packs
      - Pushing Pack aws-alb:2.5.1
      Setting up Images
      Setup Completed

  2. Repeat step 14 for each pack you want to install.

You now have completed the preparation steps for an airgap installation. Check out the Validate section to ensure the airgap setup process completed successfully.

Validate​

Use the following steps to validate the airgap setup process completed successfully.

  1. Log in to your OCI registry and verify the Palette images and packs are available.

  1. Verify the manifest file is accessible from the file server. The manifest file is required for the Palette installation process. The screenshot below is an example of a file server hosting the unzipped manifest content. The example uses Caddy as the file server.

    Example of a file server hosting the unzipped manifest content

  1. Ensure your file server is accessible from the environment you are installing Palette. Use the following command to verify the manifest content is accessible from the file server. Replace the hostname or IP address below with your file server hostname or IP address.

    curl http://<hostname>:<port>/roar/nickfury/versions.yaml
      versions:
      - version: "3.3"
        filepath: "/roar/nickfury/3.3/version.yaml"
        patchVersionsFilepath: "/roar/nickfury/3.3/versions.yaml"
      - version: "3.4"
        filepath: "/roar/nickfury/3.4/version.yaml"
        patchVersionsFilepath: "/roar/nickfury/3.4/versions.yaml"
      - version: "4.0"
        filepath: "/roar/nickfury/4.0/version.yaml"
        patchVersionsFilepath: "/roar/nickfury/4.0/versions.yaml"

Next Steps​

You are now ready to deploy the airgap Palette installation. You will specify your OCI registry and file server during the installation process. Refer to the VMware Install Instructions guide for detailed guidance on installing Palette.