Configuring an integration server to connect to an IBM App Connect Dashboard

Configure an integration server to connect to an IBM® App Connect Dashboard.

About this task

If you start an integration node, you can visualize the managed integration servers in the dashboard by creating a connection to the integration node from the dashboard. The only way that you can visualize a managed integration server in the dashboard is by creating a connection to the integration node in the dashboard.

If you start an independent integration server, you can visualize it in the dashboard by creating a connection to it from the dashboard.

If you configure an independent integration server with an agentA configuration file for a switch, it registers with the switch. Then, you can create a connection to the switch in the dashboard to visualize the independent integration server.

If you configure an independent integration server with an agentA configuration file, other users who can download the agentA file from the switch server can perform remote administration on your integration server from an IBM App Connect Dashboard. Any users and roles that are created for securing the administrative RESTAPI, are not applicable to remote administration with an agentA file. For more information, see Managing resources by using the administration REST API.

As shown in the diagram, if multiple integration servers are connected to a single switch server, remote administration can be performed on the connected integration servers from an IBM App Connect Dashboard. In this example, access for users A and B is controlled separately through the administration REST API of the respective Integration Servers. However, user C can perform remote administration on both integration servers by using the switch server and the agentA configuration file.

The diagram shows two integration servers and three users. User A has access to one of the integration servers, and user B has the access to the other integration server. The access for users A and B is controlled separately through the administration REST API of the respective Integration Servers. However, user C can perform remote administration on both integration servers by using the switch server and the agentA configuration file.

You cannot configure an integration node with an agentA configuration file. You can configure only independent servers with an agentA configuration file.

Procedure

If an integration server has a publicly accessible end point, you can connect directly to it from the IBM App Connect Dashboard, as described in step 1.

If an integration server is behind a firewall, you must configure the integration server with an agentA file, and then connect to it from the IBM App Connect Dashboard by using a switch server. You can obtain an agentA file by using a managed service, or by creating a switch operand in IBM Cloud Pak for Integration, as described in step 2.

If you want to connect to an integration server that is running on a container, you must also configure it with an agentA file.

  1. Connect directly to an integration server that has a publicly accessible end point, as described in Creating connections in an IBM App Connect Dashboard.

If you configure an independent integration server with an agentA configuration file for a switch, it registers with the switch. Then, you can create a connection to the switch in the dashboard to visualize the independent integration server.

  1. Configure the integration server with an agentA file by using a managed service, as described in substep a, or by creating a SwitchServer operand in IBM App Connect Operator, as described in substep b.

    As an alternative to configuring an integration server with an agentA file agenta.json, you can configure it with a server client file serverclient.json, as described in substep c.

    1. Configure the integration server with an agentA file by using a managed service by completing the following steps:
      1. Download the agentA file by completing the following steps:
        1. If you have not created an App Connect Agent, click New on the Private Network Connections tab in App Connect, and then click App Connect Agent.
        2. On the Actions menu for the App Connect Agent, select View setup instructions to open a window in which the instructions are displayed.
        3. Download the configuration by clicking the button under step 2 of the instructions, which are displayed in the window, which you opened in step 2.
      2. Copy the downloaded agenta.json configuration file to the directory --work-dir/config/iibswitch/agenta, where --work-dir is the work directory that you specified when you created the integration server. You might need to create the agenta directory at the same level as the agentx directory that is there by default. You cannot configure agenta and agentx on the same integration server.
    2. Create an agentA file as described in App Connect Switch Server reference. Then, configure the integration server with the agentA file by creating a SwitchServer operand in IBM App Connect Operator version 1.0.0 or later (operand 11.0.0.10-r3-eus) by running the following commands. The parameter values that are shown are examples only.
      1. oc get Configuration my-switch-agenta -o=jsonpath={.spec.secretName} my-switch-agenta
      2. oc get secret my-switch-agenta -o=jsonpath={.data.configuration} eyJuYW1lIjoiYWdlbnRhIiwic3dpdGNoIjp7InVybCI6IndzczovL21hcnRpbi1zcy1zd2l0Y2gtYWNlLW1hcnRpb ... 0tLVxuIl0sInJlamVjdFVuYXV0aG9yaXplZCI6dHJ1ZX19fQ==
      3. oc get secret my-switch-agenta -o=jsonpath={.data.configuration} | base64 -d | jq
        The output from running the commands is similar to the following example:
        
{
  "name": "agenta",
  "switch": {
    "url": "wss://example.ibm.com:443",
    "certs": {
      "key": "-----BEGIN PRIVATE KEY-----\nMIIEvwIBADANBgk ... bNo12hvjjI2NJBwVIA==\n-----END PRIVATE KEY-----\n",
      "cert": "-----BEGIN CERTIFICATE-----\nMIID8jCCAtqgAwIB ... Zu/Ep+k/\n-----END CERTIFICATE-----\n",
      "ca": [
        "-----BEGIN CERTIFICATE-----\nMIIEXjCCA0agA ... HpL0V1+U7xrajhpjh+tbTmD6\n-----END CERTIFICATE-----\n"
      ],
      "rejectUnauthorized": true
    }
  }
}
      4. Save the output to a local file, for example, /my/work/dir/config/iibswitch/agenta/agenta.json.
      5. Edit /my/work/dir/config/iibswitch/agenta/agenta.json by adding an agentID field at the same level as the name field.

        Alternatively, you can set the MQSI_AGENT_ID environment variable in the environment for the independent integration server.

        The value for agentID must be a uuidv4 string.
        The following example shows an agenta.json file that was edited to add an agentID field that is populated with a uuidv4 string. 
        
{
  "name": "agenta",
  "agentId": "7690095b-3db8-40d2-8584-d09335a0dab9"
  "switch": {
    "url": "wss://example.ibm.com:443",
    "certs": {
      "key": "-----BEGIN PRIVATE KEY-----\nMIIEvwIBADANBgk ... bNo12hvjjI2NJBwVIA==\n-----END PRIVATE KEY-----\n",
      "cert": "-----BEGIN CERTIFICATE-----\nMIID8jCCAtqgAwIB ... Zu/Ep+k/\n-----END CERTIFICATE-----\n",
      "ca": [
        "-----BEGIN CERTIFICATE-----\nMIIEXjCCA0agA ... HpL0V1+U7xrajhpjh+tbTmD6\n-----END CERTIFICATE-----\n"
      ],
      "rejectUnauthorized": true
    }
  }
}
      6. Copy the edited agenta.json configuration file to the directory --work-dir/config/iibswitch/agenta, where --work-dir is the work directory that you specified when you created the integration server. You might need to create the agenta directory at the same level as the agentx directory that is there by default. You cannot configure agenta and agentx on the same integration server.
    3. Configure the integration server with a server client file serverclient.json by setting its property admin to enabled, and setting its property callableFlows to enabled. The server client file must be copied to the directory --work-dir/config/switch.

What to do next

Create connections in an IBM App Connect Dashboard, as described Creating connections in an IBM App Connect Dashboard.