Haishi's Blog

Bono

2019-12-09T20:12:00.005-08:00

When we learn classic compute algorithms, we don't start with learning how a computer is built. We don't start with how a transistor works or how to build integrated circuits. Instead, we go straight with the abstraction - bits, commands, programs and such. I think we should take the same approach when we learn quantum computing. Instead of trying to understand the bizarre quantum world, we should take some quantum behaviors granted and go straight with higher-level abstracts such as qubits and quantum gates. And once we grasp these basic concepts, we should go even a level higher to use a high-level language like Q# and focus on how quantum algorithms work, and how we can apply quantum algorithms on practical problems.

Bono is an open source quantum algorithm visualizer I'm building in the open. This project is inspired by a few existing systems such as Quirk, IBM Q Experience, and the Programming Quantum Computers book. Bono is a Javascript-based visualizer that features:

Drag-and-drop quantum circuit editing.
Dynamic circuit evaluation.
Works offline in a browser. No server is needed.
Generates Q# code.

I've also created a YouTube channel dedicated to quantum algorithms. My goal is to create an easily digestable course for regular software developers to learn about quantum computing without needing to understand any underlying quantum physics.

Bono is at its infancy. And I'm still a new student in the quantum world. I intentionally develop both Bono and the video series in the open. I hope the early results can inspire collaborations so that we can explore the quantum computing world together.

Last but not least, you can find more Q# related contents at the Q# Advent Calendar 2019.

Open Service Broker API and Service Fabric Service Catalog

2018-04-06T11:57:00.001-07:00

A service running on cloud often has dependencies on external services such as storage and identity. Because the lifecycle management of these external service instances is separate from your application, your application must implicitly assume these services are properly configured and available when it runs. The idea of Open Service Broker API (OSB API) is to allow applications to take control of the lifecycle of dependent services by allowing them to explicitly define and verify external service instance statuses when they run. The API defines a set of operations for an application to provision, update, and delete external service instances as needed. Azure provides an OSB API implementation, OSB for Azure (OSBA), as an open source project here.

Applications can certainly talk to OSB API directly to manage external service instances. However, this requires applications to be aware of OSB API configurations, which creates an unnecessary coupling to OSB API. Instead, the OSB API community has advised using a Service Catalog to provide platform-native representation of external service instances so that the applications concern only with the hosting platform. For example, Kubernetes Service Catalog is an extension to Kubernetes control plane that allows applications to use external services with native Kubernetes artifacts and tools, without ever needing to know about OSB API. The OSB API configuration in this case is a platform configuration concern and uncoupled from the applications.

This blog article records my journey to enable a Service Fabric Catalog Service (SFCAT) on Service Fabric. The following diagram is adapted from this diagram to illustrate where SFCAT fits.

OSB Check and OSB mock

When I started with SFCAT, OSBA was still under active development, and there were some discrepancies between OSBA implementation and the OSB API spec. I was afraid I would be tempted to write an OSBA-specific version, so I started to create a mock OSB API implementation that strictly followed the spec. To make sure the mock OSB API staying true to the spec, I then created a OSB checker to automate the tests against the spec. I later donated both projects to OSB API and they are now hosted under the OSB API org on GitHub: https://github.com/openservicebrokerapi/osb-checker.

To try out the OSB mock and OSB checker, follow these steps:

Clone https://github.com/openservicebrokerapi/osb-checker.git (assuming to your home folder)
Launch mock server
cd ~/osb-checker/2.13/mock
npm install
node mockOSB.js
Run tests
cd ~/osb-checker/2.13/tests
npm install
npm test

Service Fabric Service Catalog (SFCAT)

With a mock OSB API implementation, I moved to SFCAT implementation itself. I looked at Kubernetes control plane, and I envied how it had extension points such as kubectl plugins and custom resources. So, I took the opportunity to prototype an extensible control plane for Service Fabric. The idea was to support new resource types in both backend and frontend simply by injecting some configuration files and binaries. I wanted the newly defined resource types to be “alive” (which I called “smart entities”), meaning a resource instance could monitor itself and reconcile its current state with the desired state. I believed this was a better architecture than Kubernetes controllers because it was simpler and more scalable. The idea was captured in my earlier blog article.

I also started to create a command-line tool, sfcat, to interact with the prototype control plane. It started as an OSB API specific client. Gradually, OSB-specific parts are contained into a few classes, leaving the command-line tool a generic tool to operate on any “smart entities”.

You can find the SFCAT source code here: https://github.com/Haishi2016/sfcat. Once you clone the repo and deploy the application to your Service Fabric cluster, you should be able to link it to the mock server (or other OSB API implementations) by modifying the appsettings.json file under the CatalogService project:

"ActorSwitches": {
    "OSBEntityCatalogActor": {
        "OSBEndpoint": "<OSB API endpoint>",
        "OSBUser": "<user name>",
        "OSBPassword": "<password>"
    }
}

Then, you should be able to use sfcat to interact with the control plane following the instructions here: https://github.com/Haishi2016/sfcat/blob/master/docs/sfcat.md.

Declarative definitions

Yet, there was still a problem. Because I couldn’t extend Service Fabric application model, I couldn’t provide a way to declaratively define the external service dependencies in application manifests. So, I came up with an alternative -- I created a BrokeredServiceActor service, which supported declarative configurations of an external service in its configuration file (the actor also supported direct OSB API connection but that was optional):

This gave me declarative definition. However, there was still a problem. Service Fabric didn’t allow dynamically composing a service into another application. Fortunately, I thought about that a few years ago and created the SFNuGet project, which allowed individual Service Fabric services to be packaged, shared, discovered and dynamically composed into other applications through NuGet mechanisms.

Conclusion

So, I had got all the pieces – a OSB mock server, a test suite to test it, a SF control plane prototype, a command-line tool to interact with it, a service wrapper actor to support declarative definition, and a mechanism to distribute the package. SFNuGet has been released for a long time; and OSB-check is in the good hands of the community. Unfortunately, SFCAT is half-baked, and I’ve been since dragged away to other projects, leaving SFCAT untouched for several months by now. I just recently got approval to make it a public repository. I wish someone out there would be interested and drag me to the project to make some new progresses on this. Tweet to @Haishi2010 or email to hbai@microsoft.com if you were interested.

Setting up High available MySQL deployments on Service Fabric using containers and Docker Compose

2017-11-16T14:15:00.001-08:00

Microsoft Service Fabric is a PaaS offering that provides not only container orchestration, but also Microservices programming models and paradigms for you to build your next-gen, cloud-native Microservices on cloud.

This blog article examines the new Docker Compose support, which allows you to take an existing Docker Compose file and deploy it directly onto a Linux-based Service Fabric cluster. As for scenario, I chose to deploy high-available MySQL clusters. Specifically, I’ll deploy two high-available MySQL deployments, one using MySQL Replication, and another using MySQL Cluster. All source code is available here: https://github.com/Haishi2016/Vault818/tree/master/Nuka-Cola-Bottler.

I’ll assume you’ve done the following:

You’ve created a Linux-based Service Fabric cluster on Azure.
Your cluster should have the Service Fabric DNS service enabled.
You’ve installed and configured sfctl.

MySQL Replication

MySQL Replication enables data to be copied from a master MySQL server to one or more slave MySQL servers. MySQL Replication doesn’t provide automatic failovers (please correct me if I’m wrong). When master fails, you can manually promote a slave to a new master. For a more detailed description, please see this MySQL doc.

For this scenario, I’ve created two new Docker images for both master (hbai/mysql-master-sf) and slave (mysql-slave-sf). Both container images use custom scripts as entry points to configure replication before launching the MySQL services. The images also support a CRATE_PET_DB flag. If the flag is set, the startup scripts automatically create a simple pet_db database for testing purposes.

Master

The master start-up script creates a MYSQL_REPLICA_USER and sets up its privileges for replication. It then creates a pet_db database if the CREATE_PET_DB flag is set:

echo "CREATE USER '$MYSQL_REPLICA_USER'@'%' IDENTIFIED BY '$MYSQL_REPLICA_PASS'; " | "${mysql[@]}"
echo "GRANT REPLICATION SLAVE ON *.* TO '$MYSQL_REPLICA_USER'@'%'; " | "${mysql[@]}"
echo "GRANT REPLICATION CLIENT ON *.* TO '$MYSQL_REPLICA_USER'@'%'; " | "${mysql[@]}"
echo "FLUSH PRIVILEGES; " | "${mysql[@]}"

if [ "$CREATE_PET_DB" ]; then
echo "CREATE DATABASE pet_db; " | "${mysql[@]}"
echo "USE pet_db; CREATE TABLE pet (name VARCHAR(20), owner VARCHAR(20), species VARCHAR(20), sex CHAR(1), birth DATE, death DATE); " | "${mysql[@]}"
fi

Slave

The slave start-up script is a bit more complex. After creating the pet_db, it enters a loop to wait for the master to get ready. When the master is ready, it continues to configure itself as the slave to the master:

if [ "$CREATE_PET_DB" ]; then
         echo "CREATE DATABASE pet_db; " | "${mysql[@]}"
         echo "USE pet_db; CREATE TABLE pet (name VARCHAR(20), owner VARCHAR(20), species VARCHAR(20), sex CHAR(1), birth DATE, death DATE); " | "${mysql[@]}"
fi

for i in $(seq $((MYSQL_MASTER_WAIT_TIME + 1))); do
     if ! mysql "-u$MYSQL_REPLICA_USER" "-p$MYSQL_REPLICA_PASS" "-h$MYSQL_MASTER" -e 'SELECT 1;' | grep -q 1; then
         echo >&2 "Waiting for $MYSQL_REPLICA_USER@$MYSQL_MASTER"
         sleep 1
     else
         break
     fi
done

MasterPosition=$(mysql "-u$MYSQL_REPLICA_USER" "-p$MYSQL_REPLICA_PASS" "-h$MYSQL_MASTER" -e "SHOW MASTER STATUS \G" | awk '/Position/ {print $2}')
MasterFile=$(mysql "-u$MYSQL_REPLICA_USER" "-p$MYSQL_REPLICA_PASS" "-h$MYSQL_MASTER" -e "SHOW MASTER STATUS \G" | awk '/File/ {print $2}')

echo >&2 "Master File: $MasterFile"
echo >&2 "Master Position: $MasterPosition"

echo "CHANGE MASTER TO MASTER_HOST='$MYSQL_MASTER', MASTER_PORT=$MYSQL_MASTER_PORT, MASTER_USER='$MYSQL_REPLICA_USER', MASTER_PASSWORD='$MYSQL_REPLICA_PASS', MASTER_LOG_FILE='$MasterFile', MASTER_LOG_POS=$MasterPosition;" | "${mysql[@]}"
echo "START SLAVE;" | "${mysql[@]}"

Compose

The Docker Compose file is straightforward. In your deployments, you can change your replica user and password as needed.

version: '3'
services:
     master:
         image: hbai/mysql-master-sf
         restart: unless-stopped
         ports:
             - 3306:3306
         environment:
             - MYSQL_ROOT_PASSWORD=master_passw0rd
             - MYSQL_REPLICA_USER=replica
             - MYSQL_REPLICA_PASS=replica_Passw0rd
             - CREATE_PET_DB=true
     slave:
         image: hbai/mysql-slave-sf
         restart: unless-stopped
         ports:
             - 3307:3306
         environment:
             - MYSQL_ROOT_PASSWORD=slave_passw0rd
             - MYSQL_REPLICA_USER=replica
             - MYSQL_REPLICA_PASS=replica_Passw0rd
             - MYSQL_MASTER=master
             - MYSQL_MASTER_WAIT_TIME=10
             - MYSQL_MASTER_PORT=3306
             - CREATE_PET_DB=true

Try it out

To deploy the cluster, use the following command.

sfctl compose create --name MySqlReplication --file-path <path to your docker-compose.yml>

Once deployed, you can follow these steps to do a simple replication test:

SSH into the Service Fabric cluster node where the master container is running. By default, you should be able to SSH into each node via port 3389-3393 for a 5-node cluster.
Attach to the master container (you can get your container name by sudo docker ps)
sudo docker exec –it <your container name> /bin/bash
Connect to your master database and insert a new record to the pet_db (the following sample assumes you use the default master_passw0rd as the root password):

mysql -uroot -pmaster_passw0rd
use pet_db;
INSERT INTO pet VALUES('Puffball', 'Diane','hamster', 'f', '1999-03-30', NULL);

SSH into the Service Fabric cluster node where the slave container runs.
Attach to the slave container.
Connect to the slave and select records from the pet_db. You should see the record you just inserted above has been replicated over:

mysql -uroot -pslave_passw0rd
use pet_db;
select * from pet;

Optionally, you also can use command SHOW SLAVE STATUS\G; to examine how your replica is configured.

The following screenshot shows the view on the slave:

MySQL NDB Cluster

A MySQL NDB Cluster is comprised of a Management server, a number of Data Nodes and a number of SQL Nodes. The Data Nodes form an in-memory clustered storage engine (called NDB), and the SQL Nodes form a stateless API layer for database clients. Please see this MySQL doc for a more detailed description of MySQL NDB Cluster.

It’s much harder to set up a fully automated MySQL Cluster using Docker Compose. MySQL Cluster requires management node, data node and service node to be launched in specific order. Although you can set up launching dependencies among containers, Docker Compose doesn’t wait for the applications inside containers to become ready before it moves down the dependency chain. To work around this, I’ve created a (very) simple gatekeeper container that provides a Web API for callers to check in/check out tokens. As containers launch, they send signals to the gatekeeper to report their stats. Other containers who depend on the states will wait until the states reach desired goals.

For this scenario, I created four custom Docker images: management (hbai/ha), ndb (hbai/ndb), mysql (hbai/mysql) and gatekeeper (hbai/gatekeeper). The first three images are all based on the official MySQL Cluster image (mysql/mysql-cluster), with custom entry point script to coordinate container launches.

Gatekeeper

Gatekeeper is a prototype-quality Node.js server that handles simple PUT requests and GET requests. A client can add a new token by sending a PUT request to a key route; and a client can retrieve a token by GET from the key route. There are no authentications or conflict avoidances implemented in this prototype. However, because for each of the keys there will only be one writer (and multiple readers), the gatekeeper works reasonable well in this setting.

Management Node

The management node launches ndb_mgmd service with a custom config.ini file as shown below. Please note: 1) all nodes are identified by DNS names instead of IP addresses; 2) ndb nodes are assigned with specific ServerPort. We need fixed ports so that we can define necessary port bindings on containers.

[ndbd default]
NoOfReplicas= 2
[ndb_mgmd]
Hostname= management
[ndbd]
HostName= ndb1
ServerPort= 50501
[ndbd]
HostName= ndb2
ServerPort= 50502
[mysqld]
HostName= mysql

In the start-up script, you’ll see a workaround to configure the host name. This is temporary workaround because of a bug in Service Fabric that causes hostnames not injected into containers correctly. This should not be necessary when the bug is fixed.

#workaround to set hostname
sed -i 's/localhost.localdomain/management/' /etc/sysconfig/network
HH=`cat /etc/hostname`
tail -1 /etc/hosts | sed -e "s/${HH}/management/" >> /etc/hosts

When you use the above ini file that uses DNS names instead of IP addresses, ndb_mgmd will do a name resolution check upon start. This puts us in a difficult situation – on one hand the management node needs to wait for other containers (ndb nodes and mysql node) to come up so that the name resolutions will pass; on the other hand other nodes are waiting for the management to start. To deal with the situation, I used a two-phase wait: When a container is launched, it sets its state to LAUNCHED. And when it finishes initialization, it sets its state to READY. The management node waits for the LAUNCHED states from other containers before it does name resolutions. And the other containers wait for the READY sate of management node before they continue.

ndb_mgmd is launched without the --nodeamon flag. This is because we need to send the READY state after we’ve launched the ndg_mgmd service.To stop the container from exiting after sending the READY state, an infinite loop is added at the end:

while true; do sleep 1000; done

Data Nodes

The compose file defines two data nodes, ndb1 and ndb2. A data node is initiated with a custom my.cnf file that points to the management node:

[mysqld]
ndbcluster
ndb-connectstring=management
user=mysql

[mysql_cluster]
ndb_connectstring=management

The container image takes a NDBID parameter, which will be used as a postfix to the host name. Please note this id has no connection with NodeId in MySQL Cluster settings. It’s just a postfix to the host name to distinguish different data node instances.

MySQL Node

The MySQL node waits for all other containers before it calls the default entrypoint.sh from the base image to initialize the database, and then launches the mysqld service.

while [[ "$MANAGEMENT" != "READY" ]] || [[ "$NDB1" != "READY" ]] || [[ "$NDB2" != "READY" ]]
do
   MANAGEMENT=`curl -sL http://gatekeeper:8180/management`
   NDB1=`curl -sL http://gatekeeper:8180/ndb1`
   NDB2=`curl -sL http://gatekeeper:8180/ndb2`
   sleep 1
   echo "Waiting: management:$MANAGEMENT; ndb1:$NDB1; ndb2:$NDB2"
done

/entrypoint.sh mysqld
mysqld

Compose

The compose file is a bit longer in this case. Please note how the port bindings on ndb* nodes match with the config.ini file above.

version: '3'
services:
    gatekeeper:
       image: hbai/gatekeeper
       hostname: gatekeeper
       ports:
         - 8180:8180
    management:
       image: hbai/ha:30
       hostname: management
       depends_on:
          - gatekeeper
       ports:
         - 1186:1186
    ndb1:
       image: hbai/ndb:8
       hostname: ndb1
       depends_on:
          - gatekeeper
          - management
       ports:
          - 2202:2202
          - 50501:50501
       environment:
          - NDBID=1
    ndb2:
       image: hbai/ndb:8
       hostname: ndb2
       depends_on:
          - gatekeeper
          - management
       ports:
          - 2202:2202
          - 50502:50502
       environment:
          - NDBID=2
    mysql:
       image: hbai/mysql:10
       hostname: mysql
       depends_on:
          - gatekeeper
          - management
          - ndb1
          - ndb2
       environment:
          - MYSQL_RANDOM_ROOT_PASSWORD=true
       ports:
          - 3306:3306
networks:
    default:
       external:
          name: nat

Try it out

To deploy the cluster, use the following command.

sfctl compose create --name MySqlCluster --file-path <path to your docker-compose.yml>

Once deployed, you can follow these steps to do a simple test:

SSH to the node where the mysql container is running.
Get the auto-generated root password from the mysql container log:
sudo docker logs <container name> 2>&1 | grep PASSWORD
Attach a shell to the mysql container.
Launch ndb_mgm and observe the cluster status:

ndb_mgm
show

The above command should return something like the following screenshot.
Exit ndb_mgm and launch mysql:
mysql -uroot -p
Enter the temporary password to log in.
Update the root password:

ALTER USER 'root'@'localhost' IDENTIFIED BY '<new password>';

Create a new database and insert a record:

CREATE DATABASE pet_db;
USE pet_db; CREATE TABLE pet (name VARCHAR(20), owner VARCHAR(20), species VARCHAR(20), sex CHAR(1), birth DATE, death DATE);
INSERT INTO pet VALUES('Puffball', 'Diane','hamster', 'f', '1999-03-30', NULL);

In Service Fabric Explorer, restart (deactivate and then activate) the node where mysql container is running. This simulates a machine crash.
Attach to the container again and launch mysql. Select records from the pet_db and you should see the record is preserved:

mysql -uroot -p<your new password>
use pet_db;
select * from pet;

The above command should return the record:

Closing Thoughts

Service Fabric allows you to take your existing containerized workloads and host it on a Service Fabric cluster. And once your workload is migrated to Service Fabric, you can start enjoying Service Fabric programming models and other programming paradigms enabled by Service Fabric to write your cloud-native Microservices applications.

This article shows you how to construct HA MySQL clusters on Service Fabric yourself. If you want to use MySQL on Azure but don’t want to take on any responsibility of managing the infrastructure yourself, you should consider the new Azure Database for MySQL offering.

Autonomous State Reconciliation with Actors

2017-08-07T15:10:00.001-07:00

Desired State Configuration (DSC) is a proven technique for configuration management. It’s been widely used in configuration management systems such as Chef, Puppet and PowerShell DSC. Besides, many PaaS systems, such as OpenShift and Kubernetes, use a Resource+Controller pattern where a Controller observes an object store (such as etcd) and reconciles object current states with their desired states, as shown in the following diagram. In such settings, consumers interact with the Object Store through a simple CRUD API. And storage events are observed by registered Controllers. The Controllers react to these event and take necessary actions, which often bear the goal to reconcile object states with desired states.

This blog proposes an alternative implementation of the pattern using stateful actors, as shown in the following diagram:

There are two major differences between the two implementations:

There are no separate Controllers in the second implementation. Instead, an actor encapsulates its state and its state reconciliation logic. This makes system configuration and extension easier – instead of adding a new object type and a new matching controller type, you can register a new actor type and the actor will take care of its state maintenance autonomously.
The Object Store in the second implementation is actually just a stateless gateway, as it doesn’t maintain any internal state. This helps to avoid the cases when the Object Store becoming the bottle neck (or a single point of failure) of the system. You can scale out the gateway easily. And because it works directly with individual actors, you don’t have a potential bottleneck at Controller layer, either.

For actor systems that don’t support actor catalogs, you may want to implement a catalog actor that corresponds to each actor type, as shown in the following diagram. The catalog actor maintains a catalog of associated actors, and provides cross-entity/actor functionalities such as searching and transforming actors. The catalog actors can be organized in different namespaces to provide scaling as well as (logical) tenant isolation.

All the actors, except for the state reconciliation logics, are quite similar. If your actor system supports polymorphism, you can create base catalog actor and base entity actor from which you can inherit common behaviors, such as the notion of current state and desired sate. Furthermore, if you feel having a separate actor type per entity is too heavy, you can use a generic implementation where state management logics are dynamically injected, driven by some sort of manifest:

The actor-implementation seems to have some architectural advantages: 1) There are no centralized components. The store gateway can be scaled out easily (as it’s stateless), and states are scattered into different actor instances. 2) Great parallelism. All actors execute on their own thread/process/machine, and you can rebalance actor instances easily based on system loads. 3) Great isolation. Each actor can decide on its own reconciliation intervals, and they don’t rely on a centralized messaging/event system to get events from an external store. Furthermore, An actor (controller) won’t be able to subscribe to events from other entities types (unless they are explicitly exposed/allowed). This avoids a rogue controller tapping into arbitrary entity event streams to make damages. 4) Better resiliency. Even if the store gateway completely fails, none of the states is missing. When the gateway comes back, it can resume service as normal by referencing to catalog service by namespaces. On the other hand, a single (and complete) actor failure has a much less blast radius than a data-store failure.

Before I conclude this article, I have to mention that I haven’t done a performance comparison between the two implementations. On the surface, having an actor instance per entity does present some overheads, but I believe the price is small and worth paying in most cases.

Cloud: A New Perspective

2017-07-17T18:46:00.001-07:00

it’s Sunday evening at 7, and I’m still at my desk. I just finished some preparation work for a conference, and now I’m brooding over the idea of writing this article before going home for dinner. I’ve been planning to write this for a long time, to explain my view on cloud. And now, I think it’s been delayed long enough. So be it, since I’ve already started typing, let’s see how far it goes…

The *-aaS myth

I’ve spoken to many customers and developers who try to adopt cloud. Regardless of the project size and type, I often see people making a difficult decision at the beginning of the project: do I do a “lift-and-shift”, or start over and write a “cloud-native” app? Or, for people who are more familiar with cloud jargon – do I do IaaS or PaaS?

Do I do IaaS or PaaS? This is the exact wrong question to ask first. It takes some work to peel the onion, so please bear with me.

The whole set of *-aaS acronyms, IaaS, PaaS and SaaS, offers a nice, layered view of a cloud platform. At the bottom you have the infrastructures; then on top of the infrastructure you have the platform to develop and host your services; and on top of that are managed services. This is indeed a powerful and precise model of a cloud platform. Maybe just because it’s so elegant and logical, people start to believe when you put your applications on cloud, you should fit your applications into one or several of these layers.

Should you?

Let’s go back to the basics. Let’s say you have an application, and you want to run it. What do you need? Some CPU, some memory, some disk space, and some networking, maybe. When you run the application locally (or, “on-premises”), you acquire and manage compute resources yourself – to buy a PC, to rent a server rack, and so on. The big promise of cloud is that cloud can offer such compute resources to you so that you are not bogged down with such nugatory tasks. How does cloud offer these resources to you? Ding-ding-ding! Through one of the *-aaS thingies, of course! The catch is, however, the ways to work with different *-aaS thingies are VERY different. The world of cloud is bright and shinny, but you have to carefully pick one of the *-aaS paths because all these paths lead to a LAYER of the cloud, not the ENTIRE cloud. You might be happy with the original lift-and-shift with IaaS but find out that you have to start over anyway because PaaS is such a different paradigm. You might have invested heavily in PaaS, and some cool kids come around, containerized your application and moved it over to cloud without even touching your code. How do you know if you were picking the right path? How do you know if you’d get the return you expected? How do you know if your choice will remain sound for future iterations of your project?

How do we resolve this situation? It’s actually fairly easy – we just need to think about the situation from a slightly different angle - If all you need is certain amount of resources, why would you care HOW the resources is given to you? Shouldn’t you be able to just say, “hey, Mr. cloud, can you give me some resources so I can run my stuff?” Does it really matter if these resources are packaged as a virtual machine, a container, a cluster of nodes, or a managed deployment slot? No, thank you. Give me some CPU and memory and I’m good.

The CMR model

Cloud is a huge pool of compute resources. On top of this pool swim many different workloads. That’s what cloud is. No IaaS, no PaaS or SaaS, it’s just a pool of resources in which your workloads can live and thrive.

This resource pool view makes logical sense, however it’s probably too coarse to be useful. Having been working for Microsoft for 5 years, I’ve started to like acronyms. So here’s my offer – a new model to describe cloud that I call “CMR”, or Control-Mesh-Resource. The model can be illustrated by the following diagram (hey, I’m not an artist – it’s much prettier in my mind…).

At the top of the model is the Control Plane. The control plane takes your workload and schedule it on to some sort of resources. It offers all the good things a cloud can possibly offer you – failover, dynamic scale, high-availability and such. You give your workload to it and it takes care everything for you. The Control Plane projects your workloads onto a Compute Plane, or a Resource pool. The resource pool can be made up by ANYTHING that can carry out compute tasks. As long as your workload’s requirement is satisfied, you don’t care. Your application exists on the resource pool if the form of a Service Mesh. A Service Mesh defines a connectivity scope, a security domain and a management boundary. I should point out that in CMR model, there are no fixed clusters. Service Meshes are completely mobile and can span across many different compute resource types, including “traditional” PaaS clusters.

The best way to visualize the CMR model is to think the Control Plane as a pane of colored spotlights that sweep across the Resource Plan and project Service Meshes on them – that’s the CMR model.

CMR is a unified view of IaaS and PaaS. When you use IaaS, you are using some APIs to provision a virtual machine and then deploy your workload to it. When you use PaaS, you use a different set of API. CMR abstracts away API differences because at the end, you are marrying your workload with some compute resources.

The *-aaS model comes from a cloud platform’s perspective and is resource-centric. CMR, on the other hand, comes from a customer’s perspective and is workload-centric. The *-aaS explains the structure of a cloud platform, but it’s lacking critical details on workloads themselves. CMR takes a workload-centric view. It concerns about how workload is projected into compute resources.

Examine the cloud through the CMR lens

CMR model is quite powerful. It can be used to describe many cloud architectures. I’ll attempt to explain a few here. As I’m getting tired typing, I’ll not going to spend much time expanding on each of the topics. I think they are quite self-explanatory anyway.

Serverless – CMR isn’t concerned about how the resources are acquired. It provides the broadest view on Serverless. Under the CMR model, Serverless isn’t bound to specific frameworks or implementations. Resources are simply acquired by a generic auction process. However, what’s more important here is CMR’s Service Mesh abstraction, which allows scattered, reactive components to be treated as a holistic application. This mesh concept is missing in many existing Serverless implementations, btw.
Hybrid – CMR isn’t concerned about where the resources come from. As long as a resource is offered by someone, it can participate in workload auctions. In other words, an auction process may involve resources from multiple cloud platforms as well as on-premises compute resources. The characteristics of the resources may impact their candidacy for specific workload, but the overall process is exactly the same for cloud, for on-premises, and for individual machines.
Cluster federation – CMR doesn’t define resource offers at certain granularity. A resource provider can offer up a portion of a CPU, a container, or even an entire compute cluster. For instance, if your application is described by Docker Compose and you want to have a global deployment, you can simply ask for two K8s clusters from different regions. The two clusters form a cross-region (but loosely-coupled) Service Mesh where your application instances run. Or, if your application needs a virtual machine, you can choose a resource that offers you the required machine.
Cloud agnostic – CMR offers an abstraction at very high-level. This high-level abstraction hides the differences among different clouds, different scheduling and orchestration frameworks, and workload architectures.
New compute options – The CMR model can be used to describe scheduling workloads on all types of compute resources – physical machines, virtual machines, containers, GPUs, ASICs, dedicated instances, shared instances, spot instances, IoT devices, … Again, as long as someone is making an offer, the resource can participate in workload distribution.
Intelligent edge – CMR doesn’t define a fixed Compute Plane. New compute resources can come in at anytime. And when existing resources disappears, CMR moves the “color spotlight” and projects the workload somewhere else. This model works for Intelligence Edge especially well, because it allows different device types with different technical stacks, different capacities and availabilities to be unified into a dynamic Compute Plane. Furthermore, it allows seamless transitions between cloud and edge so that applications have flexibility to allocate compute resources where it makes most sense. For example, an application may deploy ML inference in cloud at the beginning, and then moves the inference engine to capable devices for lower latency and massive scale. At the same time, the less capable devices can still take advantage of cloud-hosted inferences.

Key Principles of a CMR System

CMR model is an abstract model. However, it’s not hard to implement CMR for real. As I’m just talking about theoretical model here, I shall not continue with suggestions on design and implementation details. However, I envision the following as some of the key principles in such a system.

Open Compute Plane. The Compute Plane shall be made up by an open (abiding to required security constraints, of course) registration system, with which agents representing resources can register and start to make offers.
Workload auction. The workload shall be projected to the Compute Plane through an request-offer matching auction system.
Service Mesh isolation. Service Mesh is the key construct to provide a multi-tenant Compute Plane. It provides connectivity, security domain and management boundary. It can also be extended to support tracing, auditing and smart routing etc.
Desired State management. Service Mesh state is monitored and reconciled with desired state regularly. This is the key to provide QoS offerings to applications.
Minimum API. The beauty of CMR model resides in simplicity. The Control Plan shall offer a minimum set of API – probably less that 10 methods. And there really aren’t many: resource registration, state report and reconciliation, workload distribution are probably the only three mandatory things.

Closing Thoughts

As you can probably see, this article is posted on Monday instead of Sunday. I paused for a day because I was debating if CMR should be presented as a new model for the entire cloud, or just a unified view of PaaS. Two of me discussed for a long time. And eventually I decided since the model covers all compute on cloud, it’s from a different perspective, and it goes beyond what existing PaaS systems commonly offer, I’ll call it a new cloud model.

Of course, this model didn’t come from vacuum. It’s heavily influenced by existing models, systems and designs. And the fact that it abstracts away infrastructural details does make it look like PaaS – but that’s just a byproduct of abstraction. Again, the key difference between *-aaS and CMR is that CMR takes a customer’s perspective and focuses on how workload is scheduled, not how resources are offered. I hope you find this model interesting. And I do believe an implementation of the CMR model can provide a powerful, unified compute fabric that spans across the globe. And I do think I need to leave for dinner now.

Setting up a highly-available Minecraft server using Containers on a Linux-based Service Fabric cluster

2017-03-07T17:29:00.001-08:00

In the last GDC, Mark Fussell (@mfussell) and I presented a demo of setting up a high-available Minecraft server using Microsoft Service Fabric. The idea of the demo is to showcase how Service Fabric is used as a Docker container orchestration engine and brings certain Quality of Service (QoS) improvements to legacy applications without any modifications. I’ve got a few requests to reveal the details on how the demo was set up, so here it goes – everything you need to set up a similar demo yourself.

Disclaimer: This article uses an upcoming feature that supports container data volumes. The feature is coming soon, and I’ll update the article when this feature is released (which means if you see this the feature hasn’t been released yet). Please see product roadmap for more details.

Updates (9/7/2017): Container data volumes support is now in production (https://docs.microsoft.com/en-us/azure/service-fabric/service-fabric-containers-volume-logging-drivers).

Background

Many legacy applications are designed as single-tenant and single-site. For such applications, it’s a common practice to deploy a dedicated server (or server cluster) for a specific customer (tenant). In case disaster recovery (DR) is required, a passive secondary is used, with data from active site constantly replicated at certain interval, which is driven by the system’s Recovery Point Objective (RPO). When a disaster happens, the secondary is switched to primary and the data replication direction is reversed. In some systems, the secondary is never promoted. Instead, it provides read-only accesses to the data until the primary is fully restored.

This active-passive configuration improves system availability. However, it requires a spare set of compute resources that don’t actively take any customer traffic in most cases. An active-active configuration will be more efficient because both server instances can serve customer traffic. Unfortunately, active-active redundancy is often hard to achieve, because these legacy applications often assume they are the sole writers of the data. When multiple active instances try to operate on the same data, various of conflicts will occur and the results are often catastrophic.

A KPI of disaster recovery is the Recovery Time Objective (RTO), which refers to the duration for an application to be fully functional after a restore/failover request. In an ideal active-passive configuration, the RTO is minimum because the DR process is a simple address flip. Here’s the idea - if we could launch a new set of servers in a very short time, we can still meet our RTO without having to keep a spare set of servers around. This is where containers can help. One of the key characteristics of container is agility. A new container can be launched very quickly comparing to the time needed to boot up a full server. When a server fails, we simply launch a new one. And because the launching time is almost negligible, we can achieve high availability without a redundant, passive server.

Of course, data still needs to be replicated. And there are container data management solutions like Flocker. In this demo, however, I used a simpler approach – I used Azure File storage as a shared storage across multiple server instances. Because there was only a single server instance (per partition – see the last section) running at any given time, I didn’t need to worry about conflicting writes from multiple writers. And because Azure File storage itself was replicated for availability, I could assume the state would remain available under Microsoft’s SLA.

Diagram 1 shows how the demo is configured: A containerized Minecraft server is deployed to a 5-node Service Fabric cluster. A shared Azure File volume is attached to each of the nodes, and is passed in using the –v switch when the Minecraft server is launched. Azure Load Balancer is configured with a load-balancing rule over port 25565 as well as a probe that queries the same port on each node.

Diagram 1: A single Minecraft server on a Service Fabric cluster

When the hosting node fails, two things will happen. First, Service Fabric will locate a healthy node and launch a new Minecraft server (container) instance. Second, Azure Load Balancer will detect the failed node (as well as the new node who’s started responding to probe) and route traffic accordingly.

Diagram 2: Minecraft server failover

Implementation Steps

This demo uses Azure File storage, Docker containers, Azure Service Fabric Linux support, Minecraft client, Linux shell commands as well as Azure Management Portal. To keep the article short, I’d assume you are familiar with most of the concepts.

1. Provision a Linux-based Service Fabric cluster

Provisioning an unsecured Service Fabric cluster is easy. You can simply use Azure Management Portal to create an unsecured cluster using the creation wizard. Creating a secured cluster takes a few more steps – you’ll need to set up a Key Vault and upload a cluster certificate. Please refer to this article if you need more details. Obviously, an unsecured cluster is not meant for production use – event for dev-test it shouldn’t be long-lived if it’s on the public cloud.

When you create the cluster, make sure to select the Linux OS:

And allow Service Fabric to manage runtime versions:

2. Provision an Azure File share

Creating an Azure File share is also easy. In Azure Management Portal, navigate to the Storage account you want to use, click on the Files tile on the overview blade, and then click on the + File share button to create a new file share. Once the file share is created, click on the share, and then click on the Connect button. The Connect blade displays the command to mount the share onto a Linux machine (or a Windows machine):

Now, you need to mount the share onto each of the Service Fabric cluster nodes. I’m sure this part can be automated. But here I’m going to show you the manual steps. For each of the nodes:

SSH into the node. By default, there should be a inbound NAT rule defined that allows you to SSH into individual Service Fabric node, with port 3389 mapped to the first node, 3390 mapped to the second node and so on.
On the node, issue the following command:

sudo apt-get install cifs-utils

sudo mkdir /mnt/minecraftworld

sudo mount -t cifs //[your storage account name].file.core.windows.net/[your Azure File share name] /mnt/minecraftworld -o vers=3.0,username=…

The first command is to make sure you have required software package installed. It’s probably unnecessary but doesn’t hurt to check. The second command creates a mounting point and the last command mounts the Azure File share (copy the exact command from the Connect blade above).
To automatically mount the share when the machine restarts, edit the /etc/fstab file and insert the following line at the end of the file:

//[your storage account name].file.core.windows.net/[your Azure File share name] /mnt/minecraftworld cifs vers=3.0,username=…

3. Creating the Minecraft application

The easiest way to create the demo application is to use Yeoman as instructed here. When entering Image Name, enter itzg/minecraft-server, which is a Minecraft serve images on Docker Hub.
Once the application is created, modify the generate service manifest to include a few environment variables. The EULA variable is to auto-accept EULA. And the MODE variable is to switch the game to creative mode (so that you don’t need to worry about surviving).
<CodePackage Name="Code" Version="1.0.0">
    <EntryPoint>
        <ContainerHost>
            <ImageName>itzg/minecraft-server</ImageName>
            <Commands></Commands>
        </ContainerHost>
    </EntryPoint>
    <EnvironmentVariables>
        <EnvironmentVariable Name="EULA" Value="TRUE" />
        <EnvironmentVariable Name="MODE" Value="creative" />
    </EnvironmentVariables>
</CodePackage>
<Resources>
    <Endpoints>
        <Endpoint Name="MinecraftEndpoint" Port="25565" Protocol="tcp" />
    </Endpoints>
</Resources>
Then, modify the application manifest to map the /mnt/minecraftword folder to /data volume in container:

<ServiceManifestImport>
     <ServiceManifestRef ServiceManifestName="MinecraftServicePkg" ServiceManifestVersion="1.0.0" />
     <Policies>
         <ContainerHostPolicies CodePackageRef="Code">
               <PortBinding ContainerPort="25565" EndpointRef="MinecraftEndpoint" />
               <Volume Source="/mnt/minecraftworld" Destination="/data" />
         </ContainerHostPolicies>
     </Policies>
</ServiceManifestImport>
Now, you can use the install.sh script to deploy the application (after you use azure CLI command: azure servicefabric cluster connect –connection-endpoint [your cluster URL] to connect to your cluster).

4. Demo

Before demo, it’s highly recommended to SSH into each node and use sudo docker pull itzg/minecraft-server to cache the Docker image on the node’s local disk. This will make failovers much faster. Also before demo, connect to the Minecraft server and create a structure in the world so that you can show how state is persisted during failovers. For example, this is what I created for GDC:

Now, the demo steps:

Launch Minecraft client. On title screen, click on the Multiplayer button.
On the multiplayer screen, click on the Direct Connect button.
In the Server Address text box, enter your Minecraft server URL, which should be [your service fabric cluster name]. For example, my environment was sf-linuxdemo.southcentralus.cloudapp.azure.com. By default, port 25565 is used.
As the game is playing, open Service Fabric explorer, identify the node where the container is running, and restart the node. This simulates a node failure.
Observe the container moved to a new node as the game is still playing. Eventually, the connection will break because the client isn’t retrying for broken connections (it’s not expecting the server to be HA!). However, you can reconnect and the game should continue with all your states saved.

4. Scaling

Running only one instance on a 5-node cluster seems wasteful. To scale out to multiple instances, do the following:

Partition your storage. You can either attach multiple Azure File volumes to each node, or create sub folders for each of your Minecraft server instances.
Modify your Azure Load Balancer settings to have addition load balancing rules and probes on port 25566, 25567, 25568 and so on (or use a port range).
Create multiple copies of your Service Fabric application package. Each copy is configured with different port, application version and attached volume (or folder).
Now you can deploy multiple application versions, each configured for a separate world file location, to the same cluster.

5. Closing thoughts

This demo shows the idea of a “Tenant Manager” pattern, which treats a legacy server as a deployable unit and deploys customer-specific instances (tenants) to a shared infrastructure. Without modifying the existing code, the pattern provides basics QoS characteristics such as HA and scaling. The demo doesn’t provide a Tenant Manager implementation, but I imagine writing such a manager isn’t hard. At last, using Azure File as a shared volume worked well enough in this case because Minecraft server does occasional data syncs from memory to disk. The solution won’t work well if your application relies on high performance disk reads and writes.

That’s all there is to setup the interesting demo. Thank you for reading.

A World without Applications

2017-01-24T21:08:00.001-08:00

At the end of my previous article I mentioned the idea of application-less world. Indeed, it sounds like a very strange idea. To avoid the risk of being considered insane, I’m writing this article to further explain the idea. I hope the rational behind the idea would render me a logical person. To do this, I’m going to present my thinking step by step, with some assertions that I believe are safe to make, moving towards some statements that are still subject to validations. Regardless, I hope this article can entertain your mind somehow.

So, here it goes:

Problems with Applications

Whenever we use a computer – PC, phone, tablet, ATM, and what have you – we always interact with some sort of applications. This has become so natural to us that we rarely think about it – or should we? If you put some thinking into the situation, I believe it’s not hard for you to realize that what we need is the functionalities behind these applications, not the applications themselves. In other words, application is an delivery mechanism, and the way we are engaging with applications nowadays presents several problems.

Problem #1: Before we want to do anything via an application, we have to find the application that can do what we will expect it to do. Unfortunately, there are no guaranteed ways for us to do that. Let’s conduct a simple experiment: Let’s say you want to remove an unexpected stranger from one of your family vacation photos. What do you do? That’s easy! Just do a search online or in an application store, you’ll likely to find a number of options. Which one is better? How about the ones with highest ratings? Hmm… it’s not FREE. So you narrow the scope down to free applications only and find some other ones. Now, which one to choose? You need to take a leap of faith. You have no idea if the application will do exactly what you want. And if it doesn’t? That’s your bad – you made the choice. Can you force the application do what you want to do? Well, the best you can do is to file a complaint and hope for an upgrade. Or, you have to repeat the process and pick a different application. I don’t know about you, but I feel that’s quite annoying.

Problem #2: To get an application, you have to pay. And I’m talking just about money. Even if the application is free, you have to spend energy and time to download, install, and possibly configure the application. And then, you have to learn how to use it. If you think about it, this sucks. It’s like to receive a package, you have to hire a mailman, whose whole job is to deliver this single package. And what’s worse is that after delivering the package, he stays around! Can’t an application automatically come to us when we need it, do the thing and then disappear? Well, hold that thought and allow me to rant on. On the other hand, for application makers, the downloads, the installations, and the learning curves are all obstacles to adoption. How do we eliminate all those? I know someone will say “services” - I’ll come back to that later.

Problem #3: To make applications competitive, application makers keep building up new functionalities into the applications. To use another analogy – this is like when all you want is a simple bottle opener, but all you can find are Swiss knives. This is bad to application users because they are paying much more (money or resource) than what they actually need. This is also bad to application developers because they have to maintain applications with ever-increasing complexity.

Problem #4: What if you want do something complex that can’t be carried out by any existing applications? You’ll have to use multiple applications and somehow figure out a way to make everything work together. You may have to repeatedly enter same data, you may have to convert data formats between application (by using another application?), and you have to figure out a workflow to use the applications in the correct order… Can’t we make this easier?

All above problems should be quite obvious, which makes me wonder why such fundamental concept is so flawed. Well, I’m not going into that discussion because I’m not a historian or philosopher. Instead, allow me to continue with the concept of “services”.

Services are believed to solve many of the above problems – I believe some of you still remember the “thin-client” and “browser-server architecture” hypes. However, if you look closer, services don’t solve problem 1, 3, or 4. The only problem they can help to resolve is problem 2 – but is that so? True, you don’t have to download or install services, but there is another barrier – subscription. With the exception of a few world-class free services such as Bing and Google, you are almost always required to register, often with fees or forced disclosure of personal information, before you can consume a service. How many online accounts do you have? Let me count mine – XBOX Live, Twitter, Facebook, Google, LinkedIn, GitHub, Expedia, IEEE, Unity, Minecraft, utility, phone bill, bank… the list goes on and on. How many times did you have to sign in to different services? How many times did you lose your passwords? How many times did your relatives forget their passwords and asked for your help?

Problems with Isolated Ecosystems

When you buy a smart phone, you are not just buying a phone, you are joining a tribe. Each tribe gives you an application ecosystem within which you can purchase applications. There are quite large application ecosystems out there. Chances are, you will find what you need all the time – there are even applications dedicated to teaching you how to tie shoelaces. However, such ecosystems are rare – there are only a handful in the entire world. What if - I said “IF” - Apple closes its door someday? If you were relying on your phone everyday, basically you need to learn a new way of living. I switched from Windows Phone to Android a while ago (not because I didn’t like Windows Phone, but to get the VR goggle perk at the moment). I’m still adjusting myself and keep missing the wonderful email and calendar functions I got from Windows Phone. I, as a consumer, should not be bound to a specific ecosystem.

Within in these ecosystems are millions of applications. Or, to put it more precisely, millions of SILOED applications. They all work for you, but they don’t work together – please revisit problem #4 if you were not sure what I mean. All these ecosystems show a long-tail distribution in application usage and profitability. There are many applications that are terrific at certain tasks, but they are rarely used (or even discovered) because they are too specific. What get used are a bunch of generalists while true specialists remain in hibernation. So, as a user, when you have a unique request, the chances of that getting fulfilled is near to none. Why? Because NO applications understand what you want to do. They only know what they CAN do. The sad thing is, though you have access to millions of applications, you have nobody to explain what you really need.

Last but not least, let’s don’t forget accessing to such ecosystems is a luxury privilege that not everybody has. Not everyone has smart phones. Not everyone has computers.

A World without Applications

In a world without application, when I need something, I simply talk to a guy I trust – let’s call this guy “Scotty”. I tell Scotty what I want and he will see it happen. Scotty is intelligent. I can explain in great details exactly what I want. I don’t need to learn how to work with Scotty – I simply talk to him in my own language, state what I want, and move on with my life. Once Scotty takes care the business, he calls back and tells me “All is good, boss!”

Scotty is well connected. If he finds something he can’t do, he will find some specialists to help him out. In some cases, he even organize a little bidding process to find the most efficient specialist to carry out a task. And because Scotty is so well-connected, he often makes deals and gets discounts because he brings business to them. For some difficult tasks, I’ll give Scotty an award, and he will settle with the specialists he has involved.

Scotty and the specialists form a new type of ecosystem. The main difference between this new ecosystem and the isolated application ecosystems is that this new ecosystem is organic. The specialists in this ecosystem are small and specific. They are also intelligent: They can discover each other, can negotiate deals, can collaborate. This ecosystem is dynamic, but you don’t need to navigate through it at all – you have Scotty. Just ask Scotty to do it for you.

As the technology evolves, I believe we’ve got all necessary ingredients to make this a reality. Go to wake Scotty up, he’s been waiting.

Understanding Microservices: the right way

2017-01-23T17:26:00.001-08:00

What is Microservices?

Microservices is often explained as an architecture style where an application is decomposed into independent services. The idea sounds intuitive, yet it often leads to confusion. How is Microservices different from SOA? How is it different from J2EE or DCOM? Or, even, how is it different from OOP? Just last week I saw an article saying “do you have a class, make it a Microservices!” That’s … Well, I don’t even know how to comment on it. However, I’m SURE the author who wrote that is not doing so himself, if he’s sane.

I believe most of the confusion comes from the fact that people are trying to understand Microservices as an architecture style. However, when examined from the pure architectural perspective, Microservices doesn’t offer much (or even anything) new. For example, both separation of concerns and loose coupling have been proven practices for decades. Then, why do we need this new “Microservices” term? To fully understand Microservices, we have to take a different perspective:

The core value proposition of Microservices resides in how you operate your application, not how you design your application.

Once you view Microservices from the right perspective, things will become perfectly clear.

Why do people talk about Microservices NOW?

Decomposing applications into components is not a new idea. What makes Microservices significant is the context where it lives in – the cloud. Cloud is a radically different environment from your local datacenters. To achieve higher Quality of Services (QoS), a set of different approaches need to be adopted. In turn, these approaches demand your applications to have certain characteristics. And eventually, to deliver these characteristics, you need to design your applications in certain ways. So, Microservices architecture is rooted from the needs of operating applications on cloud. Only when you fully understand how applications are operated on cloud can you fully understand Microservices.

Availability

System availability can be calculated by the formula: Availability = MTBF/MTBF+MTTR, where MTBF means “mean time between failure”, and MTTR means “mean time to restore”. Intuitively, if MTBF is big enough, which means the sever rarely fails, availability goes up. On the other hand, if MTTR is small enough, it’s impact on availability becomes less significant. To improve system availability, local datacenters and cloud use two different strategies: local datacenters focus on prolonging MTBF, while cloud focuses on reducing MTTR. Traditional datacenters have fewer machines, with each machine assigned to a particular role. When a server fails, finding a replacement could be hard. In other words, MTTR in local datacenters is usually quite long. This is why local datacenters try to prolong MTBF as much as possible so that the effect of long MTTR can be reduced. Cloud is a totally different story. Cloud has many commodity servers that fail more often. However, when a server fails, it’s fairly easy for a cloud platform to find another healthy server. In other words, although MTBF on cloud is shorter, MTTR is so low that it can be neglected – at least this is the case in theory.

Finding another server is just a small portion of MTTR. The time to migrate an application (as well as its data) to a new server is heavily affected by how the application is designed and implemented. Intuitively, the smaller the application, the easier it is to migrate it. However, many applications are big and complex by nature. How to deal with these applications? There are no better ways but to split them into smaller pieces. In this way, when a portion of the application fails, we need to migrate only the failed parts. This operation strategy on cloud decides that a cloud application should be decomposed into smaller parts.

Scalability

Local datacenters scale up applications by placing applications on more powerful machines. This is again because of the difficulties in acquiring new servers. In local datacenters, adding compute resources (memory/disk/CPU) to an existing server is much easier and quicker (when possible) than buying and installing new servers. On the other hand, cloud scales out applications by splitting workload to multiple application instances – adding compute resources to a server for a specific customer is obviously too much of a management burden for a cloud vendor.

However, not all applications are easily scalable. Especially, many applications assume they are holding the global truth (or global state) of the entire system. When multiple instances of such applications work together, the global truth is split, causing all kinds of conflicts and confusions. There are two ways to deal with this – to eliminate the global state, or to concentrate the global state to one or a few components so it’s more manageable. Both approaches call for isolation. The parts who hold these states are the stateful part of your application. And the rest of the application becomes stateless, which means they operate without relying on any local states. Scaling the stateless part is easy – just throw multiple instances behind a load balancer and you are done. Scaling the stateful part is harder. Usually you need to apply some partition scheme for scale, and some replication strategy for high availability. The different nature of application parts decides that application parts should be able to operate independently.

Microservices is all about mobilizing workloads

So, to efficiently operate your applications on cloud, you need to split your applications into smaller parts; these parts should be isolated; and they should be able to operate independently. So, the notion of Microservices is really driven by how cloud operates applications, not how you design your application. The rise of containers provides a solid testament to this fact. Containers don’t demand you to change your application architecture. Instead, they help you to mobilize your applications so that the applications can be better hosted on cloud. So, at the end, Microservices is all about mobilizing your workloads. The mobilized workloads should be light-weight, self-sufficient and isolated so that they can be moved around without friction. And only when your workloads are fully mobilized can your applications take the full advantage of cloud.

Additional thoughts

Imagine how cloud would look like in the future – there will be no concept of machines or clusters. The whole datacenter, or even the entire cloud, is just a humongous pool of resources where your mobilized services can roam freely. And if I dare to dream further – what if these services can intelligently discover and collaborate with each other? Then, the concept of applications fades away as well. The cloud itself becomes an organic, intelligent entity that offers infinite functionalities to all users. Wouldn’t it be wonderful?

Tutorial: Creating a Kubernetes cluster on Microsoft Azure Container Service (from Windows client)

2016-11-24T17:54:00.001-08:00

This tutorial captures all the steps needed to provision and manage a new Kubernetes cluster on Microsoft Azure Container Service. It collects all steps in a single document so that you don’t need to jump through several links to get everything ready. To start, all you need is an Azure subscription.

Install Azure CLI 2.0

Azure CLI 2.0 (in preview when this article is written) is the next generation of Azure cross-platform command line experience. It’s built using Python. To keep my above promise true, I’m going to cover the steps of installing Python, Pip, and then Azure CLI on Windows. If you are using Linux distributions, Python and Pip are likely to be installed already.

Go to python.org and download Python 2.7.12.
Launch the downloaded msi and install Python. Accept all default settings except that on the Customize Python screen, you should enable the Add python.exe to Path option.
Once Python (and Pip) is installed, launch a new Command Prompt window and use command:

pip install –-user azure-cli

to install Azure CLI.
Edit your environment variable and add %APPDATA%\Python\Scripts to your PATH variable. Some documents say you should add the %APPDATA%\Python\PythonXY\Scripts folder instead (where XY is the Python version number, such as “27”). However this doesn’t seem to be correct with the current release.
Now, launch a new Command Prompt window, and you should be able to use “az” command from any folder.

Create an Azure AD Service Principal

In order to talk to Azure APIs to provision Azure resources, Kubernetes uses an Azure AD Service Principal – you can think of Service Principal as an account for a service/application instead for a human user. The following steps show you how to create a Service Principal using Azure CLI.

In a Command Prompt window, use:

az login

to login to your Azure subscription. The command prompts you to open a browser, navigate to the designated address, and paste in the one-time code. Once you paste in the code, click on the Continue button on the page to continue with the login process. Once the log-in process completes, you can continue with your az commands in the command window.
Use command

az account set –-subscription=<your subscription id or name>

to select the Azure subscription you want to use.
Use command

az ad sp create-for-rbac –-role=”Contributor” –-scopes=”/subscriptions/<your subscription id>”

to create a new Service Principal. If needed, you can use az account show to get your subscription id. The above command generates a JSON output like this:
{
"appId": "0f622c84-…",
"name": "http://azure-cli-…",
"password": "9290d942-…",
"tenant": "72f988bf-…"
}
save the results for later use.

Create SSH Keys (on Windows)

To create a Kubernetes cluster, you need a key pair. This has been covered at many places, but a promise is a promise. Since I’ve promised to cover all steps, here it goes:

Install Git Bash – go to https://git-scm.com/downloads, click on the “Downloads for Windows” button and install the bash shell. This is an easy way to get openssl, which we’ll need to use to generate key pairs.
Launch Git Bash, and use the following command to generate a new key:

openssl req –x509 –nodes –days 365 –newkey rsa:2048 –keyout myPrivateKey.key –out myCert.pem

The above command will ask you a series of questions such as country name, organization etc. Fill in the info and continue to create the key.
Convert the key to rsa format and constraint access to the private key file:

openssl rsa –in ./myPrivateKey.key –out myPrivateKey_rsa
chmod 0600 myPrivateKey_rsa
Download and launch PuttyGen: http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html (no install is necessary).
In PuttyGen, select the File->Load a Private Key menu. Select the myPrivateKey_rsa file you just created. When prompted, click on the OK button.
Copy down the text in the Key field at the top of the window – this is the SSH public key you’ll paste into Azure Portal later.
Click on the Save private key button and save the private key as a .PPK file. This file will be provided to Putty if you were going to use Putty as the SSH client.

Provision a Kubernetes Cluster

Login to Azure portal. Click on the Plus icon at the upper-left corner of screen. Then on the New blade, search for “Azure Container Service”.
In search results, click on the Azure Container Service entry to launch the provision wizard. On the wizard screen, click on the Create button to continue.
In the Basics section, enter a user name, paste in the public key you got from step 6 above, pick subscription, resource group and location, and then click on the OK button to continue.
In the Framework configuration section, make sure Kubernetes is selected:
One you make the selection, you’ll be prompted to enter Service Principal Client ID and Service Principal Client Secret. For Service Principal Client ID, paste in the “name” field from the Service Principal output JSON file; for Principal Client Secret, paste in the value of the “password” field.
In the Azure Container services settings section, select the number and size of your agent nodes, and provide a DNS prefix.
Follow the wizard to finish the provisioning process.

Install and configure kubectl

Supposedly, you can use Azure CLI to install and configure kubectl on your local Windows machine. However, due to a bug (https://github.com/Azure/azure-cli/issues/1350) this isn’t working yet. I’ll update the article once this bug is fixed.

UPDATE 3/8/2017: This bug is now marked as fixed. I haven’t verified it myself, though.

You can also attempt to install and configure kubectl manually, however that’s out of the scope of this article.

SSH into a master node to use kubectl

Instead of using a local client, you can also SSH into a master node on the cluster and use kubectl there. The master nodes are put behind an Azure Load Balancer, which has an associated public IP and a DNS name.

Get the master FQDN from the overview page of your cluster:
Copy your private SSH key to your %HOMEPATH%\.ssh folder:

copy <path to the myPrivateKey_rsa> %HOMEPATH%\.ssh\id_rsa
Use a SSH client such as Git Bash to connect to the cluster:

ssh <your user name>@<Master FQDN above>

When prompted to add the address to trusted host list, type in yes or y and press [Enter].
Now you can use kubectl to manage your cluster:

(This article was written on a Thanksgiving afternoon as I waited for my wife and daughter to join me for dinner, so it was a bit rushed. I apologizes for possible errors)

Tutorial: Adding UI to a Service Fabric Web API service

2016-11-14T18:39:00.001-08:00

This tutorial shows you the steps to add a UI layer on top of a Service Fabric Web API service. The goal of this article is to bring in a HTML + JavaScript UI layer on top of the Web API service with minimum changes to the existing project. This method works the best when you want to provide a simple configuration/monitor UI for your Web API. If you want to build a full ASP.NET MVC application, you should consider the ASP.NET Core (Preview) service type.

Bringing in static HTML pages

As a starting point, let’s bring in some static HTML pages to the Web API service.

Create a new Service Fabric application with a Stateless Web API service.
Under the service project, create a new wwwroot folder and a simple index.html page under it.
Change the property of index.html to set its Copy to Output Directory property to Copy Always (with Build Action as Content).
Add a reference to the Microsoft.Owin.FileSystems NuGet package and the Microsoft.Owin.StaticFiles NuGet package.
Modify the startup.cs file to add routings for static files:

var fileSystem = new PhysicalFileSystem(@".\wwwroot");
var options = new FileServerOptions
{
    EnableDefaultFiles = true,
    FileSystem = fileSystem,
    RequestPath = PathString.Empty
};
options.DefaultFilesOptions.DefaultFileNames = new[] { "index.html" };
options.StaticFileOptions.FileSystem = fileSystem;
options.StaticFileOptions.ServeUnknownFileTypes = true;
options.EnableDirectoryBrowsing = true;

config.MapHttpAttributeRoutes();
appBuilder.UseFileServer(options);

Build and deploy the application. You should be able to access the above index.html page by navigating to the root folder (such as http://localhost:<port>/)

Adding jQuery, Angular, and Bootstrap etc.

Now, you can continue to bring in JavaScript libraries such as jQuery and Angular to build up your UI.

Modify the index.html file:

<!DOCTYPE html>

Add an app.js file to the wwwroot folder:

var testApp = angular.module("testApp", ['ngRoute']);

testApp.config(['$routeProvider', function ($routeProvider) {
    $routeProvider.
    when('/ngtest', {
        templateUrl: '/views/testPage1.html', controller: 'TestController'
    });
}]);

testApp.controller('TestController', function ($scope) {
$scope.message = "This is a message from the test controller";
});

Add a new Views folder to the wwwroot folder. Create a testPage1.html page under the Views folder:
<h1>This is test page with message {{message}}</h1>
Deploy the app again. You should be able to access the Angular route by navigating to http://localhost:<port>/#/ngtest.

Tutorial: Writing a Windows native client for Dynamics 365

2016-11-09T18:45:00.001-08:00

Recently, I needed to write a Windows client demo application that connects to Dynamics 365 via its Web API. As usual, I documented the process as I went along. Overall the experience was fair. However there were a few places that required some researches. I hope this article can provide help to whoever needs to take on a similar task in the future. Disclaimer: this document was written based on pre-release system, so details are subject to change.

Navigate to your Azure AD Tenant

Before you can invoke Dynamics 365 Web APIs, you need to authenticate. Dynamics 365 uses Azure AD for authentication. When you provision a new trial Dynamics 365 organization (or tenant), a corresponding Azure AD tenant is created ( I believe in a production deployment you can reuse an existing Azure AD tenant, but I haven’t tried that myself). In order to allow your client application to authenticate with the Azure AD tenant, you’ll need to register your application with the AD tenant. And to do that, you’ll need an Azure subscription. The following steps show you how to navigate to the administrative page of your Azure AD tenant from your Dynamics 365 portal.

On your Dynamics 365 portal, click on the upper-left corner and then click on the Admin tile, which opens the Admin center page. The address to your Dynamics 365 organization, btw, is http://<your Dynamics 365 organization name>.crm.dynamics.com. Make sure you are using the correct URL, and double-check if you’ve logged in to the desired tenant (by looking at upper-right corner of the page).
In the left pane, click on the Admin centers –> Azure AD link. This link takes you to the Azure AD tenant corresponding to your Dynamics 365 organization. However, if you don’t already have an Azure subscription, you’ll be prompted to create one. In this case, you can follow the wizard to create a free Azure subscription, and try the link again.
Once you navigate to the Azure AD page, Your Azure AD tenant should have some applications already registered under the APPLICATIONS tab, among which is the “Dynamics CRM Online” application – this is the application we want to access.

Register your client application with the Azure AD Tenant

This part is pretty much standard for Azure AD – you need to register your client application as a trusted application in the tenant.

Click on the APPLICATIONS tab on your Azure AD tenant page. And then, click on the ADD icon at the bottom command bar.
On the dialog, select Add an application my organization is developing.
Enter a NAME for your application, select the NATIVE CLIENT APPLICATION option, and then click on the next arrow.
On the REDIRECT URI field, enter a well-formed URI, for example http://your-app-name. The URI doesn’t need to be accessible in this case.
Click on the check icon to complete registering the application.
Once the application is registered, you can see the application’s CLIENT ID as well as REDIRECT URI from its overview page. You’ll need these information in your code.
Switch to the application’s CONFIGURE tab.
Click on the Add application button in the permissions to other applications section.
Select the Dynamics CRM Online application to grant access to Dynamics 365.
Back on the application page, drop down the Delegated Permission box and check the Access CRM Online as organization users checkbox:
Click on the SAVE icon on the bottom command bar to save the changes.

Modify your client application

Create a new Console application
Add a reference to NuGet package: Microsoft.IdentityModel.Clients.ActiveDirectory.
Add the following code. Please note that I use a FileCache class from this sample repository to cache the token so that I don’t need to login every time. The following code authenticates to your Dynamics 365 organization and retrieve all accounts.

class Program
{
private static string tenant = "<your Azure AD tenant>.onmicrosoft.com";
private static string clientId = "<your client app client id>"; //see step 9 above
private static string aadInstance = "https://login.microsoftonline.com/{0}";
private static Uri redirectURI = new Uri("<your client redirect url>"); //see step 9 above
private static string dynamicCRMTenant = "https://<your Dynamics 354 org name>.crm.dynamics.com";
private static string authority = String.Format(CultureInfo.InstalledUICulture, aadInstance, tenant);
static void Main(string[] args)
{
    string token = loginToCRM().Result;
    retrieveAccounts(token).Wait();
    Console.ReadLine();
}
static async Task<string> loginToCRM()
{
    var authContext = new AuthenticationContext(authority, new FileCache());
    var result = await authContext.AcquireTokenSilentAsync(dynamicCRMTenant, clientId);
    if (string.IsNullOrEmpty(result.AccessToken) || result.ExpiresOn.DateTime < DateTime.UtcNow)
    {
      var token = await authContext.AcquireTokenAsync(dynamicCRMTenant, clientId, redirectURI, new PlatformParameters(PromptBehavior.Always));
      return token.AccessToken;
    }
    else
      return result.AccessToken;
    }
    static async Task retrieveAccounts(string token)
    {
      HttpClient httpClient = new HttpClient();
      httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);
      httpClient.DefaultRequestHeaders.Add("OData-MaxVersion", "4.0");
      httpClient.DefaultRequestHeaders.Add("OData-Version", "4.0");
      httpClient.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
      HttpResponseMessage response = await httpClient.GetAsync(dynamicCRMTenant + "/api/data/v8.1/accounts");
      string s = await response.Content.ReadAsStringAsync();
      Console.WriteLine(s);
    }

Btw, you can look up exposed core entity types here: https://msdn.microsoft.com/en-us/library/mt608066.aspx. And for all entity types, you can query /api/data/v8.1/.

Hope this helps!

SFNuGet 0.3.1 release: multi-service packages and application parameters

2016-08-27T17:01:00.001-07:00

I’m glad to announce that SFNuGet 0.3.1 is now available. This version added two major features: application parameter support and multi-service package support.

Application Parameters

When you add a new service to a Service Fabric application in Visual Studio, some service attributes such as instance count and partition count are externalized as application manifest parameters. This design allows you to load different parameters when you deploy your application package to different environments. In earlier versions of SFNuGet, these attributes are hard-coded. In version 0.3.1, this attributes are externalized just like in the Visual Studio experience. For example, when you add a SFNuGet reference to a stateful service named “MyStateful”, the following parameters are automatically added to your application manifest:

Multi-service Packages

Under the Microservices architecture, each of the services should be independent. However, there are cases that some services depend on some other services in order to function correctly. Now, SFNuGet allows you to add a reference to another SFNuGet-enabled service so that you can package your service with all necessary dependency services.

In the following walkthrough, I’ll create a new stateful service that depends on the HelloWorldSFNuGet service package. Then, I’ll use SFNuGet to package the new service as a new NuGet package.

Create a new Service Fabric application with a stateful service named MyStateful.
In the MyStateful service project, add a reference to the SFNuGet package and then the HelloWorldSFNuGet (2.0.0) package.
Build the MyStateful project.
Publish the generated MyStateful.1.0.0.nupkg to a NuGet storage of your choice. In Visual Studio, you can define a NuGet source based on a folder or a shared folder by using the Tools –> NuGet Package Manager –> Package Manager Settings menu.
Create a new Service Fabric application with a stateless service named Stateless1.
In the Service Fabric application project, add a reference to the MyStateful NuGet package. Because VS tooling experience has been updated, please see my earlier post on how to do this correctly.
In the Preview dialog, you’ll see the MyStateful package will pull down its dependencies when you install it. Click on the OK button to install both services.
Once the package is installed, you can observe both service packages are included, and your application manifest is updated accordingly.
Publish the application. The application should publish and function without errors:

Conclusion

This release is a major milestone. I don’t anticipate many more features before the 1.0 release. For the next few weeks, the main focus will be testing, bug fixing and filling up the omitted details (such as supporting configuration overrides, auto-populating existing parameter files etc.). Thank you for your interests in SFNuGet and I look forward to seeing your reusable Service Fabric published, discovered, and reused!

Tutorial: Running Windows Server containers on Azure Virtual Machines

2016-08-25T19:23:00.001-07:00

This tutorial covers the steps of running a Windows Server container on an Azure virtual machine. There are quite a few tutorials online but I haven’t seen one that covers Azure virtual machines – and it turns out you might need to do some changes to make the networking work.

Disclaimer: this article is based on a specific preview version of Windows (Windows Server 2016 Technical Preview 5) running as an Azure virtual machine. The steps below don’t apply to earlier/later versions, and the experience may change in the future.

Getting Docker on the machine

The first part of this blog is based on this MSDN article. There’s also a “Windows Server 2016 with Containers Tech Preview 5” image on Azure Marketplace. If you chose to use this image, you can skip all the configuration steps in this part.

Provision a new virtual machine (Windows Server 2016 Technical Preview 5) using the Azure portal.
Connect to the server via RDP.
Launch PowerShell, and use the following commands to install the container feature:
Install-WindowsFeature containers
Restart-Computer –Force
Once the computer reboots, connect to it via RDP again.
Launch PowerShell, and use the following commands to download and install Docker engine and Docker client:
Invoke-WebRequest "https://get.docker.com/builds/Windows/x86_64/docker-1.12.1.zip" -OutFile "$env:TEMP\docker-1.12.1.zip" -UseBasicParsing
Expand-Archive -Path "$env:TEMP\docker-1.12.1.zip" -DestinationPath $env:ProgramFiles
[Environment]::SetEnvironmentVariable("Path", $env:Path+";C:\Program Files\Docker", [EnvironmentVariableTarget]::Machine)
Restart the PowerShell session to ensure modified path is recognized.
Use the following commands to register Docker service and then download the Windows Server Core image:
dockerd --register-service
start-service Docker
docker pull microsoft/windowsservercore

Fix (possible) networking problem

Now comes the interesting part. Inspect the default nat network using command line:

docker network inspect nat

Observe the output. If the subnet is configured as 172.*, your container networking is most likely broken. You can still create and run containers, but you won’t be able to connect to services running on these containers. This error is because Host Networking Service (HNS) is trying to create the default nat network with prefix 172.16.0./12, which overlaps with the IP address assigned to some VM tenants in Azure.

Fixing this problem takes a few steps. I’m not sure if the following steps are optimum. And I haven’t figured out a way to permanently change the dockerd configuration (there’s a c:\ProgramData\dockers\config folder but there’s only a key.json file with unknown purpose). Please send me your comments if you knew how to make these steps better!

Launch PowerShell
Use the following commands to stop Docker service and to clean up existing network artifacts:
stop-service Docker
Get-ContainerNetwork | Remove-ContainerNetwork
Get-NetNat | Remove-NetNat
Get-VMSwitch|Remove-VMSwitch
Now we’ll launch Docker daemon (dockerd) with a different CIDR that doesn’t overlap with 127.*. Please note the first part of the CIDR is 192.168.1.1 (instead of 192.168.1.0). From what I observe, containers will pick 192.168.1.1 as the default gateway. As the dockerd on Windows doesn’t have the --default-gateway switch, setting the address to 192.168.1.1 gives the host correct address (that matches the containers’ expectations).
cd “c:\Program Files\docker”
dockerd --fixed-cidr=”192.168.1.1/24”
Now inspect the nat network again:
docker network inspect nat
You should see the subnet is configured correctly this time:

After this, your new containers should be assigned with correct IP addresses and can ping the host/each other. If you still have connectivity problems, try to turn off the firewall on the host.

I hope this helps. And I believe the above problem will be fixed in future versions. Thank you for reading .

UPDATE:

To permanently change the CIRD settings, create a daemon.json file under %ProgramData%\docker\config folder (see the complete file schema here

{

"fixed-cidr": "192.168.1.1/24"

}

How is it made: Nginx as a pre-packaged Service Fabric service

2016-08-15T16:46:00.001-07:00

Last week, I published a prototype of a reusable Nginx service as a Service Fabric service using SFNuGet. This article provides you details on how to use this service as well as how this service is designed and implemented. I wish this article will give you some ideas on how to package existing services as a reusable Service Fabric service.

Usage

The following walkthrough shows you how to use the NginxPoc NuGet package (1.4.0), and how to conduct a couple of experiments with it. If you are only interested in how the service is designed and implemented, please skip to the next section.

Include NginxPoC in your application

Create a new Service Fabric application.
Right-click on the solution node and select the “Manage NuGet Package for Solution…” menu.
Search for “nginxpoc”. Once the package is found, select the package, and make sure your application project is checked in the list, and click on the Install button.
Modify your application manifest and change the instance count of the Nginx service to “1”.
Deploy you application.
You should observe your application is deployed correctly. Nginx is launched and you should be able to access Nginx by http://localhost:88/ if you are using a local Service Fabric cluster.

Rolling a configuration change

Now let’s change the Nginx configuration to use the default port 80.

Modify the nginx.conf file under the ApplicationPackageRoot\NginxPkg\Config\confg folder and change the http->server->listen port setting from 88 to 80.
Save the file. Right-click the application project and select the “Edit Manifest Version…” menu.
Update the version of Config package of NginxPkg to 2.0.0. Make sure “Automatically update application and service versions” checkbox is checked. Then, click the Save button.
Right-click the application project and select the “Package” menu to create a new package.
Use PowerShell to trigger a rolling update:

Copy-ServiceFabricApplicationPackage -ApplicationPackagePath [app package path] -ImageStoreConnectionString 'file:C:\SFDevCluster\Data\ImageStoreShare' -ApplicationPackagePathInImageStore [app name]\_V2
Register-ServiceFabricApplicationType -ApplicationPathInImageStore "[app name]\_V2"
Start-ServiceFabricApplicationUpgrade -ApplicationName fabric:/[app name] -ApplicationTypeVersion 2.0.0 -HealthCheckRetryTimeoutSec 60 -UpgradeReplicaSetCheckTimeoutSec 3000 -FailureAction Rollback -Monitored

Once the rolling update completes, Nginx is restarted at port 80.

Failing over

When a node fails, Service Fabric automatically migrates the workload on the node to another healthy node. To test this, perform the following test:

Use Service Fabric explorer, identify the node where the Nginx service instance is deployed.
Deactivate the node.
Observe the service instance is migrated to another node where Nginx is re-launched.

Recovery

If Nginx process crashes, the wrapper service automatically restarts it. To test this, use Task Manager to kill the two nginx-1.11.3.exe processes (one main process and one worker process) and observe the two processes are restored after a few seconds.

Service Design

Service Fabric supports hosting executables as guest executables. Naturally, the easiest approach would be packaging Nginx for Windows as a guest application. The challenge, however, is to put Nginx configurations into a Service Fabric configuration package. Because configuration packages are versioned, the path to a configuration package has the package’s version in it. We need to somehow find out which is the correct folder (there could be multiple versions uploaded) to use and then use the Nginx “-c” switch to load the correct configuration file. To solve this problem, my solution is to create a stateless wrapper service that wraps the Nginx executable. The wrapper service launches Nginx as it starts. It also registers to configuration change event and re-launch Nginx with the updated configuration. Last but not least, it also monitors the Nginx process and restarts the process if Nginx has crashed.

Service Implementation

To create the service package, I followed these steps:

Create a new Service Fabric Application with a stateless service named Nginx.
Download and unpack Nginx for Windows (1.11.3) to the PackageRoot\Code folder.
Add a new setupACL.cmd file under the same folder. The file contains the following line to allow nginx-1.11.3.exe to listen to incoming traffic:
netsh advfirewall firewall add rule name="Nginx (port 80)" dir=in action=allow program=.\nginx-1.11.3.exe enable=yes
Add a new ApplicationManifest.overrides.xml file under the PackageRoot folder. This is a partial application manifest that defines service-specific principals and policies. SFNuGet supports merging such application manifests into the final application manifest so that service authors can include these service-specific configurations (in addition to what are allowed in configuration overrides). Alternatively, you can modify setupACL.cmd to explicit grant Network Services required rights so that to avoid running the service as an administrator.

<?xml version="1.0" encoding="utf-8"?>
<ApplicationManifest xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" ApplicationTypeName="NginxPoCType" ApplicationTypeVersion="1.0.0" xmlns="http://schemas.microsoft.com/2011/01/fabric">
<ServiceManifestImport>
    <ServiceManifestRef ServiceManifestName="NginxPkg" ServiceManifestVersion="1.0.0" />
    <Policies>
      <RunAsPolicy CodePackageRef="Code" UserRef="Admin" EntryPointType="All" />
    </Policies>
</ServiceManifestImport>
<Principals>
    <Users>
      <User Name="Admin">
        <MemberOf>
          <SystemGroup Name="Administrators" />
        </MemberOf>
      </User>
    </Users>
</Principals>
</ApplicationManifest>

The service implementation contains several private members:

        private string nginxProcessName = "";
        private string getConfigPath()
        {
            var codePackage = this.Context.CodePackageActivationContext.CodePackageName;
            var configPackage = this.Context.CodePackageActivationContext.GetConfigurationPackageObject("Config");
            var codePath = this.Context.CodePackageActivationContext.GetCodePackageObject(codePackage).Path;
            return Path.Combine(configPackage.Path, "conf\\nginx.conf");
        }
        private bool isNginxRunning()
        {
            if (!string.IsNullOrEmpty(nginxProcessName))
            {
                var processes = Process.GetProcessesByName(nginxProcessName);
                return processes.Length != 0;
            }
            else
                return false;
        }
        private void launchNginxProcess(string arguments)
        {
            var codePackage = this.Context.CodePackageActivationContext.CodePackageName;
            var configPackage = this.Context.CodePackageActivationContext.GetConfigurationPackageObject("Config");
            var codePath = this.Context.CodePackageActivationContext.GetCodePackageObject(codePackage).Path;
            var res = File.Exists(Path.Combine(codePath, "nginx-1.11.3.exe"));
            var nginxStartInfo = new ProcessStartInfo(Path.Combine(codePath, "nginx-1.11.3.exe"));
            nginxStartInfo.WorkingDirectory = codePath;
            nginxStartInfo.UseShellExecute = false;
            nginxStartInfo.Arguments = arguments;
            var nginxProcess = new Process();
            nginxProcess.StartInfo = nginxStartInfo;
            nginxProcess.Start();
            nginxProcessName = nginxProcess.ProcessName;
        }

The RunAsync method registers to the configuration change event, launches Nginx, and re-launch it if it crashes:

       protected override async Task RunAsync(CancellationToken cancellationToken)
        {
            this.Context.CodePackageActivationContext.ConfigurationPackageModifiedEvent += CodePackageActivationContext_ConfigurationPackageModifiedEvent;

            launchNginxProcess("-c " + getConfigPath());

            while (true)
            {
                if (cancellationToken.IsCancellationRequested)
                    launchNginxProcess("-s quit");
                cancellationToken.ThrowIfCancellationRequested();
                await Task.Delay(TimeSpan.FromSeconds(5), cancellationToken);
                if (!isNginxRunning())
                    launchNginxProcess("-c " + getConfigPath());
            }
        }

And finally, the following code handles configuration changes:

       private void CodePackageActivationContext_ConfigurationPackageModifiedEvent(object sender, PackageModifiedEventArgs<ConfigurationPackage> e)
       {
           launchNginxProcess("-s quit");
           while (isNginxRunning())
               Task.Delay(TimeSpan.FromSeconds(1));
           launchNginxProcess("-c " + Path.Combine(e.NewPackage.Path, "conf\\nginx.conf"));
       }

Conclusion

This article shows you how to wrap an existing application as a reusable Service Fabric service. I’m looking forward to seeing your services published and reused!

Before concluding this article, a few words on Nginx dynamic configuration – there’s a commercial Nginx Plus that supports dynamic configuration updates via REST API. In a dynamic cloud production environment, Nginx Plus is probably better choice than the above configuration update method.

Sharing your Service Fabric services as NuGet packages

2016-08-10T17:38:00.001-07:00

Have you been hoping for easily incorporating existing services such as Nginx, Redis and MongoDB into your Microsoft Azure Service Fabric applications? Have you made a reusable Service Fabric service that you are eager to share with the community? If your answer to either question is “yes”, this blog is just for you! I’m very happy to announce availability of SFNuGet, a NuGet package that allows you to easily share, discover and reuse Service Fabric services as NuGet packages.

To author a Service Fabric NuGet package, simply add a reference to SFNuGet and rebuild your service project. SFNGet automatically adds a new build target to your project that generates a NuGet package when you build your project. Then, the package can be published to any NuGet repositories so that others can make use of it. Using a Service Fabric NuGet package is a breeze as well – just add a reference to the service NuGet package and everything will be configured for you. No additional actions are needed – your application is ready to be published with the referenced service (of course you can still configure the service in whichever way you prefer).

Usage Experience

To use a Service Fabric NuGet package, all you need to do is to reference to the package in your Service Fabric application. The following walkthrough shows you how to add a sample “Hello World” Service Fabric NuGet package to your application.

In Visual Studio 2015, create a new Service Fabric application, or open an existing Service Fabric application.
Add a reference to HelloWorldSFNuGet, which contains a simple stateless service that writes outputs to event tracer.
1. Right-click the solution and select the Manage NuGet Packages for Solution menu.
2. Search for the HelloWorldSFNuGet package.
3. Make sure your Service Fabric application project is checked, and click on the Install button to install the package.

And that’s it! You can deploy your application as it is now and the referenced service will be deployed along other services in your application.

Of course, if you prefer, you can use the Package Manager Console as well: Install-Package HelloWorldSFNuGet.

A couple of things happen when you add the reference: first, a “HelloWorldSFNuGetPkg” folder is added to the ApplicationPackageRoot folder. This new folder contains everything from the service package – code (binaries), configuration, data as well as the service manifest.

Second, your application manifest is updated to include the service reference. The service is also registered as a default service by default. But you can certainly remove it (or make any other configuration changes as you see fit) if you want.

Publish your application and you’ll see the reference service is published as expected:

If you don’t want the service anymore, simply uninstall the package and everything will be cleaned up for you.

Authoring Experience

To create a Service Fabric NuGet package, add a reference to the SFNuGet package and rebuild your service. That’s all you need to do – no code changes, no additional actions. Simply build and the package is automatically created. The following walkthrough shows you how to package a Web API service as a reusable NuGet package.

Create a new Service Fabric Application with a stateless service using the Stateless Web API project. Name the service MyWebAPI. If you want to publish an existing service, simply go to step 2.
Add a NuGet reference to SFNuGet in your service project.
Rebuild the project (or the entire solution).

Once the project is built, you’ll find a MyWebAPI.1.0.0.nupkg under the project folder. This is the package you can share with others so they can easily include your service into their applications.

Reusable Nginx service

As a test, I’ve created and published a NginxPoC NuGet package using SFNuGet. You can reuse the service by simply adding a NuGet reference as shown in the above walkthrough. Before you publish your application to a local cluster, you need to change the instance count to 1 from the default –1 to avoid port conflicts. A couple of things to notice:

In this package, the Nginx instance uses port 88 instead of the default 80.
The Nginx configuration is included in the service’s configuration package. This allows Nginx to be dynamically configured by uploading a new configuration package. However, as I haven’t got a chance to test this part myself so there could be problems.

If you are using a local cluster, you should be able to access Nginx page by http://localhost:88/ after the application is deployed:

Why I did this?

In the world of Microservices, one of the greatest things is Docker Hub, where you can find thousands of reusable images that you can easily incorporate into your own applications. Service Fabric is still fairly new, so there isn’t such a vibrant community yet - I hope SFNuGet is a start. With SFNuGet, developers like you can easily create and share great services with the entire community. If you come from the Docker world, you can think Service Fabric NuGet packages as Docker images, while Service Fabric application manifests as Docker compose files. And if I dare to dream, the parallel concepts create opportunities for bridging the two in the future.

NuGet is familiar to Visual Studio developers, so I believe using NuGet creates the most natural experiences to both service authors and service consumers. Moreover, NuGet provides a lot of desirable capabilities (that we find in Docker Hub and Trusted Registry) including versioning and public and private repos. So, NuGet is an apparent choice that allows me to build out the system without requiring any Visual Studio tooling or Service Fabric changes. Can the experience be even better? Definitely. This is where I need your help to try SFNuGet out and send me your feedbacks, which I’ll forward to our engineering teams at Microsoft.

By default, all SFNuGet generated packages are tagged with a “SFNuGet” tag. This allows basic discoverability of reusable Service Fabric services in an existing NuGet community. Will there be a dedicated site as Docker Hub? I hope you – let me know if you want to build one :).

Some known issues/limitations and future thoughts:

When updating application manifests, no parameters are used for instance count. In future versions, instance count will be parameterized as what VS tooling does by default.
You can use SFNuGet to package stateless, stateful, Web API and actor services. But you can’t directly package a Guest Application service. This is because the Guest Application service doesn’t have its own service project. For Nginx, I created a wrapper service that wraps the guest executable.
When you install SFNuGet, it reads your assembly manifest and generates a NuGet spec (nuspec) file. The file is not updated afterwards. You’ll need to manually update the file if you want to make further changes.
NuGet.exe hangs when invoked from msbuild if the package contains many files. So in the code I have a monitor that checks the output of NuGet.exe and shuts it down when I see “Successfully created package”. This is obviously undesirable but I don’t have better alternatives at this point. You can examine the script in the NuGetPackage.ps1 file after you install SFNuGet. Please let me know if you have better solutions.
In the future, I hope to see better VS tooling integrations. Such as making the referenced services appear under the “Sevices” node in the application project, providing a “add existing service” menu with better discovery experience, and allow NuGet packages to be referenced without unpacking, etc.
I’m planning on allowing publishing a Docker image (starting with Windows-based images first) as a SFNuGet package. This will allow including a stateless Docker container as a guest application service into your Service Fabric application and deploy the application on a Docker-enabled Service Fabric cluster. Is this scenario valuable to you? Please let me know!

Call to actions

Give SFNuGet a try! And please tell me if you like it or not. And if you want to see any tooling improvements to make it an even better experience, please let me know! You can send your feedbacks to hbai@microsoft.com or Twitter handle @HaishiBai2010 (with hashtag #SFNuGet).

Running iometer on a Linux container

2016-04-20T17:24:00.000-07:00

iometer is a popular I/O subsystem measurement and characterization tool. It has two pieces: iomemter and dynamo. The iometer component provides user UI, and the dynamo component drives the actual workloads. This post introduces how to run dynamo on a Linux container and connect it to an iometer instance running on a Windows machine. The two machines can be two physical machines on the same network, or two virtual machines on the same virtual network.

Define Docker container

1. Define a Dockerfile that describes an Ubuntu-based container with dynamo installed and a /localdata volume:

FROM ubuntu
MAINTAINER haishi bai
RUN apt-get update
RUN apt-get install -y wget libaio1 libaio-dev
RUN wget http://sourceforge.net/projects/iomemter/files/iometer-stable/1.1.0/iometer-1.1.0-linux.x86_64-bin.tar.bz2/download
RUN tar -xvjf download
RUN mkdir /localdata
VOLUME /localdata

The Dockerfile is straightforward - it downloads and unpack dynamo with required libraries and creates a /localdata volume.

2. Build the container

docker build -t iomemter .

Launch iomemeter and dynamo

1. Launch iomemter on the Windows machine.
2. Launch the container on the Linux machine:

docker run -it -h mycontainer --net host --rm iometer /bin/bash

Plesae note that the command uses a --net host parameter to directly bind the container to the host's nework card. You need to do this because dynamo selects a random port to listen for messages from iometer. If it uses a fixed port, we could have used -p switch to map the specific port.

3. Inside the container, launch dynamo

sudo ./dynamo -i [ip of windows machine] -m [ip_of_Linux_macihne]

For dynamo and iomemeter to connect to each other, you need port 1006 (that iomemter listens to) and the random port picked by dynamo to be open. The easiest way is to close firewalls on both sides.

Run the test

1. In iomemter, define a new Access Specification with Transfer Request Size to be 8K, or multiples of 8K. This is to avoid a section size mismatch error.
2. Also in iomemter, define Maximum Disk Size on the Disk Targets tab. This is to avoid host disk being filled up by test data. If you are using a separate data volume, you can skip this step.
3. Set up other parts of the test profile and launch the test.

Project: Smart Fridge

2015-09-14T16:48:00.002-07:00

The project

Smart Fridge is a project my team did for the Seattle Mini Make Faire 2015. The goal of the project is to create a prototype of a REAL smart fridge that automatically tracks its own contents without any extra user actions. Users simply use the fridge as usual, and the fridge automatically identifies and tracks its inventory by using integrated weight sensors and image analysis services base on machine learning. Then, based on the inventory info, cross-referenced with the user’s consumption patterns, diet plans, favorite recipes and storage promotions, the fridge generates customized shopping lists for the user. Finally, as the user steps into a supermarket, Cortana proactively reminds him to pick up necessary groceries.

Application scenarios

Smart Fridge makes many consumer scenarios and business scenarios possible. At consumer level, the following are the some of the possible applications:

Fitness companion. An import part of a fitness program is the diet plan. A Smart Fridge can help to reinforce diet plans by monitoring food consumptions and recommending better diet options. It can go as far as casting different lights or symbols on the items to indicate which items are recommended based on user’s plan, and which items should be avoided at a particular time.
Monitoring expired items. The fridge can notify you if some of the items are going to expire so that you can keep the contents in your fridge fresh and safe to eat.
Saving money with grocery. Smart Fridge service can incorporate local store discount and promotion information and recommend items to buy, or alternatives to consider as you walk into the store.
Plan for dinners & parties. Smart Fridge service can generate shopping lists based on selected recipes so you can get everything you need for your dinners or parties. And it can also generate recipes based on what you have in case you need to put something together quickly.

At business level, Smart Fridge generates opportunities for advertisers, grocery stores, logistics, online stores, as well as a number of extended services.

Advertisers have the opportunity to push very focused advertisements based on user’s consumption patterns and spending patterns.
Grocery stores, by collecting user-shared Smart Fridge data in the neighborhood, can optimize their inventory towards lean inventory. They can also design more effective campaigns and promotions based on the data.
Smart Fridge owners can potentially have the Fridge to directly communicate with selected stores to periodically resupply itself.

Step by Step: Provision and Manage a Deis Cluster on Microsoft Azure

2015-05-21T23:21:00.001-07:00

In this blog, I’ll walk you through the steps to provision a Deis cluster on Microsoft Azure. We’ll provision the cluster using a Deis Azure template, which is one of the Azure Quickstart Templates. Then, we’ll deploy a “Hello World” Go application on the cluster.

Overview

The following diagram shows the architecture of the deployed system. A system administrator manages the cluster using Deis tools such as deis and deisctl. Connections are established through an Azure load balancer, which forwards the connection to one of the member nodes on the cluster. The clients access deployed applications via the load balancer as well. In this case the load balancer forwards the traffic to a Deis router mesh, which further routs traffic to corresponding Docker containers hosted on the cluster.

Provision the cluster

This section introduces all the steps to provision a Deis cluster. You can carry out all the steps on either Windows or Linux. I chose to use a Ubuntu VM on Azure. The steps assume you’ve got Git, openssl, and Azure PowerShell or Azure CLI installed and configured.

Clone the repository: https://github.com/Azure/azure-quickstart-templates.
```
git clone https://github.com/Azure/azure-quickstart-templates
```
Go to the template folder.
```
cd azure-quickstart-templates\deis-cluster-coreos
```
If you don’t have a OpenSSH key pair, you should create one using ssh-keygen:
```
ssh-keygen -t rsa -b 4096 -c "[your_email@domain.com]"
```
Generate a certificate using the above private key:
```
openssl req -x509 -days 365 -new -key [your private key file] -out [cert file to be generated]
```
Go to https://discovery.etcd.io/new to generate a new cluster token, which looks something like
```
https://discovery.etcd.io/6a28e078895c5ec737174db2419bb2f3
```
Each CoreOS cluster needs to have a unique token from this free service. Please see CoreOS documentation for more details.
Modify cloud-config.yaml to replace the existing discovery token with the new token:
```
#cloud-config
---
coreos:
  etcd:
    # generate a new token for each unique cluster from https://discovery.etcd.io/new
    # uncomment the following line and replace it with your discovery URL    
    discovery: https://discovery.etcd.io/3973057f670770a7628f917d58c2208a
...
```
Modify azuredeploy-parameters.json: Open the certificate you created in step 4. Copy all text between ----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- into the sshKeyData parameter (you'll need to remove all newline characters).
Modify the newStorageAccountName parameter. This is the storage account for VM OS disks. This account name has to be globally unique.
Modify the publicDomainName parameter. This will become part of the DNS name associated with the load balancer public IP. The final FQDN will have the format of [value of this parameter].[region].cloudapp.azure.com. For example, if you specify the name as deishbai32, and the resource group is deployed to West US, then the final FQDN to your load balancer will be deishbai32.westus.cloudapp.azure.com.
Save the parameter file. And then you can provision the cluster using Azure PowerShell:
```
.\deploy-deis.ps1 -ResourceGroupName [resource group name] -ResourceGroupLocation "West US" -TemplateFile .\azuredeploy.json -ParametersFile .\azuredeploy-parameters.json -CloudInitFile .\cloud-config.yaml
```
Or use Azure CLI:
```
./deploy-deis.sh -n "[resource group name]" -l "West US" -f ./azuredeploy.json -e ./azuredeploy-parameters.json -c ./cloud-config.yaml
```
Once the resource group is provisioned, you can see all the resources in the group on Azure Portal. As shown in the following screenshot, the resource group contains a virtual network with three VMs, which are joined to the same availability set. The group also contains a load balancer, which has an associated public IP.

Install the client

You need deisctl to control your Deis cluster. Although deisctl is automatically installed in all the cluster nodes, it's a good practice to use deisctl on a separate administrative machine. Because all nodes are configured with only private IP addresses, you'll need to use SSH tunneling through the load balancer, which has a public IP, to the node machines. The following are the steps of setting up deisctl on a separate machine.

Install deisctl:
```
mkdir deis
cd deis
curl -sSL http://deis.io/deisctl/install.sh | sh -s 1.6.1
sudo ln -fs $PWD/deisctl /usr/local/bin/deisctl
```
Add your private key to ssh agent:
```
eval `ssh-agent -s`
ssh-add [path to the private key file, see step 1 in the previous section]
```
Configure deisctl:
```
export DEISCTL_TUNNEL=[public ip of the load balancer]:2223
```

The template defines inbound NAT rules that map 2223 to instance 1, 2224 to instance 2, and 2225 to instance 3. This provides redundancy for using the deisctl tool. You can examine these rules on Azure Portal:

Install and start Deis platform

Now you can use deisctl to install and start the Deis platform:

deisctl config platform set domain=[some domain]
deisctl config platform set sshPrivateKey=[path to the private key file]
deisctl install platform
deisctl start platform

Note: starting the UNIT deis-builder.service deis-controller.service deis-database.service deis-logger.service deis-logspout.service deis-logspout.service deis-logspout.service deis-publisher.service deis-publisher.service deis-publisher.service deis-registry@1.service deis-router@1.service deis-router@2.service deis-router@3.service deis-store-daemon.service deis-store-daemon.service deis-store-daemon.service deis-store-gateway@1.service deis-store-metadata.service deis-store-metadata.service deis-store-metadata.service deis-store-monitor.service deis-store-monitor.service deis-store-monitor.service deis-store-volume.service deis-store-volume.service deis-store-volume.service platform takes a while (>10 minutes). Especially, starting the builder service can take a long time. And sometimes it takes a few tries to succeed. If you found the operation seems to hang after a few minutes. You can use ctrl+c to break execution of the command and retry. You can use deisctl list to verify if all services are running:

deisctl list MACHINE                 LOAD    ACTIVE          SUB ebe3005e.../10.0.0.6    loaded  active          running ebe3005e.../10.0.0.6    loaded  active          running 9c79bbdd.../10.0.0.5    loaded  active          running 9c79bbdd.../10.0.0.5    loaded  active          running 8d658d5a.../10.0.0.4    loaded  active          running 9c79bbdd.../10.0.0.5    loaded  active          running ebe3005e.../10.0.0.6    loaded  active          running 8d658d5a.../10.0.0.4    loaded  active          running 9c79bbdd.../10.0.0.5    loaded  active          running ebe3005e.../10.0.0.6    loaded  active          running ebe3005e.../10.0.0.6    loaded  active          running ebe3005e.../10.0.0.6    loaded  active          running 8d658d5a.../10.0.0.4    loaded  active          running 9c79bbdd.../10.0.0.5    loaded  active          running 8d658d5a.../10.0.0.4    loaded  active          running 9c79bbdd.../10.0.0.5    loaded  active          running ebe3005e.../10.0.0.6    loaded  active          running 9c79bbdd.../10.0.0.5    loaded  active          running 8d658d5a.../10.0.0.4    loaded  active          running 9c79bbdd.../10.0.0.5    loaded  active          running ebe3005e.../10.0.0.6    loaded  active          running 8d658d5a.../10.0.0.4    loaded  active          running 9c79bbdd.../10.0.0.5    loaded  active          running ebe3005e.../10.0.0.6    loaded  active          running 8d658d5a.../10.0.0.4    loaded  active          running 9c79bbdd.../10.0.0.5    loaded  active          running ebe3005e.../10.0.0.6    loaded  active          running .csharpcode pre "Courier New", courier, monospace; { color: #cc6633; } { background-color: #ffff00; }
Deploy and scale a Hello World application
The following steps show how to deploy a "Hello World" Go application to the cluster. The steps are based on: http://docs.deis.io/en/latest/using_deis/using-dockerfiles/#using-dockerfiles.

For the routing mesh to work properly, you’ll need to have a wildcard A record for your domain pointing to the public IP of the load balancer. The following screenshot shows the A record for my domain registration on GoDaddy: 

Install deis:mkdir deis
cd deis
curl -sSL http://deis.io/deis-cli/install.sh | sh
ln -fs $PWD/deis /usr/local/bin/deis


Create a new SSH key, and then add the public key to GitHub. You can also reuse your existing key. To create a new SSH key pair, use:cd ~/.ssh
ssh-keygen (press [Enter]s to use default file names and empty passcode)


Add id_rsa.pub, or the public key of your choice, to GitHub. You can do this by using the Add SSH key button in your SSH keys configuration screen:

Register a new user:deis register http://deis.[your domain]


Add the SSH key:deis keys:add [path to your SSH public key]


Create an application. git clone https://github.com/deis/helloworld.git
cd helloworld
deis create
git push deis master


The git push will trigger Docker images to be built and deployed, which will take a few minutes. From my experience, occasionally, Step 10 (Pushing image to private repository) may hang. When this happens, you can stop the process, remove the application using deis apps:destroy –a [application name] to remove the application and try again. You can use deis apps:list to find out the name of your application. If everything works out, you should see something like the following at the end of command outputs:-----> Launching...
       done, lambda-underdog:v2 deployed to Deis
       http://lambda-underdog.artitrack.com
       To learn more, use `deis help` or visit http://deis.io
To ssh://git@deis.artitrack.com:2222/lambda-underdog.git
 * [new branch]      master -> master



Verify if the application is working: curl -S http://[your application name].[your domain]

You should see:Welcome to Deis!
See the documentation at http://docs.deis.io/ for more information.

(you can use geis apps:list to get the name of your application).
Scale the application to 3 instances:deis scale cmd=3


Optionally, you can use deis info to examine details of your application. The following outputs are from my application deployment:deis info
=== lambda-underdog Application
{
  "updated": "2015-05-22T06:14:10UTC",
  "uuid": "10c74ee7-b7ff-4786-967a-7e65af7eabc3",
  "created": "2015-05-22T06:07:55UTC",
  "url": "lambda-underdog.artitrack.com",
  "owner": "haishi",
  "id": "lambda-underdog",
  "structure": {
    "cmd": 3
  }
}

=== lambda-underdog Processes
--- cmd:
cmd.1 up (v2)
cmd.2 up (v2)
cmd.3 up (v2)

=== lambda-underdog Domains
No domains


Future work
Currently the template only supports 3-node clusters. This is because of a limitation in Azure template NAT rule definition, which doesn’t support loop syntax. I’ll update the template and this blog when this is fixed. Another problem I’ve observed is that deploying an application sometimes hangs (see step 8 in the previous section). I’ll update the blog once I find more about it.

Running ASP.NET vNext on Linux, the Docker way – Under 5 minutes

2014-12-16T13:19:00.001-08:00

Just as I finished my lunch I thought I’d give it a try to get ASP.NET to run on Linux. And I gave myself 5 minutes to complete the task, as I did when I launched Minecraft server on Azure. So, this is NOT a blog to introduce you Docker, ASP.NET vNext or Mono. Instead, this article records the steps I did to bring up an ASP.NET vNext sample on Linux using Docker container, all under 5 minutes. And here we go.

Get an Linux VM on Azure, and put Docker on it. I chose to use Ubuntu. In my case I was just reusing one of my boxes on Azure so I didn’t count the time of provisioning VM and installing Docker in this case. Okay, okay, it might take a bit more than 5 minutes if you need to start from scratch. I also defined an input endpoint at port 80 so I could access my site via internet later as well.
There’s a Docker image on Docker Hub named microsoft/aspnet, which gives you a pre-installed environment of ASP.NET vNext. To launch a new Docker container with the image, simply use:
```
sudo docker run --name aspnet -it -p 80:5004 microsoft/aspnet
```
Now you are in the container and the environment is ready. The next step is to get samples. The image doesn’t come with git, but we can easily install it:
```
apt-get install git
```
Now pull down samples from https://github.com/aspnet/home:
```
git clone https://github.com/aspnet/home
```
Launch the HelloWeb sample:
```
cd /home/samples/HelloWeb
kpm restore
k kestrel
```
Open another console window and use curl to access the site:
```
curl http://localhost
```
And sure enough, if you’ve configured the input endpoint, you can access your site via your VM’s FQDN:

There you go, ASP.NET running on Linux, in a Container on Azure, in a couple of minutes. Now the lunch break is over! Thank you for reading!

Update 1/14/2015:

For a more elaborate tutorial, please see this MSDN article.

Use Docker and Azure CLI to deliver a smooth Linux-focused Azure training experience

2014-12-11T15:49:00.001-08:00

As an evangelist, I go around to participate and sometimes to organize hackathons, hands-on-labs and trainings for Azure. And for Linux-focused events, one thing every participant always need to do is to install and configure is Azure Cross-Platform Command-Line Interface (Azure CLI). Installing and configuring Azure CLI is easy - just follow the instructions in the link and you’ll be up and running fairly quickly. However, in larger training events, getting tens of participants to install, configure, and sort out subscriptions still takes time. The main idea of this post is to introduce a solution that uses Docker container to provide pre-built CLI environments so that participants can simply login and try, without needing to install or configure anything. Participants can use pre-provisioned subscriptions, which come with a fully automated experience. They can also use their own subscriptions, with just a couple of extra steps.

Another use case of this solution is for academics. A school or an university may have a bunch of Azure subscriptions that they want to dynamically allocate to different students to use. This solution will allow them to manage the subscriptions centrally, while granting Azure CLI to different students at different time.

The event participant experience

Before introducing the steps of setting things up, I’ll walk you through the participant experience:

A participant is given a credential and an machine address to login to a pre-provisioned virtual machine.
She logs into the machine, and issues command start-cli. And that’s all! She’s ready to go (see [1] in the following screen shot]).
She’s given a Docker container with Azure CLI installed and pre-configured (see [2]), and she can immediately use any Azure CLI commands (see [3]).
Once she’s done, she can exit out the container (see [4]) , and the container is destroyed.

The student experience

A student is given a credential and an machine address to login to a pre-provisioned virtual machine. She’s also given a token string that is mapped to an Azure subscription.
She logs into the machine, and issues command start-cli <token string>. Then she’ll be able to use the Azure subscription.

Please note that the token string is NOT for authentication. It’s up to the solution implementer to customize the start-cli script to implement additional authentication (such logging in using a student id), and mappings from the token to actual publish settings file name.

How to prepare for an event

Provision a couple of Linux VMs (my favorite is Ubuntu). Since we can run quite a few containers on one VM, you can use just a couple of VMs to support a large number of participants.
Install Docker on these VMs.
Pull the Azure-Cli image (hbai/azure-cli) from Docker Hub.
Create a new folder, for instance /localpub, on the VM. Download your Azure subscription files to this folder. You should rename the files to shorter names, but make sure you keep the .publishsettings extension. For a larger audience, you can use multiple subscriptions. And the image has an automatic script that randomly distribute container users among these subscriptions.
Put the following shell script (named start-cli.sh), which is a 1-liner, on to the VMs:
```
sudo docker run -v /localpub:/pub --env SUBSCRIPTION=$1 -it --rm hbai/azurecli /bin/bash
```

How to prepare for schools

This part is still open-ended, as additional authentication and mappings need to be implemented. An as each school is different, it’s not implemented out-of-box. Essentially, when a user uses start-cli.sh, if she supplies a publish settings file name in the place of the <token string> parameter, the file name will be passed to the container (via environment variable SUBSCRIPTION) and the container will use this particular file instead of randomly picking a subscription file. For instance, the following command launch the CLI container with demo.publishsettings file (that resides under /localpub folder on the VM) selected:

start-cli.sh demo.publishsettings

In a properly implemented system, string tokens should be issued instead of directly giving students publish settings file names. Then, a mapping from the token string space to the publish settings file space needs to be implemented, plus additional authentication as needed.

Additional Resources

And if you are curios about how exactly the Docker container is built, the following are code lists of the Docker file as well as the shell script in the container. I’m fairly new to shell scripting, so if I’m doing something that hurts your eyes, please let me know :) !

Dockerfile

FROM ubuntu:14.04
MAINTAINER Haishi Bai <hbai@microsoft.com>
ADD azure-cli.sh /
RUN chmod +x /azure-cli.sh
RUN apt-get update
RUN apt-get -qq update
RUN apt-get install -y nodejs npm
RUN update-alternatives --install /usr/bin/node node /usr/bin/nodejs 10
RUN npm install azure-cli -g
RUN cat /azure-cli.sh >> /etc/bash.bashrc

azure-cli.sh

PUBFOLDER="/pub"
CLICONFIGURED=0
SELECTEDSUB="$PUBFOLDER/$SUBSCRIPTION"
if [ -d "$PUBFOLDER" ] ; then
        FILECOUNT=$(ls $PUBFOLDER/*.publishsettings | wc -l)
        if [ $FILECOUNT -gt 0 ] ; then
                FILE=""
                if [ ${SUBSCRIPTION:-""} != "" ] ; then
                        if [ -f "$SELECTEDSUB" ] ; then
                                FILE="$SELECTEDSUB"
                        fi
                else
                        let INDEX=$RANDOM%$FILECOUNT
                        FILES=($PUBFOLDER/*.publishsettings)
                        FILE="${FILES[$INDEX]}"
                fi
                if [ "$FILE" != "" ] ; then
                        azure account import $FILE
                        CLICONFIGURED=1
                else
                        echo "Can't load Azure subscription file. Please contact your administrator. If you have Microsoft organizational account, you can log in using azure login. "
                fi
        fi
fi

Use the container image directly

Create a folder to hold your Azure publish settings file.
Launch the container. Make sure your local folder is attached as a volume mounted at /pub:
```
sudo docker run -v /localpub:/pub --env  -it azurecli hbai/azurecli /bin/bash
```

Future work

If there are enough interests, I (or YOU!) will put in a default token-to-file mapping implementation.

Thank you for reading!

MongoDB clusters on Azure using MMS and Custom Script Extension

2014-12-10T20:24:00.001-08:00

Overview

MMS is a hosted service that allows you to create and manage MongoDB deployments at different locations. The MongoDB clusters can reside on your local networks or on public clouds. And MMS provides you a unified view to monitor and manage these clusters, as long as you have installed MMS’s Automation Agents and Monitoring Agents on them.

In this article, I’ll walk you through the steps to provision MongoDB clusters along with Automation Agents on Azure so that the clusters can be managed by MMS. And then, I’ll show you how to automate the process using Azure’s Custom Script Extension.

Provision a standalone instance

First, let’s start with something simple – we’ll manually provision a standalone MongoDB instance on Azure and then register it with MMS.

First, provision a new virtual machine on Azure. In this excise I’ll use an A3 (4 cores, 7GB memory) Ubuntu Server 14.10 machine, which is named hbai15-mongo-s.cloudapp.net. If you need help in provisioning the virtual machine, please follow this tutorial. When provisioning the virtual machine, you should define an Endpoint at port 27000. If you forgot, you can also add the endpoint after the virtual machine has been provisioned (see this page).
Go to https://mms.mongodb.com and provision a new account, which is free. You don’t need a credit card, but you’ll need a cell phone or Google Authenticator for multi-factor authentication.
Log in to the MMS portal. Because you don’t have a deployment yet, you’ll be redirected to a Setup page. You can also access the page, which looks something like the following screenshot. Click the BEGIN SETUP button to continue.
At this point, there isn’t a one-click deployment on Azure yet, so we’ll choose the DEPLOY IN OTHER REMOTE option.
Click on the CREATE STANDALONE button.
On the next screen, enter the host name of your virtual machine and click the CONTINUE button to continue. In my case, I use hbai15-mongo-s.
On the next page, expand the DOWNLOAD AGENT dropdown box, and pick your server OS. In my case I use Ubuntu (12.04+1).
Click on the menu will bring up a help page, which contains a list of commands you need to run on the server:
```
curl -OL https://mms.mongodb.com/download/agent/automation/mongodb-mms-automation-agent-manager_1.4.1.769-1_amd64.deb
sudo dpkg -i mongodb-mms-automation-agent-manager_1.4.1.769-1_amd64.deb
sudo vi /etc/mongodb-mms/automation-agent.config (enter your group id and api key)
sudo mkdir -p /data
sudo chown mongodb:mongodb /data
sudo start mongodb-mms-automation-agent
```
Once you’ve executed all above commands on the server, go back to MMS portal and click on the VERIFY AGENT button to verify the agent. After the agent has been verified, click on the CONTINUE button to continue.
10. On the final page, click the DEPLOY button to continue.
After a few minutes, your standalone instance should be deployed and is ready to use. For instance, you can use Mongo client to connect to it (please note in the following screenshot I used FQDN to address the machine):
And sure enough, you can monitor your instances on MMS portal:

Automating agent deployment with Custom Script Extension

Before we go about to create replica sets, we’ll use Azure’s Custom Script Extension to automatically deploy MMS’s Automation Agent when we provision new virtual machines. Then, we’ll be able to easily leverage MMS to create replica sets on those virtual machines.

We have several options to achieve this. First, for scripting language, we can either use Azure PowerShell, or Azure Cross-Platform CLI. Second, we can inject our script using cloud-init for Ubuntu during provision, or using Custom Script Extension during or after provision. Here I’m going to choose CLI and Custom Script Extension.

Install Azure Cross-Platform CLI. For instance, on my Ubuntu box I used the following command to install Azure CLI:
```
sudo npm install azure-cli -g
```
Configure Azure CLI to use the correct Azure subscription of your choice. Please refer to this document if you need help.
Prepare a shell script (in my case I named it config-automation-agent10.sh), which contains the commands listed in step 8 in the first section with a few tweaks: we’ll use sed to replace the default @GROUP_ID@ and @API_KEY@; and we’ll make curl to work in silent mode:
```
sudo curl -sOL https://mms.mongodb.com/download/agent/automation/mongodb-mms-automation-agent-manager_1.4.1.769-1_amd64.deb
sudo dpkg -i mongodb-mms-automation-agent-manager_1.4.1.769-1_amd64.deb
sudo sed -i 's/mmsGroupId=@GROUP_ID@/mmsGroupId=[your group id]/g' /etc/mongodb-mms/automation-agent.config
sudo sed -i 's/mmsApiKey=@API_KEY@/mmsApiKey=[your API key]/g' /etc/mongodb-mms/automation-agent.config
sudo mkdir -p /data
sudo chown mongodb:mongodb /data
sudo start mongodb-mms-automation-agent
```
Upload the script to an Azure Blob storage container of your choice. Custom Script Extension will download the above script from this storage account.
Provision a new Ubuntu VM using the Azure portal or Azure CLI.
Then, in Azure CLI, use the following command to install the Custom Script Extension on to the machine, and then instruct the extension to download and execute the script. You’ll need to update highlighted parts with your settings:
```
azure vm extension set -t '{"storageAccountName":"[your storage account]","storageAccountKey":"[your storage account key]"}' -i '{"fileUris":["[your storage container url]/config-automation-agent10.sh"],"commandToExecute":"sh config-automation-agent10.sh"}' [your VM name] CustomScriptForLinux Microsoft.OSTCExtensions 1.*
```
Once this is done, in a few minutes, your VM should pop up on MMS as one of the available servers where you can deploy MongoDB to.

Provisioning a Cross-region MongoDB Replica Set

In this part, we’ll create a cross-region MongoDB Replica Set with one Primary and one Secondary in West US, and one Secondary in West Europe. To facilitate member communications, we’ll create two Virtual Networks and use VNet to VNet connection to link the two Virtual Networks together. The Primary and the first Secondary will be deployed on the first Virtual Network, with the second Secondary deployed on the other. Each VM is put its own Cloud Service with port 27000 open. The VMs are put in their corresponding Cloud Services so that we can address them via the Cloud Service FQDNs. Alternatively, you can use instance-level public IP addresses. And because the members use host names to find each other, we’ll edit the hosts file on all VMs so they can find each other by host names. Alternatively, you can set up a DNS server. The following diagram illustrate the final topology of my Replica Set:

Provision 2 virtual networks, one in West US, with address space 10.1.0.0/16, and another in West Europe, with address space 10.2.0.0/16. When naming the virtual machines, make sure you use some common prefixes that can separate these machines from other servers you register with MMS. In my case I prefixed machine names with “hbai15-mongo-t”.
Use VNet to VNet connection to link the two Virtual Networks together. The linked article is one of the best tutorials on the topic.
Deploy 3 Ubuntu virtual machines, two on the first virtual network, and one on the second virtual network.
Edit hosts file on all VMs so that they can find each other by host names.
Install MMS’s Automation Agent (see previous section).
Back on MMS, wait for all three servers to show up.
Back on MMS, click the ADD button on the Deployment page and select the Create New Replica Set menu.
Fill out the Replica Set Configuration form. Please note 1) use ^prefix to identify candidate servers; 2) set the Priority of the third machine, which is in West Europe, to 0 so it’s never elected Primary.
Deploy the Replica Set.
Once the Replica Set is ready, you can perform some simple tests to see if data replication is working. Connect to the Primary and insert a new record:
```
user1 = {name: “haishi”, rank: 1}
db.users.insert(user1)
```
and then query the record from the Secondary in West Europe:
```
rs.slaveOK()
db.users.find()
```

Summary

In this blog I walked you through the steps of provisioning virtual machines on Azure with MMS’s Automation Agent using Azure’s Custom Script Extension, and then use MMS to deploy and manage MongoDB instances. Thank you for reading!

Minecraft Server on Azure using Docker Container–Under 5 minutes

2014-10-29T02:40:00.001-07:00

As I walked across the hall of TechEd Europe 2014, an idea hit me – why don’t I try to run a Minecraft server on Azure using container? And I set a challenge for myself – I’ll get it running under 20 minutes. Then, as I sat down in the speaker room, I started to work:

Look for a Minecraft server image on Docker Hub. A quick search of “minecraft” returned a bunch of choices, among which itzg/minecraft-server seemed like a popular choice.
Provision a new Linux box with Docker support. Lucky for me, I had the Docker Client for Windows bits used during the keynote, so I could easily launch a new Linux box (in this case I chose Ubuntu) using a single command:
```
docker  hosts create --driver azure --azure-publish-settings-file ./hbai.publishsettings  --azure-name azure-docker1 --azure-location “West Europe” azure-docker1
```
Then I added a TCP endpoint at port 25565, which is the default port Minecraft server uses.
Next was to launch the container:
```
docker --tls run --name minecraft -e EULA=TRUE -d -p 25565:25565 itzg/minecraft-server
```
And once the container was downloaded, the server was up and running!
Then, I went about to download the Minecraft client: https://minecraft.net/download.
I launched the client, clicked Play, selected Multiplayer and then Direct Connect. Entered the DNS name of my VM on Azure, and I was connected!

There you go! A Minecraft server running on Docker, hosted on an Azure Ubuntu VM! That took less than 15 minutes, including the time to download packages.

Please note that I didn’t set up any data storage in this case, so don’t get mad if you found your server states are lost after reboot .

Enjoy!

Edit – 11/4/2014:

Mounting a data directory is (in theory) easy. You just need to add a –v switch: –v /path/on/host:/data (see https://registry.hub.docker.com/u/itzg/minecraft-server/).

An unrelated note – if you want to ssh into the host, you can use command :

ssh -i .\.docker\hosts\[your host name]\id_rsa tcuser@[your host name].cloudapp.net

The client uses .docker\hosts folder to track hosts being managed by the client, and you can find ssh keys for each of the host under its corresponding folder. At the moment when this edit is made, by default the user name is tcuser.

Edit – 11/18/2014

Docker CLI for Windows has been announced today: http://azure.microsoft.com/blog/2014/11/18/docker-cli-for-windows-clients/.

Walkthrough: Use boot2docker on Windows

2014-10-09T17:33:00.001-07:00

Boot2docker is a lightweight application that helps you to run Docker containers on Mac and Windows machines. This blog is a walkthrough to help you get it going on your Windows machine. First, I’ll go through the steps of getting boot2docker installed. Then, I’ll go through steps to enable fie sharing between your host machine and boot2docker, as well as between your host machine and a Docker container.

Installation

At the time when this blog is written, boot2docker relies on VirtualBox to host the Tiny Core Linux vm that boot2docker depends on. If your Windows machine has Hyper-V enabled, there might be problems to get VirtualBox running. Although it’s possible to make Hyper-V and VirtualBox running side-by-side, the exact steps are out of scope of this blog. The easiest way is to disable the Hyper-V feature for now in Control Panel –> Programs and Features –> Turn Windows features on or off.
Download and install boot2docker for Windows from this link. Simply follow the install wizard to complete the installation using all default settings.

Launch

By default, the installation wizard creates two desktop shortcuts: Boot2Docker Start and Oracle VM VirtualBox. To launch boot2docker, double-click Boot2Docker Start.
If the VM fails to launch, you can manually launch it from VirtualBox and restart boot2docker.

Share files between your host and boot2docker

In boot2docker, download cifs-utils, for example:
```
wget http://distro.ibiblio.org/tinycorelinux/5.x/x86/tcz/cifs-utils.tcz
```
Install cifs-utils:
```
tce-load -i cifs-utils.tcz
```
Then, create a new folder, for instance /mnt/datashare:
```
sudo mkdir /mnt/datashare
```
On the host Windows machine, create a new folder, and then share it with yourself. In the following example I assume the shared folder is at //<your machine’s ip>/shared.
Now, you are ready to mount the Windows folder on boot2docker:
```
sudo mount -t cifs //<your machine's ip>/shared /mnt/datashare -o user=<your user name>
```
The <your machine’s ip> should be your machine’s IP address, and <your user name> should be your Windows account name. If the user is from a domain, enter the name WITHOUT the domain name. You’ll be asked to enter your password, then the Windows folder will be mounted at /mnt/datashare.

Create a volume container from a Windows folder

If you want to have a volume container based on a Windows folder, you can use the following commands, as introduced on this page:
```
docker run -v /data --name my-data busybox true
docker run --rm -v /usr/local/bin/docker:/docker -v /var/run/docker.sock:/docker.sock svendowideit/samba my-data
```
Once the last command succeeds, it gives you some information on how to connect:

Then, you should be able to access this volume from Windows by //<your boot2docker ip>/data. Note here the IP address is your boot2docker IP, not your hosting machine IP.
And you can also mount this volume container when you launch a new Docker container. For instance, the following command start a new Ubuntu container, which will have access to the volume by /data:
```
docker run -it --volumes-from my-data ubuntu
```

Tutorial: Building an Azure Template

2014-09-26T10:40:00.001-07:00

Overview

An Azure Template is a JSON file that captures the infrastructure requirements of your application. An Azure Template defines a number of related resources that are required by your application. Each resource represents a manageable entity, such as an Azure Website, a virtual machine, a SQL database, an identity, a load balancer, or an autos-scaling rule, etc. When an Azure Template is deployed on Azure, Azure Resource Manager ensures that all resources are brought to the specified states so that your application runs under the exact desired environments.

In this tutorial, we’ll walk you through of steps of authoring and deploying a simple Azure Template. The template defines a web application with a frontend running on Azure Websites and a database running on Azure SQL Database. The goal of this tutorial is to walk you through the structure of an Azure Template. In your actual projects, you should use graphical UIs to edit your templates to avoid manual editing errors.

Preparing the environment

At the time when this blog is written, the easiest way to get started with Azure Template editing is to use Visual Studio with Azure Resource Manager Tools (Preview) for Visual Studio. In addition, you’ll also need an active Azure subscription. You can get a free trial subscription at www.azure.com.

Getting started

Azure provides a rich set of Azure Templates in its Azure Gallery. In this tutorial we’ll use an existing template from the gallery to get the editing experience started. But we’ll clear the template so that we can start from scratch.

In Visual Studio, select the FILE –> New –> Project… menu.
On the New Project dialog, select the Cloud –> Cloud App from the Azure Gallery template, enter a Name for your project, and then click the OK button.
On the Select Azure Template dialog, select the Website + SQL template, and click the OK button.
On the New ASP.NET Project dialog, select MVC template, and click the OK button.
Once the wizard completes, you’ll have an ASP.NET website and an Azure Template that is ready to be deployed to Azure. Under the solution’s DeploymentItems\Templates folder, you’ll find an Azure Template named WebSiteSQLDatabase1.json. This template already contains all necessary resources for you to deploy your website to Azure. However, for the sake of learning, we’ll clear the template to a bare minimum.
Modify the template so the code looks like the following code list:
```
{
    "$schema": "http://schema.management.azure.com/schemas/2014-04-01-preview/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "location": "West US",
    "resources": [
    ]
}
```
In this minimum template file, the $schema property indicates the schema version of the template file. The contentVersion property indicates the version of the template file itself. The main element of the file is the resources array, which contains all the resources to be defined in the group.

NOTE: There are several other top-level properties such as parameters, variables, tags and outputs. We’ll cover some of these properties later in this tutorial.
Save the template. And then, in Solution Explorer, right-click on the template and select the Deploy Template… menu. On the Deploy Template dialog, select the Azure subscription, storage account, and deployment location you want to use, then click the Deploy button to deploy the template to Azure.

NOTE: Leave the Template parameters file field at its default value. We’ll come back to this later.

The deployment should succeed after a short delay. You can observe the deployment traces in the Output window. Deployment of an Azure Template is an idempotent operation so that you can deploy the same template as many times as you like. You can think an Azure Template as a definition of the desired states of your application resources. And Azure will make sure the resources are brought to specified states when you deploy the template.

Defining a Resource

In previous section you’ve deployed an empty Azure Template to Azure. In this part you’ll add a SQL Database resource to the template. You define a new resource by adding a new child element to the resources array.

A resource definition is a JSON object with three mandatory properties: name, type and apiVersion. The name property identifies the resource. And the type property and the apiVersion property combined specifies which version of what Resource Provider to use. Azure Resource Manager has an extensible architecture, in which different Resource Providers can be plugged into the system to provide capabilities of managing a variety type of resources. For example, for SQL Database servers, the corresponding Resource Provider type is Microsoft.Sql/servers, and the current apiVersion is “2.0”.

Modify your Azure Template to include the definition of a SQL Database server resource. In the following code list, a new SQL Database server named mysqlserver has been added to the resources array.
```
 1:{
 2:     "$schema": "http://schema.management.azure.com/schemas/2014-04-01-preview/deploymentTemplate.json#",
 3:     "contentVersion": "1.0.0.0",
 4:     "resources": [
 5:         {
 6:             "apiVersion": "2.0",
 7:             "name": "mysqlserver",
 8:             "type": "Microsoft.Sql/servers",
 9:             "location": "West US",
10:             "properties": {
11:                 "administratorLogin": "admin",
12:                 "administratorLoginPassword": "password$123"
13:             }
14:         }
15:     ]
16:}
```
In above template, line 5 to line 14 defines a SQL Database server resource. In addition to the apiVersion, name, and type properties, you also see a location property and a properties property. These two properties, along with a tags property, are defined by a Resource Provider Contract, which defines the communication protocol between Azure Resource Manager and Resource Providers. The properties list is defined and consumed by the specific Resource Provider. In this case, SQL Server Resource Provider has defined two properties (among others) that represent administrator login (administratorLogin) and administrator password (administratorPassword).
Deploy the modified template. Once the template has been successfully deployed, you should be able to observe on Azure Management Portal that the new SQL Database server has been provisioned.

In above template we put password as plain text, which is not a recommended practice. We’ll fix this when we discuss parameters.

Defining a Child Resource

Next we’ll define a SQL Database on the newly defined SQL Database server. Naturally, a SQL Database belongs to a SQL Database server. In other words, a SQL Database is a child resource of a SQL Database server resource. And this is exactly how you would define it – to add a child element to the server JSON object we just defined.

Modify the template as shown in the following code list (line 14 – 28):
```
 1:{
 2:     "$schema": "http://schema.management.azure.com/schemas/2014-04-01-preview/deploymentTemplate.json#",
 3:     "contentVersion": "1.0.0.0",
 4:     "resources": [
 5:         {
 6:             "apiVersion": "2.0",
 7:             "name": "mysqlserver",
 8:             "type": "Microsoft.Sql/servers",
 9:             "location": "West US",
10:             "properties": {
11:                 "administratorLogin": "admin",
12:                 "administratorLoginPassword": "password$123"
13:             },
14:             "resources": [
15:                 {
16:                      "apiVersion": "2.0",
17:                      "name": "mysqldatabase",
18:                      "type": "databases",
19:                       "location": "West US",
20:                      "dependsOn": [
21:                           "[concat('Microsoft.Sql/servers/', 'mysqlserver')]"
22:                      ],
23:                      "properties": {
24:                          "edition": "Web",
25:                          "maxSizeBytes": "1073741824"
26:                      }
27:                 }
28:             ]
29:         }
30:     ]
31:}
```
In above template, line 15 to line 27 defines the SQL Database resource to be added to the SQL Database server resource. You can see all resource definitions in Azure Templates follow a consistent format. In this new resource definition, we define a SQL Database named “mysqldatabase”, and specify it should be a Web edition with maximum size of 1G.

NOTE: You’ll need to pick a different name other than mysqldatabase as the name is already taken.

Please note the dependsOn property in line 20. The dependsOn property is used to define dependencies among resources. In this particular case, the property specifies that the SQL Database resource depends on the SQL Database server resource – this makes sense because a SQL Database server has to be provisioned first before a SQL Database can be added to it. When an Azure Template is deployed, Azure Resource Manger builds up a dependency graph based on these dependencies and ensures the resources are configured in the correct order.

NOTE: We’ll see another type of dependency by references later in this tutorial.
As an added exercise, define another child resource under the SQL Database Server resource to enable accesses to the sever from all IP addresses:
```
{
    "apiVersion": "2.0",
    "type": "firewallrules",
    "name": "AllowAllWindowsAzureIps",
    "location": "West US",
    "dependsOn": [
        "[concat('Microsoft.Sql/servers/', 'mysqlserver')]"
    ],
    "properties": {
        "endIpAddress": "255.255.255.255",
        "startIpAddress": "0.0.0.0"
    }
}
```

Using Variables

In our current version of template, the SQL Database Server name “mysqlserver” has appeared in several different places. Since it’s not a good practice to repeat string literals in your template, you can use variables to correct this.

In an Azure Template, you can define an arbitrary JSON key/value dictionary named variables. And then, you can refer to any defined values in your template by the syntax [variables(‘[key]’)]. A property value can be a simple type or a complex type. As long as you follow standard JSON syntax, you can define very complex properties if you’d like. However in this tutorial we’ll use only string properties.

Add a variables element to the template root:
```
…
"variables": {
    "serverName":"mysqlserver"
},
…
```
Once a variable is defined, you can refer it in your template code. For instance, instead
```
"name": "mysqlserver"
```
use:
```
"name": "[variables('serverName')]"
```
And instead of
```
"[concat('Microsoft.Sql/servers/', 'mysqlserver')]"
```
use:
```
"[concat('Microsoft.Sql/servers/', variables('serverName'))]
```

Using Parameters

It’s often useful to get an Azure Template parameterized. For instance, instead of fixing the SQL Database server name in the script, you can define the server name as a parameter so that the template can be used to deploy multiple instances of identically configured servers. Another use case of parameters is to separate secure information such as passwords from the template. In the following steps, we’ll define both a serverLocation parameter and an adminPassword parameter.

To define parameters, add a new parameters element to the template root. Each parameter is defined as a complex type with a type property and optional allowedValues and defaultValue properties. In current schema the supported types are: int, string, securestring and bool. The following code segment defines a string-typed serverLocation parameter and an adminPasswword parameter as a secure string.
```
…
"parameters": {
    "serverLocation": {
        "type": "string"
    } ,
    "adminPassword": {
        "type": "securestring"
    }
},
…
```
When a parameterized template is deployed, Azure reads parameter values from a separate parameter file, which is another JSON file with a list of parameter values. You can create multiple parameter files for different environments. This helps you to make sure all your environments are configured in a consistent manor.
In Visual Studio, replace the content of WebSiteSQLDatabase1.dev.json with the following code list:
```
{
    "$schema": "http://schema.management.azure.com/schemas/2014-04-01-preview/deploymentParameters.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "serverLocation": {
            "value": "West Us"
        }
    }
}
```
Note we are not hard-coding the adminPassword value in this file. We’ll manually enter the value during deployment.
Then, replaces all “West US” constants in your template to parameter references:
```
[parameters('serverLocation')]
```
And replace all "password$123" with
```
[parameters('adminPassword')]
```
In Solution Explorer, right-click the template and select the Deploy Template menu. On the Deploy Template dialog, you can choose which template parameter file to use. Click the Edit Parameters button and enter a value for the adminPassword parameter.
Click the Deploy button to deploy the template again. The template should be deployed correctly.

Resource Dependencies

In the “Defining a Child Resource” section you’ve seen how you can add a dependency to a resource. In this part you’ll extend the template to include a definition of a web site, which is to be deployed on Azure Websites. In this case, the web site resource depends on an Azure Websites host plan resource.

Add the following resource definitions to your template:
```
{
    "apiVersion": "2014-04-01",
    "type": "Microsoft.Web/serverFarms",
    "name": "myhostplan",
    "location": "[parameters('serverLocation')]",
    "properties": {
        "name": "myhostplan",
        "sku": "Free"
    }
},
{
    "apiVersion": "2014-04-01",
    "type": "Microsoft.Web/Sites",
    "name": "mywebsite",
    "location": "[parameters('serverLocation')]",
    "dependsOn": [
        "[concat('Microsoft.Web/serverFarms/', 'myhostplan')]"
    ],
    "properties": {
        "name": "mywebsite",
        "serverFarm": "myhostplan"
    }
}
```
NOTE: You’ll need to pick a different name other than mywebsite for your website as the name is already taken.

In the above code segment, the first resource definition defines a free-tier Azure Website host plan. This shows that in addition to the resources you own, you can also use resource definitions to create references to other PaaS and SaaS services. The second resource definition defines the web site to be provisioned on the selected host plan. And the dependency is described by the dependsOn property just like you’ve seen earlier in this tutorial.
A second type of dependencies is created by references. In a resource definition, you can refer to a property from another resource definition, creating a dependency between the two. For example, in our case we’d like to enter a connection string to the SQL Database into the web.config file of our website. And in this connection string we’ll need to refer to the fully qualified domain name (FQDN) of the database server. Obviously the website resource provider has no place to understand how to find that name, but the SQL Database resource provider should be able to provide it. And this is done by the reference keyword.

Add a new child resource that represents a web.config file to the website resource, as shown in the bolded part of the following code list:

…
{
    "apiVersion": "2014-04-01",
    "type": "Microsoft.Web/Sites",
    "name": "mywebsite",
    "location": "[parameters('serverLocation')]",
    "dependsOn": [
        "[concat('Microsoft.Web/serverFarms/', 'myhostplan')]"
    ],
    properties": {
        "name": "mywebsiteddf",
        "serverFarm": "myhostplan"
    },
    "resources": [{
        "apiVersion": "2014-04-01",
        "type": "config",
        "name": "web",
        "dependsOn": [
            "[concat('Microsoft.Web/Sites/', 'mywebsiteddf')]"
        ],
        "properties": {
            "connectionStrings": [{
                "ConnectionString": "[concat('Data Source=tcp:', reference(concat('Microsoft.Sql/servers/', variables('serverName'))).fullyQualifiedDomainName, ',1433;Initial Catalog=mytestdatabase;User Id=admin@', variables('serverName'), ';Password=', parameters('adminPassword'), ';')]",
                "Name": "DefaultConnection",
                "Type": 2
            }]
        }
    }]
}
…

Please note how the connection string uses reference([SQL Database Server resource name]) to get a reference to the SQL Database server resource, and then its fullQualifiedDomainName to get the server’s fully qualified domain name.

Deploy the template again. You should see the website provisioned with the connection string correctly set.

Conclusion

In this tutorial we walked through the steps of creating a Azure Template that defines both a website and SQL Database. And we studied how to link them together using resource dependencies. We also covered how to use variables and parameters in Azure Template and how to use different parameter files for different deployment environments.

Enabling Hybrid Scenarios on Microsoft Azure

2014-09-19T13:32:00.001-07:00

Although cloud adoption has been phenomenal across the entire IT landscape, we can’t ignore the fact that there are much more compute and storage resources still running on local networks. A key criterion to evaluate the practicality of a cloud platform resides in not only what kind of workloads it can run and what services it provides, but also in how well the platform supports working with on-premises resources. Hybrid connection is a key decision driver to many companies who want to adopt cloud because it’s unrealistic for them to abandon whatever they have locally and migrate everything to cloud, given associated risk and cost. Furthermore, in some of the scenarios, such as managing automated production lines, migrating everything to cloud is simply infeasible as some devices have to be physically placed in local environments.

Microsoft Azure has been really strong in supporting hybrid scenarios. It provides not only connectivities at network level, but also various integration points at application level. The strong hybrid support provides Microsoft’s customers great flexibilities in their journey to the cloud. They can pick and chose the services that are most relevant to their businesses, and be assured that they can orchestrate these services with their on-premises resources to deliver continuous business solutions as they take steps to migrate to cloud. In this blog article, I’ll provide a brief survey of various technologies Microsoft Azure provides to enable different hybrid scenarios. Specially, I’ll cover the following scenarios:

Extend your local network into the cloud
Attach workstations (PC or Mac) to your virtual networks on cloud
Expose local services to cloud
Access on-premises resources from cloud
Bridge multiple networks

Instead of covering all the technical details, this blog focus mostly on scenarios themselves and links to external articles to provide detailed configuration steps. As there is a lot to talk about, let’s dive right in:

1. Extend your local network into the cloud

Microsoft Azure Virtual Network not only allows you to create a virtual network on cloud, but also allows you to connect the cloud-based virtual network to your on-premises network via a Site-to-Site or a Point-to-Site connection. To create a Site-to-Site VPN connection, you’ll need a public IPv4 address and a supported VPN device. You can also use Routing and Remote Access Service (RRAS) to replace the VPN device. The benefit of using Site-to-Site connection is that you only need to configure a VPN appliance (hardware or software) at the edge of your network, and all the computers located in your local network segment and in your virtual networks on cloud can communicate with each other as if they were on the same local network. For instance, you can join a virtual machine running on Azure to your local domain, or do the reverse by setting up a high-available AD on Azure and joining your local machines to it. The VPN connections use IPSec over the Internet. If you want higher speed, dedicated connections, you can also leverage Azure’s ExpressRoute to establish private connections directly to Azure.

2. Attach workstations (PC or Mac) to your virtual networks on cloud

Point-to-Site connections are perfect for you to attach your laptops or local computers to the virtual network on Azure for troubleshooting, debugging, testing, development, and commands & control. For a Windows-based PC, you can directly download a VPN client after you’ve configured your virtual network gateway and a certificate for authentication. For workstations that support only L2TP (such as Mac Book), you can set up a RRAS server (or similar servers such as OpenVPN Access Server) on your virtual network and then configure the VPN connection (see this article).

For a device that doesn’t support VPN connections, you’ll need to use Site-to-Site connection. And if Site-to-Site connections are unavailable, you can set up a local RRAS server. Both configurations require a public IP address. If you can’t acquire a public IP address, what you can do is to set up a Windows Server, join the server to your virtual network, and then use netsh to forward the traffic (more on this below).

3. Expose local services to cloud

Sometimes you need to expose a locally hosted services to cloud. A common challenge of implementing such scenario is addressing – these services don’t have public IP addresses, or even fixed IP addresses. How can we make these services accessible in this case? There are several options depends on your specific scenarios. First, at the most basic level, you can set up a Virtual Network to bridge the connection. If the service appliance doesn’t support VPN connections, you can also use a local Windows server to forward traffic using netsh:

netsh interface portproxy add v4tov4 listenport=[the port that the local server listens to] 
connectport=[port exposed to  the clients, can be the same as the server port] 
connectaddress=[local IP address of local server]

Second, if you are hosting a WCF service, you can use Service Bus Relay to acquire a relay endpoint, via which the clients can connect to your service over the Internet. Third, if you want to serve up a locally hosted service as a REST API, you can consider API Management, which provides transformation, throttling, authentication and many other features that help you to expose a legacy service as a RESTful API to the Internet.

4. Access on-premises resources from cloud

In additional to Virtual Network, you can also use Azure Hybrid Connection to connect to your local resources from your Azure Websites and Mobile Services. For example, you can access your locally hosted SQL Server, MySQL, Oracle databases, or other HTTP/HTTPS services from your Azure Website. What’s mentioned in section 3 also applies to this section as well.

5. Bridge multiple networks

Microsoft Azure also supports Multi-Site VPN, which allows you to connect multiple local networks together. This feature is especially useful when you need to integrate resources across multiple site locations. Furthermore, Azure allows you to connect different virtual networks together using the VNet to VNet Connection. These two features give you great flexibility to integrate and extend your networks as you fit and enable lots of cross-premise scenarios.

Conclusion

Microsoft Azure provides tons of options that help you to achieve a large number of hybrid scenarios at both networking level and application level. Only Microsoft Azure allows smooth transition and live collaboration among your local resources and your cloud-based resources. If you haven’t subscribed to Azure yet, you can start with a free trial subscription today!

Thank you for reading, and have a nice weekend!