Addons Management

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.

Install Addons

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 repo add kubeblocks https://apecloud.github.io/helm-charts
helm repo update
```

View the Addon versions.

helm search repo kubeblocks/elasticsearch --versions

Expected output:

NAME                           	CHART VERSION	APP VERSION	DESCRIPTION
kubeblocks/elasticsearch        	1.0.0        	8.8.2      	Elasticsearch is a distributed, RESTful search ...
kubeblocks/elasticsearch        	0.9.1        	8.8.2      	Elasticsearch is a distributed, RESTful search ...
kubeblocks/elasticsearch        	0.9.0        	8.8.2      	Elasticsearch is a distributed, RESTful search ...
kubeblocks/elasticsearch        	0.8.0        	8.8.2      	Elasticsearch is a distributed, RESTful search ...

Install the Addon (take elasticsearch as example). Specify a version with --version.
```
helm install kb-addon-elasticsearch kubeblocks/elasticsearch --namespace kb-system --create-namespace --version 1.0.0
```
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
>
NAME                    NAMESPACE	REVISION	UPDATED                                   STATUS  	CHART                            APP VERSION
...
kb-addon-elasticsearch	kb-system	1       	2025-07-17 02:31:20.687010511 +0000 UTC	deployed	elasticsearch-1.0.0             	8.8.2

(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
```

View the index.

kbcli creates an index named kubeblocks by default and you can check whether this index is created by running kbcli addon index list.
```
kbcli addon index list
>
INDEX        URL
kubeblocks   https://github.com/apecloud/block-index.git
```
If the list is empty or you want to add your index, you can add the index manually by using kbcli addon index add <index-name> <source>. For example,
```
kbcli addon index add kubeblocks https://github.com/apecloud/block-index.git
```
If you are not sure whether the kubeblocks index is the latest version, you can update it.
```
kbcli addon index update kubeblocks
```

(Optional) Search whether the Addon exists in the index.

kbcli addon search elasticsearch
>
ADDON           VERSION         INDEX
elasticsearch   0.9.0           kubeblocks
elasticsearch   0.9.1           kubeblocks
elasticsearch   1.0.0           kubeblocks

Install the Addon.

If there are multiple index sources and versions for an Addon, you can specify an index by --index and a version by --version. The system installs the latest version in the kubeblocks index by default.
```
kbcli addon install elasticsearch --index kubeblocks --version 1.0.0
```
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 Enabled and this Addon is installed successfully.

kbcli addon list
>
NAME                           VERSION        PROVIDER    STATUS     AUTO-INSTALL
elasticsearch                  1.0.0          apecloud    Enabled    true

And when you check the helm list, you will see the helm chart is installed.

helm list -A
>
NAME                    NAMESPACE	REVISION	UPDATED                                   STATUS  	CHART                            APP VERSION
...
kb-addon-elasticsearch	kb-system	1       	2025-07-17 02:31:20.687010511 +0000 UTC	deployed	elasticsearch-1.0.0             	8.8.2

Disable/Enable Addons
- Enable an Addon. Enable an Addon will install the helm chart associated with the Addon.
```
kbcli addon enable elasticsearch
```
- Disable an Addon. Disable an Addon will uninstall the helm chart associated with the Addon.
```
kbcli addon disable elasticsearch
```
Uninstall an Addon.

Uninstall an Addon will delete the Addon and all related resources.
```
kbcli addon uninstall elasticsearch
```

TIP

What is the difference between using kbcli and helm to install an Addon?

kbcli installs an Addon CR, and KubeBlocks will reconcile the Addon CR to install/uninstall/upgrade the helm chart specified in the Addon CR.
helm installs a helm chart directly, and you need to manage the helm chart manually.

Upgrade Addons

Follow these steps to upgrade Addons individually.

NOTE

Upgrading Addons may lead to restarting existing database clusters and affect availability. Only proceed during maintenance windows, and test the upgrade in a non-production environment first.

Step 1: Configure Addon Repository


# Add the primary Addon repository
helm repo add kubeblocks-addons https://apecloud.github.io/helm-charts

# Alternative repository for users in regions with limited GitHub access
# helm repo add kubeblocks-addons https://jihulab.com/api/v4/projects/150246/packages/helm/stable

# Update repository information
helm repo update

Step 2: Find Available Versions


# Search for available versions of a specific Addon
helm search repo kubeblocks-addons/{addon-name} --versions --devel
# Example: helm search repo kubeblocks-addons/mysql --versions --devel

Step 3: Upgrade the Addon

Select a version that is compatible (same major version) with your KubeBlocks release and upgrade:


# Upgrade to a specific version
helm upgrade -i {addon-release-name} kubeblocks-addons/{addon-name} --version x.y.z -n kb-system

NOTE

Parameter Reference:

{addon-name}: Replace with the actual Addon name (e.g., mysql, postgresql)
{addon-release-name}: The release name of the installed Addon (e.g., kb-addon-mysql, kb-addon-postgresql)
x.y.z: The target version number, compatible with your KubeBlocks release

Step 1: Update Addon Index


# List available Addon indexes (the default index is `kubeblocks`)
kbcli addon index list

# Update the default KubeBlocks index
kbcli addon index update kubeblocks

Step 2: Search for Available Addon Versions


# Search for available versions of a specific Addon
kbcli addon search {addon-name}

# View currently installed Addons and their versions
kbcli addon list | grep {addon-name}

Step 3: Upgrade the Addon

Select a version that is compatible (same major version) with your KubeBlocks release and upgrade:

kbcli addon upgrade {addon-name} --version x.y.z

Force upgrade (use with caution):

kbcli addon upgrade {addon-name} --version x.y.z --force

Fresh installation (if not previously installed):

kbcli addon install {addon-name} --version x.y.z

NOTE

When to use --force:

You need to downgrade to a previous version
Use with caution as it bypasses compatibility checks

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 image.registry=test.io # more values omitted for brevity


kbcli addon enable kb-addon-elasticsearch --set image.registry=test.io # more values omitted for brevity

Step 3. Verify the changes.

Check the helm chart values.

helm get values kb-addon-elasticsearch -n kb-system

Expected output:


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.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' | grep 'image:'

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:

NAME                    SERVICE         SERVICE-VERSION   STATUS      AGE
elasticsearch-7-1.0.0   elasticsearch                     Available   33m
elasticsearch-8-1.0.0   elasticsearch                     Available   33m

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-immutable-check=true

Then the status will be Available again.

Addons Management

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.

Install Addons

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 repo add kubeblocks https://apecloud.github.io/helm-charts
helm repo update
```

View the Addon versions.

helm search repo kubeblocks/elasticsearch --versions

Expected output:

NAME                           	CHART VERSION	APP VERSION	DESCRIPTION
kubeblocks/elasticsearch        	1.0.0        	8.8.2      	Elasticsearch is a distributed, RESTful search ...
kubeblocks/elasticsearch        	0.9.1        	8.8.2      	Elasticsearch is a distributed, RESTful search ...
kubeblocks/elasticsearch        	0.9.0        	8.8.2      	Elasticsearch is a distributed, RESTful search ...
kubeblocks/elasticsearch        	0.8.0        	8.8.2      	Elasticsearch is a distributed, RESTful search ...

Install the Addon (take elasticsearch as example). Specify a version with --version.
```
helm install kb-addon-elasticsearch kubeblocks/elasticsearch --namespace kb-system --create-namespace --version 1.0.0
```
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
>
NAME                    NAMESPACE	REVISION	UPDATED                                   STATUS  	CHART                            APP VERSION
...
kb-addon-elasticsearch	kb-system	1       	2025-07-17 02:31:20.687010511 +0000 UTC	deployed	elasticsearch-1.0.0             	8.8.2

(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
```

View the index.

kbcli creates an index named kubeblocks by default and you can check whether this index is created by running kbcli addon index list.
```
kbcli addon index list
>
INDEX        URL
kubeblocks   https://github.com/apecloud/block-index.git
```
If the list is empty or you want to add your index, you can add the index manually by using kbcli addon index add <index-name> <source>. For example,
```
kbcli addon index add kubeblocks https://github.com/apecloud/block-index.git
```
If you are not sure whether the kubeblocks index is the latest version, you can update it.
```
kbcli addon index update kubeblocks
```

(Optional) Search whether the Addon exists in the index.

kbcli addon search elasticsearch
>
ADDON           VERSION         INDEX
elasticsearch   0.9.0           kubeblocks
elasticsearch   0.9.1           kubeblocks
elasticsearch   1.0.0           kubeblocks

Install the Addon.

If there are multiple index sources and versions for an Addon, you can specify an index by --index and a version by --version. The system installs the latest version in the kubeblocks index by default.
```
kbcli addon install elasticsearch --index kubeblocks --version 1.0.0
```
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 Enabled and this Addon is installed successfully.

kbcli addon list
>
NAME                           VERSION        PROVIDER    STATUS     AUTO-INSTALL
elasticsearch                  1.0.0          apecloud    Enabled    true

And when you check the helm list, you will see the helm chart is installed.

helm list -A
>
NAME                    NAMESPACE	REVISION	UPDATED                                   STATUS  	CHART                            APP VERSION
...
kb-addon-elasticsearch	kb-system	1       	2025-07-17 02:31:20.687010511 +0000 UTC	deployed	elasticsearch-1.0.0             	8.8.2

Disable/Enable Addons
- Enable an Addon. Enable an Addon will install the helm chart associated with the Addon.
```
kbcli addon enable elasticsearch
```
- Disable an Addon. Disable an Addon will uninstall the helm chart associated with the Addon.
```
kbcli addon disable elasticsearch
```
Uninstall an Addon.

Uninstall an Addon will delete the Addon and all related resources.
```
kbcli addon uninstall elasticsearch
```

TIP

What is the difference between using kbcli and helm to install an Addon?

kbcli installs an Addon CR, and KubeBlocks will reconcile the Addon CR to install/uninstall/upgrade the helm chart specified in the Addon CR.
helm installs a helm chart directly, and you need to manage the helm chart manually.

Upgrade Addons

Follow these steps to upgrade Addons individually.

NOTE

Upgrading Addons may lead to restarting existing database clusters and affect availability. Only proceed during maintenance windows, and test the upgrade in a non-production environment first.

Step 1: Configure Addon Repository


# Add the primary Addon repository
helm repo add kubeblocks-addons https://apecloud.github.io/helm-charts

# Alternative repository for users in regions with limited GitHub access
# helm repo add kubeblocks-addons https://jihulab.com/api/v4/projects/150246/packages/helm/stable

# Update repository information
helm repo update

Step 2: Find Available Versions


# Search for available versions of a specific Addon
helm search repo kubeblocks-addons/{addon-name} --versions --devel
# Example: helm search repo kubeblocks-addons/mysql --versions --devel

Step 3: Upgrade the Addon

Select a version that is compatible (same major version) with your KubeBlocks release and upgrade:


# Upgrade to a specific version
helm upgrade -i {addon-release-name} kubeblocks-addons/{addon-name} --version x.y.z -n kb-system

NOTE

Parameter Reference:

{addon-name}: Replace with the actual Addon name (e.g., mysql, postgresql)
{addon-release-name}: The release name of the installed Addon (e.g., kb-addon-mysql, kb-addon-postgresql)
x.y.z: The target version number, compatible with your KubeBlocks release

Step 1: Update Addon Index


# List available Addon indexes (the default index is `kubeblocks`)
kbcli addon index list

# Update the default KubeBlocks index
kbcli addon index update kubeblocks

Step 2: Search for Available Addon Versions


# Search for available versions of a specific Addon
kbcli addon search {addon-name}

# View currently installed Addons and their versions
kbcli addon list | grep {addon-name}

Step 3: Upgrade the Addon

Select a version that is compatible (same major version) with your KubeBlocks release and upgrade:

kbcli addon upgrade {addon-name} --version x.y.z

Force upgrade (use with caution):

kbcli addon upgrade {addon-name} --version x.y.z --force

Fresh installation (if not previously installed):

kbcli addon install {addon-name} --version x.y.z

NOTE

When to use --force:

You need to downgrade to a previous version
Use with caution as it bypasses compatibility checks

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 image.registry=test.io # more values omitted for brevity


kbcli addon enable kb-addon-elasticsearch --set image.registry=test.io # more values omitted for brevity

Step 3. Verify the changes.

Check the helm chart values.

helm get values kb-addon-elasticsearch -n kb-system

Expected output:


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.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' | grep 'image:'

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:

NAME                    SERVICE         SERVICE-VERSION   STATUS      AGE
elasticsearch-7-1.0.0   elasticsearch                     Available   33m
elasticsearch-8-1.0.0   elasticsearch                     Available   33m

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-immutable-check=true

Then the status will be Available again.