Windows Azure Design Patterns, Part 1: Architectural Symbols

Today I am beginning a new article series on Windows Azure design patterns, which has been an interest of mine since Windows Azure debuted in 2008. Design patterns are usually expressed in a design pattern language which may also be accompanied by a symbology. In this first article we’ll describe the symbology we’ll be using in this series to represent Windows Azure design patterns in architectural diagrams, also used on my AzureDesignPatterns.com web site and in my upcoming book, The Windows Azure Handbook, Volume 2: Architecture.

We’ll explain the symbology progressively, but let’s start with an example to give you an idea of what we’re talking about. This diagram shows a hosted service with a web role and a worker role that uses a SQL Azure database. Now let’s take a look at the basic elements of the symbology, and by the end of the article we’ll look at a more complex example.

A symbology is warranted because Windows Azure brings a number of concepts, artifacts, terms, and patterns that aren’t in our traditional vocabulary of enterprise architecture diagramming. Some good goals for a symbology are these:

1. Symbols should be simple enough they can be easily drawn by hand legibly on a whiteboard.
2. Symbols should be available to use in productivity tools such as Visio or PowerPoint.
3. Symbols should mesh well with established diagram conventions and traditional symbols.
4. Symbols should serve several levels of granularity, from high-level views down to detailed.
5. Pattern categories such as compute or data should be easy to pick out. We can use color for this. While we shouldn’t depend on color exclusively to communicate (it isn’t always available, and some people are color-blind), it is nevertheless very effective for reinforcement.

Service and Project Symbols
At a very high level, we might just want to reference we are using a particular service:

If we’re focusing on deployment details, showing the management projects (hosted service project, , storage account, AppFabric namespace) may be necessary. Use these file folder-derived symbols for that.

Compute Symbols
Windows Azure Compute gets a lot of attention in architectural diagrams. The service model is pattern-rich, and the other platform services often play a supporting role to hosted services. We’ll color-code compute symbols green. A hosted service consists of one or more roles, each of which contains instances. We can show a role like this, indicating the number of instances in the upper right--in this case 2 or more to maintain high availability--and show the minimum number of instances with discrete symbols. For each instance we have a symbol reflecting what is running in the role, and below it the VM size.

If our diagram is complex or we are short on space, we can condense the above notation to this:

We can use different instance symbols to distinguish a web role from a worker role from a VM role.

Web roles can host web sites (accessed by people) as well as web services (accessed by programs). It’s useful in architectural diagrams to make this distinction even though it makes no difference to Windows Azure. We can use a circle symbol for web sites and a triangular symbol for web services. When a web site and a web service are combined in a single web role, which is common in ASP.NET-WCF projects, we can superimpose the two.

Roles may have endpoints. We can show an input (public) endpoint with a load balancer like this. We also want to show our clients, which might be interactive users or programmatic clients. As we start to show the larger solution it becomes important to mark the data center boundary so it’s clear what is and isn’t in the cloud.

Storage Symbols
We’ll color code data patterns blue. Starting with blob storage, we can show a blob, multiple blobs, or a container of blobs like this. We might also want to relate storage artifacts to a storage account.

If we want more granularity, we can expand to this notation where we can show the count and/or size of blobs in a container, separated into categories. The example below shows the count of image, video, and XML blobs in a container named “media” whose total size is about 20GB.

Queues and messages can be shown in a similar way, with simple representations

or with expanded detail. This shows an order queue whose message payloads come in two types, web orders and phone orders.

Finally, we can take the same approach with table storage: simple representations

or expanded detail, which shows a table’s entity properties, partition key, and row key.

Relational Data Symbols
Keeping with our blue color-coding for data, these symbols represent SQL Azure relational database tables, databases, and virtual database servers.

To show the tables a database contains, we can go to this expanded notation. Alternatively, you can use an established data dictionary notation of your preference.

For SQL Azure reporting, we have these symbols to represent a report definition and a report endpoint.

For SQL Azure Data Sync, we need symbols for a sync group and to show that a database has a 1-way or 2-way sync connection.

We can show OData endpoints for the SQL Azure OData Service or a DataMarket subscription like this:

Communication & Networking Symbols
Communication and networking patterns are color-coded red. The AppFabric Service Bus symbols include service bus connection, service bus queue, message, message buffer, and service namespace.

For Windows Azure Connect virtual networks there are symbols for a virtual network, for a role group member, and for a machine group member.

Security Symbols
For security, we need symbols for the key actors: identity providers (IPs), relying party applications (RPs), and various directories (such as AD) and security token services (STSs)--including some well-known STSs such as the Access Control Service and ADFS. Security symbols are color-coded purple-gray.

To show that a communication channel or a data store is secure, we can annotate it with a lock symbol.

Combining these symbols, here’s how we can show an application (RP) accessing domain identity via ADFS. The Windows Azure web role is the relying party. The user is redirected to ADFS for an AD domain sign-in and upon valid authentication is redirected back to the cloud application with a security token.

A Software-as-a-Service Example
Let’s put all of this together and show what a moderately complex solution looks like using this symbology. Below you see Onboarded.com, a Windows Azure-hosted SaaS solution. This is a single deployment in the cloud that serves multiple corporate clients, with separate databases and Active Directory integration for each tenant. A “T” marks the areas of the diagram that are unique to each tenant.

Hopefully this diagram is easy and intuitive to digest at this point. In the cloud we have a web role and a worker role, both of which make use of Windows Azure storage, SQL Azure databases, and the AppFabric Service Bus (each with tenant-specific resources). The web role contains both a web site and a web service. Both corporate and field users can access this solution, signing in with their domain credentials which are verified through a Service Bus connection to an on-premise AD integration service.

You can download the icons here. Note, this is a work in progress so you can expect the set to grow and see refinement over time. You can use them freely, but I'd appreciate a reference to me, my Windows Azure book series, or my AzureDesignPatterns.com web site.

In our next installment, we’ll start to look at individual patterns topically, starting with compute.