@aptusai/cycle v0.9.4-beta
README
Cycle.io Object-Oriented Adapter - Developed by Aptus Engineering, Inc.
Install using NPM
npm install @aptusai/cycle
Import into your project with either of the following depending on your node/javascript engine version:
import Cycle from '@aptusai/cycle';
const Cycle = require('@aptusai/cycle');
Usage
The Cycle Object
All operations require a Cycle object instantiated with the API token and hub ID.
const c = new Cycle(token, hubId);
Multiplie hubs can be connected to with different instantiations of the object.
To perform operations within an environment, set the environment ID using the env method.
c.env(envId);
Helper Class Constructors
The Cycle object has some built-in class constructor helpers for the Container, Image, and Server object along with some other helper functions.
await Cycle.newContainer(name, image, hostname, stateful, network, ports, instances, tags)
Create a new container and return the container resource object.
Arguments:
- name
String
: name of the container - image
Image
: Image object (see below) to use for the container - hostname
String
: container host name - stateful
Boolean
: Stateful container? (default:false
) - network
String
: One of:disabled
(default),egress-only
,enabled
- ports
list.String
: List of port mappings (default:[]
) - instances
Number
: Number of container instances (default:1
) - tags
list.String
: List of server tags to apply (default:[]
)
await Cycle.getContainer(id)
Returns container resource object with given id
. See the Cycle API docs for more details on the container resource object.
await Cycle.listContainers()
Returns a list of all container resources currently deployed in the cycle environment.
await Cycle.pullImage(url, username, password, target)
Arguments
- url
String
: Registry url where the image to import is hosted. - username
String
: Username to log into the registry. - password
String
: Password to log into the registry. - target
String
: Name of the image on the registry.
Pulls an image from a docker registry, builds within Cycle and returns the Cycle Image resource object.
await Cycle.getImage(id)
Returns Image
object with given id
.
await Cycle.listImages()
Returns a list of Image
objects in the connected hub.
await Cycle.infrastructure.addServer(model, provider, location, quantity, cluster, hostnames)
Arguments
- model
String
: Cycle modelId. See infrastructure functions for how to get this -await c.infrastructure.providers()
- provider
String
: Cycle provider identifier. See infrastructure functions for how to get this -await c.infrastructure.models(provider)
- location
String
: Cycle locations id. See infrastructure functions for how to get this -await c.infrastructure.locations(provider, modelId)
- quantity
Int
: Number of servers of the specified types to provision. - cluster
String
: What cluster the servers should be associated with. - hostnames [
Array
String
]:OPTIONAL
Array of hostnames. Must be the same length as quantity. If not provided, cycle will generate a default hostname for each server provisioned.
Provisions new server(s) with given parameters and returns the Server
object.
await Cycle.infrastructure.getServer(id)
Returns Server
object with given id
.
The Container Object
The Container object can be imported either directly from @aptusai/cycle/container
, or instantiated using one of the Container return methods in the Cycle object.
To instantiate a Container object directly from the class, the constructor requires the Cycle instance to be passed in.
import Cycle from '@aptusai/cycle';
import Container from '@aptusai/cycle/container';
const c = new Cycle(token, hubId);
const container = new Container(c);
The Container object implements the following methods:
await Container.get(id)
Given an ID, the method populates the Container object with properties of the Cycle API's Container resource object - see the Cycle API docs.
await Container.create(name, image, hostname, stateful, network, ports, instances, tags)
Create a container and populate with Container resource properties. Arguments are the same as that of Cycle.newContainer
.
await Container.start()
await Container.stop()
await Container.del()
await Container.scale(instances)
Scale container to have instances
instances. Return when scaling completed.
await Container.reimage(image)
Re-image container to use the image
Image object. Returns when reimaging completed.
await Container.setenv({ env1: val1, env2: val2, ... })
Set environment variables for container. Requires container restart to apply.
await Container.wait(state)
Wait until container state matches the input argument: state
The Image Object
The Image object can be imported either directly from @aptusai/cycle/image
, or instantiated using one of the Image return methods in the Cycle object.
To instantiate an Image object directly from the class, the constructor requires the Cycle instance to be passed in.
import Cycle from '@aptusai/cycle';
import image from '@aptusai/cycle/image';
const c = new Cycle(token, hubId);
const image = new Image(c);
The Image object implements the following methods:
await Image.get(id)
Given an ID, the method populates the Image object with properties of the Cycle API's Image resource object - see the Cycle API docs.
await Image.build(url, username, password, target)
Create an image and save that image on cycle. Arguments are the same as that of the Cycle.pullImage
function.
await Image.del()
The Server Object
The Server object can be imported either directly from @aptusai/cycle/server
, or instantiated using one of the Server return methods in the Cycle object.
To instantiate an Server object directly from the class, the constructor requires the Cycle instance to be passed in.
import Cycle from '@aptusai/cycle';
import server from '@aptusai/cycle/server';
const c = new Cycle(token, hubId);
const server = new Server(c);
The Server object implements the following methods:
await Server.get(id)
Given an ID, the method populates the Server object with properties of the Cycle API's Server resource object - see the Cycle API docs.
await Server.add(model, provider, location=null, quantity=1, cluster-"production", hostnames=undefined)
Provision server(s). Arguments are the same as that of Cycle.infrastructure.addServer
.
await Server.del()
Infrastructure Functions
The Cycle instance has many other functions for interacting with servers.
await c.infrastructure.providers()
List all available providers.
await c.infrastructure.models(provider)
List all the available servers provided by the given provider.
await c.infrastructure.locations(provider, modelId)
List all the available locaion ids for a given provider/modelId pair.
Other Notes
Most functions have an optional timeout
variable. This is the number of milliseconds the promise will wait before throwing a timeout error.