Step 1: Create a Satellite Connector

Creating a Satellite Connector is the first step in establishing a connection.

1. From Satellite console{: external}, click Create connector.

2. Enter a unique name for your Connector. The default value is connector.

3. (Optional) Enter one or more tags that can help you organize resources throughout your account by filtering by tags from your resource list.

4. Assign a resource group to your connector. The default value is Default.

5. (Optional) Describe what this Connector is used for.

6. For Managed from, select Dallas.

7. In the Summary panel, review your order details, and then click Create connector.

   You might see an error after you create the connector. You can ignore this error and proceed.

Under the list of Connectors, you can see the connector that you created. You might need to click Refresh to update the list of connectors

Step 2: Create user endpoint

After you create a connector, you must set up an agent.

1. Click the connector that you created.

2. Copy the connector ID for use later.

3. Click Create endpoint.

4. Click Agent location and click Next.

5. Enter the following Resource details and click Next:

   • A name for the endpoint

   • Destination FQDN or IP - enter w.ibm.com in this field.

   • Destination port - enter 443 in this field,

6. On the Protocol tab, enter TLS in the Source protocol field and click Next.

7. On the Connection settings tab, set the inactivity timeout to 600 and click Create endpoint.

8. You can now see the newly created endpoint. Click the endpoint to copy the Endpoint address.

   This endpoint address is the cloud endpoint to access the on-premises service (such as Cognos Analytics) and is required later.

Step 3: Create a service ID

1. Go to Access (IAM) from your Cloud account or from the Navigation menu in watsonx BI.

2. Under Service IDs, click Create service ID.

3. Enter a name for the service ID.

4. Under API keys, click Create to create API keys for this service ID.

5. Enter the following information and click Create.

   a. Enter a name for the API key.

   b. In the Leaked action field, select Disable the leaked key.

6. Download the API key file for use later. This API key is used by the Connector agent.

Step 4: Install agent

Each Satellite Connector needs at least one agent that is running on the remote location to establish a secure connection to a data source. You can install the agent as a Docker image.

Make sure that your machine has docker or snap install docker.

1. Run the installation command to install ibmcloud CLI.

   Curl -fsSL https://clis.cloud.ibm.com/install/linux | sh

2. After you install the ibmcloud CLI, use the following plug-ins:

   ibmcloud plugin install ks
   

   ibmcloud plugin install cr
   

3. Download oc client on local from https://mirror.openshift.com/pub/openshift-v4/clients/ocp/4.10.8/.

   scp openshift-client-linux.tar.gz root@epmsatelliteagent1.fyre.ibm.com:/tmp
   

4. Extract file openshift-client-linux.tar.gz.

   tar zxvf /tmp/openshift-client-linux.tar.gz
   

5. Move oc and kubectl into user/bin directory

   mv oc /usr/bin
   mv kubectl /usr/bin
   

6. Create two configuration files in the following file structure:

   • /root/agent/env-files
   • env.txt

7. The agent configuration file (env.txt) has the following parameters:

   SATELLITE_CONNECTOR_ID
   SATELLITE_CONNECTOR_IAM_APIKEY
   SATELLITE_CONNECTOR_REGIONh 
   SATELLITE_CONNECTOR_TAGS
   

   Configuration file parameters

   Parameter	Required	Description
   SATELLITE_CONNECTOR_IAM_APIKEY	Y	Your service ID API key. For security purposes, the API key is stored in a file named apikey. Set this parameter to the location of the apikey file. For example, SATELLITE_CONNECTOR_IAM_APIKEY=/agent-env-files/apikey
   SATELLITE_CONNECTOR_ID	Y	The ID of the Satellite Connector that the agent is bound to.
   SATELLITE_CONNECTOR_TAGS	N	A string that identifies your agent. This string can be any value that you find useful.
   SATELLITE_CONNECTOR_REGION	Y	Specifies the region for the nearest Satellite Connector data center. For watsonx BI, the valid SATELLITE_CONNECTOR_REGION value is: us-south Dallas, TX, USA

8. Pull the agent image by logging in to IBM Cloud® Container Registry or to the repository directly from Docker with your API key.

   ibmcloud cr region-set icr.io
   

   docker login -u iamapikey -p <your apikey> icr.io
   

9. Pull the latest version of the published image.

   dockers pull icr.io/ibm/satellite-connector/satellite-connector-agent:latest

10. Run the agent image by viewing the available versions of the agent image:

    ibmcloud cr images --include-ibm |egrep -i "tag|satellite"
    

11. Start Docker.

      docker run -d --env-file ~/agent/env-files/env.txt -v ~/agent/env-files:/agent-env-files icr.io/ibm/satellite-connector/satellite-connector-agent:latest
    

12. Verify that the tunnel gets established to your Connector by looking at the logs of the container.

    docker logs CONTAINER-ID
    

13. Stop Docker.

    docker stop CONTAINER-ID
    

Step 5: Verify agent running state

1. Go to Satellite - IBM Cloud and click Connectors.

2. Select the connector that you created earlier.

   Under Active agents, you now see the agent that is running.

3. Go to User endpoints to check the endpoint details.

   You can also verify through the https://cloud.ibm.com/shell console. Enter:

   curl https://c-01.private.us-south.link.satellite.cloud.ibm.com:34115/epm/app-dev/bi/v1/disp
   

If you're connecting to Cognos Analytics on Premises and the response contains developer.cognos.com, it indicates that the request to the private endpoint reached your watsonx BI account.

Step 6: Invite users to your project

You can now invite other users to your project. All users in the project can then create a connection to Cognos Analytics to import their FM packages and data modules.

For more information, see Adding collaborators to a project.