Updating the Hub

Every Hub release is a new, immutable template. Updating the Hub means updating its stack to the new release's template while keeping your parameter values. The Hub can do this itself from its About page; a Hub installed with Terraform is updated with Terraform.

#Which version you run

The Hub's About page shows the installed version and the latest release, with its date, a link to its release notes, and a Security mark for a security release. The stack's ProductVersion output is the installed version too.

Every release is on the release notes page, and the newest is announced in latest.json (opens in a new tab).

#Update from the About page

1. Open the Hub's About page. When a newer release exists, the Update the Hub section shows Update available, or Security update available.
2. Choose Review update. The Hub creates a change set on its own stack with the latest release's template. Every parameter keeps its current value, and parameters new in the release take their defaults. Nothing changes yet.
3. Check the changes, then choose Update the Hub, or Discard.
4. The Hub can be unavailable for a few minutes while CloudFormation replaces it. The page waits, and reloads when the new version answers and its web app is published.

If CloudFormation cannot complete the update, it rolls the stack back and the Hub keeps running its current version. The page says so and links to the stack in the CloudFormation console, where the stack's events say why.

The Hub offers Review update only when all of these hold:

• you are a Hub administrator;
• the latest release is newer than the running one;
• its template comes from the Hub's release bucket;
• the Hub's stack is not managed by Terraform;
• the stack is not busy: its status ends in _COMPLETE.

Otherwise the section says why. If the release manifest cannot be read, the page shows the reason and never claims the Hub is up to date.

The change set runs with the Hub's self-update role, which can change only the Hub's own resources. See the security model.

#Older Hubs: update once by hand

• Before 0.1.0-rc.8: the Hub cannot update itself. Update it once with the console, the AWS CLI or Terraform.
• 0.1.0-rc.8 to 0.1.0-rc.10: these releases compare release candidates as text, so their About page does not offer 0.1.0-rc.11 or later as an update. Update them once with the console, the AWS CLI or Terraform.
• 0.1.0-rc.11 and later: the About page offers every newer release.

#Hubs installed with Terraform

The Terraform module tags the Hub's stack cloudcertainty:managed-by = terraform, and the Hub then never updates itself, so your Terraform state does not drift. Its About page shows the line to set instead:

module "hub" {
  source  = "cloudcertainty/cloudcertainty-hub/aws"
  version = "0.1.0-rc.12"
  # ...
  hub_version = "0.1.0-rc.12"
}

Change version and hub_version to the new release, run terraform init -upgrade, then terraform apply. The module keeps your other inputs, and parameters new in the release take their defaults.

#Update with the console or the AWS CLI

The template URL of a release is:

https://cloudcertainty-hub-us-east-1.s3.us-east-1.amazonaws.com/<version>/main.yaml

In the CloudFormation console:

1. Select the Hub's stack and choose Update.
2. Replace the current template, and enter the new release's template URL as the Amazon S3 URL.
3. Keep the current value of every parameter. New parameters appear with their defaults.
4. Acknowledge that CloudFormation might create IAM resources with custom names, and submit.

With the AWS CLI, keep every current parameter with UsePreviousValue=true. This lists your stack's parameters, then updates it to 0.1.0-rc.12:

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

aws cloudformation update-stack \
  --region eu-west-2 --stack-name cloudcertainty-hub \
  --template-url https://cloudcertainty-hub-us-east-1.s3.us-east-1.amazonaws.com/0.1.0-rc.12/main.yaml \
  --capabilities CAPABILITY_IAM CAPABILITY_NAMED_IAM \
  --parameters $KEEP

aws cloudformation wait stack-update-complete \
  --region eu-west-2 --stack-name cloudcertainty-hub

#Update reminders

The Hub tells you when a newer Hub release exists, and keeps reminding you until the Hub is updated. Reminders are on by default.

They exist from Hub 0.1.0-rc.11: if your Hub's stack has no UpdateReminders parameter, update the Hub first (see older Hubs). Until then, the About page shows Update available when there is one.

#Set them up

Two parameters control them (see the configuration reference):

The reminders go through an Amazon SNS topic, <NamePrefix>-updates, with an email subscription for the reminder address. AWS sends a confirmation email to that address first: open it and confirm the subscription, or no reminder arrives.

#When they arrive

The Hub checks for a new release every 6 hours. It sends a message when it first sees a release, then reminders 1, 3, 7 and 30 days after that, then every 30 days, until the Hub runs that release or a newer one. A newer release starts the schedule again. If several messages were due at once, for example because the check could not run, only one is sent.

The first message's subject is Cloud Certainty Hub <version> is available; reminders say Reminder: Cloud Certainty Hub <version> is waiting to be installed. A security release has [Security] in front. Each message gives the installed and latest versions, the release date, its summary and release notes, how long it has been available, and how to update: from the Hub's About page, with the console or the AWS CLI, or, for a Terraform install, with hub_version.

#Slack, Microsoft Teams and more email addresses

The stack output UpdateTopicArn (Terraform: update_topic_arn) is the topic. Subscribe more endpoints to it: AWS Chatbot, to get the reminders in a Slack or Microsoft Teams channel, or more email addresses:

aws sns subscribe \
  --region eu-west-2 \
  --topic-arn <UpdateTopicArn> \
  --protocol email \
  --notification-endpoint platform-team@example.com

Each new email address gets its own confirmation email.

#Change the address or turn them off

Update the Hub's stack with a new UpdateNotificationEmail, or with UpdateReminders set to Disabled, and keep every other parameter. With Terraform, set update_notification_email or update_reminders and apply.