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 YAML plan of the create, modify, and delete actions that would be executed on your infrastructure, allowing you to preview the changes before you make them.
--import
Run with the import flag
--json
Emit output as JSON. The JSON flag displays command output in JSON format, which is useful for automation.
--werror
Treats any lwc compiler warnings as an error and forces the CLI to exit.
-y | --yes
Suppress confirmation dialogs.
--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.

Note: When included, --werror will treat any lwc compiler warnings as errors and force the CLI to exit. This also applies with the use of the --yes, --json, or --dry-run options.

[ fugue run ] Running <composition name>

Run Details:
    Account: default
    Alias: <alias>

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 process based on composition ...

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

[ DONE ] Process created and running.

State    Updated    Created    Account              FID                                   Alias    Flags    Last Message    Next Command
-------  ---------  ---------  -------------------  ------------------------------------  -------  ------   --------------  --------------
Running  6:33pm     6:33pm     fugue-1505320402664  64fdfd36-9748-4503-8efa-c732384e3b52  hello    -e       SUCCEEDED

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 report 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.AWS as AWS
       Fugue.AWS.EC2 as EC2

#########################
# NETWORKS
#########################
my-example-vpc: EC2.Vpc.new {
  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 an invalid 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 a parsable YAML report that looks something like this.

Asking Fugue to execute a dry run of composition...

FID:   6006d525-501b-4770-8f87-173bfaa51ab3
JobId: '1500923972'

Requests:
  - aws.ec2.create_dhcp_options:
      Region: us-west-2
      Params:
        DhcpConfigurations:
        - Key: domain-name-servers
          Values:
          - AmazonProvidedDNS
        - Key: domain-name
          Values:
          - us-west-2.compute.internal
      References:
        DhcpOptionsId: C67gQRThKb

  - aws.ec2.create_tags:
      Region: us-west-2
      Params:
        Resources:
        - C67gQRThKb
        Tags:
        - Key:   Fugue ID
          Value: 6006d525-501b-4770-8f87-173bfaa51ab3.78a97f43-4a46-5ca0-9c91-75e232efd1ce
      References:
        DhcpOptionsId: C67gQRThKb

  - aws.ec2.create_vpc:
      Region: us-west-2
      Params:
        CidrBlock:       10.0.0.0/16
        InstanceTenancy: default
      References:
        DhcpOptionsId: cnnOQqitNc
        Vpc.VpcId:     DhzORTE21V

  - aws.ec2.associate_dhcp_options:
      Region: us-west-2
      Params:
        DhcpOptionsId: cnnOQqitNc
        VpcId:         DhzORTE21V
      References:
        DhcpOptionsId: cnnOQqitNc
        Vpc.VpcId:     DhzORTE21V

  - aws.ec2.modify_vpc_attribute:
      Region: us-west-2
      Params:
        EnableDnsSupport:
          Value: true
        VpcId: DhzORTE21V
      References:
        DhcpOptionsId: cnnOQqitNc
        Vpc.VpcId:     DhzORTE21V

  - aws.ec2.modify_vpc_attribute:
      Region: us-west-2
      Params:
        EnableDnsHostnames:
          Value: false
        VpcId: DhzORTE21V
      References:
        DhcpOptionsId: cnnOQqitNc
        Vpc.VpcId:     DhzORTE21V

  - aws.ec2.create_tags:
      Region: us-west-2
      Params:
        Resources:
        - DhzORTE21V
        Tags:
        - Key:   Fugue ID
          Value: 6006d525-501b-4770-8f87-173bfaa51ab3.636cfe20-9379-5066-9286-ee63acbd4c49
        - Key:   Name
          Value: my-example-vpc
      References:
        DhcpOptionsId: cnnOQqitNc
        Vpc.VpcId:     DhzORTE21V

The output is organized by AWS API requests that the Conductor would make if the run command was executed without --dry-run. In this case, there would be seven requests. Each request is listed with its region and parameters, which vary depending on the type of request.

You can also request the dry-run output as JSON by using the --json flag, which shows more detail. 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

Passing Ludwig Compiler Options to run

You can pass any lwc options to the Fugue CLI during run by following this format:

fugue run <composition.lw> -- <LWC_OPTIONS>

Just make sure that the lwc option(s) are after the --. For example, the following command disables color output by passing the lwc option --no-color:

fugue run MyComposition.lw -- --no-color

For a full list of lwc options, see The Ludwig Compiler.

Note: The FUGUE_LWC_OPTIONS environment variable has been deprecated. It is no longer a prerequisite for passing Ludwig options to the Fugue CLI.

Overriding a Binding During run

The lwc option --set allows you to selectively override bindings marked with an @override annotation. You can pass the --set option to fugue run so that Fugue creates a process using the new value(s):

fugue run <composition_file.lw> -- --set "<binding>: <value>"

Here’s an example that overrides the binding name with the value "Bob":

fugue run MyComposition.lw -- --set "name: 'Bob'"

Make sure that the lwc option --set comes after the -- and that the composition has the @override annotation:

composition

name: @override "Alice"

Let’s look at a real-world example. If your composition declares an EC2 instance with a certain AMI ID, you can override the AMI ID by passing a new value at the command line. Say your EC2 instance declaration looks like this:

instance: EC2.Instance.new {
  subnet: exampleSubnet,
  image: myAmiId,
  securityGroups: [exampleSecurityGroup],
  instanceType: EC2.T2_micro
}

myAmiId: @override "ami-a9d276c9"

The top-level binding myAmiId uses the AMI ID "ami-a9d276c9", which is an Ubuntu 16.04 image. Because the binding has the @override annotation, you can override it with another AMI ID when you execute fugue run.

So, if you want to launch a Red Hat Enterprise Linux 7.4 instance instead, you can use the --set option to specify a different AMI ID:

fugue run EC2Override.lw -- --set "myAmiId: 'ami-9fa343e7'"

Instead of launching an Ubuntu instance, the Conductor will launch an RHEL instance.

Note: You can override more than one binding when executing fugue run. Just use the --set option for each binding.

For more information on overrides, see Overriding a binding in a composition.

Using fugue.yaml to Pass Ludwig Compiler Options to run

Warning

The lwcOptions field in fugue.yaml has been deprecated. Instead, pass lwc options directly to the Fugue CLI during fugue run. Find more details here.

Running a Fugue Import

To run a Fugue import, simply use the --import flag after specifying the target composition, which designates the existing infrastructure you want Fugue to manage.

fugue run mycomposition.lw --import