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.
--account
Run the composition as a process in the target account. If option is omitted, Fugue runs the process in the default (Conductor) account.
-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.

Note: Fugue run will accept an RBAC policy composition or even a mixture of RBAC and standard library types, but it will have no effect.

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

Running a Process in a Specific Account

By default, Fugue will launch a process in the default (Conductor) account. To launch a process in a separate account, you must first add the account using the account command, as detailed here.

Then, use the --account parameter to specify the target account:

fugue run HelloWorld.lw --account web-1483046897738

Overriding the Run Command with Ludwig Compiler Options

It is possible to pass lwc options through the fugue.yaml file during run, overriding the usual process by which run compiles a composition. This is intended for internal or support use only.

To do this, create a lwcOptions field in fugue.yaml and include the arguments you wish to pass directly to the compiler, including the name of the composition (a required argument). lwc will use those options when compiling the composition as part of the run process.

Example lwcOptions field:

lwcOptions: --timeout=30 --no-color HelloWorld.lw

The above example would set HelloWorld.lw compilation timeout at 30 seconds and disable colorized output. For more information about lwc options, see Ludwig Compiler Options. For more information about lwcOptions, see init.

Note: The semantic backend does not affect the CLI run output, so passing an -s argument (for example, -s simple) through fugue.yaml will not produce semantic output.