Creating AWS Network Diagrams with Gemini CLI

The AWS Diagram-as-code tool provides a practical way to manage AWS diagrams. With each update, it has become easier to model complex architectures such as Virtual Private Clouds (VPCs), PrivateLink connections, and service integrations. A recent workflow for a client demonstrates how to use Gemini CLI to represent a VPC connected to AWS Licence Manager via AWS PrivateLink.

TL:DR – The AWS Diagram-as-code tool is rather picky about the structure it uses for its YAML configuration file. Using Gemini CLI allows you to experiment with diagrams and iterate using english language prompts until you get what you need. A serious timesaver.

What is Gemini CLI

Gemini CLI is an open-source AI agent that brings the power of Gemini directly into your terminal. It provides lightweight access to Gemini, giving you the most direct path from your prompt to our model.

Why Gemini CLI?

• 🎯 Free tier: 60 requests/min and 1,000 requests/day with personal Google account
• 🧠 Powerful Gemini 2.5 Pro: Access to 1M token context window
• 🔧 Built-in tools: Google Search grounding, file operations, shell commands, web fetching
• 🔌 Extensible: MCP (Model Context Protocol) support for custom integrations
• 💻 Terminal-first: Designed for developers who live in the command line
• 🛡️ Open source: Apache 2.0 licensed

Installation

For Homebrew on macOS/Linux it is simple to install globally.

brew install gemini-cli

What is AWS Diagram-as-code

AWS Diagram-as-code is a command line interface (CLI) tool which enables drawing AWS architecture diagrams for Amazon Web Services through YAML code. It facilitates diagram-as-code without relying on image libraries.

Why AWS Diagram-as-code?

• 🎯 Free tool, download from GitHub
• 🧠 Up to date with latest AWS diagram styles
• 🔧 It allows managing diagrams with Git by writing human-readable YAML.
• 🔧 Promotes automatiion of diagramming as part of project source code.
• 💻 Terminal-first: Designed for the command line
• 🛡️ Open source: Apache 2.0 licensed

Installation

For Homebrew on macOS/Linux it is simple to install globally

$ brew install awsdac

Building a VPC with PrivateLink

The first scenario I wanted to try to model involves a VPC connecting to AWS Licence Manager through an AWS PrivateLink endpoint. This required creating a new YAML file based on the examples provided with the tool. Heres the prompt I used 

> can you modify the @aws-vpc-rd.yaml file (used by AWS diagram-as-code) to show a VPC connected by an AWS PrivateLink 
  endpoint to an AWS Licence Manager service provider

The following steps were applied by Gemini CLI:

• Removed the original service provider VPC for clarity.
• Reconfigured the client VPC with simplified resources.
• Introduced AWS Licence Manager as the new service provider.
• Created a VPC endpoint and connected it via PrivateLink.

PC1:
  Type: AWS::EC2::VPC
  Title: VPC1 (10.0.0.0/16)
  Children:
    - VPC1PublicStack
    - NLB1
  BorderChildren:
    - Position: W
      Resource: IGW1

VPC:
  Type: AWS::EC2::VPC
  Title: VPC (10.0.0.0/16)
  Children:
    - VPCEndpoint
    - VPCSubnetStack
  BorderChildren:
    - Position: E
      Resource: IGW
VPCEndpoint:
  Type: AWS::EC2::VPCEndpoint

LicenseManager:
  Type: AWS::LicenseManager::LicenseManager
  Title: AWS License Manager

The result: You can see that Gemini CLI had no problem modifying a diagram to show an EC2 instance inside the subnet communicating directly with AWS Licence Manager, traversing a PrivateLink endpoint. This structure would suit production-ready deployments where security and isolation are requirements.

Improving Diagram Readability

Visual clarity is essential. The diagram needed some more work to reposition the endpoints and Internet Gateway to the right of the VPC for better readability. Similarly, the AWS License Manager service provider needed to be nested inside the region and aligned horizontally with the instance, ensuring the diagram flowed in a logical left-to-right order. Here's the prompt.

> thats great can you change the order so the internet gateway and the endpoint are on the right side which will make it clearer

After a few iterations, here is the diagram (edited so as to not show any client details).

Here is the whole YAML file

Diagram:
  DefinitionFiles:
    - Type: URL
      Url: "https://raw.githubusercontent.com/awslabs/diagram-as-code/main/definitions/definition-for-aws-icons-light.yaml"
  Resources:
    Canvas:
      Type: AWS::Diagram::Canvas
      Direction: vertical
      Children:
        - AWSCloud
    AWSCloud:
      Type: AWS::Diagram::Cloud
      Direction: vertical
      Align: center
      Children:
        - Region
    Region:
      Type: AWS::Diagram::Resource
      Preset: Region
      BorderColor: 'rgba(0,0,0,255)'
      BorderWidth: 1
      Title: "Region"
      Children:
        - MainHorizontalStack # To arrange VPCs horizontally
    MainHorizontalStack:
      Type: AWS::Diagram::HorizontalStack
      Children:
        - ConsumerVPC
        - PrivateLinkGroup # For the PrivateLink connection
        - ProviderCloud
    ProviderCloud:
      Type: AWS::Diagram::Cloud
      Title: "AWS Service Provider"
      Children:
        - ProviderVPC

    # Consumer VPC
    ConsumerVPC:
      Type: AWS::EC2::VPC
      Title: "Client VPC"
      Children:
        - AvailabilityZone
        - ConsumerVPCEndpoint # VPC Endpoint for PrivateLink
    AvailabilityZone:
      Type: AWS::Diagram::Resource
      Preset: BlankGroup
      BorderColor: 'rgba(0,0,0,255)'
      BorderWidth: 1
      Title: "AZ1"
      Children:
        - InstanceStack # To hold multiple instances
    InstanceStack:
      Type: AWS::Diagram::VerticalStack # Or HorizontalStack, depending on desired layout
      Children:
        - ConsumerInstance1
        - ConsumerInstance2
    ConsumerInstance1:
      Type: AWS::EC2::Instance
      Title: "Windows Server"
    ConsumerInstance2:
      Type: AWS::EC2::Instance
      Title: "Windows Server"
    ConsumerVPCEndpoint:
      Type: AWS::EC2::VPCEndpoint

    # PrivateLink components
    PrivateLinkGroup:
      Type: AWS::Diagram::Resource
      Preset: BlankGroup
      Children:
        - PrivateLink
    PrivateLink:
      Type: AWS::Diagram::Resource
      Preset: AWS PrivateLink

    # Provider VPC
    ProviderVPC:
      Type: AWS::EC2::VPC
      Title: "AWS License Manager"
      Children:
        - LicenseManagerStack
    LicenseManagerStack:
      Type: AWS::Diagram::VerticalStack
      Children:
        - LicenseManagerService
        - LicenseManagerLabel
    LicenseManagerLabel:
      Type: AWS::Diagram::Resource
      Title: "license-manager.region.amazonaws.com" # License Manager within Provider VPC
    
    LicenseManagerService:
      Type: AWS::LicenseManager
      Title: "AWS License Manager"

  Links:
    # Consumer Instance to VPC Endpoint
    - Source: ConsumerInstance1
      SourcePosition: E
      Target: ConsumerVPCEndpoint
      TargetPosition: W
      TargetArrowHead:
        Type: Open
      Type: orthogonal
    - Source: ConsumerInstance2
      SourcePosition: E
      Target: ConsumerVPCEndpoint
      TargetPosition: W
      TargetArrowHead:
        Type: Open
      Type: orthogonal

    # VPC Endpoint to PrivateLink
    - Source: ConsumerVPCEndpoint
      SourcePosition: E
      Target: PrivateLink
      TargetPosition: W
      TargetArrowHead:
        Type: Open

    # PrivateLink to NLB
    - Source: PrivateLink
      SourcePosition: E
      Target: LicenseManagerStack
      TargetPosition: W
      TargetArrowHead:
        Type: Open

Final Result and conclusion

Using Gemini CLI, product managers can model AWS services with precision without resorting to powerpoint or other image manipulation tools. These YAML-driven diagrams not only aid architecture planning but also provide a repeatable method for documenting network topologies. By iterating through modifications in the YAML files, complex AWS relationships can be represented with accuracy and clarity.