Skip to main content

Troubleshoot Helm Installations with Replicated

This topic provides troubleshooting information for common issues related to performing installations and upgrades with the Helm CLI.

Installation Fails for Release With Multiple Helm Charts​

Symptom​

When performing installing a release with multiple Helm charts, the installation fails. You might also see the following error message:

Error: INSTALLATION FAILED: cannot re-use a name that is still in use

Cause​

In the Download Portal, each chart's values file is named according to the chart's name. For example, the values file for the Helm chart Gitea would be named gitea-values.yaml.

If any top-level charts in the release use the same name, the associated values files will also be assigned the same name. This causes each new values file downloaded with the helm show values command to overwrite any previously-downloaded values file of the same name.

Solution​

Replicated recommends that you use unique names for top-level Helm charts in the same release.

Alternatively, if a release contains charts that must use the same name, convert one or both of the charts into subcharts and use Helm conditions to differentiate them. See Conditions and Tags in the Helm documentation.

Incomplete list of required images in the Helm air gap instructions​

Symptom​

You see an empty or incomplete list of application images in the Helm air gap installation instructions provided in the Replicated Enterprise Portal or Download Portal.

Or, when attempting to install, you get an ImagePullBackOff error because Kubernetes is not able to access one or more images referenced in the Helm deployment.

Cause​

The Enterprise Portal and Download Portal provide instructions for installing with Helm in air-gapped environments. As part of installing with Helm in air-gapped environments, users are instructed to pull all required images for the Helm chart and then push them to their local image registry.

To create the list of images for the Helm air gap installation instructions, the Vendor Portal uses the Helm values provided in the HelmChart custom resource builder key to template the chart and then parse the output for image references.

If the builder key was not configured, then the Vendor Portal uses the default values for the chart when running helm template. If the Helm values used when templating the chart do not expose all the images that customers might need to install, then the installation fails when Kubernetes is unable to access one or more images in the Helm deployment from the user's local registry.

Solution​

Configure the builder key so that the ouput of helm template exposes all the images that might be required for users to install the chart in an air-gapped environment. For more information about how to configure the builder key, see builder in HelmChart v2.

For more information about why the builder key is required to support air gap installations with Helm, see Why you should create HelmChart resources for your Helm-only releases in the Replicated Community site.