OpenShift: Deciding to use individual CRs, a top-level CR, or Cloud Pak for Integration

You can install API Connect subsystems separately by using individual subsystem CRs, or you can deploy them all together with a top-level CR. You can also deploy API Connect as part of Cloud Pak for Integration. The differences between each installation type are described in this topic.

Before you review this topic, make sure that you understand the Key concepts: Custom Resources, Operators, and Operands of API Connect.

Deploying with individual subsystem CRs

Deploying API Connect using individual subsystem CRs means that you must install each subsystem separately, either with the OpenShift UI, or by manually applying YAML files for each subsystem. The portal, analytics, and gateway subsystems must then be manually registered with the management subsystem, as described in Defining your Cloud Manager topology.

Individual subsystem CRs: Key points
  • Deploying with individual subsystem CRs allows more flexibility than the alternative top-level CR deployment, and can be simpler to manage.
    • Subsystems in the same API Connect cluster can be installed in different namespaces.
    • Updates to subsystem CRs are made directly in the subsystem CR. When the top-level CR is used, all configuration updates must be made in the top-level CR, which can require copying sections from the subsystem CR and pasting them into the top-level CR.
    • Custom certificates can be used for inter-subsystem communication.
    • The two data center disaster recovery deployment topology is simpler to manage and more flexible when individual subsystem CRs are used.
  • The individual subsystem CR installation is preferable for deployments where you plan to have multiple portal and analytics services, or subsystems in different namespaces, and where you do not require the other capabilities of Cloud Pak for Integration.
  • Individual subsystem CR installation does not integrate as fully with Cloud Pak for Integration as the top-level CR installation. See the next section.

Deploying with the top-level CR

Deploying with the top-level CR automates the deployment of each subsystem. To install, you select 'API Connect' in either the OpenShift console or the Cloud Pak for Integration Platform UI, enter some properties such as namespace, click 'Create', and all the subsystems that make up an API Connect instance are automatically installed. You still have individual CRs for each subsystem, but they are all managed by the top-level CR. The top-level CR is called APIConnectCluster.

Top-level CR: Key points to consider
  • All API Connect subsystems are managed by the top-level CR. You edit the top-level CR YAML when you want to update your API Connect configuration.
  • With the top-level CR, the subsystem CRs still exist but should not be edited directly. Any changes made to them get overwritten by the top-level CR.
  • Installation with the top-level CR requires fewer steps, but subsequent management of subsystems and configuration of advanced features can be more complicated than it is with an individual subsystem deployment.
  • The top-level CR deployment provides one of each subsystem service: management, portal, analytics, and gateway. If you want additional portal, analytics, or gateway services, do not use the top-level CR.
  • For a quick proof-of-concept demonstration, the top-level CR is ideal due to the automated installation of subsystems.
  • The top-level CR deployment integrates fully with Cloud Pak for Integration. For top-level CR installation instructions on Cloud Pak for Integration, see Deploying an instance by using the Platform UI and Deploying all API management subsystems by using the CLI in the Cloud Pak for Integration documentation.

Deploying with Cloud Pak for Integration

Cloud Pak for Integration includes API Connect as one of its many capabilities. For information on everything Cloud Pak for Integration provides, see https://www.ibm.com/docs/en/cloud-paks/cp-integration.

Key points of a Cloud Pak for Integration API Connect installation:
  • Cloud Pak for Integration provides a UI, called the Platform UI, which can be used to install and manage your API Connect deployment.
  • When installing API Connect with the Cloud Pak for Integration Platform UI, the top-level CR deployment is used. All the same key points of the top-level CR apply to Cloud Pak for Integration installations that use the top-level CR.
  • If Cloud Pak for Integration is already installed in your environment, and you install API Connect with the Cloud Pak for Integration Platform UI, then API Connect automatically incorporates and attempts to use Cloud Pak features.

    You can prevent Cloud Pak for Integration incorporating your API Connect installation by setting metadata.annotations.apiconnect-operator/cp4i to false in the top-level CR before installation.

    If you are not installing API Connect with the Cloud Pak for Integration Platform UI and you want your API Connect deployment incorporated with Cloud Pak for Integration, then you can set the API Connect metadata.annotations.apiconnect-operator/cp4i annotation to true in your top-level CR (or management CR if not using the top-level CR) before installation.

    It is not possible to change the value of metadata.annotations.apiconnect-operator/cp4i after installation. If you want to do this, then you must reinstall API Connect.

  • It is not possible to uninstall Cloud Pak for Integration and retain any API Connect instance that it is managing. Nor can a Cloud Pak for Integration API Connect instance be converted to a stand-alone instance. If you want to change to a non-Cloud Pak for Integration deployment, see Migrating from v10 to v10 on a different form factor.
  • You can migrate an existing top-level CR installation to be incorporated into Cloud Pak for Integration. See see Migrating from OpenShift to Cloud Pak for Integration on the same cluster.
    Note: The reverse of this operation is not supported.
  • In a Cloud Pak for Integration installation, if the Platform UI is detected and the top-level CR deployment is used, the API Connect operator runs a job that is called the configurator, which registers all API Connect subsystems with the management service after installation. This means that your API Connect installation is ready for you to immediately start configuring provider organizations.
  • Cloud Pak for Integration does mean a higher computing resource requirement in your environment, when compared to a stand-alone API Connect installation.
  • The planning requirements for API Connect such as available PVs and Firewall settings that are described in Planning your deployment, also apply when you install API Connect with Cloud Pak for Integration.

Which deployment type should you choose?

For long-term ease of maintenance and maximum flexibility, choose Deploying with individual subsystem CRs.

For integration with the App Connect, Asset Repo, Platform UI, and other Cloud Pak for Integration features, choose Deploying with Cloud Pak for Integration.

For quick installation of API Connect that is suitable for demonstrations and testing, choose Deploying with the top-level CR.