> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# circleci/aws-health

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.


## 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.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `aws_region_to_check` | string | ${AWS_DEFAULT_REGION} | 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.
 |
| `max_poll_attempts` | integer | 6 | 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.
 |
| `profile_name` | string | default | AWS profile name to be configured. |

## 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.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `auth` | steps |  | 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.
 |
| `aws_region_to_check` | string | ${AWS_REGION} | 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.
 |
| `executor` | executor | default | The executor to use for this job. By default, this will use the "default" executor provided by this orb. |
| `max_poll_attempts` | integer | 6 | 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.
 |
| `profile_name` | string | default | AWS profile name to be configured. |

## Executors

### default

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


| Parameter | Type | Default | Description |
|---|---|---|---|
| `resource_class` | enum | medium | Configure the executor resource class |
| `tag` | string | 2023.03 | Select any of the available tags here: https://circleci.com/developer/images/image/cimg/aws.
 |

## 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.


```yaml
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.


```yaml
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.


```yaml
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).


```yaml
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
```