Add OCI Helm Registry

You can add Open Container Initiative (OCI) registries containing Helm charts to Palette and use those Helm charts in your cluster profiles.

Limitations

• Anonymous authentication is not supported for GitHub Container Registry (GHCR).

Prerequisites

Certain prerequisites apply to all OCI Helm registries, while others are specific to Amazon Elastic Container Registry (ECR) or GHCR.

Basic

• Tenant admin access to Palette.

• Credentials to access the OCI registry.

• If your OCI registry uses 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.

• If you are using Azure Container Registry (ACR), Azure recommends using a service principal for automated pull access. The service principal must have at least the AcrPull role or the Container Registry Repository Reader role, depending on the registry's role assignment permissions mode. Refer to the Azure Container Registry Entra permissions and role assignments overview for further details. Use the service principal's Application (client) ID as the registry Username and its client secret Value as the registry Password when configuring the registry in Palette.

Amazon ECR

• Tenant admin access to Palette.

• AWS credentials to an Identity Access Management (IAM) user or a trust relationship to an IAM role so that Palette can access the registry.

• Ensure you have the following IAM permissions attached to the IAM user or IAM role that Palette will use to access the registry. You can reduce the Resource scope from * to the specific Amazon Resource Name (ARN) of the ECR you are using.

  {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Sid": "VisualEditor0",
        "Effect": "Allow",
        "Action": [
          "ecr-public:DescribeRegistries",
          "ecr:DescribeImageReplicationStatus",
          "ecr:ListTagsForResource",
          "ecr:ListImages",
          "ecr:DescribeRepositories",
          "ecr:BatchCheckLayerAvailability",
          "ecr:GetLifecyclePolicy",
          "ecr-public:DescribeImageTags",
          "ecr-public:DescribeImages",
          "ecr:GetRegistryPolicy",
          "ecr-public:GetAuthorizationToken",
          "ecr:DescribeImageScanFindings",
          "ecr:GetLifecyclePolicyPreview",
          "ecr:GetDownloadUrlForLayer",
          "ecr-public:GetRepositoryCatalogData",
          "ecr:DescribeRegistry",
          "ecr:GetAuthorizationToken",
          "ecr-public:GetRepositoryPolicy",
          "ecr-public:DescribeRepositories",
          "ecr:BatchGetImage",
          "ecr:DescribeImages",
          "ecr-public:GetRegistryCatalogData",
          "ecr-public:ListTagsForResource",
          "ecr-public:BatchCheckLayerAvailability",
          "ecr:GetRepositoryPolicy"
        ],
        "Resource": "*"
      }
    ]
  }

• If your Palette or Palette VerteX instance is installed in an airgapped environment or an environment with limited internet access, you must whitelist the S3 endpoint that corresponds to the region of your Amazon ECR. This is because image layers are stored in S3, not the registry. The S3 endpoint uses the following format. Replace <region> with the region your ECR is hosted in.

  prod-<region>-starport-layer-bucket.s3.<region>.amazonaws.com
  Example S3 endpoint

  prod-us-east-1-starport-layer-bucket.s3.us-east-1.amazonaws.com

GHCR

• Tenant admin access to Palette.

• A GitHub account (user or organization) and a classic Personal Access Token (PAT) that has the appropriate OAuth scope for GHCR. Fine-grained tokens are not supported. Refer to Working with the Container registry for additional information.

• Helm charts (packages) uploaded to GHCR must be linked to a repository in order to be indexed by Palette.

Add OCI Helm Registry

Use the following steps to add an OCI Helm registry to Palette. Select the tab that corresponds to the type of OCI registry you are adding.

info

When synchronization is enabled, the Base Content Path field is required. Palette syncs only the Helm charts stored directly in the directories you specify. Charts stored at the registry root, in the parent directory of the specified path, or in child directories nested below it are not synced. To sync Helm charts from multiple locations, add each directory as a separate base content path.

Basic

1. Log in to Palette as a Tenant administrator.

2. From the left main menu, select Tenant Settings.

3. From the Tenant Settings Menu, select Registries.

4. On the OCI Registries tab, select Add New OCI Registry.

5. Enter the Name of the registry. For the Provider type, select Helm.

6. For OCI Authentication Type, select Basic.

7. Toggle the Synchronization option to enable or disable synchronization for the registry. For more information, refer to the Helm Registry - Synchronization Behavior section.

8. Provide the registry URL in the Endpoint field.

9. If Synchronization is enabled and your registry requires a suffix to be appended to the endpoint, specify it in the Endpoint Suffix field. This field is optional and applies to registries that do not use a standard Docker V2 API path. For example, JFrog Artifactory requires the API path and the repository key, such as artifactory/api/docker/spectro-charts-repo.

10. If Synchronization is enabled, in the Base Content Path field, enter the base path to the repository in the registry where the Helm charts are stored. You can specify multiple base paths by pressing the ENTER key after each path. Providing multiple base paths is useful when Helm charts are stored in different directories or projects.

11. Fill out the Username and Password fields with the credentials to access the registry. If the registry does not require authentication, leave the Username and Password fields empty.

    tip

    If you are using ACR, use the service principal App ID as the Username and its client secret as the Password.

12. If your OCI registry server is using a self-signed certificate, select Upload file to upload the certificate. If the server certificate is not signed by a trusted CA, select Insecure Skip TLS Verify to skip verifying the x509 certificate.

13. Select Confirm to add the registry.

Amazon ECR

1. Log in to Palette as a Tenant administrator.

2. From the left main menu, select Tenant Settings.

3. From the Tenant Settings Menu, select Registries.

4. On the OCI Registries tab, select Add New OCI Registry.

5. Enter the Name of the registry. For the Provider type, select Helm.

6. For OCI Authentication Type, select ECR.

7. Toggle the Synchronization option to enable or disable synchronization for the registry. For more information, refer to the Helm Registry - Synchronization Behavior section.

8. Provide the registry URL in the Endpoint field. Exclude the https:// prefix.

9. If Synchronization is enabled, in the Base Content Path field, enter the base path to the repository in the registry where the Helm charts are stored. You can specify multiple base paths by pressing the ENTER key after each path. Providing multiple base paths is useful when Helm charts are stored in different directories or projects.

10. If you are using a private ECR, toggle the Enable Authentication option to expose the AWS authentication method fields. Choose Credentials if you want to provide the static AWS credentials for an IAM user. Choose STS if you want Palette to assume an IAM role that has access to the ECR through the Security Token Service (STS). Refer to the table below to learn more about each credential type.

    Authentication Method	Field	Description
    Credentials	Access key	The access key ID of the IAM user.
    Credentials	Secret access key	The secret access key of the IAM user.
    STS	ARN	The Amazon Resource Name (ARN) of the IAM role to assume. Refer to the instructions exposed in the side-drawer to the right of the input field to review the IAM trust relationship changes you must add to your IAM role.

    warning

    If you selected STS as the authentication method, you must add a trust relationship to the IAM role you are using to access the ECR. Refer to the instructions exposed in the side-drawer to the right of the input field to review the IAM trust relationship changes you must add to your IAM role. Failure to add the trust relationship will result in an error when you attempt to validate the registry.

11. Keep the default TLS Configuration settings. Amazon ECR uses certificates signed by well-known CAs.

12. Select Confirm to add the registry.

GHCR

1. Log in to Palette as a Tenant administrator.

2. From the left main menu, select Tenant Settings.

3. From the Tenant Settings Menu, select Registries.

4. On the OCI Registries tab, select Add New OCI Registry.

5. Enter the Name of the registry. For the Provider type, select Helm.

6. For OCI Authentication Type, select Basic.

7. Enable Synchronization for the registry. Synchronization is required for GHCR. For more information, refer to the Helm Registry - Synchronization Behavior section.

8. In the Endpoint field, enter the appropriate endpoint depending on whether the Helm chart package is owned by an individual user or organization.

   User

   Replace <username> with the GitHub username that owns the package.

   ghcr.io/users/<username>

   Organization

   Replace <organization> with the GitHub name of the organization that owns the package.

   ghcr.io/orgs/<organization>

9. Leave the Endpoint Suffix blank. This field is not applicable to GHCR. Any data entered in this field is ignored.

10. Enter the Base Content Path for the Helm charts you want Palette to index. This is the GitHub repository that the Helm chart is linked to. You can specify multiple base paths by pressing ENTER after each path. Providing multiple base paths is useful when Helm charts are stored in different repositories.

11. In the Username field, enter your GitHub username or organization. A username is required for authentication, but the user or organization does not need to be associated with the repository where the Helm chart is stored.

12. In the Password or Token field, enter the PAT associated with the entered Username.

13. Keep the default TLS Configuration settings. GHCR uses certificates signed by well-known CAs.

14. Select Confirm to add the registry.

Validate

Use the following steps to validate that the OCI registry is added to Palette correctly.

1. Log in to the Palette.

2. From the left main menu, select Profiles > Add Cluster Profile.

3. In the Add a new cluster profile wizard, enter a unique Name for the cluster profile. Choose a Type of Add-on and select Next.

4. On the Profile Layers wizard step, select Add Helm Chart > Public Packs.

5. Verify the Helm chart registry you added is displayed in the Registry drop-down.

Next Steps

Once your registry is added, you can add Helm charts from these registries to full or add-on cluster profiles. Refer to our Add a Helm Chart guide for more information.