This blueprint demonstrates how infrastructure environments can be composed and scaled by linking Terraform configs. In this example four Terraform configs are linked to deploy a working Nginix application stack on VSIs within a VPC. After deployment the Nginix website can be accessed via the application URL returned by Schematics.
The following resources are created:
- Resource Group
- COS instance and bucket
- LogDNA
- VPC
- VSI
- Nginx app
The blueprint links four Terraform configs as Workspaces.
- bp-vsi-resource-group
- bp-vsi-cos-storage
- bp-vsi-Observability
- bp-vsi-vpc-app
TF configs are sourced from https://github.com/Cloud-Schematics/blueprint-example-modules
Blueprint file: vsi-app-blueprint.yaml
├── bp-vsi-resource-group
| └── source: github.com/Cloud-Schematics/blueprint-example-modules/IBM-ResourceGroup
├── bp-vsi-cos-storage
| └── source: github.com/Cloud-Schematics/blueprint-example-modules/IBM-Storage
├── bp-vsi-Observability
| └── source: github.com/Cloud-Schematics/blueprint-example-modules/IBM-Observability
└── bp-vsi-vpc-app
└── source: github.com/Cloud-Schematics/blueprint-example-modules/IBM-VPC-App
The blueprint demonstrates deploying a full application stack composed from 4 modules. The included TF examples should not be considered best practice and are only included to demonstrate the layered approach to deploying applications and data passing. LogDNA and COS instance/buckets are not essential to this example and are only included as representative examples.
The vsi-app-blueprint.yaml definition accepts the following inputs:
Name | Type | Value | Description |
---|---|---|---|
region | string | null | Resource deployment region |
resource_group_name | string | null | Resource group to create |
provision_rg | string | null | Create RG - true. Use existing RG - false |
cos_instance_name | string | null | Name for COS instance |
logdna_name | string | null | Name of LogDNA instance |
vsi_name | string | null | Name of VSIs |
ssh_public_key | string | sensitive | User SSH public key entered as env-var. The SSH key is not used, but a valid key must be specified to create the VSI |
The vsi-app-blueprint.yaml definition creates the following outputs:
Name | Type | Value | Description |
---|---|---|---|
schematics-app-url | string | URL of sample NGINX application |
The input file defines the variable values for all the required Blueprint definition inputs.
Name | Type | Value | Description |
---|---|---|---|
region | string | us-east | Sample var for resource deployment region |
resource_group_name | string | blueprint-vsi-us | Name of resource group to create |
provision_rg | string | null | Create RG - true. Use existing RG - false |
vsi_name | string | bp-vsi-app-us | Name of VSI instance |
logdna_name | string | vsi-app-logdna-us | |
cos_instance_name | string | vsi-app-cos-us | Name for COS instance |
ssh_public_key: | string | null | SSH Key |
It is advised that sensitive input values like API keys and SSH keys should not be defined in the input file as this can lead to a security exposure if the file is saved in the public git repo. To pass sensitive values to Schematics, they are passed as dynamic input variables when the Blueprint is created. Shell variable substution can be used to insert environment variables as input to Blueprint commands.
The SSH key can be sourced and saved as the environment variable user_ssh_key
using:
export user_ssh_key=`cat ~/.ssh/id_rsa.pub`
- Install the Schematics CLI plugin by follow the instructions in the documentation
- Configure IAM access permissions for the Schematics Blueprints service.
- Configure IAM access permissions for IaaS VPC resources
- Set Schematics Target Region
The target (manage from) Schematics region for the Blueprint instance is determined by the IBM Cloud CLI target region. The region can be set with the
ibmcloud target
command. - Export
user_ssh_key
for VSI creation
The following parameters are used for the blueprint create
configuration.
- Name of the blueprint:
Blueprint_vsi_app
- Schematics management resource group:
Default
- Blueprint URL:
https://github.com/Cloud-Schematics/blueprint-vsi-app-example
- Blueprint file:
vsi-app-blueprint.yaml
- Blueprint Git branch
main
- Input file URL:
https://github.com/Cloud-Schematics/blueprint-vsi-app-example
- Input file:
vsi-app-input.yaml
- Input file Git branch
main
- Inputs:
- provisiong_rg=false
- resource_group_name=Default
- ssh_public_key=$user_ssh_key
Example commands
$ ibmcloud target -r <region>
$ export user_ssh_key=`cat ~/.ssh/id_rsa.pub`
$ ibmcloud schematics blueprint create -name Blueprint_Complex -resource-group Default -bp-git-url https://github.com/Cloud-Schematics/blueprint-vsi-app-example -bp-git-branch main -bp-git-file vsi-app-blueprint.yaml -input-git-url https://github.com/Cloud-Schematics/blueprint-vsi-app-example -input-git-branch main -input-git-file vsi-app-input.yaml -inputs provision_rg=false,resource_group_name=Default,ssh_public_key=$user_ssh_key
$ ibmcloud schematics blueprint install -id blueprint_id
$ ibmcloud schematics blueprint job list -id blueprint_id
$ ibmcloud schematics blueprint get -id blueprint_id -profile output
$ ibmcloud schematics blueprint destroy -id blueprint_id
$ ibmcloud schematics blueprint delete -id blueprint_id
See the Schematics documentation for troubleshooting information.
IBM Cloud resources are deployed by this example. Most observed errors are Terraform Apply errors when running blueprint install
due to incorrect IAM permissions to create resources or existing/duplicate resources. Only one 'free/lite' LogDNA instance is allowed per account.
Looking for more samples? Check out the {{site.data.keyword.bplong_notm}} GitHub repository.
Check the example Readme files for further Blueprint customisation and usage scenarios for each sample.
In a shared account the user may not have access permissions to create resources in the Default resource group. The Blueprint can be customised to use an alternative group that the user does have access permissions to. Replace <USER_RESOURCE_GROUP>
with the alternative resource group name.
$ ibmcloud schematics blueprint create -name Blueprint_Complex -resource-group <USER_RESOURCE_GROUP> -bp-git-url https://github.com/Cloud-Schematics/blueprint-vsi-app-example -bp-git-branch main -bp-git-file vsi-app-blueprint.yaml -input-git-url https://github.com/Cloud-Schematics/blueprint-vsi-app-example -input-git-branch main -input-git-file vsi-app-input.yaml -inputs provision_rg=false,resource_group_name=<USER_RESOURCE_GROUP>,ssh_public_key=$user_ssh_key
In Pay-Go or Subscription accounts, or where the user has administrative permissions to create resource groups, the Blueprint can be customised to create a user specified resource group. The user must be an account owner or have been granted Account Management, editor or administrator permissions to create resource groups.
With the required IAM permissions, a user specified resource group can be created by changing the folllowing input parameters on the create command:
provision_rg=true
resource_group_name=<USER_RESOURCE_GROUP>
$ ibmcloud schematics blueprint create -name Blueprint_Complex -resource-group Default -bp-git-url https://github.com/Cloud-Schematics/blueprint-vsi-app-example -bp-git-branch main -bp-git-file vsi-app-blueprint.yaml -input-git-url https://github.com/Cloud-Schematics/blueprint-vsi-app-example -input-git-branch main -input-git-file vsi-app-input.yaml -inputs provision_rg=true,resource_group_name=<USER_RESOURCE_GROUP>,ssh_public_key=$user_ssh_key
This will create the resource group <USER_RESOURCE_GROUP>
and the COS instance will be created in this group.
Refer to the Schematics FAQ documentation for diagnosing and resolving the typical configuration errors with this example and their resolution.