run

Usage

fugue [global options] run [options] <composition_file.lw>

Arguments

composition_file
Composition file to be run.

Options

Global options are detailed here.

-a NAME | --alias NAME
An alias to associate with a Fugue process
--dry-run
Execute a “dry-run” of a composition run (output plan of operations). The dry-run flag allows you to see how AWS will provision your infrastructure in a composition using run, update, resume, or kill without actually executing the command. The Fugue CLI outputs a JSON document of the create, modify, and delete actions that would be executed on your infrastructure, allowing you to preview the changes before you make them.
--json
Emit output as JSON. The JSON flag displays command output in JSON format, which is useful for automation.
-h | --help
Show help text. The help flag is available throughout the CLI in both an application-level and command-level context. It enables a user to view help text for any command within the Fugue CLI.

Definition

The run command launches a Fugue composition as a process.

The command executes in several phases. It first compiles the composition and reports any errors.

[ fugue run ] Running <composition name>

Compiling Ludwig file <composition name>
[ OK ] Successfully compiled. No errors.

Second, run uploads the compiled composition to AWS.

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

Then, run sends a request to the Fugue Conductor to launch an instance of the composition, called a process.

Requesting the Conductor to create and run corresponding process...

Finally, run displays a success message containing coarse process status information.

[ DONE ] Process created and running. Details:

State    Updated    Created    FID                                   Alias    Last Message
-------  ---------  ---------  ------------------------------------  -------  --------------
Running  5:36pm     5:36pm     f75839f3-5924-4045-838d-21580e2c8fc6  test

As long as the process is running, the infrastructure declared in its composition is monitored and maintained.

The run command is not idempotent. Running the same composition more than once launches a process for each run attempt, and Fugue builds declared infrastructure in the composition for each process.

Examples

Associating An Alias With A Fugue Process

If you want to assign a human-friendly name to a Fugue process, you can use the run command with the -a or --alias flag and the desired alias as an argument.

$ fugue run -a myStuff composition.lw

Once an alias has been defined with run, that alias may be used in place of a FID wherever a FID is expected.

For example, you can use an alias with status to return the status of only that process.

$ fugue status myStuff

An alias must meet the following criteria:

  • It must be unique. If an alias already exists, the Fugue CLI returns an error.
  • It must not match the format of a UUID (i.e., 00000000-0000-0000-0000-000000000000).

Using --dry-run To Preview run Changes To Your Infrastructure

In Fugue, a dry-run attempts to test an action through progressive parts of the system, returning either failures encountered, or the expected results of success. This allows you to see how Fugue will provision your infrastructure in a composition using run, update, resume, or kill without actually executing the command. You can see this in the output of a dry-run, which is a JSON document describing the create, modify, and delete actions that would be executed on your infrastructure.

Some update operations are mutative, meaning the resource can be changed with “modify” actions, and some update operations are destructive, meaning the resource must be destroyed and created anew with “delete” and “create” actions. You can often determine whether an update is mutative or destructive based on the RequestType in the dry-run document.

You can execute run with the --dry-run flag to see either a plan of operations or an error.

$ fugue run --dry-run [composition]

Say you have a composition named vpc-only.lw.

composition

import Fugue.Core.AWS.Common as AWS
       Fugue.Core.AWS.EC2 as EC2

#########################
# NETWORKS
#########################
my-example-vpc: EC2.Vpc({
  cidrBlock: "10.0.0.0/16",
  tags: [],
  instanceTenancy: EC2.DefaultTenancy,
  region: AWS.Us-west-52,
  dhcpOptions: None
})

You can use the --dry-run flag with the run command to see what Fugue will do with this command.

$ fugue run --dry-run vpc-only.lw

The first step of the dry-run is compilation with the Ludwig compiler. If the composition cannot be compiled, Fugue returns a helpful error. Here, the composition vpc-only.lw contains a nonexisting AWS region, region: AWS.Us-west-52, so running fugue run vpc-only.lw --dry-run produces the following error.

[ ERROR ] Error compiling Ludwig composition:

ludwig (scope error):
  "<path>/vpc-only.lw" (line 13, column 11):
  Not in scope:

    13|   region: AWS.Us-west-52,
                  ^^^^^^^^^^^^^^

  Constructor not in scope: AWS.Us-west-52
  Hint: perhaps you mean the constructor AWS.Us-west-2 (from Fugue.Core.AWS.Common)

We can correct this error and try another dry-run.

sed -i 's/Us-west-52/Us-west-2/g' vpc-only.lw

Now, a new dry-run takes a bit longer. The Fugue CLI passes the compilation phase, and uploads the composition to the Conductor for processing. Finally, the CLI returns raw JSON that looks something like this.

{
    "fid": "20a2db11-4c52-472c-a27c-b9c974ae73f2",
    "job_id": "1470926532",
    "requests": [
        {
            "guid": "20a2db11-4c52-472c-a27c-b9c974ae73f2.05ab3004-7d26-50d7-8908-4a7d0f7918c4",
            "guidMap": {
                "20a2db11-4c52-472c-a27c-b9c974ae73f2.05ab3004-7d26-50d7-8908-4a7d0f7918c4": "3cB8Po5n5f"
            },
            "params": {
                "CidrBlock": "10.0.0.0/16",
                "InstanceTenancy": "default"
            },
            "region": "us-west-2",
            "request_type": "aws.ec2.create_vpc"
        },
        {
            "guid": "20a2db11-4c52-472c-a27c-b9c974ae73f2.05ab3004-7d26-50d7-8908-4a7d0f7918c4.tags",
            "guidMap": {
                "20a2db11-4c52-472c-a27c-b9c974ae73f2.05ab3004-7d26-50d7-8908-4a7d0f7918c4": "3cB8Po5n5f"
            },
            "params": {
                "Resources": [
                    "3cB8Po5n5f"
                ],
                "Tags": [
                    {
                        "Key": "Name",
                        "Value": "my-example-vpc"
                    },
                    {
                        "Key": "Fugue ID",
                        "Value": "20a2db11-4c52-472c-a27c-b9c974ae73f2.05ab3004-7d26-50d7-8908-4a7d0f7918c4"
                    }
                ]
            },
            "region": "us-west-2",
            "request_type": "aws.ec2.create_tags"
        }
    ]
}

The request_type field describes each AWS API call the Conductor would make if the run command was executed without --dry-run.

JSON Object Fields in a Dry-Run

job_id
Unique ID for the dry-run operation
requests
Array of params, guid, guidMap, region, request_type per each API request in the dry-run operation
params
Dictionary of arguments passed to the AWS API in order to create, modify, or delete the resources
guid
Globally unique ID for the resource being acted upon. NOTE: guid is not unique for resource properties (e.g., tags, security group rules, routes)
guidMap
A unique token that maps to the guid and resource reference string
region
AWS region; see list of valid codes in AWS docs
request_type
Type of request for an AWS API action in aws.service.action_resource format
fid
Fugue ID, or the process’s unique identifier