From db19d627ba851ef4b56e1d63291096ba81988809 Mon Sep 17 00:00:00 2001 From: Rahee Ghosh Date: Wed, 12 Dec 2018 23:59:34 -0800 Subject: [PATCH 1/8] Update README.md --- README.md | 44 ++++++++++++++++++++++---------------------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 583894d..2c7a6cb 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,9 @@ -Ambrosia: Highly Robust Distributed Programming Made Easy and Efficient +Ambrosia: Robust Distributed Programming Made Easy and Efficient ======================================================================= - * Windows Build (net46/netcore) [![Windows Build Status](https://msrfranklin.visualstudio.com/Franklin/_apis/build/status/Ambrosia-CI-Win-Scripted?branchName=master)](https://msrfranklin.visualstudio.com/Franklin/_build/latest?definitionId=23) + * Windows Build (net46/netcore): [![Windows Build Status](https://msrfranklin.visualstudio.com/Franklin/_apis/build/status/Ambrosia-CI-Win-Scripted?branchName=master)](https://msrfranklin.visualstudio.com/Franklin/_build/latest?definitionId=23) - * Linux Build (netcore) [![Linux Build Status](https://msrfranklin.visualstudio.com/Franklin/_apis/build/status/Ambrosia-CI-Linux-Scripted?branchName=master)](https://msrfranklin.visualstudio.com/Franklin/_build/latest?definitionId=24) + * Linux Build (netcore): [![Linux Build Status](https://msrfranklin.visualstudio.com/Franklin/_apis/build/status/Ambrosia-CI-Linux-Scripted?branchName=master)](https://msrfranklin.visualstudio.com/Franklin/_build/latest?definitionId=24) * Linux Docker Build: [![Linux Docker Build status](https://msrfranklin.visualstudio.com/Franklin/_apis/build/status/Ambrosia-CI-Linux-Docker?branchName=master)](https://msrfranklin.visualstudio.com/Franklin/_build/latest?definitionId=18) @@ -30,17 +30,19 @@ systems, or use overly expensive mechanisms. To learn more about Ambrosia's implementation and performance you can read our [whitepaper](https://www.microsoft.com/en-us/research/publication/a-m-b-r-o-s-i-a-providing-performant-virtual-resiliency-for-distributed-applications/). +We invite developers wishing to build on or contribute to AMBROSIA to join our [gitter community](https://gitter.im/AMBROSIA-resilient-systems/Lobby?utm_source=share-link&utm_medium=link&utm_campaign=share-link). + Table of Contents ----------- * [AMBROSIA Concepts](#ambrosia-concepts) * [How it works](#how-it-works) * [Features](#features) -* [Getting started]() - * [Windows]() - * [Kubernetes]() +* [Quick start for application developers](#quick-start-for-application-developers) +* [Quick start for AMBROSIA contributors](#quick-start-for-ambrosia-contributors) * [Reference](#reference) - * [Language Support](#language-support) + * [Language support](#language-support) * [Usage](#usage) + * [Secure communication between services](#secure-communication-between-services) ## AMBROSIA Concepts @@ -65,22 +67,20 @@ In addition, the language specific AMBROSIA binding provides a state serializer. ## Features Here is a list of features that AMBROSIA provides to application developers and deployers: -* Register Instance, Add Replica -* Debug Instance +* Define a new service to run on AMBROSIA +* Deploy services on AMBROSIA +* Debug service instance * Active Active * Live Upgrades, Test Upgrades * RPC -* Asynchronous RPC (beta) +* Asynchronous RPC (alpha) -Quick Start: Fetch a binary distribution ----------------------------------------- +## Quick start for application developers +Start with one of our [samples](https://github.com/Microsoft/AMBROSIA/tree/master/Samples) to get a service up and running on AMBROSIA. -FINISHME - - - -Quick Start: Build from Source ------------------------------- +## Quick start for AMBROSIA contributors +### Build from source Build the Ambrosia Immortal coordinator and C# client code generator with this Bash script: @@ -90,10 +90,7 @@ Given a .NET Core SDK, this will work on Windows, Mac OS, or Linux. After that, you have an AMBROSIA binary distribution built inside the `./bin` directory within your working copy. -Running a Sample ----------------- - -FINISHME - AmbrosiaDocs.md content will move here!! +Also check out our [contributing guide](https://github.com/Microsoft/AMBROSIA/tree/master/CONTRIBUTING). ## Reference @@ -155,4 +152,7 @@ Options: The version # to debug. --tu, --testingUpgrade Is testing upgrade. -h, --help show this message and exit -``` \ No newline at end of file +``` + +### Secure communication between services +Read about how to secure communications between distributed components deployed on AMBROSIA [here](https://github.com/Microsoft/AMBROSIA/blob/master/docs/SecuringComms.md). From f4de652a122f765c3a5bc184bba8ab9f2e107813 Mon Sep 17 00:00:00 2001 From: Rahee Ghosh Date: Thu, 13 Dec 2018 00:01:29 -0800 Subject: [PATCH 2/8] Delete AmbrosiaDocs.md --- docs/AmbrosiaDocs.md | 152 ------------------------------------------- 1 file changed, 152 deletions(-) delete mode 100644 docs/AmbrosiaDocs.md diff --git a/docs/AmbrosiaDocs.md b/docs/AmbrosiaDocs.md deleted file mode 100644 index 592d2a3..0000000 --- a/docs/AmbrosiaDocs.md +++ /dev/null @@ -1,152 +0,0 @@ -# AMBROSIA Documentation -## Concepts -What is Ambrosia? What guarantees does it provide? - -### Immortals -The basic building blocks of AMBROSIA are *Immortals*, reliable distributed -objects that communicate through RPCs. An Immortal defines a set of persistent -state and a set of RPC handlers that operate on that state. An *instance* of an -Immortal is a named entity that maintains state and executes RPC handlers -according to the Immortal's definition. An AMBROSIA application often has -multiple instances of the same Immortal; for example, an application may define -a single "job" Immortal for running a data-processing job and run multiple -instances of that job operating on different data sets. - -### Architecture -The figure below outlines the basic architecture of an AMBROSIA application. -Each box in the figure represents a separate process. Each instance of an -Immortal exists as a software object and thread of control running inside of -an application process. An Immortal instance communicates with other Immortal -instances through an *Immortal Coordinator* process, which durably logs the -instance's RPCs and encapsulates the low-level networking required to send -RPCs. - - ---------------------- ---------------------- - | | | | - | Immortal coordinator |<=========>| Immortal coordinator | - | | | | - ---------------------- ---------------------- - || || - || || - || || - ---------------------- ---------------------- - | | | | - | Immortal instance | | Immortal instance | - | | | | - ---------------------- ---------------------- - -## Requirements/Platforms supported for development and deployment - -FINISHME - - -## Setup -How to get set up to use Ambrosia - -## Compiling and running a "Hello World" Ambrosia application -This section describes how to compile and run a simple Ambrosia application -on .NET Core using the HelloWorld sample project as an example. - -For the purpose of this tutorial, we'll assume the following parameters: - -* Log directory: C:\logs\ -* Client instance name: client1 -* Client ImmortalCoordinator receive port: 1000 -* Client ImmortalCoordinator send port: 1001 -* Client ImmortalCoordinator CRA port: 1500 -* Server instance name: server1 -* Server ImmortalCoordinator receive port: 2000 -* Server ImmortalCoordinator send port: 2001 -* Server ImmortalCoordinator CRA port: 2500 - -When running the commands below, replace `$AMBROSIA` with the directory -containing the Ambrosia executables, and replace `$HELLO_WORLD` with the -directory containing the HelloWorld solution. - -### Compiling the application -To compile HelloWorld, open `HelloWorld.sln` in Visual Studio. Set the build -configuration to `Debug` and the platform to `x64`, and build the solution. - -### Registering the Immortal instances -Before running the application, you need to register each Immortal instance -so that other Immortal instances can find them. You'll do so using the -`Ambrosia` executable. Open a command prompt and enter the following commands. - - cd $AMBROSIA - dotnet .\Ambrosia.dll RegisterInstance -i=client1 -rp=1000 -sp=1001 -l=C:\logs\ - dotnet .\Ambrosia.dll RegisterInstance -i=server1 -rp=2000 -sp=2001 -l=C:\logs\ - -### Running the application -To run the HelloWorld application, you will need to run four command-line -processes, each in a separate window: the HelloWorld client Immortal, the -HelloWorld server Immortal, and two ImmortalCoordinator processes, one for -each Immortal. - -To run the client ImmortalCoordinator, open a command prompt and enter these -commands: - - cd $AMBROSIA - dotnet ImmortalCoordinator.dll --instanceName=client1 --port=1500 - -To run the server ImmortalCoordinator: - - cd $AMBROSIA - dotnet ImmortalCoordinator.dll --instanceName=server1 --port=2500 - -To run the HelloWorld client: - - cd $HELLO_WORLD\Client1\bin\x64\Debug\netcoreapp2.0 - dotnet Client1.dll - -To run the HelloWorld server: - - cd $HELLO_WORLD\Server\bin\x64\Debug\netcoreapp2.0 - dotnet Server.dll - -After starting all four processes, you should see your client and server -communicate with each other! - -### Code generation -The HelloWorld sample contains generated proxy and dispatcher classes for each -of its Immortals that were created by the Ambrosia code generation tool, -`AmbrosiaCS`. If you change an Immortal's public interface (e.g., adding -parameters to `IServer.ReceiveMessage()`), you will need to re-run the code -generation tool to update the generated source files. The sample's root -directory contains a PowerShell script to automate the process of invoking -`AmbrosiaCS`. To run code generation, first build any projects containing -updated Immortal interfaces (in this example, the `ServerAPI` project). Then -open a PowerShell prompt and enter the following commands: - - cd $HELLO_WORLD - .\Generate-Assemblies-NetCore.ps1 - -## Developing with Ambrosia -FINISHME - - -small snippet example of how to send messages through ambrosia -how to handle impulses -recovery, active active -live service upgrades -time travel debugging how to -portability - -## Deployment of services built on Ambrosia -FINISHME - Windows, Linux - -## Best Practices -FINISHME - how to ensure you get all the guarantees that Ambrosia provides - -## Examples - -FINISHME - -Brief description of each example and what it demonstrates -instructions for cloning/downloading and modifying examples - -## References -FINISHME - configurations, command line options, parameters - -## Roadmap - -FINISHME - -planned future features -other language support -support non-Azure storage From 4d6565c97d8cd826413558c9797ff2cb4368893a Mon Sep 17 00:00:00 2001 From: Rahee Ghosh Date: Thu, 13 Dec 2018 00:09:37 -0800 Subject: [PATCH 3/8] Create README.md --- Samples/README.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 Samples/README.md diff --git a/Samples/README.md b/Samples/README.md new file mode 100644 index 0000000..705d318 --- /dev/null +++ b/Samples/README.md @@ -0,0 +1,5 @@ +# AMBROSIA Samples + +1. Hello World - a simple example demonstrating a client and a server (both running on AMBROSIA) communicating, with two different client options. +2. Streaming Demo - an example showing how to use AMBROSIA in conjunction with [Trill](https://github.com/Microsoft/Trill), a query processor for streaming data. +3. AKS Scripts - instructions and scripts for getting AMBROSIA running on Azure Kubernetes Service. From 4dda57f69b2dc307e3a75052429ac6621c101aeb Mon Sep 17 00:00:00 2001 From: Rahee Ghosh Date: Thu, 13 Dec 2018 00:13:37 -0800 Subject: [PATCH 4/8] Update README.md --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index 2c7a6cb..dc42c91 100644 --- a/README.md +++ b/README.md @@ -40,6 +40,7 @@ Table of Contents * [Quick start for application developers](#quick-start-for-application-developers) * [Quick start for AMBROSIA contributors](#quick-start-for-ambrosia-contributors) * [Reference](#reference) + * [Dependencies](#dependecies) * [Language support](#language-support) * [Usage](#usage) * [Secure communication between services](#secure-communication-between-services) @@ -94,6 +95,9 @@ Also check out our [contributing guide](https://github.com/Microsoft/AMBROSIA/tr ## Reference +### Dependencies +AMBROSIA currently requires an Azure subscription to write it's logs to replicated storage. In the future, we anticipate abstracting to component out to be able to use other storage options for logs. + ### Language Support AMBROSIA currently supports C# on both .NET Core and .NET Framework. We plan to exand this support with AMBROSIA bindings for other languages in the future. From 5714ae8fd8ccc629322e6dcd73bc245153c71da0 Mon Sep 17 00:00:00 2001 From: Rahee Ghosh Date: Thu, 13 Dec 2018 00:17:14 -0800 Subject: [PATCH 5/8] typo --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index dc42c91..7e8e361 100644 --- a/README.md +++ b/README.md @@ -96,7 +96,7 @@ Also check out our [contributing guide](https://github.com/Microsoft/AMBROSIA/tr ## Reference ### Dependencies -AMBROSIA currently requires an Azure subscription to write it's logs to replicated storage. In the future, we anticipate abstracting to component out to be able to use other storage options for logs. +AMBROSIA currently requires an Azure subscription to write it's logs to replicated storage. In the future, we anticipate abstracting this component out to be able to use other storage options for logs. ### Language Support AMBROSIA currently supports C# on both .NET Core and .NET Framework. We plan to exand this support with AMBROSIA bindings for other languages in the future. From e0998df7173d0e9139caf4f41c61f121f2431da7 Mon Sep 17 00:00:00 2001 From: Rahee Ghosh Date: Thu, 13 Dec 2018 00:18:24 -0800 Subject: [PATCH 6/8] Update README.md --- CONTRIBUTING/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CONTRIBUTING/README.md b/CONTRIBUTING/README.md index adb31a4..ea876f3 100644 --- a/CONTRIBUTING/README.md +++ b/CONTRIBUTING/README.md @@ -7,6 +7,8 @@ For developers interested in adding to AMBROSIA, or developing new [language-level or RPC-framework bindings to AMBROSIA](#new-client-bindings), this document provides a few pointers. +We invite developers wishing to build on or contribute to AMBROSIA to join our [gitter community](https://gitter.im/AMBROSIA-resilient-systems/Lobby?utm_source=share-link&utm_medium=link&utm_campaign=share-link). + Overview of repository ---------------------- From 65f9d0774e2b02150197ba735cf029aced4c24a8 Mon Sep 17 00:00:00 2001 From: Rahee Ghosh Date: Thu, 13 Dec 2018 00:24:37 -0800 Subject: [PATCH 7/8] Update README.md --- Samples/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Samples/README.md b/Samples/README.md index 705d318..73e041b 100644 --- a/Samples/README.md +++ b/Samples/README.md @@ -3,3 +3,5 @@ 1. Hello World - a simple example demonstrating a client and a server (both running on AMBROSIA) communicating, with two different client options. 2. Streaming Demo - an example showing how to use AMBROSIA in conjunction with [Trill](https://github.com/Microsoft/Trill), a query processor for streaming data. 3. AKS Scripts - instructions and scripts for getting AMBROSIA running on Azure Kubernetes Service. + +Have any questions? Come join our [gitter community](https://gitter.im/AMBROSIA-resilient-systems/Lobby?utm_source=share-link&utm_medium=link&utm_campaign=share-link) or create a github issue. From fc96d9f0d858ae6aaccd403727b6f495bfac71ec Mon Sep 17 00:00:00 2001 From: Rahee Ghosh Date: Thu, 13 Dec 2018 00:32:18 -0800 Subject: [PATCH 8/8] Update README.md --- README.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 7e8e361..c15818b 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,13 @@ Ambrosia: Robust Distributed Programming Made Easy and Efficient ======================================================================= - * Windows Build (net46/netcore): [![Windows Build Status](https://msrfranklin.visualstudio.com/Franklin/_apis/build/status/Ambrosia-CI-Win-Scripted?branchName=master)](https://msrfranklin.visualstudio.com/Franklin/_build/latest?definitionId=23) +Windows Build (net46/netcore): [![Windows Build Status](https://msrfranklin.visualstudio.com/Franklin/_apis/build/status/Ambrosia-CI-Win-Scripted?branchName=master)](https://msrfranklin.visualstudio.com/Franklin/_build/latest?definitionId=23) - * Linux Build (netcore): [![Linux Build Status](https://msrfranklin.visualstudio.com/Franklin/_apis/build/status/Ambrosia-CI-Linux-Scripted?branchName=master)](https://msrfranklin.visualstudio.com/Franklin/_build/latest?definitionId=24) +Linux Build (netcore): [![Linux Build Status](https://msrfranklin.visualstudio.com/Franklin/_apis/build/status/Ambrosia-CI-Linux-Scripted?branchName=master)](https://msrfranklin.visualstudio.com/Franklin/_build/latest?definitionId=24) - * Linux Docker Build: [![Linux Docker Build status](https://msrfranklin.visualstudio.com/Franklin/_apis/build/status/Ambrosia-CI-Linux-Docker?branchName=master)](https://msrfranklin.visualstudio.com/Franklin/_build/latest?definitionId=18) +Linux Docker Build: [![Linux Docker Build status](https://msrfranklin.visualstudio.com/Franklin/_apis/build/status/Ambrosia-CI-Linux-Docker?branchName=master)](https://msrfranklin.visualstudio.com/Franklin/_build/latest?definitionId=18) + + [![Gitter](https://img.shields.io/badge/chat-on%20gitter-yellow.svg)](https://gitter.im/AMBROSIA-resilient-systems/) Ambrosia is a programming language independent approach for authoring