Package @pulumi/cloud

var cloud = require("@pulumi/cloud");
import * as cloud from "@pulumi/cloud";

APIs

APIs

type Action

type Action = () => Promise<void>;

Action is a handler that performs an action in response to a timer firing.

interface API

interface API

API publishes an internet-facing HTTP API, for serving web applications or REST APIs.

let api = new API("myapi")
api.get("/", (req, res) => res.json({hello: "world"}));
api.publish().url.then(url =>
  console.log(`Serving myapi at ${url}`)
);

Paths are / seperated. A path can use {param} to capture zero-or-more non-/ characters and make the captured path segment available in req.params.param, or {param+} to greedily capture all remaining characters in the url path into req.params.param.

Paths and routing are defined statically, and cannot overlap. Code inside a route handler can be used to provide dynamic decisions about sub-routing within a static path.

method all

all(path: string, handlers: RouteHandler[]): void

Routes all HTTP methods on the given path to the provided handler(s).

method attachCustomDomain

attachCustomDomain(domain: Domain): void

Attach a custom domain to this API.

Provide a domain name you own, along with SSL certificates from a certificate authority (e.g. LetsEncrypt).

Must be called prior to [publish]ing the API.

Note: It is strongly encouraged to store certificates in config variables and not in source code.

method delete

delete(path: string, handlers: RouteHandler[]): void

Routes DELETE requests on the given path to the provided handler(s).

method get

get(path: string, handlers: RouteHandler[]): void

Routes GET requests on the given path to the provided handler(s).

method options

options(path: string, handlers: RouteHandler[]): void

Routes OPTIONS requests on the given path to the provided handler(s).

method post

post(path: string, handlers: RouteHandler[]): void

Routes POST requests on the given path to the provided handler(s).

method proxy

proxy(path: string, target: string | pulumi.Output<Endpoint>): void

proxy forwards an HTTP request to a target URL or Endpoint.

method publish

publish(): HttpDeployment

Publishes an API to be internet accessible.

This should be called after describing desired routes and domains. Throws an error if called multiple times on the same endpoint.

method put

put(path: string, handlers: RouteHandler[]): void

Routes PUT requests on the given path to the provided handler(s).

method route

route(method: string, path: string, handlers: RouteHandler[]): void

Routes any requests with given HTTP method on the given path to the provided handler(s).

method static

static(path: string, localPath: string, options?: ServeStaticOptions): void

static serves a file or directory from within the source folder at the requested path.

interface APIConstructor

interface APIConstructor

constructor

new APIConstructor(apiName: string)

interface Bucket

interface Bucket

Bucket is a simple blob store.

Gets are read-after-write consistent for puts of new blobs, and eventually consistent for overwriting puts.

Blobs in a bucket are encrypted at rest by default.

method delete

delete(key: string): Promise<void>

Delete a blob from the bucket.

method get

get(key: string): Promise<Buffer>

Get a blob from the bucket.

method onDelete

onDelete(name: string, handler: BucketHandler, filter?: BucketFilter): void

Registers a handler to be notified when blobs are deleted from the bucket.

method onPut

onPut(name: string, handler: BucketHandler, filter?: BucketFilter): void

Registers a handler to be notified when blobs are put into the bucket (created or updated).

method put

put(key: string, contents: Buffer): Promise<void>

Insert a blob into the bucket.

interface BucketConstructor

interface BucketConstructor

constructor

new BucketConstructor(name: string, opts?: pulumi.ResourceOptions)

Creates a new Bucket.

  • name A unique name for the bucket.
  • opts A bag of options that controls how this resource behaves.

interface BucketFilter

interface BucketFilter

BucketFilter specifies filters to apply to an [onPut] or [onDelete] subscription.

property keyPrefix

keyPrefix?: undefined | string;

property keySuffix

keySuffix?: undefined | string;

type BucketHandler

type BucketHandler = (args: BucketHandlerArgs) => Promise<void>;

BucketHandler is the callback that handles an [onPut] or [onDelete] event.

interface BucketHandlerArgs

interface BucketHandlerArgs

BucketHandlerArgs are the arguments passed to an [onPut] or [onDelete] handler.

property eventTime

eventTime: string;

The time (in ISO-8601 format) when the [put] or [delete] was completed.

property key

key: string;

The key that was updated or deleted by the operation.

property size

size: number;

The size, in bytes, of the blob that was [put].

interface CacheFrom

interface CacheFrom

CacheFrom may be used to specify build stages to use for the Docker build cache. The final image is always implicitly included.

property stages

stages?: string[];

An optional list of build stages to use for caching. Each build stage in this list will be built explicitly and pushed to the target repository. A given stage’s image will be tagged as “[stage-name]”.

interface Container

interface Container

Container specifies the metadata for a component of a Service.

property build

build?: string | ContainerBuild;

Either a path to a folder in which a Docker build should be run to construct the image for this Container, or a ContainerBuild object with more detailed build instructions. If image is also specified, the built container will be tagged with that name, but otherwise will get an auto-generated image name.

property command

command?: pulumi.Input<string[]>;

The command line that is passed to the container. This parameter maps to Cmd in the Create a container section of the Docker Remote API and the COMMAND parameter to docker run. For more information about the Docker CMD parameter, go to https://docs.docker.com/engine/reference/builder/#cmd.

property cpu

cpu?: pulumi.Input<number>;

Number of CPUs for the container to use. Maps to the Docker --cpus option - see https://docs.docker.com/engine/reference/commandline/run.

property dockerLabels

dockerLabels?: pulumi.Input<{[name: string]: string}>;

A key/value map of labels to add to the container. This parameter maps to Labels in the Create a container section of the Docker Remote API and the –label option to docker run.

property environment

environment?: undefined | {[name: string]: pulumi.Input<string>};

Optional environment variables to set and make available to the container as it is running.

property function

function?: undefined | () => void;

The function code to use as the implementation of the contaner. If function is specified, neither image nor build are legal.

property image

image?: pulumi.Input<string>;

The image to use for the container. If image is specified, but not build, the image will be pulled from the Docker Hub. If image and build are specified, the image controls the resulting image tag for the build image that gets pushed.

property memory

memory?: pulumi.Input<number>;

The maximum amount of memory the container will be allowed to use. Maps to the Docker --memory option - see https://docs.docker.com/engine/reference/commandline/run.

This should be supplied in MB. i.e. A value of 1024 would equal one gigabyte.

property memoryReservation

memoryReservation?: pulumi.Input<number>;

The amount of memory to reserve for the container, but the container will be allowed to use more memory if it’s available. At least one of memory and memoryReservation must be specified. Maps to the Docker --memory-reservation option - see https://docs.docker.com/engine/reference/commandline/run.

This should be supplied in MB. i.e. A value of 1024 would equal one gigabyte.

property ports

ports?: ContainerPort[];

An array of ports to publish from the container. Ports are exposed using the TCP protocol. If the [external] flag is true, the port will be exposed to the Internet even if the service is running in a private network. Maps to the Docker --publish option - see https://docs.docker.com/engine/reference/commandline/run.

property volumes

volumes?: ContainerVolumeMount[];

An array of volume mounts, indicating a volume to mount and a path within the container at which to mount the volume. Maps to the Docker --volume option - see https://docs.docker.com/engine/reference/commandline/run.

interface ContainerBuild

interface ContainerBuild

ContainerBuild may be used to specify detailed instructions about how to build a container.

property args

args?: undefined | {[key: string]: string};

An optional map of named build-time argument variables to set during the Docker build. This flag allows you to pass built-time variables that can be accessed like environment variables inside the RUN instruction.

property cacheFrom

cacheFrom?: boolean | CacheFrom;

An optional CacheFrom object with information about the build stages to use for the Docker build cache. This parameter maps to the –cache-from argument to the Docker CLI. If this parameter is true, only the final image will be pulled and passed to –cache-from; if it is a CacheFrom object, the stages named therein will also be pulled and passed to –cache-from.

property context

context?: undefined | string;

context is a path to a directory to use for the Docker build context, usually the directory in which the Dockerfile resides (although dockerfile may be used to choose a custom location independent of this choice). If not specified, the context defaults to the current working directory; if a relative path is used, it is relative to the current working directory that Pulumi is evaluating.

property dockerfile

dockerfile?: undefined | string;

dockerfile may be used to override the default Dockerfile name and/or location. By default, it is assumed to be a file named Dockerfile in the root of the build context.

interface ContainerPort

interface ContainerPort

ContainerPort represents the information about how to expose a container port on a [Service].

property external

external?: undefined | false | true;

Whether the port should be exposed externally. Defaults to false.

property port

port: number;

The incoming port where the service exposes the endpoint.

property protocol

protocol?: ContainerProtocol;

The protocol to use for exposing the service:

  • tcp: Expose TCP externaly and to the container.
  • udp: Expose UDP externally and to the container.
  • http: Expose HTTP externally and to the container.
  • https: Expose HTTPS externally and HTTP to the container.

property targetPort

targetPort?: undefined | number;

The target port on the backing container. Defaults to the value of [port].

type ContainerProtocol

type ContainerProtocol = "tcp" | "udp" | "http" | "https";

interface Containers

interface Containers

A collection of Containers

interface ContainerVolumeMount

interface ContainerVolumeMount

property containerPath

containerPath: string;

property sourceVolume

sourceVolume: Volume;

function cron

cron(name: string, cronTab: string, handler: Action, opts?: pulumi.ResourceOptions): void

A cron timer, which fires on based on a specificied cron schedule.

function daily

daily(name: string, handler: Action, opts?: pulumi.ResourceOptions): void

A daily timer, firing each day, on the day (at UTC midnight).

daily(name: string, schedule: DailySchedule, handler: Action, opts?: pulumi.ResourceOptions): void

A daily timer, firing at the specified UTC hour and minute each day.

interface DailySchedule

interface DailySchedule

DailySchedule describes a time of day ([[hourUTC]] and [[minuteUTC]]) at which a daily timer should fire.

property hourUTC

hourUTC?: undefined | number;

The hour, in UTC, that the timer should fire.

property minuteUTC

minuteUTC?: undefined | number;

The minute, in UTC, that the timer should fire.

interface Domain

interface Domain

Domain includes the domain name and certificate data to enable hosting an API on a custom domain.

property certificateBody

certificateBody: string;

An SSL/TLS certficicate issued for this domain (cert.pem).

property certificateChain

certificateChain: string;

The certificate chain for the SSL/TLS certificate provided for this domain (chain.pem).

property certificatePrivateKey

certificatePrivateKey: string;

An SSL/TLS private key issued for thie domain (privkey.pem).

property domainName

domainName: string;

The domain name to associate with the API.

interface Endpoint

interface Endpoint

property hostname

hostname: string;

property port

port: number;

interface Endpoints

interface Endpoints

type HostOperatingSystem

type HostOperatingSystem = "linux" | "windows";

interface HostPathVolume

interface HostPathVolume

A volume mounted from a path on the host machine.

Note: This is an emphemeral volume which will not persist across container restarts or across different hosts. This is not something that most containers will need, but it offers a powerful escape hatch for some applications.

property kind

kind: "HostPathVolume";

property path

path: string;

interface HostPathVolumeConstructor

interface HostPathVolumeConstructor

constructor

new HostPathVolumeConstructor(path: string)

Construct a new Volume with the given unique name.

interface HostProperties

interface HostProperties

HostProperties describes the kind of host where a service or task can run.

property os

os?: HostOperatingSystem;

The operating system of the host.

Default is “linux”.

function hourly

hourly(name: string, handler: Action, opts?: pulumi.ResourceOptions): void

An hourly timer, firing each hour, on the hour.

hourly(name: string, schedule: HourlySchedule, handler: Action, opts?: pulumi.ResourceOptions): void

An hourly timer, firing at the specified UTC minute each hour.

interface HourlySchedule

interface HourlySchedule

HourlySchedule describes a time of the hour ([[minuteUTC]]) at which an hourly timer should fire.

property minuteUTC

minuteUTC?: undefined | number;

The minute, in UTC, that the timer should fire.

interface HttpDeployment

interface HttpDeployment

HttpDeployment represents an API that has been deployed and is available at a URL.

property customDomainNames

customDomainNames: pulumi.Output<string>[];

An optional list of custom domain names, each corresponding to a previous call to attachCustomDomain on the API. Each name should be mapped using a DNS A record.

property url

url: pulumi.Output<string>;

The URL at which the HttpDeployment is available to the Internet.

type HttpEndpoint

DEPRECATED HttpEndpoint has been renamed to API
type HttpEndpoint = API;

function interval

interval(name: string, options: IntervalRate, handler: Action, opts?: pulumi.ResourceOptions): void

An interval timer, which fires on a regular time interval.

interface IntervalRate

interface IntervalRate

IntervalRate describes the rate at which a timer will fire.

At least one of [[minutes]], [[hours]] or [[days]] must be provided.

property days

days?: undefined | number;

The number of days in the interval. Must be a positive integer.

property hours

hours?: undefined | number;

The number of hours in the interval. Must be a positive integer.

property minutes

minutes?: undefined | number;

The number of minutes in the interval. Must be a positive integer.

type PrimaryKeyType

type PrimaryKeyType = "string" | "number" | "boolean";

The available types for primary keys. The default primary key type is string.

interface Request

interface Request

Request represents an API request.

property baseUrl

baseUrl: string;

The base url on which this http request was served.

property body

body: Buffer;

The body of the HTTP request.

property headers

headers: {[header: string]: string | string[]};

The headers of the HTTP request.

property hostname

hostname: string;

The hostname of the request.

property method

method: string;

The method of the HTTP request.

property params

params: {[param: string]: string};

The path parameters of the HTTP request. Each {param} in the matched route is available as a property of this oject.

property path

path: string;

The raw path from the HTTP request.

property protocol

protocol: string;

The protocol of the request (e.g. HTTP/HTTPS).

property query

query: {[query: string]: string | string[]};

The query parameters parsed from the query string of the request URL.

property rawHeaders

rawHeaders: string[];

The headers of the HTTP request.

interface Response

interface Response

Response represents the response to an API request.

method end

end(data?: string | Buffer, encoding?: undefined | string): void

Sends the HTTP response, optionally including data to write to the HTTP response body.

method getHeader

getHeader(name: string): string

Gets the Headers for the Response

method json

json(obj: any): void

JSON serializes an object, writes it to the HTTP response body, and sends the HTTP response.

method redirect

redirect(url: string): void

Mark the response to redirect the client to the provided URL with the optional status code, defaulting to 302.

redirect(status: number, url: string): void

method setHeader

setHeader(name: string, value: string): Response

Sets a header on the HTTP response and returns the Response for chaining operations.

method status

status(code: number): Response

Sets the HTTP response status code and returns a Response for chaining operations.

method write

write(data: string | Buffer, encoding?: undefined | string): Response

Writes a string to the HTTP response body and returns the Response for chaining operations.

property locals

locals: any;

Object containing local variables scoped to a single request. Useful for exposing request-level information such as user settings.

type RouteHandler

type RouteHandler = (req: Request, res: Response, next: () => void) => void;

RouteHandler represents a handler for a route on an API.

Implementations should invoke methods on res to respond to the request, or invoke next to pass control to the next available handler on the route for further processing.

interface ServeStaticOptions

interface ServeStaticOptions

property contentType

contentType?: undefined | string;

The content-type to serve the file as. Only valid when localPath points to a file. If localPath points to a directory, the content types for all files will be inferred.

property index

index?: boolean | string;

By default API.static will also serve ‘index.html’ in response to a request on a directory. To disable this set false or to supply a new index pass a string.

interface Service

interface Service

A persistent service running as part of the Pulumi Cloud application. A collection of container specifications are provided to define the compute that will run inside this service.

method getEndpoint

getEndpoint(containerName?: undefined | string, containerPort?: undefined | number): Promise<Endpoint>

The exposed hostname and port for connecting to the given containerName on the given containerPort. If containerName is not provided, the first container in the service is used. If containerPort is not provided, the first exposed port is used.

Only usable on the inside.

property defaultEndpoint

defaultEndpoint: pulumi.Output<Endpoint>;

The primary endpoint exposed by the service. All endpoints (including this one) can also be retrieved by using the ‘Service.endpoints’ property. Note: this value may not be present if the service does not actually expose any endpoints.

property endpoints

endpoints: pulumi.Output<Endpoints>;

The exposed hostname and port for connecting to the given containerName on the given containerPort.

property name

name: string;

interface ServiceArguments

interface ServiceArguments extends Container

The arguments to construct a Service object. These arguments may include container information, for simple single-container scenarios, or you may specify that information using the containers property. If a single container is specified in-line, it is implicitly given the name “default”.

property build

build?: string | ContainerBuild;

Either a path to a folder in which a Docker build should be run to construct the image for this Container, or a ContainerBuild object with more detailed build instructions. If image is also specified, the built container will be tagged with that name, but otherwise will get an auto-generated image name.

property command

command?: pulumi.Input<string[]>;

The command line that is passed to the container. This parameter maps to Cmd in the Create a container section of the Docker Remote API and the COMMAND parameter to docker run. For more information about the Docker CMD parameter, go to https://docs.docker.com/engine/reference/builder/#cmd.

property containers

containers?: Containers;

A collection of containers that will be deployed as part of this Service, if there are multiple.

property cpu

cpu?: pulumi.Input<number>;

Number of CPUs for the container to use. Maps to the Docker --cpus option - see https://docs.docker.com/engine/reference/commandline/run.

property dockerLabels

dockerLabels?: pulumi.Input<{[name: string]: string}>;

A key/value map of labels to add to the container. This parameter maps to Labels in the Create a container section of the Docker Remote API and the –label option to docker run.

property environment

environment?: undefined | {[name: string]: pulumi.Input<string>};

Optional environment variables to set and make available to the container as it is running.

property function

function?: undefined | () => void;

The function code to use as the implementation of the contaner. If function is specified, neither image nor build are legal.

property host

host?: HostProperties;

The properties of the host where this service can run.

property image

image?: pulumi.Input<string>;

The image to use for the container. If image is specified, but not build, the image will be pulled from the Docker Hub. If image and build are specified, the image controls the resulting image tag for the build image that gets pushed.

property memory

memory?: pulumi.Input<number>;

The maximum amount of memory the container will be allowed to use. Maps to the Docker --memory option - see https://docs.docker.com/engine/reference/commandline/run.

This should be supplied in MB. i.e. A value of 1024 would equal one gigabyte.

property memoryReservation

memoryReservation?: pulumi.Input<number>;

The amount of memory to reserve for the container, but the container will be allowed to use more memory if it’s available. At least one of memory and memoryReservation must be specified. Maps to the Docker --memory-reservation option - see https://docs.docker.com/engine/reference/commandline/run.

This should be supplied in MB. i.e. A value of 1024 would equal one gigabyte.

property ports

ports?: ContainerPort[];

An array of ports to publish from the container. Ports are exposed using the TCP protocol. If the [external] flag is true, the port will be exposed to the Internet even if the service is running in a private network. Maps to the Docker --publish option - see https://docs.docker.com/engine/reference/commandline/run.

property replicas

replicas?: undefined | number;

The number of copies of this Service’s containers to deploy and maintain as part of the running service. Defaults to 1.

property volumes

volumes?: ContainerVolumeMount[];

An array of volume mounts, indicating a volume to mount and a path within the container at which to mount the volume. Maps to the Docker --volume option - see https://docs.docker.com/engine/reference/commandline/run.

property waitForSteadyState

waitForSteadyState?: undefined | false | true;

Determines whether the service should wait to fully transition to a new steady state on creation and updates. If set to false, the service may complete its deployment before it is fully ready to be used. Defaults to ’true’.

interface ServiceConstructor

interface ServiceConstructor

constructor

new ServiceConstructor(name: string, args: ServiceArguments, opts?: pulumi.ResourceOptions)

Construct a new Service, which is one or more managed replicas of a group of one or more Containers.

  • name The unique name of the service.
  • opts A bag of options that controls how this resource behaves.

interface SharedVolume

interface SharedVolume

A shared volume that can be mounted into one or more containers.

property kind

kind: "SharedVolume";

property name

name: string;

interface SharedVolumeConstructor

interface SharedVolumeConstructor

constructor

new SharedVolumeConstructor(name: string, opts?: pulumi.ResourceOptions)

Construct a new Volume with the given unique name.

  • name The unique name of the volume.
  • opts A bag of options that controls how this resource behaves.

interface Stream

interface Stream

A Stream provides access to listen to an (infinite) stream of items coming from a data source. Unlike [[Topic]], a Stream provides only access to read from the stream, not the ability to publish new items to the stream.

method subscribe

subscribe(name: string, handler: (item: T) => Promise<void>): void

Subscribe to items published to this stream.

Each subscription receives all items published to the stream. If a subscription handler returns a failed promise, the subscription handler may be retried some number of times. If no retry is successful, the item will be sent to the global error handler. Note that as a result, subscription handlers must ensure they can safely be retried.

interface Table

interface Table

Table is a simple document store for persistent application backend storage.

let table = new Table("my-table");
await table.insert({id: "kuibai", data: 42});
let item = await table.get({id: "kuibai"});

Tables support a single primary key with a user-defined name and type. All other document properties are schemaless. If not specified, a primary key named id with type string is used.

All queries provide a subset of properties to filter on, and only filters on value equality are supported. The get, update and delete operations expect the query to contain only the value for the primary key.

method delete

delete(query: Object): Promise<void>

Deletes a documents from the table.

method get

get(query: Object): Promise<any>

Get a document from the table.

method insert

insert(item: Object): Promise<void>

Insert a document into the table.

method scan

scan(): Promise<any[]>

Gets all documents from the table.

scan(callback: (items: any[]) => Promise<boolean>): Promise<void>

method update

update(query: Object, updates: Object): Promise<void>

Updates a documents in the table.

property primaryKey

primaryKey: pulumi.Output<string>;

The name of the primary key.

property primaryKeyType

primaryKeyType: pulumi.Output<string>;

The type of the primary key.

interface TableConstructor

interface TableConstructor

constructor

new TableConstructor(name: string, primaryKey?: pulumi.Input<string>, primaryKeyType?: pulumi.Input<PrimaryKeyType>, opts?: pulumi.ResourceOptions)

Creates a new Table.

  • name A unique name for the table.
  • primaryKey An optional primary key name.
  • primaryKeyType An optional primary key type.
  • opts A bag of options that controls how this resource behaves.

interface Task

interface Task

A Task represents a container which can be [run] dynamically whenever (and as many times as) needed.

method run

run(options?: TaskRunOptions): Promise<void>

Run the task, passing in additional task run options.

interface TaskConstructor

interface TaskConstructor

constructor

new TaskConstructor(name: string, container: Container, opts?: pulumi.ResourceOptions)

Construct a new Task, which is a Container that can be run many times as individual tasks.

  • name The unique name of the task.
  • container The container specification.
  • opts A bag of options that controls how this resource behaves.

interface TaskRunOptions

interface TaskRunOptions

Arguments to use for initializing a single run of the Task

property environment

environment?: Record<string, string>;

Optional environment variables to override those set in the container definition.

property host

host?: HostProperties;

The properties of the host where this task can run.

interface Topic

interface Topic extends Stream<T>

A Topic is used to distribute work which will be run concurrently by any susbcribed handlers. Producers can [[publish]] to the topic, and consumers can [[subscribe]] to be notified when new items are published.

method subscribe

subscribe(name: string, handler: (item: T) => Promise<void>): void

Subscribe to items published to this topic.

Each subscription receives all items published to the topic.

property publish

publish: (item: T) => Promise<void>;

Publish an item to this Topic.

interface TopicConstructor

interface TopicConstructor

constructor

new TopicConstructor<T>(name: string, opts?: pulumi.ResourceOptions)

Allocate a new Topic with a given name.

  • name The unique name of the Topic.
  • opts A bag of options that controls how this resource behaves.

type Volume

type Volume = SharedVolume | HostPathVolume;

type VolumeKind

type VolumeKind = "SharedVolume" | "HostPathVolume";