IBM Cloud Docs
Onboarding software to your private catalog

Onboarding software to your private catalog

The process to onboard your software includes importing a version to your private catalog, configuring the deployment details, setting any license requirements, and validating that the version can be successfully installed on the target infrastructure that you require.

Before you begin

  1. Upload your source code to a release in your GitHub, GitLab, or Azure repository. For more information, see Setting up your source code repository.

  2. Verify that you're using a Pay-As-You-Go or Subscription account. See Viewing your account type for more information.

  3. Make sure you're assigned the editor role on the catalog management service. See Assigning access to account management services.

  4. Set up the test environment that was previously created for you:

Importing a version to your private catalog

Complete the following steps to import a version of your software to your private catalog. Your private catalog was created for you as part of Getting set up to sell software.

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

  2. Select the product that you're onboarding.

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

  4. Select your deployment method.

  5. Select whether you are adding your product from a private or public repository. For Operators, select your source repository and then choose private or public repository.

  6. Enter your source URL.

    You can review the following list of supported formats per software type:

    • Helm chart: https://raw.githubusercontent.com/IBM/charts/master/repo/ibm-helm
    • Node-RED Operator: https://github.com/IBM-Cloud/operator-bundle-sample/archive/refs/tags/v0.0.3.tar.gz
    • Operator bundle from a Red Hat OpenShift on IBM Cloud registry: For an example, select the Akka Cluster Operator from the list of available Operators in the Certified repository.
    • OVA image: https://github.com/gcatalog/OVA-sample/blob/main/ova-sample.yaml
    • Terraform template: https://github.com/IBM-Cloud/terraform-sample/archive/refs/tags/v1.1.0.tar.gz
    • Virtual server image with Terraform: https://github.com/IBM-Cloud/isv-vsi-product-deploy-sample/releases/download/v1.0/isv-vsi-product-deploy-sample.tar.gz
    • Virtual server image for VPC: Select an image from the list of available images that were imported into your VPC, or import a new image to your account.

    A virtual server image for VPC can only be added to one product within one private catalog at a time. If the virtual server image you want to import is already imported into another product, you must remove the image from that product or delete the product before you add the virtual server image to a new product.

    If you're adding your product from a private repository, you can choose to provide a personal access token or you can use a secret. Instead of giving users a personal access token, you can give them access to a secret, add the token to a secret, and centrally manage all tokens and access the secret allows.

    If your software is located in GitLab, you must use a personal access token as GitLab doesn't support downloading releases using project access tokens. You can create a personal access token with the required read_api permission by following the instructions here.

    • If you're using a personal access token, select No to indicate that you aren't using a secret and provide your personal access token.
    • If you're using a secret, select Yes and click Select from Secrets Manager. Select your service instance, secret group, and secret. If you don't see your secret, make sure you're using the correct secret group and service instance.

    The message No service instance available might be displayed if you haven't created a secret or if you don't have the correct access to use secrets, even if you have service instances that are created.

  7. If applicable, set your deployment target and add your software version.

  8. Click Add version.

Configuring the version details

  1. From the version list, click the row that contains your software.
  2. Review the version details, and click Next.
  3. Depending on your software type, there might be additional steps, including setting deployment values.
  4. Click Next.

Set deployment values

If applicable to your software type, you can set deployment values that users are required to specify when they install the software. You can add new deployment values or import deployment values from an existing version.

Add new deployment values

  1. Click Configure version > Next.
  2. Click Add deployment values.
  3. In the table, select Parameter > Add to select and add all options.
  4. If necessary, you can customize the parameters by selecting them from the table and clicking Edit.

Import existing values

Complete these steps if you previously set deployment values for an existing version and want to import the values to your current version.

Imported values don't replace any deployment values that you already added to your current version.

  1. Click Configure version > Next.
  2. Click Add deployment values.
  3. Click Import values from a previous version
  4. Select the version that contains the values that you want to import.
  5. Click Import.
  6. If necessary, you can customize the parameters by selecting them from the table and clicking Edit.

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

If applicable to your software type, you can add the service access and platform access roles that are required to install your product from the IBM Cloud catalog. You can define new IAM access or import IAM access that you set in an earlier version.

Defining new IAM access

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.

Importing existing IAM access

Complete the following steps if you previously defined IAM access for an existing version and want to import the values to your current version.

Imported IAM access doesn't replace any IAM access that you already added to your current version.

  1. Click Configure version > Next > Next.
  2. Click Add.
  3. Click Import IAM access from a previous version.
  4. Select the version that contains the IAM access that you want to import.
  5. Click Add.

Adding license agreements

If users are required to accept any license agreements beyond the IBM Cloud Services Agreement when they install the software, provide the URL to each agreement or import licenses from an existing version.

Add new license agreements

  1. Click Add license agreements > Add license.
  2. Enter the name and URL, and click Add license.
  3. After entering all additional license agreements, click Next.

Import license agreements

Complete these steps if you previously added license agreements for an existing version and want to import the licenses to your current version.

Imported licenses don't replace any license agreements that you already added to your current version.

  1. Click Add license agreements > Add license.
  2. Click Import licenses from a previous version.
  3. Select the version that contains the licenses that you want to import.
  4. Click Import.

Reviewing your readme file

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

  1. From the Edit readme tab, click the Edit icon Edit icon.
  2. Preview how the information in the readme file will be displayed to users when they are installing the software.
  3. To make updates, click the Edit icon Edit icon next to the Readme section title.
  4. Click Save.
  5. 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 product

The steps to validate your product can vary based on the type of software that you're onboarding.

  1. From the Validate product tab, configure your validation target, and click Next. This step applies only to Helm charts and Operators.
  2. Configure your workspace, and click Next. This step applies only to Helm charts, Operators, Terraform templates, and virtual server images with Terraform.
  3. Click Validate.

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

Validating your software by using the API

You can validate your software by calling the 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)

Manage security and compliance controls

Controls are safeguards that are used to meet security and compliance requirements. Only controls that are supported by Security and Compliance Center, formatted correctly, and validated by Code Risk Analysis and Security and Compliance Center scans appear in the catalog. For more information, see Formatting controls in your readme file.

  1. Click Add controls.
  2. Choose a profile.
  3. Select the controls that you want to add to your version.
  4. Click Add.
  5. In the Code Risk Analyzer scan section, click Run scan.
  6. Wait for the scan to finish.
  7. In the Security and Compliance Center scan section, select the profile that you scanned.
  8. Select the Security and Compliance Center scan.
  9. Click Add scan.
  10. Click Next.

Review requirements

You must complete validation and any other requirements to publish your product.