IBM Cloud Docs
Planning for using workspaces

Planning for using workspaces

Plan and design your workspaces using the following questions as prompts:

  • How do I relate workspaces to Git repositories?
  • How many workspaces does my application environment need?
  • How do I reuse Terraform configuration files across environments and workspaces?
  • How do I control access to and manage my workspaces?

Workspaces and Git repositories

Workspaces use Terraform templates from private or public Git repositories such as GitHub, GitLab, Bitbucket, and Azure DevOps. The table provides the format of the repositories source.

Git repositories
Git repositories URL
GitHub https://github.com/<your_user_name>/<repo_name>/tree/<branch_name>/<folder_name>
GitLab https://gitlab.com/<your_user_name>/<project_name>/tree/<branch_name>/<folder_name>
Bitbucket https://bitbucket.org/<your_user_name>/<repo_name>/src/<branch_name>/<folder_name>
https://<username>@bitbucket.org/<workspace_name>/tf_cloudless_sleepy/src/master
Azure DevOps https://azure.com/<your_user_name>/<repo_name>/src/<branch_name>/<folder_name>
https://visualstudio.com/<your_user_name>/<repo_name>/src/<branch_name>/<folder_name>

How many workspaces does my application environment need?

The number of workspaces you need in IBM Cloud Schematics are determined by the structure of your application and the environments that you need to develop, test, and publish your application or micro-service.

As a rule of thumb, consider separate workspaces for each microservice and the environments that you use. For example, if you have a product app that consists of a search, payment, and review microservice components, consider creating separate workspaces for each microservice component and their development, staging, and production environments. With separate workspaces for each component and environment, you can develop, deploy, and update your Terraform configuration files and associated IBM Cloud resources without affecting other components.

Review the following image, observing the workspace structure IBM Cloud Schematics for an app that consists of three microservices.

Workspace structure for IBM Cloud Schematics
Figure 1. workspace structure for IBM Cloud Schematics

In organizations where infrastructure responsibilities are spread across multiple teams, it is not recommended to use one workspace to manage entire staging or production environments. When you deploy all your IBM Cloud resources using a single workspace, it can become difficult for various teams to coordinate updates and manage access for these resources. Separate workspaces, sharing infrastructure definitions using remote-state data sources provides a mechanism to create separate out areas of responsibility.

How do I structure my Git repositories to map my workspaces?

Structure your Git repository so that you have one repository for all your Terraform configuration files that build your microservice, and use input variables in Schematics, or GitHub branches or directories to differentiate between your development, staging, and production environments.

Review the following table to find a list of options for how to structure your Git repository to map the different workspace environments.

Structure of the Git repository
Option Description
One Git repo, use variables to distinguish between environments Create one Git repository where you store the Terraform configuration files that make up your microservice component. Make your Terraform configuration files as general as possible so that you can reuse the same configuration across your environments. To configure the specifics of your development, staging, and production environment, use Terraform input variables in your configuration files. Input variables are automatically loaded into IBM Cloud Schematics when you create your workspace. To customize your workspace, you enter the environment-specific values for your variables. This setup is useful if you have one team that manages the lifecycle of the microservice component and where the configuration of your environments does not differ drastically.
One Git repo, use branches to distinguish between environments Create one Git repository for your microservice component, and use different Git branches to store the Terraform configuration files for each of your environments. With this setup, you have a clear distinction between your environments and more control over who can access and change a particular configuration. Make sure to set up how changes in one configuration file are populated across branches to avoid that you have different configurations in each environment.
One Git repo, use directories to distinguish between environments For organizations that prefer short-lived branches, and where configurations differ drastically across environments, consider creating directories that represent the different configurations of your environments. With this setup, all your directories listen for changes that are committed to the master branch. Make sure to set up how changes in one configuration file are populated across directories to avoid having different configurations in each environment.
Use one Git repo per environment Use one Git repository for each of your environments. With this setup, you have a 1:1 relationship between your workspace and Git repository and you can apply separate permissions for each of your Git repositories. Make sure that your team can manage multiple Git repositories and keep them in sync.

How can I reuse configuration files across environments and workspaces?

Try to minimize the number of Terraform configuration files that you need to manage by creating standardized Terraform templates and by using variables to customize the use of a template to your needs.

Now, you can use Terraform modules from the Terraform module registry for IBM Cloud.

With standardized Terraform templates or Terraform modules, you can ensure that development best practices are followed within your organization and that all Terraform configuration files have the same structure. Knowing the structure of a Terraform configuration file makes it easier for your developers to understand a file, declare variables, contribute to the code, and troubleshoot the errors.

How do I control access to my workspaces?

IBM Cloud Schematics is fully integrated with IBM Cloud® Identity and Access Management. To control access to a workspace, and who can execute your infrastructure code with IBM Cloud Schematics, see Managing user access.

What do I need to be aware of when I have a repository that has been previously used with Terraform standalone?

Because IBM Cloud Schematics delivers Terraform-as-a-Service, you can reuse your existing Terraform templates with workspaces. Depending on how your Terraform templates are written and Git repositories structured, you might need to make changes to successfully use IBM Cloud Schematics.

  • Provider block declaration: Because IBM Cloud Schematics is integrated with IBM Cloud® Identity and Access Management, your IBM Cloud API key is automatically retrieved for all IAM-enabled resources and you don't have to provide this information in the provider block. However, the API key is not retrieved for classic infrastructure resources. For more information, see Configuring the provider block.
  • Terraform command-line and IBM Cloud provider plug-in: To use IBM Cloud Schematics, you don't need to install the Terraform command-line or the IBM Cloud Provider Plug-in for Terraform. If you want to automate the provisioning of resources, try out the IBM Cloud Schematics command-line plug-in instead.

Setting up a continuous delivery toolchain for your workspace

Connect your source repository to a continuous delivery pipeline in IBM Cloud to automatically generate a Terraform execution plan and run your Terraform code in IBM Cloud whenever you update your Terraform configuration files.

  1. If you do not have a Continuous Delivery service instance in your account yet, create one.
    1. From the IBM Cloud catalog, open the Continuous Delivery service.
    2. Select the IBM Cloud region where you want to create the service.
    3. Select a pricing plan.
    4. Enter a name for your service instance, select a resource group, and enter any tags that you want to associate with your service instance.
    5. Click Create to create the service instance in your account.
  2. From the workspace dashboard, select a workspace.
  3. Select the Settings tab.
  4. In the Summary section, click Enable continuous delivery.
  5. Configure your toolchain.
    1. Enter a name for your toolchain, and select the region and resource group where you want to deploy this toolchain. The region and resource group can be different from the region and resource group that you used for your Schematics workspace.
    2. Select the type of source repository where your Terraform configuration files are stored. For Example GitHub.
    3. Review the information for your source repository. For example, if your Terraform files are stored in GitHub, review the GitHub server and the repository for which you want to create a continuous delivery toolchain. These fields are pre-populated based on your workspace configuration.
    4. Optional: Choose if you want to enable Git issues and code change tracking for your toolchain.
  6. Select the Delivery Pipeline icon to configure your Delivery Pipeline.
    1. Verify that the workspace ID that is displayed to you is correct.
    2. Enter an IBM Cloud API key. If you do not have an API key, click New + to create one.
  7. Click Create to finish the setup of your toolchain. You see an overview of tools that were configured for your toolchain.
  8. Open the Delivery Pipeline. The Delivery Pipeline includes stages to retrieve updates from your source repository, create a Terraform execution plan, apply this plan, and to run a health check against your workspace.
  9. Update the Terraform file in your source repository and review how this change is processed in your Delivery Pipeline. If one of the stages fails, click View logs and history to start troubleshooting errors. For more information about viewing logs and history, see Reviewing the Schematics job details.