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.
- Git for working with Kinvey repositories
- NodeJS v6.x and NPM (node package manager). We recommend installing NodeJS and NPM using NVM.
- A FlexService which includes the latest flex-sdk module (a sample service is available in the FlexServices Guide.
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
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.
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.
- Log into the Management Console and select an environment
- Select the 'Service Catalog' tab
- Click 'Add a Service'
- Select 'Internal' under 'Flex' (on the right-hand side)
- Complete the required Service fields (name, description, and a secret key of your choice)
- Click 'Save Service'
- The newly-created Internal Flex Service should be visible in your Service Catalog
kinvey config. When prompted, choose the Flex Service created above.
configcommand takes an optional
[instance]parameter in order to deploy FlexServices to dedicated instances of Kinvey. For more information, run
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
https_proxyfor routing commands through a 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.
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.
kinvey job(with no arguments)
To check the health of your FlexService (after a deploy or any other time), run:
|The configured FlexService has not been deployed to|
|Service is in the process of deploying, updating, or scaling|
|Error starting one (but likely every) instance of your service. Check |
|Service instances have been started on the FlexService Runtime and are responding to pings|
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.
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 recycleis downtime-prone. Your service(s) will be unavailable anywhere from a few seconds to a few minutes while the operation completes
kinvey recycle returns a job ID. After the recycle operation completes you can observe the state of your cluster as it restarts via
The output of any
console.error statements in your service can be accessed with the Kinvey CLI
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'); abc console.log('Service initialization complete');
Following deploy, logs for the above service would contain:
flex.loggermodule supports DEBUG, INFO, WARNING, and FATAL logging thresholds. See the Flex Services Guide for examples
FlexService Runtime containers are based on Ubuntu (LTS) and run NodeJS version 6.9.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.9.1 changelog.
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 installis executed with the ‘--production’ flag when services are deployed to the FlexService Runtime. Any contents within the
devDependenciessection of your package.json file will not be installed
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.
Before attempting to deploy a service you should run it locally (
node .) to verify that it is free of startup errors.
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
onGetByIdevent in your service)
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.