Skip to content

Elastic Stack Helm chart upgrade and configuration changes documentation #4388

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
eedugon wants to merge 5 commits into
base: main
Choose a base branch
from
+147 −9
Open

Elastic Stack Helm chart upgrade and configuration changes documentation #4388

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
7905046
Elastic Stack Helm chart upgrade and configuration changes
eedugon Dec 17, 2025
7df2eb4
Merge branch 'main' of github.com:elastic/docs-content into eck_helm_…
eedugon Dec 17, 2025
c2d99aa
linting hint
eedugon Dec 17, 2025
f93faef
Apply suggestions from code review
eedugon Dec 29, 2025
004dff7
Merge remote-tracking branch 'origin/main' into eck_helm_upgrades
eedugon Dec 29, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion deploy-manage/deploy/cloud-on-k8s/install-using-helm-chart.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down
149 changes: 142 additions & 7 deletions deploy-manage/deploy/cloud-on-k8s/managing-deployments-using-helm-chart.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,24 +88,142 @@

## 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:

1. Using Helm values
2. Using the individual Helm Charts directly (not the `eck-stack` helm chart)
* 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

**Using Helm values to install only Elasticsearch**
The following examples show how to install only {{es}} using each approach.

### 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 key principle is to use the same options and values you used during installation, along with any changes you want to apply.

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.

::::{important}
When using `helm upgrade`, you must include all the options and values from your original installation command (for example, custom values files and `--set` options). Helm does not retain your previous configuration, so omitting them causes values to revert to their default settings.
::::

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](#individual-chart) 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]

Check notice on line 226 in deploy-manage/deploy/cloud-on-k8s/managing-deployments-using-helm-chart.md

View workflow job for this annotation

GitHub Actions / preview / vale 

Elastic.Capitalization: 'Add Ingress to the' should use sentence-style capitalization.

:::{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.
Expand Down Expand Up @@ -135,7 +253,7 @@
--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
Expand Down Expand Up @@ -193,3 +311,20 @@
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
```
5 changes: 4 additions & 1 deletion deploy-manage/upgrade/deployment-or-cluster/upgrade-on-eck.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,6 @@ 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}}.
Expand All @@ -20,6 +19,10 @@ Before you start the upgrade, [plan your upgrade](/deploy-manage/upgrade/plan-up
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.

::::{note}
If you deploy your {{stack}} resources using our Helm chart, refer to [](/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.
::::
Comment on lines +22 to +24
Copy link
Collaborator

@shainaraskas shainaraskas Dec 17, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this note kind of works, but I don't like how it's splitting the instructions and example, and it is burying an up-front choice in the middle of the procedure

consider instead:

  1. introducing that there are two ways to do it in the intro for the page
  2. making two H2s, one for each: e.g. "Perform the upgrade in the cluster spec file" "Perform the upgrade using a Helm chart"

not sure if there is a better way to word the headings, because it's less about the method of performing the upgrade, than the context of the configuration ... some alternative headings might be:

"For orchestrators using spec files"
"For orchestrators using Helm charts"

orchestrators / operators / environments / deployments / clusters ... whatever feels the most accurate

you see what I'm getting at :)

Copy link
Contributor Author

@eedugon eedugon Dec 29, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see your point, and I agree.... however I didn't want to do extra changes on documents that are already established and feel very simple (in a good way).

Take in mind the following and let me know your thoughts.... :)

Currently we have this:

image

  • The doc intro feels accurate for all ECK users (helm vs no helm) as it starts with an intro about upgrading in general with links to preparations, etc.

  • Then when it comes to the "procedure" what we show is that technically upgrading is super simple, just change the version of your spec. It's true that we don't mention helm based installations earlier, but considering how small the procedure is and that we have the note right after I think it should be fine.

  • I also think it's good to "force" a helm-user to read the standard procedure, because at the end of the day, what they have to achieve through helm is the same (change the version on the final spec file).

What I think we could really to do improve this is moving upwards these two paragraphs that are currently at the end:
image

They are relevant to all users and those feel a big hidden at the end of a big example. Maybe those 2 paragraphs could be in the intro. What do you think? :)

Copy link
Collaborator

@shainaraskas shainaraskas Dec 29, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think moving up those paragraphs makes sense, but I still think that forcing helm chart users to read through this procedure is a little confusing, especially because the easiest way to upgrade is via a flag on a helm command, which might impact the underlying spec file, but it's not the same thing as editing the spec file directly.

won't block this but that is my opinion


In this example, we’re modifying the version to {{version.stack}}.

:::{important}
Expand Down
Loading