Skip to content

Commit 15328e9

Browse files
author
Christoph Bühler
committed
docs(readme): add a propper readme
closes #11
1 parent 8d79237 commit 15328e9

File tree

1 file changed

+162
-0
lines changed

1 file changed

+162
-0
lines changed

‎README.md‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,163 @@
11
# dotnet operator sdk
2+
3+
This package (sadly DotnetOperatorSdk is already taken on nuget, so its "KubeOps")
4+
is a kubernetes operator sdk written in dotnet. It is heavily inspired by "kubebuilder"
5+
that provides the same and more functions for kubernetes operators in go.
6+
7+
The goal was to learn about resource watching in .net and provide a neat way of writing a
8+
custom operator yourself.
9+
10+
## How To Use
11+
12+
Using this sdk is pretty simple:
13+
14+
- Install the package
15+
- Map the main function
16+
- Write entities / controllers / finalizers
17+
- Go.
18+
19+
### Install the package
20+
21+
```bash
22+
dotnet add package KubeOps
23+
```
24+
25+
That's it.
26+
27+
### Map the main function
28+
29+
In your `Program.cs` file, map the main function to a kubernetes operator:
30+
31+
```csharp
32+
public static class Program
33+
{
34+
public static Task<int> Main(string[] args) =>
35+
new KubernetesOperator()
36+
.ConfigureServices(
37+
services =>
38+
{
39+
// add resource controllers here
40+
// add finalizers here
41+
})
42+
.Run(args);
43+
}
44+
```
45+
46+
This adds the default commands (like run and the code generators) to your app.
47+
48+
### Write Entities
49+
50+
A custom entity could be:
51+
52+
```csharp
53+
class FooSpec
54+
{
55+
public string? Test { get; set; }
56+
}
57+
58+
[KubernetesEntity(Group = "test", ApiVersion = "v1")]
59+
public class Foo : CustomKubernetesEntity<FooSpec>
60+
{
61+
}
62+
```
63+
64+
Now a CRD for your "Foo" class is generated on build.
65+
66+
### Write Controllers
67+
68+
```csharp
69+
[EntityRbac(typeof(ClusterDatabaseHost), Verbs = RbacVerb.All)]
70+
public class FooCtrl: ResourceControllerBase<Foo>
71+
{
72+
protected override async Task<TimeSpan?> Created(ClusterDatabaseHost resource){}
73+
// overwrite other methods here.
74+
}
75+
```
76+
77+
The entity rbac attribute does provide the information needed about
78+
your needed roles / rules.
79+
80+
If you return `null` in an event function, the event is not requeued.
81+
If you return a timespan, then the event is requeued after this delay.
82+
83+
If the function throws an error, the event is requeued with an exponential backoff.
84+
85+
The backoff function is defined as follows:
86+
87+
```csharp
88+
private const double MaxRetrySeconds = 64;
89+
private TimeSpan ExponentialBackoff(int retryCount) => TimeSpan
90+
.FromSeconds(Math.Min(Math.Pow(2, retryCount), MaxRetrySeconds))
91+
.Add(TimeSpan.FromMilliseconds(_rnd.Next(0, 1000)));
92+
```
93+
94+
### Write Finalizers
95+
96+
A finalizer can be as simple as:
97+
98+
```csharp
99+
public class FooFinalizer : ResourceFinalizerBase<Foo>
100+
{
101+
public override async Task Finalize(Foo resource)
102+
{
103+
// do something with the resource.
104+
}
105+
}
106+
```
107+
108+
And can be added to a resource with:
109+
110+
```csharp
111+
await resource.RegisterFinalizer<FooFinalizer, Foo>();
112+
```
113+
114+
After the finalizer ran successfully on a resource, it is unregistered
115+
on the resource.
116+
117+
## Commands
118+
119+
There are default command line commands which you can see when using
120+
`dotnet run -- --help` in your project. As you can see, you can run
121+
multiple commands. Some of them do install / uninstall your crds in
122+
your currently selected kubernetes cluster or can generate code.
123+
124+
## Code Generation
125+
126+
When installing this package, you also reference the default Targets and Props
127+
that come with the build engine. While building the following elements are generated:
128+
129+
- Dockerfile (if not already present)
130+
- CRDs for your custom entities
131+
- RBAC roles and role bindings for your requested resources
132+
- Deployment files for your operator
133+
- Installation file for your operator (kustomize)
134+
135+
The dockerfile will not be overwritten in case you have custom elements in there.
136+
The installation files won't be overwritten as well if you have custom elements in there.
137+
138+
To regenerate those two elements, just delete them and rebuild your code.
139+
140+
## Prop Settings
141+
142+
You can overwrite the default behaviour of the building parts with the following
143+
variables that you can add in a `<PropertyGroup>` in your `csproj` file:
144+
145+
| Property | Description | Default Value |
146+
| ---------------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
147+
| KubeOpsDockerfilePath | The path of the dockerfile | $(SolutionDir)Dockerfile<br>or<br>$(MSBuildProjectDirectory)\Dockerfile |
148+
| KubeOpsDockerTag | Which dotnet sdk / run tag should be used | latest |
149+
| KubeOpsConfigRoot | The base directory for generated elements | $(SolutionDir)config<br>or<br>$(MSBuildProjectDirectory)\config |
150+
| KubeOpsCrdDir | The directory for the generated crds | \$(KubeOpsConfigRoot)\crds |
151+
| KubeOpsCrdFormat | Output format for crds | Yaml |
152+
| KubeOpsCrdUseOldCrds | Use V1Beta version of crd instead of V1<br>(for kubernetes version < 1.16) | false |
153+
| KubeOpsRbacDir | Where to put the roles | \$(KubeOpsConfigRoot)\rbac |
154+
| KubeOpsRbacFormat | Output format for rbac | Yaml |
155+
| KubeOpsOperatorDir | Where to put operator related elements<br>(e.g. Deployment) | \$(KubeOpsConfigRoot)\operator |
156+
| KubeOpsOperatorFormat | Output format for the operator | Yaml |
157+
| KubeOpsInstallerDir | Where to put the installation files<br>(e.g. Namespace / Kustomization) | \$(KubeOpsConfigRoot)\install |
158+
| KubeOpsInstallerFormat | Output format for the installation files | Yaml |
159+
| KubeOpsSkipDockerfile | Skip dockerfile during build | "" |
160+
| KubeOpsSkipCrds | Skip crd generation during build | "" |
161+
| KubeOpsSkipRbac | Skip rbac generation during build | "" |
162+
| KubeOpsSkipOperator | Skip operator generation during build | "" |
163+
| KubeOpsSkipInstaller | Skip installer generation during build | "" |

0 commit comments

Comments
 (0)