feat: added documentation; restructure installation components; added install scripts by ron96g · Pull Request #306 · telekom/controlplane

ron96g · 2026-03-31T13:27:56Z

Overhaul the documentation from a technology-focused structure (docs/pages/)
to a journey-based structure (docs/) organized around admin, user, and
developer workflows. Add comprehensive architecture documentation for all
domains.

Restructure install directory into base/overlays/components layout
Add admin journey docs (setup, environments, orgs, notifications, ops)
Add user journey docs (onboarding, APIs, events, approvals)
Add developer journey docs (contributing, operators, local dev)
Add architecture docs for all domains (admin, api, gateway, identity, etc.)
Add CRD reference generation scripts and remark plugin
Update CI workflows for new docs paths and enable deployment on feat branch
Simplify root README
Add local-setup script in hack/
Already published via https://telekom.github.io/controlplane/

Overhaul the documentation from a technology-focused structure (docs/pages/) to a journey-based structure (docs/) organized around admin, user, and developer workflows. Add comprehensive architecture documentation for all domains. - Restructure install directory into base/overlays/components layout - Add admin journey docs (setup, environments, orgs, notifications, ops) - Add user journey docs (onboarding, APIs, events, approvals) - Add developer journey docs (contributing, operators, local dev) - Add architecture docs for all domains (admin, api, gateway, identity, etc.) - Add CRD reference generation scripts and remark plugin - Update CI workflows for new docs paths and enable deployment on feat branch - Simplify root README - Add local-setup script in hack/

…teps 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

…n documentation

…eneration script Add @docusaurus/theme-mermaid for rendering Mermaid diagrams and @easyops-cn/docusaurus-search-local for offline search. Include a new script to generate JSON Schema files from CRD definitions and update .gitignore to exclude the generated output.

… Remote Organizations as planned Rename the user-journey features section for clarity and add "planned feature" notices to Remote Organizations across the admin architecture and reference pages. Add a resource hierarchy diagram to the components overview and remove the redundant feature-support-by-Rover-section table from the API reference. Remove the unused high-level architecture SVG.

Add a new "Platform Governance Features" section to the admin journey with documentation for API Categories, covering category creation, team restrictions, group prefix enforcement, and API linting. Add a JSON Schema reference page listing downloadable schemas for all CRDs with usage instructions for editor autocompletion.

Copilot

Pull request overview

This PR restructures the documentation site from a technology-oriented layout into a journey-based information architecture, while updating local installation overlays and samples to match the new install structure and docs paths.

Changes:

Reorganize and modernize the docs site structure/assets (including scripts and dependencies).
Refactor install/ into a base/overlays/components model and extend the local overlay with sample admin/org/rover resources.
Update various READMEs and sample manifests to reflect new paths (docs assets, install overlays).

Reviewed changes

Copilot reviewed 144 out of 191 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
`README.md`	Simplifies root README and updates logo path to new docs static location.
`rover-server/README.md`	Updates install overlay link to `install/overlays/default`.
`notification/config/samples/notification_v1_notificationtemplate.yaml`	Fixes logo asset URL to match new docs static path.
`install/overlays/local/kustomization.yaml`	Reworks local overlay to use `install/base`, adjusts module paths, and enables eventing component.
`install/overlays/local/README.md`	Adds local install documentation and command sequence for applying overlays/resources.
`install/overlays/local/secret-manager-config.yaml`	Formatting-only change in commented config example.
`install/overlays/local/resources/.gitignore`	Ignores locally-copied zone config files to reduce secret-leak risk.
`install/overlays/local/resources/admin/kustomization.yaml`	Adds admin resource bundle (environment + zones).
`install/overlays/local/resources/admin/environment.yaml`	Introduces Environment (and Namespace) sample manifest.
`install/overlays/local/resources/admin/zones/kustomization.yaml`	Adds zone resource bundle referencing local-copied zone configs.
`install/overlays/local/resources/admin/zones/dataplane1.example.yaml`	Adds example Zone manifest template for dataplane1.
`install/overlays/local/resources/admin/zones/dataplane2.example.yaml`	Adds example Zone manifest template for dataplane2.
`install/overlays/local/resources/admin/eventconfigs/README.md`	Adds eventconfig sample documentation.
`install/overlays/local/resources/admin/eventconfigs/kustomization.yaml`	Updates eventconfig resources list (now only dataplane1).
`install/overlays/local/resources/admin/eventconfigs/dataplane1.example.yaml`	Adds example EventConfig manifest template.
`install/overlays/local/resources/org/kustomization.yaml`	Adds org resource bundle (group + team).
`install/overlays/local/resources/org/group.yaml`	Adds sample Group manifest.
`install/overlays/local/resources/org/team.yaml`	Adds sample Team manifest.
`install/overlays/local/resources/rover/kustomization.yaml`	Adds rover sample bundle (ApiSpecification + Rover).
`install/overlays/local/resources/rover/apispec.yaml`	Adds sample ApiSpecification for the local journey.
`install/overlays/local/resources/rover/rover.yaml`	Adds sample Rover exposure/subscription resources.
`install/components/notificationtemplates/onboarding-template-mail.yaml`	Updates/adds notification template manifest (component-provided templates).
`docs/scripts/download-logos.sh`	Adds/updates logo download helper used by docs assets.
`docs/package.json`	Updates docs build dependencies for the new docs site setup.

Comments suppressed due to low confidence (1)

install/overlays/local/resources/admin/eventconfigs/kustomization.yaml:6

resources references dataplane1.yaml, but this directory only contains dataplane1.example.yaml (no dataplane1.yaml), so kustomize build/apply will fail. Either commit a real dataplane1.yaml, or switch the kustomization to reference the example file and/or document a copy step (and gitignore the copied file) similar to admin/zones/*.example.yaml.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-08T08:12:18Z

+# local zone configs copied from *.example.yaml templates (may contain secrets)
+admin/zones/dataplane1.yaml
+admin/zones/dataplane2.yaml


If admin/eventconfigs/dataplane*.yaml files are meant to be created locally from the *.example.yaml templates (they contain credentials/placeholders), they should also be gitignored like the zone configs to reduce the risk of committing secrets. Otherwise, consider committing non-secret sample dataplane*.yaml files and keeping them referenced by kustomize.

Copilot · 2026-04-08T08:12:19Z

+metadata:
+  labels:
+    cp.ei.telekom.de/environment: env
+  name: onboarded--mail
+  namespace: env
+spec:


These templates hardcode metadata.namespace: env and cp.ei.telekom.de/environment: env. Notifications resolve templates by looking them up in the current environment namespace (from context), so leaving this placeholder will cause template lookup to fail (and may fail apply if namespace env doesn't exist). Make the namespace/environment configurable (e.g., remove the explicit namespace so a parent kustomization can set it, or provide an overlay/patch example) and update all templates in this component consistently.

Copilot · 2026-04-08T08:12:19Z

+  "dependencies": {
+    "@docusaurus/core": "3.9.2",
+    "@docusaurus/preset-classic": "3.9.2",
+    "@docusaurus/theme-mermaid": "^3.9.2",
+    "@easyops-cn/docusaurus-search-local": "^0.55.1",
+    "@mdx-js/react": "^3.0.0",
+    "clsx": "^2.0.0",
+    "docusaurus-plugin-image-zoom": "^3.0.1",
+    "js-yaml": "^4.1.1",


@docusaurus/theme-mermaid is version-ranged (^3.9.2) while the core/preset packages are pinned to 3.9.2. This can lead to mismatched Docusaurus package versions after fresh installs. Prefer pinning all @docusaurus/* packages to the same exact version.

Copilot · 2026-04-08T08:12:20Z

+# Event Configuration
+
+This directory contains sample event configuration which are needed to enable the eventing feature in the controlplane.
+They are zone-specific and need to be applied in each zone where you want to use the eventing feature. 


Grammar: “sample event configuration which are needed” should be “sample event configurations that are needed” (or similar).

Agent-Logs-Url: https://github.com/telekom/controlplane/sessions/8ec344b1-cd24-4cb8-b6a0-d03a273be52e Co-authored-by: ron96g <46990708+ron96g@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 144 out of 191 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

install/overlays/local/resources/admin/eventconfigs/kustomization.yaml:6

kustomization.yaml references dataplane1.yaml, but this directory only contains dataplane1.example.yaml in the PR. As-is, kubectl apply -k install/overlays/local/resources/admin/eventconfigs will fail due to the missing file. Either add/rename the tracked file to dataplane1.yaml or update the kustomization to reference the .example.yaml (and document/ignore the local copy if it may contain secrets).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-08T12:00:58Z

+  // Fix links pointing to "roverctl" (the root command):
+  // In subcommand pages these become broken because the file is now index.md.
+  // Replace (roverctl) with (./) but only when it is an exact match — not a
+  // prefix like roverctl_apply.
+  if (!isRoot) {
+    transformed = transformed.replace(/\]\(roverctl\)/g, "](.)");
+  }


In subcommand pages, the script replaces links to (roverctl) with ](.), but the comment says it should become (./). (.) is not a valid relative link target in Markdown/Docusaurus and will likely produce broken links to the root command page. Update the replacement to a working relative target (e.g., ./ or ./index) and keep it consistent with how the root file is renamed to index.md.

Copilot · 2026-04-08T12:00:59Z

+This directory contains sample event configuration which are needed to enable the eventing feature in the controlplane.
+They are zone-specific and need to be applied in each zone where you want to use the eventing feature. 
+You can apply them after installing the controlplane components.


Grammar: "sample event configuration which are needed" should be plural/agree (e.g., "sample event configurations that are needed"). Also consider consistently spelling the product name as "Control Plane" in prose (currently "controlplane").

stefan-ctrl

Overall create documentation +1

Could we perhabs improve some broken links? Otherwise, I fould feel confident merging it, and further improving it over time

stefan-ctrl · 2026-04-13T08:02:41Z

+- **Go 1.25.8** — the primary language for all operators and services
+- **Kubebuilder 4.9.0** — scaffolding and code generation for Kubernetes operators


We should not add this here, and instead link to our main ./contributing.md in the root-repo paths, so that we do not double this information.

stefan-ctrl · 2026-04-13T08:04:16Z

+### Operators
+
+These are Kubebuilder-scaffolded controllers, each managing a specific domain:
+
+`admin/` · `api/` · `application/` · `approval/` · `event/` · `gateway/` · `identity/` · `notification/` · `organization/` · `pubsub/` · `rover/`
+
+### Services
+
+Backend services that are not Kubernetes operators:
+
+`common-server/` · `controlplane-api/` · `rover-server/` · `secret-manager/` · `file-manager/`


Perhabs be a little bit more abstract and only name them as examples, so that we are more flexible adding new ones, without needing to up this part of the doc?

stefan-ctrl · 2026-04-13T08:05:11Z

+### End-to-End Tests
+
+```bash
+make test-e2e
+```
+
+Runs [Ginkgo](https://onsi.github.io/ginkgo/) tests against a Kind cluster.


Since we do not have general e2e tests per domain right now, should be perhabs remove that for now?

stefan-ctrl · 2026-04-13T08:10:51Z

@@ -4,4 +4,3 @@

 resources:
  - dataplane1.yaml


Unrelated, but dataplane1.yaml does not exists.

Instead it should be dataplane1.example.yaml

The example is not useable so this was actually intentional that people copy it and fill in the required values. That the problem with the CP that we cannot provide easy-to-use defaults

stefan-ctrl · 2026-04-13T08:15:46Z

+    payloadType: Data
+    callback: https://analytics.internal:8080/events
+    trigger:
+      responseFilterMode: INCLUDE


https://github.com/telekom/controlplane/blob/feat%2Fdocumentation/event/config/crd/bases/event.cp.ei.telekom.de_eventexposures.yaml#L156-L158:

Uses responseFilterMode: INCLUDE / EXCLUDE (uppercase). CRD validation expects Include / Exclude (PascalCase). The mapper does a direct cast with no normalization, so uppercase values would fail CRD validation.

stefan-ctrl · 2026-04-13T08:16:55Z

+| ----- | ----------- |
+| `security.type` | The authentication method. Use `oauth2` for OAuth2-based authentication or `basicAuth` for username/password authentication. |
+| `security.tokenEndpoint` | The OAuth2 token endpoint URL. Required when using an external identity provider. |
+| `security.grantType` | The OAuth2 grant type. Supported values: `CLIENT_CREDENTIALS`, `PASSWORD`, `REFRESH_TOKEN`. |


https://github.com/telekom/controlplane/blob/feat%2Fdocumentation/api/api/v1/security_types.go#L74

Lists REFRESH_TOKEN as a valid grantType but the CRD enum is client_credentials;authorization_code;password. refresh_token would fail validation. Also omits AUTHORIZATION_CODE which is a valid CRD value.

stefan-ctrl · 2026-04-13T08:17:50Z

+## Feature Architecture
+
+The Gateway operator uses a plugin-based feature system for configuring route behavior:
+
+| Feature | Description |
+| ------- | ----------- |
+| **PassThrough** | Basic request forwarding. |
+| **AccessControl** | Consumer-based access control. |
+| **RateLimit** | Request rate limiting via Redis. |
+| **ExternalIDP** | External identity provider authentication. |
+| **CustomScopes** | Fine-grained OAuth2 scope enforcement. |
+| **LastMileSecurity** | End-to-end security in cross-mesh scenarios. |


Are not all features here listed by design?

- Remove hardcoded version numbers and e2e test references from local development guide - Fix enum casing (Include/Exclude) in event filtering docs and remove unsupported REFRESH_TOKEN grant type - Replace gateway feature table with prose description - Pin @docusaurus/theme-mermaid version and fix CLI docs link generation - Standardize notification templates: use kustomize managed-by label, remove hardcoded namespace - Update install overlay links, gitignore patterns, and minor wording

ron96g had a problem deploying to github-pages March 31, 2026 13:29 — with GitHub Actions Failure

ron96g temporarily deployed to github-pages March 31, 2026 13:31 — with GitHub Pages Inactive

ron96g temporarily deployed to github-pages March 31, 2026 13:32 — with GitHub Actions Inactive

ron96g self-assigned this Mar 31, 2026

ron96g temporarily deployed to github-pages April 2, 2026 11:27 — with GitHub Pages Inactive

Merge branch 'main' into feat/documentation

57a0076

ron96g temporarily deployed to github-pages April 2, 2026 11:28 — with GitHub Pages Inactive

ron96g temporarily deployed to github-pages April 2, 2026 11:29 — with GitHub Actions Inactive

docs: update sidebar positions for event exposure and API subscriptio…

6be3661

…n documentation

ron96g temporarily deployed to github-pages April 2, 2026 13:39 — with GitHub Pages Inactive

ron96g temporarily deployed to github-pages April 2, 2026 13:39 — with GitHub Actions Inactive

ron96g added 3 commits April 8, 2026 09:30

ron96g temporarily deployed to github-pages April 8, 2026 07:32 — with GitHub Pages Inactive

ron96g temporarily deployed to github-pages April 8, 2026 07:33 — with GitHub Actions Inactive

ron96g marked this pull request as ready for review April 8, 2026 08:02

Copilot AI review requested due to automatic review settings April 8, 2026 08:02

Merge branch 'main' into feat/documentation

5fc946e

Copilot started reviewing on behalf of ron96g April 8, 2026 08:03 View session

ron96g temporarily deployed to github-pages April 8, 2026 08:03 — with GitHub Pages Inactive

Copilot AI reviewed Apr 8, 2026

View reviewed changes

ron96g temporarily deployed to github-pages April 8, 2026 08:17 — with GitHub Actions Inactive

ron96g requested review from BjoernKarma, lukas016 and stefan-ctrl April 8, 2026 08:18

ron96g requested review from iagarba, julius-malcovsky, stefan-ctrl and twacht April 8, 2026 08:18

ron96g commented Apr 8, 2026

View reviewed changes

Comment thread .github/workflows/docs-deploy.yaml

Copilot started work on behalf of ron96g April 8, 2026 11:55 View session

ron96g requested a review from Copilot April 8, 2026 11:55

ci: add main branch to docs-deploy workflow triggers

9f74e9d

Agent-Logs-Url: https://github.com/telekom/controlplane/sessions/8ec344b1-cd24-4cb8-b6a0-d03a273be52e Co-authored-by: ron96g <46990708+ron96g@users.noreply.github.com>

Copilot started reviewing on behalf of ron96g April 8, 2026 11:56 View session

github-pages Bot temporarily deployed to github-pages April 8, 2026 11:56 Inactive

Copilot AI changed the title ~~docs: restructure documentation site with journey-based architecture~~ ci: trigger docs deployment on main branch Apr 8, 2026

Copilot finished work on behalf of ron96g April 8, 2026 11:57

Copilot AI temporarily deployed to github-pages April 8, 2026 11:58 Inactive

Copilot AI reviewed Apr 8, 2026

View reviewed changes

ron96g changed the title ~~ci: trigger docs deployment on main branch~~ feat: added documentation; restructure installation components; added install scripts Apr 10, 2026

stefan-ctrl requested changes Apr 13, 2026

View reviewed changes

ron96g temporarily deployed to github-pages April 13, 2026 10:11 — with GitHub Pages Inactive

ron96g temporarily deployed to github-pages April 13, 2026 10:12 — with GitHub Actions Inactive

ron96g added documentation Improvements or additions to documentation enhancement New feature or request labels Apr 13, 2026

stefan-ctrl approved these changes Apr 14, 2026

View reviewed changes

ron96g merged commit 27478bb into main Apr 15, 2026
132 of 143 checks passed

ron96g deleted the feat/documentation branch April 15, 2026 07:41

		- Go 1.25.8 — the primary language for all operators and services
		- Kubebuilder 4.9.0 — scaffolding and code generation for Kubernetes operators

Conversation

ron96g commented Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

stefan-ctrl left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

ron96g commented Mar 31, 2026 •

edited

Loading