Using a customization bundle to customize a deployable architecture
This tutorial walks you through how to customize an IBM Cloud® pre-built deployable architecture to fit your business needs by using a preconfigured customization bundle. By completing this tutorial, you learn how to download the customization bundle, update the details and Terraform files of a deployable architecture, and then test the customized deployable architecture.
By starting with an IBM Cloud deployable architecture, you don't need to worry about creating compliant infrastructure architecture from the ground up. You can get a jump-start by using an IBM Cloud deployable architecture and customizing it to meet your specific needs.
Imagine you are a developer for the fictitious company Example Corp. You're looking for a product to provide secure and customizable compute resources for running your applications and services. You browse the IBM Cloud catalog and discover the VSI on VPC landing zone option, a deployable architecture that provides what you need. However, you need to modify the architecture to meet your business needs:
- Remove unwanted variables
- Use only US deployment regions
- Use an existing SSH key instead of a personal SSH key
- Use a specific Virtual Server Instance profile called
example-profile
This tutorial uses a fictitious scenario to help you learn and understand a few of the customization options for a deployable architecture. As you complete the tutorial, adapt each step to match your organization's needs.
Before you begin
- Verify that you're using a Pay-As-You-Go or Subscription account by going to Manage > Account > Account settings in the IBM Cloud console.
- Create a repository to store your customized deployable architecture. For the purposes of this tutorial, GitHub is used. For more information, see Create a repo.
- Make sure that you have an editor of your choice set up, for example, Visual Studio Code.
- Verify that you're assigned the following IBM Cloud Identity and Access Management (IAM) roles:
- Administrator on all account management services and all IAM services
- Editor on the Catalog management service
- Manager service access role for Schematics
- Other roles that are required for specific resources in your customized deployable architecture
Downloading the customization bundle
-
In the IBM Cloud console, click Catalog.
-
Select Deployable architectures from the list of Type filters > VSI on VPC landing zone.
-
Click Review deployment options from the summary panel.
-
Select Work with code > Start customizing to download the customization bundle.
-
Open the downloaded bundle on your local computer.
-
If needed, extract the
.tar.gz
customization bundle to access and edit the files.After successfully downloading and extracting the bundle, you'll see the following files and folders:
- automation folder - ibm_catalog.json - main.tf - outputs.tf - provider.tf - README.md - variables.tf - version.tf
-
Rename the bundle
Example-corp-architecture
for findability and ease-of-use.
Editing your list of variables
When you researched VSI on VPC landing zone, you determined that you wanted to modify the region, SSH key, IBM Cloud API key, and VSI profile variables. The other variables that are included in the architecture aren't needed for your purposes, and you would like to remove them by using your favorite editor Visual Studio Code.
-
In Visual Studio Code, open the
variables.tf
file. -
Move the following variables to the start of the
variables.tf
file.existing_ssh_key_name
ibmcloud_api_key
region
prefix
The order of the variables does not matter.
-
Delete all the other variables and save the file.
Updating the main.tf file
Now that you updated the variables.tf
file, make sure that the configuration information in the main.tf
file is correct. Since you want to use an existing SSH key and a specific VSI profile, replace the ssh_public_key
variable and add the vsi_instance_profile
variable.
-
Open the
main.tf
file. -
Replace
ssh_public_key = var.ssh_public_key
with the following text to indicate that you want users to use an existing SSH key and not a public or personal SSH key.existing_ssh_key_name = var.existing_ssh_key_name
-
To hardcode the architecture to use the
example-profile
VSI profile, addvsi_instance_profile = "example-profile"
as the last variable. -
Confirm that the
ibmcloud_api_key
,prefix
, andregion
variables are as shown in the following example.module "deploy-arch-ibm-slz-vsi" { source = "https://cm.globalcatalog.cloud.ibm.com/api/v1-beta/offering/source//patterns/vsi?archive=tgz&flavor=standard&installType=fullstack&kind=terraform&name=deploy-arch-ibm-slz-vsi&version=v4.0.0" ibmcloud_api_key = var.ibmcloud_api_key prefix = var.prefix existing_ssh_key_name = var.existing_ssh_key_name region = var.region vsi_instance_profile = "example-profile" }
-
Save the file.
Your architecture is now hardcoded to use the specific example-profile
VSI profile and configured to use the variables for IBM Cloud API key, prefix, and existing SSH key.
Updating the ibm_catalog.json file
The ibm_catalog.json
file is a manifest JSON file that is used to automatically import version information when you onboard to a private catalog. Because you changed the deployable architecture, you created a brand new architecture
for your needs. Update the following information in the ibm_catalog.json
file to reflect your changes.
Updating the product information
Now that you customized the deployable architecture and created your own architecture, you must also update the name and the programmatic name. For the purposes of this tutorial, update the name to Example Corps' architecture
and the programmatic name to deploy-arch-example-corp
.
- Open the
ibm_catalog.json
file. - Find the
label
field and update the name of your deployable architecture toExample Corps' architecture
. - Find the
name
field and update the programmatic name of your architecture todeploy-arch-example-corp
. - Find the
version
field and enter0.0.1
to update the version number. - Save the file.
Updating the configuration information
Now, you want to make sure that users of your customized architecture must specify an existing SSH key and can deploy it from only US regions and. To do so, update the variable information in the configuration section of the ibm_catalog.json
file.
-
In the
configuration
section of theibm_catalog.json
file, find the following variables and move them to the beginning of the configuration section.existing_ssh_key_name
ibmcloud_api_key
region
prefix
-
To require users to specify an
existing_SSH_key
, change the required field totrue
. -
To restrict the regions to only US regions, you must add each region as an option for the region variable, for example:
{ "key": "region", "type": "string", "default_value": "__NOT_SET__", "description": "Region where VPC is created. To find your VPC region, use `ibmcloud is regions` command to find available regions.", "required": true, "custom_config": {}, "options": [ { "displayname": "us-east", "value": "us-east" }, { "displayname": "us-south", "value": "us-south" } ] }
-
Delete the rest of the variables in the configuration section.
When users deploy your architecture, they can choose between the region options that you listed. For a list of available regions, see Regions.
-
Save the
ibm_catalog.json
file.
Testing your customized deployable architecture
Before you onboard your customized deployable architecture to a private catalog and make it available for use, test your customization to ensure that the architecture runs as intended. To test your architecture with the Terraform command line, complete the following steps:
-
Create or update a
.netrc
file that is needed to use Terraform modules from the IBM Cloud. For more information, see ibmcloud catalog utility netrc.ibmcloud catalog utility netrc
-
Initialize the Terraform CLI. For more information, see Initializing Working Directories.
terraform init
-
Provision the resources. For more information, see Provisioning Infrastructure with Terraform.
-
Run
terraform plan
to generate a Terraform execution plan to preview the proposed actions.terraform plan
-
Run
terraform apply
to create the resources that are defined in the plan.terraform apply
-
Next steps
If your deployable architecture ran as expected, you successfully customized your own architecture from VSI on VPC landing zone. You are now ready to move your updated files to the GitHub repository that you created and onboard your product to a private catalog.