Skip to content

Commit 74e2ee7

Browse files
cjorge-graphopscjorge-graphops
committed
feat(common): initial commit
1 parent 8c56e3a commit 74e2ee7

36 files changed

+1918
-0
lines changed

‎charts/common/Chart.yaml

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
apiVersion: v2
2+
name: common
3+
description: A Helm library chart providing a framework for generating Kubernetes resources with advanced templating and layered value inheritance for single and multi-component charts.
4+
5+
# A chart can be either an 'application' or a 'library' chart.
6+
#
7+
# Application charts are a collection of templates that can be packaged into versioned archives
8+
# to be deployed.
9+
#
10+
# Library charts provide useful utilities or functions for the chart developer. They're included as
11+
# a dependency of application charts to inject those utilities and functions into the rendering
12+
# pipeline. Library charts do not define any templates and therefore cannot be deployed.
13+
type: library
14+
15+
# This is the chart version. This version number should be incremented each time you make changes
16+
# to the chart and its templates, including the app version.
17+
# Versions are expected to follow Semantic Versioning (https://semver.org/)
18+
version: 0.0.1-canary.1

‎charts/common/README.md

+179
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
# Common Helm Chart
2+
3+
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) ![Version: 0.0.1](https://img.shields.io/badge/Version-0.0.1-informational?style=flat-square) ![Type: library](https://img.shields.io/badge/Type-library-informational?style=flat-square)
4+
5+
# Common Chart
6+
7+
A Helm library chart providing a framework for generating Kubernetes resources with advanced templating and layered value inheritance for single and multi-component charts.
8+
9+
## Overview
10+
11+
This library chart enables:
12+
- Component-based resource generation
13+
- Layered value inheritance
14+
- Advanced template processing
15+
- Generalized ability to override-anything
16+
- Automatic map-to-list transformations for more conveniet values interfaces
17+
- Standardized resource generation patterns
18+
19+
## Usage
20+
21+
### 1. Include it as Dependency
22+
23+
```yaml
24+
# Chart.yaml
25+
dependencies:
26+
- name: common
27+
```
28+
29+
### 2. Configure Components
30+
31+
Configuation is done by creating a file named `_common.config.yaml` in the root of your chart.
32+
Components can be configured in three modes:
33+
34+
#### Single Component
35+
36+
```yaml
37+
# _common.config.yaml
38+
dynamicComponents: false
39+
40+
components:
41+
- myComponent
42+
43+
componentLayering:
44+
myComponent: []
45+
```
46+
47+
which decleares a top level key `myComponent` for a single component, and no keys from which to inherit defaults.
48+
Even for a single component, you may wish to have a separate key from which to inherit defaults just to leave the main top level key a bit cleaner for the user, i.e.:
49+
50+
```yaml
51+
# _common.config.yaml
52+
dynamicComponents: false
53+
54+
components:
55+
- myComponent
56+
57+
componentLayering:
58+
myComponent:
59+
- myComponentDefaults
60+
```
61+
62+
#### Multiple Static Components
63+
64+
```yaml
65+
# _common.config.yaml
66+
dynamicComponents: false
67+
68+
components:
69+
- statefulNode
70+
- rpcdaemon
71+
72+
componentLayering:
73+
statefulNode:
74+
- erigonDefaults
75+
rpcdaemon:
76+
- erigonDefaults
77+
78+
```
79+
80+
This defines two separate components, `statefulNode` and `rpcdaemon`, both of which inherit common defaults from an `erigonDefaults` key.
81+
82+
#### Dynamic Components
83+
84+
```yaml
85+
# _common.config.yaml
86+
dynamicComponents: true
87+
88+
componentsKey: <Top Level key expected to have components as subkeys>
89+
90+
componentLayering: '{{ Templating Logic that generates componentLayering based dinamically }}
91+
```
92+
93+
### 3. Define Values
94+
95+
Structure your values in layers that match your inheritance configuration:
96+
97+
```yaml
98+
# values.yaml
99+
defaults:
100+
resources:
101+
```
102+
103+
### 4. Template References
104+
105+
Components can reference values from other components using `@needs` directive:
106+
107+
```yaml
108+
rpcdaemon:
109+
config: |
110+
@needs(ComponentValues.statefulnode.ports[0].containerPort as nodePort)
111+
```
112+
113+
## Architecture
114+
115+
The chart processes resources through several phases:
116+
117+
1. **Initialization**
118+
- Processes component configuration and inheritance stacks
119+
- Merges values according to defined layers
120+
- Setup Templating Context
121+
- Template resolution on values, with preprocessor directives (@needs, @type, ...)
122+
123+
2. **Per-Component Resource Generation**
124+
- Starts with base resource templates
125+
- Overlays component-specific values
126+
- Does an intermediate render with resolved context
127+
- Applies resource transformations (convert back maps to lists)
128+
- Prunes output of internal or disabled fields
129+
- Prints final resources render
130+
131+
```mermaid
132+
flowchart TB
133+
%% Input Configuration
134+
A([Chart Layout Config + Values]) --> B
135+
136+
subgraph Init["Initialization Phase"]
137+
direction TB
138+
B["Process Layout Config</br><i>(component keys and values inheritance stack)</i>"]
139+
B --> C["Merge Values Stacks></br><i>(per component)</i>"]
140+
C --> D[Setup Templating Context]
141+
D --> E["Template Resolution<br/><i>(process @needs/@type directives and executes templates)</i>"]
142+
end
143+
144+
E --> R1[(Base: Service YAML)]
145+
E --> R2[(Base: ConfigMap YAML)]
146+
147+
subgraph CompA["Component A: StatefulNode"]
148+
subgraph ResA["Per Resource Type Pipeline"]
149+
R1 --> H1[Merge Resource Values]
150+
H1 --> M1["Intermediate Render"]
151+
M1 --> I1["Transforms<br/><i>(convert maps to lists)</i>"]
152+
I1 --> J1["Prune Output<br/><i>(clean internal fields)</i>"]
153+
end
154+
end
155+
156+
subgraph CompB["Component B: rpcdaemon"]
157+
subgraph ResB["Per Resource Type Pipeline"]
158+
R2 --> H2[Overlay Resource Values]
159+
H2 --> M2["Intermediate Render"]
160+
M2 --> I2["Transforms<br/><i>(convert maps to lists)</i>"]
161+
I2 --> J2["Prune Output<br/><i>(clean internal fields)</i>"]
162+
end
163+
end
164+
165+
J1 --> K{Output Final Kubernetes<br/>Resources}
166+
J2 --> K
167+
```
168+
169+
## Upgrading
170+
171+
We recommend that you pin the version of the Chart that you deploy. You can use the `--version` flag with `helm install` and `helm upgrade` to specify a chart version constraint.
172+
173+
This project uses [Semantic Versioning](https://semver.org/). Changes to the version of the application (the `appVersion`) that the Chart deploys will generally result in a patch version bump for the Chart. Breaking changes to the Chart or its `values.yaml` interface will be reflected with a major version bump.
174+
175+
We do not recommend that you upgrade the application by overriding `image.tag`. Instead, use the version of the Chart that is built for your desired `appVersion`.
176+
177+
## Contributing
178+
179+
We welcome and appreciate your contributions! Please see the [Contributor Guide](/CONTRIBUTING.md), [Code Of Conduct](/CODE_OF_CONDUCT.md) and [Security Notes](/SECURITY.md) for this repository.

‎charts/common/README.md.gotmpl

+172
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
2+
{{ template "graphops.title" . }}
3+
4+
{{ template "graphops.badges-noAppVersion" . }}
5+
6+
# Common Chart
7+
8+
A Helm library chart providing a framework for generating Kubernetes resources with advanced templating and layered value inheritance for single and multi-component charts.
9+
10+
## Overview
11+
12+
This library chart enables:
13+
- Component-based resource generation
14+
- Layered value inheritance
15+
- Advanced template processing
16+
- Generalized ability to override-anything
17+
- Automatic map-to-list transformations for more conveniet values interfaces
18+
- Standardized resource generation patterns
19+
20+
## Usage
21+
22+
### 1. Include it as Dependency
23+
24+
```yaml
25+
# Chart.yaml
26+
dependencies:
27+
- name: common
28+
```
29+
30+
### 2. Configure Components
31+
32+
Configuation is done by creating a file named `_common.config.yaml` in the root of your chart.
33+
Components can be configured in three modes:
34+
35+
#### Single Component
36+
37+
```yaml
38+
# _common.config.yaml
39+
dynamicComponents: false
40+
41+
components:
42+
- myComponent
43+
44+
componentLayering:
45+
myComponent: []
46+
```
47+
48+
which decleares a top level key `myComponent` for a single component, and no keys from which to inherit defaults.
49+
Even for a single component, you may wish to have a separate key from which to inherit defaults just to leave the main top level key a bit cleaner for the user, i.e.:
50+
51+
```yaml
52+
# _common.config.yaml
53+
dynamicComponents: false
54+
55+
components:
56+
- myComponent
57+
58+
componentLayering:
59+
myComponent:
60+
- myComponentDefaults
61+
```
62+
63+
#### Multiple Static Components
64+
65+
```yaml
66+
# _common.config.yaml
67+
dynamicComponents: false
68+
69+
components:
70+
- statefulNode
71+
- rpcdaemon
72+
73+
componentLayering:
74+
statefulNode:
75+
- erigonDefaults
76+
rpcdaemon:
77+
- erigonDefaults
78+
79+
```
80+
81+
This defines two separate components, `statefulNode` and `rpcdaemon`, both of which inherit common defaults from an `erigonDefaults` key.
82+
83+
#### Dynamic Components
84+
85+
```yaml
86+
# _common.config.yaml
87+
dynamicComponents: true
88+
89+
componentsKey: <Top Level key expected to have components as subkeys>
90+
91+
componentLayering: '{{ Templating Logic that generates componentLayering based dinamically }}
92+
```
93+
94+
### 3. Define Values
95+
96+
Structure your values in layers that match your inheritance configuration:
97+
98+
```yaml
99+
# values.yaml
100+
defaults:
101+
resources:
102+
```
103+
104+
### 4. Template References
105+
106+
Components can reference values from other components using `@needs` directive:
107+
108+
```yaml
109+
rpcdaemon:
110+
config: |
111+
@needs(ComponentValues.statefulnode.ports[0].containerPort as nodePort)
112+
```
113+
114+
## Architecture
115+
116+
The chart processes resources through several phases:
117+
118+
1. **Initialization**
119+
- Processes component configuration and inheritance stacks
120+
- Merges values according to defined layers
121+
- Setup Templating Context
122+
- Template resolution on values, with preprocessor directives (@needs, @type, ...)
123+
124+
2. **Per-Component Resource Generation**
125+
- Starts with base resource templates
126+
- Overlays component-specific values
127+
- Does an intermediate render with resolved context
128+
- Applies resource transformations (convert back maps to lists)
129+
- Prunes output of internal or disabled fields
130+
- Prints final resources render
131+
132+
```mermaid
133+
flowchart TB
134+
%% Input Configuration
135+
A([Chart Layout Config + Values]) --> B
136+
137+
subgraph Init["Initialization Phase"]
138+
direction TB
139+
B["Process Layout Config</br><i>(component keys and values inheritance stack)</i>"]
140+
B --> C["Merge Values Stacks></br><i>(per component)</i>"]
141+
C --> D[Setup Templating Context]
142+
D --> E["Template Resolution<br/><i>(process @needs/@type directives and executes templates)</i>"]
143+
end
144+
145+
E --> R1[(Base: Service YAML)]
146+
E --> R2[(Base: ConfigMap YAML)]
147+
148+
subgraph CompA["Component A: StatefulNode"]
149+
subgraph ResA["Per Resource Type Pipeline"]
150+
R1 --> H1[Merge Resource Values]
151+
H1 --> M1["Intermediate Render"]
152+
M1 --> I1["Transforms<br/><i>(convert maps to lists)</i>"]
153+
I1 --> J1["Prune Output<br/><i>(clean internal fields)</i>"]
154+
end
155+
end
156+
157+
subgraph CompB["Component B: rpcdaemon"]
158+
subgraph ResB["Per Resource Type Pipeline"]
159+
R2 --> H2[Overlay Resource Values]
160+
H2 --> M2["Intermediate Render"]
161+
M2 --> I2["Transforms<br/><i>(convert maps to lists)</i>"]
162+
I2 --> J2["Prune Output<br/><i>(clean internal fields)</i>"]
163+
end
164+
end
165+
166+
J1 --> K{Output Final Kubernetes<br/>Resources}
167+
J2 --> K
168+
```
169+
170+
{{ template "graphops.upgradingSection" . }}
171+
172+
{{ template "graphops.contributingSection" . }}

0 commit comments

Comments
 (0)