Skip to content

Commit

Permalink
docs: document how to generate FIPS-compliant Edge artifacts (#2462)
Browse files Browse the repository at this point in the history 
* docs: WIP fips images

* docs: fips first draft

* docs: fips-canvos

* docs: add fips instructions

* docs: fix tabs issue

* docs: copyedits

* fix vale issues

* docs: minor edits

* fix vale

* fix step numbering

* Apply suggestions from code review

Co-authored-by: Yuliia Horbenko <[email protected]>

* make format

* clarify pxk-e

* punctuation

---------

Co-authored-by: Lenny Chen <[email protected]>
Co-authored-by: Yuliia Horbenko <[email protected]>
  • Loading branch information
@lennessyy @yuliiiah
3 people authored Mar 26, 2024
1 parent 7d0ab71 commit dd66c09
Show file tree
Hide file tree
Showing 4 changed files with 288 additions and 21 deletions.
29 changes: 29 additions & 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
@@ -0,0 +1,29 @@
---
sidebar_label: "Edge Artifact Build Configurations"
title: "Edge Artifact Build Configurations"
description: "A reference document of the parameters using in the Edge artifact build process. "
icon: ""
sidebar_position: 10
hide_table_of_contents: false
tags: ["edge"]
---

During the EdgeForge process, you provide an **.arg** document that contains a list of parameters to configure the build
of both the provider images and the Edge Installer ISO. This page lists the parameters available in the **.arg** file.

| **Argument** | **Description** | **Allowed Values** |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
| `ARCH` | Architecture of the image. | `amd64`, `arm64`. |
| `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. |
| `FIPS_ENABLED` | Whether to generate FIPS compliant binaries. | `true`, `false.` |
| `HTTP_PROXY` | URL of the HTTP Proxy server. | URL string. |
| `HTTPS_PROXY` | URL of the HTTPS Proxy server. | URL string. |
| `IMAGE_REGISTRY` | The image registry to use for tagging the generated provider images. | Your image registry hostname, without `http` or `https` <br /> Example: docker.io/spectrocloud. |
| `IMAGE_REPO` | The image repository to use for tagging the generated provider images. | Your image repository name. |
| `ISO_NAME` | Name of the Installer ISO file. | Lowercase alphanumeric string without spaces. The characters `-` and `_` are allowed. |
| `K8S_DISTRIBUTION` | Kubernetes distribution. | ` k3s`, `rke2`, `kubeadm`, `kubeadm-fips`. |
| `NO_PROXY` | URLS that should be excluded from the proxy. | Comma-separated URL string. |
| `OS_DISTRIBUTION` | OS distribution. | `ubuntu`, `opensuse-leap`, `rhel`. |
| `OS_VERSION` | OS version. This applies to Ubuntu only. | `20`, `22`. |
| `PROXY_CERT_PATH` | Absolute path of the SSL Proxy certificate in the PEM format. | Absolute path string. |
| `UPDATE_KERNEL` | Determines whether to upgrade the Kernel version to the latest from the upstream OS provider. | `true`, `false`. |
20 changes: 2 additions & 18 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 @@ -94,24 +94,8 @@ Use the following instructions to build the Edge Installer ISO. The optional ste

5. Review the **.arg.template** file to view a template of all the arguments that are used during the build process.
Since the process to build provider images uses the same **.arg** file, some of the arguments in the template are
related to the provider images. The following is a table of all the arguments in that can be used in the file:

| **Argument** | **Description** | **Default Value** | **Allowed Values** |
| ------------------ | -------------------------------------------------------------------------------------------- | ---------------------- | ---------------------------------------------------------------------------------------------- |
| `CUSTOM_TAG` | Tag for the provider images | demo | Lowercase alphanumeric string without spaces. |
| `IMAGE_REGISTRY` | Image registry name | ttl.sh | Your image registry hostname, without `http` or `https` <br /> Example: docker.io/spectrocloud |
| `OS_DISTRIBUTION` | OS Distribution | ubuntu | ubuntu, opensuse-leap |
| `IMAGE_REPO` | Image repository name.<br /> It is the same as the OS distribution. | `$OS_DISTRIBUTION` | Your image repository name. |
| `OS_VERSION` | OS version, only applies to Ubuntu | 22 | 20, 22 |
| `K8S_DISTRIBUTION` | Kubernetes Distribution | k3s | k3s, rke2, kubeadm |
| `ISO_NAME` | Name of the Installer ISO | palette-edge-installer | Lowercase alphanumeric string without spaces. The characters `-` and `_` are allowed. |
| `ARCH` | Architecture of the image. | `amd64` | `amd64`, `arm64` |
| `FIPS_ENABLED` | to generate FIPS compliant binaries `true`or`false` | `false` | `true`, `false` |
| `HTTP_PROXY` | URL of the HTTP Proxy server. | `""` | URL string |
| `HTTPS_PROXY` | URL of the HTTPS Proxy server. | `""` | URL string |
| `NO_PROXY` | URLS that should be excluded from the proxy. | `""` | Comma separated URL string |
| `PROXY_CERT_PATH` | Absolute path of the SSL Proxy certificate in PEM format. | `""` | Absolute path string |
| `UPDATE_KERNEL` | Determines whether to upgrade the Kernel version to the latest from the upstream OS provider | `false` | `true`, `false` |
related to the provider images. Refer to [Edge Artifact Build Configuration](./arg.md) for all available
configuration parameters.

6. Customize these arguments to use during the build process. The following is an example **.arg** file.

Expand Down
253 changes: 253 additions & 0 deletions docs/docs-content/clusters/edge/edgeforge-workflow/palette-canvos/fips.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,253 @@
---
sidebar_label: "Build FIPS-Compliant Edge Artifacts"
title: "Build FIPS-Compliant Edge Artifacts"
description: "Learn how to build Edge Installer ISO and provider images to install FIPS-compliant Palette Edge."
icon: ""
hide_table_of_contents: false
sidebar_position: 30
tags: ["edge"]
---

Palette Edge supports
[Federal Information Processing Standards](https://www.nist.gov/standardsgov/compliance-faqs-federal-information-processing-standards-fips)
(FIPS)-compliant Edge clusters. To deploy a FIPS-compliant Edge cluster, you need to build FIPS-enabled Edge artifacts.
Both the Edge Installer ISO and the provider images must be FIPS-compliant.

This page guides you through the process of building FIPS-compliant Edge Installer ISO and provider images.

## Prerequisites

- 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.

```bash
uname -m
```

- Minimum hardware configuration of the Linux machine:

- 4 CPU
- 8 GB memory
- 50 GB storage

- Depending on the Operating System (OS) you want to use on your Edge host, you will need the following subscription
credentials:

- Red Hat Enterprise Linux (RHEL): RHEL subscription token.
- Ubuntu Pro: Ubuntu Pro subscription token.

Contact your system administrator for access to the subscription credentials.

- [Git](https://cli.github.com/manual/installation). 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.

- A [VerteX](/docs/docs-content/vertex/vertex.md) account. Refer to
[Palette VerteX](/docs/docs-content/vertex/vertex.md#access-palette-vertex) for information on how to set up a VerteX
account.

- VerteX registration token for pairing Edge hosts with VerteX. You will need tenant admin access to VerteX to generate
a new registration token. For detailed instructions, refer to the
[Create Registration Token](/clusters/edge/site-deployment/site-installation/create-registration-token) guide.

## Build FIPS-Enabled Edge Artifacts

### Clone CanvOS Repository

1. Clone the [CanvOS](https://github.com/spectrocloud/CanvOS) GitHub repository containing the starter code.

```bash
git clone https://github.com/spectrocloud/CanvOS.git
```

2. Change to the **CanvOS/** directory.

```bash
cd CanvOS
```

3. Ensure that you are using the **main** branch of the repository.

```bash
git tag
```

### Build FIPS-Compliant Base OS Image

Before you can build the Edge Installer ISO or the provider images, you need to build a FIPS-compliant OS base image
with the Kairos framework. This base image is then used to build the final Edge artifacts.

Palette supports the RHEL and Ubuntu for FIPS-compliant base OS images. Choose the OS that you want to build the base
image with.

<Tabs>

<TabItem label="Red Hat Enterprise Linux" value="rhel">

5. Change into the **rhel-fips** directory.

6. In the file **Dockerfile**, provide your RHEL subscription username and password.

```text
ARG [email protected]
ARG PASSWORD=***********
```

7. Issue the following command to start building the provider images.

```shell
bash build.sh
```

:::info

If you experience issues with the script not recognizing the RHEL credentials, try searching **Dockerfile** for the
following line and replacing the credentials directly:

```dockerfile
RUN rm /etc/rhsm-host && subscription-manager register --username 'your-username' --password '*******' \
```

:::

8. When the build finishes, issue `docker images` and confirm there is an image named `rhel-byoi-fips:latest`. This is
the base image that you will use to build provider images and the Edge installer ISO later on.

9. Tag the image with a repository that is accessible by your Linux machine. For example, the following command uses the
publicly accessible `ttl.sh` repository.

```shell
docker tag rhel-byoi-fips:latest ttl.sh/rhel/rhel-byoi-fips:latest
```

10. Push the image to the repository.

```shell
docker push ttl.sh/rhel/rhel-byoi-fips:latest
```

</TabItem>

<TabItem label="Ubuntu" value="ubuntu">

5. Change into the **ubuntu-fips** directory.

6. In the file **pro-attach-config.yaml**, provide your Ubuntu Pro subscription token.

```yaml
token: *******
```

7. Issue the following command to start building the provider images.

```shell
bash build.sh
```

8. When the build finishes, issue `docker images` and confirm there is an image named `ubuntu-focal-fips:latest`. This
is the base image that you will use to build provider images and the Edge installer ISO later on.

9. Tag the image with a repository that is accessible by your Linux machine. For example, use the publicly accessible
`ttl.sh` repository.

```shell
docker tag ubuntu-focal-fips:latest ttl.sh/ubuntu/ubuntu-focal-fips:latest
```

10. Push the image to the repository.

```shell
docker push ttl.sh/ubuntu/ubuntu-focal-fips:latest
```

</TabItem>

</Tabs>

### Build Edge Installer ISO

11. Return to the **CanvOS** directory.

```shell
cd ..
```

12. Create a file named **.arg**. This file will contain parameters that customize the Edge Installer ISO build.

13. In the **.arg** file, provide the following required information. Refer to
[Edge Artifact Build Configuration](arg.md) for more information.

| Argument | Description |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| IMAGE_REGISTRY | The image registry to use for tagging the generated provider images. |
| OS_DISTRIBUTION | The OS distribution in your provider image. |
| IMAGE_REPO | The image repository to use for tagging the generated provider images. |
| OS_VERSION | The OS version in your provider image. This applies to Ubuntu only. |
| K8S_DISTRIBUTION | The Kubernetes distribution for your provider image. Allowed values are `rke2` (RKE2) and `kubeadm-fips` (PXK-E). The other distributions are not FIPS-compliant. |
| FIPS_ENABLED | Whether to enable FIPS compliance. This parameter must be set to `true`. |
| ARCH | The architecture of the image. Allowed values are `amd64` and `arm64`. |
| BASE_IMAGE | The base image used by EdgeForge to build the Edge Installer and provider images. This must be the same image that you build in the previous step. |
| ISO_NAME | The file name of the ISO file that will be generated. |

14. Create a file named **user-data**. Add the following blocks to the root level of the **user-data** file. Replace the
value for `edgeHostToken` with your VerteX registration token, and replace the value `paletteEndPoint` with the URL
of your VerteX instance.

```yaml
install:
grub_options:
extra_cmdline: "fips=1"
stylus:
site:
edgeHostToken: ********
paletteEndpoint: https://vertex.palette-devx.spectrocloud.com
```

15. Add further customization to the **user-data** file as needed. This file configures the Edge Installer. Refer to
[Installer Reference](../../edge-configuration/installer-reference.md) for more information.

16. Issue the following command to build the Edge Installer ISO.

```shell
./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.

### Build Provider Images

Provider images are Kairos-based container images for a supported OS and Kubernetes distribution combination.
FIPS-complaint provider images are built on top of the base OS image you have built previously.

17. Locate **Earthfile** in the CanvOS directory. In the file, find the block that starts with
`build-provider-images-fips:` and delete the Kubernetes versions that you do not want. This will speed up the build
process and save storage space.

18. Review the **.arg** file again to ensure the parameters are correct. Issue the following command to build the
provider images.

```shell
./earthly +build-provider-images-fips
```

:::warning

For the Kubernetes distribution set in your **.arg** file, only `rke2` and `kubeadm-fips` will produce
FIPS-compliant provider images.

:::

## Validate

1. Follow the [Site Installation](../../site-deployment/stage.md) guide to install the Palette Edge on your Edge host.

2. Issue the following command and ensure that the output is `1`. This means the OS is FIPS enabled.

```shell
cat /proc/sys/crypto/fips_enabled
```
7 changes: 4 additions & 3 deletions vale/styles/config/vocabularies/Internal/accept.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,8 +30,6 @@ kubeadm
upsize
Alertmanager
alertmanager
application
Application
grafana
Grafana
etcd
Expand Down Expand Up @@ -203,5 +201,8 @@ Palette eXtented Kubernetes
Palette eXtented Kubernetes - Edge
timeframe
Luet
rhel
Ubuntu
RHEL
repave
airgap
airgap

0 comments on commit dd66c09

Please sign in to comment.