Cloud Services

Enterprise Marketplace

Content package management
Published On Jun 13, 2024 - 1:04 PM

Content package management

Implement lifecycles to manage your content in Enterprise Marketplace Catalog from public cloud providers.
You can use Enterprise Marketplace to implement a lifecycle to manage the catalog content available to your buyers in your Enterprise Marketplace Catalog using a content package. These content packages can contain services from support public cloud service providers.
Content packages include all of the information that you need to connect to and communicate with the provider along with information about the fields that need to be filled in during provisioning. These content packages can be created from scratch, altered from a template, or exported from an existing catalog and either imported as is or altered as needed.
The following public cloud service providers are supported:
  • Alibaba Cloud
  • Amazon Web Services (AWS)
  • Google Cloud Platform (GCP)
  • IBM Cloud
  • Microsoft Azure
In addition, content packages that use Terraform templates, which include the above providers, are supported.
The following topics are covered:

Creating content packages for Enterprise Marketplace

You can develop your content and locate it in your local filesystem or GitHub repository. Create a directory structure with either single or multiple template files along with the required metadata file
icb_catalog_metadata.json
, and compress it into a .zip file.
The icb_catalog_metadata.json file
You must include an
icb_catalog_metadata.json
file in your zip file for file based import, or in your GitHub Repository for Git import. The file must contain these parameters.
Parameter
Description
Allowed values
Type
Required?
providerCode
This is the provider code referenced by the Catalog to refer to the provider onboarded to Enterprise Marketplace for importing the catalogs. This parameter is set by Enterprise Marketplace when you export the catalogs.
ibmcloud, azure, aws, alicloud, gcp
string
Yes
sourcePath
The path to the folder that contains the raw templates relative to the location of the
icb_catalog_metadata.json
file.
Attempting to import catalogs without an empty string for the sourcePath will result in a "sourcePath cannot be empty" error.
Attempting to import catalogs without adding a valid sourcePath will result in an "Error occurred while extracting zip. Please check supplied sourcePath is correct." error.
You can use "/" as the sourcePath if the
icb_catalog_metadata.json
file is located in the same folder as the templates for the catalog. In this case the name of the catalogs will be generated from the names of the template files. This technique is not applicable for Google because it needs the templates to be grouped in a folder. This technique is applicable for providers using Terraform templates only when the catalog is created from a single Terraform (
.tf
) file.
string
Yes
The following is an example file for Microsoft Azure.
{ "icbCatalogRepository": [ { "providerCode": "azure", "sourcePath": "Azure_Templates" } ] }
The following is a multiple provider content pack example file.
{ "icbCatalogRepository": [ { "providerCode": "azure", "sourcePath": "Azure_Templates" }, { "providerCode": "aws", "sourcePath": "AWS_Templates" } ] }
How names are generated
The following table covers how the catalog names are generated for each provider.
Provider
Name generation technique
Azure
Every JSON is considered as an individual catalog. The name of the catalog is based on the full path of the individual templates in the content package. All "/" characters in the path will be replaced with "_".
AWS, Alibaba
The names of the catalogs resulting from the import correspond to the individual filenames of the JSON/YAML files included in the content package.
GCP
Each folder is considered as an individual catalog. The names of the catalogs resulting from the import correspond to the folder names that contain the YAML/PY/JINJA files included in the content package. You must always create a Zip/Git folder structure for your YAML/PY/JINJA files related to the catalog.
IBM Cloud, Terraform templates for any provider
If you use single
.tf
files (with no separate state/variables files), you can include these
.tf
templates in the directory of your Zip/Git structure where your
icb_catalog_metadata.json
file is located. In this case, the names of the imported catalogs correspond to the filename (without extension) of your .tf files.
If you use multiple .tf files for a single catalog, you must locate them inside their own folder structure. In this case, the names of the imported catalogs correspond to the folder name of the folder structure where your
.tf
files are located. You can create Zip/Git folder structures with a mix of individual
.tf
files that are each for an individual catalog in the root folder of your Zip/Git folder structure.
If
sourcepath = "/"
in
icb_catalog_metadata.json
, then the names of the catalogs correspond to the parent folder name for each template.

Directory structure for content packages

This section covers the common directory structure for all providers. Some providers use specialized structures. For more information, see Guidelines by provider.
Folder structure for single provider packages
A single provider content package .zip file contains these files:
  • icb_catalog_metadata.json
  • Template(s)>/<Folder(s)ToTemplate(s)>
The
icb_catalog_metadata.json
file needs to contain this information:
  • providerCode
    : Routes the imported content to the correct provider (pre-defined). Allowed provider codes are
    azure
    ,
    aws
    ,
    gcp
    ,
    ibmcloud
    , and
    alicloud
    .
  • sourcePath
    : Path to where the provider-specific templates reside.
The following is a sample
icb_catalog_metadata.json
file for single provider.
{ "icbCatalogRepository": [ { "providerCode": "azure", "sourcePath": "Azure_Templates" } ] }
Folder structure for multiple provider packages
A multiple provider content package .zip file contains these files:
  • icb_catalog_metadata.json
  • Template(s)>/<Folder(s)ToTemplate(s)>
  • Template(s)>/<Folder(s)ToTemplate(s)>
The following is a sample
icb_catalog_metadata.json
file for multiple providers.
{ "icbCatalogRepository": [ { "providerCode": "azure", "sourcePath": "Azure_Templates" }, { "providerCode": "aws", "sourcePath": "AWS_Templates" } ] }

Guidelines by provider

The following sections detail the directory structures and naming conditions required by the available public cloud providers:

Alibaba Cloud

The following are the provider-specific guidelines for Alibaba Cloud.
Single import for Alibaba Cloud
For a single json or a terraform file format, keep the template in a folder inside the provided source path. A JSON template directory within the .zip file would look like the following example.
icb_catalog_metadata.json Template DNS/dns.json
Similarly, a Terraform template directory within the .zip file would look like this example.
icb_catalog_metadata.json Template SEC_GROUP/sec.tf
To import a single catalog, add the following code to
icb_catalog_metadata.json
:
{ "icbCatalogRepository": [ { "providerCode": "alicloud", "providerName": "alibaba", "providerOfferingTypes": ["iaas"], "sourcePath": "/Templates", "serviceOfferings": [] } ] }
Single imports for Alibaba have these naming conventions:
  • Terraform catalog template:
    The name of the catalog will be the same as that of the provided folder name for that template.
  • JSON catalog template:
    The name of the catalog will be the same as that of the provided file name.
Bulk import and directory structure for Alibaba
For importing multiple catalogs in bulk in a single operation, follow these guidelines divided by template type:
  • Terraform templates:
    • Keep each catalog in a separate folder inside a provided source path as shown in this example.
      Templates icb_catalog_metadata.json ECS/ecs.tf SEC_GROUP/sec.tf
    • Add the following code to
      icb_catalog_metadata.json
      :
      { "icbCatalogRepository": [ { "providerCode": "alicloud", "providerName": "alibaba", "providerOfferingTypes": ["iaas"], "sourcePath": "/Templates", "serviceOfferings": [] } ] }
    • The name of the catalog will be the same as the provided folder name for that template.
  • JSON file format:
    • You can keep all the templates in a single folder or use multiple folders for different templates inside the provided source path.
      Templates icb_catalog_metadata.json DNS/dns.json ECS/scs.json
    • Add the following code to
      icb_catalog_metadata.json
      :
      { "icbCatalogRepository": [ { "providerCode": "alicloud", "providerName": "alibaba", "providerOfferingTypes": ["iaas"], "sourcePath": "/Templates", "serviceOfferings": [] } ] }
    • The name of the catalog will be the same as that of the provided file.

Amazon Web Services

The following are the provider-specific guidelines for Amazon Web Services (AWS).
Single import for AWS
For a single catalog, place the templates in the same folder inside the provided source path. For example, you might use the following directory structure:
  • icb_catalog_metadata.json
  • AWS_Service_Offerings
    • AWS_Single
      • EC2_Json_Native.json
To import a single catalog, add the following code to
icb_catalog_metadata.json
:
{ "icbCatalogRepository": [ { "providerCode": "aws", "providerName": "Amazon", "sourcePath": "/AWS_Service_Offerings" }, ] }
The following are the naming conventions per type of template:
  • For the JSON and YAML catalog templates, the name of the catalog will be the same as that of the provided file name.
  • For Terraform catalog templates, the name of the catalog will be the same as that of the provided folder name for that particular template. Any underscore ( _ ) characters in the folder name will be replaced with spaces.
Bulk import and directory structure for AWS
For importing multiple catalogs in bulk in a single operation, follow these guidelines:
  • For JSON or YAML file format, you can keep all the templates in a single folder or could use multiple folders for different templates inside the provided source path.
  • For Terraform templates, keep each catalog in a separate folder inside a provided source path.
The following is an example .zip directory structure:
  • icb_catalog_metadata.json
  • AWS_Service_Offerings
    • AWS_Multiple_Json_Templates
      • EC2_Json_Native.json
      • S3_Json_Native.json
    • AWS_Multiple_Yaml_Templates
      • EC2_Yaml_Native.yaml
      • S3_Yaml_Native.yaml
    • AWS_Multiple_Terraform_Templates
      • S3_tf_Template/S3_Native.tf
      • EC2_tf_Template/EC2_Native.tf
To bulk import, add the following code to
icb_catalog_metadata.json
:
{ "icbCatalogRepository": [ { "providerCode": "aws", "providerName": "Amazon", "sourcePath": "/AWS_Service_Offerings" }, ] }
The following are the naming conventions per type of template:
  • For the JSON and YAML catalog templates, the name of the catalog will be the same as that of the provided file name.
  • For Terraform catalog templates, the name of the catalog will be the same as that of the provided folder name for that particular template. Any underscore ( _ ) characters in the folder name will be replaced with spaces.

Google Cloud Platform

When importing single or multiple catalogs, follow these guidelines:
  • Use the following directory structure. Each directory under the source folder will be treated as an individual catalog.
    ├── my_source_dir | └── my_service │ └────file_name.yaml │ └────file_name_1.py... │ └────file_name_n.jinja
  • The naming convention is that the catalog directory name is used as the catalog name.

Microsoft Azure

The following are the provider-specific guidelines for Microsoft Azure.
Single import for Azure
To import a single catalog, add the following code to
icb_catalog_metadata.json
:
{ "icbCatalogRepository": [ { "providerCode": "azure", "sourcePath": "Azure_Templates" }, ] }
The name of the catalog would be taken from the sourcePath to the catalog template folder and the name of the file, such as
Azure_Templates_Linux_VM_Template_azuredeploy
.
Bulk import and directory structure for Azure
You need to create the following directory structure for bulk import. From the sourcePath specified in
icb_catalog_metadata.json
, all the directories are recursively parsed and each folder is treated as a single catalog. For example, take the following folder structure:
  • Main Folder -
    • Sub folder for template 1 -
    • Sub folder for template 2 -
For this example, the directory in the .zip folder looks like this:
  • icb_catalog_metadata.json
  • Azure_Templates
    • Linux_VM_Template/azuredeploy.json
    • Windows_VM_Template/azuredeploy.json
To import multiple catalogs in a single operation, add the following code to
icb_catalog_metadata.json
:
{ "icbCatalogRepository": [ { "providerCode": "azure", "sourcePath": "Azure_Templates" }, ] }
The name of the catalog would be taken from the sourcePath to the catalog template folder and the name of the file. The names of the example directory would be these:
  • Azure_Templates_Linux_VM_Template_azuredeploy
  • Azure_Templates_Windoes_VM_Template_azuredeploy

Terraform for all public providers

The following guidelines apply to all Terraform templates regardless of which public provider you are using:
  • Terraform templates, if placed in a GitHub repository or imported from local file system, should follow the same structure as that of a local file system.
  • For native Terraform templates, create the following type of directory structure:
    content_import-9403-folder-level2 icb_catalog_metadata.json templates bluemix bluemix.tf VM1 variables.tf main.tf cloudamqp.tf
  • For the example directory structure, if
    sourcepath = "content_import-9403-folder-level2/templates"
    in
    icb_catalog_metadata.json
    , then the catalog name for the three catalogs on the Catalog Management would be as follows:
    • bluemix
    • VM1
    • cloudamqp
      If
      sourcepath = "/"
      in
      icb_catalog_metadata.json
      , then the catalog name for the three catalogs on the Catalog Management would be as follows:
      • bluemix
      • VM1
      • templates
Consider the following example where a cloudamqp.tf file is in a directory inside the templates directory. In this case the folder name is used as the catalog name.
content_import-9403-folder-level2 icb_catalog_metadata.json templates bluemix bluemix.tf VM1 variables.tf main.tf cloudamqpsvc cloudamqp.tf
If
sourcepath = "/"
in
icb_catalog_metadata.json
, then the catalog name for the three catalogs on the Catalog Management would be as follows:
  • bluemix
  • VM1
  • Cloudamqpsvc

Preferred practices

Keep in mind these preferred practices when working with content packages.
  • Ensure that the
    icb_catalog_metadata.json
    name is intact and valid.
  • Validate that the directory structure is created as per the public cloud provider requirements
  • Validate the template to be imported according to the native cloud provider expectations.
  • Limit the size of your content pack zip file to 10 MB.

Limitations

The content pack .zip file must be no larger than 10 MB.
Do you have two minutes for a quick survey?
Take Survey