DOCSEARCHbyAlgolia
Submit Docs

diagram-as-code

repository·main·Indexed 23 days ago

https://github.com/awslabs/diagram-as-code

A CLI tool and Golang library for drawing AWS infrastructure diagrams using YAML code. It provides the awsdac CLI for generating diagrams from YAML or CloudFormation templates, and the awsdac-mcp-server for Model Context Protocol integration. The tool allows users to define AWS resources, hierarchical relationships, and connections using a specific Diagram-as-code (DAC) YAML format, ensuring compliance with AWS architecture guidelines without requiring a GUI or headless browser.

Tokens
14.7K
Snippets
40
Records
74
Agent score
80%

What's inside diagram-as-code

  1. How DAC files are structured

    main

    A Diagram-as-Code (DAC) file is a YAML document composed of three primary sections: DefinitionFiles (to load icon/resource definitions), Resources (to define the AWS components and their hierarchy), and Links (to define connections between resources).

    Diagram:
    DefinitionFiles:  # Specify the location of the definition file
      ...
    Resources:        # Define your AWS resources here
      ...
    Links:            # Define connections between resources
      ...

  2. How Link Grouping Offset calculation works

    main

    The link grouping mechanism follows these rules:

    • Offset Spacing: Links from the same position are offset by increments (e.g., ±5px, ±10px).
    • Direction: The offset is applied perpendicular to the link direction.
    • Ordering: Links are sorted by target/source position to ensure consistent ordering.
    • Formula: The offset is calculated as (index - (count-1)/2.0) * 10 pixels.
    • Directional Mode: When GroupingOffsetDirection is enabled, links are grouped by target direction before the offset calculation is applied.

  3. How the UnorderedChildren reordering algorithm works

    main

    The reordering algorithm processes each link once to minimize distance and overlap. It follows these conceptual steps:

    1. Find Lowest Common Ancestor (LCA): Identifies the first shared parent of the link's source and target.
    2. Determine LCA Direction: Checks if the LCA is horizontal or vertical.
    3. Identify LCA Children: Finds which direct children of the LCA contain the source and target.
    4. Determine Order: Checks if the SourceParent is currently to the left or right of the TargetParent.
    5. Calculate Movement:
      • If the source is to the left of the target, the source's ancestor is moved to the rightmost position of its parent, and the target's ancestor is moved to the leftmost position of its parent.
      • If the target is to the left of the source, the opposite occurs.
    6. Handle Direction Mismatches: If a child's layout direction differs from the LCA's direction, the child is moved to the first position (index 0) to reduce crossing.
    7. Reorder at LCA: The TargetParent is moved to be adjacent to the SourceParent to eliminate intermediate resources from the link path.

  4. Related features for UnorderedChildren

    main

    The UnorderedChildren feature works in conjunction with several core diagram-as-code capabilities to improve layout and link routing:

    • LCA (Lowest Common Ancestor): A mechanism used to find common parent resources in the resource hierarchy.
    • Auto-positioning: Automatically calculates the optimal position for links.
    • Orthogonal Links: Provides right-angle link routing, which achieves better visual results when combined with the optimal ordering provided by UnorderedChildren.

  5. Use Straight and Orthogonal link types

    main

    You can choose between different visual styles for links:

    1. Straight: A direct line between the source and target.
    2. Orthogonal: Right-angled connections that create cleaner, organized paths.
      • Single-arm: Contains one bend (e.g., horizontal then vertical).
      • Double-arm: Contains two bends (e.g., horizontal-vertical-horizontal).

    To use orthogonal links, set the Type: orthogonal key in the link definition.

      Links:
      # Orthogonal (single-arm)
    - Source: Orthogonal1Lambda
      SourcePosition: N
      Target: Orthogonal1Bucket
      TargetPosition: W
      TargetArrowHead:
        Type: Open
      Type: orthogonal

      # Orthogonal (double-arm)
    - Source: Orthogonal2Lambda
      SourcePosition: E
      Target: Orthogonal2Bucket
      TargetPosition: W
      TargetArrowHead:
        Type: Open
      Type: orthogonal

  6. Design architecture diagrams using stacks and parent-child relationships

    main

    When designing diagrams in the Diagram-as-code (DaC) format, you must define both the logical relationship between resources and their physical/hierarchical containment.

    Parent-Child Relationships

    Resources must follow a tree structure based on their hierarchy. For example, a VPC contains Subnets, and Subnets contain EC2 instances. This hierarchy is essential for the DaC engine to render the diagram correctly.

    Using Stacks for Alignment

    To manage how resources are grouped and aligned, use AWS::Diagram::HorizontalStack and AWS::Diagram::VerticalStack. These are used to organize multiple resources to prevent overlapping and to represent redundancy layers:

    • HorizontalStack: Groups children side-by-side.
    • VerticalStack: Groups children one above the other.

    Placement Conventions:

    • North/South: In infrastructure diagrams, 'North' typically represents external entities (Users, Internet Gateway), while 'South' represents internal entities (Administrators, internal systems).
    • East/West: Redundancy layers like Availability Zones or Subnets are often represented horizontally (East-West).
    # Example of grouping subnets using stacks
Subnets:
  Type: AWS::Diagram::HorizontalStack
  Children:
    - PublicSubnets
    - PrivateSubnets
PublicSubnets:
  Type: AWS::Diagram::VerticalStack
  Children:
    - PublicSubnet1
    - PublicSubnet2

  7. Configure Link positions and auto-positioning

    main

    Links represent relationships between resources. You can specify exactly where a link starts and ends on a resource using a 16-wind rose coordinate system (e.g., N, S, E, W, NNE, SSW).

    Auto-positioning allows the system to automatically determine optimal connection points, removing the need for manual coordinates. You can use auto for explicit auto-positioning, or omit the position keys entirely for default auto-positioning behavior. You can also mix manual and automatic positioning.

    Links:
  # Default behavior - auto-positioning
  - Source: ALB
    Target: Instance1
    
  # Explicit auto-positioning
  - Source: ALB
    SourcePosition: auto
    Target: Instance2
    TargetPosition: auto
    
  # Mixed positioning - manual source, auto target
  - Source: ALB
    SourcePosition: E
    Target: Instance3
    TargetPosition: auto
    
  # Traditional manual positioning
  - Source: ALB
    SourcePosition: NNE
    Target: Instance4
    TargetPosition: S

  8. Understand the Canvas and Cloud resource types

    main

    The AWS::Diagram::Canvas and AWS::Diagram::Cloud types serve as the foundational containers for your diagram.

    • AWS::Diagram::Canvas: Represents the drawable area. It is a special resource type that does not draw anything itself, but it acts as the root of the dependency graph. There must be exactly one Canvas resource in your file, and all other resources must be reachable from it.
    • AWS::Diagram::Cloud: Indicates that resources are within the AWS cloud. It is internally treated as an AWS::Diagram::Group. While not strictly required, it is useful for distinguishing cloud resources from on-premises or user environments.

    Example of a basic structure:

    Diagram:
  Resources:
    Canvas:
      Type: AWS::Diagram::Canvas
      Direction: vertical
      Children:
        - AWSCloud
    AWSCloud:
      Type: AWS::Diagram::Cloud
      Preset: AWSCloudNoLogo

  9. Choose the right diagram type for your use case

    main

    Select a diagram type based on the primary information you need to communicate:

    1. Action Flow Diagrams: Best for API documentation and user journey visualization. Focus on the flow of user actions, request/response cycles, and include protocol information (e.g., HTTP, HTTPS) and request type labels on arrows.
    2. Infrastructure Diagrams: Best for network planning and security reviews. Focus on network topology, VPCs, subnets, network boundaries, security groups, network ACLs, and routing. Use a North-South orientation.
    3. Management Diagrams: Best for operations documentation and troubleshooting guides. Focus on administrative access, management tools (Console, CLI, SSM), monitoring, logging, and observability.

  10. Plan your diagram's tree structure and hierarchy

    main

    To ensure logical organization, follow the AWS resource hierarchy when defining parent-child relationships:

    Canvas → AWS Cloud → Region → VPC → Subnet → Instance

    Before writing YAML, perform tree structure planning:

    1. Identify the root resource (typically a user or external service).
    2. Map dependencies from the root down to the leaves.
    3. Group related resources together.

  11. Define resource hierarchies and layout in the Resources section

    main

    Resources are organized using a parent-child model. A resource can contain other resources by listing them under the Children property.

    Layout Control

    • Direction: Controls how children are laid out. Options are horizontal (default) or vertical.
    • AWS::Diagram::HorizontalStack: Groups resources horizontally.
    • AWS::Diagram::VerticalStack: Groups resources vertically.
    • BorderChildren: Positions resources on the edges (N, S, E, W) of a parent container (e.g., for Gateways).
    • SpanResources (Overlay): Draws a resource as a visual overlay spanning multiple other resources. Note: A resource cannot have both Children and SpanResources.
    Resources:
    VPC:
        Type: AWS::EC2::VPC
        Direction: "vertical"
        Children:
            - ELB
            - HorizontalStackGroup
    HorizontalStackGroup:
        Type: AWS::Diagram::HorizontalStack
        Children:
            - Subnet1
            - Subnet2

  12. Structure of a Diagram-as-code (DAC) YAML file

    main

    A Diagram-as-code (DAC) file uses YAML syntax to define architecture. It must consist of three main sections:

    1. DefinitionFiles: Specifies the location of resource definitions (icons, properties, etc.). You can use a URL (e.g., from the awsdac GitHub repository) or a LocalFile path.
    2. Resources: Defines the AWS resources and their hierarchical relationships using the Children property.
    3. Links: Defines the connections (lines) between resources, specifying Source and Target.
    Diagram:
    DefinitionFiles:
      - Type: URL
        Url: https://raw.githubusercontent.com/awslabs/diagram-as-code/main/definitions/definition-for-aws-icons-light.yaml
    Resources:
        # Resource definitions go here
    Links:
        # Connection definitions go here