@turbot/sdk

The turbot JavaScript SDK simplifies writing controls, actions and calculated policies for execution in a Turbot environment. It is generally used as a key component of @turbot/fn, which establishes context and environment for Turbot when run inside an AWS Lambda function.

Install

The turbot SDK is used as a sub-component of @turbot/fn and should be installed through @turbot/fn instead using:

npm install @turbot/fn

The turbot SDK can be used without @turbot/fn with the source downloadable from GitHub. The easiest installation is through npm by running:

npm install @turbot/sdk

SDK components

Logging

• turbot.log.debug
• turbot.log.info
• turbot.log.notice
• turbot.log.warning
• turbot.log.error

turbot.log.{level}(message, data)

• Logging requires a message and data/or data to be processed Valid log levels are:

• error
• warning
• notice
• info
• debug

Examples:

• turbot.log.debug("String message for logging");
• turbot.log.debug({object: "will", be: "logged", as: "data", with: "no", message: "string"});
• turbot.log.debug("A message", {and: "an", object: "works fine"});

Limits:

• Each log message with its data must be less than 256kB in size.

States

• turbot.ok(reason, data)
• turbot.invalid(reason, data)
• turbot.error(reason, data)
• urbot.tbd(reason, data)
• turbot.skipped(reason, data)

Action

• turbot.action.run(actionUri, parameters)
• turbot.action.run(aka, actionUri, parameters)
  • Run actionUri with parameters for resource aka (optional, defaults to target resource). Examples: turbot.action.run("tmod:@turbot/aws-s3#/action/types/bucketDelete");

Policy

Policies that are set to manage the configuration settings for controls, return the states as per the conditions provided.

• turbot.policy.ok(value, reason, data)
• turbot.policy.invalid(reason, data)
• turbot.policy.error(reason, data)
• turbot.policy.tbd(reason, data)

State	Description
OK	The state is returned when the Policy value is set correctly and is valid against the schema at the time it was set.
Invalid	State is returned when the Policy value is not set, Either a prerequisite was Invalid, or the value given for this policy was not valid against its schema. The previous value of the policy is still in place, but any controls or policies depending on this policy are blocked until it is in an OK state.
Error	The state is returned when an unexpected error occurrs while calculating the policy. Human intervention is required to fix, and support may be required to review.
TBD	The state is returned when insufficient information or input has been provided for the policy to be calculated.

Control

turbot.control.{ok,alarm,skipped,error,invalid,tbd}(reason, data)

Set controlId (optional, defaults to target control) to be {state} with an optional reason and data.

State	Description
OK	The state is returned when the control runs successfully with no change required.
Alarm	The state is returned when conditions are not met and changes are required in the resource or the environment.
Invalid	The state is returned when the policy settings require changes in order to meet the conditions or the environment needs configuration checks. The only resolution is by changes to the policies or different configurations.
Error	The state is returned when unexpected error occurs while executing the control. Human intervention is required to fix unexpected conditions, and support may be required to review.
TBD	The state is returned when insufficient information or input has been provided for the control to be executed. The state is fixed with correct required inputs.
Examples:

• turbot.control.ok();
• turbot.control.invalid("Incompatible requirements or state that requires human intervention");
• turbot.control.error("Not Found", { more: "details" });
• turbot.control.tbd("Waiting on updates");
• turbot.control.skipped();

Resource

• turbot.resource.create(parentId, resourceTypeAka, data, turbotData)
• turbot.resource.upsert(parentId, resourceTypeAka, data, turbotData)
• turbot.resource.put(resourceId,data, turbotData)
• turbot.resource.putPath(resourceId, path, data, turbotDataPath, turbotData)
• turbot.resource.putPaths(resourceId,data, turbotData)
• turbot.resource.update(resourceId,data, turbotData)
• turbot.resource.delete(resourceId)
• turbot.resource.notify(resourceId, icon, message, data)

State	Description
upsert	It upsert the resource with the parentID
put	It put the resource data in the CMDB with resourceId
putPaths	It put the resource data in the CMDB with
update	It update the data of resource in the CMDB with the given resourceId

Examples:

• turbot.resource.upsert(“#/resource/types/certificate”, resource, turbotData);
• turbot.resource.put(result, turbotData);
• turbot.resource.putPaths(result, turbotData);
• turbot.resource.update({ title: ‘New title’ });
• turbot.resource.delete(resourceId);

Watch

• turbot.watch.create(resourceId, filters, action)
• turbot.watch.delete(watchId)

State	Description
create	It creates the watch
delete	It deletes the watch

Examples:

• turbot.watch.delete(227139196406160, [ "level:self,descendant notificationType:resource_deleted" ], "tmod:@turbot/aws-s3#/action/types/bucketDelete");
• turbot.watch.delete(304627475971091);

Action

• turbot.action.ok(reason, data)
• turbot.action.invalid(reason, data)
• turbot.action.tbd(reason, data)
• turbot.action.error(reason, data)
• turbot.action.skipped(reason, data) Examples: turbot.action.ok() turbot.action.error()

Notifications

• turbot.notify(icon, message, data)
• turbot.notify(controlId, icon, message, data)