Useful Tips

Here are some useful tips to prevent some common user configuration issues.

  1. All the Host machines in the collective and the machines where you publish application using the APIC Toolkit must have the same architecture, OS, node version and npm versions.

      Examples of not to have

    • APIC Toolkit installed on a windows machine while your collectives are on Linux .
    • Controller installed on zLinux and APIC Toolkit on windows
    • Controller Host has Node 4.x but member Host machine has Node 0.12.x.
    • Collective does not support windows.
    • To find out software requirements for specific apiconnect version:

  2. Make sure the controllers, members can communicate to each other.
    When perform the setup , always use Fully qualified host name. In some environment
    with dynamic IP, IP will change, therefore IP is not reliable to use.
  3. In production, the goal is to avoid single point of failure.

    The collective members should be on a separate machine as your controller.
    You should have more than one members and each one should be on separate machine.
    If you want High Availability, (HA), you should have at least 3 controllers, each installed on a different machine. That is a liberty ND solution. Currently, we do not support HA.

  4. If you update the password of any memberH ost machines, you need to
    perform updateHost so that the controller is aware of the changes.
  5. Increase Heap space for the controller
    Add -Xmx4096m or whatever appropriate values in jvm.options under .liberty/wlp/usr/servers/controller
  6. Publishing application from APIC Toolkit command line.

    • Before you publish, verify that your application is installed and started correctly without any errors.
      Try apic start to start the application and then apic stop to stop the application
    • use apic apps:publish -h to find out more information.
    • Only allow to perform publish once per application. – republish is not supported
    • To set the scale of the service deployed on APIConnect collectives, use –scale
      apic apps:publish –scale scalenumber
  7. Utilize the Help commands
    • apic apps:publish –h
    • wlpn-controller help
    • wlpn-controller help setup
    • wlpn-collective help
    • wlpn-collective help registerHost
    • wlpn-collective help updateHost
  8. Logging

    Enable the tracing in server.xml in ~/.liberty/wlp/usr/servers/controller/

    <logging traceSpecification="com.ibm.ws.collective.command.internal.*=all:Scaling=all:com.ibm.ws.imf.
    *=all:com.ibm.ws.collective.deploy.*=all:com.ibm.ws.scaling.manager.stack.internal.*=all" />

  9. Ports information:
    • Default controller adminCenter https port: 9443
    • To locate the application port information,
      get the join.json in wlpn folder from the member Host machine
      [root@host ~]#wlpn-server list
      The following servers are defined relative to the user directory /root/wlpn
      acme-bank-5844d8e1e4b056adb47d967d-1480907129282-1
      acme-bank-5844d8e1e4b056adb47d967d-1480907129282-2

      [root@host ~]# cat wlpn/acme-bank-5844d8e1e4b056adb47d967d-1480907129282-1/join.json
      {
      "hostName": "host.ibm.com",
      "userDir": "/root/wlpn",
      "serverName": "acme-bank-5844d8e1e4b056adb47d967d-1480907129282-1",
      "keystorePassword": "{xor}a2sINTIQGTAGGBlvKBsobSZuJzU9PmYFEmcaYg==",
      "controllerList": [
      "https://host.ibm.com:9443"
      ],
      "clusterName": "apic.acme-bank-5844d8e1e4b056adb47d967d-1480907129282",
      "appPort": "9081",
      "adminPort": "9444"

    • Refrain from manually modify the ports
  10. When your collective is totally messed up and you want to start over.

    Note: If you have other java or node process running, you need to looks for specific process id to terminate.

      To scrap controller java process and meta-data from controller machine

    1. killall -9 java
    2. rm -R ~/.liberty
    3. npm uninstall -g apiconnect-collective-controller
      To scrap the member processes and meta-data from member machine

    1. killall -9 node
    2. rm -R ~/wlpn
    3. npm uninstall -g apiconnect-collective-member

Prior to contact support

Before contacting support, validate your configuration by using the wlpn-diagnostic tools

Install the diagnostic tools on the controller machine.
npm install –g wlpn-diagnostics
wlpn-diagnostics checkAll

Information to provide when contact support

  • Versions of the Products and and environment
    apic --ext-version
    wlpn –ext-version
    wlpn-controller version
    node –v
    npm –v
  • Where did you install the Toolkit and collective member code from?
    npmjs.org or From fix-central
  • Topology on your environment

    • OS/architecture of the controller, member , APIC toolkit machines
    • How many Remote members or local members?
    • How many controllers?
  • Reproducible Steps. How often is the failure? Has it ever worked before? When does the failure start to to occur?
  • Logs:

    • Controller machine server logs location:
      ~/.liberty/wlp/usr/servers/controller/logs
    • apic log location:
      ~/.apiconnect/apic.log
    • controller server dump:

      .liberty/wlp/bin/server dump controller
      Dumping server controller.
      Server controller dump complete in /root/.liberty/wlp/usr/servers/controller/controller.dump-16.12.07_17.36.51.zip.
    • configuration settings of your controller and server machines

      ulimit -a
    • The /etc/security/limit.config
    • wlpn-diagnostics information

Useful References:

removing application from collective
logging microgateways and apic

Join The Discussion

Your email address will not be published. Required fields are marked *