machines/create.js

  1. 'use strict';
  3. var method = require('./../method');
  4. var assign = require('lodash.assign');
  6. /**
  7.  * @memberof machines
  8.  * @method create
  9.  * @description Create a new Paperspace virtual machine. If you are using an individual account,
  10.  * you will be assigned as the owner of the machine. If you are a team administrator, you must
  11.  * specify the user that should be assigned to the machine, either by specifing a user id, or by providing an email address, password, first name and
  12.  * last name for the creation of a new user on the team.  (The email address must not already be associated with a Paperspace account, otherwise a user creation error is returned.)
  13.  *
  14.  * Note: if you attempt to create a new user along with the machine, the user creation step is executed before the creation of the machine.
  15.  * Therefore, if an error occurs, the user creation step may or may not have succeeded.  To deal with this, if an error object is returned from the `machines create`
  16.  * method, subsquently call the `users list` method (with a search filter specifying the email address) to check if the user creation step succeeded.
  17.  *
  18.  * Note: machine creation is not always guaranteed to succeed, due to various possible issues such as machine availability, billing issues, resource issues, or system errors.
  19.  * However you can call the `machines availability` method to check for current point-in-time availability of a given machine type.
  20.  *
  21.  * This machine create action can only be performed by the account owner. (Team members cannot create machines themselves; only the team administrator may do so.)
  22.  * @param {object} params - Machine creation parameters
  23.  * @param {string} params.region - Name of the region: either 'East Coast (NY2)', 'West Coast (CA1)', or 'Europe (AMS1)'
  24.  * @param {string} params.machineType - Machine type: either 'Air', 'Standard', 'Pro', 'Advanced', 'GPU+', 'P4000', 'P5000', 'P6000', 'V100', 'C1', 'C2', 'C3', 'C4', 'C5', 'C6', 'C7', 'C8', 'C9', or 'C10'<p>
  25.  * Note:<br>
  26.  * Windows os templates cannot be used to create CPU-only machine types 'C1' - 'C10'.<br>
  27.  * Ubuntu os templates cannot be used to create GRID GPU machine types: 'Air', 'Standard', 'Pro', or 'Advanced'.
  28.  * @param {number} params.size - Storage size for the machine in GB
  29.  * @param {string} params.billingType - Either 'monthly' or 'hourly' billing
  30.  * @param {string} params.machineName - A memorable name for this machine
  31.  * @param {string} params.templateId - Template id of the template to use for creating this machine
  32.  * @param {boolean} [params.assignPublicIp] - Assign a new public ip address on machine creation. Cannot be used with dynamicPublicIp.
  33.  * @param {boolean} [params.dynamicPublicIp] - Assigns a new public ip address on machine start and releases it from the account on machine stop. Cannot be used with assignPublicIp.
  34.  * @param {string} [params.networkId] - If creating on a specific network, specify its id
  35.  * @param {string} [params.teamId] - If creating the machine for a team, specify the team id
  36.  * @param {string} [params.userId] - If assigning to an existing user other than yourself, specify the user id (mutually exclusive with email, password, firstName, lastName)
  37.  * @param {string} [params.email] - If creating a new user for this machine, specify their email address (mutually exclusive with userId)
  38.  * @param {string} [params.password] - If creating a new user, specify their password (mutually exclusive with userId)
  39.  * @param {string} [params.firstName] - If creating a new user, specify their first name (mutually exclusive with userId)
  40.  * @param {string} [params.lastName] - If creating a new user, specify their last name (mutually exclusive with userId)
  41.  * @param {string} [params.notificationEmail] - Send a notification to this email address when complete
  42.  * @param {string} [params.scriptId] - The script id of a script to be run on startup.  See the [Script Guide]{@link https://paperspace.github.io/paperspace-node/scripts.md} for more info on using scripts.
  43.  * @param {function} cb - Node-style error-first callback function
  44.  * @returns {object} machine - The created machine JSON object
  45.  * @example
  46.  * paperspace.machines.create({
  47.  *   region: 'East Coast (NY2)',
  48.  *   machineType: 'Air',
  49.  *   size: 50,
  50.  *   billingType: 'hourly',
  51.  *   machineName: 'My Machine 1',
  52.  *   templateId: 't123abc',
  53.  *   assignPublicIp: true, // optional - assign a new public ip address
  54.  *   networkId: 'n123abc', // optional - only if creating on a specific network
  55.  *   teamId: 'te456def', // optional - required if creating this machine for a team
  56.  *   email: 'example@example.com', // optional - if creating a new user
  57.  *   password: 'secret123', // optional - if creating a new user
  58.  *   firstName: 'Jon', // optional - if creating a new user
  59.  *   lastName: 'Snow', // optional - if creating a new user
  60.  *   notificationEmail: 'example@example.com', // optional - address to send a notification when complete
  61.  *   scriptId: 'sc123abc', // optional - a script to be run on startup
  62.  * }, function(err, res) {
  63.  *   // handle error or result
  64.  * });
  65.  * @example
  66.  * $ paperspace machines create \
  67.  *     --region "East Coast (NY2)" \
  68.  *     --machineType "Air" \
  69.  *     --size 50 \
  70.  *     --billingType "hourly" \
  71.  *     --machineName "My Machine 1" \
  72.  *     --templateId "t123abc" \
  73.  *     --assignPublicIp true \
  74.  *     --networkId "n123abc" \
  75.  *     --teamId "te456def" \
  76.  *     --userId "u123abc" \
  77.  *     --email "example@example.com" \
  78.  *     --password "secret123" \
  79.  *     --firstName "Jon" \
  80.  *     --lastName "Snow" \
  81.  *     --notificationEmail "example@example.com" \
  82.  *     --scriptId "sc123abc"
  83.  * @example
  84.  * # HTTP request:
  85.  * https://api.paperspace.io
  86.  * POST /machines/createSingleMachinePublic {"region": "East Coast (NY2)", "machineType": "Air", "size": 50, "billingType": "monthly", "machineName": "My Machine 1", "templateId": "t123abc", "assignPublicIp": true, "networkId": "n123abc", "teamId": "te456def", "email": "example@example.com", "password": "secret123", "firstName": "Jon", "lastName": "Snow", "notificationEmail": "example@example.com"}
  87.  * x-api-key: 1ba4f98e7c0...
  88.  * # Returns 201 on success
  89.  * @example
  90.  * // Example return value:
  91.  * {
  92.  *   "id": "ps123abc",
  93.  *   "name": "My Machine",
  94.  *   "os": null,
  95.  *   "ram": null,
  96.  *   "cpus": 1,
  97.  *   "gpu": null,
  98.  *   "storageTotal": null,
  99.  *   "storageUsed": null,
  100.  *   "usageRate": "Air hourly",
  101.  *   "shutdownTimeoutInHours": 24,
  102.  *   "shutdownTimeoutForces": false,
  103.  *   "performAutoSnapshot": false,
  104.  *   "autoSnapshotFrequency": null,
  105.  *   "autoSnapshotSaveCount": null,
  106.  *   "agentType": "WindowsDesktop",
  107.  *   "dtCreated": "2017-02-16T20:26:54.880Z",
  108.  *   "state": "provisioning",
  109.  *   "updatesPending": false,
  110.  *   "networkId": null,
  111.  *   "privateIpAddress": null,
  112.  *   "publicIpAddress": "169.255.255.254",
  113.  *   "region": null,
  114.  *   "userId": "u123abc",
  115.  *   "teamId": "te456def",
  116.  *   "scriptId": "sc123abc",
  117.  *   "dtLastRun": null,
  118.  *   "dynamicPublicIp": null
  119.  * }
  120.  */
  122. function create(params, cb) {
  123. 	return method(create, params, cb);
  124. }
  126. assign(create, {
  127. 	auth: true,
  128. 	group: 'machines',
  129. 	name: 'create',
  130. 	method: 'post',
  131. 	route: '/machines/createSingleMachinePublic',
  132. 	requires: {
  133. 		region: 'string',
  134. 		machineType: 'string',
  135. 		size: 'number',
  136. 		billingType: 'string',
  137. 		machineName: 'string',
  138. 		templateId: 'string',
  139. 	},
  140. 	returns: {},
  141. });
  143. module.exports = create;