`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

Overriding the Update Command with Ludwig Compiler Options¶

It is possible to pass lwc options through the fugue.yaml file during update, overriding the usual process by which update 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 update 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 update output, so passing an -s argument (for example, -s simple) through fugue.yaml will not produce semantic output.