Skip to content

Commit

Permalink
docs: document signed content (#3251)
Browse files Browse the repository at this point in the history 
* docs: draft for signed content

* docs: fix broken link

* docs: add crosslink

* docs: add minor clarifications

* Update docs/docs-content/clusters/edge/edgeforge-workflow/palette-canvos/signed-content.md

* docs: address review comments

* docs: add note about signed content

---------

Co-authored-by: Lenny Chen <lenny.chen@spectrocloud.com>
  • Loading branch information
@lennessyy
lennessyy and Lenny Chen committed Jul 11, 2024
1 parent 0dcf2a6 commit c35a088
Show file tree
Hide file tree
Showing 7 changed files with 248 additions and 29 deletions.
1 change: 1 addition & 0 deletions docs/docs-content/clusters/edge/edgeforge-workflow/palette-canvos/arg.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ of both the provider images and the Edge Installer ISO. This page lists the para
| `ARCH` | Architecture of the image. Required. | `amd64`, `arm64`. |
| `AUTO_ENROLL_SECUREBOOT_KEYS` | Determines whether to auto enroll keys used for Trusted Boot. | `true`, `false`. Default is `false`. |
| `CUSTOM_TAG` | A custom tag for the provider images. This custom tag will be appended to the `IMAGE_REGISTRY` and `IMAGE_REPO` parameters to form the full image tag. | Lowercase alphanumeric string without spaces. |
| `EDGE_CUSTOM_CONFIG` | Path to a custom configuration YAML file for your Edge host Local UI. | Absolute path or relative path, with **CanvOS/** as the root directory. |
| `FIPS_ENABLED` | Whether to generate FIPS compliant binaries. | `true`, `false.` Default is `false` |
| `HTTP_PROXY` | URL of the HTTP Proxy server. | URL string. |
| `HTTPS_PROXY` | URL of the HTTPS Proxy server. | URL string. |
Expand Down
20 changes: 11 additions & 9 deletions ...content/clusters/edge/edgeforge-workflow/palette-canvos/build-content-bundle.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -259,18 +259,20 @@ Creating a content bundle provides several benefits that may address common use
--palette-endpoint <PALETTE_API_ENDPOINT> \
--outfile <BUNDLE_NAME> \
--cred-file-path <FILE_PATH> \
--private-key <PRIVATE_KEY_PATH>\
--include-palette-content
```

| Flag | Description |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `--api-key` | Your Palette API key. |
| `--cluster-profile-ids` | Comma-separated list of cluster profile IDs to download content for. |
| `--cred-file-path` | Path to the JSON file storing registry credentials if you are using a private registry. |
| `--include-palette-content` | Whether to include content necessary for Palette itself. Required for airgap installations. |
| `--outfile` | Name of your content bundle. The final file name should have the following pattern: `core-<bundle-name>-random-string`. |
| `--palette-endpoint` | API endpoint for your Palette instance. |
| `--project-id` | The ID of your Palette project. |
| Flag | Description |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--api-key` | Your Palette API key. |
| `--cluster-profile-ids` | Comma-separated list of cluster profile IDs to download content for. |
| `--cred-file-path` | Path to the JSON file storing registry credentials if you are using a private registry. |
| `--include-palette-content` | Whether to include content necessary for Palette itself. Required for airgap installations. |
| `--outfile` | Name of your content bundle. The final file name should have the following pattern: `core-<bundle-name>-random-string`. |
| `--palette-endpoint` | API endpoint for your Palette instance. |
| `--project-id` | The ID of your Palette project. |
| `--private-key` | The path to the private key used to sign the content bundle and cluster definition if it is present. This is necessary if your Edge host has an embedded corresponding public key. For more information, refer to [Embed Public Key in Edge Artifacts](./signed-content.md). |

The result is a content bundle that you can use to preload into your installer. The content bundle will be a zst
file in a folder that starts with **content-** followed by a random string. For more information about how to use a
Expand Down
39 changes: 29 additions & 10 deletions ...-content/clusters/edge/edgeforge-workflow/palette-canvos/build-installer-iso.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,8 @@ process.
- 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.

- [Git](https://git-scm.com/downloads). You can ensure git installation by issuing the `git --version` command.

## Instructions

Use the following instructions to build the Edge Installer ISO. The optional steps can be completed any order.
Expand Down Expand Up @@ -116,9 +118,14 @@ Use the following instructions to build the Edge Installer ISO. The optional ste
EOF
```

7. (Optional) You can embed a public key in your Edge installer ISO. If you choose to add a public key to your ISO or
provider image, then only content that is signed by the corresponding private 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).

### Prepare User Data

7. Refer to [Prepare User Data](./../prepare-user-data.md) to prepare the **user-data** file in the root directory of
8. Refer to [Prepare User Data](./../prepare-user-data.md) to prepare the **user-data** file in the root directory of
the **CanvOS** directory.

User data contains installer configuration and is required for an installer ISO. If you do not supply user data
Expand All @@ -136,14 +143,26 @@ If you do not include content bundle in your Edge Installer ISO, you can still b
a disconnected Edge host instance via [Local UI](../../local-ui/local-ui.md). For more information, refer to
[Upload Content Bundle](../../local-ui/cluster-management/upload-content-bundle.md).

8. Refer to [Build Content Bundle](build-content-bundle.md) to learn how to build content bundles for your ISO image.
9. Refer to [Build Content Bundle](build-content-bundle.md) to learn how to build content bundles for your ISO image.
Since you are including the content bundle in the Installer ISO, you should choose either the zst format or the tar
format for the content bundle. Do not build the content bundle as an ISO image.

9. When the content bundle build finishes, the output will be in a directory named **content-XXXXXX**, where XXXXXX is a
random alphanumerical string. Inside the directory is the content bundle file.
:::info

If you are embedding a public key in your ISO, you do not need to sign the content bundle with the corresponding
private key when building the content bundle.

This is because the public key and the content bundle are provided by the same entity during build time, and
therefore verification is not needed. However, after the build is completed and an Edge host has already been
installed, content bundles that are uploaded through Local UI must have the correct signature in order to be accepted
by the Edge host.

:::

10. When the content bundle build finishes, the output will be in a directory named **content-XXXXXX**, where XXXXXX is
a random alphanumerical string. Inside the directory is the content bundle file.

10. Place the directory containing the content bundle file in the root directory of the **CanvOS** directory.
11. Place the directory containing the content bundle file in the root directory of the **CanvOS** directory.

### Prepare Cluster Definition (Tech Preview)

Expand All @@ -154,12 +173,12 @@ API endpoint.
If you do not include cluster definitions in your Edge Installer ISO, you can still import the cluster definition from
Local UI once you finish installing Palette on the Edge host.

11. Refer to [Export Cluster Definition](../../local-ui/cluster-management/export-cluster-definition.md) to learn how to
12. Refer to [Export Cluster Definition](../../local-ui/cluster-management/export-cluster-definition.md) to learn how to
export cluster definitions.

12. Put the cluster definition tgz file in the **CanvOS/** directory.
13. Put the cluster definition tgz file in the **CanvOS/** directory.

13. In the **.arg** file, add an argument `CLUSTERCONFIG` and set it to the name of the cluster configuration file. For
14. In the **.arg** file, add an argument `CLUSTERCONFIG` and set it to the name of the cluster configuration file. For
example:

```
Expand All @@ -168,14 +187,14 @@ Local UI once you finish installing Palette on the Edge host.

### Build Edge Installer ISO

14. Ensure that all components of the ISO you want to include are in the **CanvOS/** directory:
15. Ensure that all components of the ISO you want to include are in the **CanvOS/** directory:

- **.args** file: **CanvOS/.args**
- User data: **CanvOS/user-data**
- Content bundle: **CanvOS/content-XXXXX/core-spectro-content**
- Cluster definition: **CanvOS/cluster-name-XXXX.tgz**

15. Issue the following command to build the ISO image.
16. Issue the following command to build the ISO image.

```shell
./earthly.sh +iso
Expand Down
11 changes: 8 additions & 3 deletions ...ontent/clusters/edge/edgeforge-workflow/palette-canvos/build-provider-images.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -126,7 +126,12 @@ artifacts at the same time.
Refer to [Edge Artifact Build Configurations](./arg.md) for all available arguments.
11. CanvOS utility uses [Earthly](https://earthly.dev/) to build the target artifacts. Issue the following command to
11. (Optional) You can embed a public key in your provider image. If you choose to add a public key to your provider
image, after you create a cluster with the provider image, only content that is signed by the corresponding private
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.
```bash
Expand All @@ -139,14 +144,14 @@ artifacts at the same time.
Share your logs with an Earthly account (experimental)! Register for one at https://ci.earthly.dev.
```
12. To use the provider images in your cluster profile, push them to your image registry mentioned in the **.arg** file.
13. To use the provider images in your cluster profile, push them to your image registry mentioned in the **.arg** file.
Issue the following command to log in to Docker Hub. Provide your Docker ID and password when prompted.
```bash
docker login
```
13. Use the following commands to push the provider images to the Docker Hub image registry you specified. Replace the
14. Use the following commands to push the provider images to the Docker Hub image registry you specified. Replace the
`[REGISTRY-HOSTNAME]` and version numbers in the command below.
```bash
Expand Down
14 changes: 14 additions & 0 deletions .../docs-content/clusters/edge/edgeforge-workflow/palette-canvos/palette-canvos.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -897,3 +897,17 @@ Palette-managed Edge clusters, we encourage you to check out the reference resou
- [Deploy an Edge Cluster on VMware](../../../../tutorials/edge/deploy-cluster.md)
- [Installation](../../site-deployment/stage.md)
## Resources
- [Edge Artifact Build Configurations](./arg.md)
- [Build Installer ISO](./build-installer-iso.md)
- [Build Provider Images](./build-provider-images.md)
- [Build FIPS-Compliant Edge Artifacts](./fips.md)
- [Build Content Bundles](./build-content-bundle.md)
- [Edge Artifact Build Configurations](./signed-content.md)
Loading

0 comments on commit c35a088

Please sign in to comment.