You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
`score-compose` comes with out-of-the-box support of the following provisioners, that you can list with this command `score-compose provisioners list`:
12
+
Resource provisioners are the way for Platform Engineers to write concrete implementations of resource types that Developers can use in their Score file in the [`resources` section](/docs/score-specification/score-spec-reference/#resources-definition).
13
+
14
+
With the `score-compose init` command, a `.score-compose/zz-default.provisioners.yaml` file is created, which is a YAML file holding the definition of the [built-in provisioners](#default-provisioners).
15
+
16
+
When running `score-compose generate`, all `*.provisioners.yaml` files are loaded in lexicographic order from the `.score-compose` directory. This allows projects to include their own custom provisioners that extend or override the defaults.
17
+
18
+
To list the provisioners available from the `.score-compose` directory, run the `score-compose provisioners list` command.
The source code of these provisioners implementations can be found in the [`score-compose`'s default provisioners file](https://github.com/score-spec/score-compose/blob/main/internal/command/default.provisioners.yaml).
32
40
33
-
Users are encouraged to write their own custom provisioners to support new resource types or to modify the default implementations above. Learn how to do that with this example [here](https://score.dev/blog/writing-a-custom-score-compose-provisioner-for-apache-kafka/).
41
+
## Community provisioners
34
42
35
43
A list of provisioners authored and shared by the community can also be found [here](https://github.com/score-spec/community-provisioners). Users are encouraged to use them and contribute to this growing list of community provisioners:
36
44
@@ -44,3 +52,99 @@ A list of provisioners authored and shared by the community can also be found [h
44
52
|`environment`| (any) | (none) | (none) | Loads environment variables from a local `.env` file. |
45
53
|`horizontal-pod-autoscaler`| (any) | (none) | (none) | Generates an empty object because HPA is not supported in Docker Compose. |
46
54
|`service`| (any) | (none) |`name`| Outputs the name of the Workload dependency if it exists in the list of Workloads. |
55
+
56
+
## Install provisioner files
57
+
58
+
To easily install provisioners, `score-compose` provides the `--provisioners` flag with the `init` command, which downloads the provisioner file via a URL and installs it with the highest priority.
59
+
60
+
For example, when running the following, the provisioners file B will be matched before A because B was installed after A:
This is commonly used to import custom provisioners or common provisioners used by your team or organization and supported by your platform.
77
+
78
+
## Write your own provisioners
79
+
80
+
Users are encouraged to write their own custom provisioners to support new resource types or to modify the default implementations.
81
+
82
+
Each entry in the file has the following common fields, other fields may also exist for specific provisioner types.
83
+
84
+
```yaml
85
+
- uri: <provisioner uri>
86
+
type: <resource type>
87
+
class: <optional resource class>
88
+
id: <optional resource id>
89
+
description: <optional description>
90
+
```
91
+
92
+
The `uri` of each provisioner is a combination of its implementation (either [`template://`](#the-template-provisioner) or [`cmd://`](#the-cmd-provisioner)) and a unique identifier. Provisioners are matched in first-match order when loading the provisioner files lexicographically, so any custom provisioner files are matched first before `zz-default.provisioners.yaml`.
93
+
94
+
### The `template://` provisioner
95
+
96
+
Most built in provisioners are implemented as a series of Go templates using the template provisioner. The implementation can be found [here](https://github.com/score-spec/score-compose/blob/main/internal/provisioners/templateprov/template.go). The Go template engine is [text/template](https://pkg.go.dev/text/template).
97
+
98
+
The following extra fields can be configured as required on each instance of this provisioner:
| `init` | String, Go template | A Go template for a valid YAML dictionary. The values here will be provided to the next templates as the `.Init` state. |
103
+
| `state` | String, Go template | A Go template for a valid YAML dictionary. The values here will be persisted into the state file and made available to future executions and are provided to the next templates as the `.State` state. |
104
+
| `shared` | String, Go template | A Go template for a valid YAML dictionary. The values here will be _merged_ using a JSON-patch mechanism with the current shared state across all resources and made available to future executions through `.Shared` state. |
105
+
| `outputs` | String, Go template | A Go template for a valid YAML dictionary. The values here are the outputs of the resource that can be accessed through `${resources.*}` placeholder resolution. |
106
+
| `directories` | String, Go template | A Go template for a valid YAML dictionary. Each path -> bool mapping will create (true) or delete (false) a directory relative to the mounts directory. |
107
+
| `files` | String, Go template | A Go template for a valid YAML dictionary. Each path -> string\|null will create a relative file (string) or delete it (null) relative to the mounts directory. |
108
+
| `networks` | String, Go template | A Go template for a valid set of named Compose [Networks](https://github.com/compose-spec/compose-spec/blob/master/06-networks.md). These will be added to the output project. |
109
+
| `volumes` | String, Go template | A Go template for a valid set of named Compose [Volumes](https://github.com/compose-spec/compose-spec/blob/master/07-volumes.md). |
110
+
| `services` | String, Go template | A Go template for a valid set of named Compose [Services](https://github.com/compose-spec/compose-spec/blob/master/05-services.md). |
111
+
| `info_logs` | String, Go template | A Go template for informational messages for the user which may help connecting or testing the provisioned resource. |
112
+
| `supported_params` | List of String | A list of parameters that the provisioner expects to be passed in. |
113
+
| `expected_outputs` | List of String | A list of expected outputs that the provisioner should return. |
114
+
115
+
Each template has access to the [Sprig](http://masterminds.github.io/sprig/) functions library and executes with access to the following structure:
116
+
117
+
```go
118
+
type Data struct {
119
+
Uid string
120
+
Type string
121
+
Class string
122
+
Id string
123
+
Params map[string]interface{}
124
+
Metadata map[string]interface{}
125
+
Init map[string]interface{}
126
+
State map[string]interface{}
127
+
Shared map[string]interface{}
128
+
WorkloadServices map[string]NetworkService
129
+
ComposeProjectName string
130
+
MountsDirectory string
131
+
}
132
+
```
133
+
134
+
### The `cmd://` provisioner
135
+
136
+
The command provisioner implementation can be used to execute an external binary or script to provision the resource. The provision IO structures are serialised to json and send on standard-input to the new process, any stdout content is decoded as json and is used as the outputs of the provisioner.
137
+
138
+
The `uri` of the provisioner encodes the binary to be executed:
139
+
140
+
- `cmd://python`will execute the `python` binary on the PATH
141
+
- `cmd://../my-script`will execute `../my-script`
142
+
- `cmd://./my-script`will execute `my-script` in the current directory
143
+
- and `cmd://~/my-script` will execute the `my-script` binary in the home directory
144
+
145
+
Additional arguments can be provided via the `args` configuration key, for example a basic provisioner can be created using python inline scripts:
Copy file name to clipboardExpand all lines: content/en/docs/score implementation/score-k8s/resources-provisioners.md
+99-2Lines changed: 99 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,7 +9,15 @@ aliases:
9
9
- /docs/reference/score-cli/score-k8s/resources
10
10
---
11
11
12
-
`score-k8s` comes with out-of-the-box support of the following provisioners, that you can list with this command `score-k8s provisioners list`:
12
+
Resource provisioners are the way for Platform Engineers to write concrete implementations of resource types that Developers can use in their Score file in the [`resources` section](/docs/score-specification/score-spec-reference/#resources-definition).
13
+
14
+
With the `score-k8s init` command, a `.score-k8s/zz-default.provisioners.yaml` file is created, which is a YAML file holding the definition of the [built-in provisioners](#default-provisioners).
15
+
16
+
When running `score-k8s generate`, all `*.provisioners.yaml` files are loaded in lexicographic order from the `.score-k8s` directory. This allows projects to include their own custom provisioners that extend or override the defaults.
17
+
18
+
To list the provisioners available from the `.score-k8s` directory, run the `score-k8s provisioners list` command.
The source code of these provisioners implementations can be found in the [`score-k8s`'s default provisioners file](https://github.com/score-spec/score-k8s/blob/main/internal/provisioners/default/zz-default.provisioners.yaml).
29
37
30
-
Users are encouraged to write their own custom provisioners to support new resource types or to modify the default implementations above. Learn how to do that with this example [here](https://score.dev/blog/writing-a-custom-score-compose-provisioner-for-apache-kafka/).
38
+
## Community provisioners
31
39
32
40
A list of provisioners authored and shared by the community can also be found [here](https://github.com/score-spec/community-provisioners). Users are encouraged to use them and contribute to this growing list of community provisioners:
33
41
@@ -46,3 +54,92 @@ A list of provisioners authored and shared by the community can also be found [h
46
54
|`route`| (any) |`host`, `path`, `port`| (none) | Provisions an Ingress route on a shared Nginx instance. |
47
55
|`route`| (any) |`host`, `path`, `port`| (none) | Generates an `HTTPRoute` attached to a shared `Gateway`. |
48
56
|`service`| (any) | (none) |`name`| Outputs the name of the Workload dependency if it exists in the list of Workloads. |
57
+
58
+
## Install provisioner files
59
+
60
+
To easily install provisioners, `score-k8s` provides the `--provisioners` flag with the `init` command, which downloads the provisioner file via a URL and installs it with the highest priority.
61
+
62
+
For example, when running the following, the provisioners file B will be matched before A because B was installed after A:
This is commonly used to import custom provisioners or common provisioners used by your team or organization and supported by your platform.
79
+
80
+
## Write your own provisioners
81
+
82
+
Users are encouraged to write their own custom provisioners to support new resource types or to modify the default implementations.
83
+
84
+
Each entry in the file has the following common fields, other fields may also exist for specific provisioner types.
85
+
86
+
```yaml
87
+
- uri: <provisioner uri>
88
+
type: <resource type>
89
+
class: <optional resource class>
90
+
id: <optional resource id>
91
+
description: <optional description>
92
+
```
93
+
94
+
The `uri` of each provisioner is a combination of its implementation (either [`template://`](#the-template-provisioner) or [`cmd://`](#the-cmd-provisioner)) and a unique identifier. Provisioners are matched in first-match order when loading the provisioner files lexicographically, so any custom provisioner files are matched first before `zz-default.provisioners.yaml`.
95
+
96
+
### The `template://` provisioner
97
+
98
+
Most built in provisioners are implemented as a series of Go templates using the template provisioner. The implementation can be found [here](https://github.com/score-spec/score-k8s/blob/main/internal/provisioners/templateprov/template.go). The Go template engine is [text/template](https://pkg.go.dev/text/template).
99
+
100
+
The following extra fields can be configured as required on each instance of this provisioner:
| `init` | String, Go template | A Go template for a valid YAML dictionary. The values here will be provided to the next templates as the `.Init` state. |
105
+
| `state` | String, Go template | A Go template for a valid YAML dictionary. The values here will be persisted into the state file and made available to future executions and are provided to the next templates as the `.State` state. |
106
+
| `shared` | String, Go template | A Go template for a valid YAML dictionary. The values here will be _merged_ using a JSON-patch mechanism with the current shared state across all resources and made available to future executions through `.Shared` state. |
107
+
| `outputs` | String, Go template | A Go template for a valid YAML dictionary. The values here are the outputs of the resource that can be accessed through `${resources.*}` placeholder resolution. |
108
+
| `manifests` | String, Go template | A Go template for a valid YAML dictionary. Each path -> string\|null will create a relative file (string) or delete it (null) relative to the mounts directory. |
109
+
| `supported_params` | List of String | A list of parameters that the provisioner expects to be passed in. |
110
+
| `expected_outputs` | List of String | A list of expected outputs that the provisioner should return. |
111
+
112
+
Each template has access to the [Sprig](http://masterminds.github.io/sprig/) functions library and executes with access to the following structure:
113
+
114
+
```go
115
+
type Data struct {
116
+
Uid string
117
+
Type string
118
+
Class string
119
+
Id string
120
+
Params map[string]interface{}
121
+
Metadata map[string]interface{}
122
+
Init map[string]interface{}
123
+
State map[string]interface{}
124
+
Shared map[string]interface{}
125
+
WorkloadServices map[string]NetworkService
126
+
}
127
+
```
128
+
129
+
### The `cmd://` provisioner
130
+
131
+
The command provisioner implementation can be used to execute an external binary or script to provision the resource. The provision IO structures are serialised to json and send on standard-input to the new process, any stdout content is decoded as json and is used as the outputs of the provisioner.
132
+
133
+
The `uri` of the provisioner encodes the binary to be executed:
134
+
135
+
- `cmd://python`will execute the `python` binary on the PATH
136
+
- `cmd://../my-script`will execute `../my-script`
137
+
- `cmd://./my-script`will execute `my-script` in the current directory
138
+
- and `cmd://~/my-script` will execute the `my-script` binary in the home directory
139
+
140
+
Additional arguments can be provided via the `args` configuration key, for example a basic provisioner can be created using python inline scripts:
0 commit comments