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 Architecture OS Kubernetes Container Network Interface (CNI) Verified
AMD64 Ubuntu Palette eXtended Kubernetes - Edge (PXK-E) Calico ✅
AMD64 Ubuntu K3s Flannel ✅
Clusters with Flannel CNI is not verified for airgap deployments.

Host Architecture	OS	Kubernetes	Container Network Interface (CNI)	Verified
AMD64	Ubuntu	Palette eXtended Kubernetes - Edge (PXK-E)	Calico	✅
AMD64	Ubuntu	K3s	Flannel	✅

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:
- jq
- Zstandard
- Rsync
- conntrack. This requirement is specific for clusters that use PXKE as the Kubernetes layer.
- (Airgap only) Crane is installed and available.
- (Airgap only) Palette Edge CLI 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

Connected
Airgap

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>
```
Export your Palette registration token. Replace <your-palette-registration-token> with your token.
```
export TOKEN=<your-palette-registration-token>
```
(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>
```
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
```
Export the path to your user data file.
```
export USERDATA=./user-data
```

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

Grant execution permissions to the install.sh script.
```
chmod +x ./palette-agent-install.sh
```
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.
```
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.
Log in to Palette and select Clusters from the left Main Menu.
Select the Edge Hosts tab and verify your host is displayed and marked as Healthy in the Edge hosts list.
Once the host has been registered with Palette, proceed with the cluster profile creation. Select Profiles from the left Main Menu.
Click on Add Cluster Profile.
In the Basic Information section, assign the a profile name, a description, and tags. Select the type as Full and click Next.
Select Edge Native as the Cloud Type and click Next.
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.
Click Values under Pack Details, then click on Presets on the right-hand side. Select Agent Mode.
Click Next Layer to continue.
Complete the cluster profile creation process by filling out the remaining layers.
Follow the steps in the Create Cluster Definition guide to deploy a cluster using your registered host as a cluster node.

In an airgapped environment, your host does not have a connection to Palette and may also have limited access to the internet.

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>
```
Issue the command below to create the user-data file and configure your host declaratively.

The following configuration indicates the installation mode to be airgap 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
  installationMode: airgap
stages:
  initramfs:
    - users:
        kairos:
          groups:
            - sudo
          passwd: kairos
EOF
```
Export the path to your user data file.
```
export USERDATA=./user-data
```
(Optional) If you are not accessing the internet via a proxy, skip this step.

If you are downloading the agent on a host that accesses the internet via a proxy network, export the proxy configurations in your current terminal session so that the script downloading the agent binary can execute successfully. 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>
```
Download the agent installation image from a host with internet access and export it to a TAR file. Replace <architecture> with the architecture of your CPU. If you have ARM64, use arm64. If you have AMD64 or x86_64, use amd64. Replace <version> with the desired version number. In this example, we use v4.5.0.
```
crane pull us-docker.pkg.dev/palette-images/edge/stylus-agent-mode-linux-<architecture>:<version> agent-image.tar
```
Issue the following command from a host with internet access to download the agent binary and name the binary palette-agent. Replace <architecture> with the architecture of your CPU. If you have ARM64, use arm64. If you have AMD64 or x86_64, use amd64. Replace <version> with the desired version number. In this example, we use v4.5.0.
```
export URL=https://github.com/spectrocloud/agent-mode/releases/download/<version>/palette-agent-linux-<architecture>
curl --verbose --location $URL --output palette-agent
```
Issue the following command to make the binary executable.
```
chmod +x palette-agent
```
Copy the agent binary as well as the agent image TAR file from your host with internet access to the host where you want to install the Palette agent.
Issue the following command to install the agent on your host. Replace <image-tag> with the tag of the installation image. If your user data is not in the current directory, replace ./user-data with the path to your user data file. If your agent image TAR file is not in the current directory, replace ./agent-image.tar with the path to your image TAR file.
```
sudo ./palette-agent install --source ./agent-image.tar --config "./user-data" --local
```
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.
```
Log in to Palette and select Clusters from the left Main Menu.
Select the Edge Hosts tab and verify your host is displayed and marked as Healthy in the Edge hosts list.
Once the host has been registered with Palette, proceed with the cluster profile creation. Select Profiles from the left Main Menu.
Click on Add Cluster Profile.
In the Basic Information section, assign the a profile name, a description, and tags. Select the type as Full and click Next.
Select Edge Native as the Cloud Type and click Next.
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.
Click Values under Pack Details, then click on Presets on the right-hand side. Select Agent Mode.
Click Next Layer to continue.

In the Kubernetes layer, under cluster.config.kube-apiserver-arg, remove AlwaysPullImages from the list item enable-admission-plugins:

kube-apiserver-arg:
  - anonymous-auth=true
  - profiling=false
  - disable-admission-plugins=AlwaysAdmit
  - default-not-ready-toleration-seconds=60
  - default-unreachable-toleration-seconds=60
  - enable-admission-plugins=NamespaceLifecycle,ServiceAccount,NodeRestriction

Complete the cluster profile creation process by filling out the remaining layers. In the application layer, make sure you include the Harbor Edge-Native Config pack. This pack is required for airgapped clusters.
Follow the steps in Export Cluster Definition to export a cluster definition of your profile. You will use this cluster definition later when you create the cluster in Local UI.
(Optional) If your host has access to all the images referenced by your cluster profile, you may skip this step.

Follow the steps in Build Content Bundles to build a content bundle for your cluster profile. The content bundle will contain all the artifacts required to create your cluster and it will allow you to create a cluster even if your host has no access to an external image registry.
Log in to Local UI.
Follow the steps in Upload Content Bundles to upload the content bundle to your host.
Follow the steps in Create Local Cluster to use the cluster definition you exported previously to create a cluster.

Validate

Connected
Airgap

Log in to Palette.
Select Clusters from the left Main Menu.
Select the host cluster you created to view its details page.
Verify that the cluster is listed as Healthy and has a Running status.

Limitations​

Prerequisites​

Install Palette Agent​

Validate​

Limitations

Prerequisites

Install Palette Agent

Validate