Installing API Connect collective

[V5.0.6 and earlier]Install the API Connect collective Member host and the API Connect collective controller. Add the API Connect collective to the Cloud Manager.

Before you begin

Important:
  • IBM® API Connect collectives are deprecated in IBM API Connect Version 5.0.7 in favor of container runtimes. For more information and background, see Open, scalable, flexible runtime management of APIs through API Connect enabled containers. For information on setting up and migrating to containers, see Installing a containerized runtime environment.
  • Existing customers can continue to use their collectives with IBM API Connect Version 5.0.7, and if wanted can expand their collective deployments to new servers. API Connect collectives are supported for existing customers until the end of support of IBM API Connect Version 5.0 (see Software lifecycle page for IBM API Connect Version 5.0). Until then, users of API Connect collectives are encouraged to migrate to container runtimes to take advantage of their agility and scalability.
  • New customers should not install API Connect collectives because this feature is no longer supported for new users.
This task assumes that you installed IBM API Connect and that the host server can access the API Connect collective member package.
This document provides the following instructions. If you want to install more than one collective, you must provide a unique name. For instructions, see Preparing to install multiple collectives and Installing extra collectives to an existing installation.
Requirements:
  • A host server with a supported operating system.
  • Administrative privileges, such as root privileges, on the host machine.
  • The Management server.
  • A supported version of Node.js.
  • C++ compiler, make, and Python.
For information about supported operating systems and Node.js versions, see the IBM API Connect Version 5.0 Detailed System Requirements report on the IBM Software Product Compatibility Reports site according to which API Connect offering you are using. Use the product component filter to specify the collective controller or collective member.

Installing the collective controller

Install the API Connect collective controller. Add the collective to the Cloud Manager.

Before you begin

As a prerequisite to installing the collective controller, you must install a supported version of Node.js.

For details of supported Node.js versions, follow the link on the IBM API Connect Version 5.0 requirements page to the IBM API Connect Software Product Compatibility Report for the API Connect offering you are using, then click the Prerequisites tab.

Node.js is available as part of the IBM SDK for Node.js.

About this task

Install and configure the API Connect collective controller host. The controller package comes with Liberty Profile and a JRE to run the API Connect collective and controller. The bundled packages come with the appropriate JRE for Liberty.
Note: Global installs with the npm install -g command might require root or administrator privileges or use of the --unsafe-perm parameter. In general, use the following guidelines based on how Node.js was installed:
  • If Node.js is installed under a user account, then the controller and member installation commands do not require sudo or the --unsafe-perm argument.
  • If Node.js and the controller and member installation commands are run under the root account, then the controller and member installation commands do not require sudo but do need to use the --unsafe-perm argument.
  • If Node.js is installed under the root account but the controller or member installation commands are run from a non-root account, then the controller and member installation commands do require sudo and the --unsafe-perm argument.

Procedure

  1. Download the IBM API Connect controller package from Passport Advantage®.
  2. Install the collective controller: 
    [sudo] npm install -g [--unsafe-perm] /<path>/apiconnect-collective-controller-<platform>-<version>.tgz
    where:
    • --unsafe-perm specifies that npm runs as the root account.
    • <path> is the path to the package.
    • <platform> is the operating system and processor architecture. The following values are valid:
      • darwin - Mac OS X
      • linux-x86_64 - Linux® 64-bit
      • linux-s390x - Linux z/OS®
      • linux-ppc64le - Linux Power® 64-bit Little-Endian
    • <version> is the current package version.
  3. Setup the password: 
    wlpn-controller setup --password=password [--keystorePassword=PASS] [...]
    where:
    • --password=<PASS>: Sets the administrative password of the controller. This password is used to login to the Admin Center, and is required to join members and host machines to the collective.
    • --user=<USER>: The administrative account name. Required to login to the Admin Center, and is required to join members and host machines to the collective.
    • --hostName=<HOSTNAME>: The hostname of the machine. The installation makes use of the available hostname for setting up the controller.
      Note: If the hostname is not a routable address, you must set this flag to a routable server name or IP address, for example, server.address.local or 12.34.56.78.
    • --httpPort=<PORT>: The HTTP port that the controller listens on. The default value is 8080.
    • --httpsPort=<PORT>: The HTTPS port that the controller listens on. The default value is 9443.
    • --keystorePassword=<PASS>: The password for the PFX key that is used for HTTPS communication with other collective members. This certificate is generated by the Liberty Profile as a part of the controller installation. If the password is not set, it defaults to the password that is used for the administrative account.
      Note: Set a unique value for this option on setup.
  4. Start the controller. 
    wlpn-controller start

    When the controller starts, you can log into the controller from a browser. Log in to see the status of the controller and ensure that the configured ports are open for use.

    https://<controllerHostname>):<controllerPort>/adminCenter/
  5. Add the API Connect collective to the Cloud Manager.
    1. Login to the Cloud Manager: 
      https://<API_manager_hostname>/cmc
      where <API_manager_hostname> is the address of the API Manager.
    2. Click Services.
    3. Click Add > Add Collective, and enter a name for the collective.
    4. Click Create.
    5. Under the name of the API Connect collective that you added, click Add Controller and enter the controller name, IP address, port, user name, and password.
    6. Click Create.

Installing the collective member host

Install the collective member host.

Before you begin

The host on which you install the collective member must have an SSH daemon installed. You must be able to SSH into that host with the user name and password that are supplied to the wlpn-collective registerHost command by using the --rpcUser and --rpcPassword options; these options are separate from --user and --password, which are the credentials required to log in to the Admin Center.

You can install the collective member in any of the following ways:
  • From the public npm registry.
  • From a locally hosted IBM API Connect server.
  • From a locally downloaded .tgz file.

If you are installing the collective member locally from an IBM API Connect server or a downloaded .tgz file, you must first install a supported version of Node.js

For details of supported Node.js versions, follow the link on the IBM API Connect Version 5.0 requirements page to the IBM API Connect Software Product Compatibility Report for the API Connect offering you are using, then click the Prerequisites tab.

Node.js is available as part of the IBM SDK for Node.js.

About this task

Install a member host to host your applications and the Micro Gateway.
Note: Global installs with the npm install -g command might require root or administrator privileges and use of the --unsafe-perm parameter; the --unsafe-perm parameter applies only when you are using the sudo command.

Procedure

  1. Install the member host:
    • Install from the public npm registry:
      [sudo] npm install -g [--unsafe-perm] apiconnect-collective-member
    • Install from a locally hosted IBM API Connect server that was deployed from an OVA file with the OVF Tool: 
      [sudo] npm install -g [--unsafe-perm] https://<host>/packages/apiconnect-collective-member
      where <host> is the host name or IP address of the IBM API Connect OVA.
    • Install from a locally downloaded .tgz file:
      [sudo] npm install -g [--unsafe-perm] /<path>/apiconnect-collective-member-<platform>-<version>.tgz
  2. Register or update the host with the member:
    • If the member is hosted on a different host from the controller:
      wlpn-collective registerHost <HOSTNAME> --host=<name> --port=<num> --user=<name> --password=<pwd> [options]
    • If the member is hosted on the same host as the controller:
      wlpn-collective updateHost <HOSTNAME> --host=<name> --port=<num> --user=<name> --password=<pwd> [options]
    where:
    <HOSTNAME>
    Required. The hostname corresponds to the member host machine. The value for this field is either the host name or the IP address of the member machine.
    --host=<name>
    Required. The host name of the target collective controller.
    --port=<num>
    Required. The HTTPS port number of the target collective controller.
    --user=<name>
    Required. An Administrator user for the target collective controller. Required to log in to the Admin Center, and required to join members and host machines to the collective.
    --password=<pwd>
    Required. The password for the Administrator user for the target collective controller.
    --rpcHost=<name>
    Optional. The host on which the RPC or SSH mechanism is listening. Defaults to the hostName.
    --rpcPort=<num>
    Optional. The port on which the RPC or SSH mechanism is listening. Defaults to SSH port 22.
    --rpcUser=<name>
    Optional. The user with which to authenticate to the RPC or SSH mechanism. Defaults to the current operating system user.
    --rpcUserPassword=<pwd>
    Optional. The password for the rpcUser. The default is to use SSH key authentication. Set this value if SSH is not supported for the host. Use only one authentication option, rpcUserPassword or sshPrivateKey, not both.
    --sshPrivateKey=<path>
    Optional. The path to the SSH key to use to authenticate to the host. Defaults to a newly generated SSH key. Use only one authentication option, rpcUserPassword or sshPrivateKey, not both.
    --autoAcceptCertificates
    Optional. Automatically trust SSL certificates during this command.

    If you setup the controller with the wlpn-controller setup --password=password command without other parameters, the controller uses a self-signed certificate. Then, if you run the wlpn-collective updateHost without the --autoAcceptCertificates, you get an error.

What to do next

If you are installing the Professional offering on-premises with the Micro Gateway, next install the IBM HTTP Server server or servers for load balancing.

Preparing to install multiple collectives

For an APIC Liberty collective being configured for the first time, you can provide a unique name that distinguishes it from existing or future collectives. Otherwise, the identical default name is applied to each new collective that you create.

Before you begin

The following instructions are to be completed before you enter wlpn-controller start and prior to registering the members.

About this task

To configure a collective with a unique name, you must create a file containing the unique name.

Procedure

  1. From the CLI, change directories to collective by entering -- cd /root/.liberty/wlp/usr/servers/controller/resources/collective.
  2. Create a file named "collective.name" and add a string that contains your collective's unique name. You can enter this command to accomplish the step: echo "collective-<some-uniqueName>" > output; tr -d '\n' < output > collective.name
  3. Start the controller and then register the members.

Installing extra collectives to an existing installation

You can install extra collectives by creating a unique name to override the default collective name.

Before you begin

Ensure that the controller is started and functioning normally before you complete the steps.

About this task

Note: This task is to adjust an API Connect Liberty collective that is already configured and running, so that extra collectives can be created.

The apic-liberty-collective uses a default collective name called defaultCollective. To create more collectives, you must assign a unique name to each.

Procedure

  1. Change to the collective directory by entering cd /root/.liberty/wlp/usr/servers/controller/resources/collective.
  2. Create a file called "collective.name", add to a string (for example, collective-<some-uniqueName>) and then save the file. The string "collective-<some-uniqueName>" replaces the default collective name, which is "defaultCollective". Be sure to replace "<some-uniqueName>" with an appropriate unique name for the given collective. Create the file by entering echo "collective-<some-uniqueName>" > output; tr -d '\n' < output > collective.name
  3. Unregister the members.
  4. Restart the controller by entering wlpn-controller stop && wlpn-controller start.
  5. Register the members.
    Note: It takes several minutes before the members come into view.
  6. Restart the DataPower® On Demand Router (ODR).
    1. Go to the DataPower WebGUI under On Demand Router.
    2. Disable, and then Enable the On Demand Router to Apply the object during the restart.

What to do next

Accomplish the steps on one controller to validate it comes back online. When the odr-event log target is enabled, you see:
  • Before the change: '/cell/defaultCollective/node/<hostname>.......
  • After the change: '/cell/collective-<some_unique_name>/node/<hostname>......
When the first collective is updated and you validate it is running as expected, proceed to do the other collectives.