Fugue Composer

What is Composer?

Fugue Composer is a tool that allows users to explore visualizations of compositions (Ludwig files). By selecting a Fugue Project Directory containing your compositions, you can use the File Browser to open an individual Ludwig file that will launch a detailed interactive diagram of the declared AWS infrastructure. Additionally, Fugue Composer can scan your AWS account to generate a composition and visualization of any infrastructure that is already running. You can also use the Create Process feature to launch a process from a composition.

If you experience any issues with performance or have questions about service coverage we want to know! Send us your questions and feedback at support@fugue.co.

One item to note – the “Generate Composition” feature auto-generates compositions. As with all code-generation tools, it can be a challenge to manage lots of automatically generated compositions from a large environment. There are some features, like filtering, that make it easier to scale down the transcribed environment. For help with transcribing large or complex environments, contact support@fugue.co.

Note: If you don’t have a Fugue account, you can sign up for free here. Don’t have Composer yet - download it here.

Fugue Composer visualization.

Fugue Composer visualization.

How does it work?

When you open Fugue Composer, you’ll see a “Welcome to Composer” screen that provides a quick overview and helpful links to get started. You have the option to disable the initial screen so that subsequent sessions open with the launch screen.

Fugue Composer Welcome screen.

Fugue Composer Welcome screen.

After the Welcome screen you’ll see the launch screen where you can choose the “Open Fugue Project Directory” button or the “Generate Composition” button. The next time you launch Composer, you’ll also see a “Recently Accessed Directories” list.

Fugue Composer Launch page.

Fugue Composer Launch page.

Once you’ve selected a directory or generated a composition, Fugue Composer displays the selected composition, or Ludwig file, side-by-side with a detailed architecture visualization. Composer allows you to view all of the components of your infrastructure architecture and to modify the visualization in real time by modifying the composition in the Editor. When you make changes and save your composition, Composer compiles the Ludwig and updates the visualization. Any changes that you make to the composition are instantly reflected in the visualization, including errors and policy violations. In addition, Composer includes a switch to toggle for the compilation of GovCloud specific compositions. If you toggle this switch while the composition is visible (selected) it will recompile. To access the switch, select the Compile Options icon near the top right of the screen and tick the “Use GovCloud Partition” checkbox.

Note

You can also use your favorite text editor or IDE to modify Ludwig files, and Composer will watch the selected directory for changes, updating the visualization automatically.

If a composition fails to compile, Composer shows an error message indicating the type of error, the line number where the error occurs, and other relevant error information. When the error is fixed, the visualization returns. You can view or hide the error message by selecting the triangular Fix Errors icon in the utility bar on the right border of the screen. Note: The No Errors icon appears when a composition compiles correctly.

Fugue Composer error.

Fugue Composer error.

Selecting an individual element in the visualization provides configuration details through an element Inspector. In the Inspector Panel, click on underlined bindings to view information about that resource. The > character indicates that a field can be expanded or collapsed to view or hide further configuration information. You can click the Inspector icon on the right side of the screen to show or hide this information.

Fugue Composer Inspector Panel.

Fugue Composer Inspector Panel.

In the Editor, top-level bindings are indicated by bold text in a purple rectangle. Comments are gray and italicized.

Generate Composition Feature

The Generate Composition feature provides functionality powered by Fugue Transcriber. It just needs read-only IAM permissions. You can access the feature by selecting the “Generate Composition” button when you open Fugue Composer. Or, if you’ve already opened a directory, you can select the “Generate Composition” button in the bottom-left corner of Composer.

Note: Learn more about Transcriber here.

You’ll be taken to a screen prompting you to enter your AWS account details and optionally customize how resources in your AWS accounts are included in the generated composition. For instance, you can generate a composition that excludes specific resources in the account by AWS service.

The Generate Composition feature describes AWS resources in one of two ways - first, by generating the Ludwig code necessary to create the resource, or second by emitting an External binding that references an existing resource.

  • The first approach is used when generating bindings for included services; and is useful for creating compositions to replicate existing resources in one or more AWS accounts.
  • The second approach is used when generating bindings for excluded services; and is useful for creating compositions without bindings for specific resources. Externals are generated instead of the appropriate type declarations in order for the composition to compile successfully.

In both cases, the generated composition can be edited as needed. Fugue provides capabilities to declare AWS resources, as well as manage them after provisioning. These phases are roughly analogous to “compile time” and “run time” in the traditional computing model. Since this feature generates a composition that is used at “compile time”, the Ludwig bindings in those compositions do not contain information generated during “run time”, such as resource IDs.

Note

Composer only supports generating compositions that can provision the services prepopulated in the “Included AWS Services” picklist under “Service Options.” Compositions can contain excluded services (via externals) but only if an excluded resource is needed by an included resource.

Fugue Composer Generate Composition.

Fugue Composer Generate Composition.

AWS Account Details

There are two ways to enter the AWS account to be scanned.

The “Select AWS Profile” button enables you to pick from a dropdown list populated by profiles in the AWS credentials file.

The “Enter AWS Credentials Manually” button allows you to enter the AWS access key and AWS secret key associated with the account you want to scan. Every time you launch Composer and open the “Generate Composition” screen, you’ll need to reenter your keys.

Note

Keys are only used for scanning your AWS account. Your credentials are not sent to Fugue, nor are they stored in Composer.

Once you’ve selected a profile or entered creds, you can pick the region you want to scan from the drop-down menu.

Service Options

If you want Composer to include a certain AWS service in the scan, select it from the “Excluded AWS Services” list and click the < button to move it to the “Included AWS Services” list. To move that service back to the “Excluded AWS Services” list, click the > button.

Resource Options

Composer offers several ways to filter the results of the services scan.

If you only want Composer to include resources tagged with a specific key or key-value pair, enter the key my-key or the key-value pair my-key:my-value.

The other two options are hidden under “Advanced Options,” so click on the text to reveal them.

The Fugue Conductor has its own set of resources. To include Fugue runtime resources in Composer’s scan, check the “Include Fugue Conductor Resources” box.

Check the box that says “Exclude Resources that are Part of an Existing Fugue Process” if you don’t want Composer’s scan to include resources already under Fugue management. This option requires additional information to authenticate with the Conductor. Select the text box under the “Fugue.yaml File” heading and browse to the fugue.yaml file associated with the Conductor managing the resources. Composer will look for a credentials file in these locations and use it to populate the “Fugue Profile” dropdown menu, from which you may pick the desired profile.

When you are ready, select the “Generate Composition” button. You’ll be prompted to save the result in a directory of your choosing. The default name is Composition.lw and the default location is the current Fugue Project Directory, if one is open; otherwise, it’s your Home directory on macOS or %userprofile% on Windows.

Fugue Composer advanced options for Generate Composition.

Fugue Composer advanced options for Generate Composition.

The Generated Composition

Once you’ve given the composition a name and directory, Composer will scan your AWS account and create a composition incorporating all of your existing AWS infrastructure in the specified region (excluding any filtered resources or services).

When the scan is complete, you’ll see the generated composition in the Editor alongside a visualization of the infrastructure. Each resource declaration in the composition is preceded by a comment that indicates the type and ID of the resource that it represents.

For example:

############################################################
# VPC
#   Generated from AWS resource: vpc-ba7cd2dc
############################################################
ec2-vpc-2: EC2.Vpc.new {
  cidrBlock: "172.31.0.0/16",
  dhcpOptions: ec2-dhcpoptions-1,
  instanceTenancy: EC2.DefaultTenancy,
  region: region,
  resourceId: "vpc-ba7cd2dc",
}

Generating a composition is the first step in migrating existing resources to Fugue management. The second step is launching a process to import the existing resources to Fugue. This can be done with Composer’s Create Process feature.

Create Process Feature

The Create Process feature allows you to launch a process from a composition. It is analogous to executing the Fugue CLI’s run command.

The Fugue Conductor must be installed and booted before you can launch a process through Composer. You can find out more in the install documentation or the Fugue Quick Setup. In addition, the Create Process feature cannot be used with read-only IAM permissions. For more information, jump to the FAQ.

You can access the feature by selecting the “Create Process” button in the bottom-left corner of Composer. You’ll be brought to the “Create Process from <directory> Project Directory” screen, where you can enter process details and set up Conductor authentication. First, in the “Process Details” section, select a composition to run. You can pick one from the current Fugue Project Directory or browse to another folder. Next, give your process-to-be a nickname in the “Process Alias” field.

Fugue Composer Create Process screen.

Fugue Composer Create Process screen.

If your Conductor is installed in the AWS GovCloud (US) region, tick the “Run in GovCloud” checkbox.

Check the “Import Existing Resources” box to use Fugue’s import feature to begin active management of existing resources noted by resource IDs in a composition. If you used the Generate Composition feature to scan your account and create a composition of the results, the composition includes resource IDs. This option is the second step of migration and is analogous to fugue run –import. Keep the box unchecked if you want the Conductor to provision new resources and leave existing resources unmanaged.

If desired, you may create the process in another AWS account by entering the Fugue-generated account ID in the “Run Process in a Separate Account” field. For information on adding, listing, or removing accounts, see the Fugue CLI’s account command or Adding Accounts (Multi-Account).

The “Conductor Authentication” section lets you select an AWS profile or enter AWS credentials manually, similar to the Generate Composition screen. This is used to authenticate with the AWS API. (See our note to learn how Composer handles your credentials.)

The “Fugue Credentials Profile” dropdown menu is populated with profiles sourced from the credentials file, if present. Composer looks for the credentials file in this order of locations.

Warning

Please note that any AWS resources created by this process will be billed to your AWS account. Considering utilizing the Fugue CLI’s dry-run flag in order to preview the resources that will be provisioned or modified by this process.

When you’re all set, select the “Create Process” button.

The Created Process

After communicating with the AWS API, Composer displays a report detailing the results of the process creation. A successful run results in a “Process ‘<alias>’ Created & Running” message, below which you’ll find the process state, account ID, FID (Fugue ID), and alias.

Fugue Composer successful process screen.

Fugue Composer successful process screen.

Once your process has been created, you can manage it using the Fugue CLI. Just navigate to the appropriate project directory and run the desired command. Composer suggests two useful commands to start with, each of which can be copied to your clipboard by selecting the Copy icon next to it. The fugue status command displays the full list of processes on the Conductor. The fugue status <alias> command displays detailed information for the given process.

For a full list of commands, including usage and examples, see the CLI Reference.

Metrics

As part of Composer, Fugue is tracking some metrics related to application usage. The purpose of these metrics is exclusively to help us understand how Composer is being used, and what we can do to improve this tool. Users can opt out of sending metrics at any time by unchecking the “Help Us Improve Composer” checkbox on the Composer welcome screen. All users are anonymous and any data we collect will never be shared externally. You can read the complete details and see an example here.

FAQ

How do I install Fugue Composer?

Fugue Composer is part of the Fugue Client Tools. To install the Fugue Client Tools, log into the Fugue Download Portal and download the appropriate Client Tools package for your platform. Install the Client Tools by following the instructions here. Once the Client Tools have been successfully installed, you can launch Fugue Composer from your Applications directory on macOS, from the Start Menu or desktop shortcut on Windows (or alternatively from c:\Program Files\Fugue\bin), and via the desktop entry for both Ubuntu and RHEL 7.

How do I update Fugue Composer?

While some auto-updates may be deployed for small fixes, the full version of Composer must be updated manually. Existing users will receive a notification announcing any new releases, otherwise to get the latest version visit the Download Portal here.

How do I uninstall Fugue Composer?

You can remove Fugue Composer by uninstalling Fugue Client Tools. Follow the instructions here.

What IAM permissions are necessary for using Fugue Composer?

The Generate Composition feature simply requires read-only permissions for each AWS service to be scanned. For more information, including how to generate an IAM user with read-only permissions, see IAM Policies for Transcriber.

The Create Process feature is powered by the Fugue Conductor and requires additional permissions. If you don’t want to use an AWS profile with administrator access, you can create an IAM user and give it the permissions listed in the fugue-user-iam-policy inline policy, which is attached to the fugue-user-<region> role. Fugue creates these resources during the install process. Once you’ve downloaded and set credentials for the new user, select the associated AWS profile in the “Conductor Authentication” section of the Create Process screen.

For more information about Fugue and IAM, see AWS Permissions and the Fugue CLI.

Where can I find sample compositions to use with Fugue Composer?

If you don’t have any compositions you can test out the Composer with a sample composition from our Composer sample public repo. In addition, the Fugue Fake Book is a great place to start for simple service-specific compositions, as well as more complex full-stack compositions. You can also find more sample compositions in our walkthroughs.

Where can I learn more about how to write Ludwig?

How do I change the parent file directory?

To change the parent file directory, select “Change Project Directory” in the top-left corner of Composer.

How do I zoom in or out?

In the bottom of the visualization pane, next to the “Zoom: X%” text, select the + to zoom in and the - to zoom out. You can also drag the zoom slider to a particular value, or scroll up or down with your mouse wheel or trackpad.

How can I reset the visualization size?

Select the crosshairs-shaped Center View icon in the bottom-right corner of the screen. Composer will fit the diagram to the width of the visualization panel.

How do I update the visualization? (How do I save the composition?)

When you save your composition after making changes in the Editor, Composer will redraw the visualization. Save your composition by pressing CMD+S (in macOS), CTRL+S (in Windows), or by clicking the purple Save Changes button at the top-right of the screen (this button is only visible when a file is modified and has not been saved). If you’d prefer to use your own text editor or IDE, you can edit and save your composition there and Composer will automatically update the visualization when it detects a file change.

How can I hide or show the File Browser or Editor?

Click the View Options icon near the top-right corner of the screen to select the panels you want to show or hide.

How can I send my Composer feedback to Fugue?

We’d love to hear your comments and suggestions! Just click the “Send Feedback” button in the top-right corner of the screen.

What if I have a question that isn’t answered here?

You can reach out to us at support@fugue.co.