From 548e97d6de3ca15e7e1dfa0d2120484648d168a3 Mon Sep 17 00:00:00 2001 From: Donna Malayeri Date: Fri, 1 Jun 2018 11:38:58 -0700 Subject: [PATCH] Quickstart cleanup (#343) * Refactor tutorials: - Move images under main images folder - Move quickstart landing page contents to a new tutorial - List examples on QS landing page - Rename quickstart to "tutorials" * Add simple steps to tutorial landing page --- _data/quickstart.yaml | 7 +- .../quickstart/hello}/Quickstart1.png | Bin .../quickstart/hello}/Quickstart2.png | Bin .../quickstart/hello}/Quickstart3.png | Bin .../quickstart/hello}/Quickstart4.png | Bin .../quickstart/hello}/Quickstart5.png | Bin .../quickstart/hello}/Quickstart6.png | Bin .../quickstart/hello}/Quickstart7.png | Bin .../quickstart/s3-website.png | Bin .../quickstart}/url-shortener-diagram.graffle | Bin .../quickstart}/voting-app-webpage.png | Bin quickstart/aws-ec2.md | 111 +++++------- quickstart/aws-hello-world.md | 131 ++++++++++++++ quickstart/aws-s3-website.md | 109 +---------- quickstart/examples.md | 28 --- quickstart/index.md | 171 ++++-------------- 16 files changed, 214 insertions(+), 343 deletions(-) rename {quickstart/images => images/quickstart/hello}/Quickstart1.png (100%) rename {quickstart/images => images/quickstart/hello}/Quickstart2.png (100%) rename {quickstart/images => images/quickstart/hello}/Quickstart3.png (100%) rename {quickstart/images => images/quickstart/hello}/Quickstart4.png (100%) rename {quickstart/images => images/quickstart/hello}/Quickstart5.png (100%) rename {quickstart/images => images/quickstart/hello}/Quickstart6.png (100%) rename {quickstart/images => images/quickstart/hello}/Quickstart7.png (100%) rename quickstart/images/part2-website.png => images/quickstart/s3-website.png (100%) rename {quickstart/images => images/quickstart}/url-shortener-diagram.graffle (100%) rename {quickstart/images => images/quickstart}/voting-app-webpage.png (100%) create mode 100644 quickstart/aws-hello-world.md delete mode 100644 quickstart/examples.md diff --git a/_data/quickstart.yaml b/_data/quickstart.yaml index c455e7e559eb..3374b94622e1 100644 --- a/_data/quickstart.yaml +++ b/_data/quickstart.yaml @@ -1,12 +1,11 @@ -nav_section: "Quickstart" +nav_section: "Tutorials" toc: -- title: Quickstart +- title: Tutorials path: /quickstart/index section: + - quickstart/aws-hello-world.md - quickstart/aws-containers.md - quickstart/aws-rest-api.md - quickstart/aws-ec2.md - quickstart/aws-extract-thumbnail.md - quickstart/aws-s3-website.md - -- quickstart/examples.md diff --git a/quickstart/images/Quickstart1.png b/images/quickstart/hello/Quickstart1.png similarity index 100% rename from quickstart/images/Quickstart1.png rename to images/quickstart/hello/Quickstart1.png diff --git a/quickstart/images/Quickstart2.png b/images/quickstart/hello/Quickstart2.png similarity index 100% rename from quickstart/images/Quickstart2.png rename to images/quickstart/hello/Quickstart2.png diff --git a/quickstart/images/Quickstart3.png b/images/quickstart/hello/Quickstart3.png similarity index 100% rename from quickstart/images/Quickstart3.png rename to images/quickstart/hello/Quickstart3.png diff --git a/quickstart/images/Quickstart4.png b/images/quickstart/hello/Quickstart4.png similarity index 100% rename from quickstart/images/Quickstart4.png rename to images/quickstart/hello/Quickstart4.png diff --git a/quickstart/images/Quickstart5.png b/images/quickstart/hello/Quickstart5.png similarity index 100% rename from quickstart/images/Quickstart5.png rename to images/quickstart/hello/Quickstart5.png diff --git a/quickstart/images/Quickstart6.png b/images/quickstart/hello/Quickstart6.png similarity index 100% rename from quickstart/images/Quickstart6.png rename to images/quickstart/hello/Quickstart6.png diff --git a/quickstart/images/Quickstart7.png b/images/quickstart/hello/Quickstart7.png similarity index 100% rename from quickstart/images/Quickstart7.png rename to images/quickstart/hello/Quickstart7.png diff --git a/quickstart/images/part2-website.png b/images/quickstart/s3-website.png similarity index 100% rename from quickstart/images/part2-website.png rename to images/quickstart/s3-website.png diff --git a/quickstart/images/url-shortener-diagram.graffle b/images/quickstart/url-shortener-diagram.graffle similarity index 100% rename from quickstart/images/url-shortener-diagram.graffle rename to images/quickstart/url-shortener-diagram.graffle diff --git a/quickstart/images/voting-app-webpage.png b/images/quickstart/voting-app-webpage.png similarity index 100% rename from quickstart/images/voting-app-webpage.png rename to images/quickstart/voting-app-webpage.png diff --git a/quickstart/aws-ec2.md b/quickstart/aws-ec2.md index 5f48f553e6dc..b1f87d6d5df8 100644 --- a/quickstart/aws-ec2.md +++ b/quickstart/aws-ec2.md @@ -3,18 +3,20 @@ title: "Infrastructure on AWS" redirect_from: "/quickstart/part1.html" --- -In this tutorial, we'll use JavaScript to deploy a simple webserver EC2 instance in AWS. +In this tutorial, we'll use JavaScript to deploy a simple webserver EC2 instance in AWS. The [code for this tutorial](https://github.com/pulumi/examples/tree/master/aws-js-webserver) is available on GitHub. {% include aws-resource-note.md %} {% include aws-js-prereqs.md %} ## Create an EC2 instance with SSH access {#webserver} -1. In a new folder `webserver`, create an empty project with `pulumi new`: +1. In a new folder `webserver`, create an empty project with `pulumi new`. Be sure to use `us-east-1` as the region: ``` $ mkdir webserver; cd webserver - $ pulumi new javascript + $ pulumi new aws-javascript + ... + aws:region: (us-east-1) ``` 1. Open `index.js` and replace the contents with the following: @@ -23,7 +25,7 @@ In this tutorial, we'll use JavaScript to deploy a simple webserver EC2 instance const aws = require("@pulumi/aws"); let size = "t2.micro"; // t2.micro is available in the AWS free tier - let ami = "ami-7172b611"; // AMI for Amazon Linux in us-west-2 (Oregon) + let ami = "ami-6869aa05"; // AMI for Amazon Linux in us-west-1 (Virginia) let group = new aws.ec2.SecurityGroup("webserver-secgrp", { ingress: [ @@ -46,56 +48,43 @@ In this tutorial, we'll use JavaScript to deploy a simple webserver EC2 instance [aws.ec2.Instance][EC2 Instance], which is created in that security group using the appropriate Amazon Machine Image (AMI) for the region where you deploy the program. -1. Install the `@pulumi/aws` NPM package: +1. To preview and deploy changes, run `pulumi update`. The command shows a preview of the resources that will be created and prompts on whether to proceed with the deployment. Note that the stack itself is counted as a resource, though it does not correspond to a physical cloud resource. ```bash - $ npm install --save @pulumi/aws - ``` - -1. Configure the AWS region to deploy to, such as `us-west-2`. Use `pulumi config` to view the current stack's configuration values. - - ```bash - $ pulumi config set aws:region us-west-2 - ``` - -1. To preview and deploy changes, run `pulumi update`. The command shows a preview of the resources that will be created and prompts on whether to proceed with the deployment. Note that the stack itself is counted as a resource, though it does not correspond to a physical cloud resource. - - ``` $ pulumi update - Previewing stack 'webserver-testing' + Previewing update of stack 'webserver-dev' Previewing changes: - #: Resource Type Name Plan Extra Info - 1: pulumi:pulumi:Stack webserver-webserver-testing + create - 2: aws:ec2:SecurityGroup webserver-secgrp + create - 3: aws:ec2:Instance webserver-www + create - + Type Name Plan Info + + pulumi:pulumi:Stack webserver-webserver-dev create + + ├─ aws:ec2:SecurityGroup webserver-secgrp create + + └─ aws:ec2:Instance webserver-www create + info: 3 changes previewed: + 3 resources to create - - Do you want to proceed? - yes - no - details ``` 1. Now, proceed with the deployment, which takes about 30 seconds to complete. ``` - Do you want to proceed? yes - Updating stack 'webserver-testing' + Do you want to perform this update? yes + Updating stack 'ec2-quickstart-dev' Performing changes: - #: Resource Type Name Status Extra Info - 1: pulumi:pulumi:Stack webserver-webserver-testing + created - 2: aws:ec2:SecurityGroup webserver-secgrp + created - 3: aws:ec2:Instance webserver-www + created + Type Name Status Info + + pulumi:pulumi:Stack webserver-webserver-testing created + + ├─ aws:ec2:SecurityGroup webserver-secgrp created + + └─ aws:ec2:Instance webserver-www created + + ---outputs:--- + publicHostName: "ec2-34-224-93-18.compute-1.amazonaws.com" + publicIp : "34.224.93.18" info: 3 changes performed: + 3 resources created - Update duration: 24.875321975s + Update duration: 32.938640858s - Permalink: https://pulumi.com/lindydonna/-/-/webserver-testing/updates/1 + Permalink: https://pulumi.com/lindydonna/ec2-quickstart-dev/updates/3 ``` To see the full details of the deployment and the resources that are now part of the stack, open the update link in a browser. The **Resources** tab on pulumi.com has a link to the AWS console for the provisioned EC2 instance. @@ -157,50 +146,32 @@ Pulumi program to define the new state we want our infrastructure to be in, then defined in our program. We'll see in later sections how we can deploy and version the application code of our program in a variety of different ways using Pulumi. -1. Run `pulumi update` to see that two changes will be made when this is deployed. +1. Run `pulumi update` to preview and deploy the changes. You'll see two changes: the `ingress` property of the `SecurityGroup` will be _updated_ in-place. Second, the `Instance` will be _replaced_ with a new EC2 Instance which will run the new script on startup. Pulumi understands which changes to a given cloud resource can be made in-place, and which require replacement, and computes the minimally disruptive change to achieve the desired state. - ``` + ```bash $ pulumi update - Previewing stack 'webserver-testing' - Previewing changes: - - #: Resource Type Name Plan Extra Info - 1: pulumi:pulumi:Stack webserver-webserver-testing * no change - 2: aws:ec2:SecurityGroup webserver-secgrp ~ update changes: +-ingress - 3: aws:ec2:Instance webserver-www +-replace changes: + userData - - info: 2 changes previewed: - ~ 1 resource to update - +-1 resource to replace - 1 resource unchanged - - Do you want to proceed? - yes - > no - details - ``` - - We see that two changes will be applied. First, the `ingress` property of the `SecurityGroup` will be _updated_ in-place. Second, the `Instance` will be _replaced_ with a new EC2 Instance which will run the new - script on startup. Pulumi understands which changes to a given cloud resource can be made in-place, and which - require replacement, and computes the minimally disruptive change to achieve the desired state. - -1. Select "yes" to deploy the changes: + Previewing update of stack 'ec2-quickstart-dev' + ... - ``` - Do you want to proceed? yes - Updating stack 'webserver-testing' + Updating stack 'ec2-quickstart-dev' Performing changes: - #: Resource Type Name Status Extra Info - 1: pulumi:pulumi:Stack webserver-webserver-testing done - 2: aws:ec2:SecurityGroup webserver-secgrp ~ updated changes: +-ingress - 3: aws:ec2:Instance webserver-www +-replaced changes: + userData + Type Name Status Info + * pulumi:pulumi:Stack ec2-quickstart-ec2-quickstart-dev done + ~ ├─ aws:ec2:SecurityGroup webserver-secgrp updated changes: ~ ingress + +- └─ aws:ec2:Instance webserver-www replaced changes: + userData + + ---outputs:--- + publicHostName: "ec2-52-23-161-125.compute-1.amazonaws.com" + publicIp : "52.23.161.125" info: 2 changes performed: ~ 1 resource updated +-1 resource replaced 1 resource unchanged - Update duration: 1m15.29471554s + Update duration: 1m44.50461533s + + Permalink: https://pulumi.com/lindydonna/ec2-quickstart-dev/updates/6 ``` 1. We can use `pulumi stack output` to get the value of stack outputs from the CLI. So we can `curl` the EC2 instance to see the HTTP server running there. Stack outputs can also be viewed on the Pulumi Console. diff --git a/quickstart/aws-hello-world.md b/quickstart/aws-hello-world.md new file mode 100644 index 000000000000..677322252c31 --- /dev/null +++ b/quickstart/aws-hello-world.md @@ -0,0 +1,131 @@ +--- +title: Hello, World on AWS +--- + +In this tutorial, we'll use Pulumi to create a serverless single-page app that uses a AWS Lambda to change the content that is served. We'll do this with 5 lines of JavaScript, a few lines of configuration, and whatever static content we wish to serve (in this case, a simple HTML page and a favicon). + +{% include aws-resource-note.md %} + +## What we'll do + +- **Initialize** a new Pulumi project. +- **Define** our stack in JavaScript. +- **Deploy** our stack to AWS. +- **Manage** our stack in the Pulumi dashboard. +- Tear it down. + +{% include aws-js-prereqs.md %} + +## Initialize the project + +Create a new folder: + +``` +mkdir ahoy-pulumi && cd ahoy-pulumi +``` + +Now, let's use the Pulumi CLI to initialize a new project: + +``` +pulumi new hello-aws-javascript +``` + +You can accept the defaults for this command. For instance, you can change the AWS region to `us-west-2`. + +![Run Pulumi new](../images/quickstart/hello/Quickstart1.png){:width="700px"} + +After some dependency installations from NPM, you'll see a few files have been generated from this initialization process. + +![View files](../images/quickstart/hello/Quickstart2.png){:width="700px"} + +Let's look at some of those. + +- `Pulumi.yaml` defines the [project](../reference/project.html). +- `Pulumi.ahoy-pulumi-dev.yaml` is the [configuration file](../tour/basics-configuring.html) for the stack we initialized. +- `www` contains our sample static content. +- The key file for defining our stack resources `index.js` so let's examine that. + +## Define stack resources + +Normally, we'd write some code to define resources for our cloud stack, but in the quickstart this work is done for us. This is the content of `index.js`: + +```javascript +// Import the @pulumi/cloud-aws package +const cloud = require("@pulumi/cloud-aws"); + +// Create a public HTTP endpoint (using AWS APIGateway) +const endpoint = new cloud.HttpEndpoint("hello"); + +// Serve static files from the `www` folder (using AWS S3) +endpoint.static("/", "www"); + +// Serve a simple REST API on `GET /name` (using AWS Lambda) +endpoint.get("/source", (req, res) => res.json({name: "AWS"})) + +// Export the public URL for the HTTP service +exports.url = endpoint.publish().url; +``` + +See the [reference documentation](../reference/index.html) for details on the APIs we're using. + +## Deploy the stack + +The stack is ready to deploy, which is done as follows: + +```bash +pulumi update +``` + +This command instructs Pulumi to determine the resources needed to create the stack. First, a preview is shown of the changes that will be made: + +![Stack preview](../images/quickstart/hello/Quickstart3.png){:width="700px"} + +Choosing `yes` will create resources in AWS. This may take a minute or two. + +![Stack update](../images/quickstart/hello/Quickstart4.png){:width="700px"} + +Since there was a stack export (via `exports.url` in the code), this is printed in the output of `pulumi update`. We can easily `curl` this URL via `pulumi stack output`: + +```bash +curl $(pulumi stack output url) +``` + +For a more interesting view that shows the result of calling a Lambda function, open the page in a browser: + +![Stack page in browser](../images/quickstart/hello/Quickstart5.png){:width="600px"} + +## Manage the stack + +Our output also contained a permalink to the Pulumi dashboard. We can review the stack in the UI, and examine logs and resource usage, along with inviting friends and co-workers to collaborate on stacks. + +![](../images/quickstart/hello/Quickstart6.png){:width="600px"} + +## Tear Down + +To destroy resources, run the following: + +```bash +pulumi destroy +``` + +Once confirmed, Pulumi will remove all of the resources you've created. The stack itself is preserved in the Pulumi dashboard and is ready to go again as needed. + +![](../images/quickstart/hello/Quickstart7.png){:width="700px"} + +## Recap + +In this example we've seen: + +- How Pulumi makes the definition of cloud resources and stacks a highly productive, code-driven activity. +- How the Pulumi CLI can initialize, configure, deploy, and manage cloud stacks. +- How the Pulumi dashboard can log, monitor, and manage information about a cloud stack. + +## Next Steps + +From here, you can dive deeper: + +- Take [a tour of Pulumi](../tour/index.html). +- Try out these tutorials: + - [Create a serverless REST API](./aws-rest-api.html) + - [Host a static site on S3](./aws-s3-website.html) + - [Create EC2 instances on AWS](./aws-ec2.html) diff --git a/quickstart/aws-s3-website.md b/quickstart/aws-s3-website.md index 7b258bf2a142..403c8d7c6312 100644 --- a/quickstart/aws-s3-website.md +++ b/quickstart/aws-s3-website.md @@ -1,111 +1,14 @@ --- -title: "Host a Static Website on S3" +title: "Static Website on AWS S3" redirect_from: "/quickstart/part2.html" --- - -There are two ways to host a static website on S3 using Pulumi: you can use raw AWS resources to create a bucket and bucket objects, or you can use the higher-level `@pulumi/cloud-aws` package. +In this tutorial, we'll show how you can use [@pulumi/aws] to provision raw resources. First, we'll create a Pulumi program that uploads files from the `www` directory to S3. Then, we'll configure the bucket to serve a website. The [code for this tutorial][s3-folder] is available on GitHub. {% include aws-resource-note.md %} {% include aws-js-prereqs.md %} -## Option 1: Use the Pulumi Cloud framework {#pulumi-cloud} - -The [Pulumi Cloud] framework provides high-level components that encode common infrastructure and application patterns. Using the class [HttpEndpoint], you can create an AWS API Gateway resource that proxies requests to S3. - -1. In a new folder `cloud-static`, create an empty project with `pulumi new`: - - ```bash - $ mkdir cloud-static; cd cloud-static - $ pulumi new javascript - ``` - -1. Create some files in `www`: - - Create a subfolder of `cloud-static` called `www`. - - Download [favicon.png](/examples/favicon.png) and save it to `www`. - - In `www`, save the following as `index.html`: - - ```html - - Hello S3 - - -

Hello, world!

Made with ❤️ with Pulumi

- - ``` - -1. Replace the contents of `index.js` with the following: - - ```javascript - const cloud = require("@pulumi/cloud-aws"); - - const endpoint = new cloud.HttpEndpoint("cloud-static"); - endpoint.static("/", "www"); // Serve static files from the `www` folder, using S3 - - exports.url = endpoint.publish().url; // Export the public URL for the HTTP service - ``` - -1. Add and install the NPM dependencies: - - ```bash - $ npm install --save @pulumi/cloud-aws - ``` - -1. Run `pulumi update` to preview and deploy AWS resources. This creates a stack component, a Bucket, two S3 Objects (one for each file in the `www` folder), and several API Gateway resources. - - ```bash - $ pulumi update - Previewing update of stack 'cloud-static-dev' - ... - - Do you want to perform this update? yes - Updating stack 'cloud-static-dev' - Performing changes: - - Type Name Status Info - + pulumi:pulumi:Stack cloud-static-cloud-static-dev created - + └─ cloud:http:HttpEndpoint cloud-static created - + ├─ aws:s3:Bucket cloud-static created - + ├─ aws:iam:Role cloud-static4c238266 created - + ├─ aws:s3:BucketObject cloud-static4c238266/favicon.png created - + ├─ aws:s3:BucketObject cloud-static4c238266/index.html created - + ├─ aws:iam:RolePolicyAttachment cloud-static4c238266 created - + ├─ aws:apigateway:RestApi cloud-static created - + ├─ aws:apigateway:Deployment cloud-static created - + └─ aws:apigateway:Stage cloud-static created - - ---outputs:--- - url: "https://g8tc01nssk.execute-api.us-west-2.amazonaws.com/stage/" - - info: 10 changes performed: - + 10 resources created - Update duration: 13.403487743s - - Permalink: https://pulumi.com/lindydonna/cloud-static-dev/updates/1 - ``` - -1. Open the url shown in the "outputs" section to view the page and the favicon. - -1. To display just the endpoint that was created, run `pulumi stack output`. - - ```bash - $ pulumi stack output - Current stack outputs (1): - OUTPUT VALUE - url https://simc3a8ieg.execute-api.us-west-1.amazonaws.com/stage/ - ``` - -### Clean up - -{% include cleanup.md %} - -## Option 2: Configure AWS resources directly {#pulumi-aws} - -The Pulumi Cloud framework has been created as a higher-level abstraction over AWS resources. For full control over you resources, you can use [@pulumi/aws] directly. - -First, we'll create a Pulumi program that uploads files from the `www` directory to S3. Then, we'll configure the bucket to serve a website. - -### Create a bucket and upload files +## Create a bucket and upload files 1. In a new folder `s3website`, create an empty project with `pulumi new`: @@ -190,7 +93,7 @@ First, we'll create a Pulumi program that uploads files from the `www` directory 2018-04-17 15:40:48 249 index.html ``` -### Add S3 website support +## Add S3 website support In this section, we configure the S3 bucket to serve the files to a browser. To do this, we use the [aws.s3.Bucket.websites] property and attach an [aws.s3.BucketPolicy] object. @@ -266,9 +169,9 @@ In this section, we configure the S3 bucket to serve the files to a browser. To s3-website-bucket-8533d8b.s3-website-us-west-2.amazonaws.com ``` - ![Hello S3 example](images/part2-website.png){:width="700px"} + ![Hello S3 example](../images/quickstart/s3-website.png){:width="700px"} -### Clean up +## Clean up {% include cleanup.md %} diff --git a/quickstart/examples.md b/quickstart/examples.md deleted file mode 100644 index 5b12dad13f37..000000000000 --- a/quickstart/examples.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: "Example Code" ---- - -We have a number of examples in the [Pulumi examples repo](https://github.com/pulumi/examples) on GitHub. Below are some highlighted samples. If you don't have access to the GitHub repo, please email [support@pulumi.com](mailto:support@pulumi.com) to get access, or download the [Pulumi examples zipfile](/examples/pulumi-examples.zip). - -**Virtual machines** - -- [AWS EC2 instance (JavaScript)](https://github.com/pulumi/examples/tree/master/aws-js-webserver) -- [AWS EC2 instance (Python)](https://github.com/pulumi/examples/tree/master/aws-py-webserver) -- [Azure Virtual Machine (JavaScript)](https://github.com/pulumi/examples/tree/master/azure-js-webserver) - -**Containers** - -- [Voting app with two containers (TypeScript)](https://github.com/pulumi/examples/tree/master/cloud-ts-voting-app). -A simple voting app that uses Redis for a data store and a Python Flask app for the frontend. - -**Kubernetes** - -- [Kubernetes Guestbook (TypeScript)](https://github.com/pulumi/examples/tree/master/kubernetes-ts-guestbook). A version of the Kubernetes Guestbook app using Pulumi and `@pulumi/kubernetes`. - -**Serverless functions** - -- [URL Shortener (TypeScript)](https://github.com/pulumi/examples/tree/master/cloud-ts-url-shortener/). A complete URL shortener web application using high-level `cloud.Table` and `cloud.HttpEndpoint` components. -- [Video Thumbnailer (JavaScript)](https://github.com/pulumi/examples/tree/master/cloud-js-thumbnailer/). An end-to-end pipeline for generating keyframe thumbnails from videos uploaded to a bucket using containerized [FFmpeg](https://www.ffmpeg.org/). -- [Raw AWS Serverless (TypeScript)](https://github.com/pulumi/examples/tree/master/aws-ts-serverless-raw). A complete serverless application using raw `aws.apigateway.RestAPI`, `aws.lambda.Function` and `aws.dynamodb.Table` resources from `@pulumi/aws`. - - diff --git a/quickstart/index.md b/quickstart/index.md index 3332d0640804..fe4ad515d401 100644 --- a/quickstart/index.md +++ b/quickstart/index.md @@ -1,167 +1,62 @@ --- -title: Quickstart tutorials +title: Tutorials and examples --- - -[Pulumi examples repo]: https://github.com/pulumi/examples - - -In this quickstart, we'll use Pulumi to create a serverless SPA that uses a AWS Lambda to change the content that is served. We'll do this with 5 lines of JavaScript, a few lines of configuration, and whatever static content we wish to serve (in this case, a simple HTML page and a favicon). - -## Pulumi helps you get code to the cloud. Together. Faster. - -Pulumi is a set of tools and services to help Development and DevOps teams define, deploy, and manage cloud native infrastructure. - -Pulumi enables teams to define cloud native infrastructure in familiar languages (e.g. JavaScript, Python). So, you can be more productive and take advantage of your existing skills, rather than learn a new DSL. +Pulumi is a set of tools and services to help Development and DevOps teams define, deploy, and manage cloud native infrastructure. Pulumi enables teams to define cloud native infrastructure in familiar languages (e.g. JavaScript, Python). So, you can be more productive and take advantage of your existing skills, rather than learn a new DSL. -Pulumi enables teams to deploy cloud stacks to any cloud. It has high-level, cloud agnostic capabilities to "write once, run anywhere," but also has low-level, cloud-specific capabilities for full control of a chosen cloud stack. +## Get started with Pulumi -Pulumi enables teams to manage cloud native infrastructure with familiar code management and application lifecycle techniques. So, cloud native infrastructure defined in Pulumi can easily be incorporated into existing development and DevOps software delivery processes. +First, [configure AWS](../install/aws.html). Then, run the following commands: -## What we'll do - -- Install and configure Pulumi. -- **Initialize** a new Pulumi project. -- **Define** our stack in JavaScript. -- **Deploy** our stack to AWS. -- **Manage** our stack in the Pulumi dashboard. -- Tear it down. - -## First time using Pulumi? - -If so, then you need to install the CLI, and configure AWS. - -### Install Pulumi - -On Mac or Linux, run the following command: - -``` +```bash +# Step 1. Install Pulumi curl -fsSL https://get.pulumi.com | sh -``` - -On Windows, [follow these install instructions](../install#windows). - -### ⚠️ Prerequisites: configure AWS credentials - -Pulumi deploys to your AWS account, so [make sure you have configured the AWS CLI](../install/aws.html). - -## Initialize the project - -Create a new folder: -``` -mkdir ahoy-pulumi && cd ahoy-pulumi -``` - -Now, let's use the Pulumi CLI to initialize a new project: - -``` +# Step 2. Create a new project pulumi new hello-aws-javascript -``` - -You can accept the defaults for this command. For instance, you can change the AWS region to `us-west-2`. -![Run Pulumi new](./images/Quickstart1.png){:width="700px"} - -After some dependency installations from NPM, you'll see a few files have been generated from this initialization process. - -![View files](./images/Quickstart2.png){:width="700px"} - -Let's look at some of those. - -- `Pulumi.yaml` defines the [project](../reference/project.html). -- `Pulumi.ahoy-pulumi-dev.yaml` is the [configuration file](../tour/basics-configuring.html) for the stack we initialized. -- `www` contains our sample static content. -- The key file for defining our stack resources `index.js` so let's examine that. - -## Define stack resources - -Normally, we'd write some code to define resources for our cloud stack, but in the quickstart this work is done for us. This is the content of `index.js`: - -```javascript -// Import the @pulumi/cloud-aws package -const cloud = require("@pulumi/cloud-aws"); - -// Create a public HTTP endpoint (using AWS APIGateway) -const endpoint = new cloud.HttpEndpoint("hello"); - -// Serve static files from the `www` folder (using AWS S3) -endpoint.static("/", "www"); - -// Serve a simple REST API on `GET /name` (using AWS Lambda) -endpoint.get("/source", (req, res) => res.json({name: "AWS"})) - -// Export the public URL for the HTTP service -exports.url = endpoint.publish().url; -``` - -See the [reference documentation](../reference/index.html) for details on the APIs we're using. - -## Deploy the stack - -The stack is ready to deploy, which is done as follows: - -```bash +# Step 3. Deploy to the cloud pulumi update ``` -This command instructs Pulumi to determine the resources needed to create the stack. First, a preview is shown of the changes that will be made: - -![Stack preview](./images/Quickstart3.png){:width="700px"} - -Choosing `yes` will create resources in AWS. This may take a minute or two. - -![Stack update](./images/Quickstart4.png){:width="700px"} - -Since there was a stack export (via `exports.url` in the code), this is printed in the output of `pulumi update`. We can easily `curl` this URL via `pulumi stack output`: - -```bash -curl $(pulumi stack output url) -``` - -For a more interesting view that shows the result of calling a Lambda function, open the page in a browser: +## Featured tutorials -![Stack page in browser](./images/Quickstart5.png){:width="600px"} +- [Hello World](aws-hello-world.html). A simple single-page app that uses serverless functions. +- [Containers](aws-containers.html). Deploy an NGINX container to production in 5 minutes. +- [Serverless REST API](aws-rest-api.html). In just 20 lines of code, create a REST API that uses serverless functions and Dynamo DB. +- [Provision virtual machines on AWS](aws-ec2.html). Use JavaScript to create repeatable deployments of cloud infrastructure. +- [Create an application with serverless functions and containers](aws-extract-thumbnail.html). Create a full application that extracts a thumbnail from a video, using AWS Lambda and FFmpeg running in a Docker container. -## Manage the stack +## Examples -Our output also contained a permalink to the Pulumi dashboard. We can review the stack in the UI, and examine logs and resource usage, along with inviting friends and co-workers to collaborate on stacks. +We have a number of examples in the [Pulumi examples repo](https://github.com/pulumi/examples) on GitHub. Below are some highlighted samples. -![](./images/Quickstart6.png){:width="600px"} +If you don't have access to the GitHub repo, please email [support@pulumi.com](mailto:support@pulumi.com) to get access, or download the [Pulumi examples zipfile](/examples/pulumi-examples.zip). -## Tear Down +### Containers -To destroy resources, run the following: +- [Voting app with two containers (TypeScript)](https://github.com/pulumi/examples/tree/master/cloud-ts-voting-app). +A simple voting app that uses Redis for a data store and a Python Flask app for the frontend. -```bash -pulumi destroy -``` - -Once confirmed, Pulumi will remove all of the resources you've created. The stack itself is preserved in the Pulumi dashboard and is ready to go again as needed. - -![](./images/Quickstart7.png){:width="700px"} +### Serverless functions -## Recap +- [URL Shortener (TypeScript)](https://github.com/pulumi/examples/tree/master/cloud-ts-url-shortener/). A complete URL shortener web application using high-level `cloud.Table` and `cloud.HttpEndpoint` components. +- [Video Thumbnailer (JavaScript)](https://github.com/pulumi/examples/tree/master/cloud-js-thumbnailer/). An end-to-end pipeline for generating keyframe thumbnails from videos uploaded to a bucket using containerized [FFmpeg](https://www.ffmpeg.org/). +- [Raw AWS Serverless (TypeScript)](https://github.com/pulumi/examples/tree/master/aws-ts-serverless-raw). A complete serverless application using raw `aws.apigateway.RestAPI`, `aws.lambda.Function` and `aws.dynamodb.Table` resources from `@pulumi/aws`. -In this example we've seen: +### Infrastructure -- How Pulumi makes the definition of cloud resources and stacks a highly productive, code-driven activity. -- How the Pulumi CLI can initialize, configure, deploy, and manage cloud stacks. -- How the Pulumi dashboard can log, monitor, and manage information about a cloud stack. +- [AWS EC2 instance (Python)](https://github.com/pulumi/examples/tree/master/aws-py-webserver) +- [Azure Virtual Machine (JavaScript)](https://github.com/pulumi/examples/tree/master/azure-js-webserver) +- [Static website on AWS S3 (JavaScript)](https://github.com/pulumi/examples/tree/master/aws-js-s3-folder) -## Next Steps +### Kubernetes -From here, you can dive deeper: +- [Kubernetes Guestbook (TypeScript)](https://github.com/pulumi/examples/tree/master/kubernetes-ts-guestbook). A version of the Kubernetes Guestbook app using Pulumi and `@pulumi/kubernetes`. -- Take [a tour of Pulumi](../tour/index.html). -- Try out more quickstarts including: - - [Create a serverless REST API](./aws-rest-api.html) - - [Host a static site on S3](./aws-s3-website.html) - - [Create EC2 instances on AWS](./aws-ec2.html) -- View the [JavaScript API reference](../reference/). -## More Examples -We have a number of code examples available in the [Pulumi examples repo] on GitHub. If you don't have access to the GitHub repo, please email [support@pulumi.com](mailto:support@pulumi.com) to get access, or download the [Pulumi examples zipfile](/examples/pulumi-examples.zip). + +[Pulumi examples repo]: https://github.com/pulumi/examples + -To learn more, check out the [featured example list](./examples.html).