Locally editing the catalog manifest

The catalog manifest file specifies the information about your onboarded solution that you want to share with users through a catalog. You can provide licensing and compliance information, make specific settings, and provide descriptions about the intended purpose of your product.

Prefer to use the console to edit your catalog details? You can make the selections by following the provided wizard and then export the manifest file to add to your source repo. If you are stacking deployable architectures, the catalog manifest is created for you when you add the stack to a private catalog from your project.

Mapping catalog details to the manifest file

To help visualize how the content added to the manifest file is displayed to users, see the following examples that show the relationship between the ibm_catalog.json and the catalog details page.

Let's look at how the deployable architecture name, description, features, and variations are defined in the catalog manifest file and how the user sees the information on the catalog details page.

Figure 2. Deployable architecture title, description, features text mapping to the source file

Let's look at how the variation features list is used to help users compare variations based on how it's defined in the catalog manifest file.

Figure 3. Deployable architecture variation feature comparison

Let's look at where the permissions and architecture diagram details are specified in the catalog manifest file and how it's displayed on the catalog details page.

Figure 4. Deployable architecture permissions and architecture text mapping to the source file

And, if your architecture meets a specific level of compliance that is verified with a scan by using the Security and Compliance Center, you can add a compliance claim per variation. You define how your architecture meets a certain level of compliance in the ibm_catalog.json file by specifying the Security and Compliance Center profile. You must also run a scan on the resources that your architecture creates before onboarding to IBM Cloud. For more information, see Managing compliance information for your deployable architecture.

See in the following example how the compliance information that is defined in the manifest file is displayed to users.

Figure 5. Deployable architecture compliance

Editing your manifest

To edit your manifest locally, you can use the following steps.

Copy the following example manifest file into a local editor.
Name the file ibm_catalog.json.
Add your preferred configurations into the file by using the example manifest as a guide. To learn more about each value, view the available values.
Add the file into the root folder of your source code repository.
Add your deployable architecture to your catalog.

If your deployable architecture is already onboarded to a private catalog, you can download the manifest from the console.

Example manifest file

The following code snippet can be used as a template.

{
   "products": [
      {
         "name": "",
         "label": "",
         "product_kind": "",
         "tags": [
            "tag 1",
            "tag 2"
         ],
         "keywords": [
            "keyword 1",
            "keyword 2",
            "keyword 3"
         ],
         "short_description": "Short description of your product.",
         "long_description": "A longer description of your product.",
         "offering_docs_url": "URL",
         "offering_icon_url": "URL or emebbed image",
         "provider_name": "Community",
         "module_info": {
            "works_with": [
               {
                  "catalog_id": "",
                  "name": "module name",
                  "kind": "terraform",
                  "version": "0.1.0",
                  "flavor": "Variation name"
               }
            ]
         },
         "support_details": "Explanation of support.",
         "features": [
            {
               "title": "Feature 1 title"
               "description": "Feature 1 description"
            },
            {
               "title": "Feature 2 title"
               "description": "Feature 2 description"
            }
         ],
         "flavors": [
            {
               "label": "Display name",
               "name": "Programatic name",
               "install_type": "Install type",
               "working_directory": "Directory path",
               "usage_template": "template",
               "scripts": [
                  {
                     "type": "ansible",
                     "short_description": "Short description of what your script is intended to do.",
                     "path": "Path to script location.",
                     "stage": "The stage. For example, pre.",
                     "action": "The action. For example, validate."
                  }
               ],
               "change_notices": {
                  "breaking": [
                     {
                        "title": "Title of breaking change",
                        "description": "Description of the change."
                     }
                  ],
                  "new": [
                     {
                        "title": "Title of new feature",
                        "description": "Description of the new feature or capability."
                     }
                  ],
                  "update": [
                     {
                        "title": "Title of general update",
                        "description": "Description of the general update."
                     }
                  ]
               },
               "compliance": {
                  "authority": "scc-v3",
                  "controls": [
                     {
                        "profile": {
                           "name": "Security and Compliance Center profile name",
                           "version": "Profile version"
                        },
                        "names": [
                           "Control name 1 e.g. AC-2(a)",
                           "Control name 2",
                           "Control name 3"
                        ]
                     }
                  ]
               },
               "configuration": [
                  {
                     "key": "key type e.g. ssh_key",
                     "required": true
                  },
                  {
                     "key": "Key type e.g. ibmcloud_api_key",
                     "required": true,
                     "type": "The data type"
                  }
               ],
               "outputs": [
                  {
                     "description": "Output description",
                     "key": "key"
                  },
                  {
                     "description": "Output description",
                     "key": "key"
                  }
               ],
               "dependencies": [
                  {
                     "catalog_id": "ID",
                     "id": "ID",
                     "name": "Product programmatic name",
                     "kind": "Format kind",
                     "version": "Versions or range of versions",
                     "flavors": [
                        "Variation name 1",
                        "Variation name 2",
                        "Variation name 3"
                     ],
                     "install_type": "fullstack or extension",
                  }
               ],
               "iam_permissions" [
                  {
                     "role_crns": [
                        "CRN 1 e.g. crn:v1:bluemix:public:iam::::serviceRole:Manager",
                        "CRN 2 e.g. crn:v1:bluemix:public:iam::::role:Administrator"
                     ],
                     "service_name": "Programatic service name e.g. is.vpc"
                  }
               ],
               "licenses": [
                  {
                     "name": "License name",
                     "smref": "Link to the license"
                  }
               ],
               "schematics_env_values": {
                  "value": "value",
                  "smref": " "
               },
               "architecture": {
                  "descriptions": " ",
                  "features": [
                     {
                        "title": "Feature 1 title",
                        "description": "Feature 1 description"
                     },
                     {
                        "title": "Feature 1 title",
                        "description": "Feature 1 description"
                     }
                  ],
                  "diagram": {
                     "caption": "Diagram caption",
                     "url": "Link to diagram or embedded image",
                     "metadata": []
                  },
                  "description": "Description of the diagram"
               }
            }
         ]
      }
   ]
}

Available values

The following sections include information about each value that can be referenced in your manifest file.

Products

The products value indicates an array of products with size one or more. If a catalog manifest file exists at the root of your repository, only the products within the file can be imported. Products are imported one at a time. The following values can be included at the products level:

label

The product display name. This value must match the display name that you provide during onboarding.

name

The programmatic name of the product.

version

The version of the product in SemVer format, including the major version, minor version, and revision, for example, 1.0.0. This value can also be specified when the product is onboarded to a catalog.

product_kind

The kind of product that you are onboarding. Valid values are software, module, or solution. A solution is otherwise known as a deployable architecture.

tags

An array of predefined values that can help users to filter the catalog to identify and learn more about your product. To view the available options, run the following command: ibmcloud catalog filter options --all.

keywords

An array of specific words or phrases that a user might try to search for.

short_description

A concise summary of what your product is and its value.

long_description

A detailed description of your product that explains the product's value and benefits to users.

provider_name

Users can filter the catalog by the provider of a product. When you onboard a product to a private catalog, the provider name is set to Community by default. However, you can customize this field to display your company or organization name. IBM is a reserved value and can be used for IBM build products only.

offering_docs_url

A link to documentation about the product that users can access.

offering_icon_url

A link to the URL where the icon that you want to appear on the product's catalog entry page is located.

support_details

Support information in markdown format that can include support contacts, support locations, and support methods.

features

Section header for details that highlight the processes, abilities, and results of the product. These product-level features are listed on your catalog entry page with your product description. For example, features might include CPU requirements, security features, or more. Each entry is defined as an array as shown in the example manifest in the previous section.

title: The name of the feature.
description: A concise description of the feature.

Modules

The module_info value indicates information about other products that the deployable architecture is compatible with. The following values can be included at the module_info level:

works_with

Section header for information about a singular product that is compatible with the deployable architecture.

catalog_id (optional): ID of the catalog that houses the product. If not specified, the IBM Cloud catalog is the default.
id (optional): ID of the product. The ID is not required if the name value is set.
name (optional): Programmatic name of the product that works with the deployable architecture.
kind: The format of the module that works with your deployable architecture. Most often this is terraform.
version: Version or range of product versions that work with the deployable architecture in SemVer format.
flavors (optional): The programmatic names of the compatible variations. Variations are onboarded individually to a catalog and are given a version number. An example variation name might be standard or advanced.

Flavors

Section header for information about the deployable architecture variations. Flavors are now known as variations in the console. The following values can be included at the flavors level:

label

Variation display name.

name

Variation programmatic name.

working_directory

For a working directory that is at the root level of your repo, you don't need to specify the working directory. If it is not at the root, then list the path from the root of your repository. For example, ./examples/.

usage

Information on how to embed the architecture or run it locally through Terraform.

usage_template

Similar to usage. With a template you can use variables as a place holder where the values can be substituted. The string is stored in the usage property.

Table 1. Usage template values and descriptions
Template variable	Replacement value
${{version}}	The version string of this variation or flavor.
${{flavor}}	The programmatic name of the variation or flavor.
${{kind}}	The implementation kind. I.e. `terraform`.
${{id}}	The offering or product ID.
${{name}}	The programmatic name of the offering or product.
${{catalogID}}	The ID of the catalog where the offering or product is located.
${{workingDirectory}}	The working directory of the flavor or variation.

licenses

Information about the end user 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.

{
	"id": "string, license id",
	"name": "string, license display name",
	"type": "string, type of license, e.g. Apache xxx",
	"url": "string, URL for the license text",
	"description": "string, license description"
}

id: The license ID.
name: The name of the license.
type: The type of license. For example, Apache.
url: A URL to where the user can access the license agreement.
description: A description of the license.

compliance

Section header that indicates which compliance controls that the architecture satisfies with the default installation settings. The evaluation and validation of the claims made is completed by IBM Cloud® Security and Compliance Center.

"compliance": {
   "authority": "scc-v3",
   "profiles": [
      {
            "profile_name": "",
            "profile_version": ""
      }
   ]
}

You can list multiple profiles in your catalog manifest JSON file, but only the first profile is added to your compliance information in a private catalog.

authority

IBM Cloud Security and Compliance Center v3 is the only authority accepted. This is programmatically written as scc-v3.

profiles

Section header that indicates the profile that contains the controls that are being claimed. You can view predefined profiles in Security and Compliance Center.

profile_name: The name of the profile. For example, NIST. You can find the profile name in Security and Compliance Center.
profile_version: The version of the profile. For example, 1.0.0. You can find the profile name in Security and Compliance Center.

controls

Section header that indicates that the variation has claimed controls. The catalog manifest accepts an array of controls that you can claim on your variation by specifying a control's profile_name, profile_version, and control_name. You can view predefined profiles in Security and Compliance Center.

profile

Section header that indicates that you are adding controls from a specific profile.

name: The profile name of the claimed control. For example, NIST. You can find the profile name in Security and Compliance Center.
version: The version of the profile. For example, 1.0.0. You can find the profile name in Security and Compliance Center.

names

Section header to indicate a list of claimed controls. For example:

"names": [
   "CM-7(b)",
   "AC-2(a)"
]

If you have included controls in your readme and your catalog manifest file, the manifest file takes precedence. It is best practice to make sure the controls that are listed in your catalog manifest file match the controls in your readme file.

change_notices (optional)

A list of the three types of changes that you might want to alert your users to when releasing a new version of your deployable architecture. You can specify breaking changes, new features, and general updates. Breaking changes are those updates that break functionality that was available through a previous version. New features highlight any new functionality that a user might encounter with the new version. Updates encompass any changes that you want to highlight to a user such as a modified behavior that doesn't necessarily break existing functionality or changes that make the deployable architecture easier for them to use.

"change_notices": {
   "breaking": [
      {
         "title": "",
         "description": ""
      }
   ],
   "new_features": [
      {
         "title": "",
         "description": ""
      }
   ],
   "updates": [
      {
         "title": "",
         "description": ""
      }
  ]
}

iam_permissions(optional)

Section header for a list of all IAM permissions that are required for a user to work with your deployable architecture version. IAM permission information includes the programmatic name of the service that is required and a list of CRNs for roles that are needed. If you build your catalog manifest file from the UI, the CRNs are already included.

{
   "service_name": "IAM defined service name",
   "role_crns" [
      ""
   ],
   "resources": [
      {
         "name": "",
         "description": "",
         "role_crns: [
            ""
         ]
      }
   ]
}

service_name

The programmatic name of the service that users must have access to.

role_crns

Section header to indicate a list of access roles. For example:

resources

The resources for a permission.

name: The name of the resource.
description: A description of the resource.
role_crns: Section header to indicate a list of access roles. For example:

architecture

High-level information about the deployable architecture version that includes a description, features, and a diagram. Multiple diagrams, with captions, can be provided.

"architecture" {
   "descriptions": "",
   "features": [
      {
         "title": "",
         "description": ""
      }
   ],
   "diagrams": [
      {
         "diagram" {
            "caption": "",
            "url": "",
            "type": "image/svg+xml"
         },
         "description": ""
      }
   ]
}

features

Information that highlights the processes, abilities, and results of the version, or if applicable, architecture variation. When onboarding by using the console, these details are called highlights. These details appear on the variation selection box within your catalog entry. If your product has multiple architecture variations, users can compare the variation-level features to decide which variation suits their needs.

title: Name of the feature.
description: A description of the feature.

diagrams

Information about the architecture diagram that includes the diagram caption, the URL to embed the SVG of the diagram, the diagram metadata such as element ID and element description, and the description of the reference architecture.

diagram

Section marker for information about a singular architecture diagram.

url

The URL to the diagram's SVG. You can also embed an SVG.

api_url

The catalog management API URL to the diagram.

url_proxy

Section header for information about a proxied image.

url: The URL to the proxied image.
sha: The sha identifier of the image.

caption

A short label for the architecture diagram.

type

The type of media.

thumbnail_url

A link to a thumbnail for the diagram.

description

Information about architecture diagram as a whole, including the outline of the system and the relationships, constraints, and boundaries between components of the deployable architecture.

dependencies

Section header for a list of prerequisite products that are required to deploy the architecture. Information includes the programmatic name of the product and product versions. Optionally, you can include the catalog ID and a list of dependent variations.

{
   "name": "offering name",
   "id": "offering ID",
   "kind": "terraform",
   "version": "SemVer version e.g. 3.1.2"
   "flavors": [
      "flavor name"
   ],
   "install_type": "fullstack or extension",
   "catalog_id": "catalog ID"
}

catalog_id (optional): ID of the catalog that houses the product. If not specified, the IBM Cloud catalog is the default.
id (optional): The product ID. The ID is not required if the name value is set.
name (optional): Programmatic name of the product.
kind: The format kind of the dependency. Use stack for a deployable architecture made of grouped deployable architectures where a stack config file is present. Use terraform for deployable architectures made solely of one or more modules.
version: A version or range of versions to include as dependencies in SemVer format.
flavors (optional): List of variations that the architecture depends on.

release_notes_url

URL to the architecture's release notes.

configuration

Section header that specifies the configuration of deployment variables for specific variation. Catalog data types are used to extend native types and facilitate for a better user experience when you're working in the IBM Cloud console. If you are running your code on a local machine or another environment, the variables are not used. An example might be a catalog type of password that is used to extend the capabilities of a Terraform variable defined with a type of string so that it is treated as sensitive in the UI.

{
   "key": "The configuration key. This value should match the name of a deployment variable.",
   "type": "The data type of the variable. This must be a valid catalog management type.",
   "default_value": "The default value set by the person who onboarded the deployable architecture",
   "value_constraint": "string",
   "description": "The description of the variable that is shown in the catalog to those who use your deployable architecture.",
   "display_name": "The display name for the configuration type.",
   "required": boolean,
   "options": [
      "Selectable option 1",
      "Selectable option 2"
   ],
   "hidden": boolean,
   "custom_config": {
      "type": "The ID of the widget type.",
      "grouping": "Where the configuration type is rendered.",
      "original_grouping": "The original groupiing type for the configuration.",
      "grouping_index": "The order in which the configuration item shows in a particular grouping.",
      "config_constraints": "Map of constraint parameters that are passed to the custom widget.",
      "associations": "The list of parameters associated with the configuration.",
      "options_url": "The URL where the options for your custom type can be pulled by using dynamic data from objects in the catalog."
   },
   "configuration_group": "The name of the assocated configuration group."
}

key

The configuration key. The value should match the name of a deployment variable.

type

The type of input that a customer can define or select. The data type must be supported by the Catalog Management service. Native Terraform types map to some of the supported types. For example, the Terraform type map equates to object. The Terraform type list equates to array. A Terraform type string with a sensitive attribute equates to password. Customers that consume your deployable architecture must provide values for the input type that you define in the catalog manifest.

Supported predefined types:

boolean requires a true or false string input from users.
float requires a point decimal from users.
int requires an integer input from users.
number requires a numeric value. The number type can represent both whole numbers and fractional values like 4.56.
password requires a string input from users. The string is redacted in the console and logs.
string requires a sequence of Unicode characters representing text.
object requires a Terraform object input from users. For more information, see map.

Predefined types require manual input from users.

Supported custom types:

array requires a list of values separated by a comma.
region requires user to select a region to deploy the deployable architecture from a dropdown list. You can filter the regions that are available to end users. For example, you might specify country_id:us,ca,jp in the Region filter to limit the available regions to those countries. For more information, see Filtering syntax.
textarea requires users to input text that can be split into multiple lines. For example, a description.
vpc requires users to select a VPC by name from a dropdown list. The output is the VPC name or ID that your template requires.
vpc ssh key requires users to select a VPC SSH key for authentication to a virtual machine.
cluster requires users to select a Kubernetes Service or Red Hat OpenShift cluster. The output is the cluster ID.
power iaas requires users to select a Power Virtual Server instance.
resource group requires users to select a resource group. The output is the resource ID or name.
multi-line secure value requires users to input text that can be split into multiple lines, which is redacted in the console and logs. For example, if a long key is required, the value is hidden in workspaces.
schematics workspace requires users to select a specific workspace form a dropdown list. This list is dynamically filtered based on dependencies defined in the deployable architecture. For example, if your deployable architecture, example-da-1, depends on another deployable architecture, example-da-2, the input dropdown list for example-da-1 shows only workspaces associated with example-da-2. Users then select the appropriate instance of example-da-2's workspace when setting up example-da-1. For more information, see dependencies.
json editor gives users a space to specify larger JSON inputs or plain text files.
Platform resource requires users to select an instance resource from a dropdown list for the type of resource that you specify. The resource type can be VPC Subnet, VPC Image, or VPC Floating IPs. You can specify the ID or name as the values that users can choose from and allow a single or multiple selections. The output is the name or ID that your template requires.

default_value

The value that is to be set as the default.

description

A description of the variable that you want to display in the UI for users of your deployable architecture.

display_name

The name that is displayed for the configuration type.

required

A boolean that indicates if users are required to specify the parameter during installation.

hidden

A boolean that indicates if the parameter should be hidden from users during installation.

options

An array of options that users can choose from for a parameter.

custom_config

Section header use to indicate that a custom configuration can be used.

type: The ID of the widget type used for configuration
grouping: Where the configuration type should appear in the catalog. Valid values are Target, Resource, and Deployment.
original_grouping: Where the configuration type originally appeared. Valid values are Target, Resource, and Deployment.
grouping_index: The order of this configuration item when there are mulitple.
config_constraints: Map of constraint parameters that are given to the custom widget.
associations: Section header for parameters that are associated with the configuration.

configuration_group

The name of an associated configuration group.

schematics_env_values

A list of the values and variables that need to be passed to the Schematics service to be used as environment variables during the execution of the Terraform. This might be a secure value, a setting of the Terraform logging or something else. You can choose to specify a string or create a reference to Secrets Manager. If both are specified, then the Secrets Manager reference is used.

{
   "value": "Environment variables and their values",
   "sm_ref": "Specification of an instance of Secrets Manager and a key"
}

terraform_version

The Hashicorp Terraform runtime version that is needed to validate and install the version. Setting this value in the manifest overrides what is specified in the source code.

outputs

Section header for information about Terraform output values.

{
   "key": "name of the output value as defined in the Terraform",
   "description": "The description of the key"
}

key: Specifies the output value.
description: A short summary of the output value.

install_type

Specifies whether a deployable architecture is fullstack or extension. Architectures listed as extensions require prerequisites. The dependencies array must also completed if you set this value to extension.

scripts

A list of scripts contained within the same repository that can be run by a project during a particular stage of a specified action. Each key in the map must match the format action and stage in the entry. Stage must be either pre or post. Action must be validate, deploy, or undeploy.

{
   "short_description": "description for the script",
   "type": "type of script. i.e. ansible",
   "path": "the path to the script in the repo. Must begin with scripts/..."
   "stage": "pre or post"
   "action": "The action that executes the script. Options include validate, deploy, or undeploy."
}