Spheron Compute SDK
The Spheron Compute SDK is a npm package, that provides support for working with Spheron Compute organizations.
NOTE: The package is only meant for Node.js environments and will not work in a browser or frontend apps.
Installation
Using NPM
npm i @spheron/compute
Using Yarn
yarn add @spheron/compute
Usage
To use the Spheron Compute SDK, you have to create an instance of SpheronClient
.
import SpheronClient from "@spheron/compute";
const client = new SpheronClient({ token });
The SpheronClient
constructor takes an object that has one property token
.
Follow the instructions in the DOCS (opens in a new tab) to generate this token. When you are creating the tokens, please choose Compute type in the dashboard.
The SpheronClient
has five properties:
organization
provides methods for working with organization.cluster
provides methods for working with cluster.instance
provides methods for working with specific instance.computeMarketplace
provides methods for getting information about marketplace apps.computeMachine
provides methods for getting information about available compute machines.
Organization
The methods for working with organization are available on the organization
property of the SpheronClient
object.
get
Used to get the organization based on the passed id.
const organization: Organization = await spheron.organization.get();
Returns an Organization object.
interface Organization {
id: string;
profile: {
name: string,
username: string,
image: string,
};
}
NOTE: At the moment, Spheron Tokens are scoped to a single organization. So you can only use them to get the information about the organization for which you have created the token.
getClusters
Used to get the clusters of the organization. The method supports pagination.
const clusters: Cluster[] = await spheron.organization.getClusters({
skip: 0,
limit: 10
});
Params:
options
:skip
: (number) - number of clusters to skip.limit
: (number) - number of clusters to take.
Return an array of clusters. Checkout the get cluster section for more details on the cluster interface properties.
getUsage
Used to get the current subscription usage of the organization.
const usage: UsageWithLimits = await spheron.organization.getUsage();
Returns the UsageWithLimits
object.
interface UsageWithLimits {
used: {
computeCredit: number; // the amount used by organization, in usd
computeBuildExecution: number; // the time used for builds, in seconds
numberOfRequests: number; // the number of requests organization has had until now
bandwidth: number; // the bytes of bandwith used for current subscription
domains: number; // the number of domains and subdomains an organization has
};
limit: {
computeCredit: number; // the amount limit for organization, in usd
computeBuildExecution: number; // the time limit for builds, in seconds
bandwidth: number; // the limit of bandwith for subscription
domains: number; // the limit on how many domains and subdomains can an organization have
};
}
Cluster
The methods for working with clusters are available on the cluster
property of the SpheronClient
object.
get
Used to get the cluster based on the passed Id.
const cluster: Cluster = await spheron.cluster.get(clusterId);
Params:
- Id of the cluster.
Returns an object of type Cluster
.
interface Cluster {
id: string; // id of a cluster
name: string; // name of a cluster
url: string; // docker image
proivder: ProviderEnum; // docker image provider (currently only dockerhub is supported)
createdBy: string; // id of the user that created cluster
createdAt: Date;
updatedAt: Date;
};
enum ProviderEnum {
DOCKERHUB
};
delete
Used to delete a cluster.
await spheron.cluster.delete(clusterId);
Method return type is void. If there is an issue while deleting, an error will be thrown.
NOTE: Clusters with running instances cannot be deleted.
getInstancesInfo
Used for getting information about instances in cluster.
const instanceInfo: InstancesInfo = await spheron.cluster.getInstancesInfo(clusterId);
Returns an object of type InstancesInfo
.
interface InstancesInfo {
provisioned: number; // number of provisioned instances in cluster
provisioning: number; // number of provisioning instances in cluster
failedToProvision: number; // number of fail to provision instances in cluster
closed: number; // number of closed instances in cluster
total: number; // total number of instances in cluster
}
getUsage
Used to getting the current funds usage of the cluster.
const clusterUsage: ClusterFundsUsage = await spheron.cluster.getUsage(clusterId);
Params:
- Id of the cluster.
Returns an object of type ClusterFundsUsage
.
interface ClusterFundsUsage {
dailyUsage: number; // cluster daily usage in usd
usedTillNow: number; // cluster daily usage in usd
}
getInstances
Used to get the list of instances in the cluster. The method supports pagination.
const instances: InstanceDetailed[] =
await spheron.cluster.getInstances(
clusterId,
options: {
skip: 0,
limit: 10
}
);
Params:
- Id of the cluster.
options
:skip
: (number) - number of instances to skip.limit
: (number) - number of instances to take.
Returns an array of InstanceDetailed
objects. Checkout the get instance section for more details on the instance interface properties.
interface InstanceDetailed {
id: string; // id of a istance
state: InstanceStateEnum; // state of a instance
name: string; // name of a instance
deployments: Array<string>; // list of all instance deployment ids
cluster: string; // instance cluster id
activeDeployment: string; // id of active deployment
agreedMachine: MachineImageType; // compute machine information
healthCheck: HealthCheck; // instance health check endpoint information
cpu: number; // compute machine cpu
memory: string; // compute machine memory
storage: string; // compute machine storage
image: string; // docker image
tag: string; // docker tag
createdAt: Date;
updatedAt: Date;
}
Instance
The methods for working with instances are available on the instance
property of the SpheronClient
object.
create
Used for deploying new instance.
const instanceResponse: InstanceResponse =
await spheron.instance.create(creationConfig: {
clusterName: "hello world",
configuration: {
image: "crccheck/hello-world",
tag: "latest",
ports: [{ containerPort: 8000, exposedPort: 8000 }],
environmentVariables: [],
secretEnvironmentVariables: [],
commands: [],
args: [],
region: "any",
machineImageId: ventusSmallId
},
healthCheckConfig: {
path: "/",
port: 8000
}
});
Params:
clusterName
: (string) - name of cluster.configuration
: the name of the variable.image
: (string) - dockerhub image url (should be publicly available).tag
: (string) - tag for docker image.ports
: (Port[]) - list of port mappings.environmentVariables
: (EnvironmentVariable[]) - list of environment variables.secretEnvironmentVariables
: (EnvironmentVariable[]) - list of secret environment variables.commands
: (string[]) - list of executables for docker CMD command.args
: (string[]) - list of params for docker CMD command.region
: (string) - region in which to deploy instance. List of available can be acquired from getRegions section under compute machine section.machineImageId
: (string) - id of machine image which should be used for deploying instance. List of available machines can be aquierd from get section under compute machine section.healthCheckConfig
:path
: (string) - path on which health check should be done.port
: (number) - container port on which health check should be done.
Types:
Port
:containerPort
: (number) - container port that will be mapped.exposedPort
: (number) - port to be mapped to.
NOTE: At the moment, only mapping to port 80 can be guarantied. For all the others, container port will be mapped to random port asigned on instance deployment.
- { containerPort: 3000, exposedPort: 80 } - port 3000 will be mapped to port 80.
- { containerPort: 3000, exposedPort: 3000 } - port 3000 will be mapped to random port.
EnvironmentVariable
:key
: (string) - key of environment variable.value
: (string) - value of environment variable.
Returns InstanceResponse
object, indicating instance deployment has started. If there is an issue while deploying, an error will be thrown.
interface InstanceResponse {
clusterId: string; // id of cluster instance is deployed in
instanceId: string; // id of instance
instanceDeploymentId: string; // id of instance deployment
}
get
Used to get Instance based on the passed id.
const instance: Instance = await spheron.instance.get(instanceId);
Params:
- Id of the instance.
Returns object of a type Instance
.
interface Instance {
id: string; // id of a istance
state: InstanceStateEnum; // state of a instance
name: string; // name of a instance
deployments: Array<string>; // list of all instance deployment ids
cluster: string; // instance cluster id
activeDeployment: string; // id of active deployment
agreedMachine: MachineImageType; // compute machine information
healthCheck: HealthCheck; // instance health check endpoint information
createdAt: Date;
updatedAt: Date;
};
interface MachineImageType {
machineName: string; // compute machine type
agreementDate: number; // date of deploying instance
}
enum InstanceStateEnum {
STARTING,
FAILED_START,
ACTIVE,
CLOSED
};
interface HealthCheck {
path: string; // healthcheck path
port: Port; // cotainer port on which healthcheck should be done
status: HealthStatusEnum; // latest health check status
timestamp: Date; // timestamp of last health check
};
enum HealthStatusEnum {
ACTIVE,
INACTIVE,
UNKNOWN
}
delete
Used to delete a instance.
await spheron.instance.delete(instanceId);
Method return type is void. If there is an issue while deleting, an error will be thrown.
update
Used to update instance.
await spheron.instance.update(
instanceId,
{
environmentVariables: [{ key: "key", value: "value"}],
secretEnvironmentVariables: [{ key: "key", value: "value"}],
commands: ["executable"],
args: ["param"],
tag: "latest";
}
);
Params:
environmentVariables
: (EnvironmentVariable[]) - list of environment variables.secretEnvironmentVariables
: (EnvironmentVariable[]) - list of secret environment variables.commands
: (string[]) - list of executables for docker CMD command.args
: (string[]) - list of params for docker CMD command.tag
: (string[]) - tag for docker image.
Returns InstanceResponse
object, indicating instance update has started.
interface InstanceResponse {
clusterId: string; // id of cluster instance is deployed in
instanceId: string; // id of instance
instanceDeploymentId: string; // id of instance deployment
}
updateHealthCheck
Used to update endpoint used for instance health check.
const updated = await spheron.instance.updateHealthCheck(
instanceId,
{ path: "/health", port: 3000 }
);
Params:
- Id of the instance.
- Id of the environment variable.
healthCheck
:path
: (string) - health check path.port
: (number) - container port on which health check should be done.
Returns the response indicating if update was successful.
{
message: string; // the response message
success: boolean; // the flag signaling if action was successful
}
close
Used to close the instance.
const closed = await spheron.instance.close(instanceId);
Params:
- Id of the instance.
Returns the response indicating if update was successful.
{
message: string; // the response message
success: boolean; // the flag signaling if action was successful
}
getInstanceDeployment
Used to get the instance deployment based on the passed id.
const deployment: InstanceDeployment; = await spheron.instance.getInstanceDeployment(deploymentId);
Params:
- Id of the instance deployment.
Returns an InstanceDeployment
object.
interface InstanceDeployment {
id: string; // id of deployment
type: DeploymentTypeEnum; // type of deployment
status: DeploymentStatusEnum; // status of deployment
buildTime: number; // deployment build time
instance: string; // id of instance
connectionUrls: string; // list of connection url for the deployed instance
deploymentInitiator: string; // userId that initiated deployment
instanceConfiguration: {
image: string; // docker image
tag: string; // docker image tag
ports: Array<Port>; // port mappings
environmentVariables: Array<EnvironmentVar>; // environment variables
secretEnvironmentVariables: Array<EnvironmentVar>; // secret environment variables
commands: Array<string>; // list of executables for docker CMD command
args: Array<string>; // list of params for docker CMD command
region: string; // region to which instance is deployed
agreedMachineImage: MachineImageType
};
};
// Note: This is used to determine the instance deployment type
enum DeploymentTypeEnum {
DEPLOY,
UPDATE,
}
enum DeploymentStatusEnum {
QUEUED,
PENDING,
DEPLOYED,
FAILED,
DEPRECATED,
DEPRECATED_PROVIDER,
};
interface Port {
containerPort: number; // container port
exposedPort: number; // eposed port container port is mapped to
};
interface EnvironmentVariable {
key: string; // environment variable key
value: string; // environment variable value
isSecret: boolean; // is environment variable secret
};
interface MachineImageType {
machineName: string; // compute machine name
agreementDate: number; // date of deploying instance
cpu?: number; // compute machine cpu
memory?: string; // compute machine memory
storage?: string; // compute machine storage
persistentStorage?: PersistentStorage; // persistent storege information
}
interface PersistentStorage {
size: string;
class: PersistentStorageClassEnum;
mountPoint: string;
};
enum PersistentStorageClassEnum {
BETA1,
BETA2,
BETA3
}
getInstanceLogs
Used to fetch InstanceDeployment with specified logs.
const instanceLogs: Array<string> = await spheron.instance.getInstanceLogs(
deploymentId,
{
from: 0;
to: 1000;
logType: InstanceLogType.DEPLOYMENT_LOGS;
search: searchString;
});
Params:
- Id of the deployment.
options
:from
: (number) - from which line you want to fetch the first log.to
: (number) - till which line you want to fetch the logs.logType
: (InstanceLogType) - log type to fetch (deployment logs/instance logs/instance events).search
: (string) - search string (optional).
enum InstanceLogType {
DEPLOYMENT_LOGS, // the logs of instance deployment process
INSTANCE_LOGS, // the logs from container running on instance
INSTANCE_EVENTS // the logs of instance events
}
Returns an list of for instance deployment logs.
createFromMarketplace
Used to create new instance from marketplace app.
const instanceCreate: MarketplaceInstanceResponse =
await spheron.instance.createFromMarketplace(
{
marketplaceAppId: marketplaceAppId;
environmentVariables: [
{key: "User", value: "admin"},
{key: "Password", value: "super secret password"},
{key: "Database", value: "mydb" }
];
machineImageId: machineId;
region: "any";
}
);
Params:
createConfig
:marketplaceAppId
: (string) - Id of marketplace app. List of available apps can be aquierd from get section under compute marketplace section.environmentVariables
: (EnvironmentVariable[]) - list of environment variables for specified marketplace app. List of available environemt variables can be found in MarketplaceApp object.machineImageId
: (string) - name of machine image which should be used for deploying instance. List of available can be aquierd from get section under compute machine section.region
: (string) - region in which to deploy instance. List of available can be acquired from getRegions section under compute machine section.
Returns MarketplaceInstanceResponse
object, indicating instance deployment has started. If there is an issue while deploying, an error will be thrown.
interface MarketplaceInstanceResponse {
marketplaceApp: MarketplaceApp; // marketplace app used
marketplaceAppId: string; // the id of the marketplace app
clusterId: string; // the id of the cluster instance belongs to
instanceId: string; // the id of the instance
instanceDeploymentId: string; // the id of the instance deployment
}
getDomains
Used to get the domains of an instance.
const domains: Domain[] = await spheron.instance.getDomains(instanceId);
Params:
- Id of the instance.
Returns an array of instance domains.
interface Domain {
id: string; // the id of the domain
name: string; // the domain name
verified: boolean; // true means that the domain is verified and that it will start serving the content
link: string; // the link to which the domain points to
type: DomainTypeEnum; // the type of the domain
instanceId: string; // the instance id of which the domain is
};
enum DomainTypeEnum {
DOMAIN,
SUBDOMAIN
}
addDomain
Used to add a new domain to an instance.
const domain: Domain = await spheron.instance.addDomain(instanceId, {
name: "domain.com",
type: DomainTypeEnum.DOMAIN,
link: connectionUrl
});
Params:
- Id of the instance.
options
:name
: (string) - the domain name.type
: (DomainTypeEnum) - the domain type.link
: (string) - one of theconnectionUrls
list elements of a active deployment of the instance to which the domain will point to.
Returns the newly created domain. After a domain is created you need to call the verifyDomain function for it to work.
updateDomain
Used to update a domain of an instence.
const domain: Domain = await spheron.instance.updateDomain(
instanceId,
domainId,
{
name: "test.com",
type: DomainTypeEnum.DOMAIN,
link: connectionUrl,
}
);
Params:
- Id of the instance.
- Domain identifier. The domain identifier can be the domain id, or the domain name itself.
doamin
:name
: (string) - the domain name.type
: (DomainTypeEnum) - the domain type.link
: (string) - one of theconnectionUrls
list elements of a active deployment of the instance to which the domain will point to.
Returns the updated domain. If the domain name is updated you need to call the verifyDomain function again.
verifyDomain
Used to verify the domain, after which the content behind the domain will be cached on CDN.
const domain: Domain = await spheron.instance.verifyDomain(instanceId, domainId);
Params:
- Id of the instance.
- Domain identifier. The domain identifier can be the domain id, or the domain name itself.
Returns the verified domain.
deleteDomain
Used to delete a domain of an instance.
await spheron.instance.deleteDomain(instanceId, domainId);
Params:
- Id of the instance.
- Domain identifier. The domain identifier can be the domain id, or the domain name itself.
Method return type is void.
triggerLatestLog
Used to trigger fetch of latest logs for instance.
await spheron.instance.triggerLatestLog(instanceId);
Params:
- Id of the instance.
Returns the response indicating the fetching process has started.
{
message: string; // the response message
}
triggerLatestHealth
Used to trigger fetch of latest helth status for instance.
await spheron.instance.triggerLatestHealth(instanceId);
Params:
- Id of the instance.
Returns the response indicating the fetching process has started.
{
message: string; // the response message
}
Compute Marketplace
The methods for working with marketplace apps are available on the computeMarketplace
property of the SpheronClient
object.
getAll
Used to get all available compute marketplace apps.
const marketplaceApps: MarketplaceApp[] =
await spheron.computeMarketplace.getAll();
Method returns list of MarketplaceApp
objects. For more details about MarketplaceApp
check get section under compute marketplace.
get
Used to get marketplace app based on the passed id.
const marketplaceApp: MarketplaceApp =
await spheron.computeMarketplace.get(marketplaceAppId);
Params:
- Id of the marketplace app.
Method returns MarketplaceApp
object.
interface MarketplaceApp {
id: string; // id of a marketplace app
name: string; // name of a marketplace app
description: string; // description of a marketplace app
category: MarketplaceCategoryEnum; // marketplace app category
variables: MarketplaceAppVariable[]; // list of enironemt variables
};
enum MarketplaceCategoryEnum {
DATABASE,
NODE,
TOOLS
};
interface MarketplaceAppVariable {
defaultValue: string;
key: string;
required?: string;
}
getCategories
Used to get available categories for marketplace apps.
const categories: string[] = await spheron.computeMarketplace.getCategories();
Method returns list of available categories.
Compute Machine
The methods for working with compute machines are available on the computeMachine
property of the SpheronClient
object.
get
Used to get list of available compute machines.
const computeMachines: ComputeMachine[] = await spheron.computeMachine.get({
skip: 0,
limit: 10,
search: "2Gi"
});
Params:
options
:skip
: (number) - number of machines to skip.limit
: (number) - number of machines to take.search
: (string) - (optional) search string. Search for specific cpu/storage/memory.
Method returnns list of ComputeMachine
objects.
interface ComputeMachine {
id: string; // id of compute machine
name: string; // name of compute machine
cpu: number; // compute machine cpu
storage: string; // compute machine storage
memory: string; // compute machine memeory
}
getRegions
Used to get available regions.
const regions: string[] = await spheron.computeMachine.getRegions();
Returns list of available regions.