Moving resources from a Schematics workspace into a project

You can manage the lifecycle of an enterprise architecture by moving resources from an IBM Cloud® Schematics workspace into an IBM Cloud® project. While you can use a Schematics workspace for using Terraform and deployable architectures, you can use a project to manage the full lifecycle at scale. After you complete this task, you have a deployable architecture tile in your private catalog, and you can manage your deployable architecture's lifecycle from a project.

During this process, you can use the CLI commands ibmcloud catalog utility create-product-from-workspace and ibmcloud project config-create to create a catalog and a project that are linked together, and then move the Schematics workspace resources into the project.

Watch and learn the process of moving deployed resources to a project.

Watch and learn

Video transcript

I am Gili Mendel, an STSM with the IBM Cloud development team. I am going to show you how to move a Schematics workspace in the IBM Cloud deployable architecture or a project.

A Schematics workspace is the way that you run a Terraform automation on the IBM Cloud. The workspace holds a link to a Git repository from which it fetches the Terraform template. It also holds the template variable, and the resources state as it creates it.

It is a great way to run Terraform IaaS automation on the cloud without maintaining a highly available IBM Cloud® Object Storage bucket for the state with the intimate integrations to cloud resource providers.

However, this approach does not scale if you are driving multiple automations. Managing the resources and rolling up a new version of the template can be a daunting task.

Although an enterprise leverages Terraform automation, is all about deployable architectures. You publish a reference architecture, with a compliance footprint designation, cost estimates, and a Terraform template that automates the deployment of the architecture.

The Git repository is used to iterate and build the architecture and its automations. It might or might not be visible to users that deploy the architecture. The architecture itself has a lifecycle that includes version upgrades.

Step 1: Use the Catalogs management CLI to create a deployable architecture from the existing workspace, and the lifecycle that is needed to publish the new versions for it.

Step 2: Use the Project CLI to modify the workspace so that it is managed as a deployable architecture by a project. As such, these resources can be treated as a single deployable architecture version configuration and can be managed from an admin account across many environments. Version migration, cost, and the compliance footprint are simpler and is all involving the architecture that is deployed.

Before you begin

Make sure that the IBM Cloud® Schematics workspace is created and the resources are provisioned in your account. The project and the workspace must be in the same account.
Set a GIT_TOKEN environment variable to authenticate your Git source repository. For example, run export GIT_TOKEN="enter your GIT TOKEN".
Set access to your account in either of the following ways:
- Set the IC_API_KEY environment variable to access your IBM Cloud account. For example, run IC_API_KEY="Your API key".
- Use your trusted-profile-id details to access your IBM Cloud account. For more information, see Finding the trusted profile ID. For example, a trusted profile ID might look similar to Profile-1bd5eala-000-4a6666-00000.
Make sure that the Project and Catalogs management CLI plug-ins are up to date. Run the ibmcloud plugin list command to view the current version of the CLI plug-ins.
Create a project for production deployment and record the name and ID of the project where you want to move the resources.
Make sure that the Projects service is authorized in your account to communicate with other IBM Cloud services. For more information, see Granting access between the Projects service and other IBM Cloud services.

Creating a deployable architecture from a Schematics workspace

Skip this section if you already have a deployable architecture in your Schematics workspace.

If you deployed software by using a Schematics workspace or through a private catalog, you can move the deployed resources to a project by using the ibmcloud catalog utility create-product-from-workspace command.

The command does the following Git-related tasks:

Clones the deployable architecture repo.
Pushes the ibm_catalog.json manifest file to a new branch.
Creates a placeholder architecture diagram (architecture-diagram-placeholder.drawio.svg).
Creates a Git release in the repo.
Provides the release asset URL.

The command also completes the following IBM Cloud-related tasks:

Creates a private catalog in IBM Cloud.
Creates a project where you do development and testing.
Links the project and catalog together by using a trusted profile ID or an API key.
Creates the product tile in the private catalog.
Onboards the product version to the new private catalog.
Marks the version as ready to share.
Completes the onboarding of the workspace and the deployable architecture by moving the workspace to the catalog.
Shows you the project ID, catalog ID, offering ID, and version locator.

Complete the following steps to create a deployable architecture and move all the deployed resources into a project configuration:

Run the ibmcloud catalog utility create-product-from-workspace command.

ibmcloud catalog utility create-product-from-workspace [--workspace-id ID] [--api-key KEY] [--trusted-profile-id ID] [--catalog-label LABEL] [--offering-label LABEL] [--project-name NAME] [--project-resource-group GROUP] [--target-version VERSION] [--variation-label LABEL]

--api-key and --trusted-profile-id are mutually exclusive. You need only one or the other. The --project-name parameter creates the project where you do development and testing. You might want to name it the same as your workspace ID for simplicity.

See the following example of the utility create-product-from-workspace command options.

ibmcloud catalog utility create-product-from-workspace --workspace-id us-south.workspace.move.xxxx --api-key $IC_API_KEY --catalog-label myCatalog --offering-label myOffering --project-name myProject --project-resource-group Default --target-version 1.0.0 --variation-label test_standard

When the command is finished running, the command prompt returns OK.

Verify the results in Git by viewing the commit, repo, and the new release. You can see the .tgz file with the versions.
Verify the results in the IBM Cloud console:
1. Go to Manage > Catalogs > Private catalogs.
2. Select the new private catalog.
3. Select the new product in your private catalog, and then select the Versions tab. See that you have version 1.0.0 (or similar) of your deployable architecture. If you go to your private catalog, you see the same deployable architecture in a tile.
4. Click the Navigation menu icon > Projects, and look at the new project.
5. Select the Configurations tab to see the deployable architecture. See that it is in draft status.

Creating the project configuration

The ibmcloud project config-create command creates a project configuration that makes the Schematics workspace run under a project where you can then create another version from the project and modify the deployable architecture as needed.

Before you begin this section, make sure that you have a deployable architecture in a private catalog and a running Schematics workspace and know its CRN. You can locate the workspace CRN either from the resource list in the IBM Cloud console or by using the CLI.

IBM Cloud console: In the IBM Cloud console, click the Navigation menu icon > Resource list > Developer tools > find the workspace, and copy the CRN.
IBM Cloud CLI: Run the ibmcloud schematics workspace get command to fetch the workspace CRN details. For example, run ibmcloud schematics workspace get --id workspace-id --output destination folder --json output.json to fetch the Schematics workspace CRN details.

Complete the following steps to add a project configuration and move the Schematics workspace resources to the project:

Run the ibmcloud project config-create command.
```
ibmcloud project config-create --project-id PROJECT-ID [--schematics-workspace-crn SCHEMATICS-WORKSPACE-CRN] [--definition-name DEFINITION-NAME] [--definition-locator-id DEFINITION-LOCATOR-ID]
```
The value for --project-id is from the project that you created for deployment-production by using the Projects UI earlier. The value for --definition-locator-id is the same as the version locator from the previous section.

See the following example of project config-create command options.
```
ibmcloud project config-create --project-id myProdProject --schematics-workspace-crn MyWorkspaceCRN --definition-name production-deployment --definition-locator-id myVersionLocator
```
When the command is finished running, the command prompt returns the name, state, and type.
Verify that your Terraform templates are deployed in your project:
1. In the IBM Cloud console, click the Navigation menu icon > Projects.
2. Select your project that you first created for deployment production, and go to the Configurations tab.
3. Click the Actions icon > View last deployment.
4. In the Deployment successful section, click Changes deployed successfully > Logs to view all the deployed resources in the project.

The Schematics workspace deployment is now included in the logs that are inside the new project.

If you want to verify the results by using the CLI, run the ibmcloud project get or ibmcloud project list commands to verify that your workspace was successfully moved to your project.

Next steps

To complete the remainder of the process for the deployable architecture, complete the following steps:

Configure deployment details for the deployable architecture.
Define IAM access.
Add an architecture diagram, prereqs, and highlights.
Add compliance information (controls).
Revalidate to receive a cost estimate.

For more information about how to complete the steps, see Onboarding a customized deployable architecture to your private catalog.

For more information, see Adopting the Enterprise Architecture.