feat(scripts): introduce modular, multi-region playground management (#33)

This overhauls the playground management scripts to provide a more flexible,
powerful, and maintainable user experience. The entire workflow, from setup to
teardown, is now dynamic and customizable.

Key changes include:

- **Multi-Region Support**: `setup.sh` now accepts a list of region names as
  arguments to provision multiple, isolated Kubernetes clusters and MinIO
  instances. It defaults to 'eu' and 'us' if no arguments are provided, for
  back-compatibility.
- **New Teardown Script**: Adds a new `teardown.sh` script for cleanup. It
  operates in two modes:

  - Auto-detects and removes all managed clusters if run without arguments.
  - Selectively removes specific clusters when region names are provided.

- **Auto-Discovery**: `info.sh` now automatically discovers all running
  playground clusters created by the setup script, removing the need for manual
  input.

- **Modularization**: Introduces a `common.sh` file to centralize shared
  configurations, prerequisite checks, and functions. This reduces code
  duplication and simplifies the `setup`, `info`, and `teardown` scripts.

Closes #32

Signed-off-by: Gabriele Bartolini <[email protected]>

Author: gbartolini

README.md

@@ -58,28 +58,52 @@ The architecture is illustrated in the diagram below:
 
 ![Local Environment Architecture](images/cnpg-playground-architecture.png)
 
-## Setting Up the Learning Environment
+## Usage
 
-To set up the environment, simply run the following script:
+This playground environment is managed by three main scripts located in the
+`/scripts` directory.
+
+| Script       | Description                                                  |
+| :----------- | :----------------------------------------------------------- |
+| `setup.sh`   | Creates and configures the multi-region Kubernetes clusters. |
+| `info.sh`    | Displays status and access information for active clusters.  |
+| `teardown.sh`| Removes clusters and all associated resources.               |
+
+### Setting Up the Learning Environment
+
+The `setup.sh` script provisions the entire environment. By default, it creates
+two regional clusters: `eu` and `us`.
 
 ```bash
+# Create the default two-region environment (eu, us)
 ./scripts/setup.sh
 ```
 
-## Connecting to the Kubernetes Clusters
+You can easily customize this by providing your own list of region names as
+arguments.
+
+```bash
+# Create a custom environment with 'it' and 'de' regions, simulating Italy and Germany
+./scripts/setup.sh it de
+
+# Create a single-region environment
+./scripts/setup.sh local
+```
+
+### Connecting to the Kubernetes Clusters
 
 To configure and interact with both Kubernetes clusters during the learning
-process, you will need to connect to them.
+process, you will need to connect to them. After setup, you can run the
+`info.sh` script at any time to see the status of your environment.
 
-The **setup** script provides detailed instructions for accessing the clusters.
-If you need to view the connection details again after the setup, you can
-retrieve them by running:
+It automatically detects all running playground clusters and displays their
+access instructions, and node status.
 
 ```bash
 ./scripts/info.sh
 ```
 
-## Inspecting Nodes in a Kubernetes Cluster
+### Inspecting Nodes in a Kubernetes Cluster
 
 To inspect the nodes in a Kubernetes cluster, you can use the following
 command:
@@ -93,19 +117,43 @@ output similar to:
 
 ```console
 NAME                   STATUS   ROLES           AGE     VERSION
-k8s-eu-control-plane   Ready    control-plane   10m     v1.33.0
-k8s-eu-worker          Ready    infra           9m58s   v1.33.0
-k8s-eu-worker2         Ready    app             9m58s   v1.33.0
-k8s-eu-worker3         Ready    postgres        9m58s   v1.33.0
-k8s-eu-worker4         Ready    postgres        9m58s   v1.33.0
-k8s-eu-worker5         Ready    postgres        9m58s   v1.33.0
+k8s-eu-control-plane   Ready    control-plane   10m     v1.34.0
+k8s-eu-worker          Ready    infra           9m58s   v1.34.0
+k8s-eu-worker2         Ready    app             9m58s   v1.34.0
+k8s-eu-worker3         Ready    postgres        9m58s   v1.34.0
+k8s-eu-worker4         Ready    postgres        9m58s   v1.34.0
+k8s-eu-worker5         Ready    postgres        9m58s   v1.34.0
 ```
 
 In this example:
 - The control plane node (`k8s-eu-control-plane`) manages the cluster.
 - Worker nodes have different roles, such as `infra` for infrastructure, `app`
   for application workloads, and `postgres` for PostgreSQL databases. Each node
-  runs Kubernetes version `v1.33.0`.
+  runs Kubernetes version `v1.34.0`.
+
+### Cleaning Up the Environment
+
+When you're finished, the `teardown.sh` script can remove the resources. It can
+be run in two ways:
+
+#### Full Cleanup
+
+Running the script with no arguments will auto-detect and remove all playground
+clusters and their resources, returning your system to its initial state.
+
+```bash
+# Destroy all created regions
+./scripts/teardown.sh
+```
+
+#### Selective Cleanup
+
+You can also remove specific clusters by passing the region names as arguments.
+
+```bash
+# Destroy only the 'it' cluster
+./scripts/teardown.sh it
+```
 
 ## Demonstration with CNPG Playground
 
@@ -121,8 +169,8 @@ distributed across two regions** within the playground. The symmetric
 architecture also includes **continuous backup** using the
 [Barman Cloud Plugin](https://cloudnative-pg.io/plugin-barman-cloud/).
 
-For complete instructions and supporting resources, refer to the [demo
-folder](./demo/README.md).
+For complete instructions and supporting resources, refer to the
+[demo folder](./demo/README.md).
 
 ## Installing CloudNativePG on the Control Plane
 
@@ -149,50 +197,6 @@ both the `kind-k8s-eu` and `kind-k8s-us` clusters.
 Ensure that you have the latest version of the `cnpg` plugin installed on your
 local machine.
 
-## Cleaning up the Learning Environment
-
-When you're ready to clean up and remove all resources from the learning
-environment, run the following script to tear down the containers and
-associated resources:
-
-```bash
-./scripts/teardown.sh
-```
-
-This will safely destroy all running containers and return your environment to
-its initial state.
-
-## Single Kubernetes Cluster Setup
-
-In some situations, you may prefer to have a single Kubernetes cluster
-playground without the object store. To create such a cluster, run the
-following command:
-
-```sh
-kind create cluster --config k8s/kind-cluster.yaml
-```
-
-Then, run:
-
-```sh
-kubectl label node -l postgres.node.kubernetes.io node-role.kubernetes.io/postgres=
-kubectl label node -l infra.node.kubernetes.io node-role.kubernetes.io/infra=
-kubectl label node -l app.node.kubernetes.io node-role.kubernetes.io/app=
-```
-
-The result is the following:
-
-```console
-$ kubectl get nodes
-NAME                 STATUS   ROLES           AGE   VERSION
-cnpg-control-plane   Ready    control-plane   22m   v1.33.0
-cnpg-worker          Ready    infra           22m   v1.33.0
-cnpg-worker2         Ready    app             22m   v1.33.0
-cnpg-worker3         Ready    postgres        22m   v1.33.0
-cnpg-worker4         Ready    postgres        22m   v1.33.0
-cnpg-worker5         Ready    postgres        22m   v1.33.0
-```
-
 ## Nix Flakes
 
 Do you use Nix flakes? If you do, this package have a configured

scripts/common.sh

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+#
+# This script contains common variables and functions shared by the setup,
+# info, and cleanup scripts for the CloudNativePG playground.
+#
+#
+# Copyright The CloudNativePG Contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+set -euo pipefail
+
+# --- Common Configuration ---
+# Kind base name for clusters
+K8S_BASE_NAME=${K8S_NAME:-k8s}
+
+# MinIO Configuration
+MINIO_IMAGE="${MINIO_IMAGE:-quay.io/minio/minio:RELEASE.2025-09-07T16-13-09Z}"
+MINIO_BASE_NAME="${MINIO_BASE_NAME:-minio}"
+MINIO_BASE_PORT=${MINIO_BASE_PORT:-9001}
+MINIO_ROOT_USER="${MINIO_ROOT_USER:-cnpg}"
+MINIO_ROOT_PASSWORD="${MINIO_ROOT_PASSWORD:-Cl0udNativePGRocks}"
+
+# --- Common Prerequisite Checks ---
+REQUIRED_COMMANDS="kind kubectl git grep sed"
+for cmd in $REQUIRED_COMMANDS; do
+    if ! command -v "$cmd" &> /dev/null; then
+        echo "❌ Error: Missing required command: $cmd"
+        exit 1
+    fi
+done
+
+# --- Common Setup ---
+# Find a supported container provider
+CONTAINER_PROVIDER=""
+for provider in docker podman; do
+    if command -v "$provider" &> /dev/null; then
+        CONTAINER_PROVIDER=$provider
+        break
+    fi
+done
+
+if [ -z "${CONTAINER_PROVIDER:-}" ]; then
+    echo "❌ Error: Missing container provider. Supported providers are: docker, podman"
+    exit 1
+fi
+
+# Determine project root and kubeconfig path
+GIT_REPO_ROOT=$(git rev-parse --show-toplevel)
+KUBE_CONFIG_PATH="${GIT_REPO_ROOT}/k8s/kube-config.yaml"

scripts/info.sh

@@ -1,5 +1,8 @@
 #!/usr/bin/env bash
 #
+# This script automatically detects running CloudNativePG playground clusters
+# and displays their status, including version, nodes, and pods.
+#
 # Copyright The CloudNativePG Contributors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -15,23 +18,60 @@
 # limitations under the License.
 #
 
-set -eu
-
-git_repo_root=$(git rev-parse --show-toplevel)
-kube_config_path=${git_repo_root}/k8s/kube-config.yaml
-
-cat <<EOF
-To access the playground clusters, ensure you set the following environment
-variable:
+# Source the common setup script
+source "$(dirname "$0")/common.sh"
 
-export KUBECONFIG=${kube_config_path}
+# --- Script Setup ---
+if [ ! -f "${KUBE_CONFIG_PATH}" ]; then
+    echo "❌ Error: Kubeconfig file not found at '${KUBE_CONFIG_PATH}'"
+    echo "Please run the setup.sh script first."
+    exit 1
+fi
+export KUBECONFIG="${KUBE_CONFIG_PATH}"
 
-To switch between clusters, use the commands below:
+# --- Auto-detect Regions ---
+echo "🔎 Detecting active playground clusters..."
+REGIONS=($(kind get clusters | grep "^${K8S_BASE_NAME}-" | sed "s/^${K8S_BASE_NAME}-//" || true))
 
-kubectl config use-context kind-k8s-eu
-kubectl config use-context kind-k8s-us
+if [ ${#REGIONS[@]} -eq 0 ]; then
+    echo "🤷 No active playground clusters found with the prefix '${K8S_BASE_NAME}-'."
+    exit 0
+fi
+echo "✅ Found regions: ${REGIONS[*]}"
 
-To check which cluster you’re currently connected to:
+# --- Access Instructions ---
+echo
+echo "--------------------------------------------------"
+echo "🕹️  Cluster Access Instructions"
+echo "--------------------------------------------------"
+echo
+echo "To access your playground clusters, first set the KUBECONFIG environment variable:"
+echo "export KUBECONFIG=${KUBE_CONFIG_PATH}"
+echo
+echo "Available cluster contexts:"
+for region in "${REGIONS[@]}"; do
+    echo "  • kind-${K8S_BASE_NAME}-${region}"
+done
+echo
+echo "To switch to a specific cluster (e.g., the '${REGIONS[0]}' region), use:"
+echo "kubectl config use-context kind-${K8S_BASE_NAME}-${REGIONS[0]}"
+echo
 
-kubectl config current-context
-EOF
+# --- Main Info Loop ---
+echo "--------------------------------------------------"
+echo "ℹ️  Cluster Information"
+echo "--------------------------------------------------"
+for region in "${REGIONS[@]}"; do
+    CONTEXT="kind-${K8S_BASE_NAME}-${region}"
+    echo
+    echo "🔷 Cluster: ${CONTEXT}"
+    echo "==================================="
+    echo "🔹 Version:"
+    kubectl --context "${CONTEXT}" version
+    echo
+    echo "🔹 Nodes:"
+    kubectl --context "${CONTEXT}" get nodes -o wide
+    echo
+    echo "🔹 Secrets:"
+    kubectl --context "${CONTEXT}" get secrets
+done