AWS.CloudControl reference

CancelResourceRequest

Source: src/AWS/CloudControl/CancelResourceRequest.ts

Runtime binding for cloudformation:CancelResourceRequest.

Cancels a resource operation request that is still PENDING or IN_PROGRESS — the companion to CreateResource / UpdateResource / DeleteResource for aborting slow or mistaken provisioning operations.

CancelResourceRequest: Tracking Requests

const cancelResourceRequest = yield* CloudControl.CancelResourceRequest();

// runtime
yield* cancelResourceRequest({
  RequestToken: created.ProgressEvent!.RequestToken!,
});

CreateResource

Source: src/AWS/CloudControl/CreateResource.ts

Runtime binding for cloudformation:CreateResource.

Provisions any Cloud Control-supported resource from inside a Function — the building block for dynamic, per-tenant provisioning services. The call is asynchronous: poll the returned RequestToken with GetResourceRequestStatus until the operation settles. Because Cloud Control invokes the resource type’s create handler with the caller’s credentials, pass the handler’s underlying permissions via CloudControlBindingOptions.handlerPolicyStatements.

CreateResource: Provisioning Resources

// init — account-level; grant the create handler's permissions too
const createResource = yield* CloudControl.CreateResource({
  handlerPolicyStatements: [
    {
      Effect: "Allow",
      Action: ["ssm:PutParameter", "ssm:GetParameters", "ssm:AddTagsToResource"],
      Resource: ["*"],
    },
  ],
});

// runtime
const created = yield* createResource({
  TypeName: "AWS::SSM::Parameter",
  DesiredState: JSON.stringify({
    Name: "/tenants/acme/greeting",
    Type: "String",
    Value: "hello",
  }),
});
// poll created.ProgressEvent.RequestToken until SUCCESS

DeleteResource

Source: src/AWS/CloudControl/DeleteResource.ts

Runtime binding for cloudformation:DeleteResource.

Deletes a Cloud Control-supported resource. The call is asynchronous: poll the returned RequestToken with GetResourceRequestStatus until the operation settles. Because Cloud Control invokes the resource type’s delete handler with the caller’s credentials, pass the handler’s underlying permissions via CloudControlBindingOptions.handlerPolicyStatements.

DeleteResource: Provisioning Resources

const deleteResource = yield* CloudControl.DeleteResource({
  handlerPolicyStatements: [
    { Effect: "Allow", Action: ["ssm:DeleteParameter"], Resource: ["*"] },
  ],
});

// runtime
const deleted = yield* deleteResource({
  TypeName: "AWS::SSM::Parameter",
  Identifier: "/tenants/acme/greeting",
});

GetResource

Source: src/AWS/CloudControl/GetResource.ts

Runtime binding for cloudformation:GetResource.

Reads the current state of any Cloud Control-supported resource — whether or not it was provisioned through Cloud Control. Because Cloud Control invokes the resource type’s read handler with the caller’s credentials, pass the handler’s underlying permissions via CloudControlBindingOptions.handlerPolicyStatements.

GetResource: Reading Resources

// init — account-level; grant the read handler's permissions too
const getResource = yield* CloudControl.GetResource({
  handlerPolicyStatements: [
    { Effect: "Allow", Action: ["ssm:GetParameters"], Resource: ["*"] },
  ],
});

// runtime
const result = yield* getResource({
  TypeName: "AWS::SSM::Parameter",
  Identifier: "/app/greeting",
});

GetResourceRequestStatus

Source: src/AWS/CloudControl/GetResourceRequestStatus.ts

Runtime binding for cloudformation:GetResourceRequestStatus.

Polls the status of an asynchronous Cloud Control operation started with CreateResource, UpdateResource, or DeleteResource until its OperationStatus settles (SUCCESS / FAILED / CANCEL_COMPLETE).

GetResourceRequestStatus: Tracking Requests

const getResourceRequestStatus =
  yield* CloudControl.GetResourceRequestStatus();

// runtime — bounded poll every 2s until the operation settles
const settled = yield* getResourceRequestStatus({
  RequestToken: created.ProgressEvent!.RequestToken!,
}).pipe(
  Effect.repeat({
    schedule: Schedule.spaced("2 seconds"),
    until: (r): boolean =>
      r.ProgressEvent?.OperationStatus !== "PENDING" &&
      r.ProgressEvent?.OperationStatus !== "IN_PROGRESS",
    times: 30,
  }),
);

ListResourceRequests

Source: src/AWS/CloudControl/ListResourceRequests.ts

Runtime binding for cloudformation:ListResourceRequests.

Lists resource operation requests made in the account and Region over the last 7 days — useful for surfacing in-flight or failed provisioning operations from a management Function.

ListResourceRequests: Tracking Requests

const listResourceRequests = yield* CloudControl.ListResourceRequests();

// runtime
const page = yield* listResourceRequests({
  ResourceRequestStatusFilter: { OperationStatuses: ["IN_PROGRESS"] },
  MaxResults: 20,
});

ListResources

Source: src/AWS/CloudControl/ListResources.ts

Runtime binding for cloudformation:ListResources.

Discovers resources of a given CloudFormation type in the account and Region — whether or not they were provisioned through Cloud Control. Because Cloud Control invokes the resource type’s list handler with the caller’s credentials, pass the handler’s underlying permissions via CloudControlBindingOptions.handlerPolicyStatements.

ListResources: Reading Resources

// init — account-level; grant the list handler's permissions too
const listResources = yield* CloudControl.ListResources({
  handlerPolicyStatements: [
    { Effect: "Allow", Action: ["ssm:DescribeParameters"], Resource: ["*"] },
  ],
});

// runtime
const page = yield* listResources({
  TypeName: "AWS::SSM::Parameter",
  MaxResults: 100,
});
const identifiers = (page.ResourceDescriptions ?? []).map((r) => r.Identifier);

Resource

Source: src/AWS/CloudControl/Resource.ts

A generic AWS resource managed through the Cloud Control API — the escape hatch that covers hundreds of CloudFormation resource types with a single Alchemy resource.

Provide a CloudFormation typeName and a desiredState object; the provider drives Cloud Control’s asynchronous create/update/delete and polls the request token (bounded) until it reaches SUCCESS, surfacing a FAILED operation as a typed error rather than hanging. Updates are expressed as an RFC 6902 JSON Patch computed over the keys you specify.

Resource: Managing a Resource

SSM Parameter

const param = yield* CloudControl.Resource("Greeting", {
  typeName: "AWS::SSM::Parameter",
  desiredState: {
    Name: "/app/greeting",
    Type: "String",
    Value: "hello",
  },
});
// param.identifier -> "/app/greeting"
// param.properties.Value -> "hello"

SNS Topic

const topic = yield* CloudControl.Resource("Alerts", {
  typeName: "AWS::SNS::Topic",
  desiredState: { TopicName: "alerts", DisplayName: "Alerts" },
});
// topic.identifier -> "arn:aws:sns:us-west-2:...:alerts"

UpdateResource

Source: src/AWS/CloudControl/UpdateResource.ts

Runtime binding for cloudformation:UpdateResource.

Applies an RFC 6902 JSON Patch to an existing resource’s properties. The call is asynchronous: poll the returned RequestToken with GetResourceRequestStatus until the operation settles. Because Cloud Control invokes the resource type’s update handler with the caller’s credentials, pass the handler’s underlying permissions via CloudControlBindingOptions.handlerPolicyStatements.

UpdateResource: Provisioning Resources

const updateResource = yield* CloudControl.UpdateResource({
  handlerPolicyStatements: [
    {
      Effect: "Allow",
      Action: ["ssm:PutParameter", "ssm:GetParameters"],
      Resource: ["*"],
    },
  ],
});

// runtime
const updated = yield* updateResource({
  TypeName: "AWS::SSM::Parameter",
  Identifier: "/tenants/acme/greeting",
  PatchDocument: JSON.stringify([
    { op: "replace", path: "/Value", value: "howdy" },
  ]),
});