docs: expand admin journey with quickstart, installation, and first-steps guides; add install overlay improvements

- Replace setup.md with separate quickstart (Kind) and installation (ArgoCD) guides
- Add first-steps tutorial for bootstrapping environment, zones, teams, and sample APIs
- Expand environments-and-zones with zone setup details and EventConfig configuration
- Rewrite notification-templates with selection logic, placeholders, and troubleshooting
- Add user-journey features section (traffic management, security, event delivery, filtering)
- Add secret-manager architecture page and update resource specs
- Add Kustomize component with default notification templates
- Rename zone files to .example.yaml; add EventConfig examples for local overlay
- Fix install path in .releaserc.mjs; remove deprecated install.sh

Author: ron96g

.github/scripts/update_install.sh

@@ -5,8 +5,8 @@
 # SPDX-License-Identifier: Apache-2.0
 
 # This script should only be run in a CI environment when a new release is created.
-# It will update the install-files to point to the newly released version.
-# See `.releaserc.mjs` for more information on how its integrated with semantic-release.
+# It updates the install overlay references to the newly released version.
+# See `.releaserc.mjs` for integration with semantic-release.
 
 set -e
 
@@ -18,4 +18,4 @@ if [ -z "$NEXT_VERSION" ]; then
 fi
 
 sed -i "s/ref=[^ ]*/ref=${NEXT_VERSION}/" "$KUSTOMIZATION_FILE"
-sed -i "s/newTag: [^ ]*/newTag: ${NEXT_VERSION}/" "$KUSTOMIZATION_FILE"
+sed -i "s/newTag: [^ ]*/newTag: ${NEXT_VERSION}/" "$KUSTOMIZATION_FILE"

.github/workflows.md

@@ -171,23 +171,23 @@ The repository uses a **unified versioning approach** where all modules and Helm
 
 #### **Versioning Scripts** (`.github/scripts/`)
 
-Two scripts ensure consistent versioning across the monorepo:
+Two scripts ensure consistent versioning across install overlays and Helm charts:
 
-1. **`update_chart_version.sh`**
+1. **`update_install.sh`**
+   - Updates `install/overlays/default/kustomization.yaml` to the newly released tag
+   - Rewrites both remote `ref` values and image `newTag` values
+   - Called by semantic-release during the prepare phase
+
+2. **`update_chart_version.sh`**
    - Updates `version` and `appVersion` in Helm Chart.yaml files
    - Called by semantic-release during the prepare phase
    - Example: Updates `common-server/helm/Chart.yaml`
 
-2. **`update_install.sh`**
-   - Updates the install kustomization file with new version references
-   - Modifies `install/overlays/default/kustomization.yaml` to point to the new release tag
-   - Updates both `ref` and `newTag` fields
-
 #### **Integration with Semantic Release**
 
 These scripts are executed automatically during the release process via `.releaserc.mjs`:
 - Runs during the `prepare` phase before creating the release
-- Updates version references in install files and Helm charts
+- Updates version references in install overlays and Helm charts
 - Commits changes back to the repository
 - Modified files: `CHANGELOG.md`, `install/overlays/default/kustomization.yaml`, `common-server/helm/Chart.yaml`
 

.releaserc.mjs

@@ -31,9 +31,9 @@ EOF`,
         ['@semantic-release/git', {
             assets: [
                 'CHANGELOG.md',
-                'install/kustomization.yaml',
+                'install/overlays/default/kustomization.yaml',
                 'common-server/helm/Chart.yaml',
             ],
         }],
     ],
-};
+};

docs/docs/admin-journey/environments-and-zones.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 2
+sidebar_position: 4
 ---
 
 # Environments & Zones
@@ -32,6 +32,20 @@ A Zone represents a physical or logical deployment target within an environment.
 
 Zones are the key building block for multi-cloud deployments. You can have zones pointing to different cloud providers (for example, one zone on AWS and another on Azure), and the Control Plane will manage API routing and event meshing across them.
 
+### How a Zone is Set Up
+
+Each zone is expected to have:
+
+- **1 Gateway instance** — used for API routing and policy enforcement in that zone
+- **1 Identity Provider (IDP) instance** — used for authentication and client management in that zone
+
+By default, the current platform setup uses:
+
+- **Kong** as the gateway, typically deployed with Helm via [`gateway-kong-charts`](https://github.com/telekom/gateway-kong-charts)
+- **Keycloak** as the IDP, typically deployed with Helm via [`identity-iris-keycloak-charts`](https://github.com/telekom/identity-iris-keycloak-charts)
+
+When creating the Zone resource in the Control Plane, you provide the connection details for exactly these zone-local instances (gateway + IDP). This keeps each zone self-contained and allows different zones to use separate runtime endpoints if needed.
+
 ### Creating a Zone
 
 A Zone references the gateway and identity provider to use, along with Redis configuration and visibility settings:
@@ -94,6 +108,81 @@ spec:
     namespace: dev
 ```
 
+## Event Config
+
+:::info
+Before creating an `EventConfig`, make sure the eventing subsystem is enabled in your Control Plane installation. Follow the steps in [Installation](./installation.md#optional-enable-the-eventing-subsystem).
+:::
+
+After a zone is created, eventing is still not active for that zone by default. To enable the event feature, create an `EventConfig` resource for the zone.
+
+`EventConfig` is the zone-level setup for the Event domain. It bootstraps the required event infrastructure in that zone (for example gateway routes, identity clients, and event store wiring).
+
+### What `EventConfig` does
+
+When an `EventConfig` is reconciled, the event controller prepares core building blocks used by event publishers and subscribers:
+
+- **Identity clients** for event administration and cross-zone mesh communication
+- **EventStore** connection used by the pub/sub runtime
+- **Gateway routes and URLs** for publishing, callbacks, and (optionally) Voyager APIs
+
+### Creating an `EventConfig`
+
+Apply one `EventConfig` per zone:
+
+```yaml
+apiVersion: event.cp.ei.telekom.de/v1
+kind: EventConfig
+metadata:
+  name: dataplane1-event-config
+  namespace: dev
+spec:
+  zone:
+    name: dataplane1
+    namespace: dev
+  admin:
+    url: https://config-backend.example.com
+    client:
+      clientId: event-admin
+      clientSecret: <your-event-admin-secret>
+  serverSendEventUrl: http://event-backend.dev.svc.cluster.local/sse
+  publishEventUrl: http://event-backend.dev.svc.cluster.local/publish
+  voyagerApiUrl: http://voyager.dev.svc.cluster.local
+  mesh:
+    fullMesh: true
+    client:
+      clientId: event-mesh
+      clientSecret: <your-event-mesh-secret>
+```
+
+### Mesh configuration options
+
+- **`fullMesh: true`** — events can be distributed across all zones.
+- **`fullMesh: false` + `zoneNames`** — events are only distributed to selected zones.
+
+Example for partial mesh:
+
+```yaml
+mesh:
+  fullMesh: false
+  zoneNames:
+    - dataplane2
+    - dataplane3
+  client:
+    clientId: event-mesh
+    clientSecret: <your-event-mesh-secret>
+```
+
+### Verifying readiness
+
+After creation, the resource status is populated with generated references and URLs (for example `publishUrl`, `callbackUrl`, and `eventStore`).
+
+If these fields appear and conditions are healthy, your zone is ready for event exposures and subscriptions.
+
+:::caution
+Do not commit secrets (for example `clientSecret`) to version control. Use your platform's secret management approach.
+:::
+
 ## Next Steps
 
 - [Organizations & Teams](./organizations-and-teams.md) — Set up teams within your environments