[RFC] Repository architecture and structure proposal

[jpmewenemesse]

As we move forward with the helm-handbook repo, we need to align on its structure before content contribution begins at scale.
This issue is an open RFC (Request for Comments) to collect architecture and implementation proposals from team members.

Goal

Define the directory structure and organization conventions for helm-handbook, covering at minimum:

• How modules values files are organized
• How environement-specific values are handled (sandbox, integration...)
• Where post-install manifests live
• How documentation (READMEs, install guides) is structured across the repo

How to contribute

• Open a PR referencing this issue with your proposed structure (diagram, draft etc...)
• Comment directly on this issue to discuss trade-offs

All proposals will be reviewed collectively before a structure is adopted.

[jpmewenemesse]

Here is my proposal for the helm-handbook repository structure. If this is ok for you, we can start creating stuffs on differents PR and issues.

The structure organizes the repo around a modules directory with two sub-categories:

• modules/apps: One folder per data component (trino, jupyterhub, airflow, etc.) each with environnement-specific values and README
• modules/prerequisites: Infrastructure layer with a Helm umbrella Chart.yaml, environnement values, and post-install manifests

A root README.md serves as the full ordered install guide.

[PaulFarault]

This work should be inspired by the KuboCD packages that have been created for the okdp-sandbox (which is now based on the platform-packages).

Starting with the prerequisites ("system" packages in platform-packages), KuboCD packages already define a dependency tree that we should follow. I compiled it in a diagram to help visualize it:

flowchart LR
  certManager["<b>certManager</b><br />(<a href="https://github.com/OKDP/platform-packages/tree/main/packages/system/cert-manager">cert-manager</a>)"]
  pgOperator["<b>pg-operator</b><br />(<a href="https://github.com/OKDP/platform-packages/tree/main/packages/system/cloudnative-pg">cloudnative-pg</a>)"]
  externalSecrets["<b>external-secrets</b><br />(<a href="https://github.com/OKDP/platform-packages/tree/main/packages/system/local-secrets-provider">local-secrets-provider</a>)"]
  databaseServer["<b>database-server</b><br />(<a href="https://github.com/OKDP/platform-packages/tree/main/packages/system/cnpg-postgresql">cnpg-postgresql</a>)"]
  coredns["<b>coredns</b><br />(<a href="https://github.com/OKDP/platform-packages/tree/main/packages/system/coredns-patch">coredns-patch</a>)"]
  dnsServer["<b>dns-server</b><br />(<a href="https://github.com/OKDP/platform-packages/tree/main/packages/system/dns-server">dns-server</a>)"]
  ingress["<b>ingress</b><br />(<a href="https://github.com/OKDP/platform-packages/tree/main/packages/system/ingress-nginx">ingress-nginx</a>)"]
  identity["<b>identity</b><br />(<a href="https://github.com/OKDP/platform-packages/tree/main/packages/system/keycloak">keycloak</a>)"]
  okdpServer["<b>okdp-server</b><br />(<a href="https://github.com/OKDP/platform-packages/tree/main/packages/system/okdp-server">okdp-server</a>)"]
  okdpUi["<b>okdp-ui</b><br />(<a href="https://github.com/OKDP/platform-packages/tree/main/packages/system/okdp-ui">okdp-ui</a>)"]
  tools["<b>tools</b><br />(<a href="https://github.com/OKDP/platform-packages/tree/main/packages/system/tools">tools</a>)"]
  kubocdWebhooks["<a href="https://github.com/OKDP/platform-packages/tree/main/packages/system/kubocd-webhooks">kubocd-webhooks</a>"]
  tools --> externalSecrets
  externalSecrets --> databaseServer
  pgOperator --> databaseServer
  externalSecrets --> identity
  databaseServer --> identity
  ingress --> identity
  identity --> okdpServer
  ingress --> okdpServer
  okdpServer --> okdpUi
  certManager --> kubocdWebhooks

Loading

As Helm handbook do not use KuboCD directly, we won't have to migrate kubocd-webhooks, okdp-server and okdp-ui for now.

Here is the list of packages that we may want to migrate. I'll create specific issues for each of them:

• Initialize prerequisites/tools values file and documentation #6
• Initialize prerequisites/coredns-patch values file and documentation #7
• Initialize prerequisites/dns-server values file and documentation #8
• Initialize prerequisites/cert-manager values file and documentation #9
• Initialize prerequisites/pg-operator values file and documentation #10
• Initialize prerequisites/ingress values file and documentation #11
• Initialize prerequisites/local-secrets-provider values file and documentation #12
• Initialize prerequisites/database-server values file and documentation #13
• Initialize prerequisites/identity values file and documentation #14