Creating a deployable architecture from an existing offering

You can take advantage of an IBM®-curated deployable architectureCloud automation for deploying a common architectural pattern that combines one or more cloud resources that is designed for easy deployment, scalability, and modularity. to create a new deployable architecture or consume an existing deployable architecture as a module for your teams to use. Each deployable architecture in the catalog provides its own bundle that is available to download and work with. With the bundle, you can edit the deployable architecture on your local computer, use your own pipelines to test, and update the architecture to fit your enterprise's needs. To work with an architecture, you must have familiarity with Terraform.

After you modify the architecture, you can add it to a private catalog and use IBM's tools to check for vulnerabilities, ensure security and compliance, and share the architecture with your enterprise.

Options for working with the bundle

While there are many things that you can do with a deployable architecture provided by IBM, we suggest starting with simple modifications, such as hardcoding or removing variables. For more information, see Creating another configuration from a deployable architecture.

Limitations

There are a few limitations to be aware of when working with deployable architecture bundles downloaded from the catalog:

A deployable architecture includes a provider configuration that is locked to a specific provider version. Any changes to a deployable architecture must work with that provider and version. If your logic calls other modules, those modules must use the same provider and version.
Depending on your changes, IBM Cloud might not support the deployable architecture. The components of the architecture that are supplied in the bundle are supported by IBM Cloud, but any modified code that's used to extend it is not.

Before you begin

To work with deployable architectures, you must have familiarity with Terraform.
Create a repository to store the deployable architecture, for example, a GitHub repository. For more information, see Creating a new repository.
Make sure that you have an editor of your choice to modify the deployable architecture, for example, Visual Studio Code. For more information, see Visual Studio Code.
Make sure that you have the tools of your choice to test your deployable architecture and ensure that it works. For example, you can use Terraform runtime, which supplies the Terraform command line.

Downloading a deployable architecture bundle

IBM Cloud provides multiple deployable architectures that you can use as-is or update to fit your needs. When you choose to update a deployable architecture, you download a .tar.gz file that contains a bundle of terraform files. To download the bundle, complete the following steps:

In the IBM Cloud catalog, select a deployable architecture.
Download the bundle by selecting Review deployment options > Work with code > Customize locally > Download bundle.
If needed, unzip the .tar.gz bundle to access and edit the files.

After successfully downloading and unzipping the bundle, you should see the following:

Using the deployable architecture bundle

When you download the bundle, you receive a set of files that are designed to help you get started with making changes such as modifying variables.

The deployable architecture bundle also includes an automation directory that includes starter scripts to help you manage the lifecycle of your deployable architecture from onboarding and validation to publishing it to a private catalog on IBM Cloud. Currently, two pipeline methods are included in this directory: GitHub actions or a Toolchain from IBM Cloud.

`ibm_catalog.json`

The ibm_catalog.json file is a manifest JSON file that is used to automatically import version information into a private catalog. With a catalog manifest file, you can avoid manually entering version metadata through the console. To view how to set up an ibm_catalog.json file and the values that you can include, see Locally editing the catalog manifest.

`main.tf`

The main.tf file is where configuration information about each deployable architecture that you want to use is stored. Depending on the deployable architecture, you can use this file to specify specific regions, API keys, and source code locations. You can also use this file to add other modules and update the architecture's Terraform parameters.

Example of `main.tf` with specifications

The following example shows Secure infrastructure on VPC for regulated industries using a specific region, us-south:

module "landing-zone" {
  source           = "https://cm.globalcatalog.cloud.ibm.com/api/v1-beta/offering/source//examples/power-sap?archive=tgz&catalogID=7df1e4ca-d54c-4fd0-82ce-3d13247308cd&flavor=power&kind=terraform&name=slz-vpc-with-vsis&version=0.0.22"
  ibmcloud_api_key = var.ibmcloud_api_key
  ssh_public_key   = var.ssh_public_key
  region           = "us-south"
  prefix           = "slz"
}

`outputs.tf`

The outputs.tf file contains available output values that you can include in your deployable architecture. The values are commented out, but you can include the values by removing the # symbol from the value. Also, you can add more output variables to the file. To include certain values, complete the following steps.

Open the outputs.tf file.
Remove the #s from any output value that you want to include.

Example of `outputs.tf`

The following example includes the vsi_names value and excludes the transit_gateway_name value:

output "vsi_names" {
  value       = var.vsi_names
  description = "A list of the vsis names provisioned within the VPCs"
}

#output "transit_gateway_name" {
#  value       = var.transit_gateway_name
#  description = "The name of the transit gateway"
#}

`provider.tf`

The provider.tf file contains required information about which provider, API key, and region that users are required to use.

This information is pulled in from the variables.tf file. If you need to make changes, update the variables.tf file.

Example of a `provider.tf` file

The following example lists IBM as the provider:

provider "ibm" {
  ibmcloud_api_key = var.ibmcloud_api_key
  region           = var.region
}

`README.md`

The readme file contains background and usage information about the deployable architecture. You can customize the readme file to help members of your enterprise use the deployable architecture.

`variables.tf`

The variables.tf file includes the required variables for the deployable architecture. You can add any additional variables that you need.

`version.tf`

The version.tf file stores information about the Terraform version and provider version that is needed to run the deployable architecture. If you are running the deployable architecture as-is, no updates are necessary. Your configuration might require you to update this file. If you need to specify a particular Terraform or provider version, complete the following steps:

Open the versions.tf file.
Update required_version to the Terraform version that users need to use.
Update version to the provider version that users need to use.

Testing your deployable architecture

Before you onboard the deployable architecture that you created with the bundle to a private catalog, test the architecture and ensure that it 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
```
After you create your architecture, initialize the Terraform CLI. For more information, see Initializing Working Directories.
```
terraform init
```
Provision the resources. For more information, see Provisioning Infrastructure with Terraform.
1. Run terraform plan to generate a Terraform execution plan to preview the proposed actions.
```
terraform plan
```
2. Run terraform apply to create the resources that are defined in the plan.
```
terraform apply
```

Creating a release

If your tests were successful, you can prepare to onboard your architecture to a private catalog by making sure that your files are in the repository and creating a release. For more information, see Creating a release.

Onboarding to a private catalog

After you have created your deployable architecture, you can choose to onboard to a private catalog by using automation, the console, or CLI. By using private catalogs, members of your enterprise are required to use approved architectures that they can deploy by using projects.

Using automation to onboard to a private catalog

The bundle has an automation directory that includes a couple of options for starter pipelines. These pipelines can be used to automate the lifecycle of your products that you share by using a private catalog on IBM Cloud. This includes managing the onboarding, validation, and sharing of the deployable architecture version to a private catalog. README files are included for each pipeline option that provide details on how to leverage it. For more information about each one, see GitHub Actions and Creating a toolchain.

Using the console or CLI to onboard to a private catalog

If you'd like to use the console or CLI to onboard your deployable architecture, see onboarding your deployable architecture to a private catalog for step-by-step guidance.

Creating a deployable architecture from an existing offering

Options for working with the bundle

Limitations

Before you begin

Downloading a deployable architecture bundle

Using the deployable architecture bundle

ibm_catalog.json

main.tf

Example of main.tf with specifications

outputs.tf

Example of outputs.tf

provider.tf

Example of a provider.tf file

README.md

variables.tf

version.tf