Your first step in succeeding with your platform engineering journey.

Recently, IBM Cloud introduced projects and deployable architectures. Projects are a named collection of configurations that are used to manage related resources and Infrastructure as Code (IaC) deployments. A deployable architecture is a cloud automation for deploying a common architectural pattern that combines one or more cloud resources that are designed for easy deployment, scalability and modularity.

Projects and deployable architectures enable teams to capture best practices into reusable patterns, get started with new environments in a few clicks and ensure that the environments remain compliant, secure and up-to-date over time. IBM Cloud provides a set of ready-to-use deployable architectures that can be deployed as-is or extended to meet your needs.

In this blog post, I will walk you through the steps of turning a simple Terraform template into a deployable architecture in a private IBM Cloud catalog. Eventually, you could build your own deployable architectures (or extend an existing one) to capture recommended security configurations and build pipelines and architectures for new projects in your organizations.

Note that you will need a paid IBM Cloud account if you plan to go through all the steps in your own account.

Capture best practices in a template

If you are already using Terraform to deploy your infrastructure, you’ve already been creating a deployable architecture. The only difference is that you might have had to come up with your own approach to distribute the templates across your company and manage updates.

With the native support for deployable architectures provided by IBM Cloud, you can turn your template into a tile in a private IBM Cloud catalog. The tile will allow self-service infrastructure to be deployed by your teams while ensuring that the provisioned resources adhere to your company standards and controls.

Let’s consider the following architecture that could be the starting point for new application development:

This architecture includes the following:

• A resource group to isolate all resources required by the application
• A virtual private cloud (VPC) to deploy virtual server instances or Red Hat OpenShift clusters
• Access groups for administrators, operators and developers to implement separation of duties between team members

The main Terraform template for this architecture would look something like this:

Turn your template into a deployable architecture

At this stage, we have a set of Terraform files. A deployable architecture, as defined by IBM Cloud, is slightly more than just the Terraform files. It has the ability to turn a template into a product. By product, I mean a package including the following:

• A version number so that you can manage product lifecycle
• The Terraform templates and its inputs and outputs
• IAM permissions to document what are the required permissions to deploy your architecture (very useful!)
• Architecture diagrams so that the users looking at your product can understand what it is about
• Prerequisites in case your product is not self-contained and must be deployed on top of another deployable architecture (yes, this is supported)
• Flavors so you can bundle different variations of your deployable architecture (think small, medium, large configurations, for example, or proof-of-concept vs. production)
• End-user license agreements so that you can define your own usage rules
• A readme file (it is always good to provide some documentation)
• Cost information to provide a rough estimate about the cost of deploying the architecture
• Compliance information to capture all the controls implemented by your architecture

As you onboard your deployable architecture into IBM Cloud, you will be able to specify all of the above in the IBM Cloud console. Alternatively, the catalog manifest (a JSON file) provides a nice way to capture all this information as part of the Git repository hosting your Terraform templates. A template for this manifest is available here.

For our example, the manifest is provided at the root of the repository. It must be named ibm_catalog.json. If you look at the file, you will recognize most of the content listed above (version information, descriptions, architecture diagrams, inputs and outputs).

The deployable architecture is now almost ready to be included in your private IBM Cloud catalog. It just needs to be packaged into a single archive. In GitHub, this is as easy as creating a new release. The resulting archive (a .tar.gz) is exactly what private IBM Cloud catalogs need.

Create a catalog to distribute your deployable architecture

I’ve been using the word “catalog” without a proper introduction. As an IBM Cloud user, you must be familiar with the IBM Cloud catalog—it’s where you are finding all the products you can provision in IBM Cloud. Did you know that you can create your own private catalogs with your own products or a remix of IBM Cloud products?

A private catalog includes products, and each product can have multiple versions. You are in control of which products and versions you made available to others. When the time comes, you can deprecate versions and retire versions and products.

1. In the IBM Cloud console, go to Catalog management.
2. Create a catalog:
   • Select Product as the catalog type.
   • Give the catalog a name: “my-catalog.”
   • Start with no products.
   • Click Create.

Distribute the deployable architecture as an accelerator for new projects

Our private catalog is ready to welcome our deployable architecture.

To add the deployable architecture to the private catalog:

1. Click Add.
2. Select Deployable architecture as the product type.
3. Select Terraform as the delivery method.
4. Keep Public Repository as the repository type. Catalogs give the option to host the deployable architecture in private repositories if needed.
5. Go to https://github.com/l2fprod/simple-da/releases/latest to find the link to the archive file of the most recent version of the deployable architecture for this blog. At the time of this post, the most recent is https://github.com/l2fprod/simple-da/archive/refs/tags/v1.0.17.tar.gz. Enter the URL in the Source URL field.
6. Select Standard as the variation. The software version and category get populated automatically.
7. Click Add product.

The product is now added and the first version is ready to be validated. You will notice that a lot of the information has been pre-filled for you. This is because we provided the catalog manifest ibm_catalog.json in the archive. This makes it easy to reduce the number of manual steps and to manage your metadata as code:

The next step is to use the action menu on the imported version and to go through the validation phase. The validation gives you an opportunity to review all provided information and to perform a test deployment of the architecture:

After the deployable architecture is successfully validated, you can review the cost estimate and compliance. Then, the product is ready to share with others:

This deployable architecture is now a product in this private catalog. It can have multiple versions, just like any software you install on your computer. When a new version is available, users of the deployable architecture will be able to update their existing deployment to benefit from the latest and greatest.

Start your next project quickly

The deployable architecture should now be visible in your private catalog. Go back to the IBM Cloud catalog. Notice a new dropdown to select the active catalog. Use it to switch to the my-catalog catalog that you created. There, you’ll see the deployable architecture that we imported:

The next step is to create an instance of this deployable architecture. Anyone with access to the private catalog can do this. The architecture will be added to a project, and you can start managing its resources from there and evolve the deployed configuration as new versions of the architecture are made available in the catalog:

1. Select the deployable architecture.
2. Review deployment options.
3. Select Add to project.
4. Set the project name to “simple-da.”
5. Create the project.
6. Edit the configuration to your needs:
   • Enter an API key to use for deployment.
   • Optionally, set a prefix for the resources to be created.
7. Save and Validate the configuration.

After the validation completes, you can deploy the architecture. As part of the deployment, it will create a resource group, a virtual private cloud and access groups. As you release new versions of the product, the project will notice and offer a seamless upgrade path for all configurations by using the product:

Get started

Even though the example in this post is rather simple, in few steps, you went from a set of Terraform files to a tile in a private catalog where you can configure visibility and lifecycle of the product and versions.

In addition, this project gives you visibility on the cost of the configuration, ensures that the deployed resources are secure and compliant with the controls selected by your organization, and provides a clear approach to deploying new versions and managing upgrades.

You should now have a good understanding of the basics of deployable architectures and projects. The next step is to understand how they can be used within your organization. I would recommend reading the article on how to run secure enterprise workloads. It goes through the concepts in great details. In addition, start browsing the growing list of deployable architectures available in the IBM Cloud catalog and learn how you can customize and extend them to your needs. And as you embark in creating your own deployable architectures, keep in mind that automation through CLI or Terraform can also be used to build and make your deployable architecture available in private catalogs.

To learn more about projects and deployable architectures, see the following articles:

• Projects and Cost Estimation: How IBM Cloud is Revolutionizing Complex Workloads for Enterprises
• Accelerating and Maintaining Your Regulated Standards at Scale

Feedback, questions and suggestions

Go ahead and try the sample on your own from the GitHub source. If you have feedback, suggestions, or questions about this post, please reach out to me on Linkedin.