810-well-known-custom-extensions.md

title	weight
Well-known custom extensions	810

Well-known custom extensions

This section is non-normative, but is here to propose a common set of custom extensions a bundle MAY define, and that CNAB tools MAY implement.

A bundle indicates that it uses a custom extension by including them in its custom section (as defined in Custom Extensions).

Dependencies

A custom bundle extension, io.cnab.dependencies, MAY be defined that specifies that the bundle depends up on other bundles. See the Dependencies Specification for details.

Parameter Sources

A custom bundle extension, io.cnab.parameter-sources, MAY be defined that provides additional guidance for how a runtime MAY determine the default value of a parameter. The parameter source extension does not cover how the runtime should set the value of a parameter because each implementation may have different information to take into account when determining the final value of a parameter.

The invocation image:

• MAY use the the io.cnab.parameter-sources extension with outputs that are generated by actions other than the install action. It is the responsibility of the invocation image to handle when the output does not exist in the case when the action that generates the output has not been executed yet, for example by setting a default on the parameter or marking the parameter required.
• MAY use the io.cnab.parameter-sources extension with outputs that are generated by stateless: false actions.

A CNAB runtime implementing the io.cnab.parameter-sources extension:

• SHOULD allow users to manually override parameter values.
• SHOULD allow users to specify a parameter value when when a value cannot be determined using its parameter sources.

In the example below, the output tfstate is initially generated during the install action, and the required parameter tfstate is used by the upgrade and uninstall actions. The parameter source specifies that the tfstate output can be used to set the tfstate parameter. This enables a bundle to pass data, in this case state, between actions.

{
  "custom": {
    "io.cnab.parameter-sources": {
      "tfstate": {
        "priority": ["output"],
        "sources": {
          "output": {
            "name": "tfstate"
          }
        }
      }
    }
  },
  "outputs": {
    "tfstate": {
      "applyTo": [ "install", "upgrade", "uninstall" ],
      "definition": "tfstate",
      "path": "/cnab/app/outputs/tfstate"
    }
  },
  "parameters": {
    "tfstate": {
      "applyTo": [ "upgrade", "uninstall" ],
      "definition": "tfstate",
      "required": true
    }
  }
}

• io.cnab.parameter-sources: Defines the parameter sources extension.
  • <parameterName>: The name of the destination parameter.
    • priority: Array of source types in the priority order that they should be used to populated the parameter.
    • sources: A map of key/value pairs of a source type and definition for the parameter value.

Well-known Source Types

Output

The source of the parameter value comes from the output of a previous action.

• output: Specifies that the source of the parameter is an output.
  • name: The name of the source output.