Skip to main content
Version: latest

Environment Setup

Overview diagram of the pre-install steps eager-load

This guide provides instructions to prepare your airgap environment for a Palette VerteX installation by completing the required preparatory steps one through four 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 VerteX installation.

tip

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

Prerequisites​

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

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

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

    warning

    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 VerteX manifest. The file server must be accessible from the target environment where VerteX will be installed. Below is a list of common file servers:

    warning

    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 VerteX to function properly.

  • 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.
    • jq - Command-line JSON processor installed and available.
    • Docker - The airgap setup binary requires Docker to be installed and available.

Instructions​

Complete the following steps before deploying the airgap VerteX installation.

  1. Log in to the OCI registry where you will host the VerteX images and packages.

  2. Create a private repository named spectro-packs. This repository will host the VerteX 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.

  3. In your OCI registry, create a public repository named spectro-images. The public repositry will host the images required by VerteX.

  4. Download the Certificate Authority (CA) for your OCI registry and make it available in the local file system. You will need to provide the CA to the Palette CLI installation wizard later in the installation process. If you don't give the Palette CLI the file path to the CA when prompted, you may encounter errors when authenticating with the OCI registry, which could result in an incomplete installation. Skip this step if you are using AWS ECR.

  5. Log in to the Linux environment where you will download the airgap binaries. This steps requires internet access to download the airgap setup binary.

  6. Download the airgap setup binary. Our support team will provide you with the proper version and credentials. Replace the values in the commands below with our support team's recommended version and credentials.

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

  7. 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-fips-v$VERSION.bin

  8. Copy or move the airgap binary to another Linux environment inside your airgap environment. Use any approved method to transfer the binary to the airgap environment.

  9. Log in to the Linux environment inside your airgap environment where you copied the airgap setup binary.

  10. Authenticate with your OCI registry and acquire credentials to both repositories you created earlier. You will need these credentials when deploying the airgap VerteX 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.

  11. The airgap setup binary requires a set of environment variables to be available and populated. The environment variables will be different depending on the OCI registry you are using. Select the OCI registry 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 VerteX 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 VerteX 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

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

    ./airgap-fips-v$VERSION.bin

    Upon completion, a success message will be displayed. The output 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.

  13. 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.

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

  15. Once you select the packs you want to install, download the pack binaries and start the binary to initiate the upload process. This step requires internet access, so you may have to download the binaries on a separate machine outside the airgap environment and transfer them to the airgap environment using an approved method.

    In the example below, the airgap-fips-pack-amazon-linux-eks-1.0.0.bin binary permissions are updated to allow execution and the binary is started.

    chmod +x airgap-fips-pack-amazon-linux-eks-1.0.0.bin && \
    ./airgap-fips-pack-amazon-linux-eks-1.0.0.bin
      Verifying archive integrity...  100%   MD5 checksums are OK. All good.
      Uncompressing Airgap Pack - amazon-linux-eks Version 4.0.17  100%
      Setting up Packs
      - Pushing Pack amazon-linux-eks:1.0.0
      Setup Completed

  16. Repeat step 13 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 VerteX images and packs are available.

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

    Example of a file server hosting the unzipped manifest content

  3. Ensure your file server is accessible from the environment you are installing VerteX. 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 VerteX installation. The important difference is that you will specify your OCI registry and file server during the installation process. Refer to the VerteX Install guide for detailed guidance on installing VerteX.