Cloud Platform as a Service

 View Only

Connecting your Code Engine applications to various backends using Satellite Connector

By Enrico Regge posted Tue April 09, 2024 02:53 PM


Written by
Simon Daniel Moser (
Distinguished Engineer, IBM Cloud Container Services (IKS, ROKS, Code Engine)

Jeremias Werner (
STSM - IBM Cloud Code Engine & Functions

Enrico Regge (
Architect - IBM Cloud Code Engine

Introduction and problem statement 

Code Engine is IBM Clouds premier Serverless Container Service, because it makes running a container in the cloud so easy and frees its users from much of the operational burden of maintaining and operating their own infrastructure.

But there is one feature that Code Engine customers have been constantly asking about, and that is connecting their Code Engine application, job or function to a “backend” that runs outside of Code Engine, and doing that over a private network connection.

Why is that a problem, you’re asking ? The technical explanation is that Code Engine is an IBM Cloud service that runs on IBMs Virtual Private Cloud Infrastructure, and because it is a managed service (otherwise, it would not be able to relief the customers from the burden of maintaining and operating their own infrastructure), the VPC network is owned and operated by the IBM Code Engine team. That means, usually if you want to connect from a VPC to (let’s say) another VPC, you’d define two VPE Gateways (one on the source VPC, and one on the target VPC), and you’d connect them up to let the data flow. But, given the Code Engine VPC is not owned by the customer who owns the application, and Code Engine cannot provide a way for a customer to define it’s own VPE in its VPC for security reason, a customer seems to be stuck when he wants to connect his app to someplace else. But is this really the case ? In this article, we’ll explain what you can do to overcome this issue. 

Connection Use Cases

Before we dive into solutions, let’s take a step back and look at three distinct connection use-cases that the Code Engine team has been getting requests for: 

  1. Connecting from Code Engine to e.g. a virtual machine in a different VPC (including using a direct link from that VPC to connect further on to an on-premise network or system)

  2. Connecting from Code Engine directly to a system outside of IBM Cloud (e.g. directly to a on-premise system)

  3. Connecting from Code Engine to a system in IBM Cloud classic infrastructure (e.g. a bare metal server)

Each of those use cases requires can theoretically be solved with the solution we are about to describe, but you should keep in mind that for some scenarios there might be more elegant solutions on the horizon, although not fully available at the time of writing of this blog post.


Let’s assume we’ll want to expose an API backend, that requires specialized hardware and is therefore deployed on VPC virtual machines. Instead of exposing such an API directly, we’ll want to front it with an application deployed on Code Engine, which provides a secure and reliable HTTPs endpoint and adds advanced scaling and caching capabilities.

By default, Code Engine applications would not be able to reach the API backend, unless the backend is exposed to the public internet. Assuming we’ll only want to expose the API backend to some selected callers within the private IBM Cloud network, adding a Satellite Connector instance between the Code Engine component and the virtual machines is a viable solution. At a high-level, the request flow of such a setup looks as follows:

A Satellite what? IBM Cloud Satellite® provides a distributed cloud architecture that brings the scalability and flexibility of public cloud services to the applications and data that run in your secure private cloud. As such, it offers Satellite Connectors, which provide a secure and private connection, through TLS tunneling, between applications that need to communicate with hybrid and multi-cloud environments. If you are interested in learning more about the concept of Satellite Connectors, you’ll find useful information in our documentation page “Satellite Connector overview”.

Instead of establishing an HTTP outbound connection to the virtual machine directly, the Code Engine component calls the Satellite Connector tunnel server, which is exposed on a shared, regional endpoint, like “ Each connector instance allows to configure so called endpoints, which point to the FQDN, or the IP address and a specific port of the target destination, and tells the connector how to route traffic. Furthermore, each configured endpoint is represented by a unique port on the shared tunnel server endpoint, like “<endpoint-specific-port>”. 

Ok - So we just we just learned how an HTTP API backend can be connected. But does that work with a database backend that is exposed on TCP port XYZ? Yes, it does 🙂 Let’s take a look at the following high-level flow, which depicts the second concrete use case that we are exploring in this post:

Let’s assume you’ll want to crunch a large amount of data on a regular basis and also want to have some visualization through a web application on the results of such compute-intensive batch operation. Code Engine jobs are a perfect choice, if you require a large amount of capacity for some time, which will be released once the task is done, as you’ll only need to pay for the capacity and duration that you used it. Deploying a Code Engine app is a perfect choice, if you’ll want to run an HTTP server that automatically scales up or down (to zero) based on incoming requests. Enabling both, apps and jobs, to access backend services that are deployed in your virtual private cloud, is a great asset to many use cases.

Let’s see how this works in action 🚀 

We prepared a little script in our sample repository ( that will provision all needed resources within your IBM Cloud account to provide an end-to-end sample solution that covers the two use cases depicted in the flow charts above.

A word of warning: The script will create IBM Cloud resources that will cause usage and costs in your IBM Cloud account. The amount of the costs ultimately depends on the lifetime length of the example setup.

  • Clone or download the IBM Cloud Code Engine Sample repository
git clone
cd CodeEngine/satellite-connector-to-vpc-vsi
  • Login to your IBM Cloud account using the IBM Cloud CLI, like described in our documentation

ibmcloud login ...
  • Run the setup script, which will provision the entire setup


The script execution can take a bit. While we are waiting let’s take a look on the resources that are being created:

Code Engine components

Mainly, the script provisions three different components, representing the different types of workload that IBM Cloud Code Engine supports today.

  • Function - ideal for short running use cases that require low latency - acts as the HTTP proxy for the payload provided by the NGINX server (See Node.js source code)

  • Job - ideal for long-running, run-to-completion tasks that require a lot of resources for some time - connects to the PostgreSQL database and insert a record per submitted instance (See Node.js source code)

  • App - the swiss knife, which is ideal for all sorts of HTTP server use cases that need to scale efficiently - connects to the PostgreSQL database to query stored data and provide it as JSON payload on an HTTP endpoint (See Golang source code)

Satellite Connector

The Satellite Connector setup comprises of three components:

  • Instance - the IBM Cloud resource that provides a secure connection between a specific remote location and IBM Cloud. The instance allows to manage endpoints and access control list rules

  • Endpoint - Endpoints are either the FQDNs or the IP addresses of the resources being made available across Satellite Connector. The script will create two endpoints. One for the NGINX server, and one for the PostgreSQL database. As a result, both backend destinations are targeted through different ports on the same generic Connector tunnel server domain (e.g.

  • Agent - Running in the network of the destination to establish the connection. The script deploys the agent on a separate virtual machine within the same VPC subnet

VPC resources

The provisioned VPC infrastructure components, such as network ACLs, subnet, public gateway, security group, are essential and well-known for any VPC-based solution. Furthermore, a virtual machine that provides the compute power to run workload, which is a NGINX server and a PostgreSQL database in this scenario, has been created. 

Please note: Regardless of whether this solution pattern is being applied on IBM Cloud classic infrastructure or to connect your on-premise backends, the architecture and flow would look pretty similar. Basically, only the VPC portion would be replaced with corresponding infrastructure components, tailored to the needs of your backend.

Coming back to our script: Once it is has been finished, the output should look something like this:

Following commands can be used to further play around with the sample setup:
1. Submit another job run: 'ibmcloud ce jobrun submit --job friendship-book-writer --array-size 10'
2. Invoke the function: 'curl https://http-proxy-function.<your-id>.<region>'
3. Invoke the app: 'curl https://friendship-book-api.<your-id>.<region>'
4. Inspect the Satellite Connector configuration<some-unique-id>
5. Inspect the Code Engine project setup<region>/<some-unique-id>/overview
6. Tear down the sample setup: './run clean'


The Code Engine project details page, provides an overview on the running resources and their configuration. It can be found in the IBM Cloud console using following URL

The details page of each configured Connector endpoint provides information of the current traffic consumption, allowing operators to get sense on the utilization of a specific endpoint. Satellite Connector details can be found in the IBM Cloud console using following URL

Well, this is all that we’ve prepared for you as part of this blog post. We hope that it helps you to get an idea whether this solution applicable for your use cases. For further explorations, we suggest to take a look at the operational aspects (e.g. HA support) of hosting a Connector agent and to explore how ACL rules on the Connector endpoints can help to tighten the security aspects of the overall setup.

Before wrapping it up, please make sure to properly tear down the sample solution using the command shown below, to avoid unwanted costs in your account:

./run clean

Conclusion and outlook

That is it 🎉 🙌

In this blog post, we explored and verified a solution that uses Satellite Connectors to enable workload deployed on IBM Cloud Code Engine to connect to backends located within network segments that would otherwise hardly be reachable by Code Engine. While our concrete sample focusses on backends hosted on IBM Cloud VPC infrastructure, the same solution is applicable for IBM Cloud classic infrastructure and your on-premise environment, too. 

To give you an outlook on what else is coming: Specifically for connections into the IBM Cloud VPC, we are looking into how the upcoming Private Path services can be adopted by Code Engine to further simplify the user experience… we’ll tell you more about it, soon 🙂 

If you have feedback, suggestions, or questions about this post, please reach out to us on LinkedIn (,, or, or on StackOverflow by using one of the following tags “ibm-cloud” or “ibm-cloud-code-engine“.