@aptusai/cycle

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.