Docs: update Helm Chart page to show usage without cloning Polaris github repo

[olsoloviov]

…

What changes were proposed in this pull request?

Minor documentation fix intended to let users know how to use Polaris Helm Charts

Why are the changes needed?

There was a mention in #2272 that it is not clear where to obtain released Polaris Helm charts, so it made sense to update the doc for users who want to use released distributives instead of working with Polaris code repo.

Does this PR introduce any user-facing change?

How was this patch tested?

CHANGELOG.md

[MonkeyCanCode]

For this file, you can use make helm-doc-generate to generate instead of manual edit.

[olsoloviov]

Thanks @MonkeyCanCode, I did not know it was automatically copied. But I see that there are already merged changes that diverge helm.md from helm/polaris/readme.md - markup for blockquotes was changed in #2656.
Also, there is a problem with rendering badges in the original page header when hosted on the apache.org:

Apparently apache.org content security policy does not allow embedding images from external hosts:

Refused to load the image 'https://img.shields.io/badge/Version-1.2.0--incubating--SNAPSHOT-informational?style=flat-square' because it violates the following Content Security Policy directive: "default-src 'self' data: blob: 'unsafe-inline' 'unsafe-eval' https://www.apachecon.com/ https://www.communityovercode.org/ https://*.apache.org/ https://apache.org/ https://*.scarf.sh/". Note that 'img-src' was not explicitly set, so 'default-src' is used as a fallback.

It was my motivation to remove the header from page version for the site.

As a sidenote, we have other pages on the site that are copies from getting-started docs (e.g. Keycloak setup page, Telemetry setup page), but they are not copied automatically. It would be good to have some unified approach for such cases.

[MonkeyCanCode]

Yes. That is correct. If u run local, it will all show up. Either we will need to update the policy or have a better way to handle these. Manually edit those can be fairly tedious. @flyrain

[flyrain]

Agreed with @MonkeyCanCode to rely on automation. Can we also add a post-process step to make helm-doc-generate, e.g., generate helm.md automatically with minor adjustments (strip badges, convert blockquotes)?

[adutra]

I would love to see this automated, but unfortunately the two pages are different, especially the warning box style.

I think we would need two different templates.

[adutra]

FWIW, I think this needs to be addressed separately, in a follow-up PR.

[olsoloviov]

I agree it is a good idea to converge helm.md back with helm chart readme and sync them automatically.
I see that we can go back from Hugo shortcodes to github-style blockqoutes for alert blocks - I made it work locally, but it requires updating Hugo version. It may bring additional concerns (full site testing etc.), so I would make it a separate PR as @adutra suggested.

[flyrain]

Explicitly pulling isn't needed, Helm will pull images automatically if imagePullPolicy: IfNotPresent or Always is configured in the chart (which it is by default for most charts). All we need here is:

Otherwise, Helm will automatically pull released images during installation.

[adutra]

This isn't for Helm, but for the kubelet inside Minikube. The kubelet can only download images if they are publicly available.

If the image is from a private registry, or only present locally in the host machine (e.g. because you built a custom apache/polaris:latest image from sources and you want to use it), then this instruction is necessary.

All in all, I think it's fine to leave the instructions.

[flyrain]

Thanks for the clarification, that makes sense. Good point about the kubelet behavior inside Minikube. I agree it’s fine to keep the minikube image pull instructions for users running with private or locally built images.

That said, I still think it’d be clearer to separate the doc into two sections, one for the standard “Helm install from the official repo” path, and another “advanced / from source” section for developers. This way, most users can follow the simple flow without extra steps, while contributors still have the detailed Minikube setup if needed. More details are in this comment, #2939 (review).

[flyrain]

Thanks a lot @olsoloviov for working on this!
Since we are here, I’d suggest splitting this section into two parts:

• Recommended: Installing from the official Helm repository. This is the simplest and most common way to deploy Polaris, without cloning or building locally.
• Advanced: Building and running from source. For developers who want to test local changes or custom images.

This separation would make the “happy path” much clearer for most users, while still keeping the advanced instructions for contributors. It would also eliminate the need for commands like minikube image pull in the main flow since Helm automatically pulls images from the registry.

Something like the followng:

Install from official Helm repository (recommended)

minikube start
helm repo add polaris https://downloads.apache.org/incubator/polaris/helm-chart
helm repo update
kubectl create namespace polaris
helm install polaris polaris/polaris --namespace polaris

Build and install from source (advanced)

minikube start
eval $(minikube docker-env)
./gradlew :polaris-server:assemble :polaris-server:quarkusAppPartsBuild \
  :polaris-admin:assemble :polaris-admin:quarkusAppPartsBuild \
  -Dquarkus.container-image.build=true
helm upgrade --install polaris ./helm/polaris --namespace polaris