Anthropic aligned docs from JSON definitions

Author: JohnPreston

docs/modules_syntax.rst

@@ -7,6 +7,7 @@
     :titlesonly:
 
     syntax/compose_x/ecs.details/*
+    syntax/compose_x/ecs.details/environment
 
 
 .. toctree::

docs/syntax/compose_x/alarms.rst

@@ -17,8 +17,18 @@ x-alarms
         Properties: {}
         MacroParameters: {}
         Settings: {}
-        Services: {}
-        Topics: []
+        Services:
+          service-name:
+            Scaling:
+              Steps:
+                - LowerBound: 0
+                  UpperBound: 100
+                  Count: 2
+        Topics:
+          - TopicArn: "arn:aws:sns:us-east-1:123456789012:my-topic"
+            NotifyOn: alarm
+          - x-sns: topic-name
+            NotifyOn: all
 
 Define AWS CloudWatch alarms on the different resources, services, and define actions.
 
@@ -50,10 +60,24 @@ Services
 
     x-alarms:
       kafka-scaling-01:
-        Properties: {}
+        Properties:
+          AlarmName: "high-cpu-usage"
+          MetricName: "CPUUtilization"
+          Namespace: "AWS/ECS"
+          Statistic: "Average"
+          Period: 300
+          EvaluationPeriods: 2
+          Threshold: 80.0
+          ComparisonOperator: "GreaterThanThreshold"
         Services:
-          <service_name>:
-            Scaling: {} # Service scaling definition
+          my-service:
+            Scaling:
+              Steps:
+                - LowerBound: 0
+                  UpperBound: 100
+                  Count: 2
+                - LowerBound: 100
+                  Count: 4
 
 
 Scaling
@@ -72,11 +96,19 @@ Topics
 
     x-alarms:
       alarms-01:
-        Properties: {}
+        Properties:
+          AlarmName: "service-health-check"
+          MetricName: "HealthyHostCount"
+          Namespace: "AWS/ApplicationELB"
+          Statistic: "Average"
+          Period: 60
+          EvaluationPeriods: 2
+          Threshold: 1.0
+          ComparisonOperator: "LessThanThreshold"
         Topics:
-          - TopicArn: <str>
+          - TopicArn: "arn:aws:sns:us-east-1:123456789012:alerts-topic"
             NotifyOn: okay
-          - x-sns: <str>
+          - x-sns: notification-topic
             NotifyOn: all
 
 TopicArn
@@ -153,17 +185,32 @@ to define is the Alarm expression
 .. code-block:: yaml
 
     MacroParameters:
-      CompositeExpression: <str>
+      CompositeExpression: "ALARM(alarm-01) and ALARM(alarm-02)"
 
 ServiceName
 --------------
 
 Allows to set the service name or family defined in the compose file, and automatically fills in the ``Cluster``
 and ``ServiceName`` Dimensions.
 
+.. code-block:: yaml
+
+    x-alarms:
+      service-cpu-alarm:
+        MacroParameters:
+          ServiceName: my-web-service
+        Properties:
+          MetricName: "CPUUtilization"
+          Namespace: "AWS/ECS"
+          Statistic: "Average"
+          Period: 300
+          EvaluationPeriods: 2
+          Threshold: 75.0
+          ComparisonOperator: "GreaterThanThreshold"
+
 .. note::
 
-    If you did set ``Dimensions`` in the Properties, these will be overriden.
+    If you did set ``Dimensions`` in the Properties, these will be overridden.
 
 CompositeExpression
 --------------------

docs/syntax/compose_x/common.rst

@@ -222,9 +222,9 @@ This is accomplished by using **AWS Resources Group Tags API** which means, you
 
     Lookup:
       Tags:
-        - Key: Value
-        - Key: Value
-      RoleArn: <str|optional>
+        - Environment: production
+        - Application: web-service
+      RoleArn: "arn:aws:iam::123456789012:role/cross-account-lookup"
 
 .. hint::
 
@@ -233,9 +233,30 @@ This is accomplished by using **AWS Resources Group Tags API** which means, you
 Tags
 ------
 
-The tags are a list of Tags that have been assigned to the resource. Based on the type of resource, this might
+The tags are a list of key-value pairs that have been assigned to the resource. Based on the type of resource, this might
 need to resolve to a single specific resource in your AWS account / region.
 
+Tags can be specified in two formats:
+
+.. code-block:: yaml
+    :caption: Object format (key-value pairs)
+
+    Tags:
+      Environment: production
+      Application: web-service
+      Owner: devops-team
+
+.. code-block:: yaml
+    :caption: Array format (list of objects)
+
+    Tags:
+      - Key: Environment
+        Value: production
+      - Key: Application
+        Value: web-service
+      - Key: Owner
+        Value: devops-team
+
 RoleArn
 --------
 
@@ -247,6 +268,25 @@ your templates in a central CICD account.
 
     Compose-X will never modify the looked up object!
 
+Example Lookup Configuration
+-----------------------------
+
+.. code-block:: yaml
+    :caption: Complete lookup example
+
+    x-s3:
+      existing-bucket:
+        Lookup:
+          Tags:
+            Environment: production
+            Project: myapp
+          RoleArn: "arn:aws:iam::123456789012:role/cross-account-lookup"
+        Services:
+          web-service:
+            Access:
+              bucket: ListOnly
+              objects: RW
+
 
 .. warning::
 
@@ -257,6 +297,10 @@ your templates in a central CICD account.
 
     Tags keys and values are case sensitive.
 
+.. note::
+
+    When using the object format for tags, ECS Compose-X will automatically convert them to the array format internally for AWS API compatibility.
+
 .. _settings_syntax_reference:
 
 Settings

docs/syntax/compose_x/ecs.details/alarms.rst

@@ -15,7 +15,7 @@ services.x-alarms
       app01:
         x-alarms:
           Predefined:
-            RuleName:
+            HighCpuUsageAndMaxScaledOut:
               Topics: []        # Similar to other x-alarms settings
               Settings: {}      # Input values override.
 
@@ -65,10 +65,14 @@ count is equal to the max scaling capacity (or otherwise overriden value).
 .. code-block:: yaml
     :caption: Example at 50% CPU usage and override to 4 tasks.
 
-    - Name: HighCpuUsageAndMaxScaledOut
-      Settings:
-        CPUUtilization: 50             # In percent
-        RunningTaskCount: 4            # Number of tasks to evaluate against.
+    services:
+      app01:
+        x-alarms:
+          Predefined:
+            HighCpuUsageAndMaxScaledOut:
+              Settings:
+                CPUUtilization: 50             # In percent
+                RunningTaskCount: 4            # Number of tasks to evaluate against.
 
 
 HighRamUsageAndMaxScaledOut
@@ -89,12 +93,16 @@ This rule will trigger an alert when the CPUUtilization of a given service will
 count is equal to the max scaling capacity (or otherwise overriden value).
 
 .. code-block:: yaml
-    :caption: Example at 50% CPU usage and override to 4 tasks.
+    :caption: Example at 50% RAM usage and override to 4 tasks.
 
-    - Name: HighRamUsageAndMaxScaledOut
-      Settings:
-        MemoryUtilization: 50          # In percent
-        RunningTaskCount: 4            # Number of tasks to evaluate against.
+    services:
+      app01:
+        x-alarms:
+          Predefined:
+            HighRamUsageAndMaxScaledOut:
+              Settings:
+                MemoryUtilization: 50          # In percent
+                RunningTaskCount: 4            # Number of tasks to evaluate against.
 
 
 

docs/syntax/compose_x/ecs.details/ecs.rst

@@ -14,10 +14,13 @@ services.x-ecs
       serviceA:
         image: nginx/nginx
         x-ecs:
-          CapacityProviderStrategy: [CapacityProviderStrategyItem]
-          EnableExecuteCommand: bool
-          CpuArchitecture: str
-          OperatingSystemFamily: str
+          CapacityProviderStrategy:
+            - CapacityProvider: FARGATE
+              Base: 1
+              Weight: 2
+          EnableExecuteCommand: true
+          CpuArchitecture: ARM64
+          OperatingSystemFamily: LINUX
 
 CapacityProviderStrategy
 ============================
@@ -76,6 +79,7 @@ Examples
             - CapacityProvider: FARGATE_SPOT
               Base: 4
               Weight: 8
+          EnableExecuteCommand: true
 
 
 .. code-block:: yaml
@@ -91,6 +95,7 @@ Examples
             - CapacityProvider: FARGATE
               Base: 1
               Weight: 2
+          CpuArchitecture: X86_64
       nginx:
         deploy:
           labels:
@@ -103,6 +108,7 @@ Examples
             - CapacityProvider: FARGATE_SPOT
               Base: 4
               Weight: 8
+          CpuArchitecture: X86_64
 
 In the above example, where grafana and nginx are part of the same task definition and therefore same ECS Service,
 we do the following:

docs/syntax/compose_x/ecs.details/monitoring.rst

@@ -14,7 +14,11 @@ services.x-monitoring
     services:
       serviceA:
         x-monitoring:
-          CWAgentCollectEmf: bool|SidecarConfig
+          CWAgentCollectEmf: true
+          CollectEmf:
+            CloudwatchAgent:
+              UseLatest: true
+              InterpolateWithDigest: false
 
 Shorthands for monitoring features.
 
@@ -35,21 +39,24 @@ See the `AWS CloudWatch agent & EMF Configuration for details`_ of what's config
 boolean value
 -------------
 
-When set to true|false, enables the sidecar using the `latest CloudWatch agent image from AWS ECR Public`_.
+When set to true, enables the sidecar using the `latest CloudWatch agent image from AWS ECR Public`_.
+When set to false, disables EMF collection entirely.
 
 SidecarConfig
 --------------
 
 This configuration allows you to define more options to control the behaviour of the used sidecar image.
 You must explicitly set either ``UseLatest`` or `OverrideImage`_
 
-.. code-block::
+.. code-block:: yaml
 
-    x-monitoring:
-      CWAgentCollectEmf:
-        InterpolateWithDigest: bool
-        OverrideImage: str
-        UseLatest: bool
+    services:
+      serviceA:
+        x-monitoring:
+          CWAgentCollectEmf:
+            InterpolateWithDigest: true
+            OverrideImage: "public.ecr.aws/cloudwatch-agent/cloudwatch-agent:1.247357.0b252275"
+            UseLatest: false
 
 .. hint::
 
@@ -58,12 +65,14 @@ You must explicitly set either ``UseLatest`` or `OverrideImage`_
 OverrideImage
 ^^^^^^^^^^^^^^
 
-.. code-block::
+.. code-block:: yaml
 
-    x-monitoring:
-      CWAgentCollectEmf:
-        InterpolateWithDigest: false
-        OverrideImage: public.ecr.aws/cloudwatch-agent/cloudwatch-agent:1.247357.0b252275
+    services:
+      serviceA:
+        x-monitoring:
+          CWAgentCollectEmf:
+            InterpolateWithDigest: false
+            OverrideImage: "public.ecr.aws/cloudwatch-agent/cloudwatch-agent:1.247357.0b252275"
 
 .. note::
 
@@ -80,12 +89,14 @@ the digest.
     This setting is recommended if you want to ensure that the image used is going to be consistently the same throughout
     the lifecycle of your Task Definition revision.
 
-.. code-block::
+.. code-block:: yaml
 
-    x-monitoring:
-      CWAgentCollectEmf:
-        InterpolateWithDigest: true
-        UseLatest: true
+    services:
+      serviceA:
+        x-monitoring:
+          CWAgentCollectEmf:
+            InterpolateWithDigest: true
+            UseLatest: true
 
 .. _AWS CloudWatch agent & EMF Configuration for details: https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Embedded_Metric_Format_Generation_CloudWatch_Agent.html
 .. _latest CloudWatch agent image from AWS ECR Public: https://gallery.ecr.aws/cloudwatch-agent/cloudwatch-agent