Skip to content

Commit 829bad0

Browse files
aqilazizaqilaziz
authored
docs: document patch template inputs (#290)
Signed-off-by: aqilaziz <gonzes7@gmail.com>
1 parent eaf794b commit 829bad0

2 files changed

Lines changed: 75 additions & 4 deletions

File tree

‎content/en/docs/score implementation/score-compose/patch-templates.md‎

Lines changed: 36 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,11 +10,11 @@ aliases:
1010

1111
## Overview
1212

13-
A common requirement is for Platform Engineers to slightly modify or adjust the output of the conversion process, and this seemlessly for their Developers. This can be done by providing one or more patching templates at `init` time. These patching templates generate JSON patches which are applied on top of the output compose file, just before being written. Patching templates have access to the current compose spec as `.Compose`, the map of workload name to Score Spec as `.Workloads`, and can use any functions from [`Masterminds/sprig`](https://github.com/Masterminds/sprig).
13+
A common requirement is for Platform Engineers to slightly modify or adjust the output of the conversion process, and this seamlessly for their Developers. This can be done by providing one or more patching templates at `init` time. These patching templates generate JSON patches which are applied on top of the output compose file, just before being written. Patching templates have access to the current compose spec as `.Compose`, the map of workload name to Score Spec as `.Workloads`, and can use any functions from [`Masterminds/sprig`](https://github.com/Masterminds/sprig).
1414

1515
In this way, you can extend the behavior of the `score-compose` implementation.
1616

17-
Each template file is evaluated as a Golang text/template and should output a yaml/json encoded array of patches. Each patch is an object with required `op` (`set` or `delete`), `patch` (a dot-separated json path, use backslash to escape), a `value` if the `op` is `set`, and an optional `description` for showing in the logs.
17+
Each template file is evaluated as a Golang text/template and should output a yaml/json encoded array of patches. Each patch is an object with required `op` (`set` or `delete`), `path` (a dot-separated json path, use backslash to escape), a `value` if the `op` is `set`, and an optional `description` for showing in the logs.
1818

1919
Example of paths:
2020

@@ -25,6 +25,40 @@ services.foo.ports.-1 # adds to the end of the ports array
2525
something.:0000.xyz # patches the xyz item in the "0000" item of something (: escapes a numeric index)
2626
```
2727

28+
## Template inputs
29+
30+
Patch templates run after `score-compose` has converted the Score workloads and provisioned resources, but before the final `compose.yaml` file is written.
31+
The root template input exposes these fields:
32+
33+
| Field | Description |
34+
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
35+
| `.Compose` | The generated Compose project that will be patched. This uses the same YAML keys that appear in `compose.yaml`, such as `services`, `volumes`, `networks`, and `models`. |
36+
| `.Workloads` | A map of workload name to the original Score workload specification. Use this when the patch decision depends on Score metadata, containers, resources, annotations, or extensions. |
37+
38+
Both inputs are available as maps and lists in the template, so access fields using their YAML names, for example `.Compose.services` or `$spec.containers`.
39+
The template can also use Sprig helpers such as `dig`, `default`, `toJson`, and `b64enc`.
40+
41+
When designing a new patch template, a temporary debugging patch can make the available input easier to inspect.
42+
For example, this writes the full template input as a base64-encoded JSON label on the generated services:
43+
44+
```yaml
45+
{{ $input := . }}
46+
{{ range $name, $_ := .Compose.services }}
47+
- op: set
48+
path: services.{{ $name }}.labels.score\.dev/debug-template-input
49+
value: {{ $input | toJson | b64enc | quote }}
50+
description: Inspect patch template input
51+
{{ end }}
52+
```
53+
54+
After running `score-compose generate`, copy the label value from `compose.yaml` and decode it locally:
55+
56+
```bash
57+
printf '%s' '<label-value>' | base64 --decode | jq .
58+
```
59+
60+
Remove this debugging patch once you have identified the fields your final template needs.
61+
2862
## Example
2963

3064
Here is a concrete example showing how to inject more security for each Workload by using this template [`score-compose/unprivileged.tpl`](https://docs.score.dev/examples/patch-templates/score-compose/unprivileged/):

‎content/en/docs/score implementation/score-k8s/patch-templates.md‎

Lines changed: 39 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,11 +10,11 @@ aliases:
1010

1111
## Overview
1212

13-
A common requirement is for Platform Engineers to slightly modify or adjust the output of the conversion process, and this seemlessly for their Developers. This can be done by providing one or more patching templates at `init` time. These patching templates generate JSON patches which are applied on top of the output manifests file, just before being written. Patching templates have access to the current manifests spec as `.Manifests`, the map of workload name to Score Spec as `.Workloads`, the optional name of the namespace in Kubernetes `.Namespace`, and can use any functions from [`Masterminds/sprig`](https://github.com/Masterminds/sprig).
13+
A common requirement is for Platform Engineers to slightly modify or adjust the output of the conversion process, and this seamlessly for their Developers. This can be done by providing one or more patching templates at `init` time. These patching templates generate JSON patches which are applied on top of the output manifests file, just before being written. Patching templates have access to the current manifests spec as `.Manifests`, the map of workload name to Score Spec as `.Workloads`, the optional name of the namespace in Kubernetes `.Namespace`, and can use any functions from [`Masterminds/sprig`](https://github.com/Masterminds/sprig).
1414

1515
In this way, you can extend the behavior of the `score-k8s` implementation.
1616

17-
Each template file is evaluated as a Golang text/template and should output a yaml/json encoded array of patches. Each patch is an object with required `op` (`set` or `delete`), `patch` (a dot-separated json path, use backslash to escape), a `value` if the `op` is `set`, and an optional `description` for showing in the logs.
17+
Each template file is evaluated as a Golang text/template and should output a yaml/json encoded array of patches. Each patch is an object with required `op` (`set` or `delete`), `path` (a dot-separated json path, use backslash to escape), a `value` if the `op` is `set`, and an optional `description` for showing in the logs.
1818

1919
Example of paths:
2020

@@ -25,6 +25,43 @@ services.foo.ports.-1 # adds to the end of the ports array
2525
something.:0000.xyz # patches the xyz item in the "0000" item of something (: escapes a numeric index)
2626
```
2727

28+
## Template inputs
29+
30+
Patch templates run after `score-k8s` has converted the Score workloads and provisioned resources, but before the final `manifests.yaml` file is written.
31+
The root template input exposes these fields:
32+
33+
| Field | Description |
34+
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
35+
| `.Manifests` | The generated Kubernetes manifests that will be patched. This is a list, so patch paths start with the manifest index, for example `0.metadata.labels`. |
36+
| `.Workloads` | A map of workload name to the original Score workload specification. Use this when the patch decision depends on Score metadata, containers, resources, annotations, or extensions. |
37+
| `.Namespace` | The namespace passed to `score-k8s generate --namespace`. This is an empty string when no namespace is configured. |
38+
39+
These inputs are available as maps, lists, and strings in the template, so access fields using their YAML names, for example `$m.metadata.name` or `$spec.containers`.
40+
The template can also use Sprig helpers such as `dig`, `default`, `toJson`, and `b64enc`.
41+
42+
When designing a new patch template, a temporary debugging patch can make the available input easier to inspect.
43+
For example, this writes the full template input as a base64-encoded JSON annotation on generated Deployment manifests:
44+
45+
```yaml
46+
{{ $input := . }}
47+
{{ range $i, $m := .Manifests }}
48+
{{ if eq $m.kind "Deployment" }}
49+
- op: set
50+
path: {{ $i }}.metadata.annotations.score\.dev/debug-template-input
51+
value: {{ $input | toJson | b64enc | quote }}
52+
description: Inspect patch template input
53+
{{ end }}
54+
{{ end }}
55+
```
56+
57+
After running `score-k8s generate`, copy the annotation value from `manifests.yaml` and decode it locally:
58+
59+
```bash
60+
printf '%s' '<annotation-value>' | base64 --decode | jq .
61+
```
62+
63+
Remove this debugging patch once you have identified the fields your final template needs.
64+
2865
## Example
2966

3067
Here is a concrete example showing how to inject more security for each Workload by using this template [`score-k8s/unprivileged.tpl`](https://docs.score.dev/examples/patch-templates/score-k8s/unprivileged/):

0 commit comments

Comments
 (0)