Skip to main content
Version: latest

Environment Setup with an Existing RHEL VM

This guide helps you prepare your VMware vSphere airgap environment for VerteX installation using an existing Red Hat Enterprise Linux (RHEL) VM.

You will learn how to execute an appliance binary in your VM that installs the necessary tools to deploy an OCI registry for hosting VerteX images and assists in starting the VerteX installation.

info

This guide is for preparing your airgap environment only. For instructions on installing VerteX on VMware, refer to the Install VerteX guide.

Limitations​

  • Currently, 9.4 is the only supported RHEL version.

Prerequisites​

  • An RHEL airgap VM deployed in your VMware vSphere. The VM must be registered with Red Hat and have ports 80 and 443 available. This guide uses RHEL version 9.4 as an example.

  • The RHEL VM must have a Fully Qualified Domain Name (FQDN) that is DNS resolvable and must be accessible via SSH.

  • The RHEL VM must have Podman installed.

  • An HTTP file server installed within the RHEL VM to host the VerteX files. The file server must serve files from the /var/www/html directory and have SSL support enabled. Below is a list of common file servers. This guide uses Apache as an example.

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

  • Review the required vSphere permissions and ensure you have created the proper custom roles and zone tags. Zone tagging enables dynamic storage allocation across fault domains when provisioning workloads that require persistent storage. Refer to Zone Tagging for information.

  • The following artifacts must be available in the root home directory of the RHEL airgap VM. You can download the files in a system with internet access and then transfer them to your airgap environment. Contact your VerteX support representative to obtain the latest version of each artifact.

    • RHEL airgap appliance binary.
    • VerteX airgap installation binary.

Prepare for Airgap Installation​

  1. Log in to your vCenter environment.

  2. Create a vSphere template folder named spectro-templates. Ensure you can access this folder with the user account you plan to use when deploying the VerteX installation.

  3. Right-click on your cluster or resource group and select Deploy OVF Template.

  4. In the Deploy OVF Template wizard, enter the following URL to import the Operating System (OS) and Kubernetes distribution OVA required for the VerteX nodes creation. Contact your VerteX support representative to learn if the version of VerteX you are using requires a new OS and Kubernetes OVA.

    https://vmwaregoldenimage-console.s3.amazonaws.com/u-2204-0-k-1294-0.ova

    Place the OVA in the spectro-templates folder. Append the r_ prefix, and remove the .ova suffix when assigning its name and target location. For example, the final output should look like r_u-2204-0-k-1294-0. This naming convention is required for the installation process to identify the OVA. Refer to the Additional Packs page for a list of additional OS and Kubernetes OVAs.

    You can terminate the deployment after the OVA is available in the spectro-templates folder. Refer to the Deploy an OVF or OVA Template guide for more information about deploying an OVA in vCenter.

    warning

    If you encounter an error message during the OVA deployment stating that vCenter is unable to retrieve a manifest or certificate, refer to this known issue from VMware's knowledge base for guidance on how to resolve the issue.

  5. Open a terminal window and SSH into the RHEL airgap VM as a root user with the command below. Replace /path/to/private_key with the path to your private SSH key, docs with the username, and palette.example.com with the FQDN of the RHEL airgap VM.

    ssh -i /path/to/private_key docs@palette.example.com

  6. Switch to the root user account to complete the remaining steps.

    sudo --login

  7. Set the VM timezone to Coordinated Universal Time (UTC).

    timedatectl set-timezone UTC

  8. Ensure that ports 80 and 443 are not in use by your file server, as these ports will be used by the Harbor registry that will be installed later.

    Open the /etc/httpd/conf.d/ssl.conf file and make the following changes:

    • Replace the line Listen 443 https with Listen 8443 https.
    • Replace the line <VirtualHost _default_:443> with <VirtualHost _default_:8443>.

    Save and exit the file.

  9. Next, open the /etc/httpd/conf/httpd.conf file and replace the line Listen 80 with Listen 8080. Save and exit the file.

  10. Restart the Apache HTTP server to apply the configuration changes.

    systemctl restart httpd.service

  11. Allow TCP traffic on ports 80, 8080, 443, and 8443, then reload the firewall.

    firewall-cmd --permanent --add-port=80/tcp
    firewall-cmd --permanent --add-port=8080/tcp
    firewall-cmd --permanent --add-port=443/tcp
    firewall-cmd --permanent --add-port=8443/tcp
    firewall-cmd --reload

    The output displays a success message.

    success

  12. Set the AIRGAP_BUILD variable as true. This is required for the RHEL airgap appliance binary.

    export AIRGAP_BUILD=true

  13. Start the RHEL airgap appliance binary, which installs the tools and configures the manifests that are required to set up the Harbor registry and push images. Replace <version> with the version of the binary received from the support team.

    chmod +x ./airgap-appliance-<version>-rhel-podman.bin && ./airgap-appliance-<version>-rhel-podman.bin

    Consider the following example for reference.

    chmod +x ./airgap-appliance-v4.4.2-rhel-podman.bin && ./airgap-appliance-v4.4.2-rhel-podman.bin
    Verifying archive integrity...  100%   MD5 checksums are OK. All good.
    Uncompressing Airgap Appliance Setup - 4.4.2  100%
    Setting up  directories and certs
    warning: /opt/spectro/pwgen-2.08-3.el8.x86_64.rpm: Header V3 RSA/SHA256 Signature, key ID 2f86d6a1: NOKEY
    Verifying...                          ################################# [100%]
    Preparing...                          ################################# [100%]
    Updating / installing...
    1:pwgen-2.08-3.el8                 ################################# [100%]
    Skipping setting up Nginx and Podman for airgap
    Installing Podman
    Setting up Harbor
    Setting up oras and jq
    Setting up Manifests
    Cleaning up setup files
    Reboot the system for selinux changes to take effect

  14. Reboot your RHEL VM to apply the changes.

    reboot

    Your SSH connection will be terminated.

  15. Start a new SSH session and switch to sudo mode before proceeding.

    sudo --login

  16. Issue the following command to configure the Harbor registry. Replace palette.example.com with the FQDN of the RHEL airgap VM. The script will generate a self-signed certificate for the value you provide.

    /bin/airgap-setup.sh palette.example.com

    The script output should look similar to the example below. It contains the credentials and values you will need when completing the installation with the Palette CLI. If you need to review this information in the future, invoke the script again.

    Setting up SSL Certs
    /opt/spectro/functions.sh: line 118: /etc/nginx/.htpasswd: No such file or directory
    chmod: cannot access '/etc/nginx/.htpasswd': No such file or directory
    mkdir: cannot create directory ‘/etc/nginx/ssl’: No such file or directory
    cp: target '/etc/nginx/ssl' is not a directory
    Setting up Harbor
    setenforce is /usr/sbin/setenforce
    Setup Completed

    Details:
    -------
    Spectro Cloud Repository
    Location: https://palette.example.com:8443
    UserName: spectro
    Password: **************
    CA certificate filepath: /opt/spectro/ssl/server.crt

    Pack OCI Registry
    Endpoint: https://palette.example.com
    Base Content Path: spectro-packs
    CA certificate Filepath: /opt/spectro/ssl/server.crt
    Username: admin
    Password: **************

    Image OCI Registry
    Endpoint: https://palette.example.comv
    Base Content Path: spectro-images
    CA certificate Filepath: /opt/spectro/ssl/server.crt
    Username: admin
    Password: **************

  17. Update the SSL certificate file and key in the httpd service.

    warning

    You can skip this step if you do not plan to use the local Spectro Cloud Artifact Repository (SCAR) during the VerteX installation process.

    Open the /etc/httpd/conf.d/ssl.conf file and add the path to the certificate and key generated in step 15 of this guide:

    • Replace the line SSLCertificateFile /etc/pki/tls/certs/localhost.crt with SSLCertificateFile /opt/spectro/ssl/server.crt.
    • Replace the line SSLCertificateKeyFile /etc/pki/tls/private/localhost.key with SSLCertificateKeyFile /opt/spectro/ssl/server.key.

    Save and exit the file. Next, restart the HTTP server to apply the changes.

    systemctl restart httpd.service

  18. Start the VerteX installation binary, which uploads release-specific VerteX images and packs to the Harbor registry. Replace <version> with the version of the binary received from the support team.

    chmod +x airgap-<version>.bin && ./airgap-<version>.bin

    Consider the following example for reference.

    chmod +x airgap-4-4-14.bin && ./airgap-4-4-14.bin

    This step may take some time to complete. A Setup Completed message confirms it is finished.

    Verifying archive integrity...  100%   MD5 checksums are OK. All good.
    Uncompressing Airgap Setup - Version 4.4.14  100%
    Setting up CLI
    Setting up Manifests
    Setting up Packs
    ...

    Setup Completed

  19. Grant the Apache user and group the necessary permissions to serve the files in the /var/www/html directory.

    chown -R apache.apache /var/www/html

    Restart the HTTP server to apply the changes.

    systemctl restart httpd.service

  20. Review the Additional Packs page and identify any additional packs you want to add to your registry. You can also add additional packs after the installation is complete.

You have now completed the preparation steps for an airgap installation. Check out the Validate section to ensure the airgap setup process is completed successfully. After you validate the airgap setup process, review the Next Steps.

warning

Do not power off the RHEL VM. The RHEL VM is required for VerteX to function properly and must remain available at all times. If for some reason the VM is powered off, power the VM back on and restart the required services.

Switch to sudo mode and restart the file server.

sudo --login
systemctl restart httpd

Next, navigate to the /opt/spectro/harbor directory and issue the following command to restart the registry.

docker compose up --detach

Validate​

  1. SSH into the RHEL airgap VM as a root user with the command below. Replace /path/to/private_key with the path to the private SSH key, docs with the username, and palette.example.com with the FQDN of the RHEL airgap VM.

    ssh -i /path/to/private_key docs@palette.example.com

  2. Switch to the root user account.

    sudo --login

  3. Issue the following command to validate that you have successfully completed the airgap setup process. Replace palette.example.com with the FQDN of the RHEL airgap VM.

    bin/airgap-setup.sh palette.example.com

    The output must include the registry location and credentials, which must be accessible from within your environment.

    Setting up SSL Certs
    /opt/spectro/functions.sh: line 118: /etc/nginx/.htpasswd: No such file or directory
    chmod: cannot access '/etc/nginx/.htpasswd': No such file or directory
    mkdir: cannot create directory ‘/etc/nginx/ssl’: No such file or directory
    cp: target '/etc/nginx/ssl' is not a directory
    Setting up Harbor
    setenforce is /usr/sbin/setenforce
    Setup Completed

    Details:
    -------
    Spectro Cloud Repository
    Location: https://palette.example.com:8443
    UserName: spectro
    Password: **************
    CA certificate filepath: /opt/spectro/ssl/server.crt

    Pack OCI Registry
    Endpoint: https://palette.example.com
    Base Content Path: spectro-packs
    CA certificate Filepath: /opt/spectro/ssl/server.crt
    Username: admin
    Password: **************

    Image OCI Registry
    Endpoint: https://palette.example.comv
    Base Content Path: spectro-images
    CA certificate Filepath: /opt/spectro/ssl/server.crt
    Username: admin
    Password: **************

Next Steps​

You are now ready to deploy VerteX in an airgapped environment with the Palette CLI. As a root user, issue the Palette CLI command below to start the installation.

palette ec install

Complete all the Palette CLI steps outlined in the Install guide from the RHEL VM.

info

The following table maps the airgap script output values to their respective Palette CLI prompts and example values. The example values are for reference only.

Output ValuePalette CLI PromptExample Value
Spectro Cloud Repository LocationSCAR Locationhttps://palette.example.com:8443
CA certificate filepathSCAR CA certificate filepath/opt/spectro/ssl/server.crt
OCI RegistryRegistry TypeOCI
Pack OCI RegistryRegistry Endpointhttps://palette.example.com
CA certificate FilepathRegistry CA certificate filepath/opt/spectro/ssl/server.crt
Image OCI RegistryRegistry Endpointhttps://palette.example.com
CA certificate FilepathRegistry CA certificate filepath/opt/spectro/ssl/server.crt

When prompted for Allow Insecure Connection (Bypass x509 Verification)?, enter n to continue and specify the server certificate file path from the script output.