Elastic Stack Helm chart upgrade and configuration changes documentation

deploy-manage/deploy/cloud-on-k8s/install-using-helm-chart.md

@@ -9,7 +9,7 @@ products:
   - id: cloud-kubernetes
 ---
 
-# Install using a Helm chart [k8s-install-helm]
+# Install ECK using a Helm chart [k8s-install-helm]
 
 Starting from ECK 1.3.0, a Helm chart is available to install ECK. It is available from the Elastic Helm repository and can be added to your Helm repository list by running the following command:
 

deploy-manage/deploy/cloud-on-k8s/managing-deployments-using-helm-chart.md

@@ -24,7 +24,9 @@ The minimum supported version of Helm is {{eck_helm_minimum_version}}.
 
 The {{stack}} (`eck-stack`) Helm chart is built on top of individual charts such as `eck-elasticsearch` and `eck-kibana`. For more details on its structure and dependencies, refer to the [chart repository](https://github.com/elastic/cloud-on-k8s/tree/main/deploy/eck-stack/).
 
-The chart enables you to deploy the core components ({{es}} and {{kib}}) together, along with other {{stack}} applications if needed, under the same chart release. The following sections guide you through the installation process for multiple use cases. Choose the command that best fits your setup.
+The chart enables you to deploy the core components ({{es}} and {{kib}}) together, along with other {{stack}} applications if needed, under the same chart release.
+
+The following sections guide you through common installation, configuration, and upgrade use cases, and assume basic familiarity with [Helm](https://helm.sh/docs/). This guide does not provide a comprehensive introduction to Helm itself. Choose the command that best fits your setup.
 
 ::::{tip}
 All the provided examples deploy the applications in a namespace named `elastic-stack`. Consider adapting the commands to your use case.
@@ -88,24 +90,144 @@ Enterprise Search is not available in {{stack}} versions 9.0 and later. For an e
 
 ## Install individual components of the {{stack}} [k8s-eck-stack-individual-components]
 
-You can install individual components in one of two ways using the provided Helm Charts.
+You can install individual components in one of two ways using the provided Helm charts:
+
+* Using Helm values with the `eck-stack` chart to include only the components you need
+* Using the individual Helm charts directly, without using the `eck-stack` chart
 
-1. Using Helm values
-2. Using the individual Helm Charts directly (not the `eck-stack` helm chart)
+The following examples show how to install only {{es}} using each approach.
 
-**Using Helm values to install only Elasticsearch**
+### Using Helm values to install only {{es}}
+
+This example installs only {{es}} by deploying the `eck-stack` chart and excluding {{kib}}. By default, the chart deploys both {{es}} and {{kib}}.
 
 ```sh
 helm install es-quickstart elastic/eck-stack -n elastic-stack --create-namespace --set=eck-kibana.enabled=false
 ```
 
-**Using the eck-elasticsearch Helm Chart directly to install only Elasticsearch**
+### Using the eck-elasticsearch Helm chart directly to install only {{es}} [individual-chart]
+
+This example installs {{es}} by deploying the `eck-elasticsearch` chart on its own.
 
 ```sh
 helm install es-quickstart elastic/eck-elasticsearch -n elastic-stack --create-namespace
 ```
 
-## Adding Ingress to the {{stack}} [k8s-eck-stack-ingress]
+## Upgrade or change your {{stack}} configuration with Helm [k8s-upgrade-modify-helm]
+
+To upgrade your {{stack}} components to a new version or modify the configuration of your existing installation (known as a `release`), use the [`helm upgrade`](https://helm.sh/docs/helm/helm_upgrade/) command.
+
+The `helm upgrade` command requires the following arguments:
+- The name of the release to update, which must match the name used with `helm install`.
+- The chart name, which must be the same chart used during installation.
+
+::::{note}
+When running `helm upgrade`, it’s recommended to pass the same values and configuration options that were used during installation, together with any changes you want to apply. This ensures that the resulting configuration matches your expectations and reduces the risk of values reverting to the chart defaults during the upgrade.
+
+Helm provides additional options to control how values associated with an existing release are reused or reset during an upgrade. For details, refer to the [`helm upgrade` documentation](https://helm.sh/docs/helm/helm_upgrade/).
+::::
+
+By default, `helm upgrade` uses the latest available version of the chart unless the `--version` option is specified. Refer to [View chart versions](#show-versions) to list the available chart versions or the version associated with an installed release.
+
+::::{admonition} Chart version vs {{stack}} component version
+There is an important distinction between the Helm chart version and the {{stack}} component version:
+
+- **Chart version**: The version of the Helm chart itself (for example, `eck-stack` version 0.17.0). You can specify this using the `--version` flag in your Helm `install` or `upgrade` commands.
+- **Component version**: The version of a {{stack}} component (for example, {{es}} {{version.stack}} or {{kib}} {{version.stack}}). You can specify this in your values file or by using `--set` parameters.
+
+Each chart version defines default {{stack}} component versions. Unless explicitly overridden, installing or upgrading the chart deploys those default versions.
+
+% When available we can tell users how to check the default {{stack}} version associated with each chart release. That's not feasible today.
+::::
+
+All examples in this section assume that your release was installed using the `eck-stack` Helm chart. Adapt the examples if you deployed the [individual charts](#k8s-eck-stack-individual-components) directly.
+
+### Upgrade to the latest version of the chart
+
+To upgrade an installed release named `es-kb-quickstart` to the latest version of the Helm chart, do the following:
+
+```sh
+helm repo update <1>
+helm upgrade es-kb-quickstart elastic/eck-stack -n elastic-stack
+```
+1. Refresh the local chart cache.
+
+By default, upgrading the Helm chart also upgrades the {{stack}} components to the versions associated with that chart version. To override this behavior, you can explicitly set the {{stack}} component versions to use, as shown in the following section.
+
+### Upgrade to specific {{stack}} version
+
+If you want to upgrade the {{stack}} components to a later version that is not the default for the Helm chart, or you want to update your Helm chart without upgrading the {{stack}}, you can explicitly set the component versions using Helm values or `--set` options.
+
+The following examples show both ways to upgrade the release to the latest available version of the Helm chart and all {{stack}} components to version {{version.stack}}.
+
+#### Using the `--set` option
+
+Use `--set` options to override the component versions directly from the command line:
+
+```sh subs=true
+helm repo update <1>
+helm upgrade es-kb-quickstart elastic/eck-stack -n elastic-stack \
+  --set eck-elasticsearch.version={{version.stack}} \ <2>
+  --set eck-kibana.version={{version.stack}}
+```
+1. Refresh the local chart cache.
+2. Specify versions for all the components you deploy. Components without an explicitly defined version continue to use the default versions provided by the chart.
+
+#### Using a values file
+
+If you already use a values file for this release, update it to include the following settings. Otherwise, create a new values file (for example, `custom-values.yaml`) with the following content:
+
+```yaml subs=true
+eck-elasticsearch: <1>
+  version: {{version.stack}}
+eck-kibana:
+  version: {{version.stack}}
+```
+1. Specify versions for all the components you deploy. Components without an explicitly defined version continue to use the default versions provided by the chart.
+
+Then upgrade the release using the values file:
+
+```sh
+helm repo update <1>
+helm upgrade es-kb-quickstart elastic/eck-stack -n elastic-stack -f custom-values.yaml
+```
+1. Refresh the local chart cache.
+
+### Apply configuration changes
+
+To apply configuration changes to an existing release, run `helm upgrade` with the complete configuration you want the release to use. This includes both the current configuration and any new changes.
+
+For example, if you installed the [quickstart release](#k8s-install-elasticsearch-kibana-helm) and want to scale the {{es}} cluster to three nodes and expose the {{kib}} service using a LoadBalancer, do the following:
+
+1. Create a values file with the desired configuration, and save it as `custom-values.yaml`:
+
+   ```yaml
+   eck-elasticsearch:
+     nodeSets:
+     - name: default
+       count: 3
+
+   eck-kibana:
+     http:
+       service:
+         spec:
+           # This deploys a load balancer in a cloud service provider, where supported.
+           type: LoadBalancer
+   ```
+
+2. Apply the configuration using `helm upgrade`:
+
+   ```sh
+   helm upgrade es-kb-quickstart elastic/eck-stack \
+     -n elastic-stack \
+     -f custom-values.yaml
+   ```
+
+::::{warning}
+This example also upgrades the {{stack}} components if a newer Helm chart version is available. To avoid this, [identify the chart version](#show-versions) currently used by your release and include the `--version` option when running `helm upgrade`.
+::::
+
+## Add Ingress to the {{stack}} [k8s-eck-stack-ingress]
 
 :::{admonition} Support scope for Ingress Controllers
 [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) is a standard Kubernetes concept. While ECK-managed workloads can be publicly exposed using ingress resources, and we provide [example configurations](/deploy-manage/deploy/cloud-on-k8s/recipes.md), setting up an Ingress controller requires in-house Kubernetes expertise.
@@ -135,7 +257,7 @@ helm install es-kb-quickstart elastic/eck-stack -n elastic-stack --create-namesp
   --set=eck-kibana.ingress.enabled=true --set=eck-kibana.ingress.hosts[0].host=kibana.example.com --set=eck-kibana.ingress.hosts[0].path="/"
 ```
 
-For illustration purposes, the ingress objects created by the previous command will look similar to the following:
+For illustration purposes, the ingress objects created by the previous command look similar to the following:
 
 ```yaml
 # Source: eck-stack/charts/eck-elasticsearch/templates/ingress.yaml
@@ -193,3 +315,20 @@ helm show values elastic/eck-apm-server
 helm show values elastic/eck-fleet-server
 helm show values elastic/eck-logstash
 ```
+
+## View available chart versions [show-versions]
+
+To view the available versions of a Helm chart, update the local chart cache and use the `helm repo search` command with `--versions` option. You can use this flag with `eck-stack` or [individual charts](#k8s-eck-stack-individual-components).
+
+```sh
+helm repo update
+helm repo search elastic/eck-stack --versions
+```
+
+To view the version associated with an installed release, check the **CHART** column of the `helm list` command output. For example:
+
+```sh
+$ helm list -n elastic-stack
+NAME            	NAMESPACE    	REVISION	UPDATED                             	STATUS  	CHART                   	APP VERSION
+es-kb-quickstart	elastic-stack	2       	2025-12-17 11:24:06.156007 +0100 CET	deployed	eck-stack-0.17.0
+```

deploy-manage/upgrade/deployment-or-cluster/upgrade-on-eck.md

@@ -8,22 +8,32 @@ products:
   - id: cloud-kubernetes
   - id: elasticsearch
 ---
-
 # Upgrade your deployment on {{eck}} (ECK)
 
 The ECK orchestrator can safely perform upgrades to newer versions of the {{stack}}.
 
 Before you start the upgrade, [plan your upgrade](/deploy-manage/upgrade/plan-upgrade.md), [take the upgrade preparation steps](/deploy-manage/upgrade/prepare-to-upgrade.md), and ensure your ECK version is [compatible](/deploy-manage/deploy/cloud-on-k8s.md#stack-compatibility) with the {{stack}} version you’re upgrading to. If it's incompatible, [upgrade your orchestrator](/deploy-manage/upgrade/orchestrator/upgrade-cloud-on-k8s.md) first.
 
+## How ECK manages upgrades
+
+ECK ensures that {{stack}} components are upgraded in the correct order. Upgrades to dependent resources are delayed until that dependency is upgraded. For example, the {{kib}} upgrade starts only when the associated {{es}} cluster has been upgraded.
+
+Check out [Nodes orchestration](/deploy-manage/deploy/cloud-on-k8s/nodes-orchestration.md) for more information on how ECK manages upgrades and how to tune its behavior.
+
 ## Perform the upgrade
 
+The upgrade procedure depends on whether you are deploying the {{stack}} components [using resource manifests](/deploy-manage/deploy/cloud-on-k8s/elasticsearch-deployment-quickstart.md) or the [{{stack}} Helm chart](/deploy-manage/deploy/cloud-on-k8s/managing-deployments-using-helm-chart.md).
+
+### Upgrade using resource manifests
+
 1. In the resource spec file, modify the `version` field for the desired {{stack}} version.
 2. Save your changes. The orchestrator will start the upgrade process automatically.
 
-In this example, we’re modifying the version to {{version.stack}}.
+In this example, we're upgrading {{es}} and {{kib}} to {{version.stack}} by changing the `spec.version` field in each component.
 
+::::{dropdown} Example manifest
 :::{important}
-For production use, for {{stack}} version 8.16 and later, set the `vm.max_map_count` kernel setting to `1048576`; for {{stack}} version 8.15 and earlier, set `vm.max_map_count` to `262144`.
+For production use, for {{stack}} version 8.16 and later, set the `vm.max_map_count` kernel setting to `1048576`; for {{stack}} version 8.15 and earlier, set `vm.max_map_count` to `262144`. Refer to [Virtual memory](/deploy-manage/deploy/cloud-on-k8s/virtual-memory.md) for more information.
 :::
 
 ```yaml subs=true
@@ -142,10 +152,11 @@ spec:
   elasticsearchRef:
     name: elasticsearch-sample
 ```
+::::
 
-ECK will ensure that {{stack}} components are upgraded in the correct order. Upgrades to dependent resources are delayed until that dependency is upgraded. For example, the {{kib}} upgrade will start only when the associated {{es}} cluster has been upgraded.
+### Upgrade using Helm charts
 
-Check out [Nodes orchestration](/deploy-manage/deploy/cloud-on-k8s/nodes-orchestration.md) for more information on how ECK manages upgrades and how to tune its behavior.
+If you deploy your {{stack}} resources using our Helm chart, refer to [managing deployments using Helm chart](/deploy-manage/deploy/cloud-on-k8s/managing-deployments-using-helm-chart.md#k8s-upgrade-modify-helm) for details on how to perform upgrades with Helm.
 
 ## Next steps