Catalogs management CLI plug-in

The IBM Cloud® catalogs management command-line interface (CLI) provides extra capabilities for working with products in the IBM Cloud catalog and the private catalogs in your account. You can use this CLI plug-in to manage your private catalogs, onboard private software products, and manage catalog visibility between the public catalog and your private catalogs.

Before you begin

Install the IBM Cloud CLI. For more information, see Getting started with the IBM Cloud CLI. The prefix for running commands by using the IBM Cloud CLI is ibmcloud.
Before you run the registry commands, log in to IBM Cloud with the ibmcloud login command to generate an access token and authenticate your session.

Installing the catalogs management plug-in

To install the catalogs management plug-in, run the following command:

ibmcloud plugin install catalogs-management

In the command line, you are notified when updates to the ibmcloud CLI and catalogs-management CLI plug-in are available. Ensure that you keep your CLI up to date so that you can use all the available commands and flags.

If you want to view the current version of your catalogs-management CLI plug-in, run ibmcloud plugin list.

To maintain privacy and security, don't put personal information in your catalog names or catalog descriptions.

ibmcloud catalog account add-approval-access

Run the following command to add approval access to your catalog account.

ibmcloud catalog account add-approval-access [--account-ids IDS] [--object-kind KIND]

Command options

--object-kind VALUE: Provide the object kind. Options are offering, vpe, proxy_source, or preset_configuration.
--account-ids VALUE: Provide a comma separated list of account IDs prefixed with one of the following. -acct- for regular accounts, -ent- for enterprise accounts, and -entgrp- for enterprise account groups.

ibmcloud catalog account delete-approval-access

Run the following command to delete approval access to your catalog account.

ibmcloud catalog account delete-approval-access [--account-ids IDS] [--object-kind KIND]

Command options

--object-kind VALUE: Provide the object kind. Options are offering, vpe, proxy_source, or preset_configuration.
--account-ids VALUE: Provide a comma separated list of account IDs prefixed with one of the following. -acct- for regular accounts, -ent- for enterprise accounts, and -entgrp- for enterprise account groups.

ibmcloud catalog account get-approval-list

Run the following command to get approval list for your catalog account.

ibmcloud catalog account get-approval-list [--object-kind KIND]

Command options

--object-kind VALUE: Provide the object kind. Options are offering, vpe, proxy_source, or preset_configuration.

ibmcloud catalog account get-approval-list-source

Run the following command to get all target accounts pointing to a source.

ibmcloud catalog account get-approval-list-source [--approval-state STATE] [--enterprise-id ID] [--object-kind KIND]

Command options

--object-kind VALUE: Provide the object kind. Options are offering, vpe, proxy_source, or preset_configuration.
--approval-state VALUE: Provide the approval state. Options are approved, pending, or rejected.
--enterprise-id VALUE (optional): Provide an enterprise or enterprise account group ID to view or manage requests for the enterprise. Prefix the ID with -ent- for an enterprise and -entgrp for an account group.

ibmcloud catalog account set-approval-state-source

Run the following command to set the approval state for target accounts pointing to a source.

ibmcloud catalog account set-approval-state-source [--account-ids IDS] [--approval-state STATE] [--enterprise-id ID] [--object-kind KIND]

Command options

--object-kind VALUE: Provide the object kind. Options are offering, vpe, proxy_source, or preset_configuration.
--approval-state VALUE: Provide the approval state. Options are approved, pending, or rejected.
--account-ids VALUE: Provide a comma separated list of account IDs prefixed with one of the following. -acct- for regular accounts, -ent- for enterprise accounts, and -entgrp- for enterprise account groups.
--enterprise-id VALUE (optional): Provide an enterprise or enterprise account group ID to view or manage requests for the enterprise. Prefix the ID with -ent- for an enterprise and -entgrp for an account group.

ibmcloud catalog create

Use this command to create a new private catalog in your account. A private catalog is used to organize a set of products, private ones you add, or references to products in the IBM Cloud catalog. A user must have access to your private catalog through an IAM access policy and the resource group that contains your private catalog to view and work with the products.

You must target a resource group to create a catalog because the catalog exists in the context of a particular resource group. To get the list of resource groups, you can run the ibmcloud resource groups command, and then the ibmcloud target -g "resource group" command.

ibmcloud catalog create --name CATALOG [--catalog-description "DESCRIPTION"]

Command options

--name CATALOG: The catalog name.
--catalog-description DESCRIPTION (optional): Short description for the new catalog.

Example

Create a catalog called dev-catalog with the description a catalog for development and testing purpsoses.

ibmcloud catalog create --name dev-catalog --catalog-description "a catalog for development and testing purposes"

ibmcloud catalog list

Run the following command to retrieve the list of catalogs in this particular account.

ibmcloud catalog list [--output FORMAT]

Command options

--output FORMAT (optional): Specifies output format. Default is terminal compatible and the only supported alternative is JSON. For example, --output json.

Output

The command returns the following output:

Name                                           ID                                     Description                   Last Updated
dev-catalog                                    93f592fb-e09b-4a53-bbd9-92f6ab9e253b   short-description             2019-11-21 21:28:28.347 +0000 UTC
ABDemoTestCatalog                              7a246530-e191-45e2-87cc-07c8c7033d2b   short-description             2019-08-19 17:43:48.59 +0000 UTC

ibmcloud catalog get

Run the following command to retrieve information for a particular catalog in the account.

ibmcloud catalog get --catalog CATALOG [--output FORMAT]

Command options

--catalog CATALOG: The catalog name or ID.
--output FORMAT (optional): Specifies output format. Default is terminal compatible and the only supported alternative is JSON. For example, --output json.

Output

The command returns the following output:

Name                                     Current State   Version Locator
dev-catalog
|__dev-offering
|  |__Openshift
|     |__1.0.0                           Draft           480fb4e3-d7ba-4e9b-9d4c-42f0ab811040.fd8f91a3-8027-4919-ad6d-c5189a4a8ee

ibmcloud catalog delete

Run the following command to delete a particular catalog in the account.

ibmcloud catalog delete --catalog CATALOG

Command options

--catalog CATALOG: The catalog name or ID.

ibmcloud catalog search

Run the following command to search the public catalog for published products, including services and software.

ibmcloud catalog search <QUERY> [--catalog CATALOG] [--type TYPE] [-r, --region REGION] [-k, --kind KIND] [--fields FIELDS] [-p, --price PRICE] [-t, --tag TAG] [--sort-by PROPERTY] [--col COLUMNS] [--reverse] [--output TYPE] [--global]

Command options

--type TYPE (optional): Optional. Default is services. Valid options are services and software.
--catalog CATALOG (optional): Search for the software published by your account. Specify the catalog name or ID to search by.
--output FORMAT (optional): Specifies output format. Default is terminal compatible and the only alternative options are json and csv.
--kind KIND (optional): Flag is only valid for services search. Provide a comma-separated list of types of products.
--region REGION (optional): Flag is only valid for services search. Provide a comma-separated list of regions. Run ibmcloud cs regions to return a valid list.
--price PRICE (optional): Flag is only valid for services search. Provide a comma-separated list of pricing types.
--tag TAG (optional): Flag is only valid for services search. Provide a comma-separated list of tags.
--global (optional): Flag is only valid for services search. Use it to operate in global scope.
--sort-by TYPE (optional): Flag is only valid for services search and used to order the search result. Available options are name, displayname, kind, provider, created, and updated.
--reverse (optional): Flag is only valid for services search. Use it to reverse the sorting order.
--fields FIELDS (optional): Flag is only valid for services search. Customize the table, for example, --fields name,kind,metadata.service.iam_compatible.

Output

The command returns the following output:

Name                                       ID                                                    Category
2 Zone VPC                                 f10d9ae9-ac94-4718-b24a-3994241ae2a4-global           Networking
Apache                                     Qml0bmFtaS1hcGFjaGU=-global                           Developer Tools
Apache Airflow                             Qml0bmFtaS1haXJmbG93-global                           Databases
Apache Airflow                             Qml0bmFtaS1haXJmbG93-global                           Developer Tools

ibmcloud catalog filter get

Run the following command to retrieve filter details for either the account or a particular catalog.

ibmcloud catalog filter get --catalog CATALOG [--output FORMAT]

Output

The command returns the following output:

Account: The IBM Cloud catalog is visible to all users in this account.

Filter:
Including IBM Cloud catalog

Type           Include   Tags
Pricing plan   false     Free
Provider       false     Third Party

ibmcloud catalog filter create

Run the following command to create a new filter. If a filter exists, this command overrides the current filter.

ibmcloud catalog filter create [--catalog CATALOG] [--category CATEGORY] [--compliance COMPLIANCE] [--deployment-target TARGET] [--exclude-list LIST] [--include-all ALL] [--include-list LIST] [--offering-format FORMAT] [--pricing-plan PLAN] [--provider PROVIDER] [--release RELEASE] [--type TYPE]

--catalog CATALOG (optional): Specify the catalog name or ID. If not specified, the filter is created at the account level.
--account-group ACCOUNT GROUP: The account group name or ID. This option applies only to enterprise accounts.
--hide-ibm-catalog (optional): By default, the catalog is visible to all users in this account. By providing this flag, you can make products available only to the users you choose by turning off visibility to the IBM Cloud catalog and adding the products to your private catalogs.
--include-all BOOLEAN (optional): Default is true if flag not provided. Valid values are true and false. If set to true, the filter defaults to include the entire public catalog, and subsequent filters are excluded. If set to false, the filter excludes the entire public catalog, and subsequent flags are included. For more information, see Managing catalog settings.

--offering-format FORMAT (optional)

--category CATEGORY (optional): Provide the category that best fits how users might use your product. Categories are used to organize products in the catalog based on common solutions, function, or use. You can select only one category. Run the ibmcloud catalog offering category-options command to view all options. Default is Developer tools.
--compliance TYPE (optional): Provide a comma-separated list of compliance categories that you want to include or exclude. Run the ibmcloud catalog filter options command to view all options.
--deployment-target TARGET (optional): Provide a comma-separated list of deployment targets that you want to include or exclude. Run the ibmcloud catalog filter options command to view all options.
--exclude-list LIST (optional): Provide a comma-separated list of product IDs or names that must be excluded in the filtered public catalog.
--include-list LIST (optional): Provide a comma-separated list of product IDs or names that must be included in the filtered public catalog.; Provide a comma-separated list of product formats that you want to include or exclude. Run the ibmcloud catalog filter options command to view all options.
--pricing-plan PLAN (options): Provide a comma-separated list of pricing plans that you want to include or exclude. Run the ibmcloud catalog filter options command to view all options.
--provider PROVIDER (optional): Provide a comma-separated list of providers that you want to include or exclude. Run the ibmcloud catalog filter options command to view all options.
--release RELEASE (optional): Provide a comma-separated list of categories that you want to include or exclude. Run the ibmcloud catalog filter options command to view all options.
--type TYPE (optional): Provide a comma-separated list of software types that you want to include or exclude. Run the ibmcloud catalog filter options command to view all options.

ibmcloud catalog filter delete

Run the following command to delete an applied filter. This filter defaults to the account level unless a catalog is specified. As a result, the filter is reset to include all products in the public catalog.

ibmcloud catalog filter delete --catalog CATALOG

ibmcloud catalog filter offering

Update the filter to include or exclude a particular product and any applicable pricing plans. This filter defaults to the account level unless a catalog or account group is specified.

ibmcloud catalog filter offering --offering PRODUCT-NAME

Command options

--catalog CATALOG: The catalog name or ID.
--account-group ACCOUNT GROUP: The account group name or ID. This option applies only to enterprise accounts.
--plans-list PLANS LIST: A comma-separated list of plan IDs or names to include or exclude.
--offering OFFERING: The product name or ID.
--include: The default value is true if a flag is not provided. Valid values are true and false. If set to true, the product and plans provided are visible to users in the account. If set to false, the product and plans aren't visible to users in the account.

ibmcloud catalog filter hide-ibm-public-catalog

By default, the IBM Cloud catalog is visible to all users in the account. You can make products available only to the users you choose by turning off visibility to the IBM Cloud catalog and adding the products to your private catalogs.

ibmcloud catalog filter hide-ibm-public-catalog

ibmcloud catalog filter show-ibm-public-catalog

ibmcloud catalog filter show-ibm-public-catalog

ibmcloud catalog filter options

Run the following command to retrieve the filter options for each filter category.

ibmcloud catalog filter options

Output

The command returns the following output:

Deployment target              ID
IBM Cloud Kubernetes Service   target_iks
IBM Cloud Schematics           target_terraform
Red Hat OpenShift              target_roks
VMware vCenter Server          target_vcenter
Virtual private cloud          target_vpc-x86
Power Systems Virtual Server   target_power-iaas

Provider      ID
Third party   ibm_third_party
Community     ibm_community
IBM           ibm_created

Works with             ID
SAP Certified          sap_certified
Quantum Technologies   quantum_tech
Satellite Enabled      satellite_enabled
HPC                    hpc

Delivery method   ID
Cloud Paks        cloud_pak
Helm charts       helm
Operators         operator
OVA Images        ova
Starter kits      template
Terraform         terraform
Server Images     vsi_image
Blueprint         blueprint
Toolchains        toolchain

Compliance                     ID
EU Supported                   eu_access
Financial Services Validated   fs_ready
HIPAA Enabled                  hipaa
IAM-enabled                    rc_compatible
Service Endpoint Supported     service_endpoint_supported

Release      ID
Beta         ibm_beta
Deprecated   ibm_deprecated

Support                 ID
Third party supported   support_third_party
Community supported     support_community
IBM supported           support_ibm

Category                   ID                   Tags
Compute                    compute              compute,compute_classic,content,openwhisk,runtime,virtualservers,compute_baremetal
Containers                 containers           containers,clusters,registry
Networking                 network              network,network_vpc,network_classic,network_edge,network_interconnectivity
Storage                    storage              storage,storage_vpc,storage_classic,storage_datamovement
Converged infrastructure   converged_infra      converged_infra
Enterprise applications    enterprise_app       enterprise_app
AI / Machine Learning      ai                   watson,ai
Analytics                  analytics            data_analytics,business_analytics,analytics
Blockchain                 blockchain           blockchain
Databases                  databases            data_management,database
Developer tools            devops               dev_ops
Logging and monitoring     logging_monitoring   logging_monitoring
Migration                  migration_tools      migration_tools
Integration                integration          integration,api
Internet of Things         iot                  internet_of_things
Security                   security             security
Mobile                     mobile               mobile,web_and_app

ibmcloud catalog offering create

Run the following command to add a product to a private catalog in the account.

ibmcloud catalog offering create [--catalog CATALOG_NAME] [--zipurl URL] [--include-config] [--target-version VERSION] [--token TOKEN] [--vpc-body BODY]

Command options

--catalog CATALOG_NAME: The catalog name or ID.
--zipurl URL (optional): URL pointing to .zip file of the product.
--target-version VERSION: Specify the version of the product.
--include-config (optional): If provided, all configuration values are included and available when you add the product.
--token TOKEN (optional): Specify the personal access token for a private repository.
--vpc-body BODY (optional): Provide the information to import a virtual server image for VPC, including a name, label, install kind, target kind, version, sha, tags, and metadata.

Virtual server image for VPC Example #1

Import a virtual server image for VPC as an offering to a catalog with ID 51c9e0db-2911-45a6-adb0-ac5332d27cf2.

ibmcloud catalog offering create --catalog 51c9e0db-2911-45a6-adb0-ac5332d27cf2 --vpc-body '{
    "name": "virtual-server-image",
    "label": "virtual server image",
    "install_kind": "instance",
    "target_kinds": ["vpc-x86"],
    "version": "0.0.10",
    "sha": "64245e5f3f1e9c4048b18db3abd1450d4b6f9e263ac1b33df6fc1ae96fcbdebb",
    "tags": ["virtualservers"],
    "metadata": {
        "operating_system": {
            "dedicated_host_only": false,
            "vendor": "CentOS",
            "name": "centos-7-amd64",
            "href": "https://us-south-stage01.iaasdev.cloud.ibm.com/v1/operating_systems/centos-7-amd64",
            "display_name": "CentOS 7.x - Minimal Install (amd64)",
            "family": "CentOS",
            "version": "7.x - Minimal Install",
            "architecture": "amd64"
        },
        "minimum_provisioned_size": 100,
        "file": {
            "size": 1
        },
        "images": [{"id": "r134-14903434-faf0-4a66-b861-7b35198de393", "name": "virtual-server-image", "region": "us-south"}]
    }
}'

Virtual server image for VPC Example #2

Import a virtual server image for VPC as an offering to a catalog with ID 2bdc3974-dfcf-4711-b298-cd238f7d3734.

ibmcloud catalog offering create --catalog 2bdc3974-dfcf-4711-b298-cd238f7d3734 --vpc-body '{
"name": "virtual-server-image-s390x",
"label": "virtual-server-image-s390x",
"install_kind": "instance",
"target_kinds": ["vpc-z"],
"version": "0.0.10",
"sha": "4739f1eaeeebc69ad5d48f9191fcc0d23960cb720bb16c67e915e5556c1da9b2",
"tags": ["virtualservers"],
"metadata": {
    "operating_system": {
        "dedicated_host_only": false,
        "vendor": "SUSE Linux Enterprise Server",
        "name": "sles-15-sp2-s390x-byol",
        "href": "https://us-south-stage01.iaasdev.cloud.ibm.com/v1/operating_systems/sles-15-s390x",
        "display_name": "Suse enterprise server(s390x)",
        "family": "SUSE",
        "version": "15-sp2",
        "architecture": "s390x"
    },
    "minimum_provisioned_size": 100,
    "file": {
        "size": 1
    },
    "images": [{"id": "r134-f20e2e4e-3133-423c-afa2-365afa14c4dc", "name": "virtual-server-image-s390x", "region": "us-south"}]
}

ibmcloud catalog offering list

Run the following command to get details about the products in your private catalogs. This command provides a filter by private catalog, product, and version.

ibmcloud catalog offering list [--catalog CATALOG] [--offering OFFERING_NAME] [--version VERSION] [--output FORMAT]

Command options

--catalog CATALOG: The catalog name or ID.
--output FORMAT (optional): Specifies output format. The default is terminal compatible and the only supported alternative is JSON, for example, --output json.

Example

List all of the products that are in the dev-catalog catalog.

ibmcloud catalog offering list --catalog dev-catalog

Output

The command returns the following output:

Name                                   ID                                     Current State   Version Locator
Cloud Pak for Automation               cb90274e-398b-4373-9b28-d6428d3302df
|__OpenShift
   |__19.0.2                                                                  New             7b7e590f-259b-437b-b1f4-39e8615ed837.21d1d712-80ab-4318-9d05-73c6caaaee23
Cloud Pak for Data                     8993c7b1-1794-4447-9275-db83faa08ee4
|__OpenShift
   |__2.1.0.2                                                                 New             7b7e590f-259b-437b-b1f4-39e8615ed837.ab6ba56f-788d-4d6b-b880-a1001fca8451
harbor                                 927adb44-6784-4bec-a771-f639900f07f1
|__Kubernetes
   |__1.9.1                                                                   New             7b7e590f-259b-437b-b1f4-39e8615ed837.e437b06c-273f-49de-8c44-f55e408abf78
IBM Starter Collection for Openshift   fd1857f4-cf17-4e97-9443-b615bc71f6a0
|__OpenShift
   |__0.0.1                                                                   New             7b7e590f-259b-437b-b1f4-39e8615ed837.72e0f636-9dc4-49ae-b3c2-7a5de90487b9
tf_cloudless_sleepy-2.0                c260a67a-1b25-49fc-9896-46e7e6212990
|__
   |__1.0.0                                                                   New             7b7e590f-259b-437b-b1f4-39e8615ed837.965df91d-5760-4872-adf6-4019796c06b0
   |__1.0.1                                                                   New             7b7e590f-259b-437b-b1f4-39e8615ed837.aff4cecb-4c9b-41ba-ae3d-71f4217dc0bc

ibmcloud catalog offering search

Run the following command to get details about the products in your private catalogs. This command provides a filter by private catalog, product, and version.

ibmcloud catalog offering search [--catalog CATALOG] [--offering OFFERING_NAME] [--version VERSION] [--output FORMAT]

Command options

--catalog CATALOG (optional): The catalog name or ID.
--offering OFFERING (optional): The product name or ID.
--version VERSION (optional): The version name or ID.
--output FORMAT (optional): Specifies output format. The default is terminal compatible and the only supported alternative is JSON, for example, --output json.

Example

List all of the products that are in the dev-catalog catalog.

ibmcloud catalog offering list --catalog dev-catalog

Output

The command returns the following output:

Name                                     Current State          Version Locator
dev-catalog
|__dev-offering
|  |__Kubernetes
|     |__1.0.0                           Validated              b636d651-8489-4425-bd6a-f30af1603577.17ac792e-a603-4f1a-a1b6-48e90a46940c
|__dev-offering-2.0
|  |__Kubernetes
|     |__1.0.0                           Published to account   b636d651-8489-4425-bd6a-f30af1603577.decdb0e1-46d2-401a-b482-80f9d6855f98

ibmcloud catalog offering get

Run the following command to get details about a specific product in the catalog.

ibmcloud catalog offering get --catalog CATALOG --offering OFFERING_NAME [--output FORMAT]

Command options

--catalog CATALOG: The catalog name or ID.
--offering OFFERING_NAME: The product name or ID.
--output FORMAT (optional): Specifies output format. The default is terminal compatible and the only supported alternative is JSON, for example, --output json.

Output

The command returns the following output:

Name           Current State   Version Locator
dev-offering
|__
   |__1.0.0    Draft           480fb4e3-d7ba-4e9b-9d4c-42f0ab811040.a92f5409-ebd9-413c-88ae-7ed311c1b793

ibmcloud catalog offering import-version

Run the following command to import a new version of a product in your private catalog.

ibmcloud catalog offering import-version --catalog CATALOG --offering OFFERING_NAME [--zipurl URL] [--target-version APP_VERSION] [--include-config] [--vpc-body BODY]

Command options

--catalog CATALOG: The catalog name or ID.
--offering OFFERING_NAME: : The product name or ID.
--zipurl URL (optional): URL pointing to the .zip file of the product.
--target-version APP_VERSION (optional): The application version of the "tgz" being imported.
--include-config (optional): If provided, all configurations values are included and available when you import the new version.
--vpc-body BODY (optional): Provide the information to import a virtual server image for VPC, including a name, label, install kind, target kind, version, sha, tags, and metadata.

Virtual server image for VPC example

Import a virtual server image for VPC to an existing offerng with to a catalog with ID 51c9e0db-2911-45a6-adb0-ac5332d27cf2 and offering ID 97cdaf1b-62b2-48e2-8589-10b31023866d.

ibmcloud catalog offering import-version --catalog 51c9e0db-2911-45a6-adb0-ac5332d27cf2 --offering 97cdaf1b-62b2-48e2-8589-10b31023866d --vpc-body '{
    "name": "virtual-server-image",
    "label": "virtual server image",
    "install_kind": "instance",
    "target_kinds": ["vpc-x86"],
    "version": "0.0.10",
    "sha": "64245e5f3f1e9c4048b18db3abd1450d4b6f9e263ac1b33df6fc1ae96fcbdebb",
    "tags": ["virtualservers"],
    "metadata": {
        "operating_system": {
            "dedicated_host_only": false,
            "vendor": "CentOS",
            "name": "centos-7-amd64",
            "href": "https://us-south-stage01.iaasdev.cloud.ibm.com/v1/operating_systems/centos-7-amd64",
            "display_name": "CentOS 7.x - Minimal Install (amd64)",
            "family": "CentOS",
            "version": "7.x - Minimal Install",
            "architecture": "amd64"
        },
        "minimum_provisioned_size": 100,
        "file": {
            "size": 1
        },
        "images": [{"id": "r134-14903434-faf0-4a66-b861-7b35198de393", "name": "virtual-server-image", "region": "us-south"}]
    }
}'

ibmcloud catalog offering update

To update a product in your private catalog, you first need get the product and then you can update.

Run the offering get command. For more information, see ibmcloud catalog offering get.

ibmcloud catalog offering get -c <CATALOGID> -o <OFFERINGID> --output json

Run the offering update command.

ibmcloud catalog offering update -c <CATALOGID> -o <OFFERINGID> --updated-offering <UPDATED_OFFERING.json>

ibmcloud catalog offering version preinstall

Run the following command to run the preinstallation script for a particular product.

ibmcloud catalog offering version preinstall --version-locator VERSION_NUMBER --cluster CLUSTER_ID --namespace NAME

Command options

--version-locator VERSION_NUMBER: To get the version locator for this product, run the ibmcloud catalog offering list command and locate the specified product and version that you'd like to use.
--cluster CLUSTER_ID: Provide the cluster ID of the cluster where you want to install the product.
--namespace NAME: Provide the namespace that you'd like to use. You can specify a new one and it is automatically created as part of the preinstallation.

Example

Run the preinstallation script for a product with a version locator number of b636d651-8489-4425-bd6a-f30af1603577.18aad484-c78b-4269-808b-52027621abd4 in cluster with ID bn5ebho206o7fg45f2e0 in the namespace called test-namespace.

ibmcloud catalog offering version preinstall --version-locator b636d651-8489-4425-bd6a-f30af1603577.18aad484-c78b-4269-808b-52027621abd4 --cluster bn5ebho206o7fg45f2e0 --namespace test-namespace

ibmcloud catalog offering version preinstall-status

Run the following command to get the status of an ongoing preinstallation.

ibmcloud catalog offering version preinstall-status --version-locator VERSION_NUMBER --cluster CLUSTER_ID --namespace NAME [--output FORMAT]

Command options

--version-locator VERSION_NUMBER: To get the version locator for the product, run the ibmcloud catalog offering list command and locate the specified product and version that you'd like to use.
--cluster CLUSTER_ID: Provide the cluster ID of the cluster where the preinstallation was run.
--namespace NAME: Provide the namespace used for the preinstallation.
--output FORMAT (optional): Specifies output format. The default is terminal compatible and the only supported alternative is JSON, for example, --output json.

ibmcloud catalog offering version validate

Run the following command to validate a new version of a product in your private catalog. Products must be validated to ensure that they work as expected before they can be published to the account for other users to create an instance from the private catalog.

ibmcloud catalog offering version validate --version-locator VERSION_NUMBER --cluster CLUSTER_ID --namespace NAME [--timeout TIMEOUT] [--wait WAIT] [--override-values VALUES|FILENAME] [--workspace-tf-version VERSION] [--workspace-region REGION] [--workspace-rg-id ID][--schematics-destroy][--schematics-delete]

Command options

--version-locator VERSION_NUMBER: To get the version locator for the product, run the ibmcloud catalog offering list command and locate the specified product and version you'd like to use.
--cluster CLUSTER_ID: Provide the cluster ID of the cluster where you want to install the product.
--namespace NAME: Provide the namespace that you'd like to use. You can specify a new one and it is automatically created as part of the preinstallation.
--timeout TIMEOUT: Specify in seconds how long the Schematics workspace waits it installs. Default is 180.
--wait WAIT: Wait and track the progress of the Schematics workspace job. If true, installation waits. If false, the software installs immediately. Default is true.
--override-values VALUES|FILENAME (optional): Provide any custom configurations for the installation. You can provide this value either inline or by using a JSON or TXT file. For example, override-values values.json. When validating a virtual server image for VPC, the following fields must be provided: vsi_instance_name, vsi_id, vpc_profile, subnet_id, vpc_id, subnet_zone, ssh_key_id, vpc_region
--workspace-tf-version VERSION (optional): Provide a workspace terraform version.
--workspace-region REGION (optional): Provide a workspace region.
--workspace-rg-id ID (optional): Provide a workspace resource group ID.
--schematics-destroy (optional): Provide this flag to delete the workspace resources after validation and installation.
--schematics-delete VALUE (optional): Provide this flag to delete the Schematics workspace after validation and installation.

Example validating a product using a cluster

Validate a product with the version locator b636d651-8489-4425-bd6a-f30af1603577.18aad484-c78b-4269-808b-52027621abd4 in a cluster with the ID bn5ebho206o7fg45f2e0 within a namespace called test-namespace. This installation has custom configurations, so the values are provided by using a values.json file.

ibmcloud catalog offering version validate --version-locator b636d651-8489-4425-bd6a-f30af1603577.18aad484-c78b-4269-808b-52027621abd4 --cluster bn5ebho206o7fg45f2e0 --namespace test-namespace --override-values values.json

Override values example format from the values.json file:

{
  "username": "provision-test-1",
  "password": "passw0rd"
}

Virtual server image for VPC Example

Validate a product with the version locator 51c9e0db-2911-45a6-adb0-ac5332d27cf2.ecebffdc-f1f8-4a85-965f-9cbe31920542 in a VPC with the ID r134-476cbb67-a6c2-4957-9806-3fcbac3498be.

ibmcloud catalog offering version validate --version-locator 51c9e0db-2911-45a6-adb0-ac5332d27cf2.ecebffdc-f1f8-4a85-965f-9cbe31920542 --workspace-region=us-south --workspace-rg-id Default --override-values '{
  "vsi_instance_name": "instance-name-1",
  "vsi_id": "r134-14903434-faf0-4a66-b861-7b35198de393",
  "vpc_profile": "bx2-2x8",
  "subnet_id": "0716-d799c449-466c-4844-902c-a5d3f8948d7d",
  "vpc_id": "r134-476cbb67-a6c2-4957-9806-3fcbac3498be",
  "subnet_zone": "us-south-1",
  "ssh_key_id": "r134-0c53e7f2-771f-4d0e-a19e-39f2e6e6949c",
  "vpc_region": "us-south"
}'

ibmcloud catalog offering version validate-status

Run the following command to get the status of an ongoing validation.

ibmcloud catalog offering version validate-status --version-locator VERSION_NUMBER [--output FORMAT]

Command options

--version-locator VERSION_NUMBER: To get the version locator for the product, run the ibmcloud catalog offering listcommand and locate the specified product or version you want to use.
--output FORMAT (optional): Specifies output format. The default is terminal compatible and the only supported alternative is JSON, for example, --output json.

ibmcloud catalog offering category-options

Run the following command to retrieve the list of category choices.

ibmcloud catalog offering category-options [--output FORMAT]

Command options

--output FORMAT (optional): Specifies output format. The default is terminal compatible and the only supported alternative is JSON, for example, --output json.

Example

ibmcloud catalog offering category-options

Output

The command returns the following output:

Name                    Tags                                                  Description
VPC Infrastructure      vpc                                                   Fully customizable, software-defined virtual network with superior isolation.
Compute                 compute,content,containers,openwhisk,vmware,runtime   Build your virtual environments
Containers              containers,clusters,registry                          Get started by creating a Kubernetes cluster, or manage your Docker images in the registry.
Networking              network                                               Order network.
Storage                 storage                                               Order storage.

ibmcloud catalog offering add-category

Run the following command to add a category tag to a product. You can provide the category name, which you can find by running the ibmcloud catalog offering category-options command. The products must be placed in a category to be visible in the catalog. Default is Developer tools.

ibmcloud catalog offering category-options [--output FORMAT]

Command options

--catalog CATALOG: The catalog name or ID.
--offering OFFERING: The product name or ID.
--category CATEGORY: Provide the category that best fits how users might use your product. Categories are used to organize products in the catalog based on common solutions, function, or use. You can select only one category. Run the ibmcloud catalog offering category-options command to view all options. Default is Developer tools.

Example

ibmcloud catalog offering add-category --catalog dev-catalog --offering dev-offering --category dev_ops

ibmcloud catalog offering categories

Run the following command to retrieve the category of a product version.

ibmcloud catalog offering version categories [--catalog CATALOG] [--offering OFFERING] [--output OUTPUT]

Command options

--catalog CATALOG: The catalog name or ID.
--offering OFFERING: The product name or ID.
--output FORMAT (optional): Specifies output format. The default is terminal compatible and the only supported alternative is JSON, for example, --output json.

Example

Retrieve the category of a product that is called dev-offering and located in the dev-catalog.

ibmcloud catalog offering version categories --catalog dev-catalog --offering dev-offering

ibmcloud catalog offering version get-claims

Run the following command to retrieve the security and compliance information that a version claimed.

  ibmcloud catalog offering version get-claims [--output OUTPUT] [--version-locator LOCATOR]

Command options

--version-locator LOCATOR: To get the version locator for the product, run the ibmcloud catalog offering list command and locate the specified product or version you want to use.
--output OUTPUT (optional): Specifies output format. The default is terminal compatible and the only supported alternative is JSON, for example, --output json.

ibmcloud catalog offering version update-claims

Run the following command to update the security and compliance claims of a version.

  ibmcloud catalog offering version update-claims [--claims CLAIMS] [--version-locator LOCATOR]

Command options

--claims CLAIMS: Specify the claims data for a version as a JSON object or file.
--version-locator LOCATOR: To get the version locator for the product, run the ibmcloud catalog offering list command and locate the specified product or version you want to use.

ibmcloud catalog offering version scc-apply

Run the following command to add a Security and Compliance Center scan to your version. You must add security and compliance information to your version and validate your version before you can add a scan.

  ibmcloud catalog offering version scc-apply [--instance-region REGION] [--scan SCAN] [--service-instance INSTANCE] [--target-account-name NAME] [--target-api-key KEY] [--timeout TIMEOUT] [--version-locator LOCATOR] [--wait WAIT]

Command options

--instance-region REGION: The region of the instance.
--scan SCAN: The ID of a Security and Compliance Center scan.
--service-instance INSTANCE: Provide the Security and Compliance Center instance ID.
--target-account-name NAME (optional): Provide the name of the target account.
--target-api-key KEY (optional): Provide an API key if you want to use an alternative account (target account) to apply a scan to your source account. For more information, see Setting up a target account.
--timeout TIMEOUT: Specify in seconds how long you want to wait for the scan to be applied to the version before the command returns. Default value is 600 (10 minutes).
--version-locator LOCATOR: To get the version locator for the product, run the ibmcloud catalog offering list command and locate the specified product or version you want to use.
--wait WAIT: Wait and track the progress of a scan application. Default is true if flag is not provided. If true, the command tracks progress of the scan application. If false, the command returns immediately.

ibmcloud catalog offering version scc-apply-status

Run the following command to see the status of a Security and Compliance Center scan application to your version.

  ibmcloud catalog offering version scc-apply-status [--scan SCAN] [--version-locator LOCATOR]

Command options

--scan SCAN: The ID of a Security and Compliance Center scan.
--version-locator LOCATOR: To get the version locator for the product, run the ibmcloud catalog offering list command and locate the specified product or version you want to use.

ibmcloud catalog offering version get-scans

Run the following command to retrieve the Security and Compliance Center scans that are added to your version.

  ibmcloud catalog offering version get-scans [--instance-region REGION] [--output OUTPUT] [--profiles PROFILES] [--service-instance INSTANCE] [--target-account-name NAME] [--target-api-key KEY]

Command options

--instance-region REGION: Provide the region of the instance.
--output OUTPUT (optional): Specifies output format. The default is terminal compatible and the only supported alternative is JSON, for example, --output json.
--profiles PROFILES: Provide a comma-separated list of profile names with versions, for example, "IBM Cloud for Financial Services::1.2.0".
--service-instance INSTANCE: Provide the Security and Compliance Center instance ID.
--target-account-name NAME (optional): Provide the name of the target account.
--target-api-key KEY (optional): Provide an API key if you want to use an alternative account (target account) to apply a scan to your source account. For more information, see Setting up a target account.

ibmcloud catalog offering get-scan-results

Run the following command to generate a report of your security and compliance scan results. To generate a full report, you must apply a Security and Compliance Center scan. For more information, see ibmcloud catalog offering version scc-apply.

ibmcloud catalog offering get-scan-results [--version-locator LOCATOR]

Command options

--version-locator LOCATOR: To get the version locator for the product, run the ibmcloud catalog offering list command and locate the specified product or version you want to use.

ibmcloud catalog offering version create-draft

Run the following command to create a draft of an existing version. This command is useful for changing an existing version that you want to publish without introducing a new version. Some changes, like changing the source file, require you to revalidate the product.

ibmcloud catalog offering version create-draft --version-locator VERSION_NUMBER [--output FORMAT]

Command options

--version-locator VERSION_NUMBER: To get the version locator for the product, run the ibmcloud catalog offering list command and locate the specified product or version you want to use.
--output FORMAT (optional): Specifies output format. The default is terminal compatible and the only supported alternative is JSON, for example, --output json.

ibmcloud catalog offering version delete-version

Run the following command to delete a version of a product.

ibmcloud catalog offering version delete-version --version-locator VERSION_NUMBER [--output FORMAT]

Command options

--version-locator VERSION_NUMBER: To get the version locator for the product, run the ibmcloud catalog offering list command and locate the specified product or version you want to use.
--output FORMAT (optional): Specifies output format. The default is terminal compatible and the only supported alternative is JSON, for example, --output json.

ibmcloud catalog offering version deprecate-version

Run the following command to deprecate a previously published product version from the IBM Cloud catalog.

ibmcloud catalog offering version deprecate-version --version-locator VERSION_NUMBER

Command options

--version-locator VERSION_NUMBER: To get the version locator for the product, run the ibmcloud catalog offering list command and locate the specified product or version you want to use.

ibmcloud catalog offering version refresh-version

Run the following command to create a change the source file of a draft version. This command is useful for updating an existing version.

ibmcloud catalog offering version refresh-version --version-locator VERSION_NUMBER --zipurl URL [--include-config]

Command options

--version-locator VERSION_NUMBER: To get the version locator for the product, run the ibmcloud catalog offering list command and locate the specified product or version you want to use.
--zipurl URL: URL pointing to the .zip file of the product.
--include-config (optional): If provided, all configuration values are included and available when you add the product.

ibmcloud catalog offering version merge-draft

Run the following command to merge a draft version of a product.

ibmcloud catalog offering version merge-draft --version-locator VERSION_NUMBER

Command options

--version-locator VERSION_NUMBER: To get the version locator for the product, run the ibmcloud catalog offering list command and locate the specified product or version you want to use.

Run the following command to enable your product to be shared.

ibmcloud catalog offering enable-sharing --catalog CATALOG --offering OFFERING

ibmcloud catalog offering ready

Run the following command to mark your product as ready to share or publish.

ibmcloud catalog offering ready --version-locator VERSION_NUMBER

Command options

--version-locator VERSION_NUMBER: To get the version locator for the product, run the ibmcloud catalog offering list command and locate the specified product or version you want to use.

ibmcloud catalog offering delete

Run the following command to delete a product from your private catalog. You cannot delete a product that is published in the IBM Cloud catalog. To deprecate a published product from the IBM Cloud catalog, see ibmcloud catalog offering deprecate-offering.

ibmcloud catalog offering delete --catalog CATALOG --offering OFFERING

Command options

--catalog CATALOG: The catalog name or ID.
--offering OFFERING: The product name or ID.

ibmcloud catalog offering publish account

Run the following command to publish a product from your private catalog to an account. After the product is published, users in the account that have access to the private catalog and its containing resource group can create an instance and start using it.

ibmcloud catalog offering publish account [--catalog CATALOG][--offering OFFERING]

Command options

--catalog CATALOG: The catalog name or ID.
--offering OFFERING: The product name or ID.

ibmcloud catalog offering publish allowlist

Run the following command to publish a product from your private catalog to a set of allowlisted accounts. After the product is published, users in the allowlisted accounts can create an instance and start using it.

ibmcloud catalog offering publish allowlist [--catalog CATALOG][--offering OFFERING][--account-ids ACCOUNT-IDS]

Command options

--catalog CATALOG: The catalog name or ID.
--offering OFFERING: The product name or ID.
--account-ids ACCOUNT-IDS: The account IDs.

ibmcloud catalog offering publish enterprise

Run the following command to publish a product to an enterprise. After the product is published, users within the enterprise can create an instance of the product.

ibmcloud catalog offering publish enterprise [--catalog CATALOG][--offering OFFERING]

Command options

--catalog CATALOG: The catalog name or ID.
--offering OFFERING: The product name or ID.

ibmcloud catalog offering suspend-offering

Run the following command to suspend a product from the catalog. You can suspend it for a short time without permanently deleting or deprecating it. Suspending a product can be useful if, for example, you discover a bug or a vulnerability in your product that must be investigated before more customers install it.

ibmcloud catalog offering suspend-offering [--catalog CATALOG][--offering OFFERING]

Command options

--catalog CATALOG: The catalog name or ID.
--offering OFFERING: The product name or ID.

ibmcloud catalog offering version suspend-version

Run the following command to suspend a version of a product from the catalog. You can suspend the version for a short time without permanently deleting or deprecating it.

ibmcloud catalog offering version suspend-version [--version-locator VERSION_NUMBER]

Command options

--version-locator VERSION_NUMBER: To get the version locator for this offering, run ibmcloud catalog offering list and locate the version that you want to use.

ibmcloud catalog offering workspaces

Run the following command to get the Schematics workspaces for a product version.

ibmcloud catalog offering workspaces [--version-locator VERSION_NUMBER] [output FORMAT]

Command options

--version-locator VERSION_NUMBER: To get the version locator for this offering, run ibmcloud catalog offering list and locate the specified version that you want to use.
--output FORMAT (optional): Specifies output format. Default is terminal compatible and the only supported alternative is JSON. For example, --output json.

ibmcloud catalog install

Run the following command to install a software version from the IBM Cloud catalog.

ibmcloud catalog install [--version-locator VERSION_NUMBER] [--cluster CLUSTER_ID] [--namespace NAME] [--override-values VALUES] [--timeout TIMEOUT] [--wait WAIT] [--workspace-name NAME] [--workspace-tags TAGS] [--workspace-tf-version VERSION] [--workspace-region REGION] [--workspace-rg-id ID] [schematics-delete VALUE]

Command options

--version-locator VERSION_NUMBER: To get the version locator for this offering, run ibmcloud catalog offering list and locate the version that you want to use.
--cluster CLUSTER_ID: Specify the cluster name or ID.
--namespace NAME: Specify the namespace that you'd like to use.
--override-values VALUES: Provide any custom configurations for the installation. You can provide this value either inline or by using a JSON or TXT file. For example, override-values values.json.
--timeout TIMEOUT: Specify in seconds how long the Schematics workspace waits before it installs. Default is 180.
--wait WAIT: Wait and track the progress of the Schematics workspace job. If true, installation waits. If false, the software installs immediately. Default is true.
--workspace-name NAME (optional): Provide a workspace name. Default is OfferingName-Date.
--workspace-tags TAGS (optional): Provide a comma-separated list of tags.
--workspace-tf-version VERSION (optional): Provide a workspace terraform version.
--workspace-region REGION (optional): Provide a workspace region.
--workspace-rg-id ID (optional): Provide a workspace resource group ID.
--schematics-delete VALUE (optional): Provide this flag to delete the Schematics workspace after validation and installation.

ibmcloud catalog pricing

Run the following command to get pricing information for catalog offerings.

ibmcloud catalog pricing [-r, --region REGION] [-k, --kind KIND] [-p, --price PRICE] [--tag TAG] [--country COUNTRY] [--global] [--iam] [--json] [--csv] [-f, --file FILENAME]

Command options

-r, --region (optional): Filter by geo.
-k, --kind (optional): Filter by kind of resources. Currently service (default), iaas, runtime, template, and geography are supported
-p, --price (optional): Filter by price. Currently free, paygo, and subscription are supported
-t, --tag (optional): Filter by tag. This flag is repeatable and results in a logical OR of all the tags specified.
--co, --country (optional): Filter by a country. Output to csv or json may use the value ALL to get values for all countries.
--json (optional): Output JSON response.
--csv (optional): Output CSV file.
-f, --file (optional): Specify a filename for the csv output.
--global (optional): Operate in global scope.
--iam (optional): Filter by Iam compatible offerings.

Example

Get pricing information for Virtual Server for VPC for a Pay-As-You-Go account.

ibmcloud catalog pricing is.instance [--price paygo]

ibmcloud catalog utility create-product-from-workspace

Run the following command to create a deployable architecture tile from a Schematics workspace that was created directly from the Git repository. The deployable architecture creates a project to enable you to continue to develop and maintain the deployable architecture with the future version.

The command requires a GIT_TOKEN environment variable to authenticate with your source repository so a catalog manifest can be added. The command pushes to a new branch in the Git repository that is found in the Schematics workspace and creates a release that is used for onboarding.

ibmcloud catalog utility create-product-from-workspace [--workspace-id ID] [--api-key KEY] [--trusted-profile-id ID] [--catalog-label LABEL] [--offering-label LABEL] [--project-name NAME] [--project-resource-group GROUP] [--target-version VERSION] [--variation-label LABEL]

Command options

--api-key or --ak API KEY: Provide an API key that will be used to link the catalog and project. Mutually exclusive with '--trusted-profile-id'.
--catalog-label CATALOG LABEL (optional): Provide the label of an existing catalog to import into or the name of a new catalog to create. Default is 'Migrated DAs'.
--offering-label OFFERING LABEL (optional): Provide the label of an existing offering to import into or the name of a new offering to create. Default is 'Migrated <workspace_name>'. The label overwrites the existing offering label if the workspace is created from a catalog offering.
--project-name NAME (optional): Provide a project name that will be linked to the onboarded catalog. If the project does not exist it will be created. Default name is 'Dev Migration Project'.
--project-resource-group (optional): Provide a resource group for the project that will be created. Default resource group is 'Default'.
--target-version VERSION (optional): Provide the target version for the migrated offering. Default is '1.0.0'.
--trusted-profile-id or --tpi TRUSTED PROFILE ID: Provide a trusted profile ID that will be used to link the catalog and project. Mutually exclusive with '--api-key'.
--variation-label VARIATION LABEL (optional): Provide a variation label for the version to be onboarded. Default is 'Standard'. The label overwrites the existing version label if the workspace is created from a catalog offering.
--workspace-id WORKSPACE ID: Provide a Schematics workspace ID. To get the workspace ID, you must create the Schematics workspace. For more information, see ibmcloud schematics workspace new.

ibmcloud catalog utility netrc

Run the following command to create a .netrc file, generate the machine name in your .netrc file, or update the credential in your .netrc file. A .netrc file stores the required login information that is needed to use Terraform modules from the IBM Cloud catalog.

By running this command, you configure a .netrc file for the machine name cm.globalcatalog.cloud.ibm.com with iamtoken as the username and your IAM token as the password.

You need version 1.2.7 or higher of the catalogs management CLI plug-in to run the .netrc command.

ibmcloud catalog utility netrc

ibmcloud catalog utility update-module-references

Run the following command to check your working directory's Terraform modules for updates from the catalog and update the source attribute to the latest version. The README.md is also updated.

ibmcloud catalog utility update-module-references

ibmcloud catalog offering unpublish account

Run the following command to unpublish a product from your account. After the product is unpublished, users in your account cannot create an instance of the product.

ibmcloud catalog offering unpublish account [--catalog CATALOG][--offering OFFERING]

Command options

--catalog CATALOG: The catalog name or ID.
--offering OFFERING: The product name or ID.

ibmcloud catalog offering unpublish allowlist

Run the following command to remove account IDs from the product's allowlist. Accounts that are removed from the allowlist cannot create an instance of the product.

ibmcloud catalog offering unpublish allowlist [--catalog CATALOG][--offering OFFERING][--account-ids ACCOUNT-IDS]

Command options

--catalog CATALOG: The catalog name or ID.
--offering OFFERING: The product name or ID.
--account-ids ACCOUNT-IDS: The account IDs.

ibmcloud catalog offering unpublish enterprise

Run the following command to unpublish a product from an enterprise. After the product is unpublished, the enterprise cannot create an instance of the product.

ibmcloud catalog offering unpublish enterprise [--catalog CATALOG][--offering OFFERING]

Command options

--catalog CATALOG: The catalog name or ID.
--offering OFFERING: The product name or ID.

ibmcloud catalog offering publish public

Run the following command to publish your private offering to the IBM Cloud catalog for all users to see and use. To get to this step in the publication process, you must first publish the offering to your account and to all IBMers to complete the testing process. After your testing is complete, you can run this command.

This option requires approval. As soon as your approval is complete, your tile is available for all IBM Cloud customers.

ibmcloud catalog offering publish public [--catalog CATALOG][--offering OFFERING]

Command options

--catalog CATALOG: The catalog name or ID.
--offering OFFERING: The product name or ID.

ibmcloud catalog offering deprecate-offering

Run the following command to deprecate a previously published offering version in the IBM Cloud catalog.

ibmcloud catalog offering deprecate-offering [--catalog CATALOG][--offering OFFERING]

Command options

--catalog CATALOG: The catalog name or ID.
--offering OFFERING: The product name or ID.

ibmcloud catalog offering restore-offering

Run the following command to restore a previously deprecated product in the IBM Cloud catalog. After you validate a version of your product, you can restore it to the published state that it was in before it was deprecated.

ibmcloud catalog offering restore-offering [--catalog CATALOG][--offering OFFERING]

Command options

--catalog CATALOG: The catalog name or ID.
--offering OFFERING: The product name or ID.

ibmcloud catalog offering version restore-version

Run the following command to restore a previously deprecated version of a product in the IBM Cloud catalog. Restoring it places the version in draft state. After you validate it, you can restore the original version to the published state that it was in before it was deprecated.

ibmcloud catalog offering version restore-version [--catalog CATALOG][--offering OFFERING] [--include-config]

Command options

--catalog CATALOG: The catalog name or ID.
--offering OFFERING: The product name or ID.
--include-config (optional): If provided, all configuration values are included and available when you add the product.