#1151 Add documentation for OCI feature in Apps & Marketplace Section #1171

martyav · 2024-03-12T14:44:59Z

Reminders

See the README for more details on how to work with the Rancher docs.
Verify if changes pertain to other versions of Rancher. If they do, finalize the edits on one version of the page, then apply the edits to the other versions.
If the pull request is dependent on an upcoming release, make sure to target the release branch instead of main.

Description

From the issue:

GitHub Issue - Ability to use an OCI Helm Chart Registry on a Rancher Catalog rancher#29105

UI Issue - Ability to use OCI Helm Chart Registry in Apps&Marketplace dashboard#9815

GitHub PR - [2.9] Add OCI support for Helm Repos rancher#43823

Summary
There is a new feature that is going to be released in the Apps and Marketplace category. That is support for OCI-based Helm repositories.

Acceptance criteria

There are docs covering the functionality of the OCI Helm repository feature in Apps & Marketplace

There are docs covering debugging and logging for any known OCI Helm repository issues

There are docs covering the limitations of the feature.

Comments

martyav · 2024-03-21T15:02:56Z

I'm going to open this up for review, but I'm reluctant to create the release branch yet, as 2.9 is several months from now. Added the DO NOT MERGE label and have to to remember to point this to the 2.9 branch at a more appropriate time.

martyav · 2024-03-21T15:06:14Z

@rohitsakala

I edited most of the draft provided, but the last section needs more instructions.

To view logs, enable the debug option of rancher

The first option if there is any discrepancy is to refresh a cluster repository
The last option is to delete the oci helm repository clusterrepo and readd it. This will not delete any already installed helm charts.

Where in the UI do they go to perform these steps?

Thank you!

martyav · 2024-03-21T15:14:03Z

docs/how-to-guides/new-user-guides/helm-charts-in-rancher/oci-registries.md

+The CRD that is linked to the OCI Helm registry is `ClusterRepo`.
+
+[Screenshot of the ClusterRepo YAML]<!-- Engineers - Can we get this screenshot? Thank you! -->


I left this part in, but it feels like we need a little more content here to explain the relevance of mentioning it in this section vs somewhere else, and what users can use that information for.

martyav · 2024-03-21T15:15:22Z

docs/how-to-guides/new-user-guides/helm-charts-in-rancher/oci-registries.md

+  1. **oci://\<registry-host\>/**: Every chart in the registry becomes available for installation, regardless of namespace or tag.
+  1. **oci://\<registry-host\>/\<namespace\>**: Every chart in the specified namespace within the registry becomes available for installation.
+  1. **oci://\<registry-host\>/\<namespace\>/\<chart-name\>**: Only the specified chart and any associated tags or versions of that chart become available for installation.
+  1. **oci://\<registry-host\>/\<namespace\>/\<chart-name\>:\<tag\>**: Only the chart with the specified tag becomes available for installation.


I opted not to format these as code snippets, so the backslashes are required as escape characters for the angle brackets.

docs/how-to-guides/new-user-guides/helm-charts-in-rancher/oci-registries.md

rohitsakala · 2024-03-25T22:04:25Z

@martyav Thank you for this PR. There has been some modification requested for this feature. So, I complete those modifications and get back to you.

martyav · 2024-04-15T14:08:19Z

@martyav Thank you for this PR. There has been some modification requested for this feature. So, I complete those modifications and get back to you.

@rohitsakala do you have any updates on this?

martyav · 2024-05-06T14:30:31Z

@rohitsakala checking in again, do you have any updates?

rohitsakala · 2024-05-06T15:22:34Z

@martyav Yes, I do have to update the docs. I have sent the PR to product team for playing. Once they have given me the approval, I will update the docs and inform. Maybe in max 2 weeks.

…151-add-documentation-for-oci-feature-in-apps-and-marketplace-section

...oned_docs/version-2.9/how-to-guides/new-user-guides/helm-charts-in-rancher/oci-registries.md

rohitsakala · 2024-06-10T23:21:51Z

...oned_docs/version-2.9/how-to-guides/new-user-guides/helm-charts-in-rancher/oci-registries.md

+
+Rancher supports BasicAuth for OCI registries. You must create a [**BasicAuth** Kubernetes secret](https://kubernetes.io/docs/concepts/configuration/secret/#basic-authentication-secret). You can also [create the secret through the Rancher UI](../kubernetes-resources-setup/secrets.md). 
+
+Rancher 2.9.0 also adds the `spec.insecurePlainHttp` field, which allows insecure connections to OCI registries. When this field is set to `true`, Rancher connects to the OCI endpoint without performing an SSL check. This works exactly the same as how the `spec.insecurePlainHttp` field works in [ORAS CLI](https://oras.land/docs/commands/use_oras_cli), since Rancher uses the ORAS library.


Can you replace this point with this section ?

Do you mean "Explanation of fields"? It seems like we should explain those fields in context with the steps they are related to. "There are more fields that the user can define". Where do these fields appear and how can the user define them? Do they all appear on the same screen where the user sets up authentication?

@martyav These fields appear while creating the OCI-based Helm repository, basically in the same page where the user will be inputting the name, OCI URL etc.

Ok, I added the explanations as part of the step-by-step instructions, in order of where they appear in the UI

...oned_docs/version-2.9/how-to-guides/new-user-guides/helm-charts-in-rancher/oci-registries.md

rohitsakala · 2024-06-10T23:25:28Z

...oned_docs/version-2.9/how-to-guides/new-user-guides/helm-charts-in-rancher/oci-registries.md

+1. Click **Apps > Charts**.
+1. Select the OCI repository from the dropdown.
+
+## Refresh an OCI Registry


Can you add this section as well ?

Rate limiting section added

...oned_docs/version-2.9/how-to-guides/new-user-guides/helm-charts-in-rancher/oci-registries.md

rohitsakala · 2024-06-10T23:27:43Z

...oned_docs/version-2.9/how-to-guides/new-user-guides/helm-charts-in-rancher/oci-registries.md

+
+## Troubleshooting OCI-based Helm Registries <!-- Unedited draft -->
+
+To view logs, enable the debug option of rancher 


To enhance logging information from the operations, enable the debug option while deploying Rancher.

This section has now been edited and the link has been added

...oned_docs/version-2.9/how-to-guides/new-user-guides/helm-charts-in-rancher/oci-registries.md

martyav · 2024-06-11T16:45:19Z

@rohitsakala I made a number of edits addressing suggestions. However, there are still three things unresolved:

The last section needs to describe how to enable the debug option
There are two sentences I wasn't sure how to edit and wrapped in HTML comment tags
The section explaining fields feels like it needs to be revised extensively, so that the fields are mentioned in context with where they can be found or used. Are they all on the Authentic part of the UI?

...oned_docs/version-2.9/how-to-guides/new-user-guides/helm-charts-in-rancher/oci-registries.md

rohitsakala · 2024-06-11T18:37:46Z

...oned_docs/version-2.9/how-to-guides/new-user-guides/helm-charts-in-rancher/oci-registries.md

+
+If you have a OCI-based Helm chart repository which doesn't implement the `Retry-After` header, or which behaves differently than Dockerhub, provide your response values with the `ExponentialBackOff` field. 
+
+For example, if you have an OCI-based Helm chart repository that doesn't send a HTTP header, but you know that it allows 50 requests in 24 hours, you can provide a `MinWait` value of 86400 seconds, a `MaxWait` of 90000 seconds, and a `Maxretry` of `1`. <!-- I'm not sure what these two sentences from the draft mean? --> This would allow adding the Helm repository complete but it would take 24 hours if Rancher gets rate limited. There is no user intervention needed here.<!-- end -->


So let me explain it more clearly here

User adds Dockerhub to the OCI based Helm Repository

Rancher gets ratelimited.

User knows that Dockerhub allows 50 requests in 24 hours of time window.

Rancher doesn't know this information about 50 requests in 24 hours.

But the user knows it through dockerhub documentation

User can enter ExponentailBackOff values as MinWait: 86400 seconds (24 hours), MaxWait : 90000 seconds, MaxRetry: 1

Since the user has entered the values, Rancher when its gets throttled or ratelimited will wait for 24 hours before making a new request. This new request will pass since Dockerhub will renew the 50 requests since 24 hours have been passed.

Now, for 24 hours, the repository will not be in Active state. Only, when the Rancher completes 24 hour waiting and makes a call to get information, it will change to active state.

Let me know at which point it is unclear.

Thanks! Updating and adding to next commit

rohitsakala · 2024-06-11T18:38:20Z

@rohitsakala I made a number of edits addressing suggestions. However, there are still three things unresolved:

The last section needs to describe how to enable the debug option

There are two sentences I wasn't sure how to edit and wrapped in HTML comment tags

The section explaining fields feels like it needs to be revised extensively, so that the fields are mentioned in context with where they can be found or used. Are they all on the Authentic part of the UI?

I replied to all your queries in the respective comments. Let me know if you have any more doubts.

…151-add-documentation-for-oci-feature-in-apps-and-marketplace-section

diogoasouza · 2024-06-11T21:45:59Z

...oned_docs/version-2.9/how-to-guides/new-user-guides/helm-charts-in-rancher/oci-registries.md

+1. Click **☰ > Cluster Management**.
+2. Find the name of the cluster whose repositories you want to access. Click **Explore** at the end of the cluster's row.
+3. In the left navigation bar, select **Apps > Repositories**.
+4. Click **Create**.


Can we add a screenshot here, similar to this one in the extension doc in step 3.3?

diogoasouza · 2024-06-11T21:47:33Z

...oned_docs/version-2.9/how-to-guides/new-user-guides/helm-charts-in-rancher/oci-registries.md

+
+  :::note
+
+  You can use the **OCI URL** field to finetune how many charts from the registry are availabe for installation on Rancher. More generic endpoints target more charts, as the following examples demonstrate:


Do we need to add this section? AFAIK, this is standard for every oci registry, not something specific to Rancher.
@rohitsakala keep me honest here

Yes this is standard but I thought users can look here into Rancher documentation at one place while they are adding the OCI based helm repository

diogoasouza · 2024-06-11T21:50:59Z

...oned_docs/version-2.9/how-to-guides/new-user-guides/helm-charts-in-rancher/oci-registries.md

+7. Set up authentication. Select **Basicauth** from the authentication field and enter a username and password as required. Otherwise, create or select an **Authentication** secret. See [Authentication](#authentication-for-oci-based-helm-chart-repositories) for a full description.
+8. (optional) Enter a base64 encoded DER certificate in the **CA Cert Bundle** field. This field is for cases where you have a private OCI-based Helm chart repository and need Rancher to trust its certificates.   
+9. (optional) To allow insecure connections without performing an SSL check, select **Skip TLS Verification**. To force Rancher to use HTTP instead of HTTPS to send requests to the repsoitory, select **Insecure Plain Http**. See  [Authentication](#authentication-for-oci-based-helm-chart-repositories) for more details.
+10. (optional) If you know that your repository may respond with status code `429 Too Many Requests` (for example, if your repository is on DockerHub), fill out the fields under **Exponential Back Off**:


Suggested change

10. (optional) If you know that your repository may respond with status code `429 Too Many Requests` (for example, if your repository is on DockerHub), fill out the fields under **Exponential Back Off**:

10. (optional) If your repository has a rate-limiting policy and may respond with status code `429 Too Many Requests` (for example, if your repository is on DockerHub), you may want to fill out the fields under **Exponential Back Off**:

diogoasouza · 2024-06-11T21:55:13Z

...oned_docs/version-2.9/how-to-guides/new-user-guides/helm-charts-in-rancher/oci-registries.md

+8. (optional) Enter a base64 encoded DER certificate in the **CA Cert Bundle** field. This field is for cases where you have a private OCI-based Helm chart repository and need Rancher to trust its certificates.   
+9. (optional) To allow insecure connections without performing an SSL check, select **Skip TLS Verification**. To force Rancher to use HTTP instead of HTTPS to send requests to the repsoitory, select **Insecure Plain Http**. See  [Authentication](#authentication-for-oci-based-helm-chart-repositories) for more details.
+10. (optional) If you know that your repository may respond with status code `429 Too Many Requests` (for example, if your repository is on DockerHub), fill out the fields under **Exponential Back Off**:
+  1. **Min Wait**: The default is 1 second.


Suggested change

1. **Min Wait**: The default is 1 second.

1. **Min Wait**: The minimum duration in seconds that Rancher should wait before retrying. The default is 1 second.

diogoasouza · 2024-06-11T21:55:52Z

...oned_docs/version-2.9/how-to-guides/new-user-guides/helm-charts-in-rancher/oci-registries.md

+9. (optional) To allow insecure connections without performing an SSL check, select **Skip TLS Verification**. To force Rancher to use HTTP instead of HTTPS to send requests to the repsoitory, select **Insecure Plain Http**. See  [Authentication](#authentication-for-oci-based-helm-chart-repositories) for more details.
+10. (optional) If you know that your repository may respond with status code `429 Too Many Requests` (for example, if your repository is on DockerHub), fill out the fields under **Exponential Back Off**:
+  1. **Min Wait**: The default is 1 second.
+  1. **Max Wait**: The default is 1 second.


Suggested change

1. **Max Wait**: The default is 1 second.

1. **Max Wait**: The maximum duration in seconds that Rancher should wait before retrying. The default is 5 second.

The default value is 5 seconds

rohitsakala · 2024-06-12T00:06:48Z

...oned_docs/version-2.9/how-to-guides/new-user-guides/helm-charts-in-rancher/oci-registries.md

rename the file to oci-repositories.md

rohitsakala · 2024-06-12T00:09:35Z

...oned_docs/version-2.9/how-to-guides/new-user-guides/helm-charts-in-rancher/oci-registries.md

+
+7. Set up authentication. Select **Basicauth** from the authentication field and enter a username and password as required. Otherwise, create or select an **Authentication** secret. See [Authentication](#authentication-for-oci-based-helm-chart-repositories) for a full description.
+8. (optional) Enter a base64 encoded DER certificate in the **CA Cert Bundle** field. This field is for cases where you have a private OCI-based Helm chart repository and need Rancher to trust its certificates.   
+9. (optional) To allow insecure connections without performing an SSL check, select **Skip TLS Verification**. To force Rancher to use HTTP instead of HTTPS to send requests to the repsoitory, select **Insecure Plain Http**. See  [Authentication](#authentication-for-oci-based-helm-chart-repositories) for more details.


See Authentication for more details.

is not required here.

rohitsakala · 2024-06-12T00:10:50Z

...oned_docs/version-2.9/how-to-guides/new-user-guides/helm-charts-in-rancher/oci-registries.md

+7. Set up authentication. Select **Basicauth** from the authentication field and enter a username and password as required. Otherwise, create or select an **Authentication** secret. See [Authentication](#authentication-for-oci-based-helm-chart-repositories) for a full description.
+8. (optional) Enter a base64 encoded DER certificate in the **CA Cert Bundle** field. This field is for cases where you have a private OCI-based Helm chart repository and need Rancher to trust its certificates.   
+9. (optional) To allow insecure connections without performing an SSL check, select **Skip TLS Verification**. To force Rancher to use HTTP instead of HTTPS to send requests to the repsoitory, select **Insecure Plain Http**. See  [Authentication](#authentication-for-oci-based-helm-chart-repositories) for more details.
+10. (optional) If you know that your repository may respond with status code `429 Too Many Requests` (for example, if your repository is on DockerHub), fill out the fields under **Exponential Back Off**:


remove the example of Dockerhub. For dockerhub,adding exponentailBackoff values has no use since Rancher automatically waits for 6 hours that dockerhub sends as a header.

rohitsakala · 2024-06-12T00:11:50Z

...oned_docs/version-2.9/how-to-guides/new-user-guides/helm-charts-in-rancher/oci-registries.md

+
+Rancher supports BasicAuth for OCI registries. You must create a [**BasicAuth** Kubernetes secret](https://kubernetes.io/docs/concepts/configuration/secret/#basic-authentication-secret). You can also [create the secret through the Rancher UI](../kubernetes-resources-setup/secrets.md). 
+
+Rancher 2.9.0 also adds the `spec.insecurePlainHttp` field, which forces Rancher to use HTTP instead of HTTPS to send requests. This works exactly the same as the `spec.insecurePlainHttp` field in [ORAS CLI](https://oras.land/docs/commands/use_oras_cli), since Rancher uses the ORAS library.


Suggested change

Rancher 2.9.0 also adds the `spec.insecurePlainHttp` field, which forces Rancher to use HTTP instead of HTTPS to send requests. This works exactly the same as the `spec.insecurePlainHttp` field in [ORAS CLI](https://oras.land/docs/commands/use_oras_cli), since Rancher uses the ORAS library.

rohitsakala · 2024-06-12T00:12:10Z

...oned_docs/version-2.9/how-to-guides/new-user-guides/helm-charts-in-rancher/oci-registries.md

+
+Rancher 2.9.0 also adds the `spec.insecurePlainHttp` field, which forces Rancher to use HTTP instead of HTTPS to send requests. This works exactly the same as the `spec.insecurePlainHttp` field in [ORAS CLI](https://oras.land/docs/commands/use_oras_cli), since Rancher uses the ORAS library.
+
+The CRD that is linked to the OCI Helm registry is `ClusterRepo`.


Suggested change

The CRD that is linked to the OCI Helm registry is `ClusterRepo`.

The CRD that is linked to the OCI based Helm repository is `ClusterRepo`.

rohitsakala · 2024-06-12T00:12:28Z

...oned_docs/version-2.9/how-to-guides/new-user-guides/helm-charts-in-rancher/oci-registries.md

+1. Click **Apps > Charts**.
+1. Select the OCI-based Helm chart repository from the dropdown.
+
+## Refresh an OCI-Based Helm Chart Registry


Suggested change

## Refresh an OCI-Based Helm Chart Registry

## Refresh an OCI-Based Helm Chart Repository

1151 Add documentation for OCI feature in Apps & Marketplace Section

fb19f68

martyav changed the title ~~1151 Add documentation for OCI feature in Apps & Marketplace Section~~ #1151 Add documentation for OCI feature in Apps & Marketplace Section Mar 12, 2024

martyav added this to the v2.9.0 milestone Mar 12, 2024

martyav added 7 commits March 12, 2024 11:04

rename file, edit intro, add canonical link

ec5d9a8

edited refresh instructions

3c8f0a9

edited update instructions

bd93373

edited delete instructions

b7206f2

initial attempt at add an oci registry

70c45fe

completed edit of first section, made misc revisions to other text

29187fa

escape angle brackets

87f2bef

martyav added the DO NOT MERGE label Mar 21, 2024

martyav marked this pull request as ready for review March 21, 2024 15:03

martyav requested review from btat, LucasSaintarbor and sunilarjun as code owners March 21, 2024 15:03

martyav commented Mar 21, 2024

View reviewed changes

docs/how-to-guides/new-user-guides/helm-charts-in-rancher/oci-registries.md Outdated Show resolved Hide resolved

martyav requested a review from rohitsakala March 25, 2024 19:07

martyav mentioned this pull request Jun 6, 2024

Add docs for OCI Helm Repository feature #1320

Closed

martyav added 4 commits June 6, 2024 13:29

Merge branch 'main' of https://github.com/rancher/rancher-docs into 1…

9fb6c9d

…151-add-documentation-for-oci-feature-in-apps-and-marketplace-section

moved file

43ce187

added edited text of helm-charts-in-rancher from rancher#1320

960d72d

instructions updated to sync with rancher#1320

17a167d

rohitsakala reviewed Jun 10, 2024

View reviewed changes

...oned_docs/version-2.9/how-to-guides/new-user-guides/helm-charts-in-rancher/oci-registries.md Outdated Show resolved Hide resolved