Skip to main content
Version: latest

Environment Setup

Overview diagram of the pre-install steps eager-load

This guide provides instructions on how to prepare your airgap environment before installing self-hosted Palette by completing the required preparatory steps one through four, as shown in the diagram.

Prepare for Airgap Installation​

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

tip

Carefully review the prerequisites section before proceeding with the environment setup. 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 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 Palette manifest. The file server must be accessible from the target environment where Palette 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 failure. The file server is a critical component of the airgap installation and must be available post-install for Palette 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 Palette installation.

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

  2. Create a private repository named spectro-packs. 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.

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

  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 step requires internet access.

  6. Download the airgap setup binary. Our support team will provide you with the proper version and the necessary credentials. Replace the commands below with the recommended version and credentials provided by our support team.

    VERSION=X.X.X
    curl --user XXXXX:YYYYYYY https://software-private.spectrocloud.com/airgap/$VERSION/airgap-v$VERSION.bin  \
    --output airgap-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-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 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.

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

      Consider the following 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-v$VERSION.bin

    Upon completion, a success message will be displayed. The output in the example below 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-pack-aws-alb-2.5.1.bin binary permissions are updated to allow execution and the binary is 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

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

You have now 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.

  2. 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 shows 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 in which you are installing Palette. Use the following command to verify the file server can access the manifest content. 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 install the airgap self-hosted Palette. You will specify your OCI registry and file server during the installation process. Refer to the Install Palette guide for detailed guidance on installing Palette.