Skip to content

Commit 7f8a82b

Browse files
galvesribeirogalvesribeiro
authored
Merge pull request #32 from galvesribeiro/update-readme
Update badges
2 parents 3efdec0 + 68fce93 commit 7f8a82b

File tree

3 files changed

+114
-100
lines changed

3 files changed

+114
-100
lines changed

‎.github/workflows/ci.yml

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,11 +11,16 @@ jobs:
1111

1212
steps:
1313
- uses: actions/checkout@v1
14+
# - uses: engineerd/[email protected]
15+
# with:
16+
# config: .github/workflows/kind.yml
17+
# - name: Setup Kube API
18+
# run: kubectl proxy &
1419
- name: Setup .NET Core
1520
uses: actions/setup-dotnet@v1
1621
with:
1722
dotnet-version: 3.1.100
1823
- name: Build
1924
run: dotnet build --configuration Release
20-
- name: Test
21-
run: dotnet test --configuration Release --no-build
25+
# - name: Test
26+
# run: dotnet test --configuration Release --no-build

‎.github/workflows/kind.yml

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
kind: Cluster
2+
apiVersion: kind.x-k8s.io/v1alpha4
3+
networking:
4+
# WARNING: It is _strongly_ recommended that you keep this the default
5+
# (127.0.0.1) for security reasons. However it is possible to change this.
6+
apiServerAddress: "127.0.0.1"
7+
# By default the API server listens on a random open port.
8+
# You may choose a specific port but probably don't need to in most cases.
9+
# Using a random port makes it easier to spin up multiple clusters.
10+
apiServerPort: 8001

‎README.md

Lines changed: 97 additions & 98 deletions
Original file line numberDiff line numberDiff line change
@@ -1,98 +1,97 @@
1-
<p align="center">
2-
<img src="https://github.com/dotnet/orleans/blob/gh-pages/assets/logo.png" alt="Orleans.Clustering.Kubernetes" width="300px">
3-
<h1>Orleans Clustering Provider for Kubernetes</h1>
4-
</p>
5-
6-
7-
[![CircleCI](https://circleci.com/gh/OrleansContrib/Orleans.Clustering.Kubernetes.svg?style=svg)](https://circleci.com/gh/OrleansContrib/Orleans.Clustering.Kubernetes)
8-
[![NuGet](https://img.shields.io/nuget/v/Orleans.Clustering.Kubernetes.svg?style=flat)](http://www.nuget.org/packages/Orleans.Clustering.Kubernetes)
9-
10-
[Orleans](https://github.com/dotnet/orleans) is a framework that provides a straight-forward approach to building distributed high-scale computing applications, without the need to learn and apply complex concurrency or other scaling patterns.
11-
12-
[Kubernetes](https://kubernetes.io/) (a.k.a. Kube or just K8s) is an open-source system for automating deployment, scaling, and management of containerized applications. In other words, it is one of the most popular container orchestrators out there.
13-
14-
**Orleans.Clustering.Kubernetes** is a package that use Kubernetes as a backend for Cluster Membership, making it easy to run Orleans clusters on top of Kubernetes.
15-
16-
# TL;DR
17-
18-
If you want to quickly test it, clone this repo and go to the [Samples Directory](https://github.com/OrleansContrib/Orleans.Clustering.Kubernetes/tree/master/samples) for instructions on how to run a sample cluster.
19-
20-
# Overview
21-
22-
Kubernetes has multiple ways to extend its API and one of those ways allow you to easily add custom data structures to it so it can be consumed later on by applications. Those objects are called _Custom Resources_ (CRD). The objects created based on CRDs are backed by the internal [etcd](https://coreos.com/etcd/) instance part of every Kubernetes deployment.
23-
24-
Two CRDs are created by this provider in order to store the Cluster Membership objects to comply with [Orleans Extended Cluster Membership Protocol](http://dotnet.github.io/orleans/Documentation/Runtime-Implementation-Details/Cluster-Management.html). `ClusterVersion` and `Silo`.
25-
26-
Those objects can be created at startup of the first silo in the cluster or, manually created by regular `.yaml` files. The package includes the two files with the required specs for each one. It may be useful for scenarios where the deployment is running under a very restricted Service Account, so you have to use them to create the CRDs upfront.
27-
28-
This provider uses only Kubernetes API Server to create/read those objects. By default, it uses the `In Cluster` API endpoint which is available on each `pod` but if required, can use whatever endpoint you specify at the provider options. This is useful if you want to rename the endpoint system DNS name or use a sidecar container that proxies all your requests to the real API server.
29-
30-
From the security perspective, the provider uses whatever `serviceaccount` configured for the Kubernetes Deployment object by reading the API credentials from the `pod` itself. In case you configured Kubernetes to not inject the credentials into the `pod`, you can always specify the CA certificate and API token along with the API endpoint at the provider options object.
31-
32-
# Installation
33-
34-
Installation is performed via [NuGet](https://www.nuget.org/packages?q=Orleans.Clustering.Kubernetes)
35-
36-
From Package Manager:
37-
38-
> PS> Install-Package Orleans.Clustering.Kubernetes -prerelease
39-
40-
.Net CLI:
41-
42-
> \# dotnet add package Orleans.Clustering.Kubernetes -prerelease
43-
44-
Paket:
45-
46-
> \# paket add Orleans.Clustering.Kubernetes -prerelease
47-
48-
# Configuration
49-
50-
A functional Kubernetes cluster is required for this provider to work. If you don't have one yet, there are multiple (and mostly complicated) ways to deploy Kubernetes for production use and it is out of scope of this provider as there are many articles around the web on how to do it. However, if you are playing with Docker and Kubernetes for the first time or you want to build a development box, [Scott Hanselman](https://github.com/shanselman) has [a nice article showing how to easily setup Docker for Windows with Kubernetes on your machine](https://www.hanselman.com/blog/HowToSetUpKubernetesOnWindows10WithDockerForWindowsAndRunASPNETCore.aspx). Although it shows Windows 10, it can be easily adopted to Mac OSX as well.
51-
52-
## Silo
53-
Tell Orleans runtime that we are going to use Kubernetes as our Cluster Membership Provider:
54-
55-
```cs
56-
var silo = new SiloHostBuilder()
57-
...
58-
.UseKubeMembership(opt =>
59-
{
60-
opt.CanCreateResources = true;
61-
})
62-
...
63-
.Build();
64-
```
65-
66-
The `CanCreateResources` will tell the provider to try create the CRDs at the startup time. In case it is set to false, you need to apply both `.yaml` files from the package before starting the silo. It must be done once per Kubernetes cluster.
67-
68-
## Client
69-
70-
Now that our silo is up and running, the Orleans client needs to connect to the Kubernetes to look for Orleans Gateways.
71-
72-
```cs
73-
var client = new ClientBuilder()
74-
...
75-
.UseKubeGatewayListProvider()
76-
...
77-
.Build();
78-
```
79-
80-
Both gateway list and the membership provider has other options that allow you to specify credentials and the API endpoint for your Kubernetes API server. The default will use everything discovered from the data injected from Kubernetes runtime into the `pod`.
81-
82-
Great! Now enjoy your Orleans application running within a Kubernetes cluster without needing an external membership provider!
83-
84-
# Security considerations
85-
86-
This provider behaves like any regular application being hosted on Kubernetes. That means it doesn't care about the underlying kubernetes security model. In this particular provider however, it _expects_ the pod to have access to the API server. Usually this access is granted to the service account being used by the POD (for more on that check Kubernetes docs for service accounts) by enabling RBAC or whatever other authorization plugin your cluster is using.
87-
88-
Regardless of the authorization plugin being used, ensure the following:
89-
90-
1. If `opt.CanCreateResources == true`, your service account must be able to create CRDs on Kubernetes API server.
91-
2. If `opt.CanCreateResources == false`, your service account won't try to create CRDs on your Kubernetes API server, so you should be fine for the majority of cases. However, like mentioned before, somehow (i.e. by using `kubectl`) you need to deploy the CRDs (included .yml files on this repo) before you run your Orleans application.
92-
3. Regardless of the value of `opt.CanCreateResources`, the service account _must_ have access to read and create objects (instances of the CRDs) on your Kubernetes API server at runtime using the Kubernetes API server endpoint created when you (regardless of how) deployed the CRDs to the cluster.
93-
94-
PS: If for whatever reason you are proxying the connection to the API server, make sure you set the API endpoint when registering this provider. That way, your proxy will be required to have access to Kubernetes API server. All the provider needs is to have access to the proxy endpoint.
95-
96-
# Contributions
97-
98-
PRs and feedback are **very** welcome! This repo follows the same contributions guideline as Orleans does and github issues will have `help-wanted` topics as they are coming.
1+
<p align="center">
2+
<img src="https://github.com/dotnet/orleans/blob/gh-pages/assets/logo.png" alt="Orleans.Clustering.Kubernetes" width="300px">
3+
<h1>Orleans Clustering Provider for Kubernetes</h1>
4+
</p>
5+
6+
[![CI](https://github.com/OrleansContrib/Orleans.Clustering.Kubernetes/workflows/CI/badge.svg)](https://github.com/OrleansContrib/Orleans.Clustering.Kubernetes/actions)
7+
[![NuGet](https://img.shields.io/nuget/v/Orleans.Clustering.Kubernetes.svg?style=flat)](http://www.nuget.org/packages/Orleans.Clustering.Kubernetes)
8+
9+
[Orleans](https://github.com/dotnet/orleans) is a framework that provides a straight-forward approach to building distributed high-scale computing applications, without the need to learn and apply complex concurrency or other scaling patterns.
10+
11+
[Kubernetes](https://kubernetes.io/) (a.k.a. Kube or just K8s) is an open-source system for automating deployment, scaling, and management of containerized applications. In other words, it is one of the most popular container orchestrators out there.
12+
13+
**Orleans.Clustering.Kubernetes** is a package that use Kubernetes as a backend for Cluster Membership, making it easy to run Orleans clusters on top of Kubernetes.
14+
15+
# TL;DR
16+
17+
If you want to quickly test it, clone this repo and go to the [Samples Directory](https://github.com/OrleansContrib/Orleans.Clustering.Kubernetes/tree/master/samples) for instructions on how to run a sample cluster.
18+
19+
# Overview
20+
21+
Kubernetes has multiple ways to extend its API and one of those ways allow you to easily add custom data structures to it so it can be consumed later on by applications. Those objects are called _Custom Resources_ (CRD). The objects created based on CRDs are backed by the internal [etcd](https://coreos.com/etcd/) instance part of every Kubernetes deployment.
22+
23+
Two CRDs are created by this provider in order to store the Cluster Membership objects to comply with [Orleans Extended Cluster Membership Protocol](http://dotnet.github.io/orleans/Documentation/Runtime-Implementation-Details/Cluster-Management.html). `ClusterVersion` and `Silo`.
24+
25+
Those objects can be created at startup of the first silo in the cluster or, manually created by regular `.yaml` files. The package includes the two files with the required specs for each one. It may be useful for scenarios where the deployment is running under a very restricted Service Account, so you have to use them to create the CRDs upfront.
26+
27+
This provider uses only Kubernetes API Server to create/read those objects. By default, it uses the `In Cluster` API endpoint which is available on each `pod` but if required, can use whatever endpoint you specify at the provider options. This is useful if you want to rename the endpoint system DNS name or use a sidecar container that proxies all your requests to the real API server.
28+
29+
From the security perspective, the provider uses whatever `serviceaccount` configured for the Kubernetes Deployment object by reading the API credentials from the `pod` itself. In case you configured Kubernetes to not inject the credentials into the `pod`, you can always specify the CA certificate and API token along with the API endpoint at the provider options object.
30+
31+
# Installation
32+
33+
Installation is performed via [NuGet](https://www.nuget.org/packages?q=Orleans.Clustering.Kubernetes)
34+
35+
From Package Manager:
36+
37+
> PS> Install-Package Orleans.Clustering.Kubernetes -prerelease
38+
39+
.Net CLI:
40+
41+
> \# dotnet add package Orleans.Clustering.Kubernetes -prerelease
42+
43+
Paket:
44+
45+
> \# paket add Orleans.Clustering.Kubernetes -prerelease
46+
47+
# Configuration
48+
49+
A functional Kubernetes cluster is required for this provider to work. If you don't have one yet, there are multiple (and mostly complicated) ways to deploy Kubernetes for production use and it is out of scope of this provider as there are many articles around the web on how to do it. However, if you are playing with Docker and Kubernetes for the first time or you want to build a development box, [Scott Hanselman](https://github.com/shanselman) has [a nice article showing how to easily setup Docker for Windows with Kubernetes on your machine](https://www.hanselman.com/blog/HowToSetUpKubernetesOnWindows10WithDockerForWindowsAndRunASPNETCore.aspx). Although it shows Windows 10, it can be easily adopted to Mac OSX as well.
50+
51+
## Silo
52+
Tell Orleans runtime that we are going to use Kubernetes as our Cluster Membership Provider:
53+
54+
```cs
55+
var silo = new SiloHostBuilder()
56+
...
57+
.UseKubeMembership(opt =>
58+
{
59+
opt.CanCreateResources = true;
60+
})
61+
...
62+
.Build();
63+
```
64+
65+
The `CanCreateResources` will tell the provider to try create the CRDs at the startup time. In case it is set to false, you need to apply both `.yaml` files from the package before starting the silo. It must be done once per Kubernetes cluster.
66+
67+
## Client
68+
69+
Now that our silo is up and running, the Orleans client needs to connect to the Kubernetes to look for Orleans Gateways.
70+
71+
```cs
72+
var client = new ClientBuilder()
73+
...
74+
.UseKubeGatewayListProvider()
75+
...
76+
.Build();
77+
```
78+
79+
Both gateway list and the membership provider has other options that allow you to specify credentials and the API endpoint for your Kubernetes API server. The default will use everything discovered from the data injected from Kubernetes runtime into the `pod`.
80+
81+
Great! Now enjoy your Orleans application running within a Kubernetes cluster without needing an external membership provider!
82+
83+
# Security considerations
84+
85+
This provider behaves like any regular application being hosted on Kubernetes. That means it doesn't care about the underlying kubernetes security model. In this particular provider however, it _expects_ the pod to have access to the API server. Usually this access is granted to the service account being used by the POD (for more on that check Kubernetes docs for service accounts) by enabling RBAC or whatever other authorization plugin your cluster is using.
86+
87+
Regardless of the authorization plugin being used, ensure the following:
88+
89+
1. If `opt.CanCreateResources == true`, your service account must be able to create CRDs on Kubernetes API server.
90+
2. If `opt.CanCreateResources == false`, your service account won't try to create CRDs on your Kubernetes API server, so you should be fine for the majority of cases. However, like mentioned before, somehow (i.e. by using `kubectl`) you need to deploy the CRDs (included .yml files on this repo) before you run your Orleans application.
91+
3. Regardless of the value of `opt.CanCreateResources`, the service account _must_ have access to read and create objects (instances of the CRDs) on your Kubernetes API server at runtime using the Kubernetes API server endpoint created when you (regardless of how) deployed the CRDs to the cluster.
92+
93+
PS: If for whatever reason you are proxying the connection to the API server, make sure you set the API endpoint when registering this provider. That way, your proxy will be required to have access to Kubernetes API server. All the provider needs is to have access to the proxy endpoint.
94+
95+
# Contributions
96+
97+
PRs and feedback are **very** welcome! This repo follows the same contributions guideline as Orleans does and github issues will have `help-wanted` topics as they are coming.

0 commit comments

Comments
 (0)