Skip to content

Commit 48ddeab

Browse files
committed
Updates Readme to include CFN launch command
During bug-bash it was realized that it would have been helpful if there was cfn launch command available for launching ECS updater. This change includes details in docs to fetch Updater CFN template parameters and to launch it.
1 parent 35ec468 commit 48ddeab

File tree

1 file changed

+87
-0
lines changed

1 file changed

+87
-0
lines changed

README.md

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,93 @@ When installed, the CloudFormation template will create the following resources
2020
* An IAM role for the Bottlerocket ECS Updater task itself as well as roles for Fargate and CloudWatch Events
2121
* SSM documents to query and execute updates on Bottlerocket instances
2222

23+
## Getting Started
24+
25+
To install the Bottlerocket ECS Updater, you will need to fetch some information first.
26+
27+
### Subnet info
28+
29+
You should either have a default virtual private cloud (VPC) or have already
30+
[created a VPC](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/get-set-up-for-amazon-ecs.html#create-a-vpc)
31+
in your account.
32+
33+
To find your default VPC, run this command.
34+
(If you use an AWS region other than "us-west-2", make sure to change that.)
35+
36+
```sh
37+
aws ec2 describe-vpcs \
38+
--region us-west-2 \
39+
--filters=Name=isDefault,Values=true \
40+
| jq --raw-output '.Vpcs[].VpcId'
41+
```
42+
43+
If you want to use a different VPC you created, run this to get the ID for your VPC.
44+
Make sure to change VPC_NAME to the name of the VPC you created.
45+
(If you use an EC2 region other than "us-west-2", make sure to change that too.)
46+
47+
```sh
48+
aws ec2 describe-vpcs \
49+
--region us-west-2 \
50+
--filters=Name=tag:Name,Values=VPC_NAME \
51+
| jq --raw-output '.Vpcs[].VpcId'
52+
```
53+
54+
Next, run this to get information about the subnets in your VPC.
55+
It will give you a list of the subnets and tell you whether each is public or private.
56+
Make sure to change VPC_ID to the value you received from the previous command.
57+
(If you use an EC2 region other than "us-west-2", make sure to change that too.)
58+
59+
```sh
60+
aws ec2 describe-subnets \
61+
--region us-west-2 \
62+
--filter=Name=vpc-id,Values=VPC_ID \
63+
| jq '.Subnets[] | {id: .SubnetId, public: .MapPublicIpOnLaunch, az: .AvailabilityZone}'
64+
```
65+
66+
You'll want to pick at least one and save it for the launch command later.
67+
Make sure the subnets you select have Internet access so the updater can reach its dependencies.
68+
Public subnets usually have Internet access via an [Internet gateway](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Internet_Gateway.html) while private subnets may be configured with NAT.
69+
For more information, see [the VPC user guide](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Internet_Gateway.html#vpc-igw-internet-access).
70+
71+
We recommend picking several subnets in different availability zones.
72+
However, if you want to launch in a specific availability zone, make sure you pick a subnet that matches; the AZ is listed right below the public/private status.
73+
74+
### Log Group
75+
76+
You can either choose an existing log group or create a new one to get your ECS updater logs.
77+
78+
You can run this to get the list of existing log-groups
79+
```sh
80+
aws logs describe-log-groups
81+
```
82+
83+
You'll want to pick one and save it for the installation command later.
84+
85+
If you want to create a new log group, run this (Make sure to provide LOG_GROUP_NAME)
86+
```sh
87+
aws logs create-log-group --log-group-name LOG_GROUP_NAME
88+
```
89+
90+
### Install
91+
92+
Now we can install the [CloudFormation template](stacks/bottlerocket-ecs-updater.yaml) to start the ECS updater for your cluster!
93+
94+
There are a few values to make sure you change in this command:
95+
* CLUSTER_NAME: the name of the cluster you want ECS updater to manage Bottlerocket instances in
96+
* SUBNET_IDS: a comma-separated list of the subnets you selected earlier
97+
* LOG_GROUP_NAME: the log group name you selected or created earlier
98+
99+
```sh
100+
aws cloudformation deploy \
101+
--stack-name "bottlerocket-ecs-updater" \
102+
--template-file "./stacks/bottlerocket-ecs-updater.yaml" \
103+
--capabilities CAPABILITY_NAMED_IAM \
104+
--parameter-overrides \
105+
ClusterName="CLUSTER_NAME" \
106+
Subnets="SUBNET_IDS" \
107+
LogGroupName="LOG_GROUP_NAME"
108+
```
109+
23110
## How it works
24111

25112
The Bottlerocket ECS Updater is designed to run as a scheduled Fargate task that queries, drains, and performs updates in your ECS cluster.

0 commit comments

Comments
 (0)