`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

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 and lwc will use those options when compiling the composition as part of the run process.

Example lwcOptions field:

lwcOptions: --timeout=30 --no-color

The above example would set the compilation timeout at 30 seconds and disable colorized output for your target composition. 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.

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