pulumi/docs/demo.md

# Lumi Getting Started Demo Script

## Part 1: EC2 Instances and programming with Lumi

We can start with an empty Lumi script.  We've imported the AWS package.

```typescript
import * as aws from "@lumi/aws";

```

We can use completion lists to explore the AWS API for EC2 instances.


```typescript
import * as aws from "@lumi/aws";

let instance = new aws.ec2.Instance("nano", {

})
```

We see we get an error telling us we need to provide an `imageId`.  We don't want to hardcode one in, so let's just use
a helper function to get the right Amazon Linux AMI for the instance type we want.

```typescript
import * as lumi from "@lumi/lumi";
import * as aws from "@lumi/aws";

let instance = new aws.ec2.Instance("nano", {
    imageId: aws.ec2.getLinuxAMI("t2.nano"),
    instanceType: "t2.nano",
});
```

Let's try this out:

```bash
$ lumijs && lumi deploy
Deploying changes:
Applying step #1 [create]
+ aws:ec2/instance:Instance:
      [urn=test::aws/minimal:index::aws:ec2/instance:Instance::nano]
      imageId         : "ami-6869aa05"
      instanceType    : "t2.nano"
      name            : "nano"
info: resource[aws].stdout: Creating new EC2 instance resource
info: resource[aws].stdout: EC2 instance 'i-05e52d6e8b45f1a90' created; now waiting for it to become 'running'
1 total change:
    + 1 resource created
Deployment duration: 17.435391998s
```

But we can also refactor this a bit.

```typescript
import * as lumi from "@lumi/lumi";
import * as aws from "@lumi/aws";

let instanceType: aws.ec2.InstanceType = "t2.nano";

let instance = new aws.ec2.Instance("nano", {
    imageId: aws.ec2.getLinuxAMI(instanceType),
    instanceType: instanceType,
});
```

Or even:

```typescript
import * as lumi from "@lumi/lumi";
import * as aws from "@lumi/aws";

funtion makeInstance(instanceType: aws.ec2.InstanceType): aws.ec2.Instance {
    return new aws.ec2.Instance("nano", {
        imageId: aws.ec2.getLinuxAMI(instanceType),
        instanceType: instanceType,
    });
}

let instance = makeInstance("t2.nano")
```

And if we now redeploy - even though we refactored things - Lumi understands that no changes are
needed to our infrastructure.

```bash
$ lumijs && lumi deploy
Deploying changes:
info: no resources need to be updated
```

We can also add custom checks and validation - for example, make sure we don't create any expensive
EC2 instances.

```typescript
import * as aws from "@lumi/aws";


function makeInstance(instanceType: aws.ec2.InstanceType): aws.ec2.Instance {
    if (instanceType !== "t2.micro" && instanceType !== "t2.nano") {
        throw new Error("Too rich for my blood!")
    }
    return new aws.ec2.Instance("micro", {
        imageId: aws.ec2.getLinuxAMI(instanceType),
        instanceType: instanceType,
    });
}

let instance = makeInstance("t2.xlarge");
```

And now if we deploy something too expensive, we get an error.

```bash
$ lumijs && lumi deploy
error LUMI1001: An unhandled exception in aws/minimal:index's initializer occurred:
	@lumijs:lib/errors:Error{
	    name: "Error"
	    message: "Too rich for my blood!"
	}
	at aws/minimal:index:makeInstance(string)aws:ec2/instance:Instance in index.ts(8,9)
	at aws/minimal:index:.init() in index.ts(16,16)
```

But if we change that to a `t2.micro`, we see Lumi replaces the resource for us, and will cascade this impact
on other resources which depend on this instance resource as needed.

```typescript
import * as aws from "@lumi/aws";


function makeInstance(instanceType: aws.ec2.InstanceType): aws.ec2.Instance {
    if (instanceType !== "t2.micro" && instanceType !== "t2.nano") {
        throw new Error("Too rich for my blood!")
    }
    return new aws.ec2.Instance("micro", {
        imageId: aws.ec2.getLinuxAMI(instanceType),
        instanceType: instanceType,
    });
}

let instance = makeInstance("t2.micro");
```


```bash
$ lumijs && lumi deploy
Deploying changes:
Applying step #1 [replace-create] (part of a replacement change)
~+aws:ec2/instance:Instance:
      [urn=test::aws/minimal:index::aws:ec2/instance:Instance::micro]
      imageId         : "ami-6869aa05"
      instanceType    : "t2.micro"
      name            : "micro"
info: resource[aws].stdout: Creating new EC2 instance resource
info: resource[aws].stdout: EC2 instance 'i-012cfca6b7dbc9212' created; now waiting for it to become 'running'
Applying step #2 [replace]
-+aws:ec2/instance:Instance:
      [id=arn:aws:ec2:us-east-1:490047557317:instance:i-05bb64cb057939895]
      [urn=test::aws/minimal:index::aws:ec2/instance:Instance::micro]
      imageId     : "ami-6869aa05"
    - instanceType: "t2.nano"
    + instanceType: "t2.micro"
      name        : "micro"
Applying step #3 [replace-delete] (part of a replacement change)
~-aws:ec2/instance:Instance:
      [id=arn:aws:ec2:us-east-1:490047557317:instance:i-05bb64cb057939895]
      [urn=test::aws/minimal:index::aws:ec2/instance:Instance::micro]
      imageId     : "ami-6869aa05"
      instanceType: "t2.nano"
      name        : "micro"
info: resource[aws].stdout: Terminating EC2 instance 'arn:aws:ec2:us-east-1:490047557317:instance:i-05bb64cb057939895'
info: resource[aws].stdout: EC2 instance termination request submitted; waiting for it to terminate
1 total change:
    -+1 resource replaced
Deployment duration: 1m39.704930817s
```

## Part 2: Serverless resources and higher-level abstractions

In the first step, we looked at using Lumi to program raw infrastructue.  But we can apply Lumi to any programable 
infrastructure, including higher-level hosted Cloud services.  In particular, we can work with Serverless
resources like Tables, Functions and APIs.

Let's start by looking at how we can program the raw AWS resources.  We can create a simple lambda function.

```typescript
import * as aws from "@lumi/aws";

let policy = {
  "Version": "2012-10-17",
  "Statement": [
    {
      "Action": "sts:AssumeRole",
      "Principal": {
        "Service": "lambda.amazonaws.com"
      },
      "Effect": "Allow",
      "Sid": ""
    }
  ]
}

let role = new aws.iam.Role("mylambdarole", {
  assumeRolePolicyDocument: policy,
  managedPolicyARNs: [aws.iam.AWSLambdaFullAccess],
});

let lambda = new aws.lambda.Function("mylambda", {
  code: new lumi.asset.AssetArchive({
    "index.js": new lumi.asset.String("exports.handler = (ev, ctx, cb) => cb('Hello, world!');"),
  }),
  role: role,
  handler: "index.handler",
  runtime: aws.lambda.NodeJS6d10Runtime,
});
```

The resources in use here will be familiar to anyone who has worked with AWS Lambda functions before, but there are a
few nice things to notice about the Lumi programming model.  
* We can write JSON inline, and could even compose JSON object nicely as objects instead of strings within Lumi.  
* There are named constants available to refer to the known managed IAM policies.
* We could pass a .zip file on disk directly, but we can also describe the contents of the archive directly as a map
  from filenames to file contents.

But there's still a bit of boilerplate here.  So we can provide higher-level abstractions.  For example, there is an
`aws.serverless` module available with a higher-level Function abstraction.

```typescript
import * as aws from "@lumi/aws";

let lambda = new aws.serverless.Function(
  "mylambda",
  { policies: [aws.iam.AWSLambdaFullAccess] },
  (ev, ctx, cb) => {
    callback(null, "Succeeed with " + ctx.getRemainingTimeInMillis() + "ms remaining.");
  }
)
```

Note that we've simplified the API a little - the default policy document is inferred, and the managed IAM policies
to apply are provided directly to the `aws.serverless.Function` component.  But more importantly, instead of 
providing a string of text for the body of the Lambda, we provide an actual LumiJS arrow function.  This function code 
will when the lambda is invoked, not during deployment.  But the code can be authored, versioned and maintained along
with the rest of the infrastructure it needs.

It can even reference captured variables:


```typescript
import * as aws from "@lumi/aws";

let hello = "Hello, world!"

let lambda = new aws.serverless.Function(
  "mylambda",
  { policies: [aws.iam.AWSLambdaFullAccess] },
  (ev, ctx, cb) => {
    console.log(hello);
    callback(null, "Succeeed with " + ctx.getRemainingTimeInMillis() + "ms remaining.");
  }
)
```

We can test this out:

```bash
$ export LAMBDA=<insert lambda name from lumi deploy output here>
$ aws lambda invoke --function-name $LAMBDA --log-type Tail out.txt | jq '.LogResult' -r | base64 --decode
START RequestId: 5a948c10-4fbc-11e7-bb4f-6d1f9cca5a26 Version: $LATEST
2017-06-12T22:13:25.352Z	5a948c10-4fbc-11e7-bb4f-6d1f9cca5a26	Hello, world!
END RequestId: 5a948c10-4fbc-11e7-bb4f-6d1f9cca5a26
REPORT RequestId: 5a948c10-4fbc-11e7-bb4f-6d1f9cca5a26	Duration: 20.47 ms	Billed Duration: 100 ms 	Memory Size: 128 MB	Max Memory Used: 17 MB```
```