x-alarms ¶
x-alarms:
alarm-01:
Properties: {}
MacroParameters: {}
Settings: {}
Services: {}
Topics: []
Define AWS CloudWatch alarms on the different resources, services, and define actions.
Note
You can only create new alarms.
Properties ¶
ECS Compose-X will automatically detect whether your properties define an Alarm or a Composite Alarm.
See AWS CW Alarms definition and AWS CW Composite Alarms definition
Attention
When linking to Services and/or Topics, the OKActions, AlarmActions will be overridden accordingly.
Attention
You can only create new alarms. To use existing alarms with new services would required to modify the actions of that alarm to be useful, which would be an external change to any IaC.
Services ¶
x-alarms:
kafka-scaling-01:
Properties: {}
Services:
<service_name>:
Scaling: {} # Service scaling definition
Scaling ¶
Allows to define the Scaling of an ECS Service based on that alarm. See Scaling for more details.
See autoscaling_on_custom_alarm for an example.
Topics ¶
x-alarms:
alarms-01:
Properties: {}
Topics:
- TopicArn: <str>
NotifyOn: okay
- x-sns: <str>
NotifyOn: all
TopicArn ¶
A string representing the topic ARN. The topic ARN must be valid (will be validated).
x-sns ¶
Allows you to define a SNS topic that was defined in compose-x files already. Supports new created topics and topics found via Lookup.
NotifyOn ¶
This allows you to determine whether the messages should be published based on the alarm status.
Default is
alarm
Value |
Alarm actions |
---|---|
all |
OKActions AlarmActions |
alarm |
AlarmActions |
okay |
OKActions |
Linking to x-resources properties ¶
Hint
This feature only works for Dimensions and Namespace at the moment. Future versions will add support for alarms defined using Metrics (mutually exclusive to Namespace )
When defining new alarms, you probably want to create these alarms for resources in the compose file, i.e, x-elbv2.
So from the Namespace, x-alarms will then scan resources which were defined in the compose definitions and for the dimensions you wish to import the value from, interpolate and modify the final CloudFormation template to link automatically to that resource.
Supported x-resources ¶
-
x-elbv2 (requires AWS/ApplicationELB or AWS/NetworkELB as value for Namespace)
x-elbv2 ¶
Marker for LB:
x-elbv2::<lb_name>
Marker for Target Group:
x-elbv2::<lb_name>::<service>::<port>
Hint
The port is required as you might have multiple targets for the same given service family.
timeout_seconds: 60
desync_mitigation_mode: defensive
drop_invalid_header_fields: True
http2: False
cross_zone: True
Settings: {}
Listeners:
- Port: 8080
TargetGroupAttributes:
deregistration_delay.timeout_seconds: "30"
proxy_protocol_v2.enabled: "true"
preserve_client_ip.enabled: "true"
# - Key: deregistration_delay.timeout_seconds
AlarmDescription: Alarm for Healthy hosts < 2 within a period of 1 minute
ComparisonOperator: LessThanThreshold
DatapointsToAlarm: 1
Dimensions:
- Name: LoadBalancer
Value: x-elbv2::lbC
- Name: TargetGroup
Value: x-elbv2::lbC::app03::5000
EvaluationPeriods: 1
MetricName: HealthyHostCount
Namespace: AWS/NetworkELB
Period: 60
Statistic: Maximum
Threshold: 2.0
TreatMissingData: notBreaching
lba-only-issues:
Properties:
AlarmName: unheathy_hosts_alb
ActionsEnabled: True
AlarmDescription: Alarm for Healthy hosts < 2 within a period of 1 minute
ComparisonOperator: LessThanThreshold
DatapointsToAlarm: 1
Dimensions:
- Name: LoadBalancer
Value: x-elbv2::lbA
EvaluationPeriods: 1
MetricName: HTTPCode_ELB_5XX_Count
Namespace: AWS/ApplicationELB
Period: 60
Statistic: Maximum
Threshold: 2.0
TreatMissingData: notBreaching
MacroParameters ¶
For x-alarms, MacroParameters is here to help define in a simpler way a composite alarm. More specifically, all you have to define is the Alarm expression
MacroParameters:
CompositeExpression: <str>
ServiceName ¶
Allows to set the service name or family defined in the compose file, and automatically fills in the
Cluster
and
ServiceName
Dimensions.
Note
If you did set
Dimensions
in the Properties, these will be overriden.
CompositeExpression ¶
String with a logical high level expression of the composite alarm.
In your expression, use the alarm name as defined in the compose file, not using the AlarmName property! ECS Compose-X will automatically map to the CFN Alarm being created.
For example
x-alarms:
alarm-01:
Properties {}
alarm-02:
Properties: {}
composite-alarm:
MacroParameters:
CompositeExpression: ALARM(alarm-01) and ALARM(alarm-02)
Examples ¶
x-alarms:
alarm-01:
Properties:
ActionsEnabled: true
AlarmDescription: A simple CW alarm
ComparisonOperator: GreaterThanOrEqualToThreshold
DatapointsToAlarm: 1
Dimensions:
- Name: Cluster
Value: DEV
- Name: Topic
Value: topic01
- Name: ConsumerGroup
Value: consumer01
EvaluationPeriods: 5
MetricName: TotalLagForTopicAndConsumerGroup
Namespace: lag-metrics-v4
Period: 60
Statistic: Sum
Threshold: 1.0
TreatMissingData: notBreaching
Services:
app03:
Access: NA
Scaling:
ScaleInCooldown: 60
Steps:
- Count: 1
LowerBound: 0
UpperBound: 1000
- Count: 3
LowerBound: 1000
UpperBound: 10000
Topics:
- TopicArn: arn:aws:sns:eu-west-1:012346578900:topic/sometopic
- x-sns: topic-01
x-sns:
topic-01:
Properties: {}
Hint
When the alarms is only for the service, the alarm gets created in the same stack as the service(s). When the alarm has both services and topics, the alarms are created in a separate stack.
JSON Schema ¶
Model ¶
x-alarms ¶
x-alarms.spec.json |
||||
x-alarms |
||||
type |
object |
|||
properties |
||||
|
https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-alarms-bucket.html |
|||
type |
object |
|||
|
x-resources.common.spec.json#/definitions/Settings |
|||
|
type |
object |
||
properties |
||||
|
type |
string |
||
|
Name of the service/family the alarm is for. Automatically sets Dimensions. |
|||
type |
string |
|||
|
x-resources.common.spec.json#/definitions/Services |
|||
|
List of SNS Topics to use for notifications |
|||
type |
array |
|||
items |
#/definitions/TopicDef |
|||
additionalProperties |
False |
|||
definitions |
||||
|
SNS Topic definition for x-alarms.Topics[] |
|||
type |
object |
|||
properties |
||||
|
The SNS Topic full ARN |
|||
type |
string |
|||
format |
arn:aws(?:-[a-z]+)?:sns:[a-z0-9A-Z-]+:d{12}:[a-z0-9A-Z-._]+$ |
|||
|
The name of a topic defined in x-sns.Topic. |
|||
type |
string |
|||
|
The status to trigger the SNS action on. |
|||
type |
array |
|||
default |
all |
|||
items |
type |
string |
||
enum |
all, alarm, okay |
Definition ¶
{
"$schema": "http://json-schema.org/draft-07/schema#",
"id": "x-alarms.spec.json",
"$id": "x-alarms.spec.json",
"title": "x-alarms",
"description": "x-alarms",
"type": "object",
"additionalProperties": false,
"properties": {
"Properties": {
"type": "object",
"description": "https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-alarms-bucket.html"
},
"Settings": {
"$ref": "x-resources.common.spec.json#/definitions/Settings"
},
"MacroParameters": {
"type": "object",
"properties": {
"CompositeExpression": {
"type": "string"
},
"ServiceName": {
"type": "string",
"description": "Name of the service/family the alarm is for. Automatically sets Dimensions."
}
}
},
"Services": {
"$ref": "x-resources.common.spec.json#/definitions/Services"
},
"Topics": {
"description": "List of SNS Topics to use for notifications",
"type": "array",
"items": {
"$ref": "#/definitions/TopicDef"
}
}
},
"definitions": {
"TopicDef": {
"description": "SNS Topic definition for x-alarms.Topics[]",
"type": "object",
"properties": {
"TopicArn": {
"type": "string",
"description": "The SNS Topic full ARN",
"format": "arn:aws(?:-[a-z]+)?:sns:[a-z0-9A-Z-]+:\\d{12}:[a-z0-9A-Z-._]+$"
},
"x-sns": {
"type": "string",
"description": "The name of a topic defined in x-sns.Topic."
},
"NotifyOn": {
"description": "The status to trigger the SNS action on.",
"type": "array",
"default": "all",
"items": {
"type": "string",
"enum": [
"all",
"alarm",
"okay"
]
}
}
}
}
}
}
Test files ¶
You can find the test files here to use as reference for your use-case.