Merge pull request #3807 from olamilekan000/update-doc-on-how-to-start-shard

add how to run a Shard to the docs

Author: kcp-ci-bot

docs/content/concepts/sharding/shards.md

@@ -1,12 +1,14 @@
 ---
 description: >
-    Horizontal Scaling of kcp through sharding
+  Horizontal Scaling of kcp through sharding
 ---
 
 # Shards
 
+To learn how to run a sharded environment for development, see [Running a Sharded Environment](../../developers/running-sharded.md).
+
 Every kcp shard is hosting a set of logical clusters. A logical cluster is
-identified by a globally unique identifier called a *cluster name*. A shard
+identified by a globally unique identifier called a **cluster name**. A shard
 serves the logical clusters under `/clusters/<cluster-name>`.
 
 A set of known shards comprises a kcp installation.
@@ -30,7 +32,7 @@ Logical clusters are defined through the existence of a `LogicalCluster` object
 "in themselves", similar to a `.` directory defining the existence of a directory
 in Unix.
 
-Every logical cluster name `name` is a *logical cluster path*. Every logical
+Every logical cluster name `name` is a **logical cluster path**. Every logical
 cluster is reachable through `/cluster/<path>` for every of their paths.
 
 A `Workspace` in `tenancy.kcp.io/v1alpha1` of name `name` references a logical
@@ -40,21 +42,21 @@ can be reached via a path `path:name`.
 
 ## Canonical Paths
 
-The longest path a logical cluster is reachable under is called the *canonical
-path*. By default, all canonical paths start with `root`, i.e. they start in
+The longest path a logical cluster is reachable under is called the **canonical
+path**. By default, all canonical paths start with `root`, i.e. they start in
 root logical cluster.
 
 The logical cluster object annotated with `kcp.io/path: <canonical-path>`.
 
 Additional subtrees of the workspace path hierarchy can be defined by creating
-logical clusters with `kcp.io/path` annotation *not* starting in `root`. E.g.
+logical clusters with `kcp.io/path` annotation _not_ starting in `root`. E.g.
 a home workspace hierarchy could start at `home:<user-name>`. There is no need
 for the parent (`home` in this case) to exist.
 
 ## Front Proxy
 
 A front-proxy is aware of all logical clusters, their shard they live on,
-their canonical paths and all `Workspaces`s. Non canonical paths can be
+their canonical paths and all `Workspaces`. Non canonical paths can be
 reconstructed from the canonical path prefixes and the workspace names.
 
 Requests to `/cluster/<path>` are forwarded to the shard via inverse proxying.

docs/content/developers/index.md

@@ -2,4 +2,6 @@
 
 This chapter covers developing controllers against kcp and hacking on kcp itself.
 
+- [Running a Sharded Environment](running-sharded.md)
+
 {% include "partials/section-overview.html" %}

docs/content/developers/running-sharded.md

@@ -0,0 +1,53 @@
+# Running a Sharded Environment
+
+This guide explains how to run a sharded kcp environment locally for development and testing purposes.
+
+## Using `sharded-test-server`
+
+The easiest way to stand up a sharded environment is using the `sharded-test-server` tool. This tool automates the creation of a root shard, additional shards, a front proxy, and all necessary certificates.
+
+### Prerequisites
+
+build the tool before running it:
+
+```bash
+make build WHAT=./cmd/sharded-test-server
+```
+
+### Running the Server
+
+To start a cluster with 2 shards (Shard-0/Root and Shard-1):
+
+```bash
+./bin/sharded-test-server --number-of-shards=2
+```
+
+This command will launch:
+
+- **Shard-0 (Root):** Hosting the root logical cluster and core APIs.
+- **Shard-1:** A secondary shard joined to the root.
+- **Front Proxy:** Handles routing requests to the appropriate shard.
+
+### Accessing the Cluster
+
+The tool generates several kubeconfig files in the current directory (or the path specified by `--work-dir-path`):
+
+- `.kcp/admin.kubeconfig`: **Primary Admin Access.** connects via the front-proxy. Use this for most operations.
+- `.kcp-0/admin.kubeconfig`: Direct access to Shard-0 (Root).
+- `.kcp-1/admin.kubeconfig`: Direct access to Shard-1.
+
+### Verification
+
+To verify that your shards are running and registered, query the `Shard` resources from the root shard:
+
+```bash
+KUBECONFIG=.kcp/admin.kubeconfig kubectl get shards
+```
+
+You should see both `root` (shard-0) and `shard-1` listed.
+
+```
+NAME      REGION      URL                      EXTERNAL URL             AGE
+root      us-east-2   https://127.0.0.1:6444   https://127.0.0.1:6443   111s
+shard-1   us-east-1   https://127.0.0.1:6445   https://127.0.0.1:6443   95s
+```