Using declarative API Products

A declarative Product is a custom resource that allows you to create API Connect Products using a YAML file. Learn how to create and configure this resource type.

For more information about Products, see Working with Products in the API Connect documentation.

Create a secret with your API manager credentials

Create a secret containing the credentials for the API manager you want the declarative Product to use.

You can have multiple secrets in the same namespace, and have different Products reference different secrets.

Create the secret:

cat <<EOF | oc apply -f -
apiVersion: v1
kind: Secret
  name: apim-credentials
type: Opaque
  base_url: https://<api-connect-base-url>
  username: <username>
  password: <password>
  trusted_cert: |-
  1. To get the values you need to use within the secret, run the following command in the namespace where the API manager is installed, replacing <instance-name> with the name of the API manager instance:

    oc get ManagementCluster <instance-name>-mgmt -o json | jq -r '.status.endpoints[] | select(.name=="platformApi")'

    This returns a JSON object with the following structure, where <api-secret-name>, and <api-connect-base-url>, are values that change depending on the name of your APIC manager instance.

      "name": "platformApi",
      "type": "API",
      "secretName: "<api-secret-name>",
      "uri": "<api-connect-base-url>"
  2. Replace the values in the secret with the previously returned values, as follows:

    • Replace <api-connect-base-url> with the values that were generated in the previous command.

    • Replace <certificate> with the certificate content for a cert that the API manager trusts. On OpenShift, get this content by running the following command in the namespace where the API manager is installed, replacing <api-secret-name>, with the value that was generated in the previous step:

      oc get secret <api-secret-name> -o json | jq -r '.data["ca.crt"]' | base64 --decode
    • Replace <username> with the username you want to use.

    • Replace <password> with the password for that username.

Create a product with the CLI

  1. Log into your cluster, using your OpenShift user credentials:

    oc login
  2. Create a Product YAML file. For example, you could create a file called product.yaml with the following example configuration. Update the values as indicated:

    • For metadata.namespace, enter your project (namespace) name.

    • For spec.state, specify the desired lifecycle state. For more information, see The Product lifecycle.

    • For spec.apis, specify a list of apis and integration runtimes you want to be part of this product.

      • For spec.apis.apis, you can specify an array with the names of declarative apis you want this product to consume. For more information, see Using declarative APIs.

      • For spec.apis.integrationRuntimes, you can specify an array with the names of IntegrationRuntime resources you want this product to consume. For more information, see the "Custom resource values" section.

    • For spec.share.apim:

      • For credentialsSecret, specify the name created in the Create a secret with your API manager credentials section.

      • For providerOrg, specify the name of the API Connect provider organisation to add this product to.

      • For catalog, specify the name of the API Connect catalog to add this product to.

    • Set any other configuration values as required, such as defining the properties of the product under spec.definition.

      kind: Product
        name: example-product
        namespace: <namespace>
        state: Published
          product: 1.0.0
            title: Example
            name: test-https-routes-noauth
            version: '1.0'
                  value: 100/1hour
              title: Default Plan
              description: Default Plan
              approval: false
            - name: test-https-routes-noauth
            - name: example-api-resource
            credentialsSecret: apim-credentials
            providerOrg: main-demo
            catalog: main-demo-catalog
  3. Apply the YAML file to the cluster:

    oc apply -f product.yaml
  4. Check the status of the Product by running the following command in the project (namespace) where it was deployed:

    oc get product

Custom resource values

The following table lists the configurable parameters and default values for the custom resource.

Parameter Description Default
apiVersion The API version that identifies which schema is used for this declarative Product
kind Resource type Product Unique short name by which the declarative Product can be identified
metadata.namespace Namespace (project) in which the declarative Product is installed
spec.state The required state for the product. One of Staged, Published, Deprecated, Retired.
spec.migrateSubscriptions Defaults to true if omitted. If true then when the Product CR is modified to create a new version of the product the subscriptions are migrated from the old version to the new version. If the old/new product are to be supported concurrently then a new Product CR should be created for the new version and the old Product CR left unchanged. true
spec.share If share is specified then the Product is added to API Connect and transitioned to the required state.
spec.definition Defines the product. This matches the format of the product yaml/json used by APIC.
spec.apis Allows choosing which APIs to add to the product yaml/json before passing to the API manager.
spec.apis.apis Allows choosing a number of apis by referencing API CRs by name.
spec.apis.integrationRuntimes Defines which REST API document to retrieve from a running IntegrationRuntime in the same namespace as this Product.
status.conditions Returns information on the current condition of the declarative Product
status.metadata Returns metadata for declarative Product