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​

  • 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✅
    AMD64Rocky Linux 8.10 (Green Obsidian)Palette eXtended Kubernetes - Edge (PXK-E)Cilium✅

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

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

  • The FIPS-compliant version of Agent Mode is only available for Red Hat Enterprise Linux (RHEL) and Rocky Linux 8 systems.

  • ARM64 support for airgap clusters is not available. This is because Harbor, which is required for airgap clusters, does not have an ARM64 image.

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:

    • bash
    • jq
    • Zstandard
    • rsync
    • systemd
    • systemd-timesyncd. This is required if you want Palette to manage Network Time Protocol (NTP). If you don't want Palette to manage NTP, you can skip this requirement.
    • systemd-resolved. This is required if you want Palette to manage Domain Name System (DNS). If you don't want Palette to manage DNS, you can skip this requirement
    • systemd-networkd. This requirement is specific for clusters that use static IP addresses. You also need this if you want Palette to manage the Edge host network
    • conntrack. This requirement is specific for clusters that use PXKE as the Kubernetes layer
    • iptables
    • rsyslog. This is required for audit logs.
    • (Airgap only) Palette Edge CLI
    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.

    • If installing the FIPS version of Agent Mode on a Rocky Linux edge host, you must configure your SELinux policies to grant rsync the required host permissions and ensure you enable cgroup V2.

      If you are using Cilium and have firewalld enabled, you must also configure the appropriate firewalld rules. Follow the process below to apply the necessary configurations before installing Agent Mode.

      Rocky Linux 8 Configurations

      Configure rsync​

      1. Enable SELinux to allow full rsync access.
      setsebool -P rsync_full_access 1
      1. Install the necessary tools to create and apply SELinux policy modules.
      dnf install selinux-policy-devel audit
      1. Create a file named rsync_dac_override.te.
      nano rsync_dac_override.te
      1. Add the following content to the rsync_dac_override.te file.
      module rsync_dac_override 1.0;

      require {
        type rsync_t;
        type default_t;
        class dir read;
        class capability dac_override;
      }

      # Allow rsync_t to read directories labeled default_t
      allow rsync_t default_t:dir read;

      # Allow rsync_t to override discretionary access control (DAC)
      allow rsync_t self:capability dac_override;
      1. Compile and package the SELinux policy module.
      checkmodule -M -m --output rsync_dac_override.mod rsync_dac_override.te
      semodule_package --outfile rsync_dac_override.pp -m rsync_dac_override.mod
      1. Install the compiled policy module.
      semodule --install rsync_dac_override.pp

      Enable cgroup V2​

      1. Issue the following command to check if your kernel supports cgroup v2.

        grep cgroup2 /proc/filesystems

        If the response is nodev cgroup2, your kernel supports cgroup v2 and you may proceed to the next step. If the response does not match nodev cgroup2, then your kernel does not support cgroup v2. You need to upgrade to a kernel that supports cgroup v2 to proceed.

      2. Issue the following command to check if cgroup v2 is already enabled.

        stat -fc %T /sys/fs/cgroup

        If the output is tmpfs then cgroup v2 is not enabled. When cgroup v2 is enabled, the output is cgroup2fs. If cgroup v2 is enabled, skip to step 12.

      3. Issue the following command to edit the GRUB file to enable cgroup v2.

        sudo vi /etc/default/grub

        Find the line starting with GRUB_CMDLINE_LINUX and add the systemd.unified_cgroup_hierarchy=1 parameter.

        GRUB_TIMEOUT=5
        GRUB_DISTRIBUTOR="$(sed 's, release *$,,g' / etc/system-release)"
        GRUB_DEFAULT=saved
        GRUB_DISABLE_SUBMENU=true
        GRUB_TERMINAL_OUTPUT="console"
        GRUB_CMDLINE_LINUX="crashkernel=auto resume=/dev/mapper/rl-swap rd.lvm.lv=rl/root rd.lvm.lv=rl/swap systemd.unified_cgroup_hierarchy=1
        systemd.unified_cgroup_hierarchv=1" GRUB_DISABLE_RECOVERY=" true"
        GRUB_ENABLE_BLSCFG=true

      4. Save the file and regenerate the GRUB configuration.

        sudo grub2-mkconfig -o /boot/grub2/grub.cfg

      5. Reboot the system.

        sudo reboot

      Configure firewalld (Cilium Only)​

      1. (Optional) If you are using Cilium and have firewalld enabled, put the the following commands into a shell script.

        cat << 'EOF' > firewalld-cilium.sh
        #!/bin/bash

        if [ -z "$1" ]; then
          echo "Usage: $0 <zone>"
          exit 1
        fi

        ZONE="$1"

        # Kubernetes API Server
        firewall-cmd --permanent --zone="$ZONE" --add-port=6443/tcp

        # Etcd
        firewall-cmd --permanent --zone="$ZONE" --add-port=2379-2380/tcp

        # Kubelet API
        firewall-cmd --permanent --zone="$ZONE" --add-port=10250/tcp

        # Scheduler and Controller Manager
        firewall-cmd --permanent --zone="$ZONE" --add-port=10257-10259/tcp

        # kube proxy health check
        firewall-cmd --permanent --zone="$ZONE" --add-port=10255/tcp

        # Nodeport range
        firewall-cmd --permanent --zone="$ZONE" --add-port=30000-32767/tcp

        ############### Start Cilium Rules ##########################

        # Cilium: VXLAN Overlay
        firewall-cmd --permanent --zone="$ZONE" --add-port=8472/udp

        # Cilium: Health Checks
        firewall-cmd --permanent --zone="$ZONE" --add-port=4240/tcp

        # Cilium: Geneve Overlay networking (if enabled)
        firewall-cmd --permanent --zone="$ZONE" --add-port=6081/udp

        # Cilium: WireGuard Encryption (if enabled)
        firewall-cmd --permanent --zone="$ZONE" --add-port=51871/udp

        # Cilium: IPsec Encryption (if enabled)
        firewall-cmd --permanent --zone="$ZONE" --add-protocol=esp

        # Cilium: Prometheus Observability
        firewall-cmd --permanent --zone="$ZONE" --add-port=9962/tcp
        firewall-cmd --permanent --zone="$ZONE" --add-port=9963/tcp

        # Cilium: Enable ICMP Type 8 (Echo request) and Type 0 (Echo Reply)
        firewall-cmd --permanent --zone="$ZONE" --add-icmp-block-inversion

        ############### End Cilium Rules ##########################

        # DNS and service communications

        # DNS (CoreDNS)
        firewall-cmd --permanent --zone="$ZONE" --add-port=53/tcp
        firewall-cmd --permanent --zone="$ZONE" --add-port=53/udp

        # Allow inbound/outbound traffic to port 443 (HTTPS)
        firewall-cmd --permanent --zone="$ZONE" --add-port=443/tcp

        # Allow inbound/outbound traffic to port 4222 (NATS)
        firewall-cmd --permanent --zone="$ZONE" --add-port=4222/tcp

        # Allow NAT traffic
        firewall-cmd --permanent --add-masquerade

        # Reload firewalld cache
        firewall-cmd --reload
        EOF

        # Make the script executable
        chmod +x firewalld-cilium.sh

      2. Execute the script with the name of the firewalld zone. For example, the following script sets the rules in the firewall zone public.

        ./firewalld-cilium.sh public

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 a Palette registration token and the default Palette endpoint, specifies a Palette project, and sets up the kairos user. Note the following:

    • The host will not shut down and will instead reboot after the agent is installed, 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.
    • The projectName parameter is not required if the associated Palette registration token has a Default Project set.

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

    stylus:
      skipKubeVip: false
      site:
        edgeHostToken: $TOKEN
        paletteEndpoint: api.spectrocloud.com
        projectName: Default
    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
        projectName: Default
    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. There is a FIPS-compliant script, if needed.

    curl --location --output ./palette-agent-install.sh https://github.com/spectrocloud/agent-mode/releases/latest/download/palette-agent-install.sh
    Dedicated or On-Premises Palette Instance

    If you have a dedicated or on-premises instance of Palette, you need to identify the correct agent version and then download the corresponding version of the agent installation script. Use the command below and replace <palette-endpoint> with your Palette endpoint and <api-key> with your Palette API key to identify the version.

    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

    Issue the following command to download the version of the Palette agent for your dedicated or on-prem instance. Replace <stylus-version> with your output from the previous step.

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

  7. Grant execution permissions to the installation 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.

warning

If using the FIPS version of Agent Mode on a Rocky Linux edge host, SELinux may incorrectly label the kubeadm-flags.env file during cluster deployment or when certain configurations are adjusted, preventing the Kubelet from accessing it and properly managing the cluster. Refer to the Edge Troubleshooting Guide for guidance.

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.

Alongside Palette, Local UI allows you to fully manage the lifecycle of your edge hosts. Refer to the Reboot, Shutdown, and Reset Edge Host guide for further details on how to use these operations