Using the Multi-Account Feature

Overview

This example shows you how to manage a simple composition in another AWS account with Fugue’s multi-account feature.

Prerequisites

You’ll need to have the Fugue CLI set up and the Conductor installed before you can run this example. If you haven’t done so yet, it just takes a few quick steps.

The free version of Fugue is limited to two AWS accounts, including the Conductor account. That’s all you need to complete this exercise. If you’re interested in using more accounts, reach out to support@fugue.co to discuss paid options.

What We’ll Do In This Example

We’ll cover how to use the CLI to add and remove a second AWS account with Fugue, and we’ll show you how to list all accounts. We’ll also go over how to run and kill a process in the second account and how to check its status.

What We’ll Have When We’re Done

We’ll be using the HelloWorld.lw composition from Hello World, Part 2: Fugue Basics, so we’ll create the same infrastructure: a Virtual Private Cloud (VPC) in AWS, complete with tags.

How Long It Will Take

About 15 minutes.

Download

You can download the source code for this example from Github: HelloWorld.lw. Save it to the directory in which you ran fugue init during the Quick Setup.

Get editor plug-ins here.

Let’s Go!

Listing Accounts

First off, let’s list the current accounts in the Conductor’s account table. We can do this with the following command:

fugue account list

You’ll see output like this:

Fugue Managed Accounts for main-user/xxxxxxxxxxxx - Wed Feb 8 2017 3:51pm

Name             Account Id           Provider    Provider Id    Credential
---------------  -------------------  ----------  -------------  ----------------------------------------------------------
fugue (default)  fugue-1486155481893  aws         xxxxxxxxxxxx   arn:aws:iam::xxxxxxxxxxxx:role/fugue-FugueIam-PFNBFXKZOARD

As you can see, there’s one account listed already. That’s the fugue (default) account, which is the account in which the Conductor runs. We’re going to add a second AWS account to Fugue’s account table, and it’ll show up in this list. We’ll call this our web account.

Adding an Account

Log into the IAM Dashboard in the AWS Management Console connected to the AWS account you want to add to Fugue. This must be a separate account from the default account, with a different 12-digit AWS account ID.

Click “Roles” in the left sidebar, then click the “Create New Role” button. Go ahead and give your role a name – in this example, we’ll use fugue-web.

Under “Select Role Type,” select “Role for Cross-Account Access,” then “Provide access between AWS accounts you own.”

Select Role Type screen in the AWS Management Console.

Select Role Type screen in the AWS Management Console.

Now we need to enter the 12-digit AWS account ID for the Conductor’s account (the aforementioned fugue (default) account). You can copy it from the “Provider Id” heading in your fugue account list output. For this example, we won’t require MFA, so click “Next Step.”

Go ahead and select a policy to attach to the role. You can choose AdministratorAccess if you’d like, or if you prefer to restrict the role’s access, try our user and installer IAM templates.

On the next screen, review your role information and copy the role ARN. It’ll be in this format: arn:aws:iam::xxxxxxxxxxxx:role/fugue-web, with the X’s replaced by your 12-digit AWS account ID. Click “Create Role,” and switch back to the Fugue CLI.

Execute the following command, replacing the ARN with the one you just copied:

fugue account add --name web --credential arn:aws:iam::xxxxxxxxxxxx:role/fugue-web

The CLI will verify the account and generate a Fugue account ID, which takes the form of the name you gave it (web) plus the Unix timestamp.

[ fugue account ] Adding account "web"

Verifying account ...
[ DONE ] Account "web" with account-id "web-1486591515880" successfully added.

[ HELP ] Please use the account-id, not the name, when specifying an account.

In this case, the web account’s ID is web-1486591515880. Your account ID will be different.

Now, when we run fugue account list, we’ll see two accounts listed:

fugue account list
Fugue Managed Accounts for main-user/xxxxxxxxxxxx - Wed Feb 8 2017 5:14pm

Name             Account Id           Provider    Provider Id    Credential
---------------  -------------------  ----------  -------------  ----------------------------------------------------------
fugue (default)  fugue-1486155481893  aws         xxxxxxxxxxxx   arn:aws:iam::xxxxxxxxxxxx:role/fugue-FugueIam-PFNBFXKZOARD
web              web-1486591515880    aws         xxxxxxxxxxxx   arn:aws:iam::xxxxxxxxxxxx:role/fugue-web

Neat, huh?

Removing an Account

So what happens if you want to remove an account from being managed by Fugue? Easy – with the fugue account remove command:

fugue account remove web-1486591515880

Again, replace the account ID above with your account ID.

The CLI will prompt you to confirm that you want to remove the account, and then it’ll print a success message.

[ fugue account ] Removing account "web-1486591515880"

[ WARN ] Are you sure you want to remove "web-1486591515880" ? [y/N]: y

Removing account...
[ DONE ] Account "web-1486591515880" successfully removed.

You can execute fugue account list again to confirm that the account was removed – you should only see the fugue (default) account.

Note

It’s a good idea to kill any processes running in an account before you run fugue account remove. We haven’t launched any processes yet, so we’re fine, but note for the future that any processes left running in the account at the time of removal will go into a HALT state. In that case, the Fugue-created resources need to be cleaned up manually.

Let’s go ahead and add the account back. Since you went through the work of creating the role already, all you have to do this time is execute the following command, replacing the ARN with your role’s ARN:

fugue account add --name web --credential arn:aws:iam::xxxxxxxxxxxx:role/fugue-web

You can issue fugue account list once more if you’d like, and you’ll see two accounts listed again. You’ll notice you have a new account ID – in our case, the web account is known as web-1486593189640 now.

Running a Composition

Now that we’ve set Fugue up to manage our web-1486593189640 account, let’s deploy some infrastructure in it!

Make sure you’ve downloaded the HelloWorld.lw composition, and let’s run it, using the --account option to target the desired account.

fugue run HelloWorld.lw -a HelloWorld --account web-1486593189640

Again, replace web-1486593189640 with your web account ID.

The CLI will compile the composition, upload it to S3, and ask the Conductor to launch the process, and you’ll see status output:

[ fugue run ] Running HelloWorld.lw

Run Details:
    Account: web-1486593189640
    Alias: HelloWorld

Compiling Ludwig file /Users/main-user/projects/HelloWorld.lw
[ OK ] Successfully compiled. No errors.


Uploading compiled Ludwig composition to S3...
[ OK ] Successfully uploaded.

Requesting the Conductor to create and run process based on composition ...
[ DONE ] Process created and running.


State    Updated    Created    Account            FID                                   Alias       Last Message
-------  ---------  ---------  -----------------  ------------------------------------  ----------  --------------
Running  5:40pm     5:40pm     web-1486593189640  2e52b191-3dc0-403b-bdde-cd9a288fddfc  HelloWorld

[ HELP ] Run the 'fugue status' command to view details and status for all Fugue processes.

Now, log into the VPC Dashboard of the AWS Management Console in the Oregon region. You should see your hello-world-vpc, complete with tags:

Hello World VPC with tags in the AWS dashboard.

Hello World VPC with tags in the AWS dashboard.

Hooray!

Checking Status in an Account

You can use fugue status to report the status of all running processes, as usual, but you can also use the --account option to view only the processes in a given account. So, let’s try that:

fugue status --account web-1486593189640

Again, replace web-1486593189640 with your account ID.

You’ll see output like this:

Fugue Status Report for main-user/xxxxxxxxxxxx - Wed Feb 8 2017 5:47pm

State    Updated    Created    Account            FID                                   Alias       Last Message
-------  ---------  ---------  -----------------  ------------------------------------  ----------  --------------
Running  5:40pm     5:40pm     web-1486593189640  2e52b191-3dc0-403b-bdde-cd9a288fddfc  HelloWorld  SUCCESS

Since we limited status to web-1486593189640, you’ll only see the process you just launched in that account, even if you have processes running in the fugue (default) account.

Killing the Fugue Process

Once a process is launched, it’s bound to the account in which it ran. That means we don’t have to specify the account when we execute any other command manipulating the process, since Fugue already knows which account it’s in. You can suspend, resume, kill, etc., without needing to use the --account option.

So, to terminate the process, just execute fugue kill as usual:

fugue kill HelloWorld

The CLI will prompt you for confirmation, and then it’ll kill the process and tear down the VPC.

[ fugue kill ] Killing running process with Alias: HelloWorld

[ WARN ] Are you sure you want to kill the process with Alias: HelloWorld? [y/N]: y
Requesting the Conductor to kill running composition with Alias: HelloWorld...
[ Done ] The conductor is killing the process with Alias: HelloWorld

That’s all there is to it! We’ve demonstrated the multi-account feature by adding and removing an AWS account, listing all accounts, checking status in a specific account, and running and killing a process in a specific account.

Next Steps

Now that you’re done with this walkthrough, you can read up on Fugue’s multi-account feature. Or, you might use your new skills to try the Building Compute: Instances walkthrough but launch the infrastructure in a separate account. As always, reach out to support@fugue.co with any questions.