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.
- OS X El Capitan (10.11.*)
- Ubuntu (14.04 LTS, 16.04 LTS)
- Amazon Linux (2016.03.3)
- RHEL 6 (Yum/RPM)
Download Fugue Client Tools¶
You can register at https://fugue.co/users/register/ to request access to Fugue.
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.
For Linux RPM:
$ sudo rpm -ivh fugue-client*.rpm
For Linux DEB:
$ sudo dpkg -i fugue-client*.deb
For OSX PKG:
Double-click on the PKG 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.
Initialize a Project¶
Fugue work is done in project directories. This makes Fugue projects
easy to work on in version control systems. The project settings are
saved in a
fugue.yaml file that includes the AMI ID of the Conductor
and 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
$ fugue init <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 the Fugue initialization
process and guides the Fugue CLI through its various operations.
See the init reference for
more information about the fields in
fugue.yaml and how to customize
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
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.
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 selects a Conductor AMI ID for you during
fugue init, as long
as you provide a valid region (
fugue init us-east-1 or
fugue init us-gov-west-1). However, you have the option to provide a
different Conductor AMI ID by using
--ami id. Conductor AMI IDs are
listed in the Download Portal.
If you provide an incorrect AMI ID, you’ll see this message:
fugue init us-east-1 --ami foo
[ ERROR ] There was a problem executing this command. Reason: "foo" is not a valid AMI ID.
If you receive this error, double-check your AMI ID and ensure it
matches the one listed in the Download
Portal. You can also execute
fugue init <region>, without using the
--ami id option, and
Fugue will select the Conductor AMI for you.
Incomplete Registration Process¶
If you didn’t complete the registration process in the Download
Portal, your AWS account number may not
have been whitelisted, and you will encounter one of the following error
You do not have access to any conductor in region <region>.
You do not have access to the <(TEAM|BASIC)> conductor in region <region>.
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!