upgrade

Warning

You must upgrade your Fugue client prior to issuing an upgrade for your Fugue Conductor. A mismatched client and Conductor can present unwanted issues. For any questions contact support@fugue.co.

Warning

When upgrading Fugue from a previous release, if your fugue-vars-headless-store DynamoDB table is larger than 3GB, you will see a message to contact Fugue Support (support@fugue.co) to help you compact the table. This process will ensure you have a successful upgrade.

If you wish to continue the upgrade on your own, you may enter y at the prompt. You may also use the fugue upgrade --force option to bypass the confirmation. However, we recommend that you contact Fugue Support first.

Note

If you’ve attached an RBAC policy to your Conductor prior to upgrading it, you may need to re-attach it after upgrade is complete. See Troubleshooting for more details.

Usage

fugue [global options] upgrade [options]

Options

Global options are detailed here.

--ami id
Specify the AMI to upgrade to.
--conductor-type type

Specify the Conductor type to use: PAID or FREE.

Note: TEAM and BASIC are still supported for backwards compatibility.

-y | --yes
Suppress confirmation dialogs. The yes flag suppresses confirmation dialogs and bypasses interactive prompts by providing input to aid scripting.
-f | --force
Ignore the state of the Conductor or CloudFormation stack.
-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 upgrade command upgrades the Fugue Conductor. If the --ami id option is specified, Fugue upgrades to that Conductor AMI. If no AMI ID is provided, Fugue determines the AMI for you, selecting a Conductor based on your account status, either the paid version of Fugue or the version available with Free Fugue.

Warning

While the upgrade command technically allows upgrades from any valid Conductor AMI ID to any other valid Conductor AMI ID, only upgrades between consecutive versions of the Conductor (from n-1 to n or vice versa) are tested and supported. If you are unsure whether your current Conductor’s AMI ID and the target Conductor’s AMI ID represent consecutive versions, reach out to support@fugue.co and include the AMI IDs.

Note: Fugue supports configuring the Conductor at upgrade to connect to the internet through a proxy. Refer to Fugue Proxy Support for specifics.

Note: By default, upgrade creates the necessary infrastructure for running Fugue in the user’s account. However, Fugue offers the option to install the Conductor in an existing VPC. Refer to Installing the Conductor in Your Own VPC for specifics.

Note

Do not schedule the fugue/rbac/secrets or fugue/keymanager KMS customer master keys for deletion prior to reinstalling or upgrading Fugue. See Troubleshooting for more information.

upgrade executes in several phases. First, the Fugue CLI displays the upgrade details:

  • Current AMI ID of the Conductor - what you’re upgrading from
  • Target AMI ID of the Conductor - what you’re upgrading to
  • AWS account - the account associated with the configured AWS credentials
  • AWS region - where the Conductor is installed

The CLI asks the user if they would like to proceed. If so, the CLI checks the target AMI ID to make sure it’s a valid Conductor AMI. Then the CLI verifies that the size of the system Vars DynamoDB table is smaller than 3GB. If the table exceeds 3GB, the CLI will prompt you to contact support@fugue.co in order to compact the table. Otherwise, the upgrade process continues.

[ fugue upgrade ] Upgrading Conductor

Upgrade Details:

   Conductor AMI ID: ami-c4c3fcbe -> ami-6d4a3e17
   AWS Account: user/xxxxxxxxxxxx

   Region: us-east-1

[ WARN ] Would you like to proceed with upgrading? [y/N]: y
Checking availability and validity of ami-6d4a3e17 ...
[ OK ] AMI ID is valid and available.

Checking system VARS table size ...
[ OK ] System VARS table confirmed (1.9 MB).
Upgrading the Fugue Conductor in AWS account user/xxxxxxxxxxxx ...

This next part only applies if you’ve chosen to store configuration settings in a fugue.yaml file. As part of this upgrade process, fugue upgrade also renames and replaces your existing fugue.yaml file. If a fugue.yaml and fugue.yaml.old both exist the current fugue.yaml.old file is deleted and the existing fugue.yaml is renamed.

Found existing fugue.yaml.old file in /path/to/fugue.yaml .
Deleting existing fugue.yaml.old ...
[ OK ] Existing fugue.yaml.old file deleted.

Found existing fugue.yaml file in /path/to/fugue.yaml .
Renaming existing fugue.yaml file to fugue.yaml.old ...
[ OK ] Existing fugue.yaml file renamed.

Next, Fugue updates the autoscaling group’s launch configuration in the Conductor’s CloudFormation stack with the specified AMI ID.

Fugue then terminates the old Conductor instance, activating the autoscaling group, which launches a new Conductor EC2 instance using the updated launch configuration.

[ HELP ] Exiting the upgrade command while in progress (CTRL+C) will only stop progress tracking and *not* the upgrade itself.

Creating new Launch Configuration ...
[ OK ] Launch Configuration created with new AMI.

Updating Conductor Autoscaling Group ...
[ OK ] Autoscaling Group updated.

Requesting AWS to terminate the old Conductor instance ...
[ OK ] AWS is terminating old instance.

When installation is complete, unused CloudWatch alarms are deleted and the installer and user IAM roles are displayed. The CLI asks the user to wait while the Conductor boots up.

Installing new Conductor ...
[ OK ] New Conductor installed.

Deleting unused Conductor CloudWatch Alarms ...
 Success

Fugue IAM Role Details:

   Installer: fugue-installer-us-east-1
   User: fugue-user-us-east-1

Booting the Conductor, please wait as this may take between 5-15 minutes...

When booting is complete, the CLI states that Fugue is ready to receive commands again.

[ DONE ] Fugue has been successfully installed and is ready to receive commands.

Examples

Changing the System Vars DDB Table During Upgrade

Warning

Changing your Vars table can have severe consequences, including dropping your entire dataset. Do not change your Vars table unless you have been instructed to do so by Fugue Support.

The default DynamoDB table that Vars uses for key/value storage is fugue-vars-headless-store. This is where Fugue stores internal data related to running the Conductor. To use a different table, you can specify the new table name in fugue.yaml or in an environment variable prior to installing or upgrading Fugue. Note: The new table name must begin with fugue-vars-.

Warning

When pointing Vars to a new table, there is no automatic data migration. This means that a newly booted Conductor will act like a fresh install, and any existing infrastructure will no longer be enforced, cleaned up, or even seen by the Conductor.

To configure the table via fugue.yaml, add the experimental block to it, including the desired name of the DynamoDB table. Your fugue.yaml may look like this:

conductor:
 ami: ami-491bbb5f
 region: us-east-1
experimental:
 varsSystemTable: fugue-vars-headless-store-2

To configure the table via environment variables, set the FUGUE_EXPERIMENTAL_VARSSYSTEMTABLE environment variable to the desired name of the DynamoDB table:

export FUGUE_EXPERIMENTAL_VARSSYSTEMTABLE=fugue-vars-headless-store-2

Now that you’ve specified the table name, turn on the FUGUE_CLI_PREVIEW flag. This flag is required for enabling experimental configuration.

export FUGUE_CLI_PREVIEW=yes

Finally, execute upgrade. Just like with a normal upgrade, if you need to upgrade to a specific AMI ID, you can use the --ami option as noted above. Otherwise, execute fugue upgrade to let the CLI determine the AMI ID you need.

However, if you want to change the Vars table without changing the Conductor AMI, use the --ami option to set the target AMI ID to the current AMI ID. (You can find that ID by running fugue --version.) Since target and current AMIs will be the same, the Conductor won’t change but the Vars table will.

fugue upgrade --ami ami-491bbb5f

After you execute upgrade, you’ll see output like this:

[ fugue upgrade ] Upgrading Conductor

Upgrade Details:

   Conductor AMI ID: ami-491bbb5f
   Conductor Vars Table: fugue-vars-headless-store -> fugue-vars-headless-store-2
   AWS Account: user/xxxxxxxxxxxx

   Region: us-east-1

[ WARN ] Would you like to proceed with upgrading? [y/N]:

Ensure that the Conductor Vars Table details are correct, and enter y. The CLI will create the new DynamoDB table for Vars.

Upgrading When Vars DDB Table is >3G

If you execute fugue upgrade and your fugue-vars-headless-store Vars DynamoDB table is larger than 3GB, you’ll see output instructing you to contact Fugue Support (support@fugue.co):

[ fugue upgrade ] Upgrading Conductor

Upgrade Details:

   Conductor AMI ID: ami-c4c3fcbe -> ami-6d4a3e17
   AWS Account: user/xxxxxxxxxxxx

   Region: us-east-1

[ WARN ] Would you like to proceed with upgrading? [y/N]: y
Checking availability and validity of ami-6d4a3e17 ...
[ OK ] AMI ID is valid and available.

Checking system VARS table size ...
[ WARN ] System VARS table size is too large to guarantee a smooth migration (50 GB). Please reach out to support@fugue.co before proceeding.

[ WARN ] Are you sure you want to proceed with upgrading? [y/N]:

You may enter y at the prompt to proceed with upgrading on your own. You may also use fugue upgrade --force to bypass the confirmation prompt. However, we strongly recommend that you reach out to support@fugue.co first. Without compaction, upgrading a Conductor with a large Vars DDB table can take a very long time, and in certain situations, the upgrade could fail.