The IBM Bluemix Secure Gateway service allows connectivity from Bluemix applications to local/on-premise destinations. There are many excellent articles which cover this scenario, such as:
However, a lesser-known scenario is that it can also connect back from your on-premise system to cloud-based destinations. Although this may not be the primary motivation for using it in many scenarios, it can be very useful with restrictive on-premise networks which don’t allow outbound connectivity.
This blog post walks through a very simple example of setting up this
connectivity to connect to a public JSON-based service
(http://loripsum.net/api
). Although on your local test system, it is most
likely that direct connectivity to that endpoint is possible, in many
on-premise enterprise scenarios, that may not be so straightforward. This
Secure Gateway setup thus becomes one possible option. We will define a
Secure Gateway service, and use the Docker-based client, running locally on
your machine, to connect back to the Secure Gateway.
Prerequisites
You have signed up for IBM Bluemix (Public) and have an ID to log in with.
You have installed Docker locally on your machine.
Instructions for this tutorial are written assuming you are using OS X, although they can probably be adapted to other platforms fairly easily.
Define the Secure Gateway
In a browser in which you are logged in to Bluemix, navigate to the URL https://console.ng.bluemix.net/catalog/services/secure-gateway/. Click on “Create” to create the Secure Gateway service. Note: if you already have an instance of the Secure Gateway service in the space in which you are working, you will be unable to create a new one. You can use the existing instance of the service you have and simply create a new Gateway within it (navigate to the Secure Gateway Dashboard in the Bluemix interface). Note also that the Secure Gateway has a cost attached once you exceed a certain threshold of data. Please make sure you are comfortable with this restriction.
You will now be in the Secure Gateway Dashboard. At this point, click “Add Gateway”. Specify a name for the Gateway (e.g. “GatewayFromLocal”). For this simple tutorial, you can disable “Require security token to connect clients” and “Token Expiration”. Click “Add Gateway”. It will look like this:
Once you’ve created your Gateway, you’ll need to add the Client (the local Docker container which connects back from your machine to Bluemix). Locate the Gateway on the administration console (it will have a red X to show it is not yet connected). It will look like this:
Click on it.
Click on “Add Clients”. This will bring up a dialog with multiple connectivity options. Click on “Docker”. This will show the precise Docker command required to run the local Gateway client on your local machine. The dialog should look like this:
The identifier at the end of docker run
command is the ID of this
individual gateway.
You will need to modify the docker command to make sure that the port number we pick later on (called the “Client Port”) is mapped from the Docker container (which has a separate network, with a separate set of ports) to your host machine. Add a parameter like
-p 6655:6655
to your command (you can pick any number you want, although it’s recommended to be above 1024). It should look like this:docker run -p 6655:6655 -it ibmcom/secure-gateway-client vJOMUBbT9Ax_prod_ng
Run the docker run command locally on your machine. You should see output that looks a bit like this (your client ID will, of course, be different from the one shown).
IBM Bluemix Secure Gateway Client Version 1.6.0
************************************************************************************************
You are running the IBM Secure Gateway Client for Bluemix. When you enter the provided docker
command the IBM Secure Gateway Client for Bluemix automatically downloads as a Docker image and
is executed on your system/device. This is released under an IBM license. The license agreement
for IBM Secure Gateway Client for Bluemix is available at the following location:
http://www.ibm.com/software/sla/sladb.nsf/lilookup/986C7686F22D4D3585257E13004EA6CB?OpenDocument
Your use of the components of the package and dependencies constitutes your acceptance of this
license agreement. If you do not want to accept the license, immediately quit the container by
closing the terminal window or by entering 'quit' followed by the ENTER key. Then, delete any
pulled Docker image from your device.
For client documentation, please view the ReadMe located at:
.rpm and .deb installers: /opt/ibm/securegateway/docs/
.dmg installer: <installation location>/ibm/securegateway/docs/
.exe installer: <installation location>\Secure Gateway Client\ibm\securegateway\docs\
************************************************************************************************
<press enter for the command line>
[2016-10-25 04:57:37.944] [INFO] (Client ID 1) No password provided. The UI will not require a password for access
[2016-10-25 04:57:37.953] [WARN] (Client ID 1) UI Server started. The UI is not currently password protected
[2016-10-25 04:57:37.953] [INFO] (Client ID 1) Visit localhost:9003/dashboard to view the UI.
[2016-10-25 04:57:38.169] [INFO] (Client ID 11) Setting log level to INFO
[2016-10-25 04:57:39.249] [INFO] (Client ID 11) The Secure Gateway tunnel is connected
[2016-10-25 04:57:39.546] [INFO] (Client ID Hh2eUmsFUi2_u7U) Your Client ID is Hh2eUmsFUi2_u7U
Because you specified the
-it
flag to docker, the docker client will continue to run. Leave the window open so you can monitor the client easily. Very shortly afterward, the red cross against the Gateway in the Secure Gateway Dashboard should turn to green to show that the Docker client has successfully made a connection. If it does not, proceed no further and debug.Now, we’ll add a “Destination” for a Cloud-based service which we can invoke locally. From within the Gateway control panel, click on “Add destination”:
Click “Advanced Setup” and fill out the screen as shown. The “Client Port” is the port locally within the Docker container - choose the same number you chose earlier for the
docker run
command. Click on ‘Add Destination’:
(Occasionally I have found that the process of adding a destination can hang at this point. If this happens, refresh the page - you will probably see that the destination has not been added to the gateway. Then, add the destination again, using the same details, but select “TCP” as the type. Once it is created, go in and edit the details, changing the type to “HTTP”. This should work).
If the destination is successfully created, you should see a message that looks like this:
[2016-10-25 05:19:55.346] [INFO] (Client ID Hh2eUmsFUi2_u7U) Creating TCP server for reverse connections. Listening on port 6655
You can now test this. Open a browser to the URL http://loripsum.net/api. You should see some pseudo-HTML containing some Lorem Ipsum text. Your network may allow this directly, depending on your proxy settings, but of course this scenario is most useful when this direct connectivity is not possible!
Now, open a browser to http://localhost:6655/api. You should see exactly the same result. This means that your browser is connecting through your local Docker client, across the Secure Gateway, and out onto the public internet endpoint. Even though in this case your network may allow direct connectivity to the original endpoint, this illustrates the values of the Secure Gateway in “bridging” connectivity.
Addenda
Any questions or comments, contact me at andrew DOT ferrier AT uk DOT ibm DOT com.