Skip to main content
Version: latest

Install Palette Agent

Agent mode allows you to bring your own host, regardless of its architecture and Operating System (OS), to be managed by Palette and to operate as nodes in your Kubernetes clusters. For example, you can use an AWS EC2 instance, a Raspberry Pi, a VMware vSphere virtual machine, and more, as long as they meet the minimum hardware requirements.

This page guides you through the process of installing the Palette agent on your host. You will learn how to create the user data file to configure your host, install the agent, and verify that your host was successfully registered with Palette. You will then create a cluster profile and use the registered host to deploy a cluster.

tech preview
This is a Tech Preview feature and is subject to change. Do not use this feature in production workloads.

Limitations​

  • Currently, agent mode only supports non-FIPS workflows.

  • The following table presents the verified combinations of host architecture and cluster profile layers.

    Host ArchitectureOSKubernetesContainer Network Interface (CNI)Verified
    AMD64UbuntuPalette eXtended Kubernetes - Edge (PXK-E)Calico✅
    AMD64UbuntuK3sFlannel✅

  • Clusters with Flannel CNI is not verified for airgap deployments.

  • Agent mode is only supported on Linux distributions that have systemd installed and available.

Prerequisites​

  • A physical or virtual host with SSH access, access to the internet, and connection to Palette. For airgap deployments, the host does not need to have a connection to Palette and may have limited access to the internet. This guide uses an Ubuntu 22.04 virtual machine deployed in VMware vSphere as an example.

  • The host must meet the following minimum hardware requirements:

    • 2 CPU
    • 8 GB memory
    • 100 GB storage

  • A Palette tenant registration token. Refer to the Create a Registration Token guide for instructions on how to create a token.

  • One IP address is required for the cluster's Virtual IP (VIP) address.

  • Ensure that the host has Bash configured as the default shell.

  • Ensure the following software is installed and available:

    warning

    Avoid installing Docker on the host where you want to install the agent. Docker is a heavyweight tool that could interfere with the Palette agent.

Install Palette Agent​

  1. In your terminal, use the following command to SSH into the host. Replace </path/to/private/key> with the path to your private SSH key and <host-ip-or-domain> with the host's IP address or hostname.

    ssh -i </path/to/private/key> ubuntu@<host-ip-or-domain>

  2. Export your Palette registration token. Replace <your-palette-registration-token> with your token.

    export TOKEN=<your-palette-registration-token>

  3. (Optional) If you are not installing the agent on a host that accesses the internet via a proxy, skip this step.

    If you are installing the agent on a host that accesses the internet via a network proxy, export the proxy configurations in your current terminal session. We recommend exporting the variables both in uppercase and lowercase to ensure compatibility. Replace <httpProxyAddress> and <httpsProxyAddress> with the address and port to your HTTP and HTTPS proxy servers, respectively.

    export http_proxy=<httpProxyAddress>
    export https_proxy=<httpsProxyAddress>
    export HTTP_PROXY=<httpProxyAddress>
    export HTTPS_PROXY=<httpsProxyAddress>

  4. Issue the command below to create the user-data file and configure your host declaratively.

    info

    If your host needs a proxy to access the internet, you need to provide the proxy configurations in the user data as well. For more information, refer to Site Network Parameters.

    Alternatively, you can install the agent first and configure proxy in Local UI. For more information, refer to Configure HTTP Proxy.

    The following configuration includes the default Palette endpoint, a registration token, and sets up the kairos user. The host will not shut down and will reboot after the agent installation, with kube-vip enabled, as this is required for bare metal and VMware vSphere deployments. If your environment does not require kube-vip, set skipKubeVip: to true. Refer to the Prepare User Data guide to learn more about user data configuration.

    cat << EOF > user-data
    #cloud-config
    install:
      reboot: true
      poweroff: false

    stylus:
      skipKubeVip: false
      site:
        edgeHostToken: $TOKEN
        paletteEndpoint: api.spectrocloud.com
    stages:
      initramfs:
        - users:
            kairos:
              groups:
                - sudo
              passwd: kairos
    EOF

    Confirm that the file was created correctly.

    cat user-data

    The output should contain the value of your Palette registration token assigned to the edgeHostToken parameter, as displayed in the example output below.

    #cloud-config
    install:
      reboot: true
      poweroff: false

    stylus:
      skipKubeVip: false
      site:
        edgeHostToken: ****************
        paletteEndpoint: api.spectrocloud.com
    stages:
      initramfs:
        - users:
            kairos:
              groups:
                - sudo
              passwd: kairos

  5. Export the path to your user data file.

    export USERDATA=./user-data

  6. Download the latest version of the Palette agent installation script.

    curl --location --output ./palette-agent-install.sh https://github.com/spectrocloud/agent-mode/releases/latest/download/palette-agent-install.sh

    If you have a dedicated or on-premises instance of Palette, use the command below to get the Palette's stylus version. Replace <palette-endpoint> with your Palette endpoint and <api-key> with your Palette API key.

    curl --location --request GET 'https://<palette-endpoint>/v1/services/stylus/version' --header 'Content-Type: application/json' --header 'Apikey: <api-key>'  | jq --raw-output '.spec.latestVersion.content | match("version: ([^\n]+)").captures[0].string'
    4.5.0

    Next, download the version of the Palette agent installation script that matches the stylus version. Replace <stylus-version> with your Palette stylus version. For example, if the output of the previous command was 4.5.0, replace <stylus-version> with v4.5.0.

    curl --location --output ./palette-agent-install.sh https://github.com/spectrocloud/agent-mode/releases/download/<stylus-version>/palette-agent-install.sh

  7. Grant execution permissions to the install.sh script.

    chmod +x ./palette-agent-install.sh

  8. Issue the following command to install the agent on your host.

    sudo --preserve-env ./palette-agent-install.sh

    The termination of the SSH connection, as shown in the example below, confirms that the script has completed its tasks.

    Connection to 192.168.1.100 closed by remote host.
    Connection to 192.168.1.100 closed.

  9. Upon agent installation, the host will reboot to the registration screen and use the provided EdgeHostToken for automatic registration with Palette. The host will be registered in the same project where the registration token was created.

  10. Log in to Palette and select Clusters from the left Main Menu.

  11. Select the Edge Hosts tab and verify your host is displayed and marked as Healthy in the Edge hosts list.

  12. Once the host has been registered with Palette, proceed with the cluster profile creation. Select Profiles from the left Main Menu.

  13. Click on Add Cluster Profile.

  14. In the Basic Information section, assign the a profile name, a description, and tags. Select the type as Full and click Next.

  15. Select Edge Native as the Cloud Type and click Next.

  16. The Profile Layers section specifies the packs that compose the profile. Add the BYOS Edge OS pack version 2.0.0 to the OS layer.

  17. Click Values under Pack Details, then click on Presets on the right-hand side. Select Agent Mode.

    View of the cluster profile creation page with the BYOS pack.

  18. Click Next Layer to continue.

  19. Complete the cluster profile creation process by filling out the remaining layers.

  20. Follow the steps in the Create Cluster Definition guide to deploy a cluster using your registered host as a cluster node.

Validate​

  1. Log in to Palette.

  2. Select Clusters from the left Main Menu.

  3. Select the host cluster you created to view its details page.

  4. Verify that the cluster is listed as Healthy and has a Running status.