Login

Introducing Project Tye

<div style="margin: 5px 5% 10px 5%;"><img src="https://www.sickgaming.net/blog/wp-content/uploads/2020/05/introducing-project-tye.jpg" width="150" height="150" title="" alt="" /></div><div><div class="row justify-content-center">
<div class="col-md-4">
<div><img src="https://www.sickgaming.net/blog/wp-content/uploads/2020/05/introducing-project-tye.jpg" width="58" height="58" alt="Amiee Lo" class="avatar avatar-58 wp-user-avatar wp-user-avatar-58 alignnone photo">
Amiee
</div>
</div>
</div>
<div class="entry-meta">
May 21st, 2020
</div>
 
<a href="https://github.com/dotnet/tye">Project Tye</a> is an experimental developer tool that makes developing, testing, and deploying microservices and distributed applications easier.
When building an app made up of multiple projects, you often want to run more than one at a time, such as a website that communicates with a backend API or several services all communicating with each other. Today, this can be difficult to setup and not as smooth as it could be, and it’s only the very first step in trying to get started with something like building out a distributed application. Once you have an inner-loop experience there is then a, sometimes steep, learning curve to get your distributed app onto a platform such as Kubernetes.
The project has two main goals:
<ol>
<li>Making development of microservices easier by:
<ul>
<li>Running many services with one command</li>
<li>Using dependencies in containers</li>
<li>Discovering addresses of other services using simple conventions</li>
</ul>
</li>
<li>Automating deployment of .NET applications to Kubernetes by:
<ul>
<li>Automatically containerizing .NET applications</li>
<li>Generating Kubernetes manifests with minimal knowledge or configuration</li>
<li>Using a single configuration file</li>
</ul>
</li>
</ol>
If you have an app that talks to a database, or an app that is made up of a couple of different processes that communicate with each other, then we think Tye will help ease some of the common pain points you’ve experienced.
We have recently demonstrated Tye in a few Build sessions that we encourage you to watch, <a href="https://aka.ms/Build2020AppDev-CloudNativeApps">Cloud Native Apps with .NET and AKS</a> and <a href="https://aka.ms/dotnetjourney">Journey to one .NET</a>
<h3>Installation</h3>
To get started with Tye, you will first need to have .<a href="https://dotnet.microsoft.com/download">NET Core 3.1</a> installed on your machine.
Tye can then be installed as a global tool using the following command:
<pre><code>dotnet tool install -g Microsoft.Tye --version "0.2.0-alpha.20258.3"
</code></pre>
<h3>Running a single service</h3>
Tye makes it very easy to run single applications. To demonstrate this:
1. Make a new folder called microservices and navigate to it:
<pre><code>mkdir microservices
cd microservices
</code></pre>
2. Then create a frontend project:
<pre><code>dotnet new razor -n frontend
</code></pre>
3. Now run this project using <code>tye run</code>:
<pre><code>tye run frontend
</code></pre>
<a href="https://www.sickgaming.net/blog/wp-content/uploads/2020/05/introducing-project-tye.png"> <img src="https://www.sickgaming.net/blog/wp-content/uploads/2020/05/introducing-project-tye.png" alt="Image tye run output" width="1995" height="431" class="alignnone size-full wp-image-23720"></a> The above displays how Tye is building, running, and monitoring the frontend application.
One key feature from <code>tye run</code> is a dashboard to view the state of your application. Navigate to <a href="http://localhost:8000">http://localhost:8000</a> to see the dashboard running.
<a href="https://www.sickgaming.net/blog/wp-content/uploads/2020/05/introducing-project-tye-1.png"> <img src="https://www.sickgaming.net/blog/wp-content/uploads/2020/05/introducing-project-tye-1.png" alt="Image tye dashboard" width="3239" height="1058" class="alignnone size-full wp-image-23723"></a>
The dashboard is the UI for Tye that displays a list of all of your services. The <code>Bindings</code> column has links to the listening URLs of the service. The <code>Logs</code> column allows you to view the streaming logs for the service.
<a href="https://www.sickgaming.net/blog/wp-content/uploads/2020/05/introducing-project-tye-2.png"> <img src="https://www.sickgaming.net/blog/wp-content/uploads/2020/05/introducing-project-tye-2.png" alt="Image tye logs" width="3240" height="967" class="alignnone size-full wp-image-23726"></a>
Services written using ASP.NET Core will have their listening ports assigned randomly if not explicitly configured. This is useful to avoid common issues like port conflicts.
<h3>Running multiple services</h3>
Instead of just a single application, suppose we have a multi-application scenario where our frontend project now needs to communicate with a backend project. If you haven’t already, stop the existing <code>tye run</code> command using <code>Ctrl + C</code>.
1. Create a backend API that the frontend will call inside of the <code>microservices/</code> folder.
<pre><code>dotnet new webapi -n backend
</code></pre>
2. Then create a solution file and add both projects:
<pre><code>dotnet new sln
dotnet sln add frontend backend
</code></pre>
You should now have a solution called <code>microservices.sln</code> that references the frontend and backend projects.
3. Run <code>tye</code> in the folder with the solution.
<pre><code>tye run
</code></pre>
The dashboard should show both the frontend and backend services. You can navigate to both of them through either the dashboard of the url outputted by tye run.
<blockquote>
The backend service in this example was created using the webapi project template and will return an HTTP 404 for its root URL.
</blockquote>
<h3>Getting the frontend to communicate with the backend</h3>
Now that we have two applications running, let’s make them communicate.
To get both of these applications communicating with each other, Tye utilizes service discovery. In general terms, service discovery describes the process by which one service figures out the address of another service. Tye uses environment variables for specifying connection strings and URIs of services.
The simplest way to use Tye’s service discovery is through the <code>Microsoft.Extensions.Configuration</code> system – available by default in ASP.NET Core or .NET Core Worker projects. In addition to this, we provide the <code>Microsoft.Tye.Extensions.Configuration</code> package with some Tye-specific extensions layered on top of the configuration system.
If you want to learn more about Tye’s philosophy on service discovery and see detailed usage examples, check out this <a href="https://github.com/dotnet/tye/blob/master/docs/reference/service_discovery.md">reference document</a>.
1. If you haven’t already, stop the existing <code>tye run</code> command using <code>Ctrl + C</code>. Open the solution in your editor of choice.
2. Add a file <code>WeatherForecast.cs</code> to the <code>frontend</code> project.
<pre><code>using System; namespace frontend { public class WeatherForecast { public DateTime Date { get; set; } public int TemperatureC { get; set; } public int TemperatureF => 32 + (int)(TemperatureC / 0.5556); public string Summary { get; set; } } }
</code></pre>
This will match the backend <code>WeatherForecast.cs</code>.
3. Add a file <code>WeatherClient.cs</code> to the <code>frontend</code> project with the following contents:
<pre><code>using System.Net.Http;
using System.Text.Json;
using System.Threading.Tasks; namespace frontend
{ public class WeatherClient { private readonly JsonSerializerOptions options = new JsonSerializerOptions() { PropertyNameCaseInsensitive = true, PropertyNamingPolicy = JsonNamingPolicy.CamelCase, }; private readonly HttpClient client; public WeatherClient(HttpClient client) { this.client = client; } public async Task<WeatherForecast[]> GetWeatherAsync() { var responseMessage = await this.client.GetAsync("/weatherforecast"); var stream = await responseMessage.Content.ReadAsStreamAsync(); return await JsonSerializer.DeserializeAsync<WeatherForecast[]>(stream, options); } }
}
</code></pre>
4. Add a reference to the <code>Microsoft.Tye.Extensions.Configuration</code> package to the frontend project
<pre><code>dotnet add frontend/frontend.csproj package Microsoft.Tye.Extensions.Configuration --version "0.2.0-*"
</code></pre>
5. Now register this client in <code>frontend</code> by adding the following to the existing <code>ConfigureServices</code> method to the existing <code>Startup.cs</code> file:
<pre><code>...
public void ConfigureServices(IServiceCollection services)
{ services.AddRazorPages(); /** Add the following to wire the client to the backend **/ services.AddHttpClient<WeatherClient>(client => { client.BaseAddress = Configuration.GetServiceUri("backend"); }); /** End added code **/
}
...
</code></pre>
This will wire up the <code>WeatherClient</code> to use the correct URL for the <code>backend</code> service.
6. Add a <code>Forecasts</code> property to the <code>Index</code> page model under <code>Pages\Index.cshtml.cs</code> in the <code>frontend</code> project.
<pre><code>... public WeatherForecast[] Forecasts { get; set; }
...
</code></pre>
7. Change the <code>OnGet</code> method to take the <code>WeatherClient</code> to call the <code>backend</code> service and store the result in the <code>Forecasts</code> property:
<pre><code>... public async Task OnGet([FromServices]WeatherClient client) { Forecasts = await client.GetWeatherAsync(); }
...
</code></pre>
8. Change the <code>Index.cshtml</code> razor view to render the <code>Forecasts</code> property in the razor page:
<pre><code>@page
@model IndexModel
@{ ViewData["Title"] = "Home page";
} <div class="text-center"> <h1 class="display-4">Welcome</h1> Learn about <a href="https://docs.microsoft.com/aspnet/core">building Web apps with ASP.NET Core</a>.
</div> Weather Forecast: <table class="table"> <thead> <tr> <th>Date</th> <th>Temp. ©</th> <th>Temp. (F)</th> <th>Summary</th> </tr> </thead> <tbody> @foreach (var forecast in @Model.Forecasts) { <tr> <td>@forecast.Date.ToShortDateString()</td> <td>@forecast.TemperatureC</td> <td>@forecast.TemperatureF</td> <td>@forecast.Summary</td> </tr> } </tbody>
</table>
</code></pre>
9. Run the project with <code>tye run</code> and the <code>frontend</code> service should be able to successfully call the <code>backend</code> service!
When you visit the <code>frontend</code> service you should see a table of weather data. This data was produced randomly in the <code>backend</code> service. The fact that you’re seeing it in a web UI in the <code>frontend</code> means that the services are able to communicate. Unfortunately, this doesn’t work out of the box on Linux right now due to how self-signed certificates are handled, please see the workaround <a href="https://github.com/dotnet/tye/blob/master/docs/tutorials/hello-tye/00_run_locally.md#troubleshooting">here</a>
<h3>Tye’s configuration schema</h3>
Tye has a optional configuration file (<code>tye.yaml</code>) to enable customizing settings. This file contains all of your projects and external dependencies. If you have an existing solution, Tye will automatically populate this with all of your current projects.
To initalize this file, you will need to run the following command in the <code>microservices</code> directory to generate a default <code>tye.yaml</code> file:
<pre><code>tye init
</code></pre>
The contents of the <code>tye.yaml</code> should look like this:
<a href="https://www.sickgaming.net/blog/wp-content/uploads/2020/05/introducing-project-tye-3.png"> <img src="https://www.sickgaming.net/blog/wp-content/uploads/2020/05/introducing-project-tye-3.png" alt="Image tye yaml" width="1025" height="393" class="alignnone size-full wp-image-23737"></a>
The top level scope (like the name node) is where global settings are applied.
<code>tye.yaml</code> lists all of the application’s services under the services node. This is the place for per-service configuration.
To learn more about Tye’s yaml specifications and schema, you can check it out <a href="https://github.com/dotnet/tye/blob/master/docs/reference/schema.md">here</a> in Tye’s repository on Github.
<blockquote>
We provide a json-schema for <code>tye.yaml</code> and some editors support json-schema for completion and validation of yaml files. See <a href="https://github.com/dotnet/tye/blob/master/src/schema/README.md">json-schema</a> for instructions.
</blockquote>
<h3>Adding external dependencies (Redis)</h3>
Not only does Tye make it easy to run and deploy your applications to Kubernetes, it’s also fairly simple to add external dependencies to your applications as well. We will now add redis to the frontend and backend application to store data.
Tye can use Docker to run images that run as part of your application. Make sure that <a href="https://docs.docker.com/get-docker/">Docker</a> is installed on your machine.
1. Change the <code>WeatherForecastController.Get()</code> method in the <code>backend</code> project to cache the weather information in redis using an <code>IDistributedCache</code>.
2. Add the following <code>using</code>‘s to the top of the file:
<pre><code>using Microsoft.Extensions.Caching.Distributed;
using System.Text.Json;
</code></pre>
3. Update <code>Get()</code>:
<pre><code>[HttpGet]
public async Task<string> Get([FromServices]IDistributedCache cache)
{ var weather = await cache.GetStringAsync("weather"); if (weather == null) { var rng = new Random(); var forecasts = Enumerable.Range(1, 5).Select(index => new WeatherForecast { Date = DateTime.Now.AddDays(index), TemperatureC = rng.Next(-20, 55), Summary = Summaries[rng.Next(Summaries.Length)] }) .ToArray(); weather = JsonSerializer.Serialize(forecasts); await cache.SetStringAsync("weather", weather, new DistributedCacheEntryOptions { AbsoluteExpirationRelativeToNow = TimeSpan.FromSeconds(5) }); } return weather;
}
</code></pre>
This will store the weather data in Redis with an expiration time of 5 seconds.
4. Add a package reference to <code>Microsoft.Extensions.Caching.StackExchangeRedis</code> in the backend project:
<pre><code>cd backend/
dotnet add package Microsoft.Extensions.Caching.StackExchangeRedis
cd ..
</code></pre>
5. Modify <code>Startup.ConfigureServices</code> in the <code>backend</code> project to add the redis <code>IDistributedCache</code> implementation.
<pre><code> public void ConfigureServices(IServiceCollection services) { services.AddControllers(); services.AddStackExchangeRedisCache(o => { o.Configuration = Configuration.GetConnectionString("redis"); }); }
</code></pre>
The above configures redis to the configuration string for the <code>redis</code> service injected by the <code>tye</code> host.
6. Modify <code>tye.yaml</code> to include redis as a dependency.
<pre><code>name: microservice
services:
- name: backend project: backend\backend.csproj
- name: frontend project: frontend\frontend.csproj
- name: redis image: redis bindings: - port: 6379 connectionString: "${host}:${port}"
- name: redis-cli image: redis args: "redis-cli -h redis MONITOR"
</code></pre>
We’ve added 2 services to the <code>tye.yaml</code> file. The <code>redis</code> service itself and a <code>redis-cli</code> service that we will use to watch the data being sent to and retrieved from redis.
<blockquote>
The <code>"${host}:${port}"</code> format in the <code>connectionString</code> property will substitute the values of the host and port number to produce a connection string that can be used with StackExchange.Redis.
</blockquote>
7. Run the <code>tye</code> command line in the solution root
<blockquote>
Make sure your command-line is in the <code>microservices/</code> directory. One of the previous steps had you change directories to edit a specific project.
</blockquote>
<pre><code>tye run
</code></pre>
Navigate to <a href="http://localhost:8000">http://localhost:8000</a> to see the dashboard running. Now you will see both <code>redis</code> and the <code>redis-cli</code> running listed in the dashboard.
Navigate to the <code>frontend</code> application and verify that the data returned is the same after refreshing the page multiple times. New content will be loaded every 5 seconds, so if you wait that long and refresh again, you should see new data. You can also look at the <code>redis-cli</code> logs using the dashboard and see what data is being cached in redis.
<blockquote>
The <code>"${host}:${port}"</code> format in the <code>connectionString</code> property will substitute the values of the host and port number to produce a connection string that can be used with StackExchange.Redis.
</blockquote>
<h3>Deploying to Kubernetes</h3>
Tye makes the process of deploying your application to Kubernetes very simple with minimal knowlege or configuration required.
<blockquote>
Tye will use your current credentials for pushing Docker images and accessing Kubernetes clusters. If you have configured kubectl with a context already, that’s what <a href="https://devblogs.microsoft.com/docs/reference/commandline/tye-deploy.md"><code>tye deploy</code></a> is going to use!
</blockquote>
Prior to deploying your application, make sure to have the following:
<ol>
<li><a href="https://www.docker.com/products/docker-desktop">Docker</a> installed based off on your operating system</li>
<li>A container registry. Docker by default will create a container registry on <a href="https://hub.docker.com/">DockerHub</a>. You could also use <a href="https://azure.microsoft.com/en-us/services/container-registry/">Azure Container Registry</a> (ACR) or another container registry of your choice.</li>
<li>A Kubernetes Cluster. There are many different options here, including:
</li>
</ol>
<blockquote>
If you choose a container registry provided by a cloud provider (other than Dockerhub), you will likely have to take some steps to configure your kubernetes cluster to allow access. Follow the instructions provided by your cloud provider.
</blockquote>
<h3>Deploying Redis</h3>
<code>tye deploy</code> will not deploy the redis configuration, so you need to deploy it first by running:
<pre><code>kubectl apply -f https://raw.githubusercontent.com/dotnet...redis.yaml
</code></pre>
This will create a deployment and service for redis.
<h3>Tye deploy</h3>
You can deploy your application by running the follow command:
<pre><code>tye deploy --interactive
</code></pre>
<blockquote>
Enter the Container Registry (ex: <code>example.azurecr.io</code> for Azure or <code>example</code> for dockerhub):
</blockquote>
You will be prompted to enter your container registry. This is needed to tag images, and to push them to a location accessible by kubernetes.
<a href="https://www.sickgaming.net/blog/wp-content/uploads/2020/05/introducing-project-tye-4.png"> <img src="https://www.sickgaming.net/blog/wp-content/uploads/2020/05/introducing-project-tye-4.png" alt="Image tye deploy output" width="1761" height="111" class="alignnone size-full wp-image-23743"></a>
If you are using dockerhub, the registry name will be your dockerhub username. If you are using a standalone container registry (for instance from your cloud provider), the registry name will look like a hostname, eg: <code>example.azurecr.io</code>.
You’ll also be prompted for the connection string for redis.
<a href="https://www.sickgaming.net/blog/wp-content/uploads/2020/05/introducing-project-tye-5.png"> <img src="https://www.sickgaming.net/blog/wp-content/uploads/2020/05/introducing-project-tye-5.png" alt="Image redis connection string" width="1214" height="95" class="alignnone size-full wp-image-23744"></a>
Enter the following to use the instance that you just deployed:
<pre><code>redis:6379
</code></pre>
<code>tye deploy</code> will create Kubernetes secret to store the connection string.
<blockquote>
–interactive is needed here to create the secret. This is a one-time configuration step. In a CI/CD scenario you would not want to have to specify connection strings over and over, deployment would rely on the existing configuration in the cluster.
</blockquote>
Tye uses Kubernetes secrets to store connection information about dependencies like redis that might live outside the cluster. Tye will automatically generate mappings between service names, binding names, and secret names.
<code>tye deploy</code> does many different things to deploy an application to Kubernetes. It will:
<ul>
<li>Create a docker image for each project in your application.</li>
<li>Push each docker image to your container registry.</li>
<li>Generate a Kubernetes <code>Deployment</code> and <code>Service</code> for each project.</li>
<li>Apply the generated <code>Deployment</code> and <code>Service</code> to your current Kubernetes context.</li>
</ul>
<a href="https://www.sickgaming.net/blog/wp-content/uploads/2020/05/introducing-project-tye-6.png"> <img src="https://www.sickgaming.net/blog/wp-content/uploads/2020/05/introducing-project-tye-6.png" alt="Image tye deploy building images" width="640" height="324" class="alignnone size-large wp-image-23745"></a>
You should now see three pods running after deploying.
<pre><code>kubectl get pods NAME READY STATUS RESTARTS AGE
backend-ccfcd756f-xk2q9 1/1 Running 0 85m
frontend-84bbdf4f7d-6r5zp 1/1 Running 0 85m
redis-5f554bd8bd-rv26p 1/1 Running 0 98m
</code></pre>
You can visit the frontend application, you will need to port-forward to access the frontend from outside the cluster.
<pre><code>kubectl port-forward svc/frontend 5000:80
</code></pre>
Now navigate to http://localhost:5000 to view the frontend application working on Kubernetes.
<a href="https://www.sickgaming.net/blog/wp-content/uploads/2020/05/introducing-project-tye-7.png"> <img src="https://www.sickgaming.net/blog/wp-content/uploads/2020/05/introducing-project-tye-7.png" alt="Image kubernetes portforward" width="665" height="227" class="alignnone size-full wp-image-23746"></a>
<blockquote>
Currently tye does not automatically enable TLS within the cluster, and so communication takes place over HTTP instead of HTTPS. This is typical way to deploy services in kubernetes – we may look to enable TLS as an option or by default in the future.
</blockquote>
<h3>Adding a registry to tye.yaml</h3>
If you want to use <code>tye deploy</code> as part of a CI/CD system, it’s expected that you’ll have a <code>tye.yaml</code> file initialized. You will then need to add a container registry to <code>tye.yaml</code>. Based on what container registry you configured, add the following line in the <code>tye.yaml</code> file:
<pre><code>registry: <registry_name>
</code></pre>
Now it’s possible to use <code>tye deploy</code> without <code>--interactive</code> since the registry is stored as part of configuration.
<blockquote>
This step may not make much sense if you’re using tye.yaml to store a personal Dockerhub username. A more typical use case would storing the name of a private registry for use in a CI/CD system.
</blockquote>
For a conceptual overview of how Tye behaves when using <code>tye deploy</code> for deployment, check out this <a href="https://github.com/dotnet/tye/blob/master/docs/reference/deployment.md">document</a>.
<h3>Undeploying your application</h3>
After deploying and playing around with the application, you may want to remove all resources associated from the Kubernetes cluster. You can remove resources by running:
<pre><code>tye undeploy
</code></pre>
This will remove all deployed resources. If you’d like to see what resources would be deleted, you can run:
<pre><code>tye undeploy --what-if
</code></pre>
If you want to experiment more with using Tye, we have a variety of different sample applications and tutorials that you can walk through, check them out down below:
We have been diligently working on adding new capabilities and integrations to continuously improve Tye. Here are some integrations below that we have recently released. There is also information provided on how to get started for each of these:
<ul>
<li><a href="https://github.com/dotnet/tye/blob/master/docs/recipes/ingress.md">Ingress</a> – to expose pods/services created to the public internet.</li>
<li><a href="https://github.com/dotnet/tye/blob/master/docs/tutorials/hello-tye/02_add_redis.md">Redis</a> – to store data, cache, or as a message broker.</li>
<li><a href="https://github.com/dotnet/tye/blob/master/docs/recipes/dapr.md">Dapr</a> – for integrating a Dapr application with Tye.</li>
<li><a href="https://github.com/dotnet/tye/blob/master/docs/recipes/distributed_tracing.md">Zipkin</a> – using Zipkin for distributed tracing. </li>
<li><a href="https://github.com/dotnet/tye/blob/master/docs/recipes/logging.md">Elastic Stack</a> – using Elastic Stack for logging.</li>
</ul>
While we are excited about the promise Tye holds, it’s an experimental project and not a committed product. During this experimental phase we expect to engage deeply with anyone trying out Tye to hear feedback and suggestions. The point of doing experiments in the open is to help us explore the space as much as we can and use what we learn to determine what we should be building and shipping in the future.
Project Tye is currently commited as an experiment until .NET 5 ships. At which point we will be evaluating what we have and all that we’ve learnt to decide what we should do in the future.
Our goal is to <a href="https://github.com/dotnet/tye/releases">ship every month</a>, and some new capabilities that we are looking into for Tye include:
<ul>
<li>More deployment targets</li>
<li>Sidecar support</li>
<li>Connected development</li>
<li>Database migrations</li>
</ul>
We are excited by the potential Tye has to make developing distributed applications easier and we need your feedback to make sure it reaches that potential. We’d really love for you to try it out and tell us what you think, there is a link to a survey on the Tye dashboard that you can fill out or you can create issues and talk to us on <a href="https://github.com/dotnet/tye">GitHub</a>. Either way we’d love to hear what you think.
</div>

https://www.sickgaming.net/blog/2020/05/...oject-tye/

xSicKxBot