From 782b446d1cc02d51169b4fc962adafa7de675c19 Mon Sep 17 00:00:00 2001 From: "vault-token-factory-spectrocloud[bot]" <133815545+vault-token-factory-spectrocloud[bot]@users.noreply.github.com> Date: Fri, 18 Oct 2024 22:26:55 +0000 Subject: [PATCH] docs: change earthly command to installed earthly (#4323) (#4361) * docs: change earthly command to installed earthly * docs: make changes to tutorials --------- Co-authored-by: Lenny Chen (cherry picked from commit e704e369da9860b2c978545fa67214a26f774edc) Co-authored-by: Lenny Chen <55669665+lennessyy@users.noreply.github.com> --- .../palette-canvos/build-installer-iso.md | 33 +++++++- .../palette-canvos/build-provider-images.md | 35 +++++++-- .../edgeforge-workflow/palette-canvos/fips.md | 35 +++++++-- .../palette-canvos/palette-canvos.md | 78 +++++++++++++++---- .../palette-canvos/signed-content.md | 7 ++ .../edgeforge/build-trusted-provider-image.md | 4 +- .../edge/deploy-cluster-virtualbox.md | 11 ++- .../tutorials/edge/deploy-cluster.md | 35 +++++++-- 8 files changed, 201 insertions(+), 37 deletions(-) diff --git a/docs/docs-content/clusters/edge/edgeforge-workflow/palette-canvos/build-installer-iso.md b/docs/docs-content/clusters/edge/edgeforge-workflow/palette-canvos/build-installer-iso.md index 3c1e4c8820..50dc69a3ca 100644 --- a/docs/docs-content/clusters/edge/edgeforge-workflow/palette-canvos/build-installer-iso.md +++ b/docs/docs-content/clusters/edge/edgeforge-workflow/palette-canvos/build-installer-iso.md @@ -63,6 +63,19 @@ process. - [Git](https://git-scm.com/downloads). You can ensure git installation by issuing the `git --version` command. +- (Optional) [Earthly](https://earthly.dev/) is installed and available. If you do not install Earthly, you can still + build the artifacts, but it would require root privileges, and some of the resulting artifacts will be owned by the + root user. + +- An image management tool such as [Docker](https://docs.docker.com/engine/install/) or + [crane](https://github.com/google/go-containerregistry/blob/main/cmd/crane/README.md) is installed and available. + + :::info + + If you do not install Earthly, you must install Docker. + + ::: + ## Instructions Use the following instructions to build the Edge Installer ISO. The optional steps can be completed any order. @@ -196,10 +209,26 @@ Local UI once you finish installing Palette on the Edge host. 16. Issue the following command to build the ISO image. - ```shell - ./earthly.sh +iso + + + + + ```bash + earthly +iso ``` + + + + + ```bash + sudo ./earthly.sh +iso + ``` + + + + + ``` # Output condensed for readability ===================== Earthly Build SUCCESS ===================== diff --git a/docs/docs-content/clusters/edge/edgeforge-workflow/palette-canvos/build-provider-images.md b/docs/docs-content/clusters/edge/edgeforge-workflow/palette-canvos/build-provider-images.md index e3bea22797..45aa4a3c98 100644 --- a/docs/docs-content/clusters/edge/edgeforge-workflow/palette-canvos/build-provider-images.md +++ b/docs/docs-content/clusters/edge/edgeforge-workflow/palette-canvos/build-provider-images.md @@ -41,9 +41,18 @@ artifacts at the same time. - [Git](https://git-scm.com/downloads). You can ensure git installation by issuing the `git --version` command. -- [Docker Engine](https://docs.docker.com/engine/install/) version 18.09.x or later. You can use the `docker --version` - command to view the existing Docker version. You should have root-level or `sudo` privileges on your Linux machine to - create privileged containers. +- (Optional) [Earthly](https://earthly.dev/) is installed and available. If you do not install Earthly, you can still + build the artifacts, but it would require root privileges, and some of the resulting artifacts will be owned by the + root user. + +- An image management tool such as [Docker](https://docs.docker.com/engine/install/) or + [crane](https://github.com/google/go-containerregistry/blob/main/cmd/crane/README.md) is installed and available. + + :::info + + If you do not install Earthly, you must install Docker. + + ::: ## Build Provider Images @@ -135,13 +144,29 @@ artifacts at the same time. key can be uploaded to the Edge host through Local UI. This includes both the content bundle and cluster definition. For more information, refer to [Embed Public Key in Edge Artifacts](./signed-content.md). -12. CanvOS utility uses [Earthly](https://earthly.dev/) to build the target artifacts. Issue the following command to - start the build process. +12. CanvOS utility uses [Earthly](https://earthly.dev/)(https://earthly.dev/) to build the target artifacts. Issue the + following command to start the build process. + + + + + + ```bash + earthly +build-provider-images + ``` + + + + ```bash sudo ./earthly.sh +build-provider-images ``` + + + + ```hideClipboard bash {2} # Output condensed for readability ===================== Earthly Build SUCCESS ===================== diff --git a/docs/docs-content/clusters/edge/edgeforge-workflow/palette-canvos/fips.md b/docs/docs-content/clusters/edge/edgeforge-workflow/palette-canvos/fips.md index 6e1c826a9e..98804a372c 100644 --- a/docs/docs-content/clusters/edge/edgeforge-workflow/palette-canvos/fips.md +++ b/docs/docs-content/clusters/edge/edgeforge-workflow/palette-canvos/fips.md @@ -48,9 +48,18 @@ This page guides you through the process of building FIPS-compliant Edge Install - [Git](https://git-scm.com/downloads). You can ensure git installation by issuing the `git --version` command. -- [Docker Engine](https://docs.docker.com/engine/install/) version 18.09.x or later. You can use the `docker --version` - command to check the existing Docker version. You should have root-level or `sudo` privileges on your Linux machine to - create privileged containers. +- (Optional) [Earthly](https://earthly.dev/) is installed and available. If you do not install Earthly, you can still + build the artifacts, but it would require root privileges, and some of the resulting artifacts will be owned by the + root user. + +- An image management tool such as [Docker](https://docs.docker.com/engine/install/) or + [crane](https://github.com/google/go-containerregistry/blob/main/cmd/crane/README.md) is installed and available. + + :::info + + If you do not install Earthly, you must install Docker. + + ::: - A [VerteX](/docs/docs-content/vertex/vertex.md) or Palette account. Refer to [Palette VerteX](/docs/docs-content/vertex/vertex.md#access-palette-vertex) for information on how to set up a VerteX @@ -254,10 +263,26 @@ workaround. 16. Issue the following command to build the Edge Installer ISO. - ```shell - ./earthly.sh +iso + + + + + ```bash + earthly +iso ``` + + + + + ```bash + sudo ./earthly.sh +iso + ``` + + + + + When the build finishes, the ISO file will be generated in the **build** directory under the name you specified in your **.arg** file. diff --git a/docs/docs-content/clusters/edge/edgeforge-workflow/palette-canvos/palette-canvos.md b/docs/docs-content/clusters/edge/edgeforge-workflow/palette-canvos/palette-canvos.md index 30639b2e56..407ee6bbae 100644 --- a/docs/docs-content/clusters/edge/edgeforge-workflow/palette-canvos/palette-canvos.md +++ b/docs/docs-content/clusters/edge/edgeforge-workflow/palette-canvos/palette-canvos.md @@ -80,9 +80,18 @@ To complete this basic guide, you will need the following items: - [Git](https://git-scm.com/downloads). You can ensure git installation by issuing the `git --version` command. -- [Docker Engine](https://docs.docker.com/engine/install/) version 18.09.x or later. You can use the `docker --version` - command to view the existing Docker version. You should have root-level or `sudo` privileges on your Linux machine to - create privileged containers. +- (Optional) [Earthly](https://earthly.dev/) is installed and available. If you do not install Earthly, you can still + build the artifacts, but it would require root privileges, and some of the resulting artifacts will be owned by the + root user. + +- An image management tool such as [Docker](https://docs.docker.com/engine/install/) or + [crane](https://github.com/google/go-containerregistry/blob/main/cmd/crane/README.md) is installed and available. + + :::info + + If you do not install Earthly, you must install Docker. + + ::: - A [Spectro Cloud](https://console.spectrocloud.com) account. If you have not signed up, you can sign up for an account [here](https://www.spectrocloud.com/get-started). @@ -214,9 +223,9 @@ customization. cat user-data ``` -10. The CanvOS utility uses [Earthly](https://earthly.dev/) to build the target artifacts. By default, images are - created for all the Palette-supported Kubernetes versions. Comment out the versions you do not need in the file - **Earthfile** to speed up the build process and save disk space. +10. The CanvOS utility uses [Earthly](https://earthly.dev/)(https://earthly.dev/) to build the target artifacts. By + default, images are created for all the Palette-supported Kubernetes versions. Comment out the versions you do not + need in the file **Earthfile** to speed up the build process and save disk space. ``` build-provider-images: @@ -228,10 +237,26 @@ customization. 11. Issue the following command to start the build process. + + + + + ```bash + earthly +build-all-images + ``` + + + + + ```bash sudo ./earthly.sh +build-all-images ``` + + + + ```bash hideClipboard ===================== Earthly Build SUCCESS ===================== Share your logs with an Earthly account (experimental)! Register for one at https://ci.earthly.dev. @@ -428,10 +453,10 @@ process means installing the necessary tools and configurations on a host machin ### Prerequisites -To complete this advanced guide, you will need the following items:
+To complete this advanced guide, you will need the following items: - A physical or virtual Linux machine with _AMD64_ (also known as _x86_64_) processor architecture to build the Edge - artifacts. You can issue the following command in the terminal to check your processor architecture.
+ artifacts. You can issue the following command in the terminal to check your processor architecture. ```bash uname -m @@ -445,9 +470,18 @@ To complete this advanced guide, you will need the following items:
- [Git](https://git-scm.com/downloads). You can ensure git installation by issuing the `git --version` command. -- [Docker Engine](https://docs.docker.com/engine/install/) version 18.09.x or later. You can use the `docker --version` - command to view the existing Docker version. You should have root-level or `sudo` privileges on your Linux machine to - create privileged containers. +- (Optional) [Earthly](https://earthly.dev/) is installed and available. If you do not install Earthly, you can still + build the artifacts, but it would require root privileges, and some of the resulting artifacts will be owned by the + root user. + +- An image management tool such as [Docker](https://docs.docker.com/engine/install/) or + [crane](https://github.com/google/go-containerregistry/blob/main/cmd/crane/README.md) is installed and available. + + :::info + + If you do not install Earthly, you must install Docker. + + ::: - A [Spectro Cloud](https://console.spectrocloud.com) account. If you have not signed up, you can sign up for an account [here](https://www.spectrocloud.com/get-started). @@ -690,13 +724,29 @@ git checkout v4.4.12 [Edge Configuration Stages](../../edge-configuration/cloud-init.md) and [User Data Parameters](../../edge-configuration/installer-reference.md) documents to learn more. -14. CanvOS utility uses [Earthly](https://earthly.dev/) to build the target artifacts. Issue the following command to - start the build process. +14. CanvOS utility uses [Earthly](https://earthly.dev/)(https://earthly.dev/) to build the target artifacts. Issue the + following command to start the build process. + + + + + + ```bash + earthly +build-all-images + ``` + + + + ```bash sudo ./earthly.sh +build-all-images ``` + + + + ```hideClipboard bash {2} # Output condensed for readability ===================== Earthly Build SUCCESS ===================== @@ -709,7 +759,7 @@ git checkout v4.4.12 `+build-all-images` option in the command above. The command, `sudo ./earthly.sh +build-provider-images`, will build the provider images but not the Edge installer ISO. - ::: + :::info This command may take up to 15-20 minutes to finish depending on the resources of the host machine. Upon completion, the command will display the manifest, as shown in the example below, that you will use in your cluster profile diff --git a/docs/docs-content/clusters/edge/edgeforge-workflow/palette-canvos/signed-content.md b/docs/docs-content/clusters/edge/edgeforge-workflow/palette-canvos/signed-content.md index 526974093d..ebc25a0c31 100644 --- a/docs/docs-content/clusters/edge/edgeforge-workflow/palette-canvos/signed-content.md +++ b/docs/docs-content/clusters/edge/edgeforge-workflow/palette-canvos/signed-content.md @@ -46,6 +46,13 @@ your Edge hosts come from a trusted source. For more information about content b - 150 GB storage. If you plan on using a content bundle, the actual storage will depend on the size of the content bundle you will use to build the Edge installer ISO image. +- (Optional) [Earthly](https://earthly.dev/) is installed and available. If you do not install Earthly, you can still + build the artifacts, but it would require root privileges, and some of the resulting artifacts will be owned by the + root user. + +- An image management tool such as [Docker](https://docs.docker.com/engine/install/) or + [crane](https://github.com/google/go-containerregistry/blob/main/cmd/crane/README.md) is installed and available. + ## Embed a Public Key in Edge Artifacts 1. Clone the **CanvOS** repository. diff --git a/docs/docs-content/clusters/edge/trusted-boot/edgeforge/build-trusted-provider-image.md b/docs/docs-content/clusters/edge/trusted-boot/edgeforge/build-trusted-provider-image.md index 39f0ae0829..792ddebee9 100644 --- a/docs/docs-content/clusters/edge/trusted-boot/edgeforge/build-trusted-provider-image.md +++ b/docs/docs-content/clusters/edge/trusted-boot/edgeforge/build-trusted-provider-image.md @@ -142,8 +142,8 @@ key that is in the Signature Database (DB). This is important both during instal Instead, open the **Earthfile** in the CanvOS directory. Under `build-provider-images`, remove the lines containing Kubernetes versions that you do not need. -11. CanvOS utility uses [Earthly](https://earthly.dev/) to build the target artifacts. Issue the following command to - start the build process. +11. CanvOS utility uses [Earthly](https://earthly.dev/)(https://earthly.dev/) to build the target artifacts. Issue the + following command to start the build process. ```bash ./earthly.sh +build-provider-images diff --git a/docs/docs-content/tutorials/edge/deploy-cluster-virtualbox.md b/docs/docs-content/tutorials/edge/deploy-cluster-virtualbox.md index b971d06b15..297d679eeb 100644 --- a/docs/docs-content/tutorials/edge/deploy-cluster-virtualbox.md +++ b/docs/docs-content/tutorials/edge/deploy-cluster-virtualbox.md @@ -56,7 +56,10 @@ To complete this tutorial, you will need the following prerequisites in place. guide for instructions on how to create a token. - The following software installed: - A text editor such as Vi or Nano. This tutorial uses Vi as an example. - - [Docker Engine](https://docs.docker.com/engine/install/) with `sudo` privileges + - [Docker Engine](https://docs.docker.com/engine/install/) with `sudo` privileges. Alternatively, you can install + [Earthly](https://earthly.dev/), in which case you will not need `sudo` privileges. And you can use lighter image + management tools like [crane](https://github.com/google/go-containerregistry/blob/main/cmd/crane/README.md) instead + of Docker. - [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) - [VirtualBox](https://www.virtualbox.org/wiki/Downloads) version 7.0 @@ -109,9 +112,9 @@ git checkout v4.4.12 ### Define Arguments -EdgeForge leverages [Earthly](https://earthly.dev) to build the Installer ISO and provider images artifacts. The -**.arg** file is used to pass the values of a few arguments, such as the image tag and registry name, to Earthly for the -build process. +EdgeForge leverages [Earthly](https://earthly.dev/)(https://earthly.dev) to build the Installer ISO and provider images +artifacts. The **.arg** file is used to pass the values of a few arguments, such as the image tag and registry name, to +Earthly for the build process. Execute the command below to create a custom tag for the provider images. The tag must be an alphanumeric lowercase string. This tutorial uses `vbox-tutorial` as an example. diff --git a/docs/docs-content/tutorials/edge/deploy-cluster.md b/docs/docs-content/tutorials/edge/deploy-cluster.md index f47caa359f..f1cffe0da8 100644 --- a/docs/docs-content/tutorials/edge/deploy-cluster.md +++ b/docs/docs-content/tutorials/edge/deploy-cluster.md @@ -75,9 +75,18 @@ To complete this tutorial, you will need the following: - [Git](https://git-scm.com/downloads). Ensure git installation by issuing the `git --version` command. -- [Docker Engine](https://docs.docker.com/engine/install/) version 18.09.x or later. You can use the `docker --version` - command to view the existing Docker version. You should have root-level or `sudo` privileges on your Linux machine to - create privileged containers. +- (Optional) [Earthly](https://earthly.dev/) is installed and available. If you do not install Earthly, you can still + build the artifacts, but it would require root privileges, and some of the resulting artifacts will be owned by the + root user. + +- An image management tool such as [Docker](https://docs.docker.com/engine/install/) or + [crane](https://github.com/google/go-containerregistry/blob/main/cmd/crane/README.md) is installed and available. + + :::info + + If you do not install Earthly, you must install Docker. + + ::: - A [Spectro Cloud](https://console.spectrocloud.com) account. If you have not signed up, you can sign up for an account [here](https://www.spectrocloud.com/get-started). @@ -247,8 +256,8 @@ users: ## Build Artifacts -The CanvOS utility uses [Earthly](https://earthly.dev/) to build the target artifacts. Issue the following command to -start the build process. +The CanvOS utility uses [Earthly](https://earthly.dev/)(https://earthly.dev/) to build the target artifacts. Issue the +following command to start the build process. :::warning @@ -264,10 +273,26 @@ to [Build Edge Artifacts guide](../../clusters/edge/edgeforge-workflow/palette-c ::: + + + + +```bash +earthly +build-all-images +``` + + + + + ```bash sudo ./earthly.sh +build-all-images ``` + + + + ```hideClipboard bash {2} # Output condensed for readability ===================== Earthly Build SUCCESS =====================