IBM Cloud Docs
Onboarding a virtual server image with Terraform to a private catalog

Onboarding a virtual server image with Terraform to a private catalog

Onboarding virtual server images with Terraform is deprecated. After 29 March 2024, onboarding virtual server images with Terraform is no longer supported as a delivery method, which means that no new virtual server images with Terraform can be onboarded. Existing VSIs in the IBM Cloud catalog will be available to use, but to take advantage of version updates and ensure continued support, onboard virtual server images for Virtual Private Cloud directly. For more information, see Onboarding a virtual server image for VPC.

This tutorial walks you through how to onboard a virtual server image with Terraform to a private catalog. By completing this tutorial, you learn how to import the virtual server image from a GitHub repository, configure the deployment and other details, and validate that you can deploy the image to a target IBM Cloud® Virtual Private Cloud (VPC).

This tutorial is one of four in a series that demonstrates how to onboard and publish a sample virtual server image with Terraform to IBM Cloud®. As you complete the tutorial, adapt each step to fit your product's needs.

This tutorial includes deploying the virtual server image to a target VPC. As a result, you will incur associated IBM Cloud infrastructure charges.

Before you begin

  1. Create an instance of IBM Cloud Object Storage and upload your image to a bucket.

  2. Create your VPC.

  3. Import your custom image to all regions in which you want your software to be available.

  4. Create your Terraform template.

  5. Upload your Terraform template and readme file to your GitHub repository.

    Use the latest release of the sample Terraform code as an example of how to set up your repository.

  6. Make sure you're assigned the IBM Cloud Identity and Access Management (IAM) editor role on the Catalog Management and Partner Center - Sell services. See Assigning access to account management services for more information.

  7. Complete the previous tutorials in the series: Registering a virtual server image in the Partner Center and Defining the product details of a virtual server image.

Import the virtual server image to your private catalog

Complete the following steps to import your virtual server image from your GitHub repository to a private catalog, which was created for you when you registered the virtual server image in IBM Cloud Partner Center.

  1. In the IBM Cloud console, click the Navigation Menu icon Navigation Menu icon > Partner Center > My products.

  2. Select your product.

  3. From the Software page, click Import a version.

  4. Select Virtual server image with Terraform as your deployment method.

  5. Confirm that Public repository is selected as the repository type.

  6. Click Virtual server image with Terraform to populate the Source URL field.

    Alternatively, you can copy and paste https://github.com/IBM-Cloud/isv-vsi-product-deploy-sample/releases/download/v1.0/isv-vsi-product-deploy-sample.tar.gz in the field.

  7. Enter 1.0.0 as the software version.

  8. Click Add version.

  9. Click the name of your product.

  10. Click the Edit icon Edit icon.

  11. Confirm that the Delivery method is set to VPC VSI.

  12. Click Save.

Review the version details

From the Configure version tab, you can review your version details. There are no actions that you need to take. After you review your version details, click Next.

Configure the deployment values

After you review the version details, you're ready to configure the deployment values.

  1. If you need to specify the Terraform runtime version that you want Schematics to use, click the Override the default Terraform runtime version checkbox and enter a version.
  2. From the Configure the deployment details section, click Add deployment values.
  3. Select the Parameter checkbox to select all options, and click Add.
  4. To customize which parameters are required for users to specify during the installation and which ones are hidden from users altogether, select a parameter and click Edit. Mark the checkboxes to configure the values and click Save. For the purposes of this tutorial, configure each parameter as described in the following table.
Table 1. Deployment values for a virtual server image
Parameter Description Required for users to specify? Hidden from users?
TF_VERSION The version of the Terraform engine that's used in the Schematics workspace. False True
region The region in which the Virtual Private Cloud (VPC) instance is located. True False
ssh_key_name The name of the public SSH key to use when creating the virtual server instance. True False
subnet_id The ID of the subnet within the VPC that the virtual server instance uses. True False
vsi_instance_name The name of the virtual server instance. True False
vsi_profile The profile of the compute CPU and memory resources to use when creating the virtual server instance. True False
vsi_security_group The name of the security group that is created. True False

Next, update the configuration type of the region parameter:

  1. From the Deployment values table, select the region parameter and click Edit.
  2. Open the Value details menu and select VPC region.
  3. Click Save.
  4. Click Next.

Edit output value descriptions

You can improve the descriptions for your Terraform template's output values to help users better understand the purpose of the parameters. The description of any output value that you include in your template can be updated.

To add output values, you need to include them in a new imported version of your Terraform template.

Complete the following steps to edit the product's output value descriptions:

  1. Click Configure version > Next.
  2. From the Output value descriptions section, provide a new description for the parameter that you want to update.
  3. Click Next.

Define IAM access

After you configure your deployment values, you can add the service access and platform access roles that are required to install your product from the IBM catalog.

Use the following steps to define your product's access:

  1. Click Configure version > Next > Next.
  2. Click Add.
  3. Select the service and the required service and platform access.
    • The service access role allows access for using the service and performing service API calls.
    • The platform access role enables actions to be performed on platform resources, such as creating an instance, connecting instances to apps, and assigning user access.
  4. Click Save.

Add your license agreements

If users are required to accept any license agreements beyond the IBM Cloud Services Agreement, provide the URL to each agreement.

  1. From the Add license agreements page, click Add license.
  2. Enter the name and URL, and click Add license.
  3. Enter all additional license agreements, and click Next.

Review your readme file

The TGZ file that you imported to your private catalog includes a readme file that provides product information for the virtual server image. If you want to make updates to the readme file, you can edit it directly from your private catalog. For the purposes of this tutorial, the following steps describe how to edit the description of the readme file.

  1. Click the Edit icon Edit icon, and update the description with the following sentence:

    Create and deploy a virtual server with ease by using a custom image.

  2. Click Save.

  3. Click Next.

Validate the virtual server image

Validate that you can deploy the virtual server image to your VPC.

  1. From the Validate version page, enter the name of your Schematics workspace, select a resource group, select a Schematics region, and click Next.

    In the Tags field, you can enter a name of a specific tag to attach to your virtual server image. Tags provide a way to organize, track usage costs, and manage access to the resources in your account.

  2. From the Deployment values section, review your parameter values, and click Next.

  3. In the Validate product section, select I have read and agree to the following license agreements.

  4. Click Validate.

    You can monitor the progress of the validation process by clicking View logs.

After the validation completes successfully, you can go back to the Manage compliance page to view the results of the Code Risk Analyzer scan that ran against your controls during validation. Next, you can optionally add on results for an IBM Cloud Security and Compliance Center scan based on a profile that you have already configured in your account for additional evidence of compliance.

  1. On the Validate version page, go to the Submit scan tab.
  2. Select an available scan, and click Submit scan. If you don't have any profile options to choose from, see Building custom profiles.

You can view the results of applying this scan on the Manage compliance page.

Manage compliance

You can add profiles and controls to your software to prove that it meets security and compliance requirements. You must use Security and Compliance Center to scan the resources created during validation.

Only profiles and controls that are supported by the Security and Compliance Center and validated by Security and Compliance Center scans appear in the catalog.

Run a Security and Compliance Center scan

When you claim profiles and controls, you must evaluate the resources that were created during validation to ensure compliance. To run a scan, complete the following steps:

  1. In the IBM Cloud console, click the Menu icon Menu icon > Security and Compliance to access Security and Compliance Center.
  2. In the navigation, click Profile.
  3. Click the Overflow menu in the row of the profile that you want to evaluate and select Run scan.
  4. Click Run scan.

After your scan completes, you can return to your private catalog to continue the onboarding process.

Adding compliance controls

Add the profiles and controls that you want to claim.

  1. In the Manage compliance section of your product, select Add claims.
  2. Select the profile that you want to add.
  3. Choose to add the entire profile or a subset of controls.
  4. If you choose an entire profile, continue to the next step. If you choose to add a subset of controls, select the controls that you want to add.
  5. Click Add.

Applying Security and Compliance Center scans

Add the scans that you previously ran in the Security and Compliance Center. Security and Compliance Center scans determine adherence to regulatory controls. For more information, see Running a scan on demand.

  1. Click Add scan.
  2. Select the profile that you used for the evaluation.
  3. Select the Security and Compliance Center scan.
  4. Click Apply scan.
  5. Click Next.

Review requirements

You must complete validation and any other requirements to publish your virtual server image.

Next steps

The virtual server image isn't yet publicly available to other accounts. Use a REST API to make the image public so that users can use it to create virtual server instances. For more information, see Update the visibility of your image.

After you make the virtual server image public, you can return to the Partner Center and publish it to the catalog. For more information, see Publishing a virtual server image to the IBM Cloud catalog.