install

Usage

fugue [global options] install [options]

Options

Global options are detailed here.

--ami id
Override the AMI to use in the specified <region>.
--conductor-type type

Specify the Conductor type to use: PAID or FREE.

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

--kms-key str
The KMS key used to encrypt the root user secret when saving to S3. You can use a KMS key ID, alias, or ARN. Default key alias: alias/fugue/rbac/secrets.
-y | --yes
Suppress confirmation dialogs. The yes flag suppresses confirmation dialogs and bypasses interactive prompts by providing input to aid scripting.
-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 install command installs the Fugue Conductor in the user’s AWS account and boots Fugue. (Note: Fugue supports configuring the Conductor to connect to the internet through a proxy. Refer to Fugue Proxy Support for specifics.)

By default, install 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.

First, the Fugue CLI determines the target AWS account by searching for credentials in the following order:

  • The environment variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY; then,
  • The profile in ~/.aws/credentials or ~/.aws/config that matches the environment variable FUGUE_AWS_CREDENTIALPROFILE; then,
  • The profile in ~/.aws/credentials or ~/.aws/config that matches the credentialProfile field in fugue.yaml; then finally,
  • The instance metadata service (IMDS), which is present only on EC2 instances and provides credentials reflecting the IAM Role of the instance.

The CLI tests the validity of the credentials and, in so doing, determines the account number and alias that they are associated with. This is the account that the install command targets.

Next, the CLI searches for the Conductor AMI ID in the following order:

  • The AMI specified in fugue install --ami id
  • The FUGUE_CONDUCTOR_AMI environment variable
  • The ami field in fugue.yaml, if fugue.yaml is present

If no AMI ID is found, the CLI uses the most recent AMI ID publicly available.

The CLI also searches for the AWS region in several locations to determine where the Conductor will be installed.

Next, the CLI asks the user to confirm that they want to install the Conductor using the displayed AMI ID, AWS account, and region:

[ fugue install ] Installing Fugue Conductor

Install Details:

   Conductor AMI ID: ami-e0364df7
   AWS Account: <user>/xxxxxxxxxxxx
   Region: us-east-1

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

When the user enters y, the Fugue CLI launches a CloudFormation stack inside that AWS account using the specified AMI. As the required resources are created, the CLI displays a table showing installation progress.

Installing the Fugue Conductor into AWS account user/xxxxxxxxxxxx.

FugueAutoScalingGroup                Working...
FugueCliResponsesDb                  Complete
FugueHealthCheckDb                   Complete
FugueIam                             Complete
FugueIamInstaller                    Complete
FugueIamUser                         Complete
FugueInstanceProfile                 Complete
FugueInternetRoute                   Complete
FugueLaunchConfiguration             Complete
FugueNotificationDriftTopic          Complete
FugueNotificationKillTopic           Complete
FugueNotificationReleaseTopic        Complete
FugueNotificationResumeTopic         Complete
FugueNotificationRunTopic            Complete
FugueNotificationSuspendTopic        Complete
FugueNotificationSystemTopic         Complete
FugueNotificationUpdateTopic         Complete
FugueResourceEventsTopic             Complete
FugueRouteTable                      Complete
FugueSubnet1                         Complete
FugueSubnet1RouteTableAssociation    Complete
FugueSubnet2                         Complete
FugueSubnet2RouteTableAssociation    Complete
FugueVpc                             Complete
FugueVpcGateway                      Complete
FugueVpcGatewayAttachment            Complete
FugueVpcSecurityGroup                Complete
-----------------------------------------------
Overall Progress  [########################.]   96%

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

Note: While the CLI currently indicates that (CTRL+C) will not stop the installation, we do not recommend using this command as it may interrupt the successful creation of credentials. In the event (CTRL+C) is used you can manually create your credentials using fugue support reset-secret. These recommendations will be updated in a future release.

When all the stack resources have been created, the CLI generates default user credentials in a credentials file. These are your root credentials, so don’t lose them!

Creating default user credentials ...

====================
User Credential Details:

[default-xxxxxxxxxxxx-us-east-1]
user = root
secret = fPXxKUldfPSQwtXhVKs8XOEXAMPLEEXAMPLEEXAMPLE=

====================

This next part only applies if you’ve chosen to store configuration settings in a fugue.yaml file. The CLI deletes the fugue.yaml.old file if it exists, renames the current fugue.yaml file to fugue.yaml.old, and creates a new fugue.yaml.

Found existing fugue.yaml.old file in /Users/user/projects .
Deleting existing fugue.yaml.old ...
[ OK ] Existing fugue.yaml.old file deleted.

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

After credentials have been created and any fugue.yaml files have been cleaned up, the CLI indicates that the Conductor has been successfully installed.

[ OK ] Fugue Conductor installed.

Before Fugue can be used, though, the CLI must create IAM roles and the Conductor must boot up. In the next step, the CLI creates a Fugue user IAM role and a Fugue installer IAM role, and then it displays the role names.

Fugue IAM Role Details:

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

Then, the CLI asks the user to wait while the Conductor boots up.

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

[ HELP ] The Conductor needs to boot before it can accept commands from the CLI. Exiting the install command while in progress (CTRL+C) will only stop progress tracking and *not* the install itself or the booting process.

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.

Note

When the Conductor is uninstalled, the RBAC policy is removed along with all users and their credentials. If you reinstall the Conductor with install, you’ll need to apply the policy again with policy rbac-attach, and root will have a new user secret.

Using status to confirm the Fugue Conductor is done booting

In general, it is not recommended to use CTRL+C to halt the installation process as this can prevent the creation of your credentials. However, if you exit the install command with CTRL+C while the Conductor is still installing or booting, you may run fugue status to determine whether the Conductor is ready to receive commands. If the Conductor hasn’t finished installing or booting, status returns an error message:

[ ERROR ] There was a problem executing this command.
   Reason: The Conductor is in the process of installing.

In addition, you may be forced to manually create your credentials using fugue support reset-secret. However, if the Conductor is ready to receive commands, status returns this message:

Fugue Status Report for <user>/<account> - Fri Mar 17 2017 5:31pm

State    Updated    Created    Account    FID/Alias    Flags    Last Message    Next Command
-------  ---------  ---------  ---------  -----------  -------  --------------  --------------
Nothing to see here. Go create something! :-)

As always, if you run into issues of any kind, reach out to us at support@fugue.co.

Examples

Changing The Region The Conductor Is Running In

At present Fugue supports running Conductors in us-east-1, us-east-2, us-west-2, eu-west-1, and us-gov-west-1. To specify a region for the Conductor prior to installation, you can use init and provide the desired region. Other supported ways of setting the Conductor region are listed here.

Note: Conductor region cannot be changed after installation.

Changing The Size Of The Conductor Instance

The Conductor instance type is m4.large by default. This value should not be changed unless specifically directed by Fugue support. If you have any questions, reach out to support@fugue.co.

Manually Setting Installation Availability Zones

If you have problems installing Fugue due to an Availability Zone (AZ) being unavailable for new resources in your account, or wish to customize the AZs used by Fugue for installation, you can manually specify the AZs that Fugue uses for the Fugue Conductor installation in fugue.yaml or an environment variable. These AZs will be used when you run the fugue install command.

If you configured Fugue with fugue.yaml, you can add an entry in fugue.yaml under the conductor heading called installAZ as a list of up to two known-good availability zones in your account. For example:

conductor:
  installAZ:
    - us-east-1c
    - us-east-1d

If you configured Fugue with environment variables, set the FUGUE_CONDUCTOR_INSTALLAZ environment variable to either one or two availability zones (if two, separate with a comma):

export FUGUE_CONDUCTOR_INSTALLAZ=us-east-1c,us-east-1d

Next time you run fugue install, the command will install the Fugue Conductor VPC with subnets in the first two AZs listed.

There are two caveats you should keep in mind if you have to use this feature. Firstly, bear in mind that you can specify one or two AZs. If you specify one, the CLI will log a warning during installation, but Fugue will install and run. If you specify two, installation should proceed as normal. If you specify more than two, only the first two will be used, and all subsequent entries in the list will be ignored.

Secondly, the AZs you list will be assumed valid. If you provide an invalid or unavailable AZ for your account, installation will fail with a CloudFormation stack error, like:

[ ERROR ] AWS CloudFormation stack creation failed

Note that you can get a list of AZs available to you using the AWS CLI command describe-availability-zones, but this is the same command that Fugue uses, and it sometimes returns unreliable data. As a rule of thumb, you should look for a pair of AZs that are listed as available to you, but that you don’t heavily utilize.

Changing the KMS Key For Encrypting Secrets

When the CLI generates default user credentials, it encrypts them and saves them to S3. By default, the KMS customer master key used for encryption is alias/fugue/rbac/secrets (which appears in the AWS Management Console as “fugue/rbac/secrets”).

To encrypt your credentials with a different key, you can use the --kms-key option with install. You can specify the key by its key ID, alias, or ARN. If the specified key does not exist, it will be created for you. If you provide an alias, be sure to prepend it with alias/. For example, if the AWS console lists a key named myAlias, then you must format it as alias/myAlias:

fugue install --kms-key alias/myAlias

Two other supported ways of changing the key:

conductor:
  ami: ami-5800e125
  region: us-east-1
  secretsKeyId: 96b8bb05-42e8-49e5-aae9-d69fbc57a940
  • Set the environment value FUGUE_CONDUCTOR_SECRETSKEYID to your KMS key ID, alias, or ARN. For example:
export FUGUE_CONDUCTOR_SECRETSKEYID=alias/myAlias

The order of precedence is the --kms-key argument, the FUGUE_CONDUCTOR_SECRETSKEYID environment value, and the secretsKeyId field in fugue.yaml.

Changing the System Vars DDB Table Prior to Installation

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 install:

fugue install

Fugue will create the new DynamoDB table for Vars as part of the Conductor installation process.