Manage an AWS S3 Bucket

The simplest project that can be deployed with clusterless is one that manages an AWS S3 bucket.

In this example, we will create and destroy a bucket by declaring it in a project file.

Prerequisites

It is assumed the cls cli tool is installed. And that the current cloud placement has been bootstrapped.

AWS CLI

Some tasks in this example require the AWS cli (command line interface) to be installed. It can be found here: https://aws.amazon.com/cli/

To initialize a new project, in a new directory call:

$ cls show model --model deployable > project-bucket.json

project-bucket.json

{
  "project" : {
    "name" : null,
    "version" : null
  },
  "placement" : {
    "provider" : null,
    "stage" : null,
    "account" : null,
    "region" : null
  },
  "resources" : [ ],
  "activities" : [ ],
  "boundaries" : [ ],
  "barriers" : [ ],
  "arcs" : [ ]
}

A project declares what gets deployed and where it is deployed. A project has a name and version. The name should remain constant as the project changes between deployments. The version may change if you need to make incompatible changes and want to keep the previous version.

The name and version will be used when naming cloud resources. Keep the name short, and we suggest using a simple date format for the version.

The placement specifies where to make the deployment. In this guide, use aws as the provider.

Find your account information by calling aws sts get-caller-identity --profile <credential profile>.

stage is optional, but we suggest using dev for development, and prod for production when you are deploying into the same account and region.

Next we add a new resource to the resources declaration.

The S3 bucket resource component type is aws:core:s3Bucket.

To get the JSON model for this resource, call:

$ cls show component --model aws:core:s3Bucket --required

The --required flag causes only the required JSON properties to print.

{
  "type" : "aws:core:s3Bucket",
  "name" : null,
  "bucketName" : null
}

cls show … | pbcopy can be used on OSX to copy output to the clipboard.

Paste the results into the resources JSON property.

project-bucket.json

{
  "resources": [
    {
      "type" : "aws:core:s3Bucket",
      "name" : null,
      "bucketName" : null
    }
  ]
}

Set the name and bucketName values. Ensure the bucketName is globally unique to prevent a deployment failure.

Optionally, add and set removeOnDestroy (full model) to true, this will delete the bucket (and its contents) when we destroy the project.

To verify the project is valid, call:

$ cls verify -p project-bucket.json

Finally, to deploy the project:

$ cls deploy -p project-bucket.json

If an error states you need to bootstrap the region, call:

$ cls bootstrap

Learn more.

The following commands will list all currently deployed placements and projects:

$ cls placements
$ cls projects

Call the following aws cli command, if you have it installed, to confirm the bucket was created.

$ aws s3 ls

Otherwise, log into the AWS Console.

Finally, destroy the project.

$ cls destroy -p project-bucket.json

The bucket should be removed if removeOnDestroy was set to true.