- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Advanced Configuration Set Addon Values
Install Addons
With the release of KubeBlocks v0.8.0, Addons are decoupled from KubeBlocks and some Addons are not installed by default. If you want to use these Addons, install Addons first by index. Or if you uninstalled some Addons, you can follow the steps in this tutorial to install them again.
This tutorial takes elasticsearch as an example. You can replace elasticsearch with the Addon you need.
The official index repo is KubeBlocks index. Addons are maintained in the KubeBlocks Addon repo.
NOTE
Make sure the major version of Addons and KubeBlocks are the same.
For example, you can install an Addon v0.9.0 with KubeBlocks v0.9.2, but using mismatched major versions, such as an Addon v0.8.0 with KubeBlocks v0.9.2, may lead to errors.
- (Optional) Add the KubeBlocks repo. If you install KubeBlocks with Helm, just run
helm repo update.
helm search repo kubeblocks/elasticsearch - - versions
Expected output:
Table (html):
| NAME | CHART VERSION | APP VERSION | DESCRIPTION |
| kubeblocks/elasticsearch | 1.0.0 | 8.8.2 | Elasticsearch is a distributed, |
| kubeblocks/elasticsearch | 0.9.1 | 8.8.2 | Elasticsearch is a distributed, |
| kubeblocks/elasticsearch | 0.9.0 | 8.8.2 | Elasticsearch is a distributed, |
| kubeblocks/elasticsearch | 0.8.0 | 8.8.2 | Elasticsearch is a distributed, |
- Install the Addon (take elasticsearch as example). Specify a version with - - version.
helm install kb- addon- elasticsearch kubeblocks/elasticsearch - - namespace kb- system - - create- namespace
NOTE
Version Compatibility
- Always choose the Addon version compatible with your KubeBlocks deployment- Existing deployments require version matching:- KubeBlocks v1.0.0 → Addon v1.0.x- KubeBlocks v0.9. x → Addon v0.9. x- Mismatches may cause operational issues
- Verify whether this Addon is installed.
The STATUS is deployed and this Addon is installed successfully.
helm list - A
Table (html):
| NAME | NAMESPACE | REVISION | UPDATED | STATUS |
| ... | | | | |
| kb-addon-elasticsearch | kb-system | 1 | 2025-07-17 02:31:20.687010511 +0000 UTC deploye | |
- (Optional) You can run the command below to uninstall the Addon.
If you have created a related cluster, delete the cluster first.
helm uninstall kb- addon- elasticsearch - - namespace kb- system
Advanced Configuration
Set Addon Values
You can customize the Addon values when installing or enabling an Addon, for example, set the image registry.
TIP
Each Addon has its own values, one should check the full list of values first before making any changes.
Step 1. Check the full list of values can be set:
helm show values kubeblocks/elasticsearch - - version 1.0.0
Where kubeblocks is the name of the addon helm repository, elasticsearch is the name of the chart, and 1.0.0 is the version of the chart.
Or you can go to KubeBlocks Addon repository and choose the right version to check more details.
Expected output:
image:
registry: docker.io repository: apecloud/elasticsearch exporter: repository: apecloud/elasticsearch- exporter tag:"v1.7.0"
plugin: repository: apecloud/elasticsearch- plugins tag: "8.8.2" ... # more values omitted for brevity
Step 2. Update image registry to your private registry:
helm upgrade - i kb- addon- elasticsearch kubeblocks/elasticsearch - - namespace kb- system - - version 1.0.0 - - set
Step 3. Verify the changes.
Check the helm chart values.
helm get values kb- addon- elasticsearch - n kb- system
Expected output:
image:
image: registry: test.io ... # more values omitted for brevity
Check if all values are updated as expected.
Check ComponentVersion CR if all the images are updated.
Each KubeBlocks Addon has its own ComponentVersion CR to record the list of service versions and the list of images use for each version.
kubectl get cmpv elasticsearch - oyaml | yq '.spec.releases[].images
Expected output:
elasticsearch: test.io/apecloud/elasticsearch
.7.1 # using test.io instead of docker.io
All images are using the private registry test.io as expected.
Check the ComponentDefinition CR if all the images are updated.
for each ComponentDefinition CR, check the images field kubectl get cmpd - l app.kubernetes.io/instance=kb- addon- elasticsearch - oyaml | yq '.items[].spec' | gr
Check the ComponentDefinition Status after the changes.
check the status of the ComponentDefinition CRs kubectl get cmpd - l app.kubernetes.io/instance=kb- addon- elasticsearch
Expected output:
If the status is Unavailable, you can describe the ComponentDefinition CR to see the error message.
kubectl describe cmpd - l app.kubernetes.io/instance=kb- addon- elasticsearch
If the message is immutable fields can't be updated as below,
Status: Message: Immutable fields can't be updated Observed Generation: 3 Phase: Unavailable
You need to annotate the ComponentDefinition CR to allow the changes.
kubectl annotate cmpd - l app.kubernetes.io/instance=kb- addon- elasticsearch apps.kubeblocks.io/skip- immu
Then the status will be Available again.