Use CircleCI version 2.1 at the top of your .circleci/config.yml file.
1
version: 2.1
Add the orbs
stanza below your version, invoking the orb:
1
2
orbs:
aws-health: circleci/aws-health@2.0.0
Use aws-health
elements in your existing workflows and jobs.
This example demonstrates the usage of the aws-health/check_health command to check for issues before updating an ECS service. If aws-health/check_health command detects issues, the command fails and prevents the aws-ecs/update-service command from deploying a service to a region that's unavailable.
1
2
3
4
5
6
7
8
9
10
11
version: '2.1'
orbs:
aws-cli: circleci/aws-cli@4.0
aws-ecs: circleci/aws-ecs@4.0
aws-health: circleci/aws-health@1.0
workflows:
update-service:
jobs:
- check_health_and_deploy:
context:
- CircleCI-OIDC-Token
This example demonstrates the usage of the aws-health/check_health job to check for issues before deploying an ECS service update. If aws-health/check_health job detects issues, the job fails and prevents the aws-ecs/deploy-service-update job from deploying a service update to the region that's unavailable.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
version: '2.1'
orbs:
aws-cli: circleci/aws-cli@4.0
aws-ecs: circleci/aws-ecs@4.0
aws-health: circleci/aws-health@1.0
workflows:
check_health_and_deploy:
jobs:
- aws-cli/setup
- aws-health/check_health:
aws_region_to_check: us-west-1
max_poll_attempts: 10
- aws-ecs/deploy-service-update:
cluster: ${MY_APP_PREFIX}-cluster
context:
- CircleCI-OIDC-Token
family: ${MY_APP_PREFIX}-service
requires:
- aws-health/check_health
role-arn: arn:aws:iam::123456789012:role/OIDC_ARN
Check for outages in a specific AWS region with the aws-health/check_health using OIDC authentication.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
version: '2.1'
orbs:
aws-cli: circleci/aws-cli@4.0
aws-health: circleci/aws-health@1.0
workflows:
check_health_and_deploy:
jobs:
- aws-health/check_health:
auth:
- aws-cli/setup:
profile: OIDC-USER
role-arn: arn:aws:iam::123456789012:role/VALID_OIDC_CODEDEPLOY_ROLE
aws_region_to_check: us-west-1
context:
- CircleCI-OIDC-Token
Check for outages in a specific AWS region with the aws-health/check_health using static AWS keys for authentication. Import the aws-cli orb and authenticate using the aws-cli/setup command with static AWS keys stored as env_vars (AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY).
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
version: '2.1'
orbs:
aws-cli: circleci/aws-cli@4.0
aws-health: circleci/aws-health@1.0
workflows:
check_health_and_deploy:
jobs:
- aws-health/check_health:
auth:
- aws-cli/setup:
profile: OIDC-USER
role-arn: arn:aws:iam::123456789012:role/VALID_OIDC_CODEDEPLOY_ROLE
aws_region_to_check: us-west-1
context:
- CircleCI-OIDC-Token
This job checks the specified AWS region for any issues. The job passes if there are no issues found. If there are issues in the region, the job will continue to check for issues every 10 seconds until no issues are detected. If the max attempts have been reached, the job will fail.
PARAMETER | DESCRIPTION | REQUIRED | DEFAULT | TYPE |
---|---|---|---|---|
auth | The authentication method used to access your AWS account. Import the aws-cli orb in your config and
provide the aws-cli/setup command to authenticate with your preferred method. View examples for more information.
| Yes | - | steps |
aws_region_to_check | The check_health command will check for issues in this AWS region. This parameter defaults to AWS_REGION that's set as an environment variable.
| No | ${AWS_REGION} | string |
executor | The executor to use for this job. By default, this will use the "default" executor provided by this orb. | No | default | executor |
max_poll_attempts | The max number of attempts to recheck for issues in the specified AWS region. Each attempt takes 10 seconds. By default, 6 attempts will be made for a total of 1 minute.
| No | 6 | integer |
profile_name | AWS profile name to be configured. | No | default | string |
This command checks the specified AWS region for any issues. The command passes if there are no issues found. If there are issues in the region, the command will continue to check for issues every 10 seconds until no issues are detected. If the max attempts have been reached, the command will fail. NOTE: This command requires jq. It will check for jq and install it if necessary.
PARAMETER | DESCRIPTION | REQUIRED | DEFAULT | TYPE |
---|---|---|---|---|
aws_region_to_check | The check_health command will check for issues in this AWS region. This parameter defaults to AWS_REGION that's set as an environment variable.
| No | ${AWS_DEFAULT_REGION} | string |
max_poll_attempts | The max number of attempts to recheck for issues in the specified AWS region. Each attempt takes 10 seconds. By default, 6 attempts will be made for a total of 1 minute.
| No | 6 | integer |
profile_name | AWS profile name to be configured. | No | default | string |
An AWS Docker image built to run on CircleCI that contains the AWS CLI and related tools.
PARAMETER | DESCRIPTION | REQUIRED | DEFAULT | TYPE |
---|---|---|---|---|
resource_class | Configure the executor resource class | No | medium | enum |
tag | Select any of the available tags here: https://circleci.com/developer/images/image/cimg/aws.
| No | '2023.03' | string |
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
# This code is licensed from CircleCI to the user under the MIT license.
# See here for details: https://circleci.com/developer/orbs/licensing
version: 2.1
description: |
This orb enables users to check the health of a specific AWS region for any issues. If there are issues detected, the aws-health/health-check command waits for the issue to be resolved before continuing on to next steps in the job. If the issue is not resolved before the maximum check attempts have been reached, the job will fail. This is especially useful during deployments. The AWS Health Orb can help prevent deployments to an AWS region with known issues.
display:
home_url: https://docs.aws.amazon.com/health/latest/ug/health-api.html
source_url: https://github.com/CircleCI-Public/aws-health-orb
commands:
check_health:
description: |
This command checks the specified AWS region for any issues. The command passes if there are no issues found. If there are issues in the region, the command will continue to check for issues every 10 seconds until no issues are detected. If the max attempts have been reached, the command will fail.
NOTE: This command requires jq. It will check for jq and install it if necessary.
parameters:
aws_region_to_check:
default: ${AWS_DEFAULT_REGION}
description: |
The check_health command will check for issues in this AWS region. This parameter defaults to AWS_REGION that's set as an environment variable.
type: string
max_poll_attempts:
default: 6
description: |
The max number of attempts to recheck for issues in the specified AWS region. Each attempt takes 10 seconds. By default, 6 attempts will be made for a total of 1 minute.
type: integer
profile_name:
default: default
description: AWS profile name to be configured.
type: string
steps:
- run:
command: |
#!/bin/sh
user="$(id -u)"
if [ "$user" -ne 0 ]; then export SUDO="sudo"; else export SUDO=""; fi
if grep "Alpine" /etc/issue > /dev/null 2>&1; then
#shellcheck disable=1090
. "${BASH_ENV}"
if ! command -v jq > /dev/null 2>&1; then
$SUDO apk update
$SUDO apk add jq
fi
else
if ! command -v jq > /dev/null 2>&1; then
$SUDO apt update
$SUDO apt install jq
fi
fi
ORB_STR_REGION_TO_CHECK="$(circleci env subst "${ORB_STR_REGION_TO_CHECK}")"
ORB_STR_PROFILE="$(circleci env subst "${ORB_STR_PROFILE}")"
FILTER="{\"regions\": ["\"${ORB_STR_REGION_TO_CHECK}\""],\"eventTypeCategories\": [\"issue\"], \"eventStatusCodes\": [\"open\",\"upcoming\"]}"
echo "Checking Health for ${ORB_STR_REGION_TO_CHECK} region"
i=1
while [ "$i" -le "$ORB_INT_MAX_POLL_ATTEMPTS" ]
do
echo "Poll Attempt #$i"
AWS_EVENTS=$(aws health describe-events --filter "${FILTER}" --profile "${ORB_STR_PROFILE}" | jq .events)
if [ "${AWS_EVENTS}" = "[]" ]; then
echo "No issues found in ${ORB_STR_REGION_TO_CHECK} region";
exit 0;
elif [ "$i" -eq "$ORB_INT_MAX_POLL_ATTEMPTS" ]; then
echo "Max attempts reached. Issues found in ${ORB_STR_REGION_TO_CHECK} region:"
echo "${AWS_EVENTS}"
exit 1;
else
sleep 10;
i=$((i+1))
fi
done
environment:
ORB_INT_MAX_POLL_ATTEMPTS: << parameters.max_poll_attempts >>
ORB_STR_PROFILE: << parameters.profile_name >>
ORB_STR_REGION_TO_CHECK: << parameters.aws_region_to_check >>
name: Checking Health of AWS << parameters.aws_region_to_check >>
executors:
default:
description: |
An AWS Docker image built to run on CircleCI that contains the AWS CLI and related tools.
docker:
- image: cimg/aws:<<parameters.tag>>
parameters:
resource_class:
default: medium
description: Configure the executor resource class
enum:
- small
- medium
- medium+
- large
- xlarge
- 2xlarge
- 2xlarge+
type: enum
tag:
default: "2023.03"
description: |
Select any of the available tags here: https://circleci.com/developer/images/image/cimg/aws.
type: string
resource_class: <<parameters.resource_class>>
jobs:
check_health:
description: |
This job checks the specified AWS region for any issues. The job passes if there are no issues found. If there are issues in the region, the job will continue to check for issues every 10 seconds until no issues are detected. If the max attempts have been reached, the job will fail.
executor: << parameters.executor >>
parameters:
auth:
description: |
The authentication method used to access your AWS account. Import the aws-cli orb in your config and
provide the aws-cli/setup command to authenticate with your preferred method. View examples for more information.
type: steps
aws_region_to_check:
default: ${AWS_REGION}
description: |
The check_health command will check for issues in this AWS region. This parameter defaults to AWS_REGION that's set as an environment variable.
type: string
executor:
default: default
description: The executor to use for this job. By default, this will use the "default" executor provided by this orb.
type: executor
max_poll_attempts:
default: 6
description: |
The max number of attempts to recheck for issues in the specified AWS region. Each attempt takes 10 seconds. By default, 6 attempts will be made for a total of 1 minute.
type: integer
profile_name:
default: default
description: AWS profile name to be configured.
type: string
steps:
- steps: << parameters.auth >>
- check_health:
aws_region_to_check: << parameters.aws_region_to_check >>
max_poll_attempts: << parameters.max_poll_attempts >>
profile_name: << parameters.profile_name >>
examples:
check_health_command:
description: |
This example demonstrates the usage of the aws-health/check_health command to check for issues before updating an ECS service. If aws-health/check_health command detects issues, the command fails and prevents the aws-ecs/update-service command from deploying a service to a region that's unavailable.
usage:
version: "2.1"
orbs:
aws-cli: circleci/aws-cli@4.0
aws-ecs: circleci/aws-ecs@4.0
aws-health: circleci/aws-health@1.0
workflows:
update-service:
jobs:
- check_health_and_deploy:
context:
- CircleCI-OIDC-Token
check_health_job:
description: |
This example demonstrates the usage of the aws-health/check_health job to check for issues before deploying an ECS service update. If aws-health/check_health job detects issues, the job fails and prevents the aws-ecs/deploy-service-update job from deploying a service update to the region that's unavailable.
usage:
version: "2.1"
orbs:
aws-cli: circleci/aws-cli@4.0
aws-ecs: circleci/aws-ecs@4.0
aws-health: circleci/aws-health@1.0
workflows:
check_health_and_deploy:
jobs:
- aws-cli/setup
- aws-health/check_health:
aws_region_to_check: us-west-1
max_poll_attempts: 10
- aws-ecs/deploy-service-update:
cluster: ${MY_APP_PREFIX}-cluster
context:
- CircleCI-OIDC-Token
family: ${MY_APP_PREFIX}-service
requires:
- aws-health/check_health
role-arn: arn:aws:iam::123456789012:role/OIDC_ARN
check_health_job_with_oidc:
description: |
Check for outages in a specific AWS region with the aws-health/check_health using OIDC authentication.
usage:
version: "2.1"
orbs:
aws-cli: circleci/aws-cli@4.0
aws-health: circleci/aws-health@1.0
workflows:
check_health_and_deploy:
jobs:
- aws-health/check_health:
auth:
- aws-cli/setup:
profile: OIDC-USER
role-arn: arn:aws:iam::123456789012:role/VALID_OIDC_CODEDEPLOY_ROLE
aws_region_to_check: us-west-1
context:
- CircleCI-OIDC-Token
check_health_job_with_static_keys:
description: |
Check for outages in a specific AWS region with the aws-health/check_health using static AWS keys for authentication. Import the aws-cli orb and authenticate using the aws-cli/setup command with static AWS keys stored as env_vars (AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY).
usage:
version: "2.1"
orbs:
aws-cli: circleci/aws-cli@4.0
aws-health: circleci/aws-health@1.0
workflows:
check_health_and_deploy:
jobs:
- aws-health/check_health:
auth:
- aws-cli/setup:
profile: OIDC-USER
role-arn: arn:aws:iam::123456789012:role/VALID_OIDC_CODEDEPLOY_ROLE
aws_region_to_check: us-west-1
context:
- CircleCI-OIDC-Token