May 3, 2023 By Frederic Lavigne 8 min read

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:

Simple architecture including a resource group, a virtual private cloud and access groups.

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:

Terraform template to create a simple architecture.

The full set of resources required for this architecture can be found in the companion Git repository.

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.

A catalog to distribute your deployable architectures.

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 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 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:

Imported my first deployable architecture.

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:

Ready to validate the deployable architecture.

The deployable architecture is successfully validated.

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

The deployable architecture is ready to share.

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:

Simple deployable architecture available in a private catalog.

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.

Deploying the architecture with only a few clicks.

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:

Project configuration deployed. Resource group, virtual private cloud and access groups have been created.

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:

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.

Was this article helpful?

More from Cloud

Enhance your data security posture with a no-code approach to application-level encryption

4 min read - Data is the lifeblood of every organization. As your organization’s data footprint expands across the clouds and between your own business lines to drive value, it is essential to secure data at all stages of the cloud adoption and throughout the data lifecycle. While there are different mechanisms available to encrypt data throughout its lifecycle (in transit, at rest and in use), application-level encryption (ALE) provides an additional layer of protection by encrypting data at its source. ALE can enhance…

Attention new clients: exciting financial incentives for VMware Cloud Foundation on IBM Cloud

4 min read - New client specials: Get up to 50% off when you commit to a 1- or 3-year term contract on new VCF-as-a-Service offerings, plus an additional value of up to USD 200K in credits through 30 June 2025 when you migrate your VMware workloads to IBM Cloud®.1 Low starting prices: On-demand VCF-as-a-Service deployments begin under USD 200 per month.2 The IBM Cloud benefit: See the potential for a 201%3 return on investment (ROI) over 3 years with reduced downtime, cost and…

The history of the central processing unit (CPU)

10 min read - The central processing unit (CPU) is the computer’s brain. It handles the assignment and processing of tasks, in addition to functions that make a computer run. There’s no way to overstate the importance of the CPU to computing. Virtually all computer systems contain, at the least, some type of basic CPU. Regardless of whether they’re used in personal computers (PCs), laptops, tablets, smartphones or even in supercomputers whose output is so strong it must be measured in floating-point operations per…

IBM Newsletters

Get our newsletters and topic updates that deliver the latest thought leadership and insights on emerging trends.
Subscribe now More newsletters