apache / apache/skywalking

[Docs] Align BanyanDB cluster/discovery docs, drop etcd leftovers, and publish docs from a docs branch

Open
#14,081 0 comments 0 reactions 0 assignees View on GitHub
database documentation
Dominant language
Java
Stars
25k
Forks
6.6k
Avg merge
10h 5m
Merged PRs (30d)
16

Description

## Background

Follow-up from https://github.com/apache/skywalking/discussions/14077#discussioncomment-18431254: community hit contradictory port examples between the cluster install guide and the file-based discovery guide, and asked which gRPC port liaison should use.

Default `--grpc-port` for both `banyand data` and `banyand liaison` is **17912**. `18912` is only a common override when data and liaison share the same host/IP. Etcd-based discovery has been removed; docs still mention it in places.

## Tasks

### 1. Fix cluster / file-discovery port examples

- Align [installation/cluster](https://skywalking.apache.org/docs/skywalking-banyandb/latest/installation/cluster/) and [operation/node-discovery](https://skywalking.apache.org/docs/skywalking-banyandb/latest/operation/node-discovery/) so `nodes.yaml` / liaison examples are consistent.
- State clearly: default gRPC port is `17912` for data and liaison; when co-located on one IP, use different ports (e.g. data `17912`, liaison `18912`) and list the same ports in `nodes.yaml`.

### 2. Remove redundant etcd references from documentation

- Purge leftover etcd discovery / configuration / upgrade wording from BanyanDB docs (e.g. `docs/operation/node-discovery.md`, `docs/operation/upgrade.md`, and other hits under `docs/`).
- Keep only current discovery modes: `none`, `dns`, `file`.

### 3. Docs branch for continuous doc updates without a release

- Create and maintain a dedicated docs branch in https://github.com/apache/skywalking-banyandb (e.g. `docs` / `asf-site` workflow as appropriate) so documentation can be updated and published without waiting for an official BanyanDB release.
- Document how doc PRs should target that branch and how they reach skywalking.apache.org.

## Acceptance

- [ ] Port guidance is consistent across cluster + node-discovery docs
- [ ] No obsolete etcd discovery instructions remain in the published docs
- [ ] Docs branch exists and is the agreed path for mid-release doc fixes

Contributor guide

Open the contributing guide

Research direction

Start with docs/operation/node-discovery.md and docs/operation/upgrade.md, then search the other files under docs/ for the remaining etcd references. Compare the published installation/cluster and operation/node-discovery pages to align the port examples. Review the repository's existing publication workflow before proposing the docs branch path; done means consistent port guidance, no obsolete etcd instructions, and an agreed publishable branch workflow.

Written by the indexing model from the issue text.

Assessment

Domain
documentation, release
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.