init

Usage

fugue [global options] init [options] <region>

Arguments

region

Required: The region in which to install the Fugue Conductor.

Example: fugue init us-east-1

Note: The Fugue Conductor may only be installed in the following regions: us-east-1, us-east-2, us-west-2, eu-west-1, and us-gov-west-1.

Options

Global options are detailed here.

--ami id

Override the AMI to use in the specified <region>

Example: fugue init --ami ami-1234567 us-east-1

-p | --profile PROFILE

Specify the name of the AWS credential profile to use when searching for credentials. Defaults to default.

Example: fugue init -p myprofile us-east-1

--conductor-type type

Specify the Conductor type to use: PAID or FREE.

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

--creds-check
Check that the configured AWS credentials have sufficient permissions to use the Fugue CLI and install the Fugue Conductor.
-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 init command initializes a project in the current directory. This command is one of two options available for configuring Fugue. The init command utilizes the fugue.yaml file, which is now an optional file. The details included here assume the user is setting up Fugue using the init command in combination with the fugue.yaml file. For details on setting up Fugue without using a fugue.yaml file read more here.

The initialization process consists of setting the Conductor version by recording the Conductor AMI ID and region in a fugue.yaml file. The AMI ID is selected automatically by Fugue unless the user overrides it with the --ami id option.

The fugue.yaml file may optionally contain other settings that guide the fugue CLI through its various operations. For example, the AWS credentials profile (credentialProfile in the aws block) and the Fugue user profile (profile in the user block) are recorded in fugue.yaml if non-default profiles are used.

Note: In earlier versions of Fugue the fields userId and userSecret were stored in the fugue.yaml file. Those fields are now stored in your current working directory in the credentials file as user and secret but correspond to the same values, they just vary based on your version of Fugue. The values can also be stored in environment variables. Fugue checks for these values in the fugue.yaml file, the credentials file, and environment variables to maintain backwards compatibility.

Note

Anytime the Fugue CLI executes a command, it searches and verifies Fugue user credentials in credentials, environment variables, and fugue.yaml (for backwards compatibility) and loads the applicable configuration settings. The CLI first searches for fugue.yaml in a project-level directory, then in a user-level directory, and finally in a system-level directory.

In Mac and Linux systems, these directories are:

  1. The current working directory
  2. ~/.fugue/
  3. /etc/fugue/

In Windows (PowerShell), these directories are:

  1. The current working directory
  2. $env:LocalAppData\Fugue\
  3. $env:ProgramData\Fugue\

Fugue will use the first file it finds in the search path described above.

init must be executed prior to a fugue install. Once the Fugue Conductor has been installed, the changes init makes to the fugue.yaml settings (e.g., AWS credentials and Conductor version) won’t take effect until the Fugue Conductor is uninstalled and reinstalled. Note: You may use upgrade to change the Conductor AMI without having to uninstall and reinstall Fugue (for example, fugue upgrade --ami ami-e1d64ff6).

Before you run fugue init, you should know:

  • Which AWS credentials do I want to use for this project?
  • Which region do I want to run a Conductor in for this project?

Determining AWS Credentials To Use For The Project

When init is executed, the CLI searches for credentials in the following order, using the first set it finds:

  1. The environment variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY; then,
  2. The default profile in ~/.aws/credentials, unless the init -p <profile> option is specified; then,
  3. The default profile in ~/.aws/config, unless the init -p <profile> option is specified; then finally,
  4. The instance metadata service (IMDS), which is present only on EC2 instances and provides credentials reflecting the IAM Role of the instance.

The easiest of these to use for a developer desktop is usually the credential profile option. The best way to configure credential profiles is to use the AWS CLI. You can read more about quickly setting up AWS credentials with both Fugue and the AWS CLI here.

Note: The Fugue CLI does not support the use of AWS root account credentials. If you attempt to configure Fugue to use your AWS root account, init will fail. AWS recommends creating an IAM user for everyday use and using its credentials instead, because root credentials cannot be restricted. If administrative-level permissions are desired, you can grant the IAM user full access, allowing you to modify or revoke permissions later if necessary. Use the IAM user credentials with Fugue instead. For more information, see AWS’s documentation on root account vs. IAM user credentials.

Fugue generates IAM policies and roles for you during the install process. For more information, see AWS Permissions and the Fugue CLI.

Determining Which Region To Use For The Project

The region is required for the init command. Fugue distributes versions of the Conductor with specific AMI IDs, so that you get a pre-built, working machine image instead of software you have to install on your own OS. Fugue Conductors are built on Debian Linux. You can find the ID for each release at the Download Portal.

How init Works

When the user executes fugue init, the CLI validates the Conductor AMI ID, if provided, or selects a Conductor AMI ID for the user, then creates the fugue.yaml file.

If a fugue.yaml file already exists, the CLI renames it fugue.yaml.old and creates a new fugue.yaml file with the new settings.

If a fugue.yaml.old file already exists, the CLI deletes it, renames the existing fugue.yaml to fugue.yaml.old, and creates a new fugue.yaml file with the new settings.

For example, when no fugue.yaml file exists, and AWS credentials are stored in a default profile in ~/.aws/credentials, executing fugue init --ami ami-f9baedee us-east-1 produces the following output:

[ fugue init ] Initializing Fugue project with the following configuration:

Fugue Conductor AMI ID: ami-f9baedee
AWS Credentials: Profile (default)
Region: us-east-1

Validating Fugue Conductor AMI ID ...
[ OK ] Provided AMI ID is valid.

Creating new fugue.yaml file ...

[ Done ] Project initialized.

Likewise, when no fugue.yaml file exists, and AWS credentials are stored in environment variables, executing fugue init --ami ami-f9baedee us-east-1 produces the following output:

[ fugue init ] Initializing Fugue project with the following configuration:

Fugue Conductor AMI ID: ami-f9baedee
AWS Credentials: Environment variables

Validating Fugue Conductor AMI ID ...
[ OK ] Provided AMI ID is valid.

Creating new fugue.yaml file ...

[ Done ] Project initialized.

Note: The default CLI timeout is 15 minutes. This timeout setting only applies when fugue init is being run for the first time or there are no existing timeout settings in the fugue.yaml file.

Contents of fugue.yaml

Running fugue init us-east-1 produces the following fugue.yaml file:

conductor:
  ami: ami-482ae35e
  region: us-east-1

Running fugue init --profile myProfile us-east-1 produces the following fugue.yaml file:

aws:
  credentialProfile: myProfile
conductor:
  ami: ami-482ae35e
  region: us-east-1

After running fugue install, the fugue.yaml file might look like this:

conductor:
  ami: ami-482ae35e
  region: us-east-1
  secretsKeyId: alias/fugue/rbac/secrets

Note: In earlier versions of Fugue the fugue.yaml may contain the userId and userSecret fields. These details are now stored in credentials but are respected regardless of location.

Configuring fugue.yaml

For details on all of the fields in fugue.yaml visit the Project Setup Options page.

Examples

Changing the AWS credential profile the Fugue CLI uses

If you have configured the Fugue CLI to use a particular set of AWS credentials but you need to specify a different set, you can modify fugue.yaml or set an environment variable to change which AWS profile Fugue uses from the ~/.aws/credentials or ~/.aws/config files. (Recall that root account credentials are not supported.)

For example, say you’ve configured the Fugue CLI to use the primaryUser AWS credential profile, but you need to reconfigure it to use the secondaryUser profile. There are three ways to do this.

1. You can manually edit fugue.yaml to add the credentialProfile: <profile name> line in the aws block. That might look like this:

aws:
  credentialProfile: secondaryUser
conductor:
  ami: ami-c4c3fcbe
  region: us-east-1

2. You can also run fugue init with -p or --profile to write a fugue.yaml file configured with the given profile. However, if you already have a fugue.yaml file, any custom settings will be overwritten. Here’s an example command:

fugue init us-east-1 --profile secondaryUser

3. Alternatively, you may switch Fugue to the desired profile by setting the environment variable FUGUE_AWS_CREDENTIALPROFILE to the name of the profile. This method does not require a fugue.yaml file:

export FUGUE_AWS_CREDENTIALPROFILE=secondaryUser

If the new credential profile is associated with a different AWS account and that account does not have a Conductor in it, you can install the Conductor there with fugue install. Just remember that the Conductor in the old AWS account will incur charges as long as it is installed, so you may wish to run fugue uninstall using the credential profile associated with the old account.

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.

Checking AWS credentials with init

You can use the --creds-check option to validate your AWS credentials. The CLI checks to see if the IAM policy associated with the configured AWS credentials has the required permissions to run the Fugue CLI and install the Fugue Conductor.

When you execute fugue init --creds-check <region>, the CLI does the following:

  1. The CLI searches for AWS credentials according to the order listed here.
  2. The CLI checks the credentials to ensure the user is authorized to use the Fugue CLI and install the Fugue Conductor.
  3. If the credentials do not have sufficient permissions, the CLI displays an error.
  4. If the credentials do have sufficient permissions, the CLI validates the provided Conductor AMI ID and creates the fugue.yaml file.

Example error message for credentials missing one or more required IAM permissions:

[ fugue init ] Initializing Fugue project with the following configuration:

Fugue Conductor AMI ID: ami-f9baedee
AWS Credentials: Profile (no-access-creds-test)

Checking your AWS Credentials for Fugue CLI use ...
[ ERROR ] There was a problem executing this command.
   Reason: An error occurred (AccessDenied) when calling the SimulatePrincipalPolicy operation: User: arn:aws:iam::xxxxxxxxxxxx:user/no-access-creds-test is not authorized to perform: iam:SimulatePrincipalPolicy on resource: arn:aws:iam::xxxxxxxxxxxx:user/no-access-creds-test

Example error message for erroneous credentials:

[ fugue init ] Initializing Fugue project with the following configuration:

Fugue Conductor AMI ID: ami-f9baedee
AWS Credentials: Profile (mistyped-creds)

Checking your AWS Credentials for Fugue CLI use ...
[ ERROR ] There was a problem executing this command.
   Reason: An error occurred (InvalidClientTokenId) when calling the GetCallerIdentity operation: The security token included in the request is invalid.

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.