aws_synthetics_canaries Resource

[edit on GitHub]

Use the aws_synthetics_canaries Chef InSpec audit resource to test properties of multiple AWS Synthetics canaries.

For additional information, including details on parameters and properties, see the AWS documentation on the AWS::Synthetics::Canary resource.

Installation

This resource is available in the Chef InSpec AWS resource pack.

See the Chef InSpec documentation on cloud platforms for information on configuring your AWS environment for InSpec and creating an InSpec profile that uses the InSpec AWS resource pack.

Syntax

Ensure that the canary exists.

describe aws_synthetics_canaries do
  it { should exist }
end

Parameters

This resource does not require any parameters.

Properties

ids

The unique ID of this canary.

Field: id

names

The name of the canary.

Field: name

codes

This structure contains information about the canary’s Lambda handler and where its code is stored by CloudWatch Synthetics.

Field: code

execution_role_arns

The ARN of the IAM role used to run the canary. This role must include lambda.amazonaws.com as a principal in the trust policy.

Field: execution_role_arn

schedules

A structure that contains information about how often the canary is to run, and when these runs are to stop.

Field: schedule

run_configs

A structure that contains information about a canary run.

Field: run_config

success_retention_period_in_days

The number of days to retain data about successful runs of this canary.

Field: success_retention_period_in_days

failure_retention_period_in_days

The number of days to retain data about failed runs of this canary.

Field: failure_retention_period_in_days

statuses

A structure that contains information about the canary’s status.

Field: status

timelines

A structure that contains information about when the canary was created, modified, and most recently run.

Field: timeline

artifact_s3_locations

The location in Amazon S3 where Synthetics stores artifacts from the runs of this canary. Artifacts include the log file, screenshots, and HAR files.

Field: artifact_s3_location

engine_arns

The ARN of the Lambda function that is used as your canary’s engine.

Field: engine_arn

runtime_versions

Specifies the runtime version to use for the canary.

Field: runtime_version

vpc_configs

If this canary is to test an endpoint in a VPC, this structure contains information about the subnets and security groups of the VPC endpoint.

Field: vpc_config

visual_references

If this canary performs visual monitoring by comparing screenshots, this structure contains the ID of the canary run to use as the baseline for screenshots, and the coordinates of any parts of the screen to ignore during the visual monitoring comparison.

Field: visual_reference

tags

The list of key-value pairs that are associated with the canary.

Field: tags

artifact_configs

A structure that contains the configuration for canary artifacts, including the encryption-at-rest settings for artifacts that the canary uploads to Amazon S3.

Field: artifact_config

Examples

Ensure a canary ID is available.

describe aws_synthetics_canaries do
  its('ids') { should include 'CANARY_ID' }
end

Ensure a canary name is available.

describe aws_synthetics_canaries do
  its('names') { should include 'CANARY_NAME' }
end

Matchers

This InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our Universal Matchers page.

The controls will pass if the describe method returns at least one result.

exist

Use should to test that the entity exists.

describe aws_synthetics_canaries do
  it { should exist }
end

Use should_not to test the entity does not exist.

describe aws_synthetics_canaries do
  it { should_not exist }
end

AWS Permissions

Your Principal will need the Synthetics:Client:DescribeCanariesResponse action with Effect set to Allow.