update

Usage

fugue [global options] update [options] <alias | FID> <composition_file.lw>

Arguments

<alias> | <FID>
Alias or FID of the process to update
<composition_file>
Composition file to update the process with

Options

Global options are detailed here.

--dry-run
Execute a “dry-run” of a process update (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.
-y | --yes
Suppress confirmation dialogs. The yes flag suppresses confirmation dialogs and bypasses interactive prompts by providing input to aid scripting.
--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.
-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 update command updates the infrastructure of a running process to match the infrastructure specified in a given composition.

When the update command is executed, the CLI does the following:

  • Compiles the composition and reports any errors
  • Uploads the compiled composition to an S3 bucket
  • Sends a request to the Conductor to update the process’s infrastructure

/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.

The Fugue Conductor then does the following:

  • Compares the process’s infrastructure to the infrastructure declared in the compiled, updated composition
  • Determines the infrastructure operations required to make the process match the composition
  • Performs the infrastructure operations

Updates may be destructive or mutative. A destructive update is one in which the resource properties cannot be changed, so the entire resource is destroyed and replaced with a new one (e.g., a VPC CIDR block). A mutative update is an update-in-place for resource properties that can be changed (e.g., VPC tags).

Examples

Modifying A Composition After It Has Been Run

If you need to add, modify, or delete a resource declared in a composition you have already run, you can edit the composition and execute update on the process. This lets you update the process’s resources on the fly.

For example, suppose you have already run the composition vpc-only.lw with the alias staging, but you need to update the name of the VPC:

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-2,
  dhcpOptions: None
}

You can change the name of the variable in the vpc-only.lw file from my-example-vpc to my-updated-vpc, then use the update command to make the name change take effect.

$ fugue update staging vpc-only.lw

The Fugue CLI prompts the user to confirm the update, and then the CLI indicates that it is compiling and uploading the composition to S3. Finally, the CLI returns a success message.

[ fugue update ] Updating process with Alias: staging with <path>/vpc-only.lw

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

Compiling Ludwig file <path>/vpc-only.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: staging updated with composition.

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

The updated infrastructure is enforced and maintained as long as the process is running.

Using --dry-run To Preview Update 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.

Suppose you have already run the composition vpc-only.lw with the alias staging, but you need to update the name of the VPC:

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-2,
  dhcpOptions: None
}

You can change the name of the variable in the vpc-only.lw file from my-example-vpc to my-updated-vpc, then use the update command with the --dry-run flag to see what AWS resources would be modified.

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

The CLI returns a parsable YAML report that looks something like this:

FID:   0b5df338-8e5d-45f2-9fc5-28fbb7ab29cd
JobId: '1500929505'

Requests:
  - aws.ec2.create_tags:
      Region: us-west-2
      Params:
        Resources:
        - vpc-2b3dee4d
        Tags:
        - Key:   Name
          Value: my-updated-vpc

The output is organized by AWS API requests that the Conductor would make if the update command was executed without --dry-run. In this case, there would be one request: a call to create a new set of tags for the VPC with the ID vpc-2b3dee4d in us-west-2.

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 update 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

Setting FUGUE_LWC_OPTIONS to Pass Ludwig Compiler Options to update

You can pass lwc options to the Fugue CLI during update by using the FUGUE_LWC_OPTIONS environment variable.

First, set the environment variable FUGUE_LWC_OPTIONS to yes or true:

export FUGUE_LWC_OPTIONS=yes

You can then pass any lwc option to update, like so:

fugue update <alias|FID> <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 update myProcess MyComposition.lw -- --no-color

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

Overriding a Binding During update

If you’ve exported the FUGUE_LWC_OPTIONS environment variable, you can override bindings marked with an @override annotation when you update a process.

The lwc option --set allows you to selectively override bindings marked with an @override annotation. If you’ve exported the FUGUE_LWC_OPTIONS environment variable, you can pass the --set option to fugue update. After the composition compiles, Fugue updates the process using the overriding binding. This enables you to update a process without having to modify its composition.

fugue update <alias|FID> <composition.lw> -- --set "<binding>: <value>"

For example, if your composition declares a VPC with DNS support enabled, you can override the DNS support setting by passing a new value at the command line when you update the process.

Say your VPC composition looks like this:

composition

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

exampleVpc: EC2.Vpc.new {
  cidrBlock: "10.0.0.0/16",
  region: AWS.Us-west-2,
  enableDnsSupport: dnsSupport
}

dnsSupport: @override True

The top-level binding dnsSupport is set to True. Because the binding has the @override annotation, you can override it with another value (i.e., False) when you execute fugue update.

Use the --set option to set dnsSupport to False:

fugue update myProcess VpcOverride.lw -- --set "dnsSupport: False"

The Conductor will modify the VPC and disable its DNS support.

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

As we mentioned above, updates may be destructive or mutative. The same rules apply to updates that use overrides. For example, if you override a field marked mutable in the Fugue Standard Library, like a VPC’s enableDnsSupport, the resource will be modified in place instead of being terminated. If you override a non-mutable field, like a VPC’s cidrBlock, then the resource will be destroyed and a new one will be created with the overriding attribute.

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

Using fugue.yaml to Pass Ludwig Compiler Options to update

It is possible to override the usual process by which update compiles a composition. You can pass lwc options through the fugue.yaml file, or you can apply an environment variable. This is intended for internal or support use only. We recommend setting the FUGUE_LWC_OPTIONS environment variable to pass lwc options to update at the command line instead.

To do this via fugue.yaml, create a lwcOptions field in fugue.yaml and include the arguments you wish to pass directly to the compiler. lwc will use those options when compiling the composition as part of the update process.

Example lwcOptions field:

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

To do this via environment variable, set FUGUE_LWCOPTIONS to the arguments you wish to pass directly to the compiler.

Example FUGUE_LWCOPTIONS value:

export FUGUE_LWCOPTIONS="--timeout=30 --no-color"

The above examples 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 and FUGUE_LWCOPTIONS, see Project Setup Options.

Note: The semantic backend does not affect the CLI update output, so passing an -s argument (for example, -s simple) using this method will not produce semantic output.