Hello World, Part 2: Fugue Basics

Overview

This is Hello World, Part 2, where we explain the basics of using Fugue.

Next, in Part 3: Intro to Ludwig, we’ll explain line-by-line the composition you ran here.

Prerequisites

This example assumes that you’ve just finished Hello World, Part 1: Fugue Quick Setup. If you haven’t yet, you’ll need to do a few quick steps to set up the Fugue CLI and install the Fugue Conductor into your AWS account.

What We’ll Do In This Example

We’ll show you how to run your first composition with Fugue, which will create infrastructure in your AWS account. And you’ll learn how to use the following Fugue commands:

Note: Interested to know more about the rules when writing a composition? Check out details on Ludwig Grammar and Ludwig Syntax.

What We’ll Have When We’re Done

A Virtual Private Cloud (VPC) in AWS, complete with tags.

For a quick preview of this walkthrough, check out our video here.

How Long It Will Take

About 10-15 minutes.

Download

You can download the source code for this example here. Save it to the directory in which you ran fugue init during the Quick Setup.

Get editor plug-ins here.

Let’s Go!

Running the Hello World Composition

First off, let’s take a look at our Hello World composition:

composition

import Fugue.AWS as AWS
import Fugue.AWS.EC2 as EC2

#########################
# NETWORKS
#########################

hello-world-vpc: EC2.Vpc.new {
  cidrBlock: "10.0.0.0/16",
  tags: [hello-world-tag],
  region: AWS.Us-west-2,
}

hello-world-tag: AWS.tag("Application", "Hello World")

We’ve used Ludwig to define the infrastructure we want to create in our AWS account: a VPC with tags. Don’t worry about understanding the code just yet, since we explain it line by line in Part 3 of this tutorial. The important thing to know is that when we run this composition, Fugue will create this infrastructure.

Hop into your terminal and cd into the directory in which you saved HelloWorld.lw – it should be the same directory in which you ran fugue init.

Now we’re going to run our composition. When you run a composition, the Fugue Conductor launches a process, instantiating the infrastructure defined in the Ludwig. As long as a process is running, the Conductor maintains and monitors the infrastructure.

We’re going to use the -a option to assign the alias “HelloWorld” to our process, which gives us a convenient way to refer to it later.

Ready? Let’s run our composition:

fugue run -a HelloWorld HelloWorld.lw

You’ll get output that looks something like this:

[ fugue run ] Running <path>/HelloWorld.lw with the alias "HelloWorld"

Compiling Ludwig file <path>/HelloWorld.lw
[ OK ] Successfully compiled. No errors.

Uploading compiled Ludwig composition to S3...
[ OK ] Successfully uploaded.

Requesting the Conductor to create and run corresponding process...
[ DONE ] Process created and running. Details:

State    Updated    Created    FID                                   Alias       Last Message
-------  ---------  ---------  ------------------------------------  ----------  --------------
Running  1:18pm     1:18pm     16016246-b508-47e1-986d-b7fe306405d8  HelloWorld

[ HELP ] Run the 'fugue status' command to view details and status for all Fugue processes.

As you can see, the CLI compiled the composition and found no errors, uploaded the compiled composition to S3, asked the Conductor to create and run the process, and then returned some helpful information about our shiny new process.

We can access the information shown here – State, Updated, Created, FID, Alias, and Last Message – anytime we want by executing fugue status, which fetches the latest information available. For more information about these fields, see status.

Viewing Our New Infrastructure

Now that we have launched a process, let’s check out our new infrastructure in the AWS Management Console. Log in to the VPC dashboard for the us-west-2 (Oregon) region, then click “Your VPCs” in the sidebar.

Along with your default VPC, you should see a VPC called hello-world-vpc:

Hello World VPC in the AWS dashboard

Hello World VPC in the AWS dashboard.

And if you click on the “Tags” tab, you’ll see the Application and HelloWorld key/value pair defined in the composition. (Don’t worry; we explain this part in Part 3!)

Note: You’ll also see the “Fugue ID” tag, which is internal data you needn’t worry about. If you’re curious, though, the value is made up of two GUIDs separated by a period. The first GUID represents the process and the second GUID represents the resource itself.

Here’s how it looks:

Hello World VPC with tags in the AWS dashboard

Hello World VPC with tags in the AWS dashboard.

Neat, huh? It’s our composition brought to life: the instantiation of the resources declared in HelloWorld.lw.

Updating the Process

We’ve successfully launched a process. But what if you need to change something in the composition after you’ve run it? Simple – you can use the update command to modify a running process. We’ll demonstrate this by changing our VPC’s tags.

Open the HelloWorld.lw file in your favorite text editor and go to the last line (16). Change “Hello World” to “Hello Venus”. The line should now look like this:

hello-world-tag: AWS.tag("Application", "Hello Venus")

Save the file and return to your terminal, then execute update:

fugue update HelloWorld HelloWorld.lw

This command instructs the CLI to update the process aliased “HelloWorld” with the modified composition named HelloWorld.lw. Instead of an alias, we could have used the FID (Fugue ID) that the CLI output during fugue run. This is where setting an alias comes in handy – it’s much easier to remember a name than a long string of letters and numbers!

After you enter the command, the CLI will prompt you to confirm that you want to update the selected process, so enter y. When you’re done, you should see output resembling this:

[ fugue update ] Updating process with Alias: HelloWorld with <path>/HelloWorld.lw

[ WARN ] Are you sure you want to update the process with Alias: HelloWorld with <path>/HelloWorld.lw ? [y/N]: y

Compiling Ludwig file <path>/HelloWorld.lw ...
[ OK ] Successfully compiled. No errors.

Uploading compiled Ludwig composition to S3 ...
[ OK ] Successfully uploaded.

Requesting the Conductor to update process with composition ...
[ DONE ] Process with Alias: HelloWorld updated with composition.

[ HELP ] Run the 'fugue status' command to view details and status of this process update.

We can see that the CLI compiled the composition and found no errors, uploaded the compiled composition to S3, and asked the Conductor to update the process with that composition. Hooray!

Viewing Our Updated Infrastructure

Once again, let’s check out the AWS Management Console to see the fruits of our labor. Refresh the VPC dashboard and check out what the “Tags” tab says:

Hello World VPC with updated tags in the AWS dashboard

Hello World VPC with updated tags in the AWS dashboard.

There it is! Proof that we’ve updated our VPC’s tags from “Hello World” to “Hello Venus.”

Checking the Process’s Status

Any time you want a status report on a process, you can run the status command. Let’s try it now:

fugue status

You should see output resembling this:

Fugue Status Report for <user>/<account> - Thu Sep 15 2016 7:18pm

State    Updated    Created    FID                                   Alias       Last Message
-------  ---------  ---------  ------------------------------------  ----------  --------------
Running  6:52pm     1:18pm     16016246-b508-47e1-986d-b7fe306405d8  HelloWorld  SUCCESS

But what if you want more detailed information? That’s where fugue status <alias|FID> comes in. Let’s try that:

fugue status HelloWorld

The output should look a lot different. You’ll see a JSON document resembling this one:

{
    "alias": "HelloWorld",
    "created": 1473959920,
    "fid": "16016246-b508-47e1-986d-b7fe306405d8",
    "last_job_id": 1473981474,
    "last_message": "SUCCESS",
    "resources": {
        "vpcs": {
            "16016246-b508-47e1-986d-b7fe306405d8.72831793-e6e1-50b9-85a8-be63281fa003": {
                "region": "us-west-2",
                "resource": "vpc",
                "value": {
                    "CidrBlock": "10.0.0.0/16",
                    "DhcpOptionsId": "dopt-175bb772",
                    "InstanceTenancy": "default",
                    "IsDefault": false,
                    "State": "available",
                    "Tags": [
                        {
                            "Key": "Application",
                            "Value": "Hello Venus"
                        },
                        {
                            "Key": "Fugue ID",
                            "Value": "16016246-b508-47e1-986d-b7fe306405d8.72831793-e6e1-50b9-85a8-be63281fa003"
                        },
                        {
                            "Key": "Name",
                            "Value": "hello-world-vpc"
                        }
                    ],
                    "VpcId": "vpc-a9161bcd",
                    "timestamp": 1473981471
                }
            }
        }
    },
    "state": "BUSY",
    "updated": 1473979938
}

For more information about each field in this JSON object, see the status documentation.

Killing the Process

It’s about time to wrap up this walkthrough, so let’s terminate our process. Go back to your terminal and execute the kill command:

fugue kill HelloWorld

After you enter the command, the CLI will prompt you to confirm that you want to kill the selected process, so enter y. When you’re done, you should see output like this:

[ fugue kill ] Killing running process with Alias:HelloWorld

[ WARN ] Are you sure you want to kill the process with Alias: HelloWorld? [y/N]: y
Requesting the Conductor to kill running composition with Alias: HelloWorld...
[ Done ] The conductor is killing the process with Alias: HelloWorld

The Conductor is killing the process, which means it’s asking AWS to tear down the infrastructure we created (i.e., our tagged VPC). Execute status to check if the Conductor has successfully terminated the process:

fugue status

When the process has successfully been terminated, the status report will show that there are no processes running, and it’ll display this message:

Fugue Status Report for <user>/<account> - Fri Mar 17 2017 5:31pm

State    Updated    Created    Account    FID    Alias    Last Message    Next Command
-------  ---------  ---------  ---------  -----  -------  --------------  --------------
Nothing to see here. Go create something! :-)

Due to eventual consistency, it may take AWS another minute or two to actually finish destroying the process’s resources. Once again, you can confirm this in the VPC dashboard. When AWS is done cleaning up the resources, you’ll see that hello-world-vpc has disappeared, indicating that the kill has completed successfully.

You’re Done with Part 2!

Congratulations! You’ve just finished a successful end-to-end run with Fugue. You learned how to use run, update, status, and kill to create a tagged VPC in AWS, modify it, and destroy it, all from the comfort of your command line. You’re ready for the final part of this tutorial, Part 3!

Next Steps

Now that you’re done with Hello World, Part 2, continue the walkthrough with Hello World, Part 3: Intro to Ludwig. You’ll get a crash course in Ludwig as we explain the HelloWorld.lw composition line by line.

Alternatively, check out the other examples in our “Fake Book.” May we recommend our Building A Network walkthrough?

If you’re feeling adventurous, you can peruse the Standard Library Reference, open HelloWorld.lw in your text editor again, and try adjusting some of the settings.

And as always, reach out to support@fugue.co with any questions.