Upgrading

This guide is for the platform team that runs BucketDeck. It covers how releases work, how you find out about new ones, and how to upgrade and roll back.

#How versions work

• Semantic versions. Every release has a number MAJOR.MINOR.PATCH, for example 0.2.0:
  • PATCH releases (0.2.1) fix bugs and security issues. They never change parameters.
  • MINOR releases (0.3.0) add features. New parameters always have a safe default.
  • MAJOR releases (1.0.0) may need action from you. Their release notes say exactly what.
• One template pair per release, in the vendor's public bucket in us-east-1. The same URLs work in any Region:

  https://cloudcertainty-bucketdeck-us-east-1.s3.us-east-1.amazonaws.com/<edition>/<version>/main.yaml
  https://cloudcertainty-bucketdeck-us-east-1.s3.us-east-1.amazonaws.com/<edition>/<version>/spoke-role.yaml

  <edition> is starter for BucketDeck Starter and pro for BucketDeck. main.yaml pins the container image by digest, and the image carries the release's code (API, worker, portal deployer and the web portal), so a release can't change underneath you.
• Upgrading is a stack update. Update the stack with the newer template and keep every parameter value. There is no "version" parameter. (The Advanced parameters ArtifactVersionOverride and ImageUriOverride are for Cloud Certainty support only; leave them empty.)
• Published releases never change, so you can roll back with the same procedure.

#Which version am I running?

• Portal: Administration → About.
• Stack output ProductVersion:
  bash

  aws cloudformation describe-stacks --stack-name <stack> \
    --query "Stacks[0].Outputs[?OutputKey=='ProductVersion'].OutputValue" --output text

#How you hear about new releases

• Release notes: cloudcertainty.com/bucketdeck/releases, linked from Administration → About.
• AWS Marketplace: each release is a new version of the listing.
• Release manifest: https://cloudcertainty-bucketdeck-us-east-1.s3.us-east-1.amazonaws.com/<edition>/latest.json names the latest release, whether it contains security fixes, the oldest supported version and the template URLs. You can poll it from your own tooling.

The stack itself never contacts the vendor.

#Before you upgrade

• Read the release notes. A MAJOR release lists any action you need to take, including spoke role changes.
• Use the same permissions as for the install. The update can create, change or delete IAM roles (three have fixed names), Lambda functions, the state machine and so on.
• Running jobs keep running. Jobs started before the upgrade continue on the new worker code (each release reads the job state of the release before it). For a MAJOR release, let long jobs finish first, or check the release notes.
• No backup step is needed. The DynamoDB table and the data bucket are never replaced by an upgrade, and the table has point-in-time recovery.

#Upgrade the hub

#AWS console

1. Open CloudFormation → Stacks, select the stack and choose Update stack → Make a direct update.
2. Choose Replace current template → Amazon S3 URL, paste the new main.yaml URL, choose Next.
3. Keep the current values of every parameter. New parameters appear with their defaults. Leave the Advanced (support use only) parameters empty. Choose Next twice.
4. Acknowledge "AWS CloudFormation might create IAM resources with custom names" and Submit. The update usually takes 5–10 minutes.

#AWS CLI

This keeps the current value of every parameter the new template still has; parameters that are new in this release get their defaults.

STACK=bucketdeck
REGION=eu-west-1
TEMPLATE_URL=https://cloudcertainty-bucketdeck-us-east-1.s3.us-east-1.amazonaws.com/<edition>/<version>/main.yaml

NEW=$(aws cloudformation get-template-summary --region "$REGION" --template-url "$TEMPLATE_URL" \
  --query 'Parameters[].ParameterKey' --output text | tr '\t\r' '  ')
OLD=$(aws cloudformation describe-stacks --region "$REGION" --stack-name "$STACK" \
  --query 'Stacks[0].Parameters[].ParameterKey' --output text | tr '\t\r' '  ')
PARAMS=()
for k in $NEW; do
  case " $OLD " in *" $k "*) PARAMS+=("ParameterKey=$k,UsePreviousValue=true") ;; esac
done

aws cloudformation update-stack --region "$REGION" --stack-name "$STACK" \
  --template-url "$TEMPLATE_URL" --parameters "${PARAMS[@]}" \
  --capabilities CAPABILITY_IAM CAPABILITY_NAMED_IAM
aws cloudformation wait stack-update-complete --region "$REGION" --stack-name "$STACK"

To change a value in the same update, replace its UsePreviousValue=true entry with ParameterValue=<value>. To review the changes first, use create-change-set with the same arguments plus --change-set-name upgrade, then execute-change-set.

#Upgrade the spoke roles

Spoke roles change rarely; the release notes say when. To update them, update each spoke stack (or the StackSet) with the new spoke-role.yaml URL, keeping the parameter values:

aws cloudformation update-stack-set --region us-east-1 --stack-set-name bucketdeck-spoke \
  --template-url https://cloudcertainty-bucketdeck-us-east-1.s3.us-east-1.amazonaws.com/<edition>/<version>/spoke-role.yaml \
  --parameters ParameterKey=TrustedPrincipals,UsePreviousValue=true ParameterKey=ExternalId,UsePreviousValue=true \
    ParameterKey=RoleName,UsePreviousValue=true ParameterKey=AccessLevel,UsePreviousValue=true \
    ParameterKey=BucketScope,UsePreviousValue=true ParameterKey=AllowCloudWatchMetrics,UsePreviousValue=true \
  --capabilities CAPABILITY_NAMED_IAM

The hub role ARNs (SpokeTrustedPrincipals) don't change on upgrade, so existing spoke roles keep working.

#What happens during an upgrade

• The new code is installed first. The update runs the one-off installer task from the new release's image. It checks the licence and copies the new code into the artifacts bucket under the new version's folder (about a minute). Only then are the Lambda functions and the portal updated. If it fails, the update stops and rolls back with nothing else changed. The previous version's folder is kept, so a rollback finds its code.
• The API switches to the new code within seconds; in-flight requests complete.
• Jobs in flight continue; their next step runs on the new worker.
• The portal is redeployed. Users get the new version when they reload the page.
• Data (settings, roles, connections, grants, jobs, templates, favorites, audit) is kept.
• If the update fails, CloudFormation rolls the stack back to the previous release automatically.

#Rollback

To go back after a successful upgrade, upgrade "to" the previous release with the same steps and the previous release's template URL. Every release reads the data of the release before and after it, so rolling back by one release is safe. Rolling back further isn't supported; contact support.

#Version support policy

• Supported: the latest release (N) and the release before it (N−1).
• Security fixes are released only as a new latest release, so upgrade promptly when the release notes or latest.json mark a release as a security release.
• latest.json names the oldest supported version (minimumSupported).

#Troubleshooting

#From Starter to BucketDeck

Upgrading from BucketDeck Starter to Team, Business or Enterprise changes the product, not just the version:

1. In Administration → About, choose the plan under Upgrade to. The upgrade page prepares an AWS Marketplace offer for your account that credits what is left of your Starter subscription; accept it in the AWS Marketplace console (this needs your AWS Marketplace purchasing permissions).
2. Within an hour (or after Refresh licence status) the About page says the new plan is active and asks you to apply the BucketDeck template. Until then BucketDeck keeps working as Starter.
3. Update the stack with the BucketDeck template of the same or a newer version (.../pro/<version>/main.yaml) and keep every parameter value. Only the code changes: the two templates have the same resources, so your table, buckets, users and settings stay as they are.
4. Cancel the Starter subscription's renewal if the upgrade offer didn't already do it.

#Between BucketDeck plans

From Team to Business or Enterprise, or from Business to Enterprise, no stack update is needed, but AWS Marketplace can't change a running BucketDeck contract that came from a private offer, and allows only one BucketDeck agreement at a time. The upgrade therefore replaces the agreement:

1. In Administration → About, choose the plan under Upgrade to. The upgrade page prepares an AWS Marketplace offer for your account that credits what is left of your current contract, and asks AWS Marketplace to cancel your current BucketDeck agreement.
2. In the AWS Marketplace console, first approve the cancellation request of your current agreement, then accept the offer (this needs your AWS Marketplace purchasing permissions). The offer can't be accepted while the current agreement is active.
3. BucketDeck keeps working on your current plan in between, for up to 72 hours. Within an hour of accepting (or after Refresh licence status) the new features turn on.