It is possible to run Jamsocket in an existing AWS account, but customers often prefer to use AWS accounts as a means of isolating a Jamsocket cluster from other AWS resources. This is beneficial for both security and accounting.

These instructions cover creating a new account for Jamsocket on AWS GovCloud, which is significantly different from doing so with a regular AWS account.

1. Ensure your GovCloud account has an organization

On the AWS console (opens in a new tab), click your account name in the upper-right corner and then click “Organization”. If your account does not yet have an organization, you will be able to create one.

2. Create a GovCloud account

Every GovCloud account is associated with a “commercial” AWS account. You must use this commercial account, not the GovCloud account, to create a new GovCloud account.

In a terminal (or AWS CloudShell (opens in a new tab)) with the AWS CLI (opens in a new tab) installed and authenticated as the commercial user, run the following code, replacing the bracketed email and account name:

aws organizations create-gov-cloud-account \
    --email [any-real-email-address@example.com] \
    --account-name [name-of-new-account]

If the account creation was successfully initiated, you should see output like this:

{
    "CreateAccountStatus": {
        "Id": "car-8141fd2447be96f915913b35ef8b4ac8",
        "AccountName": "name-of-new-account",
        "State": "IN_PROGRESS",
        "RequestedTimestamp": "2024-07-29T18:22:29.412000+00:00"
    }
}

Make note of the Id. You will need it in the next step.

3. Get the ID of the created account

As the same user, run:

aws organizations describe-create-account-status --create-account-request-id [Id from step 2]

Account creation happens in the background, so if you don't get back a State of SUCCEEDED, retry in a few minutes.

You should see a result like this:

{
    "CreateAccountStatus": {
        "Id": "car-8141fd2447be96f915913b35ef8b4ac8",
        "AccountName": "name-of-new-account",
        "State": "SUCCEEDED",
        "RequestedTimestamp": "2024-07-29T18:23:12.449000+00:00",
        "CompletedTimestamp": "2024-07-29T18:24:16.544000+00:00",
        "AccountId": "012345678910",
        "GovCloudAccountId": "109876543210"
    }
}

Make note of the GovCloudAccountId for the next step.

4. Invite the account to your GovCloud organization

The newly-created GovCloud account is initially a “standalone” account; it is not automatically part of the organization you created in step 1.

To associate it with your organization, log in to the AWS CLI from your root GovCloud account (not the new GovCloud account you just created).

Run:

aws organizations invite-account-to-organization \
    --target Id=[GovCloudAccountId from step 3],Type=ACCOUNT

5. Accept the invitation from the new account

The new GovCloud account has now been invited to join the organization, but we need to accept on behalf of the new account before it is complete.

We use assume-role to generate temporary credentials for the new account, and then use those credentials to get an ID for the invitation and accept it.

While still authenticated as your root GovCloud account, run:

aws sts assume-role \
  --role-arn arn:aws-us-gov:iam::[GovCloudAccountId from step 3]:role/OrganizationAccountAccessRole \
  --role-session-name AcceptHandshake

You should get a result like this:

{
    "Credentials": {
        "AccessKeyId": "...",
        "SecretAccessKey": "...",
        "SessionToken": "...",
        "Expiration": "2024-07-30T13:39:58+00:00"
    },
    "AssumedRoleUser": {
        "AssumedRoleId": "...:AcceptHandshake",
        "Arn": "arn:aws-us-gov:sts::[account ID]:assumed-role/OrganizationAccountAccessRole/AcceptHandshake"
    }
}

Now configure the AWS CLI (opens in a new tab) to use these credentials by setting the AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN environment variables to the resulting AccessKeyId, SecretAccessKey, and SessionToken, respectively.

To confirm that it worked, run:

aws sts get-caller-identity

Look for the Account field in the result and ensure that it matches the GovCloudAccountID from step 3, rather than your main GovCloud AWS account.

Next, list the invitations to find the organization invitation that was sent:

aws organizations list-handshakes-for-account

Copy the Id field of the invitation, then run:

aws organizations accept-handshake --handshake-id [Id from last step]

The new account should now be listed on your organization page (opens in a new tab).