From 44de259f00f77b16cbcc87f394f49165095fa6a6 Mon Sep 17 00:00:00 2001 From: caroldelwing Date: Mon, 15 Apr 2024 19:48:32 -0400 Subject: [PATCH] [version-4-0] docs: add guide for uploading packs to oci registries PR 2541 (#2653) * docs: add guide for uploading packs to oci registries (#2541) * docs: add guide for uploading packs to oci registries * docs: move guide to the oci-registry folder * Apply suggestions from code review Co-authored-by: Karl Cardenas * docs: apply suggestions from code review * docs: add more suggestions from review * docs: create separate guides, remove sub headings * Apply suggestions from code review Co-authored-by: Yuliia Horbenko <31223054+yuliiiah@users.noreply.github.com> * docs: apply more suggestions * docs: add an intro page, apply more suggestions --------- Co-authored-by: Karl Cardenas Co-authored-by: Yuliia Horbenko <31223054+yuliiiah@users.noreply.github.com> * docs: reorganize folders * docs: fix broken link --------- Co-authored-by: Karl Cardenas Co-authored-by: Yuliia Horbenko <31223054+yuliiiah@users.noreply.github.com> --- .../edge/site-deployment/model-profile.md | 2 +- .../devx/manage-dev-engine/registries.md | 2 +- .../registries-and-packs/deploy-pack.md | 2 +- .../oci-registry/_category_.json | 3 + .../add-pack-oci/add-pack-oci-basic.md | 161 +++++++++++++++++ .../add-pack-oci/add-pack-oci-ecr.md | 162 ++++++++++++++++++ .../oci-registry/add-pack-oci/add-pack-oci.md | 24 +++ .../{ => oci-registry}/oci-registry.md | 2 +- .../spectro-cli-reference.md | 4 +- .../config/vocabularies/Internal/accept.txt | 13 ++ vale/styles/spectrocloud/longform.yml | 3 +- 11 files changed, 371 insertions(+), 7 deletions(-) create mode 100644 docs/docs-content/registries-and-packs/oci-registry/_category_.json create mode 100644 docs/docs-content/registries-and-packs/oci-registry/add-pack-oci/add-pack-oci-basic.md create mode 100644 docs/docs-content/registries-and-packs/oci-registry/add-pack-oci/add-pack-oci-ecr.md create mode 100644 docs/docs-content/registries-and-packs/oci-registry/add-pack-oci/add-pack-oci.md rename docs/docs-content/registries-and-packs/{ => oci-registry}/oci-registry.md (99%) diff --git a/docs/docs-content/clusters/edge/site-deployment/model-profile.md b/docs/docs-content/clusters/edge/site-deployment/model-profile.md index c099624187..f435529a99 100644 --- a/docs/docs-content/clusters/edge/site-deployment/model-profile.md +++ b/docs/docs-content/clusters/edge/site-deployment/model-profile.md @@ -169,7 +169,7 @@ capabilities. If you need remote access to the cluster, consider adding the Optionally, add additional Helm or OCI registries and include applications hosted in those registries in add-on profiles. Check out the guide for adding a [Helm](../../../registries-and-packs/helm-charts.md) or -[OCI](../../../registries-and-packs/oci-registry.md) registry to learn more. +[OCI](../../../registries-and-packs/oci-registry/oci-registry.md) registry to learn more. ### Validate diff --git a/docs/docs-content/devx/manage-dev-engine/registries.md b/docs/docs-content/devx/manage-dev-engine/registries.md index 1c090b918e..7971bd65b8 100644 --- a/docs/docs-content/devx/manage-dev-engine/registries.md +++ b/docs/docs-content/devx/manage-dev-engine/registries.md @@ -28,4 +28,4 @@ Palette Dev Engine supports the following types of custom registries: - [Helm Registry](../../registries-and-packs/helm-charts.md) -- [OCI Registry](../../registries-and-packs/oci-registry.md) +- [OCI Registry](../../registries-and-packs/oci-registry/oci-registry.md) diff --git a/docs/docs-content/registries-and-packs/deploy-pack.md b/docs/docs-content/registries-and-packs/deploy-pack.md index bbc0ab3f2e..64deb9d0ca 100644 --- a/docs/docs-content/registries-and-packs/deploy-pack.md +++ b/docs/docs-content/registries-and-packs/deploy-pack.md @@ -1335,4 +1335,4 @@ To learn more about packs in Palette, we encourage you to check out the referenc - [Pack Constraints](pack-constraints.md) -- [Spectro Cloud OCI Registry](oci-registry.md) +- [Spectro Cloud OCI Registry](./oci-registry/oci-registry.md) diff --git a/docs/docs-content/registries-and-packs/oci-registry/_category_.json b/docs/docs-content/registries-and-packs/oci-registry/_category_.json new file mode 100644 index 0000000000..0b49ba8465 --- /dev/null +++ b/docs/docs-content/registries-and-packs/oci-registry/_category_.json @@ -0,0 +1,3 @@ +{ + "position": 70 +} diff --git a/docs/docs-content/registries-and-packs/oci-registry/add-pack-oci/add-pack-oci-basic.md b/docs/docs-content/registries-and-packs/oci-registry/add-pack-oci/add-pack-oci-basic.md new file mode 100644 index 0000000000..07b566b1dc --- /dev/null +++ b/docs/docs-content/registries-and-packs/oci-registry/add-pack-oci/add-pack-oci-basic.md @@ -0,0 +1,161 @@ +--- +sidebar_label: "Add a Pack to a Basic OCI Registry" +title: "Add a Pack to a Basic OCI Registry" +description: "Learn how to upload packs to a Basic OCI registry." +icon: "" +hide_table_of_contents: false +sidebar_position: 10 +--- + +This guide explains how to upload packs to an OCI registry that supports basic authentication. You will learn how to +authenticate to your Basic OCI registry, push a custom pack, and configure the registry in Palette. + +## Prerequisites + +- Tenant administrator access. + +- Custom pack files available on your computer. Refer to the [Add an Add-on Pack](../../adding-add-on-packs.md) guide to + learn how to create a custom pack. + +- A private OCI registry that supports basic authentication. This guide uses [Harbor](https://goharbor.io/) as an + example. Learn how to set up a Harbor registry server using the + [Harbor Installation and Configuration](https://goharbor.io/docs/2.9.0/install-config/) guide. + +- [ORAS](https://oras.land/docs/installation/) v1.0.0 installed and available. + + :::warning + + This specific version of ORAS is explicitly required for pushing packs to OCI registries. + + ::: + +- [Tar](https://www.gnu.org/software/tar/) installed and available. + +- If your OCI registry is using a self-signed certificate or a certificate that is not signed by a trusted Certificate + Authority (CA), you will need the certificate to add the registry to Palette. + +## Upload Pack to a Basic OCI Registry + +Palette supports all OCI-compliant registries that use basic authentication. This guide uses a +[Harbor](https://goharbor.io/) registry as an example. Follow the steps described below to set up your Harbor registry, +push the pack, and configure the registry in Palette. + +1. Access the Harbor registry server domain on your web browser and log in using your credentials. + + :::tip + + If you have kept the default credentials, the username and password are **admin** and **Harbor12345**, respectively. + + ::: + +2. In the **Projects** section, click **New Project**. A project in Harbor contains all repositories of an application. + +3. Give your project a name and keep the default settings for the remaining configuration. Click **OK** to proceed. + +4. In your terminal, export the `HARBOR_ADDRESS` variable, which will store your Harbor server hostname. Do not include + the "https://" prefix. For example, `harbor.yourdomain.com`. + + ```bash + export HARBOR_ADDRESS= + ``` + +5. Issue the command `oras login` to log in to your Harbor registry. When prompted, enter your username and password. + + ```bash + oras login $HARBOR_ADDRESS + ``` + + If the login is successful, you will receive a confirmation message. + + ```text hideClipboard + Login Succeeded + ``` + +6. Next, export the variables required for creating the Harbor repository and pushing the pack. + + - `HARBOR_PROJECT` - Specify a name for the Harbor project that will store the repositories and the pack files. For + example, `spectro-oci-registry`. + - `NAME` - The pack's name, which must match the `name` parameter in the **pack.json** file. + - `VERSION` - The pack's version, which must match the `version` parameter in the **pack.json** file. + + ```bash + export HARBOR_PROJECT= + export NAME= + export VERSION= + ``` + +7. Navigate to the directory containing the folder with the pack files. + +8. Before pushing the pack to the registry, compress the contents of the pack folder into an archive file. Issue the + command below to create the archive file. Replace `` with the name of the folder containing + the pack files. + + ```bash + tar -czvf $NAME-$VERSION.tar.gz + ``` + +9. Create a base path repository to store your pack repositories. Note that Harbor creates a repository when the user + pushes an artifact to a project. + + ```bash + oras push $HARBOR_ADDRESS/$HARBOR_PROJECT/spectro-packs/archive + ``` + + The command output is similar to the following. + + ```text hideClipboard + Uploading empty artifact + Pushed [registry] harbor.yourdomain.com/spectro-oci-registry/spectro-packs/archive + Digest: sha256:93239180c18b0b6fa99b1f0463853165bdf9fc9c6a69eff3d7545f9852b6c86e + ``` + +10. Now, proceed to create the pack repository and push your pack to the Harbor registry. + + ```bash + oras push $HARBOR_ADDRESS/$HARBOR_PROJECT/spectro-packs/archive/$NAME:$VERSION $NAME-$VERSION.tar.gz + ``` + + The command output is similar to the following. + + ```text hideClipboard + Uploading ba65d21e72f1 your-pack-name-1.0.0.tar.gz + Uploaded ba65d21e72f1 your-pack-name-1.0.0.tar.gz + Pushed [registry] harbor.yourdomain.com/spectro-oci-registry/spectro-packs/archive/your-pack-name:1.0.0 + Digest: sha256:448bc5d5ba0675dfc1906f442c5f0f294e21b85b62cea1ede789ba039c7b3f80 + ``` + +:::warning + +Make sure to include the **spectro-packs/archive** path in _all_ your repositories. Palette expects this namespace in +custom OCI registries. + +::: + +11. After pushing the pack to the Harbor registry, follow the steps in [Add OCI Packs Registry](../oci-registry.md) to + add your Harbor registry to Palette. + + :::info + + Palette automatically synchronizes the registries. However, you can manually trigger the synchronization if needed. + From the **OCI Registries** page, click the **three-dot Menu** next to the registry name you added and select + **Sync**. + + ::: + +## Validate + +Follow the steps below to validate that your pack has been successfully pushed to your OCI registry. + +1. Log in to [Palette](https://console.spectrocloud.com). + +2. From the left **Main Menu**, click on **Profiles**. + +3. Click **Add Cluster Profile**. + +4. Provide a name and select the type **Add-on**. + +5. In the following screen, click **Add Pack**. + +6. Select the Basic OCI registry you added in the **Registry drop-down Menu**. + +7. Verify the pack you uploaded to the Harbor registry is displayed. diff --git a/docs/docs-content/registries-and-packs/oci-registry/add-pack-oci/add-pack-oci-ecr.md b/docs/docs-content/registries-and-packs/oci-registry/add-pack-oci/add-pack-oci-ecr.md new file mode 100644 index 0000000000..2c76a6f9fb --- /dev/null +++ b/docs/docs-content/registries-and-packs/oci-registry/add-pack-oci/add-pack-oci-ecr.md @@ -0,0 +1,162 @@ +--- +sidebar_label: "Add a Pack to an ECR Registry" +title: "Add a Pack to an ECR Registry" +description: "Learn how to upload packs to an ECR registry." +icon: "" +hide_table_of_contents: false +sidebar_position: 20 +--- + +This guide explains how to upload packs to the [AWS Elastic Container Registry (ECR)](https://aws.amazon.com/ecr/). You +will learn how to authenticate to your AWS ECR registry, push a custom pack, and configure the registry in Palette. + +## Prerequisites + +- Tenant administrator access. + +- Custom pack files available on your computer. Refer to the [Add an Add-on Pack](../../adding-add-on-packs.md) guide to + learn how to create a custom pack. + +- A private [AWS (ECR)](https://docs.aws.amazon.com/AmazonECR/latest/userguide/Registries.html) registry. Each AWS + account is provided with a default private ECR registry. + +- An Identity and Access Management (IAM) user with the following permissions. + + - `ecr:CreateRepository` + - `ecr:InitiateLayerUpload` + - `ecr:CompleteLayerUpload` + - `ecr:InitiateLayerUpload` + - `ecr:PutImage` + - `ecr:UploadLayerPart` + - `ecr:BatchCheckLayerAvailability` + - `ecr:ListImages` + - `ecr:DescribeImages` + - `ecr:BatchDeleteImage` + - `ecr:DeleteRepository` + +- The following software installed on your computer. + + - [ORAS](https://oras.land/docs/installation/) v1.0.0 + + :::warning + + This specific version of ORAS is explicitly required for pushing packs to OCI registries. + + ::: + + - [Tar](https://www.gnu.org/software/tar/) + - [AWS CLI v2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) + +## Upload Pack to an ECR Registry + +Follow the steps described below to set up your ECR registry, push the pack, and configure the registry in Palette. + +1. Open up a terminal session and export your AWS credentials as environment variables to authenticate with your AWS + account. + + ```bash + export AWS_ACCESS_KEY_ID= + export AWS_SECRET_ACCESS_KEY= + export AWS_DEFAULT_REGION= + ``` + +2. Additionally, export the required variables for creating the ECR repository and pushing the pack. + + - `REPOSITORY_NAME` - Specify a name for the repository that will store the pack files. For example, + `spectro-oci-registry`. + - `NAME` - The pack's name, which must match the `name` parameter in the **pack.json** file. + - `VERSION` - The pack's version, which must match the `version` parameter in the **pack.json** file. + - `ACCOUNT_ID` - Your AWS account ID, containing only numerical digits and no dashes. + + ```bash + export REPOSITORY_NAME= + export NAME= + export VERSION= + export ACCOUNT_ID= + ``` + +3. Issue the command below to create a base path repository to store your pack repositories. + + ```bash + aws ecr create-repository --repository-name $REPOSITORY_NAME/spectro-packs/archive --region $AWS_DEFAULT_REGION + ``` + +4. Next, proceed to create the repository to store your pack. + + ```bash + aws ecr create-repository --repository-name $REPOSITORY_NAME/spectro-packs/archive/$NAME --region $AWS_DEFAULT_REGION + ``` + +:::warning + +Make sure to include the **spectro-packs/archive** path in _all_ your repositories. Palette expects this namespace in +custom OCI registries. + +::: + +5. After creating the ECR repositories, issue the command below to authenticate to your ECR registry. The + `aws ecr get-login-password` generates an authorization token, which is then passed to the `oras login` command. + + ```bash + aws ecr get-login-password --region $AWS_DEFAULT_REGION | oras login --username AWS --password-stdin $ACCOUNT_ID.dkr.ecr.$AWS_DEFAULT_REGION.amazonaws.com + ``` + + If the login is successful, you will receive a confirmation message. + + ```text hideClipboard + Login Succeeded + ``` + +6. Navigate to the directory containing the folder with the pack files. + +7. Before pushing the pack to the ECR registry, compress the contents of the pack folder into an archive file. Issue the + command below to create the archive file. Replace `` with the name of the folder containing + the pack files. + + ```bash + tar -czvf $NAME-$VERSION.tar.gz + ``` + +8. Push the pack to the ECR registry. + + ```bash + oras push $ACCOUNT_ID.dkr.ecr.$AWS_DEFAULT_REGION.amazonaws.com/$REPOSITORY_NAME/spectro-packs/archive/$NAME:$VERSION $NAME-$VERSION.tar.gz + ``` + + The command output is similar to the following. + + ```text hideClipboard + Uploading ba65d21e72f1 your-pack-name-1.0.0.tar.gz + Uploaded ba65d21e72f1 your-pack-name-1.0.0.tar.gz + Pushed [registry] 123456789.dkr.ecr.us-east-1.amazonaws.com/spectro-packs-oci/spectro-packs/archive/your-pack-name:1.0.0 + Digest: sha256:9067f964301c2b8e7a702fdbee35f5ca20a46695ef121e760e38967a2dd7cc4f + ``` + +9. After pushing the pack to the ECR registry, follow the steps in [Add OCI Packs Registry](../oci-registry.md) to add + your ECR registry to Palette. + + :::info + + Palette automatically synchronizes the registries. However, you can manually trigger the synchronization if needed. + From the **OCI Registries** page, click the **three-dot Menu** next to the registry name you added and select + **Sync**. + + ::: + +## Validate + +Follow the steps below to validate that your pack has been successfully pushed to your OCI registry. + +1. Log in to [Palette](https://console.spectrocloud.com). + +2. From the left **Main Menu**, click on **Profiles**. + +3. Click **Add Cluster Profile**. + +4. Provide a name and select the type **Add-on**. + +5. In the following screen, click **Add Pack**. + +6. Select the ECR registry you added in the **Registry drop-down Menu**. + +7. Verify the pack you uploaded to the ECR registry is displayed. diff --git a/docs/docs-content/registries-and-packs/oci-registry/add-pack-oci/add-pack-oci.md b/docs/docs-content/registries-and-packs/oci-registry/add-pack-oci/add-pack-oci.md new file mode 100644 index 0000000000..8a9da0aab8 --- /dev/null +++ b/docs/docs-content/registries-and-packs/oci-registry/add-pack-oci/add-pack-oci.md @@ -0,0 +1,24 @@ +--- +sidebar_label: "Add a Pack to an OCI Registry" +title: "Add a Pack to an OCI Registry" +description: "Learn how to upload packs to OCI registries." +icon: "" +hide_table_of_contents: false +sidebar_position: 0 +--- + +Palette supports the use of Open Container Initiative (OCI) registries. You can register a private OCI registry with +Palette, publish custom packs, and then use the packs in your cluster profiles. + +Two types of OCI authentication are available: registries that support basic authentication, such as +[Harbor](https://goharbor.io/), and [AWS Elastic Container Registry (ECR)](https://aws.amazon.com/ecr/), which is +supported as a third-party registry provider. To upload packs to OCI registries, you can use +[ORAS](https://oras.land/docs/), a CLI tool for pushing and pulling OCI artifacts to and from OCI registries. To learn +more about OCI registries and how they work in Palette, refer to the [OCI Registry](../oci-registry.md) page. + +## Resources + +The following pages provide detailed instructions on how to push packs to OCI-compliant registries. + +- [Add a Pack to a Basic OCI Registry](./add-pack-oci-basic.md) +- [Add a Pack to an ECR Registry](./add-pack-oci-ecr.md) diff --git a/docs/docs-content/registries-and-packs/oci-registry.md b/docs/docs-content/registries-and-packs/oci-registry/oci-registry.md similarity index 99% rename from docs/docs-content/registries-and-packs/oci-registry.md rename to docs/docs-content/registries-and-packs/oci-registry/oci-registry.md index 38a7152a1c..bdfbd4d4a1 100644 --- a/docs/docs-content/registries-and-packs/oci-registry.md +++ b/docs/docs-content/registries-and-packs/oci-registry/oci-registry.md @@ -4,7 +4,7 @@ title: "Spectro Cloud OCI Registry" description: "creation and usages of OCI Registry within Spectro Cloud" icon: "" hide_table_of_contents: false -sidebar_position: 70 +sidebar_position: 0 --- Palette supports OCI registries to serve the “filesystem bundle” unpacked on disk as helm registries. Helm charts hosted diff --git a/docs/docs-content/registries-and-packs/spectro-cli-reference.md b/docs/docs-content/registries-and-packs/spectro-cli-reference.md index c08a5706cd..12b34624f6 100644 --- a/docs/docs-content/registries-and-packs/spectro-cli-reference.md +++ b/docs/docs-content/registries-and-packs/spectro-cli-reference.md @@ -12,8 +12,8 @@ or download packs and perform other operations. :::info -We recommend using an OCI registry for storing and maintaining your packs. Refer to the [OCI registry](oci-registry.md) -section for more information. +We recommend using an OCI registry for storing and maintaining your packs. Refer to the +[OCI registry](./oci-registry/oci-registry.md) section for more information. ::: diff --git a/vale/styles/config/vocabularies/Internal/accept.txt b/vale/styles/config/vocabularies/Internal/accept.txt index 85301fa370..4c8fda60ed 100644 --- a/vale/styles/config/vocabularies/Internal/accept.txt +++ b/vale/styles/config/vocabularies/Internal/accept.txt @@ -187,3 +187,16 @@ vApp PCGs vCPU vCPUs +ORAS +preload +preloaded +eXtented +Palette eXtented Kubernetes +Palette eXtented Kubernetes - Edge +timeframe +Luet +rhel +Ubuntu +RHEL +repave +airgap \ No newline at end of file diff --git a/vale/styles/spectrocloud/longform.yml b/vale/styles/spectrocloud/longform.yml index 8d65756064..c0668ef3fe 100644 --- a/vale/styles/spectrocloud/longform.yml +++ b/vale/styles/spectrocloud/longform.yml @@ -22,4 +22,5 @@ exceptions: - chmod([\s ]{1,}[-][a-zA-Z]{1,3})+ - chown([\s ]{1,}[-][a-zA-Z]{1,3})+ - sed([\s ]{1,}[-][a-zA-Z]{1,3})+ - - wc([\s ]{1,}[-][a-zA-Z]{1,3})+ \ No newline at end of file + - wc([\s ]{1,}[-][a-zA-Z]{1,3})+ + - tar([\s ]{1,}[-][a-zA-Z]{1,3})+ \ No newline at end of file