This repository is part of the push2cloud project. For contribution guidelines, issues, and general documentation, visit the main push2cloud project page.
push2cloud-cf-adapter abstracts the cloud foundry api.
It's designed for use with Node.js and installable via npm install --save push2cloud-cf-adapter.
const cf = require('push2cloud-cf-adapter');
const api = cf({
api: process.env.CF_API ||Â 'https://api.lyra-836.appcloud.swisscom.com',
username: process.env.CF_USER,
password: process.env.CF_PWD,
org: process.env.CF_ORG,
space: process.env.CF_SPACE
});
// the callback way...
api.init((err, result) => {
api.pushApp({
name: 'temp-app',
path: '/path/to/sampleApp'
}, (err, app) => {
api.stageApp({
appGuid: app.metadata.guid
// or: name: 'temp-app'
}, (err) => {
api.startAppAndWaitForInstances({
appGuid: app.metadata.guid
// or: name: 'temp-app'
}, (err) => {
// ...
});
});
});
});
// or the promise way...
api.init()
.then((app) => {
return api.pushApp({
name: 'temp-app',
path: '/path/to/sampleApp'
});
})
.then((app) => {
return api.stageApp({
appGuid: app.metadata.guid
// or: name: 'temp-app'
});
})
.then(() => {
return api.startAppAndWaitForInstances({
appGuid: app.metadata.guid
// or: name: 'temp-app'
});
})
.then(() => {
// ...
});The source is available for download from GitHub. Alternatively, you can install using npm:
npm install --save push2cloud-cf-adapterYou can then require() push2cloud-cf-adapter as normal:
const cf = require('push2cloud-cf-adapter');Each asynchronous call can be done with classical callback style or with promise style.
createAppuploadApppushAppstageAppstartAppstopApprestartAppstartAppAndWaitForInstancesdeleteApp
General api methods.
Retrieves information of the current space. i.e. apps, services, service bindings, routes, domains, etc...
Arguments
callback(err, result)- A callback which is called when function has finished, or an error occurs.
Example
const cf = require('push2cloud-cf-adapter');
const api = cf({
api: 'https://the-url-to-the-cloud-foundry-api-endpoint',
username: 'my-funny-username',
password: 'my-very-secret-password',
org: 'the-cf-org',
space: 'the-cf-space',
rejectUnauthorized: true, // optional
maxRetries: 3, // optional
delay: 1000, // optional
delayFactor: 1 // optional
});
api.init((err, result) => {
console.log(result);
// {
// "apps": [
// {
// "name": "push2cloud-example-api-1.0.0",
// "unversionedName": "push2cloud-example-api",
// "guid": "cff85cc4-e217-47f0-b0e0-113d04e6e37d",
// "instances": 1,
// "memory": 512,
// "disk": 512,
// "state": "STARTED",
// "version": "1.0.0",
// "package_state": "STAGED"
// },
// {
// "name": "push2cloud-example-host-2.0.0",
// "unversionedName": "push2cloud-example-host",
// "guid": "9afc0b68-9004-4292-9284-6110bed72afb",
// "instances": 1,
// "memory": 512,
// "disk": 1024,
// "state": "STARTED",
// "version": "2.0.0",
// "package_state": "STAGED"
// }
// ],
// "serviceBindings": [
// {
// "service": "todo-db",
// "serviceInstanceGuid": "e0dc3f5e-7631-473e-ad3e-ebbf0549ad22",
// "app": "push2cloud-example-api-1.0.0",
// "unversionedName": "push2cloud-example-api",
// "appGuid": "cff85cc4-e217-47f0-b0e0-113d04e6e37d",
// "guid": "0d82e751-26ab-40b1-987a-8e1671b39c24"
// }
// ],
// "services": [
// {
// "name": "todo-db",
// "guid": "e0dc3f5e-7631-473e-ad3e-ebbf0549ad22",
// "type": "redis",
// "plan": "small"
// }
// ],
// "routes": [
// {
// "guid": "bd7cb2eb-f9fe-4b84-a7cd-1f43969e3ba9",
// "domain": "scapp.io",
// "domainGuid": "5f952bf2-618b-4584-b37e-92e406149285",
// "hostname": "push2cloud-example-host-iot-cf-test",
// "app": "push2cloud-example-host-2.0.0",
// "unversionedName": "push2cloud-example-host",
// "appGuid": "9afc0b68-9004-4292-9284-6110bed72afb"
// },
// {
// "guid": "47542223-1a74-45e9-8857-7baab1b29941",
// "domain": "scapp.io",
// "domainGuid": "5f952bf2-618b-4584-b37e-92e406149285",
// "hostname": "push2cloud-example-api-iot-cf-test",
// "app": "push2cloud-example-api-1.0.0",
// "unversionedName": "push2cloud-example-api",
// "appGuid": "cff85cc4-e217-47f0-b0e0-113d04e6e37d"
// }
// ],
// "envVars": [
// {
// "env": {
// "SYSTEM_VERSION": "1.0.0"
// },
// "name": "push2cloud-example-api-1.0.0",
// "unversionedName": "push2cloud-example-api"
// },
// {
// "env": {
// "SYSTEM_VERSION": "1.0.0",
// "PUSH2CLOUD_EXAMPLE_API_HOST": "https://push2cloud-example-api-iot-cf-test.scapp.io"
// },
// "name": "push2cloud-example-host-2.0.0",
// "unversionedName": "push2cloud-example-host"
// }
// ],
// "domains": [
// {
// "guid": "5f952bf2-618b-4584-b37e-92e406149285",
// "name": "scapp.io"
// },
// {
// "guid": "dc478cd0-5185-4a48-a964-1e53d868daf2",
// "name": "applicationcloud.io"
// }
// ]
// }
});Retrieves information of the cloud foundry platform.
Arguments
callback(err, result)- A callback which is called when function has finished, or an error occurs.
Example
api.getInfo((err, result) => {
console.log(result);
// {
// "name": "",
// "build": "",
// "support": "https://developer.swisscom.com/contact",
// "version": 0,
// "description": "Cloud Foundry provided by Swisscom",
// "authorization_endpoint": "https://login.lyra-836.appcloud.swisscom.com",
// "token_endpoint": "https://uaa.lyra-836.appcloud.swisscom.com",
// "min_cli_version": null,
// "min_recommended_cli_version": null,
// "api_version": "2.52.0",
// "app_ssh_endpoint": "ssh.lyra-836.appcloud.swisscom.com:2222",
// "app_ssh_host_key_fingerprint": "6d:d2:8c:09:64:b6:fc:2b:50:3c:a9:cb:2e:be:d4:a7",
// "app_ssh_oauth_client": "ssh-proxy",
// "logging_endpoint": "wss://loggregator.lyra-836.appcloud.swisscom.com:443",
// "doppler_logging_endpoint": "wss://doppler.lyra-836.appcloud.swisscom.com:443"
// }
});Will be emitted when an api request will retry.
Arguments
fn(obj)- A function which is called when an api request will retry.
Example
api.stats.on('retry', (obj) => {
console.log(obj);
// {
// "error": null,
// "response": { "statusCode": "500" /* rest of the response object */ },
// "result": {
// "code": 10011,
// "description": "Database error",
// "error_code": "CF-DatabaseError"
// },
// "attempt": 1,
// "infos": {
// "method": "POST",
// "uri": "/v2/service_instances",
// "json": {
// "name": "my-db",
// "space_guid": "7d8bf5be-a793-472b-8a84-78b04cc03864",
// "service_plan_guid": "0ad5b617-0a32-4a24-ba24-216f191ab9ef",
// "parameters": {},
// "tags": []
// },
// "qs": { "accepts_incomplete": true },
// "baseUrl": "https://api.lyra-836.appcloud.swisscom.com",
// "rejectUnauthorized": true,
// "headers": { "Authorization": "bearer eyJ..." }
// },
// "reason": "Database error"
// }
});You can attach you own retryHandler for your target.
Arguments
fn(options)- A function or an array of funcitons which is called to verify if the failed request should be retried. Should returntrueor astringto trigger a retry.
Examples
api.attachRetryHandler((options) => {
// const err = options.error;
// const response = options.response;
const result = options.result;
const infos = options.infos;
// const attempt = options.attempt;
if (infos.uri.indexOf('/service_bindings') >= 0) {
if (result && result.error_code && result.error_code === 'UnknownError') {
return result.description || 'An unknown error occurred';
}
}
if (infos.uri.indexOf('/service_instances') >= 0) {
if (result && result.code === 10011) {
return result.error_description;
}
}
});api.attachRetryHandler([
(options) => {
// const err = options.error;
// const response = options.response;
const result = options.result;
const infos = options.infos;
// const attempt = options.attempt;
if (infos.uri.indexOf('/service_bindings') >= 0) {
if (result && result.error_code && result.error_code === 'UnknownError') {
return result.description || 'An unknown error occurred';
}
}
},
(options) => {
// const err = options.error;
// const response = options.response;
const result = options.result;
const infos = options.infos;
// const attempt = options.attempt;
if (infos.uri.indexOf('/service_instances') >= 0) {
if (result && result.code === 10011) {
return result.error_description;
}
}
}
]);App related api methods.
Creates an app.
Arguments
options- An options containing:name- The app name.buildpack- Optional Buildpack to build the app. 3 options:- a) Blank or not set means autodetection.
- b) A Git Url pointing to a buildpack.
- c) Name of an installed buildpack.
command- Optional The command to start an app after it is staged, maximum length: 4096 (e.g. 'rails s -p $PORT' or 'java com.org.Server $PORT').env- Optional Object containing key/value pairs of all the environment variables to run in your app. Does not include any system or service variables.disk- Optional The maximum amount of disk available to an instance of an app. i.e. 256MB, 1G, 256, 1024memory- Optional The amount of memory each instance should have. i.e. 256MB, 1G, 256, 1024instances- Optional The number of instances of the app to run. To ensure optimal availability, ensure there are at least 2 instances.dockerImage- Optional Name of the Docker image containing the app.enableSSH- Optional Enable SSHing into the app. Supported for Diego only. false if SSH is disabled globally or on the space, true if enabled for bothhealthCheckType- Optional Type of health check to perform. 'port' or 'process'healthCheckTimeout- Optional Timeout for health checking of an staged app when starting up
callback(err, result)- A callback which is called when function has finished, or an error occurs.
Example
api.createApp({
name: 'temp-app'
}, (err, result) => {});Uploads an app.
Arguments
options- An options containing:appGuid- Optional The app guid.appGuidornameare mandatory but not both.name- Optional The app name.appGuidornameare mandatory but not both.path- The path to the app on your filesystem.tmpZipPath- Optional Custom temporary path to save the zip file. Default ispath+ '.zip.tmp'.
callback(err, result)- A callback which is called when function has finished, or an error occurs.
Example
api.uploadApp({
path: '/path/to/sampleApp'
}, (err, result) => {});Creates and uploads an app.
Arguments
options- See combinedoptionsargument ofcreateAppanduploadApp.callback(err, result)- A callback which is called when function has finished, or an error occurs.
Example
api.pushApp({
name: 'temp-app',
path: '/path/to/sampleApp'
}, (err, result) => {});Stages an app. Creates a droplet so the effective start of that app will be much faster.
Arguments
options- An options containing:appGuid- Optional The app guid.appGuidornameare mandatory but not both.name- Optional The app name.appGuidornameare mandatory but not both.stageTimeout- Optional Will return if staging duration is longer than that value in seconds. Default is 300.
callback(err, result)- A callback which is called when function has finished, or an error occurs.
Example
api.stageApp({
name: 'temp-app'
}, (err, result) => {});Starts an app.
Arguments
options- An options containing:appGuid- Optional The app guid.appGuidornameare mandatory but not both.name- Optional The app name.appGuidornameare mandatory but not both.
callback(err, result)- A callback which is called when function has finished, or an error occurs.
Example
api.startApp({
name: 'temp-app'
}, (err, result) => {});Stops an app.
Arguments
options- An options containing:appGuid- Optional The app guid.appGuidornameare mandatory but not both.name- Optional The app name.appGuidornameare mandatory but not both.
callback(err, result)- A callback which is called when function has finished, or an error occurs.
Example
api.stopApp({
name: 'temp-app'
}, (err, result) => {});Restarts an app.
Arguments
options- An options containing:appGuid- Optional The app guid.appGuidornameare mandatory but not both.name- Optional The app name.appGuidornameare mandatory but not both.
callback(err, result)- A callback which is called when function has finished, or an error occurs.
Example
api.restartApp({
name: 'temp-app'
}, (err, result) => {});Starts an app and waits for all instances to run stable.
Arguments
options- An options containing:appGuid- Optional The app guid.appGuidornameare mandatory but not both.name- Optional The app name.appGuidornameare mandatory but not both.startTimeout- Optional Will return if starting duration is longer than that value in seconds. Default is 30.interval- Optional The interval in seconds to wait between checking the app instance state. Default is 3.timeout- Optional Will return if starting duration of a single instance is longer than that value in seconds. Default is 30.gracePeriod- Optional Period to check and wait for the app instances not crashing. Default is 40.
callback(err, result)- A callback which is called when function has finished, or an error occurs.
Example
api.startAppAndWaitForInstances({
name: 'temp-app'
}, (err, result) => {});Deletes an app.
Arguments
options- An options containing:appGuid- Optional The app guid.appGuidornameare mandatory but not both.name- Optional The app name.appGuidornameare mandatory but not both.
callback(err, result)- A callback which is called when function has finished, or an error occurs.
Example
api.deleteApp({
name: 'temp-app'
}, (err, result) => {});Route related api methods.
Creates a route.
Arguments
options- An options containing:domainGuid- Optional The app guid.domainGuidordomainare mandatory but not both.domain- Optional The app name.domainGuidordomainare mandatory but not both.hostname- The host portion of the route. Required for shared-domains.path- The path for a route as raw text. 1) Paths must be between 2 and 128 characters 2) Paths must start with a forward slash "/" 3) Paths must not contain a "?"port- The port of the route. Supported for domains of TCP router groups only.generatePort- Set totrueto generate a random port. Defaults tofalse. Supported for domains for TCP router groups only. Takes precedence over manually specified port.
callback(err, result)- A callback which is called when function has finished, or an error occurs.
Example
api.createRoute({
hostname: 'my-app',
domain: 'applicationcloud.io'
}, (err, result) => {});Associates a route to an app.
Arguments
options- An options containing:appGuid- Optional The app guid.appGuidorappare mandatory but not both.app- Optional The app name.appGuidorappare mandatory but not both.routeGuid- Optional The route guid.routeGuidordomainandhostnameare mandatory but not all.domain- Optional The app name.routeGuidordomainandhostnameare mandatory but not all.hostname- Optional The host portion of the route. Required for shared-domains.routeGuidordomainandhostnameare mandatory but not all.
callback(err, result)- A callback which is called when function has finished, or an error occurs.
Example
api.associateRoute({
app: 'temp-app',
hostname: 'my-app',
domain: 'applicationcloud.io'
}, (err, result) => {});Disassociates a route from an app.
Arguments
options- An options containing:appGuid- Optional The app guid.appGuidorappare mandatory but not both.app- Optional The app name.appGuidorappare mandatory but not both.routeGuid- Optional The route guid.routeGuidordomainandhostnameare mandatory but not all.domain- Optional The app name.routeGuidordomainandhostnameare mandatory but not all.hostname- Optional The host portion of the route. Required for shared-domains.routeGuidordomainandhostnameare mandatory but not all.
callback(err, result)- A callback which is called when function has finished, or an error occurs.
Example
api.disassociateRoute({
app: 'temp-app',
hostname: 'my-app',
domain: 'applicationcloud.io'
}, (err, result) => {});Deletes a route.
Arguments
options- An options containing:routeGuid- Optional The route guid.routeGuidordomainandhostnameare mandatory but not all.domain- Optional The app name.routeGuidordomainandhostnameare mandatory but not all.hostname- Optional The host portion of the route. Required for shared-domains.routeGuidordomainandhostnameare mandatory but not all.
callback(err, result)- A callback which is called when function has finished, or an error occurs.
Example
api.deleteRoute({
app: 'temp-app',
hostname: 'my-app',
domain: 'applicationcloud.io'
}, (err, result) => {});Service related api methods.
Creates a service instance.
Arguments
options- An options containing:name- The service instance name.type- The service type.plan- The service plan.parameters- Optional Arbitrary parameters to pass along to the service broker. Must be an object.tags- Optional An array of strings for the service instance. Max characters: 2048
callback(err, result)- A callback which is called when function has finished, or an error occurs.
Example
api.createServiceInstance({
name: 'my-db',
type: 'mongodb',
plan: 'small'
}, (err, result) => {});Binds a service instance to an app.
Arguments
options- An options containing:appGuid- Optional The app guid.appGuidorappare mandatory but not both.app- Optional The app name.appGuidorappare mandatory but not both.service- Optional The service instance name.serviceInstanceGuidorserviceare mandatory but not both.serviceInstanceGuid- Optional The service instance guid.serviceInstanceGuidorserviceare mandatory but not both.parameters- Optional Arbitrary parameters to pass along to the service broker. Must be an object.
callback(err, result)- A callback which is called when function has finished, or an error occurs.
Example
api.bindService({
app: 'temp-app',
service: 'my-db'
}, (err, result) => {});Unbinds a service instance from an app.
Arguments
options- An options containing:app- Optional The app name.serviceBindingGuidorappand service` are mandatory but not all.service- Optional The service instance name.serviceBindingGuidorappand service` are mandatory but not all.serviceBindingGuid- OptionalserviceBindingGuidorappand service` are mandatory but not all.
callback(err, result)- A callback which is called when function has finished, or an error occurs.
Example
api.unbindService({
app: 'temp-app',
service: 'my-db'
}, (err, result) => {});Deletes a service instance.
Arguments
options- An options containing:name- Optional The service instance name.serviceInstanceGuidornameare mandatory but not both.serviceInstanceGuid- Optional The service instance guid.serviceInstanceGuidornameare mandatory but not both.
callback(err, result)- A callback which is called when function has finished, or an error occurs.
Example
api.deleteServiceInstance({
app: 'temp-app',
service: 'my-db'
}, (err, result) => {});