score-compose resources provisioners

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.

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.

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.

To list the provisioners available from the .score-compose directory, run the score-compose provisioners list command.

Default provisioners

The source code of these provisioners implementations can be found in the score-compose’s default provisioners file.

Community provisioners

A list of provisioners authored and shared by the community can also be found here. Users are encouraged to use them and contribute to this growing list of community provisioners:

Install provisioner files

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.

For example, when running the following, the provisioners file B will be matched before A because B was installed after A:

score-compose init --provisioners https://example.com/provisioner-A.yaml --provisionerss https://example.com/provisioner-B.yaml

The provisioners can be loaded from the following kinds of urls:

• HTTP: http://host/file
• HTTPS: https://host/file
• Git (SSH): git-ssh://git@host/repo.git/file
• Git (HTTPS): git-https://host/repo.git/file
• OCI: oci://[registry/][namespace/]repository[:tag|@digest][#file]
• Local File: /path/to/local/file
• Stdin: - (read from standard input)

This is commonly used to import custom provisioners or common provisioners used by your team or organization and supported by your platform.

Write your own provisioners

Users are encouraged to write their own custom provisioners to support new resource types or to modify the default implementations.

Each entry in the file has the following common fields, other fields may also exist for specific provisioner types.

- uri: <provisioner uri>
  type: <resource type>
  class: <optional resource class>
  id: <optional resource id>
  description: <optional description>

The uri of each provisioner is a combination of its implementation (either template:// or cmd://) 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.

The template:// provisioner

Most built in provisioners are implemented as a series of Go templates using the template provisioner. The implementation can be found here. The Go template engine is text/template.

The following extra fields can be configured as required on each instance of this provisioner:

Each template has access to the Sprig functions library and executes with access to the following structure:

type Data struct {
	Uid      string
	Type     string
	Class    string
	Id       string
	Params   map[string]interface{}
	Metadata map[string]interface{}
	Init   map[string]interface{}
	State  map[string]interface{}
	Shared map[string]interface{}
	WorkloadServices map[string]NetworkService
	ComposeProjectName string
	MountsDirectory    string
}

The cmd:// provisioner

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.

The uri of the provisioner encodes the binary to be executed:

• cmd://python will execute the python binary on the PATH
• cmd://../my-script will execute ../my-script
• cmd://./my-script will execute my-script in the current directory
• and cmd://~/my-script will execute the my-script binary in the home directory

Additional arguments can be provided via the args configuration key, for example a basic provisioner can be created using python inline scripts:

- uri: "cmd://python"
  args: ["-c", "print({\"resource_outputs\":{}})"]