# skywalking-helm: installing the SkyWalking APM backend on Kubernetes

> The Apache SkyWalking Helm repository packages the OAP backend and the Horizon UI for Kubernetes, with Elasticsearch, BanyanDB or PostgreSQL as storage, an OAP init job, a Satellite component and a documented upgrade path. It is Apache 2.0 licensed, and three values have no default and must be set on every install.

**apache/skywalking-helm** — Apache SkyWalking Kubernetes Deployment Helm Chart

- Repository: https://github.com/apache/skywalking-helm
- Website: https://skywalking.apache.org/
- Stars: 549 · Forks: 206
- Language: Shell
- License: Apache-2.0
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/apache-skywalking-helm

## What the chart actually deploys

The SkyWalking Kubernetes Helm repository provides ways to install and configure SkyWalking in a Kubernetes cluster, and the scripts are written in Helm 3.

SkyWalking is an APM and observability platform, and the chart deploys the pieces that make it work: the OAP, which is the backend that receives trace data and serves the query API, and the Horizon UI, the web interface. The documentation table in the README makes the deployment surface explicit. Storage is a choice between Pick a Backend, Elasticsearch, BanyanDB and PostgreSQL. The web UI side covers Horizon UI, Set Up Logins and Configure Horizon. Operation covers the OAP Init Job, Configure OAP, Scaling and Satellite. Upgrade has its own section with Upgrade and Version Compatibility, and there are two troubleshooting pages, one for Install and Startup and one for UI and Login.

Two of those entries deserve a note because they are the parts that go wrong in practice. The OAP Init Job is a Kubernetes Job that runs before the OAP starts, and it is what prepares storage, so an install that skips it produces an OAP that comes up and then cannot find its schemas. Satellite is a separate component that sits between the agents and the OAP and absorbs traffic bursts, and it is optional rather than part of the default deployment.

The repository layout is a chart directory, a docs directory, a test directory, a tools directory and a Makefile, which tells you the chart is tested rather than merely published.

## The three values that have no default

The Required values section is short and it is the part of the README that deserves close reading, because three values have no default and must be set explicitly on every install.

The first is oap.image.tag, the OAP docker image tag, with 11.0.0 as the example. The second is oap.storageType, the storage type of the OAP, with elasticsearch, postgresql and banyandb as the examples. The third is ui.image.tag, the Horizon UI docker image tag, with horizon-1.0.0 as the example.

The chart does not guess these, and the reason is worth understanding. The OAP and the UI are separately versioned artefacts with separately versioned tags, and a chart that pinned them would break the moment either moved ahead. Forcing the operator to state both means the OAP and the UI versions are always an explicit choice rather than an accident of chart defaults.

You can set them on the command line or put them in a values file and pass -f my-values.yaml, and the README says so directly. For anything beyond a first install, the values file is the better route, because it also lets you record the storage choice and the enabled components alongside the tags.

The storage choice is the one that shapes the deployment most, and the docs set out a path for each. Elasticsearch is the default backend and it needs its CRDs installed first, which the Quick Start page covers, along with the other chart sources including development snapshots and building from source.

## Running the install

The install command in the README is the canonical one:

```shell
helm install skywalking oci://docker.io/apache/skywalking-helm \
  --version 5.0.0 -n skywalking --create-namespace \
  --set oap.image.tag=11.0.0 \
  --set oap.storageType=banyandb \
  --set ui.image.tag=horizon-1.0.0 \
  --set elasticsearch.enabled=false \
  --set banyandb.enabled=true \
  --set banyandb.image.tag=0.11.0
```

Read it as a template rather than a command to paste. The chart is pulled as an OCI artefact from docker.io, pinned to version 5.0.0, and installed into a namespace called skywalking that is created as part of the command. The three required values are set explicitly, and then the last four lines do the work of selecting one storage backend over another by disabling Elasticsearch and enabling BanyanDB with its own image tag.

That enable and disable pattern is how the chart handles storage. Each backend has an enabled flag, and the one you choose gets enabled while the others are turned off, which is why the default Elasticsearch path needs no extra flags but a non-default path needs two.

If you prefer to keep configuration in a file rather than on the command line, the same values go into a values file passed with -f my-values.yaml.

The repository also documents where to get the chart from, including development snapshots and building from source, which matters if you need a version that has not been published yet or need to patch the chart.

## A fresh install has no login, and that is the surprising part

There is a paragraph in the README that deserves to be the first thing a new operator reads, because it describes a behaviour that will otherwise look like a bug.

A fresh install has no login. Horizon UI ships no default credentials and does not fail closed: the pod reports Ready and nobody can sign in until you configure users.

That is a deliberate design decision rather than an oversight, and the reason is stated. If the UI shipped with default credentials, anyone who could reach the endpoint would have access to your trace data until an operator noticed. Failing closed would mean the pod never went Ready, which would make an automated install look broken. Instead the pod comes up and the interface is unusable until users are configured, and the Set Up Logins page in the docs covers the procedure.

The distinction between the two failure modes is the interesting part of the design. An install that silently gives everyone access is a security problem. An install that silently never becomes ready is an operational problem that alerts on the page. This one chooses the second, and the readiness probe therefore tells you the pod started rather than that the installation is finished, which is a distinction worth internalising before you go looking for a login that does not exist yet.

## Packaging the chart, and the build tooling behind it

The Makefile shows how a release is produced, and one of its comments is a small lesson in portability.

The chart directory is chart/skywalking, and the version and name are read out of that directory's Chart.yaml rather than being duplicated in the Makefile, so there is one source of truth. The package target copies NOTICE and LICENSE into the chart directory, runs helm dep up and helm package, and then removes the copied files again so they do not linger in the working tree.

The clean target carries a long comment explaining a bug that was fixed. One rm, one list of operands. Repeating rm -rf on the continuation lines left those tokens sitting in the argument list: GNU rm permutes arguments so it happened to work, but BSD rm on macOS stops option parsing at the first operand, so -r never took effect and clean died on the first directory, taking release-src and release down with it, which depend on it.

That comment is a good indicator of the project's engineering habits. It documents the failure mode, the platform difference between GNU and BSD coreutils, and the reasoning behind the fix, which is more useful to a maintainer than a one-line change would be.

The release tags follow the chart version, with 5.0.0 from 2026-08-31, 4.9.0 from 2026-05-06 and 4.8.0 from 2025-12-25, so the chart and the SkyWalking release line move separately and the Version Compatibility page in the docs is what tells you which pair works.

## Where skywalking-helm is the wrong tool

Three limits are structural. The first is that this is a Kubernetes chart and nothing else. There is no Docker Compose path, no single-binary deployment, no static configuration file you can hand to an operator running the backend on a single VM. If your SkyWalking deployment target is not Kubernetes, this repository does not help you, and the difference in approach is that a chart expresses an opinionated topology of Kubernetes objects, workloads, services and jobs, which does not translate into a process running on one host.

The second is that the chart assumes the architectural decision is already made. Choosing between SkyWalking, Jaeger, OpenTelemetry Collector plus a backend, and a commercial APM is a decision about data model, storage and cost, and this chart is one implementation of a choice already made. There is nothing here to help you evaluate whether SkyWalking is right.

The third is that the storage options are not interchangeable. The chart lets you pick Elasticsearch, BanyanDB or PostgreSQL, but the operational burden of each is different, and the docs set out a separate path for each backend with its own prerequisites, including the Elasticsearch CRDs that have to be installed first. The chart hides the difference in the --set flags and exposes it in everything else, including the init job and the version compatibility matrix.

An alternative worth naming is a community chart with different defaults. The difference in approach there is about where the chart lives and who updates it, and for most operators the deciding factor is simply which one the SkyWalking documentation points at for the version they intend to run, since the version compatibility page in this repository's docs is the part that actually determines whether an upgrade will work.

## Conclusion

skywalking-helm suits an operator who has decided on SkyWalking's APM backend and wants a supported Kubernetes deployment rather than a hand-rolled set of manifests, since the chart, the storage options, the init job and the upgrade documentation are all in one place. It is the wrong tool if you are still choosing an APM system, because the chart assumes the choice has been made, and it is the wrong tool if you need a single-binary deployment outside Kubernetes. Verify first which storage backend you will run and that the OAP and UI image tags you set match each other, and note that a fresh install has no login at all until you configure users.

## FAQ

### What does the Apache SkyWalking Helm chart install?

It installs SkyWalking in a Kubernetes cluster, meaning the OAP backend and the Horizon UI, with Elasticsearch, BanyanDB or PostgreSQL as the storage backend, an OAP init job, and the optional Satellite component. The scripts are written in Helm 3.

### Which values must I set when installing skywalking-helm?

Three values have no default and must be set explicitly on every install: oap.image.tag for the OAP docker image tag, oap.storageType for the storage type of the OAP, and ui.image.tag for the Horizon UI docker image tag. You can set them on the command line or in a values file passed with -f my-values.yaml.

### How do I install SkyWalking with the Helm chart?

Run helm install skywalking oci://docker.io/apache/skywalking-helm with --version, a namespace and --create-namespace, then set oap.image.tag, oap.storageType, ui.image.tag and the enabled flags for the storage backend you want. The README example installs version 5.0.0 with BanyanDB enabled and Elasticsearch disabled.

### Why can I not sign in to Horizon UI after a fresh install?

A fresh install has no login. Horizon UI ships no default credentials and does not fail closed: the pod reports Ready and nobody can sign in until you configure users. The Set Up Logins page in the docs covers the procedure.

### What storage backends does the SkyWalking chart support?

Elasticsearch, BanyanDB and PostgreSQL. Elasticsearch is the default and its CRDs need to be installed first, and each backend has its own documentation page under docs/storage plus its own enabled flag and image tag.

### How is a release of the SkyWalking chart built?

The Makefile reads the version and name from chart/skywalking/Chart.yaml, copies NOTICE and LICENSE into the chart directory, runs helm dep up and helm package, and then removes the copied files again. The clean target also carries a comment explaining why rm -rf must take a single list of operands rather than repeated flags.

## Sources

- [apache/skywalking-helm on GitHub](https://github.com/apache/skywalking-helm)
- [License: Apache-2.0](https://github.com/apache/skywalking-helm/blob/master/LICENSE)
- [Project website](https://skywalking.apache.org/)
- [README](https://github.com/apache/skywalking-helm/blob/master/README.md)
- [Releases](https://github.com/apache/skywalking-helm/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/apache-skywalking-helm