docs: agent mode / deployment modes

docs/docs-content/deployment-modes/_category_.json

@@ -0,0 +1,3 @@
+{
+  "position": 50
+}

docs/docs-content/deployment-modes/agent-mode/_category_.json

@@ -0,0 +1,3 @@
+{
+  "position": 20
+}

docs/docs-content/deployment-modes/agent-mode/agent-mode.md

@@ -0,0 +1,25 @@
+---
+sidebar_label: "Agent Mode"
+title: "Agent Mode"
+description: "Learn about agent mode, its use cases, and how to deploy a cluster in agent mode. "
+hide_table_of_contents: false
+sidebar_position: 20
+tags: ["edge"]
+---
+
+In agent mode, you bring your own host, which can be any host that meets the basic hardware requirements regardless of
+environments， including an EC2 instance on AWS or a Raspberry Pi in your own home. All you need to do to have Palette
+manage your host is to download and install the Palette agent.
+
+## Use Cases
+
+Agent mode is design to work across a variety of environments, including in public cloud, on-prem data centers, and in
+Edge locations. Currently, the validated use cases include Edge and VMware vSphere.
+
+## Resources
+
+- [Architecture](./architecture.md)
+
+- [Install Palette Agent](install-agent-host.md)
+
+- [Manage Hosts in Agent Mode](./manage-agent/manage-agent.md)

docs/docs-content/deployment-modes/agent-mode/architecture.md

@@ -0,0 +1,35 @@
+---
+sidebar_label: "Architecture"
+title: "Agent Mode Architecture"
+description: "Learn about the architecture of agent mode and its minimal hardware requirements."
+hide_table_of_contents: false
+sidebar_position: 20
+tags: ["edge"]
+---
+
+The following are architectural highlights of clusters deployed using in agent mode.
+
+- You can bring an existing host with your an Operating System (OS) of your choice.
+
+- You may also build the Palette agent into your OS image to have the agent natively installed on your host.
+
+- Support for bare metal, public clouds, data centers, and Edge devices.
+
+- Support for single-node and multi-node deployments.
+
+- Customizable site properties such as network proxies and certificates for Edge deployments.
+
+- Configurable Kubernetes API servers to work with virtual IP address (VIP) or Dynamic DNS.
+
+![Architecture Diagram for Agent Mode](/deployment-modes_agent-mode.webp)
+
+## Minimum Device Requirements
+
+Agent mode deployments support both AMD64 and ARM64 architecture.
+
+| Component | Requirement                                                                                                                                               |
+| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| CPU       | - Intel: i3, i5, i7, i9, Xeon series <br /> - AMD: Ryzen 3, 5, 7, 9, and Epyc series                                                                      |
+| CPU Core  | Minimum two cores.                                                                                                                                        |
+| Memory    | Minimum 8 GB.                                                                                                                                             |
+| Storage   | Main drive requires a minimum of 100 GB storage to accommodate the Operating System (OS), Kubernetes, and workloads. The main drive must be an SSD drive. |

docs/docs-content/deployment-modes/agent-mode/install-agent-host.md

@@ -0,0 +1,239 @@
+---
+sidebar_label: "Install Palette Agent"
+title: "Install Palette Agent"
+description: "Learn how to install the Palette Agent on your host."
+hide_table_of_contents: false
+sidebar_position: 10
+tags: ["edge", "agent mode"]
+---
+
+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](https://aws.amazon.com/ec2/), a
+[Raspberry Pi](https://www.google.com/url?sa=t&source=web&rct=j&opi=89978449&url=https://www.raspberrypi.com/&ved=2ahUKEwi-38Gt__SIAxU2CnkGHeU6Ha8QFnoECAkQAQ&usg=AOvVaw12ldjgQls5EV3KbUmJD0nz),
+a
+[VMware vSphere virtual machine](https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.vm_admin.doc/GUID-F559CE9C-2D8F-4F69-A846-56A1F4FC8529.html),
+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.
+
+:::preview
+
+:::
+
+## 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                                | CNI     | Verified           |
+  | ----------------- | ------ | ----------------------------------------- | ------- | ------------------ |
+  | AMD64             | Ubuntu | Palette eXtended Kubernetes - Edge (PXKE) | Calico  | :white_check_mark: |
+  | AMD64             | Ubuntu | K3s                                       | Flannel | :white_check_mark: |
+
+## Prerequisites
+
+- A physical or virtual host with SSH access, access to the Internet, and connection to Palette. 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](../../clusters/edge/site-deployment/site-installation/create-registration-token.md)
+  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](https://jqlang.github.io/jq/download/)
+  - [Zstandard](https://facebook.github.io/zstd/)
+  - [Rsync](https://github.com/RsyncProject/rsync)
+  - [conntrack](https://conntrack-tools.netfilter.org/downloads.html). This requirement is specific for clusters that
+    use PXKE as the Kubernetes layer.
+
+## 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.
+
+   ```shell
+   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.
+
+   ```shell
+   export TOKEN=<your-palette-registration-token>
+   ```
+
+3. Issue the command below to create the **user-data** file and configure your host declaratively.
+
+   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](../../clusters/edge/networking/kubevip.md) 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](../../clusters/edge/edgeforge-workflow/prepare-user-data.md) guide to learn more about user data
+   configuration.
+
+   ```shell
+   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.
+
+   ```shell
+   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.
+
+   ```text hideClipboard
+   #cloud-config
+   install:
+     reboot: true
+     poweroff: false
+
+   stylus:
+     skipKubeVip: false
+     site:
+       edgeHostToken: ****************
+       paletteEndpoint: api.spectrocloud.com
+   stages:
+     initramfs:
+       - users:
+           kairos:
+             groups:
+               - sudo
+             passwd: kairos
+   ```
+
+4. Export the path to your user data file.
+
+   ```shell
+   export USER_DATA=./user-data
+   ```
+
+5. Download the Palette agent installation script. Access the [Agent Mode](https://github.com/spectrocloud/agent-mode)
+   GitHub repository to obtain the latest releases. This guide uses `v4.5.0-rc9` as an example.
+
+   ```shell
+   curl --location --output ./palette-agent-install.sh https://github.com/spectrocloud/agent-mode/releases/download/v4.5.0-rc9/palette-agent-install.sh
+   ```
+
+6. Grant execution permissions to the `install.sh` script.
+
+   ```shell
+   chmod +x ./palette-agent-install.sh
+   ```
+
+7. Issue the following command to install the agent on your host.
+
+   ```shell
+   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.
+
+   ```text hideClipboard
+   Connection to 192.168.1.100 closed by remote host.
+   Connection to 192.168.1.100 closed.
+   ```
+
+8. 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.
+
+9. Log in to [Palette](https://console.spectrocloud.com/) and select **Clusters** from the left **Main Menu**.
+
+10. Select the **Edge Hosts** tab and verify your host is displayed and marked as **Healthy** in the Edge hosts list.
+
+11. Once the host has been registered with Palette, proceed with the cluster profile creation. Select **Profiles** from
+    the left **Main Menu**.
+
+12. Click on **Add Cluster Profile**.
+
+13. In the **Basic Information** section, assign the a profile name, a description, and tags. Select the type as
+    **Full** and click **Next**.
+
+14. Select **Edge Native** as the **Cloud Type** and click **Next**.
+
+15. The **Profile Layers** section specifies the packs that compose the profile. Add the **BYOS Edge OS** pack version
+    **1.0.0** to the OS layer.
+
+16. Click **Values** under **Pack Details** to edit the pack's manifest.
+
+    <!-- Steps 16 and 17 use the old version of the BYOS pack. The steps will be updated once the new version of the pack is available. -->
+
+    ![View of the cluster profile creation page with the BYOS pack.](/deployment-modes_agent-mode_byos-pack.webp)
+
+17. Update the `system.uri` parameter with the desired Kubernetes image.
+
+    Additionally, include the `stylusPackage` line following the example below.
+
+    ```yaml {16,18}
+    pack:
+      content:
+        images:
+          - image: "{{.spectro.pack.edge-native-byoi.options.system.uri}}"
+      # Below config is default value, please uncomment if you want to modify default values
+      #drain:
+      #cordon: true
+      #timeout: 60 # The length of time to wait before giving up, zero means infinite
+      #gracePeriod: 60 # Period of time in seconds given to each pod to terminate gracefully. If negative, the default value specified in the pod will be used
+      #ignoreDaemonSets: true
+      #deleteLocalData: true # Continue even if there are pods using emptyDir (local data that will be deleted when the node is drained)
+      #force: true # Continue even if there are pods that do not declare a controller
+      #disableEviction: false # Force drain to use delete, even if eviction is supported. This will bypass checking PodDisruptionBudgets, use with caution
+      #skipWaitForDeleteTimeout: 60 # If pod DeletionTimestamp older than N seconds, skip waiting for the pod. Seconds must be greater than 0 to skip.
+    options:
+      system.uri: "gcr.io/spectro-dev-public/stylus/k8s:k3s-1.29.2"
+
+    stylusPackage: container://gcr.io/spectro-dev-public/stylus-edge-standard:v0.0.1
+    ```
+
+18. Click **Next Layer** to continue.
+
+19. Complete the cluster profile creation process by filling out the remaining layers. Ensure that the Kubernetes layer
+    matches the version and distribution specified in step **7** of this guide.
+
+20. Follow the steps in the [Create Cluster Definition](../../clusters/edge/site-deployment/model-profile.md) guide to
+    deploy a cluster using your registered host as a cluster node.
+
+## Validate
+
+1. Log in to [Palette](https://console.spectrocloud.com/).
+
+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.

docs/docs-content/deployment-modes/agent-mode/manage-agent/localui-theming.md

@@ -0,0 +1,65 @@
+---
+sidebar_label: "Customize Local UI Theme"
+title: "Customize Local UI Theme - Agent mode"
+description: "Instructions for customizing Local UI theme for hosts deployed in agent mode."
+hide_table_of_contents: false
+sidebar_position: 100
+tags: ["edge"]
+---
+
+Palette offers the option to customize the Local UI web interface. You can change the color of the sidebar as well as
+using your own logo. You can do this after the agent has been installed on the host to standardize the look feel of the
+console for all Edge hosts of your organization.
+
+:::warning
+
+This guide is specific to agent mode only. If you have an Edge host deployed in appliance mode, you need to provide the
+customizations during EdgeForge instead. Refer to
+[Customize Local UI Theme](../../../clusters/edge/local-ui/host-management/theming.md) for more information.
+
+:::
+
+## Prerequisite
+
+- You have installed the Palette agent on your host machine deployed in agent mode.
+
+- You have SSH access to your host deployed in agent mode and have sufficient privilege to make changes in the
+  **/opt/spectrocloud/localui/ui** folder.
+
+## Procedure
+
+1. Connect to your host via SSH.
+
+2. Navigate to the **/opt/spectrocloud/localui/ui** folder.
+
+3. In the **ui** folder, upload a logo you'd like to use for Local UI to the **ui** directory. All file types are
+   allowed. We recommend you limit the height of the logo image to between 64 px and 120 px. If you don't upload a logo,
+   Local UI will use the Spectro Cloud logo.
+
+4. In the **ui** folder, create a file named **customizations.json**.
+
+5. Populate the file with the following schema:
+
+   ```json
+   {
+     "colors": {
+       "brand": "#4A8FF1",
+       "sidebar": "#2B323C"
+     },
+     "logo": "logo.webp"
+   }
+   ```
+
+   The `colors.sidebar` property controls the color of the sidebar. This is also the color of the background in the
+   Local UI login screen. We suggest you choose a color that contrasts well against your logo as the logo as the color
+   will serve as the background for your logo. The **brand** color controls the color of buttons and checkboxes in the
+   UI. The following image displays the default logo, brand, and sidebar color.
+
+   ![A screenshot of Local UI showing the elements controlled by the color properties and the location of the logo](/cluster_edge_emc_theming.webp)
+
+## Validate
+
+1. Log in to [Local UI](../../../clusters/edge/local-ui/host-management/access-console.md).
+
+2. Confirm that the logo and CSS changes have taken effect. You may need to perform a hard refresh to refresh the cached
+   content on your browser.

docs/docs-content/deployment-modes/agent-mode/manage-agent/manage-agent.md

@@ -0,0 +1,16 @@
+---
+sidebar_label: "Manage Hosts in Agent Mode"
+title: "Manage Hosts in Agent Mode"
+description: "Learn how to manage hosts deployed in agent mode."
+hide_table_of_contents: false
+sidebar_position: 20
+tags: ["agent mode"]
+---
+
+This section provides guidance on how to manage hosts deployed in agent mode. Review the following guide to learn more
+about customizing the [Local UI](../../../clusters/edge/local-ui/local-ui.md) web interface, which you can use to
+configure and manage your host.
+
+## Resources
+
+- Customize Local UI Theme