Hello World, Part 1: Fugue Quick Setup¶
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
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.
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.
- 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:varsyntax. To determine your version of PowerShell you can use
echo $PSVersionTable.PSVersion. If you have additional questions reach out to firstname.lastname@example.org.
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.
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 email@example.com 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¶
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.
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.yamlfile created by running
- In environment variables
If you decide to configure Fugue via a fugue.yaml file, you’ll need
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
fugue init and go straight to Conductor installation. Later,
you can export an environment variable to change a
Configuration File vs. Environment Variables¶
Not sure which method to use? Here are some reasons you might use a
configuration file (
- 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
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:
$ 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 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
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
to configure the region:
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
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 config file
- AWS CLI environment variable
- AWS CLI config file (typically located at
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
The Fugue Conductor may only be installed in the following regions:
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.
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
- The profile in
~/.aws/configthat matches the environment variable
- The profile in
~/.aws/configthat matches the
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
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
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.
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
fugue install, assuming the configured region is valid.
However, you have the option to provide a different Conductor AMI ID by
--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:
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>.
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 firstname.lastname@example.org 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.
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!