Skip to content

Commit fbc8ce0

Browse files
wchomikwchomik
committed
Updated README.md
1 parent 4696958 commit fbc8ce0

File tree

1 file changed

+138
-2
lines changed

1 file changed

+138
-2
lines changed

‎README.md‎

Lines changed: 138 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,11 +4,147 @@
44

55
## About this project
66

7-
Helm charts for Cloud Orchestrator MCP using building blocks
7+
This repository contains [umbrella helm charts](https://helm.sh/docs/howto/charts_tips_and_tricks/#complex-charts-with-many-dependencies) of the [Open Managed Control Plane (openMCP) Project](https://github.com/openmcp-project/) which are leveraging the Helm Charts of the [building blocks](https://github.com/openmcp-project/blueprint-building-blocks) to give **you** a big jump start in your [Infrastructure as Data]() Cloud Journey.
88

99
## Requirements and Setup
1010

11-
*Insert a short description what is required to get your project running...*
11+
### Own repository
12+
Create your own `openmcp-blueprints` Github Repository into your own Github Organisation by ["Use this Template"](https://github.com/new?owner=openmcp-project&template_name=blueprints&template_owner=openmcp-project) for. Make sure to provide following repository Secrets with your own identity token or technical user for your artifact repository:
13+
14+
| Repository Secret Name | Description |
15+
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
16+
| HELM_REPO_USERNAME | name of your own user or technical user |
17+
| HELM_REPO_TOKEN | own or technical user identity token |
18+
19+
### Repository Configuration
20+
21+
Sadly Github does NOT copy repository settings, you have to set them initially by yourself!
22+
Do not disable or change Github Workflow `.github/workflows/git-pr-status-checks.yml` or following `main` branch protection! Otherwise, the described functionality and value-add cannot be guaranteed!
23+
24+
Additionally do NOT delete / rename `helm/charts/_templates_footer.gotmpl` and `helm/charts/_templates_header.gotmpl`! Otherwise, `README.md` generation will fail! Feel free to modify this files to your needs!
25+
26+
#### [Access Workflow](#github-access-workflow)
27+
In order for your own Github Repository to access Github Workflow `.github/workflows/git-pr-status-checks.yml` on [openmcp-project/blueprint-workflows](https://github.com/openmcp-project/blueprint-workflows) you need to configure `Settings` -> `Actions` -> `General` -> the access of GitHub Actions workflows in other repositories to:
28+
29+
![Github Actions Workflows Access to other repositories](docs/static/github-actions-workflows-other-repos.png)
30+
31+
If this section is not available, please check with [GitHub Docs](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#allowing-access-to-components-in-a-private-repository) and set visibility of your repository to `internal`. If
32+
33+
#### Branch protection rule
34+
| Field | Value |
35+
| --------------------------------------------------- | ---------------------------------- |
36+
| Branch name pattern | `main` |
37+
| Require a pull request before merging | :white_check_mark: |
38+
| Require approvals | :white_check_mark: |
39+
| Require approval of the most recent reviewable push | :white_check_mark: |
40+
| Require status checks to pass before merging | :white_check_mark: |
41+
| Require branches to be up-to-date before merging | :white_check_mark: |
42+
| Status checks that are required. | `Managed Control Plane Blueprints` |
43+
| Require conversation resolution before merging | :white_check_mark: |
44+
| Do not allow bypassing the above settings | :white_check_mark: |
45+
46+
### Umbrealla Helm Charts
47+
All [Helm Charts](http://helm.sh) located at [`./helm/umbrella`](./helm/umbrella) are build to demonstrate orchestration of different SAP Cloud Resources. Please consult `README.md` file of each Umbrella Helm Chart to discover its purpose, `values.yaml` structure and intended purpose.
48+
49+
Feel free to browse existing [Umbrella Helm Chart Blueprints](helm/umbrella/blueprints) and pick one or multiple which covers most of the SAP Resources you want to orchestrate. Copy the templates into `./helm/umbrella/mcps/` to distinguish your own Helm Charts from the existing templates.
50+
51+
Add additional Sub Helm Charts from the [building blocks repository](https://github.com/openmcp-project/blueprint-building-blocks) and add/modify/delete `values.yaml` structure to orchestrate your desired landscape.
52+
53+
### Github PR
54+
Open a Github PR into `main` in order to validate and template your Helm Charts via Github Workflow [`git-pr-status-checks.yml`](./.github/workflows/git-pr-status-checks.yml).
55+
56+
### K8s Manifest Generation
57+
The Github Workflow [`git-pr-status-checks.yml`](./.github/workflows/git-pr-status-checks.yml) ensures that every Helm Chart:
58+
1. templates valid k8s manifests
59+
2. `.version` of `Chart.yaml` is bumped, in case there is a change
60+
3. `README.md` is up-to-date
61+
4. k8s manifest is templated, moved to `./manifests`, committed and pushed for every PR merging into `main`
62+
63+
!! Do not disable or change Github Workflow `.github/workflows/git-pr-status-checks.yml` or `main` branch protection!!
64+
65+
### GitOps
66+
Set up a GitOps workflow by enabling the Flux component and configuring it to sync with your Git repository. Use the provided Helm charts to manage credentials and configurations for tools like External Secrets Operator.
67+
68+
Please use Helm Chart [flux-config](https://github.com/openmcp-project/blueprint-building-blocks/tree/main/helm/charts/mcp/flux-config) to enable GitOps on your own OpenMCP and sync the corresponding `./manifests/..` folder.
69+
70+
71+
## Clean UP
72+
Be aware, that you need to **delete** / **deactivate** your Umbrella Helm Chart Dependencies in a certain order for deletion **NOT** get **STUCK**!! More details [here](https://github.com/openmcp-project/blueprint-building-blocks#helm-chart-dependencies-deletion-dependency-graph).
73+
74+
## FAQ
75+
76+
### Q: Repository Folder Structure
77+
Do i need to follow a certain folder structure?
78+
**A**: No! You can put your Helm Chart wherever you want. It's highly recommended following the open source community best practices:
79+
80+
| Folder | Purpose |
81+
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
82+
| ./helm/charts | Contains only (Sub) Helm Charts with `chart-abc/templates/*.yaml/yml` files. |
83+
| ./helm/umbrella | Contains only (Umbrella) Helm Charts which reference to a dependent (Sub) Helm Chart within `Chart.yaml`. Typhically Umbrella Helm Charts do not contain any `chart-abc/templates/*.yaml/yml` files. |
84+
| ./manifests | This folder contains all the templated Helm Charts and can **NOT** be changed! |
85+
86+
### Q: Disable k8s manifest generation
87+
How to disable k8s manifest generation?
88+
89+
**A**: Create / Update `chart-abc/.ci.config.yaml` with the following content:
90+
91+
```yaml
92+
move-manifests.sh:
93+
enabled: false
94+
```
95+
96+
With the next run of Github Action `.github/workflows/git-pr-status-checks.yml` the `./manifest/...` folder of `chart-abc` should be removed!
97+
98+
### Q: Local Chart Dependency
99+
I am missing k8s manifest `xyz`. How can I include it into `k8s manifest generation`?
100+
101+
**A**: There is no need, to re-use CO [MCP Blueprint Building Blocks](https://github.com/openmcp-project/blueprint-building-blocks) Helm Charts!
102+
Feel free to create your own custom (Sub) Helm Charts at `helm/charts` and declare it as Dependency in an Umbrella Helm Chart at `helm/umbrella`.
103+
104+
| Helm Chart | Purpose |
105+
| --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
106+
| (Sub) [Custom Chart](./helm/charts/custom-chart) | Custom (Sub) Helm Chart containing k8s manifests which are not covered by CO [MCP Blueprint Building Blocks](https://github.com/openmcp-project/blueprint-building-blocks) or not to your liking. |
107+
| (Umbrella) [Custom Chart](./helm/umbrella/blueprints/include-custom-helm-charts.abc.shoot.live.k8s-hana.ondemand.com) | Umbrella Helm Chart which references to local (Sub) Helm Chart `helm/charts/custom-chart` and re-uses additionally CO [MCP Blueprint Building Blocks](https://github.com/openmcp-project/blueprint-building-blocks). Of course, `k8s manifest generation` for `./manifests/..` also works without any external Dependencies. |
108+
109+
110+
### Q: GH Workflow - `workflow git-pr-status-checks.yml was not found`
111+
```bash
112+
Invalid workflow file: .github/workflows/git-pr-status-checks.yml#L12
113+
error parsing called workflow ".github/workflows/git-pr-status-checks.yml"
114+
-> "cloud-orchestration/mcp-blueprint-building-blocks/.github/workflows/git-pr-status-checks.yml@main"
115+
: workflow was not found. See https://docs.github.com/en/actions/sharing-automations/reusing-workflows#access-to-reusable-workflows for more information.
116+
```
117+
118+
**A**: See [Access Workflow](#github-access-workflow) and [Github Docs](https://docs.github.com/en/actions/sharing-automations/reusing-workflows#access-to-reusable-workflows)
119+
120+
### Q: Helm Chart Files - Why `.ci.config.yaml`?
121+
122+
**A**: See [in-depth documentation](https://github.com/openmcp-project/blueprint-building-blocks#github-workflow-ci-config-yaml)
123+
124+
### Q: Helm Chart Dependency Build `can't get a valid version`
125+
Github Workflow `cloud-orchestration/mcp-blueprint-building-blocks/.github/actions/helm-chart-dep-build@main` is failing with
126+
127+
```bash
128+
$ helm dependency update ./helm/umbrella/dev
129+
Hang tight while we grab the latest from your chart repositories...
130+
...Successfully got an update from the "cloud-orchestrator-mcp-blueprint-building-blocks" chart repository
131+
Update Complete. ⎈Happy Helming!⎈
132+
Error: can't get a valid version for repositories crossplane-provider-configurations. Try changing the version constraint in Chart.yaml
133+
======== ERROR STOPPING EXECUTION =======
134+
```
135+
136+
**A**: Check if all `dependencies[].version` of `/helm/umbrella/dev/Chart.yaml` are existing! Versions are expected to follow [Semantic Versioning](https://semver.org/) and [ranges](https://devhints.io/semver) can be defined e.g. `version: ">1.2.1"`. Semantic Versioning ranges are **NOT** recommended because a Helm Chart Dependency upgrade to a new `version` should always be a conscious action!
137+
138+
### Q: Compare Helm Chart Versions How?
139+
How can I compare what has changed of [`crossplane-provider-aws-ec2`](https://github.com/openmcp-project/blueprint-building-blocks/tree/main/helm/charts/mcp/crossplane-provider-aws-ec2) from Helm Chart Version `0.0.1` to `0.0.2`?
140+
141+
**A**: For every Helm Chart `version` change of every [`mcp-blueprint-building-blocks`](https://github.com/openmcp-project/blueprint-building-blocks) Helm Chart, there is a Git Tag created.
142+
143+
You can either use Github Functionality of [comparing commits/tags](https://docs.github.com/en/pull-requests/committing-changes-to-your-project/viewing-and-comparing-commits/comparing-commits) (e.g. [crossplane-provider-aws-ec2/0.0.1 <-> crossplane-provider-aws-ec2/0.0.2](https://github.com/openmcp-project/blueprint-building-blocks/compare/crossplane-provider-aws-ec2/0.0.1...crossplane-provider-aws-ec2/0.0.2)) or use [`git diff`](https://git-scm.com/docs/git-diff) to compare certain folder or files.
144+
145+
```bash
146+
git diff "crossplane-provider-aws-ec2/0.0.1" "crossplane-provider-aws-ec2/0.0.2" -- helm/charts/mcp/crossplane-provider-aws-ec2
147+
```
12148

13149
## Support, Feedback, Contributing
14150

0 commit comments

Comments
 (0)