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 <[email protected]>

* 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 <[email protected]>

* docs: apply more suggestions

* docs: add an intro page, apply more suggestions

---------

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

docs/docs-content/registries-and-packs/registries/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: 60
+---
+
+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=<your-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=<your-harbor-project-name>
+   export NAME=<your-pack-name>
+   export VERSION=<your-pack-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 `<your_pack_folder_name>` with the name of the folder containing
+   the pack files.
+
+   ```bash
+   tar -czvf $NAME-$VERSION.tar.gz <your-pack-folder-name>
+   ```
+
+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](../add-oci-packs.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.

docs/docs-content/registries-and-packs/registries/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: 70
+---
+
+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=<your-access-key-id>
+   export AWS_SECRET_ACCESS_KEY=<your-secret-access-key>
+   export AWS_DEFAULT_REGION=<your-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=<your-repository-name>
+   export NAME=<your-pack-name>
+   export VERSION=<your-pack-version>
+   export ACCOUNT_ID=<your-aws-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 `<your_pack_folder_name>` with the name of the folder containing
+   the pack files.
+
+   ```bash
+   tar -czvf $NAME-$VERSION.tar.gz <your_pack_folder_name>
+   ```
+
+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](../add-oci-packs.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.

docs/docs-content/registries-and-packs/registries/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: 60
+---
+
+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)

vale/styles/config/vocabularies/Internal/accept.txt

@@ -194,6 +194,7 @@ vApp
 PCGs
 vCPU
 vCPUs
+ORAS
 preload
 preloaded
 eXtented
@@ -205,4 +206,4 @@ rhel
 Ubuntu
 RHEL
 repave
-airgap
+airgap

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})+
+    - wc([\s ]{1,}[-][a-zA-Z]{1,3})+
+    - tar([\s ]{1,}[-][a-zA-Z]{1,3})+