Adding Connector Designer to your deployment

You can add Connector Designer to your existing deployment of i2 Analyze. Connector Designer runs on a container and allows users to create connectors that can be used to access external data sources.

Before you begin

You do not have to install Connector Designer on the same servers as your i2 Analyze deployment, but it must be able to communicate with the Liberty servers in your deployment. When you install Connector Designer, a load balancer is configured to route traffic to the i2 Analyze deployment and to Connector Designer. Before you start the process, ensure that you have configured the DNS for the load balancer and that you have the required certificates for the load balancer and the Connector Designer server.

For more information about the network and security architecture of Connector Designer, see Connector Designer deployment architecture.

The prerequisites for Connector Designer are as follows:

  • x64 Linux

    • Connector Designer runs on a container and requires the Docker engine to be installed on an x64 Linux system.

  • Docker Engine

To add Connector Designer to your deployment, your existing deployment of i2 Analyze must be configured to use TLS when communicating with connectors. For more information, see Client-authenticated Transport Layer Security with the i2 Connect gateway

About this task

The following procedure describes how to add Connector Designer to your existing deployment of i2 Analyze. The process involves installing analyze-deployment-tooling which is used to install and run Connector Designer, configuring it to connect to your existing deployment, and configuring Connector Designer itself.

You can deploy Connector Designer in a development environment to let users create and test connectors before moving your Connector Designer configuration and connectors into your production environment.

Procedure

  1. Download the analyze-deployment-tooling.tar.gz artifact from analyze-deployment-tooling on GitHub.

  2. Open a terminal.

  3. Navigate to the directory where you copied the downloaded file.

  4. Extract the contents of the downloaded file.

    For example, tar -xzf analyze-deployment-tooling.tar.gz.

  5. Navigate to the analyze-deployment-tooling directory.

    For example, cd analyze-deployment-tooling.

  6. Download the i2 Analyze V4.4.4 Minimal for Linux.

  7. Rename the i2analyzeMinimal_4.4.4.tar.gz file to i2analyzeMinimal.tar.gz, then copy it to the analyze-deployment-tooling/pre-reqs directory.

  8. Run the following command to install Connector Designer:

    install-connector-designer

    When you are prompted, provide the following information:

    • The fully qualified domain name (FQDN) for the load balancer. For example, i2.my-organization.

      • This is the FQDN that users will use to access the i2 Analyze application via the load balancer that is configured as part of installing and running Connector Designer. You must use the common name of the certificate that you are using for the load balancer.

    • Enter the port for the application on the load balancer. For example, 9443.

    • The context root of your i2 Analyze application. By default this is opal.

    • The URLs of the Liberty servers in your i2 Analyze deployment. For example https://liberty1:9082,https://liberty2:9082.

  9. Accept the license agreement.

    1. Read the notices file in analyze-deployment-tooling/licenses/connector-designer/NOTICES.

    2. If you agree to the terms, open the analyze-deployment-tooling/licenses.conf file and set LIC_AGREEMENT=ACCEPT and save the file.

  10. To configure the TLS connection between the Connector Designer server and your existing i2 Analyze deployment, you must provide Connector Designer with the CA trust certificate for certificates that are received from Liberty. The certificate must be in PEM format and the certificate must be in the analyze-deployment-tooling/environment-secrets/generated-secrets/certificates/externalCA/CA.cer file. Overwrite the existing CA.cer file with your certificate.

  11. You must obtain a signed certificate for the machine where you are deploying Connector Designer. You must provide the certificate and private key in the environment-secrets/generated-secrets/certificates/i2analyze/server.key and environment-secrets/generated-secrets/certificates/i2analyze/server.cer files. Overwrite the existing server.key and server.cer files with your own.

The following steps must be completed in your i2 Analyze configuration:

  1. Configuring JWT authentication.

    1. Copy the jwt-key.p12 and jwt-trust.p12 files from the environment-secrets/generated-secrets/certificates/jwt directory to your i2 Analyze deployment.

    2. Configure Liberty to use JWT tokens to allow authenticated users to access Connector Designer. For more information, see Configuring JWT authentication.

    • For the jwtKeyStore and jwtTrustStore elements, use the location of the jwt-key.p12 and jwt-trust.p12 files that you copied.

    • For the jwtKeyStore and jwtTrustStore elements, use the password in the environment-secrets/generated-secrets/certificates/jwt/jwt_PASSWORD file.

    • For the Issue=<i2-analyze-url> attributes, use the FQDN and port of the load balancer specified when you installed connector designer. For example, https://acme:9443.

  2. In the i2 Analyze configuration, specify the Connector Designer configuration endpoint. In an XML editor, open the configuration/environment/topology.xml file and add the following element:

    <connector-config-providers>
    <connector-config-provider url="https://<fqdn>:<port>/connector-designer/api/configuration/connectors"/>
</connector-config-providers>

    • Where <fqdn> is the FQDN of the load balancer and <port> is the port number that you specified when you installed Connector Designer. For example, https://i2.my-organization:9443.

  3. The system requires an administrator user to be available that can access the i2 Analyze application. The user has the name adt-admin and be a member of the Administrator group. The password for the users is in the environment-secrets/generated-secrets/simulated-secret-store/adt-admin-password file.

  4. Configure i2 Analyze for connection to Connector Designer:

    1. Edit the i2analyze/deploy/wlp/usr/servers/opal-server/jvm.options file to add the following line:

      -DBASIC_AUTH_ENDPOINTS=/api/v1/metrics /api/v1/gateway/reload /api/v1/health/live /api/v1/admin/*

    2. Add the adt-admin user and adt-admin-group to the i2analyze/deploy/wlp/usr/shared/config/user.registry.xml file:

      <user name="adt-admin" password="<password>"/>
<group name="adt-admin-group">
<member name="adt-admin"/>
</group>

      • Where <password> is the password in the analyze-deployment-tooling/environment-secrets/generated-secrets/application/admin_PASSWORD file where you installed Connector Designer.

    3. Update the command access control file:

      <CommandAccessPermissions UserGroup="adt-admin-group">
    <Permission Value="i2:Administrator" />
</CommandAccessPermissions>

    4. After you make these changes, redeploy and restart i2 Analyze. In a command prompt, navigate to the toolkit/scripts directory and run the following commands:

      ./setup -t deploy
./setup -t start

  5. On the Connector Designer server, run the following command to start Connector Designer:

    ./scripts/deploy

  6. To access the system, the machine that you are connecting from must trust the certificate that it receives from the load balancer. If the machine does not already trust the certificates. Install the /environment-secrets/generated-secrets/certificates/externalCA/CA.cer certificate as a trusted root certificate authority in your browser and operating system's certificate store.

    For information about installing the certificate, see:

To connect to Connector Designer, log in to your deployment in a web browser at https://<fqdn>:<port_number>/<context_root>. For example, https://i2.my-organization:9443/opal.

Then, navigate to https://<fqdn>:<port_number>/connector-designer/connectors. For example, https://i2.my-organization:9443/connector-designer/connectors.

Configuring Connector Designer

  1. To allow connectors to access external data sources, you must specify the allowed hosts in the analyze-deployment-tooling/configs/con-des-default/configuration/connector-designer/allow-list.txt file. You specify the allowed hosts in the file, one host per line. For example:

    https://example.com
https://example2.com

  2. An endpoint or database might require an TLS connection. You can specify the trust certificates that the connectors can use.

    The certificate must be in PEM format and the content of the certificate must be added to the con-des-default/configuration/secrets/additional-trust-certificates.cer file.

  3. To configure the size of the Connector Designer container, for example the number of CPUs or available memory, edit the analyze-deployment-tooling/runtime-environments/runtime-default.properties file. For more information, see Configuring runtime environments.

  4. To update Connector Designer with your changes, run:

    ./scripts/deploy

What to do next

To configure custom authentication methods for connectors to connect to external sources, see Configuring custom functions in Connector Designer.

If you need to change the values that you provided to the installation script, you can re-run the installation script. The script will prompt you to provide the values again.

Other commands that you can run are:

To stop Connector Designer, run:

./scripts/manage-environment -t stop

To restart Connector Designer, run:

./scripts/deploy

To repair or update Connector Designer, re-run the installation script:

./install-connector-designer.sh