diff --git a/docs/docs-content/registries-and-packs/registries/oci-registry/add-pack-oci/add-pack-oci-basic.md b/docs/docs-content/registries-and-packs/registries/oci-registry/add-pack-oci/add-pack-oci-basic.md new file mode 100644 index 0000000000..6fd9a64a02 --- /dev/null +++ b/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= + ``` + +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](../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. diff --git a/docs/docs-content/registries-and-packs/registries/oci-registry/add-pack-oci/add-pack-oci-ecr.md b/docs/docs-content/registries-and-packs/registries/oci-registry/add-pack-oci/add-pack-oci-ecr.md new file mode 100644 index 0000000000..1541b923f3 --- /dev/null +++ b/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= + 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](../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. diff --git a/docs/docs-content/registries-and-packs/registries/oci-registry/add-pack-oci/add-pack-oci.md b/docs/docs-content/registries-and-packs/registries/oci-registry/add-pack-oci/add-pack-oci.md new file mode 100644 index 0000000000..374ea4d96b --- /dev/null +++ b/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) diff --git a/vale/styles/config/vocabularies/Internal/accept.txt b/vale/styles/config/vocabularies/Internal/accept.txt index af77f45111..b1ea286cc2 100644 --- a/vale/styles/config/vocabularies/Internal/accept.txt +++ b/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 \ 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