|
| 1 | +--- |
| 2 | +author: |
| 3 | + name: Linode |
| 4 | + email: docs@linode.com |
| 5 | +description: 'Learn how to install Pulumi, import the Linode module for Pulumi, and write your first Pulumi programs.' |
| 6 | +keywords: ["pulumi", "configuration management", "infrastructure as code", "iac", "javascript", "python"] |
| 7 | +license: '[CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0)' |
| 8 | +modified_by: |
| 9 | + name: Linode |
| 10 | +published: 2019-06-26 |
| 11 | +title: Getting Started with Pulumi |
| 12 | +external_resources: |
| 13 | +- '[Pulumi Documentation](https://pulumi.io/reference/)' |
| 14 | +- '[Pulumi API reference](https://pulumi.io/reference/pkg/)' |
| 15 | +- '[Why Pulumi](https://www.pulumi.com/why-pulumi/)' |
| 16 | +--- |
| 17 | + |
| 18 | +## What is Pulumi? |
| 19 | + |
| 20 | +[*Pulumi*](https://www.pulumi.com/) is a development tool that allows you to write computer programs which deploy cloud resources--a practice referred to as *infrastructure as code (IaC)*. Pulumi integrates with multiple cloud platforms, and Pulumi programs can be authored in a number of common programming languages. |
| 21 | + |
| 22 | +With Pulumi's Linode integration, you can manage your Linode resources as you would with our [API](https://developers.linode.com/api/v4/) or [CLI](/docs/platform/api/using-the-linode-cli/), but in a language you may already be familiar with. This guide will present examples written in JavaScript, but Pulumi is also compatible with Go, Python, and TypeScript. |
| 23 | + |
| 24 | +Pulumi also comes with a CLI interface for running the cloud infrastructure programs that you write. Once you've written a program, you can create your cloud resources with a single command: |
| 25 | + |
| 26 | + pulumi up |
| 27 | + |
| 28 | +In this guide you will learn how to: |
| 29 | + |
| 30 | +* [Install and set up Pulumi](#before-you-begin) on Debian 9 |
| 31 | +* [Create a single Linode instance](#create-a-linode) using Pulumi and JavaScript |
| 32 | +* [Create a NodeBalancer](#create-and-configure-a-nodebalancer) with two NGINX webserver backends using Pulumi and JavaScript |
| 33 | + |
| 34 | +## Before You Begin |
| 35 | + |
| 36 | +1. If you haven't yet, [create a Linode API token](/docs/platform/api/getting-started-with-the-linode-api/#create-an-api-token). |
| 37 | + |
| 38 | +1. [Create a free Pulumi account](https://app.pulumi.com/signup). |
| 39 | + |
| 40 | +1. Create a new Debian 9 Linode. Follow our [Getting Started](/docs/getting-started/) guide to deploy the Linode, and then follow the [Securing Your Server](/docs/security/securing-your-server/) guide. Be sure to create a [limited Linux user with sudo privileges](/docs/security/securing-your-server/#add-a-limited-user-account) on your server. All commands in this guide are to be run from a sudo user. |
| 41 | + |
| 42 | +1. Install Pulumi on your Linode using their installation script: |
| 43 | + |
| 44 | + curl -fsSL https://get.pulumi.com | sh |
| 45 | + |
| 46 | +1. To start using the Pulumi CLI: |
| 47 | + |
| 48 | + - Restart your shell session, or |
| 49 | + |
| 50 | + - Add `/home/username/.pulumi/bin` to your `$PATH` variable in your current session. Replace `username` with the name of your limited Linux user: |
| 51 | + |
| 52 | + PATH=$PATH:/home/username/.pulumi/bin |
| 53 | + |
| 54 | +1. Install [Node.js](https://nodejs.org/en/) and [npm](https://www.npmjs.com/): |
| 55 | + |
| 56 | + sudo apt-get install curl software-properties-common |
| 57 | + curl -sL https://deb.nodesource.com/setup_12.x | sudo bash - |
| 58 | + sudo apt-get install -y nodejs |
| 59 | + |
| 60 | +## Generate a Pulumi Access Token |
| 61 | + |
| 62 | +Once you have a Pulumi account, you will need to create an *access token* to use later. |
| 63 | + |
| 64 | +{{< disclosure-note "Why do I need a Pulumi access token?" >}} |
| 65 | +When Pulumi interprets the infrastructure programs that you write, it determines what cloud resources it needs to create in order to satisfy your program. Every time you run your program, [Pulumi stores the state](https://pulumi.io/reference/state/#state-and-backends) of these resources in a persistent backend. In subsequent updates to your infrastructure, Pulumi will compare your program with the recorded state so that it can determine which changes need to be made. |
| 66 | + |
| 67 | +By default, Pulumi securely stores this state information on a web backend hosted at [https://app.pulumi.com](https://app.pulumi.com). This service is free to start and offers paid tiers for teams and enterprises. |
| 68 | + |
| 69 | +It is possible to opt-out of using the default web backend and use a filesystem-based backend instead. Review [Pulumi's documentation](https://pulumi.io/reference/state/#to-the-filesystem-backend) for instructions. |
| 70 | +{{< /disclosure-note >}} |
| 71 | + |
| 72 | +1. [Log into your Pulumi account](https://app.pulumi.com/signin). After you've logged in, click on the avatar graphic to the top right of the Pulumi dashboard, then click on the **Settings** option in the dropdown menu that appears: |
| 73 | + |
| 74 | + [](pulumi-settings.png) |
| 75 | + |
| 76 | +1. Select the **Access Tokens** item in the sidebar to the left of the page that appears: |
| 77 | + |
| 78 | + [](pulumi-token.png) |
| 79 | + |
| 80 | +1. Click on the **New Access Token** button towards the top right of the following page and follow the prompts to create your new token. Make sure you save this in a secure location, similar to your Linode API token. |
| 81 | + |
| 82 | +## Create a Linode |
| 83 | + |
| 84 | +### Set up your Pulumi Project |
| 85 | + |
| 86 | +Now that you have everything you need to begin using Pulumi, you can create a new Pulumi *project*. |
| 87 | + |
| 88 | +{{< note >}} |
| 89 | +A Pulumi [project](https://pulumi.io/reference/project/) is the folder structure which contains your Pulumi programs. Specifically, a project is any folder which contains a `Pulumi.yaml` metadata file. |
| 90 | +{{< /note >}} |
| 91 | + |
| 92 | +1. Pulumi requires an empty directory for each new project, so first you'll need to create one and make it your working directory: |
| 93 | + |
| 94 | + cd ~/ && mkdir pulumi && cd pulumi |
| 95 | + |
| 96 | +1. Now that you're inside of your new empty working directory, create a new project: |
| 97 | + |
| 98 | + pulumi new |
| 99 | + |
| 100 | +1. From here, you'll see several prompts: |
| 101 | + |
| 102 | + - Enter your Pulumi access token if prompted. If you've already entered it at any point following the installation of Pulumi, you will not be prompted again and can skip this step. |
| 103 | + - Use your arrow keys to highlight the `linode-javascript` option. |
| 104 | + - Enter a project name of your choice, or leave blank to use the default option. |
| 105 | + |
| 106 | + - Enter a project description, or leave blank to use the default option. |
| 107 | + - Enter a *stack* name of your choice, or leave blank to use the default option. |
| 108 | + |
| 109 | + {{< disclosure-note "What's a stack?" >}} |
| 110 | +Multiple instances of your Pulumi programs can be created. For example, you may want to have separate instances for the development, staging, and production environments of your service. Or, you may create multiple instances of your service if you're offering it to different business clients. In Pulumi, these instances are referred to as [stacks](https://pulumi.io/tour/programs-stacks/). |
| 111 | +{{< /disclosure-note >}} |
| 112 | + |
| 113 | + - Enter your Linode API token. |
| 114 | + |
| 115 | +1. Once the installation is successful, you will see a `Your new project is ready to go!` message. The `pulumi new` command scaffolds a collection of default configuration files in your project's directory. The default configuration will give you everything you need to get started. Enter the `ls` command to ensure that the files are present: |
| 116 | + |
| 117 | + ls |
| 118 | + |
| 119 | + {{< output >}} |
| 120 | +index.js package.json Pulumi.pulumi.yaml |
| 121 | +node_modules package-lock.json Pulumi.yaml |
| 122 | +{{< /output >}} |
| 123 | + |
| 124 | + The contents of these files were defined according to our responses to each prompt after entering `pulumi new`. In particular: |
| 125 | + |
| 126 | + - `index.js` contains the JavaScript Pulumi will run |
| 127 | + - `package.json` defines the dependencies we can use and the file path Pulumi will be reading our code from. |
| 128 | + |
| 129 | +### Inspect the Default Configuration |
| 130 | + |
| 131 | +Let's take a look at the contents of our `index.js` file: |
| 132 | + |
| 133 | +{{< file "index.js" javascript >}} |
| 134 | +"use strict"; |
| 135 | +const pulumi = require("@pulumi/pulumi"); |
| 136 | +const linode = require("@pulumi/linode"); |
| 137 | + |
| 138 | +// Create a Linode resource (Linode Instance) |
| 139 | +const instance = new linode.Instance("my-instance", { |
| 140 | + type: "g6-nanode-1", |
| 141 | + region: "us-east", |
| 142 | + image: "linode/ubuntu18.04", |
| 143 | +}); |
| 144 | + |
| 145 | +// Export the Instance label of the instance |
| 146 | +exports.instanceLabel = instance.label; |
| 147 | +{{< /file >}} |
| 148 | + |
| 149 | +The file requires two JavaScript modules unique to Pulumi: Pulumi's SDK, and Pulumi's Linode integration. [Pulumi's API Reference Documentation](https://pulumi.io/reference/pkg/nodejs/pulumi/linode/) serves as a reference for the JavaScript you'll see here. It also includes a library of several additional options that enable you to create configurations more specific to your use case. |
| 150 | + |
| 151 | +In this case, your file is only creating a single Nanode instance in the Newark data center running Ubuntu 18.04. |
| 152 | + |
| 153 | +### Create and Destroy Resources |
| 154 | + |
| 155 | +- Use [Pulumi's `preview` command](https://pulumi.io/reference/cli/pulumi_preview/) to test your code and make sure it's successfully able to create resources under your account. |
| 156 | + |
| 157 | + pulumi preview |
| 158 | + |
| 159 | + The output of the command will list the operations Pulumi will perform once you deploy your program: |
| 160 | + |
| 161 | + Previewing update (dev): |
| 162 | + |
| 163 | + Type Name Plan |
| 164 | + + pulumi:pulumi:Stack my-pulumi-project-dev create |
| 165 | + + └─ linode:index:Instance my-instance create |
| 166 | + |
| 167 | + Resources: |
| 168 | + + 2 to create |
| 169 | + |
| 170 | +- Use [Pulumi's `up` command](https://pulumi.io/reference/cli/pulumi_up/) to deploy your code to your Linode account: |
| 171 | + |
| 172 | + pulumi up |
| 173 | + |
| 174 | + {{< note >}} |
| 175 | +This will create a new billable resource on your account. |
| 176 | +{{< /note >}} |
| 177 | + |
| 178 | + From here, you will be prompted to confirm the resource creation. Use your arrow keys to choose the `yes` option, hit `enter`, and you will see your resources being created. Once the process is completed, the Linode Label of your new Linode will be displayed. If you check your account manually through the [Cloud Manager](https://cloud.linode.com/), you can confirm that this Linode has been successfully created. |
| 179 | + |
| 180 | +- Since this Linode was only created as a test, you can safely delete it by entering [Pulumi's `destroy` command](https://pulumi.io/reference/cli/pulumi_destroy/): |
| 181 | + |
| 182 | + pulumi destroy |
| 183 | + |
| 184 | + Follow the prompts, and you'll be able to see the resources being removed, similar to how we could see them being created. |
| 185 | + |
| 186 | + {{< note >}} |
| 187 | +Many Pulumi commands will be logged on your Pulumi account. You can see this under the **Activity** tab of your project's stack in [Pulumi's Application Page](https://app.pulumi.com/). |
| 188 | +{{< /note >}} |
| 189 | + |
| 190 | +## Create and Configure a NodeBalancer |
| 191 | + |
| 192 | +To better demonstrate the power of Pulumi code, we'll create a new `index.js` file. This will define everything we need to create a functioning NodeBalancer which is pre-configured with two backend Linodes running NGINX. |
| 193 | + |
| 194 | +1. Replace the contents of your `index.js` file with the following: |
| 195 | + |
| 196 | + {{< file "index.js" javascript >}} |
| 197 | +const pulumi = require("@pulumi/pulumi"); |
| 198 | +const linode = require("@pulumi/linode"); |
| 199 | + |
| 200 | +// Create two new Nanodes using a StackScript to configure them internally. |
| 201 | +// The StackScript referenced will install and enable NGINX. |
| 202 | + |
| 203 | +// "linode1" (the first argument passed to the Linode instance constructor function) is the Pulumi-allocated Unique Resource Name (URN) for this resource |
| 204 | +const linode1 = new linode.Instance("linode1", { |
| 205 | + // "PulumiNode1" is the Linode's label that appears in the Cloud Manager. Linode labels must be unique on your Linode account |
| 206 | + label: "PulumiNode1", |
| 207 | + region: "us-east", |
| 208 | + image: "linode/debian9", |
| 209 | + privateIp: true, |
| 210 | + stackscriptData: { |
| 211 | + hostname: "PulumiNode1", |
| 212 | + }, |
| 213 | + stackscriptId: 526246, |
| 214 | + type:"g6-nanode-1", |
| 215 | +}); |
| 216 | + |
| 217 | +const linode2 = new linode.Instance("linode2", { |
| 218 | + label: "PulumiNode2", |
| 219 | + region: "us-east", |
| 220 | + image: "linode/debian9", |
| 221 | + privateIp: true, |
| 222 | + stackscriptData: { |
| 223 | + hostname: "PulumiNode2", |
| 224 | + }, |
| 225 | + stackscriptId: 526246, |
| 226 | + type:"g6-nanode-1", |
| 227 | +}); |
| 228 | + |
| 229 | +// Create and configure your NodeBalancer |
| 230 | + |
| 231 | +const nodeBalancer = new linode.NodeBalancer("nodeBalancer", { |
| 232 | + clientConnThrottle: 20, |
| 233 | + label: "PulumiNodeBalancer", |
| 234 | + region: "us-east", |
| 235 | +}); |
| 236 | + |
| 237 | +const nodeBalancerConfig = new linode.NodeBalancerConfig("nodeBalancerConfig", { |
| 238 | + algorithm: "source", |
| 239 | + check: "http", |
| 240 | + checkAttempts: 3, |
| 241 | + checkTimeout: 30, |
| 242 | + checkInterval: 40, |
| 243 | + checkPath: "/", |
| 244 | + nodebalancerId: nodeBalancer.id, |
| 245 | + port: 8088, |
| 246 | + protocol: "http", |
| 247 | + stickiness: "http_cookie", |
| 248 | +}); |
| 249 | + |
| 250 | +// Assign your Linodes to the NodeBalancer |
| 251 | + |
| 252 | +const balancerNode1 = new linode.NodeBalancerNode("balancerNode1", { |
| 253 | + address: pulumi.concat(linode1.privateIpAddress, ":80"), |
| 254 | + configId: nodeBalancerConfig.id, |
| 255 | + label: "PulumiBalancerNode1", |
| 256 | + nodebalancerId: nodeBalancer.id, |
| 257 | + weight: 50, |
| 258 | +}); |
| 259 | + |
| 260 | +const balancerNode2 = new linode.NodeBalancerNode("balancerNode2", { |
| 261 | + address: pulumi.concat(linode2.privateIpAddress, ":80"), |
| 262 | + configId: nodeBalancerConfig.id, |
| 263 | + label: "PulumiBalancerNode2", |
| 264 | + nodebalancerId: nodeBalancer.id, |
| 265 | + weight: 50, |
| 266 | +}); |
| 267 | + |
| 268 | +//Output your NodeBalancer's Public IPV4 address and the port we configured to access it |
| 269 | +exports.nodeBalancerIP = nodeBalancer.ipv4; |
| 270 | +exports.nodeBalancerPort = nodeBalancerConfig.port; |
| 271 | +{{< /file >}} |
| 272 | + |
| 273 | + {{< note >}} |
| 274 | +In our `index.js` file we've created and configured two Linodes using an existing [StackScript](/docs/platform/stackscripts/) which installs NGINX. Pulumi's Linode integration allows for the creation of entirely [new StackScripts](https://pulumi.io/reference/pkg/nodejs/pulumi/linode/#StackScript) directly in code, which can help you to automate your deployments even further. |
| 275 | + |
| 276 | +If you're interested in seeing how this StackScript works, you can view it [here](https://www.linode.com/stackscripts/view/526246). |
| 277 | +{{< /note >}} |
| 278 | + |
| 279 | +1. Now that you've successfully prepared your JavaScript code, let's bring up our configuration: |
| 280 | + |
| 281 | + pulumi up |
| 282 | + |
| 283 | + As before, select `yes` when prompted and wait for a few moments as your resources are created, configured, and brought online. |
| 284 | + |
| 285 | +1. Once the process is completed, you'll see your NodeBalancer's IP address and the port you configured earlier displayed as part of the output: |
| 286 | + |
| 287 | + Outputs: |
| 288 | + + nodeBalancerIP : "192.0.2.3" |
| 289 | + + nodeBalancerPort: 8088 |
| 290 | + |
| 291 | + Enter this IP address and port into your web browser, and you will see the *Hello World*-style page that the StackScript configured: |
| 292 | + |
| 293 | + curl http://192.0.2.3:8088/ |
| 294 | + |
| 295 | + {{< output >}} |
| 296 | +Hello from PulumiNode1 |
| 297 | +{{< /output >}} |
| 298 | + |
| 299 | + {{< note >}} |
| 300 | +If you do not see this page right away, you should wait a few additional moments. NodeBalancers can sometimes require a little extra time to fully apply a new configuration. |
| 301 | +{{< /note >}} |
| 302 | + |
| 303 | +1. Once you're finished with your NodeBalancer, you can remove and delete everything you added by entering `pulumi destroy` as before. |
| 304 | + |
| 305 | +## Next Steps |
| 306 | + |
| 307 | +Pulumi is a powerful tool with a vast number of possible configurations that can be applied. From here you can: |
| 308 | + |
| 309 | +* Look at Pulumi's [examples](https://github.com/pulumi/examples) for more ideas regarding the things you can do with Pulumi. |
| 310 | + |
| 311 | +* Try using Pulumi with different languages like [Python](https://pulumi.io/reference/python/) or [TypeScript](https://pulumi.io/reference/javascript/#typescript) |
| 312 | + |
| 313 | +* Import Node.js tools like [Express](https://expressjs.com/) for even more elasticity with your code. |
| 314 | + |
| 315 | +* Use Pulumi for [Serverless Computing](https://www.pulumi.com/serverless/) |
0 commit comments