Onboarding software to your account

The process to onboard software to your account includes importing a version to a private catalog, validating that the version can be successfully installed on the target infrastructure that you require, and publishing the software to your account. The software is then available to users in your account.

Before you begin

Verify that you're using a Pay-As-You-Go or Subscription account. See Viewing your account type for more details.
Review the list of software that you can onboard:
- Helm charts on Kubernetes and Red Hat OpenShift on IBM Cloud clusters
- Terraform templates
- OVA images that are deployed on VMware Solutions Dedicated - vCenter Server
- Virtual server images with Terraform deployed on VPC infrastructure or Power Virtual Server
- Virtual server images for VPC
Onboarding Virtual Server Images for VPC with IBM Z® deployment support is available in private catalogs. The onboarding experience for IBM Z-supported Virtual Server Images is the same as how you onboard other Virtual Server Images in your private catalog.
- Operators with TGZ file from GitHub or GitLab repositories
- Operator bundles from Red Hat OpenShift registries
There is no requirement to upload your source code to a release on your GitHub or GitLab repository if you are deploying VSI on VPC. Instead, ensure you have a custom image ready and available in your account. See Importing and validating custom images into VPC.
Make sure you are assigned the following IAM access:
- Manager role on the Schematics service
- Editor role on the catalog management service
- Viewer role on all resource groups in your account. You need access to at least one resource group to run the validation
- Writer role on the Secrets Manager service. This role is not required if you are using VSI on VPC
Install the IBM Cloud CLI and the IBM Cloud Schematics plug-in. See Setting up the CLI for more information.

For containerized apps, complete the following prerequisites:

Create your Kubernetes cluster or Red Hat OpenShift cluster.
For deployments to IBM Cloud Kubernetes Service, set up your Helm chart.
For deployments to Red Hat OpenShift, set up your Helm chart or Operator.

For virtual server images, complete the following prerequisites:

Review the list of supported images.
If required, create your Terraform template. Virtual server image for VPC does not require a Terraform template.
Create an instance of IBM Cloud Object Storage and add your image to a bucket.

Before you can onboard software to your account by using Terraform, make sure that you have completed the following:

Install the Terraform CLI and configure the IBM Cloud Provider plug-in for Terraform. For more information, see the tutorial for Getting started with Terraform on IBM Cloud®. The plug-in abstracts the IBM Cloud APIs that are used to complete this task.
Create a Terraform configuration file that is named main.tf. In this file, you define resources by using HashiCorp Configuration Language. For more information, see the Terraform documentation.

To share software with other accounts, your software must be approved in Partner Center. For more information, see Getting set up to sell software.

Creating a private catalog

Private catalogs provide a way for you to manage access to products for users in your account.

Go to Manage > Catalogs in the IBM Cloud console, and click Create a catalog.
Enter a name and description of your catalog.
Select to exclude or include all products in the IBM Cloud catalog in your private catalog. For more information about how this affects visibility in the catalog, see Managing catalog settings.
Click Create.

Importing software to your private catalog

Complete the following steps to import software to your private catalog:

Adding catalog entry details

When you publish your product to the catalog for users with access to your private catalog, they see a tile with the product name and other details that add during onboarding. In addition to the category that you set when you import your software, you can add other filters that are related to industry, compliance, technologies it works with, and more. Each of these filters is used in the catalog for users to find software that fits their needs. In the catalog entry details section, you can also evaluate and make updates to the short descriptions, documentation URL, and even keywords to help user search and find your product quickly.

From the Catalog entry details section, click the Edit icon .
Review the information that was imported with your product, and make edits as needed.
Review the filters and industry options to select catalog filters that apply. You can select up to five industry filters.
Check your catalog entry preview to see how your catalog tile displays to users who are evaluating your software in the catalog.
Click Save when you're happy with your changes.

For more information, see Defining your product details.

Configuring the software

Helm chart

From the version list that's displayed on the product details page, click the row that contains your software.
Review the version details, and click Next.
Configure the preinstallation, and click Next.
Configure the deployment details by setting the access that's required to run the installation script and setting the deployment values, and click Next.

Terraform

From the version list that's displayed on the product details page, click the row that contains your software.
Review the version details, and click Next.
Configure the deployment values.
If applicable, edit the output value descriptions, and click Next.
Define the required IAM access, and click Next.

Operator from GitHub repository

From the version list that's displayed on the product details page, click the row that contains your software.
Review the version details, and click Next.

Operator from Red Hat registry

From the version list that's displayed on the product details page, click the row that contains your software.
Review the version details, and click Next.

OVA image

From the version list that's displayed on the product details page, click the row that contains your software.
Review the version details, and click Next.

Virtual server image with Terraform

From the version list that's displayed on the product details page, click the row that contains your software.
Review the version details, and click Next.
Configure the deployment values.
If applicable, edit the output value descriptions, and click Next.
Define the required IAM access, and click Next.

Virtual server image for VPC

From the version list that's displayed on the product details page, click the row that contains your software.
Review the list of images, and click Next.
Review the version details, and click Next.

Adding license agreements

Provide the URLs to the license agreements that users are required to accept when they install the product. The license agreements are in addition to the IBM Cloud Services Agreement.

Click Add license agreements > Add license.
Enter the name and URL, and click Update > Next.

Editing your readme file

When users install the software, they can select the link to your readme file to view product information. The information in the Readme link is generated from the readme file that you uploaded to your source repository.

From the Edit readme tab, preview how the information in the readme file will be displayed to users when they install the software.
To make updates, click the Edit icon next to the Readme section title.
Click Save.
Click Next.

If you are importing a virtual server image for VPC, the readme file is not automatically generated. Copy and paste the contents of the readme file template and make updates as needed.

Validating the software

When you validate your software, you're confirming that the current version can be successfully installed on the deployment target. The validation steps vary based on your deployment method.

To monitor the progress of the validation process, click View logs.

Helm chart

From the Validate product tab, select your cluster.
If the deployment target is a Kubernetes cluster, select a namespace or create a new one. If the deployment target is a Red Hat OpenShift cluster, select a project or create a new one.
Click Next.
Configure your IBM Cloud Schematics workspace.
Click Next.
If applicable, review the license agreements, and select I have read and agree to the following license agreements:.
Click Validate.

Terraform

From the Validate product tab, configure your IBM Cloud Schematics workspace.
Click Next.
If applicable, review the license agreements, and select I have read and agree to the following license agreements:.
Click Validate.

Operator from GitHub repository

From the Validate product tab, select your Red Hat OpenShift cluster.
Select a project or create a new one. A project is similar to a Kubernetes cluster namespace, and the list is populated from your Red Hat OpenShift environment.
Click Next.
Configure your IBM Cloud Schematics workspace.
Click Next.
If applicable, review the license agreements, and select I have read and agree to the following license agreements:.
Click Validate.

Operator from Red Hat registry

From the Validate product tab, select an update channel.
Select an approval strategy.
Select your Red Hat OpenShift cluster.
Select a project or create a new one. A project is similar to a Kubernetes cluster namespace, and the list is populated from your Red Hat OpenShift environment.
Click Next.
Configure your IBM Cloud Schematics workspace.
Click Next.
If applicable, review the license agreements, and select I have read and agree to the following license agreements:.
Click Validate.

OVA image

From the Validate product tab, review the license agreements, and select I have read and agree to the following license agreements:.
Click Validate.

Virtual server image with Terraform

From the Validate product tab, configure your IBM Cloud Schematics workspace.
Click Next.
If applicable, review the license agreements, and select I have read and agree to the following license agreements:.
Click Validate.

Virtual server image for VPC

From the validate version tab, configure the validation target, and click Next.
Optionally, configure your Schematics workspace, and click Next.
If applicable, review the license agreements, and select I have read and agree to the following license agreements:.
Click Validate.

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:

In the IBM Cloud console, click the Menu icon > Security and Compliance to access Security and Compliance Center.
In the navigation, click Profile.
Click the Overflow menu in the row of the profile that you want to evaluate and select Run scan.
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.

In the Manage compliance section of your product, select Add claims.
Select the profile that you want to add.
Choose to add the entire profile or a subset of controls.
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.
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.

Click Add scan.
Select the profile that you used for the evaluation.
Select the Security and Compliance Center scan.
Click Apply scan.
Click Next.

Review requirements

You must complete validation and any other requirements to share to your account. When you're ready to make your product available to all users who have access to your private catalog, click Ready to share.

Sharing the software

If you want to share your product to your account or enterprise, click the name of the product in the navigation to go to the product details page. From the Actions menu, click Share. Select where you want to share your product, and click Share.

Onboarding software to your catalog by using the CLI

Complete the following steps to add your software by using the CLI. You can use this task in a CI/CD process. To add software from a private repository, you must include a personal access token.

Creating a private catalog by using the API

Private catalogs provide a way for you to manage access to products for users in your account. You can programmatically create a private catalog by calling the Catalog Management API as shown in the following sample request. For more information, see the Catalog Management API for creating a catalog.

String label = "{label}";
String shortDesc = "{shortDesc}";
CreateCatalogOptions createOptions = new CreateCatalogOptions.Builder().label(label).shortDescription(shortDesc).build();
Response<Catalog> response = service.createCatalog(createOptions).execute();
System.out.println(response.getResult());

label = "{label}";
shortDesc = "{shortDesc}";
response = await service.createCatalog({ 'label': label, 'shortDescription': shortDesc });
console.log(response);

label = "{label}"
shortDesc = "{shortDesc}"
response = self.service.create_catalog(label=label, short_description=shortDesc)
print(response)

label := "{label}"
shortDesc := "{shortDesc}"
createOptions := service.NewCreateCatalogOptions()
createOptions.SetLabel(label)
createOptions.SetShortDescription(shortDesc)
_, response, _ := service.CreateCatalog(createOptions)
fmt.Println(response)

Importing software to your private catalog by using the API

You can programmatically import software to your catalog by calling the Catalog Management API as shown in the following sample request. This API creates the software and imports it as well. For detailed information about the API, see Catalog Management API.

id = "{id}";
offeringURL = "{offeringURL}";
ImportOfferingOptions offeringOptions = new ImportOfferingOptions.Builder().catalogIdentifier(id).zipurl(offeringURL).build();
Response<Offering> response = service.importOffering(offeringOptions).execute();
System.out.println(response.getResult());

id = "{id}";
offeringURL = "{offeringURL}";
response = await service.importOffering({ 'catalogIdentifier': id, 'zipurl': offeringURL });
console.log(response);

id = "{id}"
offeringURL = "{offeringURL}"
response = self.service.import_offering(catalog_identifier=id, zipurl=offeringURL)
print(response)

id := "{id}"
offeringURL := "{offeringURL}"
offeringOptions := service.NewImportOfferingOptions(id, offeringURL)
_, response, _ := service.ImportOffering(offeringOptions)
fmt.Println(response)

Validating your software by using the API

You can programmatically validate your product to by calling the Catalog Management API as shown in the following sample request. This process can take several minutes. For detailed information about the API, see Catalog Management API.

String authRefreshToken = "{authRefreshToken}";
String versionLocator = "{versionLocator}";
ValidationInstallOptions installOptions = new ValidationInstallOptions.Builder().xAuthRefreshToken(authRefreshToken).versionLocId(versionLocator).build();
Response<Void> response = service.validationInstall(installOptions).execute();
System.out.println(response.getResult());

versionLocator = "{versionLocator}";
authRefreshToken = "{authRefreshToken}";
response = await service.validationInstall({ 'versionLocatorId': versionLocator, 'xAuthRefreshToken': authRefreshToken });
console.log(response);

authRefreshToken="{authRefreshToken}"
versionLocator = "{versionLocator}"
response = self.service.validation_install(version_locator_id=versionLocator, x_auth_refresh_token=authRefreshToken)
print(response)

versionLocator := "{versionLocator}"
authRefreshToken := "{authRefreshToken}"
installOptions := service.NewValidationInstallOptions(versionLocator, authRefreshToken)
response, _ := service.ValidationInstall(installOptions)
fmt.Println(response)

Publishing your software to your account by using the API

You can programmatically publish your software to your account by calling the Catalog Management API as shown in the following sample request.

String versionLocator = "{versionLocator}";
AccountPublishVersionOptions publishOption = new AccountPublishVersionOptions.Builder().versionLocId(versionLocator).build();
Response<Void> response = service.accountPublishVersion(publishOption).execute();
System.out.println(response.getResult());

versionLocator = "{versionLocator}";
response = await service.accountPublishVersion({ 'versionLocId': versionLocator});
console.log(response);

versionLocator = "{versionLocator}"
response = self.service.account_publish_version(version_loc_id=versionLocator)
print(response)

versionLocator := "{versionLocator}"
publishOptions := service.NewAccountPublishVersionOptions(versionLocator)
response, _ := service.AccountPublishVersion(publishOptions)
fmt.Println(response)

Creating a private catalog by using Terraform

Use the following steps to create a private catalog by using Terraform.

Add your argument to your main.tf file. The following example creates a private catalog by using the ibm_cm_catalog resource, where label is a display name to identify the catalog.
```
resource "ibm_cm_catalog" "cm_catalog" {
label = "label"
short_description = "short_description"
}
```
For more information, see the argument reference details on the Terraform Catalog Management page.
After you finish building your configuration file, initialize the Terraform CLI. For more information, see Initializing Working Directories.
```
terraform init
```
Provision the resources from the main.tf file. For more information, see Provisioning Infrastructure with Terraform.
1. Run terraform plan to generate a Terraform execution plan to preview the proposed actions.
```
terraform plan
```
2. Run terraform apply to create the resources that are defined in the plan.
```
terraform apply
```

Importing a product to your catalog by using Terraform

Use the following steps to import a product to your private catalog by using Terraform.

Add your argument to your main.tf file. The following example adds your product by using the ibm_cm_offering resource, where label is a display name to identify the product.
```
resource "ibm_cm_offering" "cm_offering" {
catalog_id = "catalog_id"
label = "label"
tags = [ "tags" ]
}
```
For more information, see the argument reference details on the Terraform Catalog Management page.
After you finish building your configuration file, initialize the Terraform CLI. For more information, see Initializing Working Directories.
```
terraform init
```
Provision the resources from the main.tf file. For more information, see Provisioning Infrastructure with Terraform.
1. Run terraform plan to generate a Terraform execution plan to preview the proposed actions.
```
terraform plan
```
2. Run terraform apply to create the resources that are defined in the plan.
```
terraform apply
```

Importing a version of your software by using Terraform

After you add your product, use the following steps to add a version of your software by using Terraform.

Add your argument to your main.tf file. The following example accesses the software version by using the cm_version resource, where offering_id identifies the software.
```
resource "cm_version" "cm_version" {
catalog_identifier = "catalog_identifier"
offering_id = "offering_id"
zipurl = "zipurl"
}
```
For more information, see the argument reference details on the Terraform Catalog Management page.
After you finish building your configuration file, initialize the Terraform CLI. For more information, see Initializing Working Directories.
```
terraform init
```
Provision the resources from the main.tf file. For more information, see Provisioning Infrastructure with Terraform.
1. Run terraform plan to generate a Terraform execution plan to preview the proposed actions.
```
terraform plan
```
2. Run terraform apply to create the resources that are defined in the plan.
```
terraform apply
```