Adopting existing stacks

The Hub lists every stack of a Cloud Certainty product in its Region, however it was installed. A stack installed before the Hub, or with the console, the AWS CLI or the Hub's CloudFormation export, shows as External: the Hub only shows it. Adopt it, and the Hub updates and deletes it like the stacks it installed itself.

Adopting needs Hub 0.1.0-rc.15 or later, with How products are installed (DeployMode) set to Full. Only Hub administrators can adopt stacks.

#What adopting changes

Adopting is a change set that you review before it runs, like every other change the Hub makes:

• Kept as they are: the stack's template, every parameter value, its resources and their data. Nothing is replaced.
• Added: three stack tags, cloudcertainty:managed-by=hub, cloudcertainty:product and cloudcertainty:hub. The stack keeps its own tags. CloudFormation passes stack tags on to the resources that support them, so the change set lists those resources as Modify, with replacement False.
• From then on, CloudFormation runs the stack's changes with the Hub's deployer role, as it does for the stacks the Hub installed.

The adoption and the change set run are recorded in the Hub's audit log.

#Which stacks can be adopted

A stack can be adopted when:

• its name starts with the Hub's Product stack name prefix (StackNamePrefix, cc- by default), or is listed in Other stacks the hub may adopt (AdoptableStacks); see step 1;
• CloudFormation has finished with it: its status is CREATE_COMPLETE, UPDATE_COMPLETE, UPDATE_ROLLBACK_COMPLETE, IMPORT_COMPLETE or IMPORT_ROLLBACK_COMPLETE;
• it is not a nested stack, and not the Hub's own stack;
• it is not managed by Terraform (see Stacks managed by Terraform).

When a stack cannot be adopted, its page in the Hub says why.

#Step 1: Let the Hub change the stack's name

Skip this step if the stack's name starts with cc- (or your StackNamePrefix).

CloudFormation cannot rename a stack, and IAM lets the Hub change only stacks named with the prefix. To let it change a stack with another name, such as sqlark, add the name to the Hub's Other stacks the hub may adopt parameter. IAM then allows the Hub on that name too, and on no other. Only someone who can update the Hub's stack can do this; the Hub never widens its own permissions.

In the CloudFormation console:

1. Select the Hub's stack, cloudcertainty-hub, and choose Update (in newer consoles, Update stack, then Make a direct update).
2. Choose Use existing template, then Next.
3. Under Installing products, enter the stack names in Other stacks the hub may adopt, separated by commas with no spaces, for example sqlark,bucketdeck-prod. Change nothing else. Choose Next, then Next again.
4. Select the IAM acknowledgement and choose Submit.
5. Wait for UPDATE_COMPLETE.

With the AWS CLI, which keeps every other parameter for you:

KEEP=$(aws cloudformation describe-stacks \
  --region eu-west-2 --stack-name cloudcertainty-hub \
  --query "Stacks[0].Parameters[?ParameterKey!='AdoptableStacks'].ParameterKey" --output text \
  | tr '\t' '\n' | sed 's/.*/ParameterKey=&,UsePreviousValue=true/')

aws cloudformation update-stack \
  --region eu-west-2 --stack-name cloudcertainty-hub \
  --use-previous-template \
  --capabilities CAPABILITY_IAM CAPABILITY_NAMED_IAM \
  --parameters 'ParameterKey=AdoptableStacks,ParameterValue="sqlark,bucketdeck-prod"' $KEEP

With Terraform, set adoptable_stacks in the module and apply:

module "cloudcertainty_hub" {
  # ...
  adoptable_stacks = ["sqlark", "bucketdeck-prod"]
}

Keep the list to the stacks you mean to adopt: each name adds to the Hub role's IAM policy.

#Step 2: Adopt the stack in the Hub

1. On the Products page, find the product and choose the stack in its installations. It shows External under Managed by.
2. On the stack's page, choose Adopt into the Hub. The Hub creates the change set and CloudFormation works out the changes, which takes a few seconds.
3. Check the changes: tag updates show as Modify, with replacement False.
4. Choose Adopt. The page refreshes until CloudFormation finishes, then shows the stack as managed by the Hub.

Discard removes the change set and leaves the stack as it was.

#After adopting

The stack's page now offers Update and Delete, as for a stack the Hub installed. An update starts from the stack's current values and keeps its own tags. To have people sign in through the Hub, turn it on in the next update.

#Stacks managed by Terraform

The Hub does not adopt a stack tagged cloudcertainty:managed-by=terraform: Terraform would undo the Hub's tags on its next apply. Keep updating the stack with Terraform; the Hub shows which release to set.

#Handing a stack back

Adopting can be undone outside the Hub:

• Remove the name from Other stacks the hub may adopt. IAM then stops the Hub from changing the stack, whatever its tags say.
• Update the stack with the tag cloudcertainty:managed-by set to another value, such as cloudformation, so the Hub shows it as external again. --tags replaces all the stack's tags, so list the ones to keep too. --role-arn sets the service role CloudFormation uses from then on, in place of the Hub's deployer role.

aws cloudformation update-stack \
  --region eu-west-2 --stack-name sqlark \
  --use-previous-template \
  --capabilities CAPABILITY_IAM CAPABILITY_NAMED_IAM \
  --parameters <every parameter as ParameterKey=Name,UsePreviousValue=true> \
  --tags Key=cloudcertainty:managed-by,Value=cloudformation \
  --role-arn <your CloudFormation role ARN>

#If adoption is refused