зеркало из https://github.com/microsoft/AMBROSIA.git
Merge branch 'master' of github.com:Microsoft/AMBROSIA l
This commit is contained in:
Ryan Newton
Коммит
acd330fd5e
|
|
@ -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
|
||||
----------------------
|
||||
|
||||
|
|
|
|||
52
README.md
52
README.md
|
|
@ -1,11 +1,13 @@
|
|||
Ambrosia: Highly Robust Distributed Programming Made Easy and Efficient
|
||||
Ambrosia: Robust Distributed Programming Made Easy and Efficient
|
||||
=======================================================================
|
||||
|
||||
* Windows Build (net46/netcore) [](https://msrfranklin.visualstudio.com/Franklin/_build/latest?definitionId=23)
|
||||
Windows Build (net46/netcore): [](https://msrfranklin.visualstudio.com/Franklin/_build/latest?definitionId=23)
|
||||
|
||||
* Linux Build (netcore) [](https://msrfranklin.visualstudio.com/Franklin/_build/latest?definitionId=24)
|
||||
Linux Build (netcore): [](https://msrfranklin.visualstudio.com/Franklin/_build/latest?definitionId=24)
|
||||
|
||||
* Linux Docker Build: [](https://msrfranklin.visualstudio.com/Franklin/_build/latest?definitionId=18)
|
||||
Linux Docker Build: [](https://msrfranklin.visualstudio.com/Franklin/_build/latest?definitionId=18)
|
||||
|
||||
[](https://gitter.im/AMBROSIA-resilient-systems/)
|
||||
|
||||
|
||||
Ambrosia is a programming language independent approach for authoring
|
||||
|
|
@ -30,17 +32,20 @@ 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)
|
||||
* [Dependencies](#dependecies)
|
||||
* [Language support](#language-support)
|
||||
* [Usage](#usage)
|
||||
* [Secure communication between services](#secure-communication-between-services)
|
||||
|
||||
## AMBROSIA Concepts
|
||||
|
||||
|
|
@ -65,22 +70,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,13 +93,13 @@ 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
|
||||
|
||||
### Dependencies
|
||||
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.
|
||||
|
||||
|
|
@ -155,4 +158,7 @@ Options:
|
|||
The version # to debug.
|
||||
--tu, --testingUpgrade Is testing upgrade.
|
||||
-h, --help show this message and exit
|
||||
```
|
||||
```
|
||||
|
||||
### 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).
|
||||
|
|
|
|||
|
|
@ -0,0 +1,7 @@
|
|||
# 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.
|
||||
|
||||
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.
|
||||
|
|
@ -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
|
||||
Загрузка…
Ссылка в новой задаче