FlexService Runtime

The FlexService Runtime is a node.js serverless runtime environment for Kinvey FlexServices. FlexServices are low-code microservices that can be used for data integrations (FlexData) or for executing business logic (FlexFunctions).

This guide covers the creation of FlexServices as well as deploying to and working with the Microservice Runtime.


  1. Git for working with Kinvey repositories
  2. NodeJS v6.x and NPM (node package manager). We recommend installing NodeJS and NPM using NVM.
  3. A FlexService which includes the latest flex-sdk module (a sample service is available in the FlexServices Guide).

Installing the Kinvey CLI

kinvey-cli is a NodeJS command line utility used for deploying, managing, and viewing logs for FlexServices running on the FlexService Runtime. To install, run:

$ npm install -g kinvey-cli

To verify installation and see a list of available commands, run:

$ kinvey -h

Creating a FlexService

The Kinvey Flex SDK emits events within your node service when Collection data is requested from your Kinvey app. These events are paired with user-defined handlers that fetch and transform data (from any number of sources) into Kinvey collections. The Flex SDK also includes modules for interacting with other Kinvey APIs (such as push notifications, email, collections access, and more).

Use the Flex SDK to write your FlexServices. For more information on how to use it and API documentation, see the FlexServices Guide.

Initializing Your FlexService

Before you can deploy your local NodeJS service to the FlexService Runtime you must provision an Internal Flex Service in the Kinvey Console and configure the Kinvey CLI to target this service.

Provisioning an Internal Flex Service

  1. Log into the Management Console and select an environment
  2. Select the 'Service Catalog' tab
  3. Click 'Add a Service'
  4. Select 'Internal' under 'Flex' (on the right-hand side)
  5. Complete the required Service fields (name, description, and a secret key of your choice)
  6. Click 'Save Service'
  7. The newly-created Internal Flex Service should be visible in your Service Catalog

Securing your FlexService

Communication to FlexServices running on FSR are encrypted by default. For FlexServices running outside of FSR, Kinvey recommends using HTTPS only to ensure all traffic is encrypted between Kinvey and the FlexService. In addition, FlexServices can be secured by use of a Shared Secret.

FlexServices (both internal and external) use a shared secret to permit or deny access to a FlexService. All requests to a FlexService from Kinvey include the shared secret, to prevent unauthorized access to the Flex Service. When configuring your Service in the Kinvey Console, enter in a secure, random, strong shared secret (256-bit minimum recommended).

To enable the shared secret within your service, pass the shared secret into the Flex Service initialization method:

sdk.service({ sharedSecret: <my shared secret> }, (err, flex)) => {
    // service code

If the shared secret is enabled in the Flex Service, the service will reject any request that does not include the shared secret key.

Configuring the Kinvey CLI

Run kinvey config. When prompted, choose the Flex Service created above.

Using a dedicated Kinvey instance? The config command takes an optional [instance] parameter in order to deploy FlexServices to dedicated instances of Kinvey. For more information, run kinvey -h

When configuring (or running any other commands in) the Kinvey CLI you will be prompted for your Kinvey credentials if you haven't logged in yet. These are the same credentials used when logging in to the Kinvey Console. Kinvey CLI sessions and Flex Service settings can be cleared at any time via kinvey logout.

Kinvey CLI has a default 5 seconds request timeout when communicating with the backend for configuration. In some rare cases a ConnectionError may appear. In this case, retry the command before contacting Kinvey support.

The CLI supports universal HTTPS_PROXY/https_proxy ENV variables for routing commands through a custom proxy server. Please see the Kinvey CLI README for more information

Congratulations! With the Kinvey CLI fully-configured to use your Flex Service, you're now able to deploy to the FlexService Runtime.

Deploying FlexServices

The Kinvey CLI deploy command deploys preconfigured NodeJS services to the FlexService Runtime and starts them. This command must be run at the root of your FlexService:

$ cd my-kinvey-node-service
$ kinvey deploy

The same service cannot be deployed to the FlexService Runtime more than once. You must bump the version in package.json before re-deploying.

The deploy operation sends your service to Kinvey, processes it, and deploys it to the FlexService Runtime. This process can take up to several minutes depending on network conditions and other factors. Each deploy request returns an ID which can be used with the job command to check the status of a pending deploy.

Deploy command with status

The Kinvey CLI retains the ID of the most recent deploy job. You can retrieve it by running kinvey job (with no arguments)

Managing, Troubleshooting, and Terminating Failed Services

FlexService Runtime and IP Whitelisting

FlexServices running on the FlexService Runtime are assigned dynamic IPs for outbound requests. These IPs can change at any time, and therefore cannot be used as part of an IP whitelisting strategy for any external services that the FlexService interacts with. If IP Whitelisting is required, Kinvey provides an HTTP(S) Proxy Server that can be used for routing traffic.

Note This proxy is only available for multitenant Kinvey instances.

To use this proxy, the HTTP_PROXY and HTTPS_PROXY environment variables should be set at the top of your index.js file:

process.env.HTTP_PROXY = 'http://' + 'proxy url';
process.env.HTTPS_PROXY = 'http://' + 'proxy url';

Supported Proxy URLs

InstanceProxy URL
US Multitenant (kvy-us1)kvy-us1-proxy.kinvey.net:3128
US HIPAA-compliant instance (kvy-us2)kvy-us2-proxy.kinvey.net:3128
EU Multitenant (kvy-eu1)kvy-eu1-proxy.kinvey.net:3128

This solution only works for libraries and http modules that honor the HTTP_PROXY and HTTPS_PROXY environment variables (e.g. request). The proxy URLs can also be used with libraries that support specifying the http/https proxy as part of the library usage.

Service Health

To check the health of your FlexService (after a deploy or any other time), run:

kinvey status

Status command results

Status Result Chart

NEWThe configured FlexService has not been deployed to
UPDATINGService is in the process of deploying, updating, or scaling
ERRORError starting one (but likely every) instance of your service. Check kinvey logs for more information
ONLINEService instances have been started on the FlexService Runtime and are responding to pings

Recycling Failed Services

When your service(s) fail for any reason and cannot self-recover, terminate via process.exit with a zero or non-zero result. Terminated instances are replaced automatically.

The Kinvey CLI Recycle Command

In cases of catastrophic failure, FlexServices can be recycled by running kinvey recycle. This allows you to get your service(s) running once again until you're able to deploy an updated version.

kinvey recycle is downtime-prone. Your service(s) will be unavailable anywhere from a few seconds to a few minutes while the operation completes

Like deploy, kinvey recycle returns a job ID. After the recycle operation completes you can observe the state of your cluster as it restarts via kinvey status.


The output of any console.log or console.error statements in your service can be accessed with the Kinvey CLI logs command:

Logging output

In addition to being a valuable tool for monitoring deployed services, FlexService logs are useful for troubleshooting problematic services. The following is an example of a service index.js file with a startup error (ReferenceError):

console.log('Service initialization started');


console.log('Service initialization complete');

Following deploy, logs for the above service would contain:

Startup error

The Flex SDK flex.logger module supports DEBUG, INFO, WARNING, and FATAL logging thresholds. See the Flex Services Guide for examples

There is a limit of 100 MB to the size of the FlexService logs that are kept. When log entries exceed that size the oldest ones are deleted.



FlexService Runtime containers are based on Ubuntu (LTS) and run NodeJS version 6.11.1 with node-gyp support. Your services should be developed against this version of node. For more information on this version of NodeJS and its features, please refer to the official v6.11.1 changelog.

More on Deploys

The Deploy Process

After Kinvey services are deployed, package.json dependencies are installed via npm install. The service is started with node . . A file named index.js must exist at the root of your project in order for your service to successfully start post-deployment.

npm install is executed with the ‘--production’ flag when services are deployed to the FlexService Runtime. Any contents within the devDependencies section of your package.json file will not be installed

Updating Deployed Services

When you're ready to update a FlexService, re-run the deploy command at the root of your source directory. The FlexService Runtime uses a rolling-restart technique which helps to eliminate downtime during the upgrade process. A few old replicas will remain online until the new service has been completely and successfully deployed.

Testing FlexServices

Before attempting to deploy a service you should run it locally (node .) to verify that it is free of startup errors.

The Flex SDK exposes your configured service handlers on port 10001 when you start your service locally (node .). You can query and test your handlers by hitting various URLs in the following format: http://localhost:10001/:ServiceObjectName/1 (this would emit an onGetById event in your service)

Architectural Notes

Several containers are spawned per service during the FlexService deployment phase. Scaling is handled automatically and updates are performed in a rolling fashion in order to curb downtime. FlexServices run under heavily-restricted user accounts within their respective containers for security purposes. Security, updates, and maintenance are handled by Kinvey.

After a successful deploy operation, the FlexService Runtime will attempt to connect to your service(s) through the Flex SDK module. Services which fail or crash due to runtime errors are automatically restarted by a mechanism which times out after 30 failed connection attempts. The logs command can (and is likely to) yield several copies of the same startup error(s) when this occurs.

Got a question?