The diagram file

Here is an example diagram file:

diagram "example" [direction=lr] {
  // creating the nodes
  aws.route53 DNS;
  aws.cloudfront cf [label="CDN"];

  group vpc [label="VPC"] {
      aws.elasticLoadBalancing load_balancer [label="Load balancer"];

      group servers [label="Servers"] {
          aws.ec2 server1 [label="Server 1"];
          aws.ec2 server2 [label="Server 2"];
      }
  }

  // creating the edges
  DNS -> cf -> load_balancer [stroke=blue,style=dashed];
  load_balancer => servers;
}

Diagram

Each diagram file must start with the word diagram. This is followed by the name of the diagram which is an identifier. Identifiers are one of the following:

a letter followed by a series of letters, digits, underscores or dashes
a number
any series of characters within double quotes. A double quote must be escaped with a /

After the name of the diagram we have [direction=lr], called an attributes list. Attributes lists are optional and can appears is several other places as we will see later. For a diagram the only supported attribute is direction determining the direction of the drawn graph. The supported values are lr for left-to-right and tb for top-to-bottom.

A diagram contains three kind of elements: nodes, groups or links.

Nodes

A node represents a service in your architecture and it is declared like aws.cloudfront cf [label="CDN"];. aws is the provider of the service, cloudfront is the type of the service and cf is an identifier, like the one we encountered before, for this service. Beware that all nodes in a diagram require a unique identifier. If you declare more than one node with the same identifier the latest node declaration will override all other.

Like we saw for diagrams a node can have attributes. Here is the list of supported attributes for a node:

label: by default a node will be drawn with its identifier as name but you can override this behaviour with the label attribute
labelPosition: location of the label, supported values are , n, s,e, w, ne, nw, se, sw

Links

A link is a directed connection between nodes and groups. Link are declared with the ->, <->, =>, <=> symbols. The second denotes a bidirectional link, the => is a convenience notation to link a node with all the children of a group, see below. For convenience a chain of links can be declared with DNS -> cf -> load_balancer.

Links also support attributes. Here is a list of supported attributes for a link:

stroke: the color of the link in the graph. The value for color can be a color name, e.g. red, blue, or in rgb form with syntax "rgb(32,64,128)"
style: the style applied to the link line, e.g. dashed or solid
width: the width for the link line
label: the label to show for the link

When attributes are declared after a link chain the attributes will apply to all the links in the chain.

Groups

A group is nothing more of a collection of other elements and will be drawn as box encompassing all the child elements. Declaration of a group starts with the keyword group followed by the identifier for the group, optional attributes and the group elements, e.g.

group servers [label="Servers"] {
  aws.ec2 server1 [label="Server 1"];
  aws.ec2 server2 [label="Server 2"];
}

the list of supported attributes for a group is:

stroke: the color of the group border. The value for color can be a color name, e.g. red, blue, or in rgb form with syntax "rgb(32,64,128)"
style: the style applied to the group border, e.g. dashed or solid
width: the width for the group border
fill: the color for the group background
opacity: the opacity of the group background
labelPosition: location of the label, supported values are n, s,e, w, ne, nw, se, sw

Comments

Comments are supported in the form // this is a comment

CloudGram supports initializing a diagram directly from a URL. The share button will generate an copy a URL suitable for sharing with others.