1. circleci/aws-health@2.0.0

circleci/aws-health@2.0.0

Certified
Sections
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.
Created: September 28, 2022Version Published: August 7, 2023Releases: 2
Org Usage:
< 25

Orb Quick Start Guide

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.

Usage Examples

check_health_command

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

check_health_job

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_health_job_with_oidc

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_health_job_with_static_keys

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

Jobs

check_health

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.

Show job Source
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

Commands

check_health

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.

Show command Source
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

Executors

default

An AWS Docker image built to run on CircleCI that contains the AWS CLI and related tools.

Show executor Source
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

Orb Source

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
Developer Updates
Get tips to optimize your builds
Or join our research panel and give feedback
By submitting this form, you are agreeing to ourTerms of UseandPrivacy Policy.