Before you begin

1. 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.

2. 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 deployable architecture. Cloud automation for Code Engine requires the Writer service access role that is scoped to all resources for the Code Engine service.

   For more information, go to Assigning access to account management services and Managing access to resources.

3. Create a customized deployable architecture called Example Corp's infrastructure and onboard it to a private catalog called Example Corp catalog. This architecture is the one you will be extending as you complete this tutorial.

4. Set up an authentication method. You can use an API key that is stored in Secrets Manager or a trusted profile to authorize a deployment to your target account:

   • Create a Secrets Manager service instance in your IBM Cloud account. To create a secret, you must have the Writer role or higher on the Secrets Manager service. After you create your secret instance, make sure that you select Other secret type to add an arbitrary secret. For information about creating an arbitrary secret, see Creating arbitrary secrets in the UI. Your arbitrary secret must contain the API key. The API key must be created in the target account that you want to deploy to. For more information, go to Using an API key with Secrets Manager to authorize a project to deploy an architecture.

   • Create a trusted profile in the account that you want to deploy to. The trusted profile needs the ability to create a service ID, create and delete API keys for the service ID, and deploy the architecture. For more information, go to Using trusted profiles to authorize a project to deploy an architecture.

Creating a version of a deployable architecture

Since Example Corp's infrastructure is already available in a private catalog, you need to update it with a new version.

1. In the IBM Cloud console, click Manage > Catalogs > Private catalogs and open the private catalog Example Corp catalog.
2. Select Example Corp's infrastructure from the list of products.
3. Click Versions > Add version
4. Select Terraform as the delivery method.
5. Specify whether your repository is public or private and provide the source URL. For the purposes of this tutorial, you can use the same source URL that you used to onboard version 0.0.1 of Example Corp's infrastructure.
6. Select Deploy Example Corp AI app on IBM Cloud Code Engine as the variation.
7. Enter 0.0.2 for the software version.
8. Click Add version

From here, you can configure details for the version that you added.

Extending Example Corp's infrastructure by adding database options

As you configure the version details, extend Example Corp's infrastructure by stacking it with two other deployable architectures that create different databases. You want your users to choose either IBM Cloud Databases for Elasticsearch or IBM Cloud Databases for PostgreSQL. Complete the following steps:

1. From Step 3 - Extend your architecture, click Add.

2. In the Product menu, search for Cloud automation for Databases for Elasticsearch and select it.

3. User Semantic Versioning Specification (SemVer) to list the versions of the architecture that work with Example Corp's infrastructure.

   Typically, patch versions don't contain breaking changes, so you can use SemVer to specify a range of versions that are compatible with Example Corp's infrastructure, for example ~1.32. That way, if Cloud automation for Databases for Elasticsearch is updated with a patch version to 1.32.5, for example, any user who deployed Example Corps with Elasticsearch can update their project to use the new version. For major version changes to Elasticsearch, create a new version of Example Corp's infrastructure to make sure the new version of Elasticsearch functions properly with your architecture.

4. Select Standard variation.

5. Specify Standard as the default variation, which is the variation that is selected for users by default.

6. Select Optional from the Relationship menu, as the architecture is not required to deploy Example Corp's infrastructure.

7. (Optional) provide a display description to help users understand how this architecture works with Example Corp's infrastructure and what benefits it provides. For example, enter NoSQL database for full-text searching and querying large datasets.

8. Click Add.

Now that you added Cloud automation for Databases for Elasticsearch, repeat the steps again but this time, search for Cloud automation for Databases for PostgreSQL. For the optional display description, enter SQL database for relational queries and structured data.

Making the databases swappable with one another

Now that you added both databases as optional to Example Corp's infrastructure, you can specify that they are swappable with one another. Your users can select which database option they want to use with Example Corp's infrastructure. Complete the following steps:

1. From Step 3 - Extend your architecture, select the checkbox for Cloud automation for Databases for Elasticsearch.
2. Select the checkbox for Cloud automation for Databases for PostgreSQL.
3. Click Group as swappable.
4. Enter Databases as the group name and click Add.
5. Click Next.

Define variables for your users

Now that you added some database options to your architecture, you need to define variables for your users. Doing so connects the inputs in the architectures together, which makes it easier for your users to configure Example Corp's infrastructure for deployment.

1. From Step 4 - Configure the deployment details, click Define variables.

   The Define variables window displays with Cloud automation for Databases for Elasticsearch selected for you, so you can access the inputs and outputs from that architecture. From here, you can either add references or move inputs to Example Corp's infrastructure so users can configure them.

2. When Example Corp's infrastructure was created, the region was restricted to the US. To make sure that Cloud automation for Databases for Elasticsearch uses the same region as Example Corp's infrastructure, add a reference to connect them together by completing the following steps:

   1. In the Required inputs window for Cloud automation for Databases for Elasticsearch, select the Reference a variable icon for the region input.
   2. Then, select region in the Variable name menu.
   3. Click Add. When a user configures the region input in Example Corp's infrastructure, Cloud automation for Databases for Elasticsearch will use that value that the user provides as its input.

3. Since Example Corp's infrastructure also contains a prefix input, complete the same steps for the prefix input in Cloud automation for Databases for Elasticsearch:

   1. Select the Reference a variable icon for the prefix input.
   2. Then, select prefix in the Variable name menu.
   3. Click Add.

4. Since Example Corp's infrastructure contains an input for the existing_resource_group_name, you can use that same resource group for Cloud automation for Databases for Elasticsearch:

   1. Select the Reference a variable icon for the resource_group_name input.
   2. Then, select existing_resource_group_name in the Variable name menu.
   3. Click Add.

5. Set the default value for use_existing_resource_group to true to indicate that your users need an existing resource group for your architecture.

6. To simplify setup and reduce costs for a development environment, remove the key encryption requirement by completing the following steps:

   1. Set the default value for existing_kms_instance_crn to __NULL__.
   2. Click Optional inputs.
   3. Set the default value for use_ibm_owned_encryption_key to true.
   4. Set the default value for plan to enterprise.
   5. Set the default value for member_cpu_count to 2.
   6. Set the default value for member_host_flavor to multitenant.

Now that you defined variables for Cloud automation for Databases for Elasticsearch, you need to define variables for the other database option you included: Cloud automation for Databases for PostgreSQL. Complete the following steps:

1. In the Define variables window, use the architecture menu to switch from Cloud automation for Databases for Elasticsearch to Cloud automation for Databases for PostgreSQL.
2. Click Required inputs and remove the key encryption requirement by setting the default value for existing_kms_instance_crn to __NULL__.
3. The three other required inputs in this architecture can all reference inputs that are already available in Example Corp's infrastructure. Complete the following steps to add references to these inputs:
   1. Select the Reference a variable icon for resource_group_name, then select existing_resource_group_name from the Variable name menu. Click Add, and the resource_group_name input within Cloud automation for Databases for PostgreSQL will reference the existing_resource_group_name value from Example Corp's infrastructure that your user provides.
   2. Select the Reference a variable icon for prefix and select prefix from the Variable name menu and click Add.
   3. Select the Reference a variable icon for region and select region from the Variable name menu and click Add.
4. Click Optional inputs.
5. Set the default value for use_existing_resource_group to true to indicate that your users need an existing resource group for your architecture.
6. Set the default value for use_ibm_owned_encryption_key to true.
7. Click Save.

Communicate changes to your users

The latest version of Example Corp's infrastructure doesn't contain breaking changes, but it does include new features that your users need to know about. Let your users know about the new database options they can use with Example Corp's infrastructure by adding a change notice. Complete the following steps:

1. From Step 6 - Add change notices, click Add new feature.
2. In the Title field, enter Database options added to Example Corp's infrastructure.
3. For the Description, enter Version 0.0.2 includes two optional databases that you can choose to add. You can either use Cloud automation for Databases for Elasticsearch, or Cloud automation for Databases for PostgreSQL.
4. Click Save.

From the Actions menu, select Generate manifest to download the latest changes. It's a best practice to download the files and add them to your source code repository so that your changes carry over into your next release.

Validate the architectures by deploying them from a project

Now, version 0.0.2 of Example Corp's infrastructure is available as a draft in your private catalog. Any user with access to your private catalog can deploy it. To make sure that the database options work with Example Corp's infrastructure, deploy it twice from your project. For one deployment, include Elasticsearch. And, for the other deployment, include PostgreSQL. By deploying the architecture twice, you verify that both database options work with Example Corp's infrastructure as intended.

Before you can share Example Corp's infrastructure with your enterprise, you must validate the version as you onboard it to your private catalog. Currently, validating the version in the catalog does not validate any architectures that you stacked with your own. Deploying the architectures from a project while Example Corp's infrastructure is in a draft state in the private catalog helps ensure that the architectures you included function properly with Example Corp's infrastructure.

Next steps

Continue onboarding the latest version of Example Corp's infrastructure. When you're done, a new version of the deployable architecture is available for users. When they add the new version to a project, they can customize it by including Cloud automation for Databases for Elasticsearch or Cloud automation for Databases for PostgreSQL.

If a user already deployed the earlier version of Example Corp's infrastructure, they are prompted in their project with the needs attention widget to update the architecture to the latest version.