Skip to content

Commit

Permalink
docs: add instructions for proxy (#4543)
Browse files Browse the repository at this point in the history 
* docs: add instructions for proxy

* Apply suggestions from code review

* Apply suggestions from code review

Co-authored-by: Karl Cardenas <[email protected]>

* ci: auto-formatting prettier issues

---------

Co-authored-by: Lenny Chen <[email protected]>
Co-authored-by: Karl Cardenas <[email protected]>
Co-authored-by: lennessyy <[email protected]>
  • Loading branch information
@lennessyy @karl-cardenas-coding
4 people authored Nov 5, 2024
1 parent 3b60199 commit 5145272
Showing 1 changed file with 78 additions and 38 deletions.
116 changes: 78 additions & 38 deletions docs/docs-content/deployment-modes/agent-mode/install-agent-host.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,32 @@ Palette. You will then create a cluster profile and use the registered host to d
export TOKEN=<your-palette-registration-token>
```

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

```shell
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](../../clusters/edge/edge-configuration/installer-reference.md#site-network-parameters).

Alternatively, you can install the agent first and configure proxy in Local UI. For more information, refer to
[Configure HTTP Proxy](../../clusters/edge/local-ui/host-management/configure-proxy.md).

:::

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
Expand Down Expand Up @@ -153,13 +178,13 @@ Palette. You will then create a cluster profile and use the registered host to d
passwd: kairos
```
4. Export the path to your user data file.
5. Export the path to your user data file.
```shell
export USERDATA=./user-data
```
5. Download the latest version of the Palette agent installation script.
6. Download the latest version of the Palette agent installation script.
```shell
curl --location --output ./palette-agent-install.sh https://github.com/spectrocloud/agent-mode/releases/latest/download/palette-agent-install.sh
Expand All @@ -184,13 +209,13 @@ Palette. You will then create a cluster profile and use the registered host to d
curl --location --output ./palette-agent-install.sh https://github.com/spectrocloud/agent-mode/releases/download/<stylus-version>/palette-agent-install.sh
```
6. Grant execution permissions to the `install.sh` script.
7. 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.
8. Issue the following command to install the agent on your host.
```shell
sudo --preserve-env ./palette-agent-install.sh
Expand All @@ -204,36 +229,36 @@ Palette. You will then create a cluster profile and use the registered host to d
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
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.
9. Log in to [Palette](https://console.spectrocloud.com/) and select **Clusters** from the left **Main Menu**.
10. 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. 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
12. 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. Click on **Add Cluster Profile**.
13. In the **Basic Information** section, assign the a profile name, a description, and tags. Select the type as
14. 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. 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
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.
16. Click **Values** under **Pack Details**, then click on **Presets** on the right-hand side. Select **Agent Mode**.
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.](/deployment-modes_agent-mode_byos-pack.webp)
17. Click **Next Layer** to continue.
18. Click **Next Layer** to continue.
18. Complete the cluster profile creation process by filling out the remaining layers.
19. Complete the cluster profile creation process by filling out the remaining layers.
19. Follow the steps in the [Create Cluster Definition](../../clusters/edge/site-deployment/model-profile.md) guide to
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.
</TabItem>
Expand Down Expand Up @@ -285,15 +310,30 @@ internet.
export USERDATA=./user-data
```
4. Download the agent installation image from a host with internet access and export it to a TAR file. Replace
4. (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.
```shell
export http_proxy=<httpProxyAddress>
export https_proxy=<httpsProxyAddress>
export HTTP_PROXY=<httpProxyAddress>
export HTTPS_PROXY=<httpsProxyAddress>
```
5. 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`.
```shell
crane pull us-docker.pkg.dev/palette-images/edge/stylus-agent-mode-linux-<architecture>:<version> agent-image.tar
```
5. Issue the following command from a host with internet access to download the agent binary and name the binary
6. 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`.
Expand All @@ -303,16 +343,16 @@ internet.
curl --verbose --location $URL --output palette-agent
```
6. Issue the following command to make the binary executable.
7. Issue the following command to make the binary executable.
```shell
chmod +x palette-agent
```
7. Copy the agent binary as well as the agent image TAR file from your host with internet access to the host where you
8. 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.
8. Issue the following command to install the agent on your host. Replace `<image-tag>` with the tag of the installation
9. 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.
Expand All @@ -329,30 +369,30 @@ internet.
Connection to 192.168.1.100 closed.
```
9. Log in to [Palette](https://console.spectrocloud.com/) and select **Clusters** from the left **Main Menu**.
10. 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. 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
12. 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. Click on **Add Cluster Profile**.
13. In the **Basic Information** section, assign the a profile name, a description, and tags. Select the type as
14. 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. 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
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.
16. Click **Values** under **Pack Details**, then click on **Presets** on the right-hand side. Select **Agent Mode**.
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.](/deployment-modes_agent-mode_byos-pack.webp)
17. Click **Next Layer** to continue.
18. Click **Next Layer** to continue.
18. In the **Kubernetes** layer, under `cluster.config.kube-apiserver-arg`, remove `AlwaysPullImages` from the list item
19. In the **Kubernetes** layer, under `cluster.config.kube-apiserver-arg`, remove `AlwaysPullImages` from the list item
`enable-admission-plugins`:
```yaml {7}
Expand All @@ -365,28 +405,28 @@ internet.
- enable-admission-plugins=NamespaceLifecycle,ServiceAccount,NodeRestriction
```
19. Complete the cluster profile creation process by filling out the remaining layers. In the application layer, make
20. 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.
20. Follow the steps in
21. Follow the steps in
[Export Cluster Definition](../../clusters/edge/local-ui/cluster-management/export-cluster-definition.md) to export
a cluster definition of your profile. You will use this cluster definition later when you create the cluster in
Local UI.
21. (Optional) If your host has access to all the images referenced by your cluster profile, you may skip this step.
22. (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](../../clusters/edge/edgeforge-workflow/palette-canvos/build-content-bundle.md) 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.
22. Log in to [Local UI](../../clusters/edge/local-ui/host-management/access-console.md).
23. Log in to [Local UI](../../clusters/edge/local-ui/host-management/access-console.md).
23. Follow the steps in
24. Follow the steps in
[Upload Content Bundles](../../clusters/edge/local-ui/cluster-management/upload-content-bundle.md) to upload the
content bundle to your host.
24. Follow the steps in [Create Local Cluster](../../clusters/edge/local-ui/cluster-management/create-cluster.md) to use
25. Follow the steps in [Create Local Cluster](../../clusters/edge/local-ui/cluster-management/create-cluster.md) to use
the cluster definition you exported previously to create a cluster.
</TabItem>
Expand Down

0 comments on commit 5145272

Please sign in to comment.