Hello World, Part 1: Fugue Quick Setup

Overview

Welcome to Hello World, a walkthrough in three parts. This example is designed to teach absolute beginners how to install the Fugue CLI and Conductor, how to use Fugue, and how to write the Ludwig language.

In Part 1 – this part! – you’ll learn how to quickly set up Fugue. We explain how to install the Fugue Conductor and the Fugue CLI.

In Part 2, you’ll learn the basics of using Fugue. We explain how to use the Fugue CLI to manipulate Amazon Web Services infrastructure defined in a basic composition, or Ludwig file, called HelloWorld.lw.

In Part 3, you’ll learn all about the Ludwig language. We explain the structure and syntax of the HelloWorld.lw composition line by line.

Prerequisites

None! If you’re ready to get started with Fugue, we’ll walk you through the entire setup process, from downloading to configuring to installing.

What We’ll Do In This Example

We’ll show you where to download Fugue, how to install the Fugue Client Tools, how to configure your AWS credentials, how to initialize a project, and how to install the Conductor. For a quick preview of this walkthrough, check out our video here.

If you’re interested, we also have a hands-on demonstration of setting up Fugue using our recommended best practices (i.e. keeping the Conductor in a separate account) in our Using the Multi-Account Feature example from our Fugue by Example section.

What We’ll Have When We’re Done

A configured Fugue CLI and a running Conductor, setting you up for Hello World, Part 2: Fugue Basics.

How Long It Will Take

About 15 minutes. The Conductor will take an additional 5-15 minutes to boot up before you can run your first composition in Part 2.

Let’s Go!

Technical Requirements

To use Fugue, you need a couple of things – an account with Amazon Web Services (AWS) and a supported operating system:

  • macOS El Capitan (10.11.*), macOS Sierra (10.12.*), macOS High Sierra (10.13.*)
  • Ubuntu (14.04 LTS, 16.04 LTS)
  • Amazon Linux (2016.03.3)
  • RHEL 6 & 7.2 (Yum/RPM)
  • Microsoft Windows (Windows 7, 10) Note: For Windows users we recommend using PowerShell 5 and $env:var syntax. To determine your version of PowerShell you can use echo $PSVersionTable.PSVersion. If you have additional questions reach out to support@fugue.co.

Download Fugue Client Tools

You can get access to Fugue at the Fugue Download Portal.

Install Client Tools

After selecting the client package for the platform you’re working on, installation should be easy to follow. Instructions based on package type are included here. This installation step provides the CLI for Fugue.

Warning

These instructions use a wildcard filename for the package names. This works fine as long as you only have one matching file in the present directory. In addition, we recommend verifying that your version of Fugue meets the needs of your business, or reach out to support@fugue.co for details on a potential upgrade. The latest version of Fugue is available through our Download Portal.

Note: Client packages, with the exception of RHEL 6, now include Fugue Composer. Refer to the Composer docs for additional details.

For Linux RPM (without Composer):

$ sudo rpm -ivh fugue-client*.rpm

For Linux RPM (including Composer):

$ sudo rpm -Uvh https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
$ sudo yum localinstall fugue-client-desktop-*.rpm

For Linux DEB (without Composer):

$ sudo dpkg -i fugue-client-*.deb

For Linux DEB (including Composer):

$ sudo dpkg -i fugue-client_*.deb
$ sudo apt-get install -f

For macOS PKG:

Double-click on the PKG file and follow the installation wizard.

For Windows MSI:

Double-click on the .MSI file and follow the installation wizard.

Configure AWS Credentials

Note

This guide assumes you are running the Fugue CLI on a local machine. You can also easily run the Fugue CLI on an EC2 instance. If you choose to run the instance with a sufficiently privileged IAM role, you can skip this step.

Before you begin working with Fugue, you’ll need to set up AWS credentials on the client machine. This step ensures that Fugue is using the right credentials when interacting with AWS. The best way to do this is simply to use the AWS CLI’s aws configure command. Here’s a quick guide on getting set up with the AWS CLI, and then how to use it to configure AWS credentials for your machine.

Warning

The Fugue CLI does not support the use of AWS root account credentials. For details, see the explanation here.

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

Configure Fugue Settings

To continue Fugue setup, you’ll need to decide where to store configuration settings. There are two options:

  • In a fugue.yaml file created by running fugue init
  • In environment variables

If you decide to configure Fugue via a fugue.yaml file, you’ll need to run fugue init to create the file. Later, you can edit fugue.yaml to change a setting.

If you decide to configure Fugue via environment variables, you’ll skip fugue init and go straight to Conductor installation. Later, you can export an environment variable to change a setting.

Configuration File vs. Environment Variables

Not sure which method to use? Here are some reasons you might use a configuration file (fugue.yaml):

  • You prefer working with a file on disk
  • You’d like to use a version control system to back up config settings
  • You plan to do most of your Fugue work in a single directory
  • You’ve installed Fugue through the AWS Marketplace

And here are some reasons you might use environment variables:

  • You prefer working with environment variables
  • You’d like to use automation with Fugue
  • You plan to use Fugue in multiple directories

Both methods work equally well, so it’s just a matter of personal preference. When you’re ready, jump ahead to the next section:

Configure Fugue With fugue.yaml

When you decide to configure Fugue via configuration file, Fugue settings are saved in a fugue.yaml file that includes the AMI ID of the Conductor and the Conductor installation region. It also includes the name of the AWS credentials profile to use for commands, if the default profile is not used. You may optionally customize your fugue.yaml with many more technical and advanced settings. All of this is set up using the fugue init command, and you can read more about init in the Fugue CLI Reference.

Note: Your AWS credentials are not checked in to version control.

Once you’ve made a directory for your Fugue project and made it your present working directory, you’re ready to initialize. Just make sure you know the region in which Fugue should operate – currently supported regions are:

  • us-east-1
  • us-east-2
  • us-west-2
  • eu-west-1
  • us-gov-west-1
$ fugue init <region>

For more about region, see A Note On Region.

Optionally, you can specify an AWS credential profile to use. This is only necessary if you used the --profile flag when you ran aws configure. If you didn’t, you set credentials for the default profile, and that is the profile Fugue commands will use. If you did set a certain profile name, fugue init conveniently uses the same flag to define the profile for Fugue commands:

$ fugue init --profile [PROFILE] <region>

If you run ls, you should now see a file called fugue.yaml. The fugue.yaml file maintains the settings for Fugue and guides the Fugue CLI through its various operations.

See the settings reference for more information about the fields in fugue.yaml and how to customize them.

All done? You can skip ahead to install the Conductor.

Configure Fugue With Environment Variables

There’s very little to configure before you can install the Fugue Conductor, especially if you’re using environment variables. Since Fugue detects the default AWS region you set in the aws configure step, you don’t have to configure anything if that’s the region where you want to install the Conductor and if you’re using the default AWS credentials profile.

However, if you want the Conductor to be installed in a different region, you can use the environment variable FUGUE_CONDUCTOR_REGION to configure the region:

export FUGUE_CONDUCTOR_REGION=eu-west-1

Alternatively, you can jump right to the install step and use the fugue --region global option to install Fugue in the given region:

fugue --region us-west-2 install

For more about region, including where the Conductor can be installed, see A Note On Region.

If you used the --profile flag to set a non-default AWS credential profile when you ran aws configure, then you’ll want to configure Fugue to use that profile. Make sure to set the FUGUE_AWS_CREDENTIALPROFILE environment variable to that profile name:

export FUGUE_AWS_CREDENTIALPROFILE=my-user-profile

You can customize Fugue with many other technical and advanced settings by assigning a value to a particular environment variable. See the settings reference for more information about these settings and how to customize them.

All set? Time to install the Conductor.

A Note On Region

Region is the only configuration option that must be specified somehow. As a result, the CLI will throw an error if it cannot determine the region.

Each time a command is executed, Fugue determines the Conductor region by searching in the following locations, in order of precedence:

  • Global option fugue –region (sets region on per-command basis)
  • Environment variable FUGUE_CONDUCTOR_REGION
  • Fugue config file fugue.yaml
  • AWS CLI environment variable AWS_DEFAULT_REGION
  • AWS CLI config file (typically located at ~/.aws/config)

The exception: init‘s required region argument takes precedence over anything else. For example, in the command fugue --region us-east-1 init eu-west-1, Fugue will execute init using the eu-west-1 region.

Note

The Fugue Conductor may only be installed in the following regions:

  • us-east-1
  • us-east-2
  • us-west-2
  • eu-west-1
  • us-gov-west-1

Install the Conductor

There are two components of Fugue to install. You’ve already installed the CLI, which is installed on a client machine such as your laptop, or an EC2 instance you’re using as an SSH bastion host.

The second component is the Fugue Conductor, which is comprised of an EC2 instance and several other resources and is installed resident in your AWS account. Installation of the Fugue Conductor is easy, and takes just about long enough for you to go and get a sandwich.

Note

This step is only required if you do not have a Fugue Conductor running in your account. If you or someone on your team has already installed the Fugue Conductor, skip this step.

To install the Fugue Conductor, simply type:

$ fugue install

The Fugue CLI determines the target AWS account for Conductor installation by sourcing AWS 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 asks you to confirm that you want to proceed with installing the Conductor into the target AWS account. Make sure that this is the account you want to use.

The CLI displays the installation progress and tells you when the Fugue Conductor and its dependencies have been successfully created. At this point in the installation process, the fields user and secret are generated and stored in a Fugue credentials file, generally located in your current working directory. The fugue install command also generates a default profile name, typically based on the account number and region. Take a look at Fugue User Credentials for more information.

Once the Fugue Conductor is installed, it needs another 5-15 minutes to boot up. The CLI displays a message asking for your patience while it boots Fugue. You’ll know it’s safe to go to the next step when the CLI returns you to your command prompt and displays this message:

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

That’s it! Fugue is ready for you to use.

Possible Issues

If you encountered trouble while attempting to install Fugue, here are some common issues and their solutions:

Wrong AMI ID

Fugue can select a Conductor AMI ID for you during fugue init (if executed) or fugue install, assuming the configured region is valid. However, you have the option to provide a different Conductor AMI ID by using the --ami id option with either command or by setting the FUGUE_CONDUCTOR_AMI environment variable. Conductor AMI IDs are listed in the Download Portal.

If you provide an incorrect AMI ID (as in fugue install --ami ami-00000000), you’ll see this message:

[ ERROR ] You do not have access to the ami-00000000 conductor in region 'us-east-1'.

If you provide a malformed AMI ID (as in fugue install --ami foo), you’ll see this message:

[ ERROR ] There was a problem executing this command.
  Reason: "foo" is not a valid AMI ID.

If you receive either error, double-check your AMI ID and ensure it matches the one listed in the Download Portal. You can also execute fugue init <region> or fugue install without using the --ami id option, and Fugue will select the Conductor AMI for you.

The Fugue Conductor may only be installed in the following regions:

  • us-east-1
  • us-east-2
  • us-west-2
  • eu-west-1
  • us-gov-west-1

Incomplete Registration Process

If you didn’t complete the registration process in the Download Portal, your AWS account number may not have been whitelisted. In that case, running fugue init would result in one of the following error messages:

[ ERROR ] You do not have access to any conductor in region <region>.
[ ERROR ] You do not have access to the <(PAID|FREE)> conductor in region <region>.

Skipping fugue init and running fugue install (if you configured Fugue with environment variables) would result in the following error message:

[ ERROR ] Fugue is unable to install the conductor due to a possible permissions issue. Please email support@fugue.co with this error message.

To fix it:

  • Complete the registration process at the Download Portal and ensure your AWS account ID has been entered properly.

Other Issues

Still having trouble installing Fugue? Reach out to support@fugue.co.

You’re Done With Part 1!

Congratulations! You’ve learned how to install the Fugue Client Tools, configure your AWS credentials, initialize a project, and install the Fugue Conductor. Pat yourself on the back, and get ready for Part 2!

Next Steps

Now that you have Fugue installed, you’re ready for Hello World, Part 2: Fugue Basics, where you’ll learn the basics of using Fugue! Or, if you want to jump right in to other examples, you can browse the walkthroughs available in Fugue by Example.