| copyright | lastupdated | keywords | subcollection | ||
|---|---|---|---|---|---|
|
2022-10-27 |
schematics blueprints template, blueprints yaml, schema definitions, definitions, yaml, |
schematics |
{{site.data.keyword.attribute-definition-list}}
{: #bp-template-schema-yaml}
This document is the reference of the YAML schema that is used to describe the blueprint template YAML file.
Blueprint templates are written in YAML with a minimum of syntax that specify the automation modules to be used, their versions, source libraries, and relationships for passing resource dependency data between modules. {: shortdesc}
A blueprint template consists of two major sections. A global settings section contains a default name and description for the environment, and settings related to the whole template. Also it defines the inputs the template requires, and any outputs it returns. This is followed by a modules section containing the module definitions. Dependencies are created between modules by interpolation of module input and output values.
Each template file has a global settings preface:
name: dev-blueprint
type: "blueprint"
schema_version: "1.0"
description: "Project to provision Application Service."
tags:
- "blueprint:dev"
inputs:
- name: resource_group
- name: region
- name: api_key
outputs:
- name: service-url
value: $module.bp-vsi-vpc-app.outputs.app_url
settings:
- name: TF_VERSION
value: 1.0{: pre}
{: #bp-parameters}
Following are the supporting setting parameters that can be used to configure a template
{: #bp-name}
Type: string
Required: true
Name that is used to identify the blueprint template in use
{: #bp-type}
Type: string
Required: true
Required file type identifier
Value: blueprint
{: #bp-schema-version}
Type: number
Required: true
Schema version used by this file.
Options: 1.0
Example
schema_version: "1.0"{: pre}
{: #bp-description}
Type: string
Default: []
A string used to describe the template to provide users with more information about its usage and the solution it describes.
Example
description: "Project to provision Application Service."{: pre}
{: #bp-tags}
Type: list
Default: []
A list of tags to be attached to all deployed cloud resources and the blueprint resource. All environments deployed using this template will have these tags. Additional tags can be specified at config create time specific to the environment to be deployed.
Example
tags:
- "blueprint:dev"{: pre}
tags:
- "blueprint:dev"
{: #bp-inputs}
Type: list
Default: []
A list defines all the inputs that are required by the template. Inputs are specified in the input file file or as input values when the blueprint is created in {{site.data.keyword.bpshort}}. Inputs are defined with a name: key.
Example
inputs:
- name: resource_group
- name: region
- name: api_key{: pre}
{: #bp-outputs}
Type: list
Default: []
A list defines all the outputs that are returned by the template to the user. Each output is identified by a key-value pair.
Example
outputs:
- name: schematics-service-url
value: $module.bp-vsi-vpc-app.outputs.app_url{: pre}
{: #bp-settings}
Type: list
Default: []
A list of the settings to be used by the template that is defined as key-value pairs. Each setting is identified by the key name.
{: pre}
{: #bp-tf-version}
Type: number
Blueprint templates set the Terraform version to be used at module execution time based on the value of TF_Version. This value can be used to pin the version of Terraform used by {{site.data.keyword.bpshort}} to remain compatible with the template supported version. Updating this value will change the Terraform version that is used on the next execution.
Options: Terraform version in SemVer format
Example
settings: # Master settings for all modules
- name: TF_VERSION
value: 1.0 {: pre}
{: #-logs}
Type: string
Configure the Terraform logging level for the blueprint and provider. See Debugging Terraform{: external} for detailed usage.
Example
settings: # Master settings for all modules
- name: TF_LOGS
value: "debug"{: pre}
{: #bp-modules-schema}
The modules block defines the Terraform, and Ansible modules from which the solution is constructed.
Each module list entry is defined by a name, followed by the source for the module, inputs, and expected outputs.
Review the automation module metadata and readme file information for the modules{: external} to guide defining the module block.
modules:
- name: bp-vsi-resource-group
module_type: terraform
source:
source_type: github
git:
git_repo_url: "https://github.com/Cloud-Schematics/blueprint-example-modules/tree/master/IBM-ResourceGroup"
git_branch: master
inputs:
- name: provision
value: $blueprint.provision_rg
- name: name
value: $blueprint.resource_group_name
outputs:
- name: resource_group_name
- name: resource_group_id
- name: bp-vsi-cos-storage
module_type: terraform
source:
source_type: github
git:
git_repo_url: "https://github.com/Cloud-Schematics/blueprint-example-modules/tree/master/IBM-Storage"
git_branch: master
inputs:
- name: cos_instance_name
value: $blueprint.cos_instance_name
- name: cos_single_site_loc
value: "ams03"
- name: resource_group_id
value: $module.bp-vsi-resource-group.outputs.resource_group_id
outputs:
- name: cos_id
- name: cos_crn{: pre}
{: #bp-modules-name}
Type: string
Required: true
The name that is used within {{site.data.keyword.bpshort}} to identify the blueprint module created to manage the resources created by the Terraform config or module specified on the modules.source.git.git_url statement.
{: #bp-modules-moduletype}
Type: string
Required: true
String specifying the IaC type of the automation module. Only Terraform is supported at this time.
Options: terraform
{: pre}
{: #bp-modules-sourceoptions}
The version control source library from where the Terraform config, or Ansible playbook are retrieved.
source:
source_type: github
git:
git_repo_url: "https://github.com/Cloud-Schematics/blueprint-example-modules/tree/master/IBM-ResourceGroup"
git_branch: master{: pre}
{: #bp-modules-source-type}
Type: string
Required: true
Type of Git source repository.
Options: github, gitlab
Specifies the module source from a version control system, e.g. a git repository to IBM Catalog. The following source parameters must match the source_type. {: pre}
{: #bp-modules-git-repo-url}
Type: url string
Required: true
URL for the automation module in its content repository. If the config exists in a sub directory the folder name is appended. {: pre}
{: #bp-modules-git-branch}
Type: string
Default: master
If content is in Git, the branch containing the version of the Terraform config or module to be used. This option is mutually exclusive with the git_release option.
{: pre}
{: #bp-modules-git-release}
Type: string
Default: latest
If content is Git, the release tag of the version of the Terraform config or module to be used. This option is mutually exclusive with the git_branch option. If not specified, {{site.data.keyword.bpshort}} will default to always pulling the latest commit during a blueprint config update operation.
Options: latest or release in SemVer format
{: pre}
{: #bp-modules-inputs-options}
Type: list
Default: []
A list that defines all the inputs that are required by the module.
inputs:
- name: list_any_flow_scalar
value: $blueprint.list_any_flow_scalar
type: list(any)
- name: cos_single_site_loc
value: "ams03"
- name: resource_group_id
value: $module.bp-vsi-resource-group.outputs.resource_group_id
- name: docker_ports
value: $blueprint.docker_ports
type: |
list(object({
internal = number
external = number
protocol = string
}){: pre}
{: #bp-modules-inputs-name}
Type: string
Required: true
Name of variable to be passed to Terraform module or Ansible playbook. It must match the value in the Terraform template for the value to be passed at execution time to the module. {: pre}
{: #bp-modules-inputs-type}
Type: YAML flow or block scalar
Default: string
As templates work with Terraform configs and modules, Terraform variable type constraints{: external} are used to set the type validation for blueprints inputs. The type constraint must match the variable type in the target config for the value to be passed successfully at execution time to the module. The type can be copied from the module metadata{: external} or the Terraform variables.tf file.
As complex Terraform types are typically represented as multi-line strings, YAML block syntax can be used.
Options: Any valid Terraform variable type
Example
- name: docker_ports
value: $blueprint.docker_ports
type: |
list(object({
internal = number
external = number
protocol = string
})
{: pre}
{: #bp-modules-inputs-value}
Type: Any valid Terraform variable type
Required: true
The value field sources the input value for a module from three sources:
- Statically defined values specified on the name value pair statement of the module, in yaml syntax
- An input to the template defined in the settings prefix and sourced at run time from the inputs defined by the blueprint configuration. Identified by the $blueprint prefix
- An output value from another module defined in the template file.
- Identified by the
$moduleprefix and must be included in the output section of another module. - The format is the token,
$modulefollowed by the module name, the tokenoutputs, followed by the module output name.
- Identified by the
The value type is as defined by the modules.inputs.type option.
Example of statically defined values
- name: provision_ats_instance
type: boolean
value: false{: pre}
Example value sourced from an input statement in the template inputs section
- name: logdna_sts_region
type: string
value: $blueprint.region{: pre}
Example value sourced from an output statement on the module IBM-Resource-Group.
- name: resource_group_name
value: $module.IBM-Resource-Group.outputs.resource_group_name{: pre}
{: #bp-modules-inputs-secure}
Type: Boolean
Default: false
Flag specifying whether the value is a sensitive variable and must be masked in the output {: pre}
{: #bp-module-outputs}
Type: list
Default: []
A list defines all the outputs that are returned by the module to be used as inputs to other modules or output from the blueprint. Each output is identified by the label name. It must match an output declaration{: external} in the Terraform template for the value to be retrieved at execution time from the module. The name can be copied from the module metadata{: external} or from inspecting the Terraform .tf files.
Example
outputs:
- name: log_analysis_instance_name
- name: sysdig_instance_name{: pre}
{: #bp-modules-injector}
Type: list
Default: []
The injectors block is an optional block to configure the parameters that are required by {{site.data.keyword.bpshort}} to inject additional files into the automation module source at execution time. The primary use with blueprint templates is to enable direct use of Terraform child modules, by the injection of .tf files containing provider and terraform blocks. Review section blueprints provider injection for guidance on the use of the injectors block.
injectors:
- tft_git_url: "https://github.com/Cloud-Schematics/tf-templates"
tft_name: "ibm"
injection_type: override
tft_parameters:
- name: provider_version
value: 1.42.3
- name: provider_source
value: IBM-Cloud/ibm
- name: region
value: us-south{: pre}
{: #bp-module-tft-git-url}
Type: URL
Required: true
URL of the Git repository that contain the templating files used for injection. {: pre}
{: #bp-module-tft-name}
Type: string
Required: true
Name of the templating file to use
Options: ibm or kubernetes
{: pre}
{: #bp-module-injection-type}
Type: string
Required: true
Two modes of injection are supported by Terraform. Definitions can be injected as extra files, only if it is believed that no conflict with any existing HCL statements. Alternatively they can be injected as HCL override files{: external}.
Options: override or inject
{: pre}
{: #bp-modules-tft-parameters}
Type: list
Required: true
A list that defines the templating inputs as name-value pairs. At this time, only static values are supported.
Example
- name: provider_version
value: 1.42.3
- name: provider_source
value: IBM-Cloud/ibm
- name: region
value: us-south{: pre}