sst
Version:
217 lines (216 loc) • 7.03 kB
TypeScript
import { AwsOptions } from "./client.js";
/**
* The `task` client SDK is available through the following.
*
* @example
* ```js title="src/app.ts"
* import { task } from "sst/aws/task";
* ```
*
* If you are not using Node.js, you can use the AWS SDK instead. For example, you can call
* [`RunTask`](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_RunTask.html) to
* run a task.
*/
export declare namespace task {
/**
* The link data for the task.
*
* @example
* For example, let's say you have a task.
*
* ```js title="sst.config.ts"
* new sst.aws.Task("MyTask", { cluster });
* ```
*
* `Resource.MyTask` will have all the link data.
*
* ```js title="src/app.ts"
* import { Resource } from "sst";
*
* console.log(Resource.MyTask);
* ```
*/
export interface Resource {
/**
* The ARN of the cluster.
*/
cluster: string;
/**
* The ARN of the task definition.
*/
taskDefinition: string;
/**
* The subnets to use for the task.
*/
subnets: string[];
/**
* The security groups to use for the task.
*/
securityGroups: string[];
/**
* Whether to assign a public IP address to the task.
*/
assignPublicIp: boolean;
/**
* The names of the containers in the task.
*/
containers: string[];
}
export interface Options {
/**
* Configure the options for the [aws4fetch](https://github.com/mhart/aws4fetch)
* [`AWSClient`](https://github.com/mhart/aws4fetch?tab=readme-ov-file#new-awsclientoptions) used internally by the SDK.
*/
aws?: AwsOptions;
}
export interface RunOptions extends Options {
/**
* Configure the capacity provider; regular Fargate or Fargate Spot, for this task.
*
* @default `"fargate"`
*/
capacity?: "fargate" | "spot";
}
interface Task {
/**
* The ARN of the task.
*/
arn: string;
/**
* The status of the task.
*/
status: string;
}
export interface DescribeResponse extends Task {
/**
* The raw response from the AWS ECS DescribeTasks API.
* @see [@aws-sdk/client-ecs.DescribeTasksResponse](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-ecs/Interface/DescribeTasksResponse/)
*/
response: any;
}
export interface RunResponse extends Task {
/**
* The raw response from the AWS ECS RunTask API.
* @see [@aws-sdk/client-ecs.RunTaskResponse](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-ecs/Interface/RunTaskResponse/)
*/
response: any;
}
export interface StopResponse extends Task {
/**
* The raw response from the AWS ECS StopTask API.
* @see [@aws-sdk/client-ecs.StopTaskResponse](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-ecs/Interface/StopTaskResponse/)
*/
response: any;
}
/**
* Get the details of a given task.
*
* :::note
* If a task had been stopped over an hour ago, it's not returned.
* :::
*
* @example
*
* For example, let's say you had previously started a task.
*
* ```js title="src/app.ts"
* const runRet = await task.run(Resource.MyTask);
* const taskArn = runRet.tasks[0].taskArn;
* ```
*
* You can use that to get the details of the task.
*
* ```js title="src/app.ts"
* const describeRet = await task.describe(Resource.MyTask, taskArn);
* console.log(describeRet.status);
* ```
*
* If you are not using Node.js, you can use the AWS SDK and call
* [`DescribeTasks`](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_DescribeTasks.html).
*/
export function describe(resource: Resource, task: string, options?: Options): Promise<DescribeResponse>;
/**
* Runs a task.
*
* @example
*
* For example, let's say you have defined a task.
*
* ```js title="sst.config.ts"
* new sst.aws.Task("MyTask", { cluster });
* ```
*
* You can then run the task in your application with the SDK.
*
* ```js title="src/app.ts" {4}
* import { Resource } from "sst";
* import { task } from "sst/aws/task";
*
* const runRet = await task.run(Resource.MyTask);
* const taskArn = runRet.tasks[0].taskArn;
* ```
*
* This internally calls an AWS SDK API that returns an array of tasks. But in our case,
* there's only one task.
*
* The `taskArn` is the ARN of the task. You can use it to call the `describe` or `stop`
* functions.
*
* You can also pass in any environment variables to the task.
*
* ```js title="src/app.ts"
* await task.run(Resource.MyTask, {
* MY_ENV_VAR: "my-value"
* });
* ```
*
* If you are not using Node.js, you can use the AWS SDK and call
* [`RunTask`](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_RunTask.html).
*/
export function run(resource: Resource, environment?: Record<string, string>, options?: RunOptions): Promise<RunResponse>;
/**
* Stops a task.
*
* @example
*
* For example, let's say you had previously started a task.
*
* ```js title="src/app.ts"
* const runRet = await task.run(Resource.MyTask);
* const taskArn = runRet.tasks[0].taskArn;
* ```
*
* You can stop the task with the following.
*
* ```js title="src/app.ts"
* const stopRet = await task.stop(Resource.MyTask, taskArn);
* ```
*
* Stopping a task is asnychronous. When you call `stop`, AWS marks a task to be stopped,
* but it may take a few minutes for the task to actually stop.
*
* :::note
* Stopping a task in asyncrhonous.
* :::
*
* In most cases you probably don't need to check if it has been stopped. But if necessary,
* you can use the `describe` function to get a task's status.
*
* If you are not using Node.js, you can use the AWS SDK and call
* [`StopTask`](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_StopTask.html).
*/
export function stop(resource: Resource, task: string, options?: Options): Promise<StopResponse>;
export class DescribeError extends Error {
readonly response: Response;
constructor(response: Response);
}
export class RunError extends Error {
readonly response: Response;
constructor(response: Response);
}
export class StopError extends Error {
readonly response: Response;
constructor(response: Response);
}
export {};
}