replicatedhq · paigecalvert · Feb 3, 2025 · Jan 31, 2025 · Jan 31, 2025 · Jan 31, 2025
@@ -64,15 +64,17 @@ To install with Helm in an air gap environment:
 
 1. Run the command to install the `preflight` plugin. This allows you to run preflight checks before installing to ensure that the installation environment meets the requirements for the application.
 
-1. For **Determine install method**, select one of the options depending on your ability to access the internet and the cluster from your workstation.
+1. For **Download a copy of the values.yaml file** and **Edit the values.yaml file**, run the `helm show values` command provided to download the values file for the Helm chart. Then, edit the values file as needed to customize the configuration of the given chart.
 
-1. Run the `helm show values` command to download the default `values.yaml`. Then, edit the values as required. 
+    If you are installing a release that contains multiple Helm charts, repeat these steps to download and edit each values file.
 
     :::note
-    Replicated recommends that vendors provide detailed documentation that describes the values that customers need to configure. 
+    For installations with mutliple charts where two or more of the top-level charts in the release use the same name, ensure that each values file has a unique name to avoid installation error. For more information, see [Installation Fails for Release With Multiple Helm Charts](helm-install-troubleshooting#air-gap-values-file-conflict) in _Troubleshooting Helm Installations_.
     :::
 
-1. Use the commands provided and the edited `values.yaml` to run preflight checks and install the release with Helm.
+1. For **Determine install method**, select one of the options depending on your ability to access the internet and the cluster from your workstation.
+
+1. Use the commands provided and the values file or files that you edited to run preflight checks and then install the release.
 
 ## Perform Updates
 

@@ -10,14 +10,26 @@ This topic describes how to package a Helm chart and the Replicated SDK into a c
 
 To add a Helm chart to a release, you first add the Replicated SDK as a dependency of the Helm chart and then package the chart and its dependencies as a `.tgz` chart archive.
 
-The Replicated SDK is a Helm chart can be installed as a small service alongside your application. The SDK is strongly recommended because it provides access to key Replicated features, such as support for collecting custom metrics on application instances. For more information, see [About the Replicated SDK](replicated-sdk-overview). 
+The Replicated SDK is a Helm chart can be installed as a small service alongside your application. The SDK provides access to key Replicated features, such as support for collecting custom metrics on application instances. For more information, see [About the Replicated SDK](replicated-sdk-overview). 
 
-## Chart Version Requirement
+## Requirements and Recommendations
+
+This section includes requirements and recommendations for Helm charts.
+
+### Chart Version Requirement
 
 The chart version in your Helm chart must comply with image tag format requirements. A valid tag can contain only lowercase and uppercase letters, digits, underscores, periods, and dashes.
 
 The chart version must also comply with the Semantic Versioning (SemVer) specification. When you run the `helm install` command without the `--version` flag, Helm retrieves the list of all available image tags for the chart from the registry and compares them using the SemVer comparison rules described in the SemVer specification. The version that is installed is the version with the largest tag value. For more information about the SemVer specification, see the [Semantic Versioning](https://semver.org) documentation.
 
+### Chart Naming
+
+For releases that contain more than one Helm chart, Replicated recommends that you use unique names for each top-level Helm chart in the release. This aligns with Helm best practices and also avoids potential conflicts in filenames during installation that could cause the installation to fail. For more information, see [Installation Fails for Release With Multiple Helm Charts](helm-install-troubleshooting#air-gap-values-file-conflict) in _Troubleshooting Helm Installations_.
+
+### Helm Best Practices
+
+Replicated recommends that you review the [Best Practices](https://helm.sh/docs/chart_best_practices/) guide in the Helm documentation to ensure that your Helm chart or charts follows the required and recommended conventions.
+
 ## Package a Helm Chart {#release}
 
 This procedure shows how to create a Helm chart archive to add to a release. For more information about the Helm CLI commands in this procedure, see the [Helm Commands](https://helm.sh/docs/helm/helm/) section in the Helm documentation.

@@ -0,0 +1,25 @@
+# Troubleshooting 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 {#air-gap-values-file-conflict}
+
+#### 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](https://helm.sh/docs/chart_best_practices/dependencies/#conditions-and-tags) in the Helm documentation. 
@@ -508,6 +508,7 @@ const sidebars = {
       'vendor/install-with-helm',
       'vendor/helm-install-airgap',
       'vendor/using-third-party-registry-proxy',
+      'vendor/helm-install-troubleshooting',
     ],
   },
   {