KubeOps.Operator.Web
9.1.4
See the version list below for details.
dotnet add package KubeOps.Operator.Web --version 9.1.4
NuGet\Install-Package KubeOps.Operator.Web -Version 9.1.4
<PackageReference Include="KubeOps.Operator.Web" Version="9.1.4" />
paket add KubeOps.Operator.Web --version 9.1.4
#r "nuget: KubeOps.Operator.Web, 9.1.4"
// Install KubeOps.Operator.Web as a Cake Addin #addin nuget:?package=KubeOps.Operator.Web&version=9.1.4 // Install KubeOps.Operator.Web as a Cake Tool #tool nuget:?package=KubeOps.Operator.Web&version=9.1.4
KubeOps Operator Web
The KubeOps Operator Web package provides a webserver to enable webhooks for your Kubernetes operator.
Usage
To enable webhooks and external access to your operator, you need to
use ASP.net. The project file needs to reference Microsoft.NET.Sdk.Web
instead of Microsoft.NET.Sdk
and the Program.cs
needs to be changed.
To allow webhooks, the MVC controllers need to be registered and mapped.
The basic Program.cs
setup looks like this:
using KubeOps.Operator;
var builder = WebApplication.CreateBuilder(args);
builder.Services
.AddKubernetesOperator()
.RegisterComponents();
builder.Services
.AddControllers();
var app = builder.Build();
app.UseRouting();
app.MapControllers();
await app.RunAsync();
Note the .AddControllers
and .MapControllers
call.
Without them, your webhooks will not be reachable.
Validation Hooks
To create a validation webhook, first create a new class
that implements the ValidationWebhook<T>
base class.
Then decorate the webhook with the ValidationWebhookAttribute
to set the route correctly.
After that setup, you may overwrite any of the following methods:
- Create
- CreateAsync
- Update
- UpdateAsync
- Delete
- DeleteAsync
The async methods take precedence over the sync methods.
An example of such a validation webhook looks like:
[ValidationWebhook(typeof(V1TestEntity))]
public class TestValidationWebhook : ValidationWebhook<V1TestEntity>
{
public override ValidationResult Create(V1TestEntity entity, bool dryRun)
{
if (entity.Spec.Username == "forbidden")
{
return Fail("name may not be 'forbidden'.", 422);
}
return Success();
}
public override ValidationResult Update(V1TestEntity oldEntity, V1TestEntity newEntity, bool dryRun)
{
if (newEntity.Spec.Username == "forbidden")
{
return Fail("name may not be 'forbidden'.");
}
return Success();
}
}
To create the validation results, use the protected
methods (Success
and Fail
)
like "normal" IActionResult
creation methods.
Mutation Hooks
To create a mutation webhook, first create a new class
that implements the MutationWebhook<T>
base class.
Then decorate the webhook with the MutationWebhookAttribute
to set the route correctly.
After that setup, you may overwrite any of the following methods:
- Create
- CreateAsync
- Update
- UpdateAsync
- Delete
- DeleteAsync
The async methods take precedence over the sync methods.
An example of such a mutation webhook looks like:
[MutationWebhook(typeof(V1TestEntity))]
public class TestMutationWebhook : MutationWebhook<V1TestEntity>
{
public override MutationResult<V1TestEntity> Create(V1TestEntity entity, bool dryRun)
{
if (entity.Spec.Username == "overwrite")
{
entity.Spec.Username = "random overwritten";
return Modified(entity);
}
return NoChanges();
}
}
To create the mutation results, use the protected
methods (NoChanges
, Modified
, and Fail
)
like "normal" IActionResult
creation methods.
Conversion Hooks
[!CAUTION] Conversion webhooks are not stable yet. The API may change in the future without a new major version. All code related to conversion webhooks are attributed with the
RequiresPreviewFeatures
attribute. To use the features, you need to enable the preview features in your project file with the<EnablePreviewFeatures>true</EnablePreviewFeatures>
property.
A conversion webhook is a special kind of webhook that allows you to convert Kubernetes resources between versions. The webhooks are installed in CRDs and are called for all objects that need conversion (i.e. to achieve the stored version state).
A conversion webhook is separated to the webhook itself (the MVC controller that registers its route within ASP.NET) and the conversion logic.
The following example has two versions of the "TestEntity" (v1 and v2) and implements a conversion webhook to convert from v1 to v2 and vice versa.
// The Kubernetes resources
[KubernetesEntity(Group = "webhook.dev", ApiVersion = "v1", Kind = "TestEntity")]
public partial class V1TestEntity : CustomKubernetesEntity<V1TestEntity.EntitySpec>
{
public override string ToString() => $"Test Entity v1 ({Metadata.Name}): {Spec.Name}";
public class EntitySpec
{
public string Name { get; set; } = string.Empty;
}
}
[KubernetesEntity(Group = "webhook.dev", ApiVersion = "v2", Kind = "TestEntity")]
public partial class V2TestEntity : CustomKubernetesEntity<V2TestEntity.EntitySpec>
{
public override string ToString() => $"Test Entity v2 ({Metadata.Name}): {Spec.Firstname} {Spec.Lastname}";
public class EntitySpec
{
public string Firstname { get; set; } = string.Empty;
public string Lastname { get; set; } = string.Empty;
}
}
The v1 of the resource has first and lastname in the same field, while the v2 has them separated.
public class V1ToV2 : IEntityConverter<V1TestEntity, V2TestEntity>
{
public V2TestEntity Convert(V1TestEntity from)
{
var nameSplit = from.Spec.Name.Split(' ');
var result = new V2TestEntity { Metadata = from.Metadata };
result.Spec.Firstname = nameSplit[0];
result.Spec.Lastname = string.Join(' ', nameSplit[1..]);
return result;
}
public V1TestEntity Revert(V2TestEntity to)
{
var result = new V1TestEntity { Metadata = to.Metadata };
result.Spec.Name = $"{to.Spec.Firstname} {to.Spec.Lastname}";
return result;
}
}
The conversion logic is implemented in the IEntityConverter
interface.
Each converter has a "convert" (from → to) and a "revert" (to → from) method.
[ConversionWebhook(typeof(V2TestEntity))]
public class TestConversionWebhook : ConversionWebhook<V2TestEntity>
{
protected override IEnumerable<IEntityConverter<V2TestEntity>> Converters => new IEntityConverter<V2TestEntity>[]
{
new V1ToV2(), // other versions...
};
}
The webhook the registers the list of possible converters and calls the converter upon request.
[!NOTE] There needs to be a conversion between ALL versions to the stored version (newest version). If there is no conversion, the webhook will fail and the resource is not stored. So if there exist a v1, v2, and v3, there needs to be a converter for v1 → v3 and v2 → v3 (when v3 is the stored version).
Installing In The Cluster
When creating an operator with webhooks, certain special resources must be provided
to run in the cluster. When this package is referenced and KubeOps.Cli is installed,
these resources should be generated automatically. Basically, instead of
generating a dockerfile with dotnet:runtime
as final image, you'll need
dotnet:aspnet
and the operator needs a service and the certificates
for the HTTPS connection since webhooks only operate over HTTPS.
With the KubeOps.Cli package you can generate the required resources or let the customized Build targets do it for you.
The targets create a CA certificate and a server certificate (with respective keys), a service, and the webhook registrations required for you.
[!WARNING] The generated certificate has a validity of 5 years. After that time, the certificate needs to be renewed. For now, there is no automatic renewal process.
Webhook Development
The Operator Web package can be configured to generate self-signed certificates on startup,
and create/update your webhooks in the Kubernetes cluster to point to your development
machine. To use this feature, use the CertificateGenerator
class and UseCertificateProvider()
operator builder extension method. An example of what this might look like in Main:
var builder = WebApplication.CreateBuilder(args);
string ip = "192.168.1.100";
ushort port = 443;
using CertificateGenerator generator = new CertificateGenerator(ip);
using X509Certificate2 cert = generator.Server.CopyServerCertWithPrivateKey();
// Configure Kestrel to listen on IPv4, use port 443, and use the server certificate
builder.WebHost.ConfigureKestrel(serverOptions =>
{
serverOptions.Listen(System.Net.IPAddress.Any, port, listenOptions =>
{
listenOptions.UseHttps(cert);
});
});
builder.Services
.AddKubernetesOperator()
// Create the development webhook service using the cert provider
.UseCertificateProvider(port, ip, generator)
// More code for generation, controllers, etc.
The UseCertificateProvider
method takes an ICertificateProvider
interface, so it can be used
to implement your own certificate generator/loader for development if necessary.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net6.0 is compatible. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 is compatible. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
-
net6.0
- KubeOps.Abstractions (>= 9.1.4)
- KubeOps.Operator (>= 9.1.4)
- Localtunnel (>= 2.0.0-preview.1)
- SystemTextJson.JsonDiffPatch (>= 2.0.0)
-
net7.0
- KubeOps.Abstractions (>= 9.1.4)
- KubeOps.Operator (>= 9.1.4)
- Localtunnel (>= 2.0.0-preview.1)
- SystemTextJson.JsonDiffPatch (>= 2.0.0)
-
net8.0
- KubeOps.Abstractions (>= 9.1.4)
- KubeOps.Operator (>= 9.1.4)
- Localtunnel (>= 2.0.0-preview.1)
- SystemTextJson.JsonDiffPatch (>= 2.0.0)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
Version | Downloads | Last updated |
---|---|---|
9.1.5 | 9,075 | 9/10/2024 |
9.1.4 | 516 | 8/26/2024 |
9.1.3 | 5,124 | 6/28/2024 |
9.1.2 | 2,244 | 6/20/2024 |
9.1.1 | 2,347 | 5/22/2024 |
9.1.0 | 1,796 | 5/15/2024 |
9.0.2 | 110 | 5/13/2024 |
9.0.0 | 5,907 | 3/13/2024 |
9.0.0-pre.4 | 60 | 4/19/2024 |
9.0.0-pre.3 | 58 | 3/21/2024 |
9.0.0-pre.2 | 62 | 3/13/2024 |
9.0.0-pre.1 | 74 | 3/7/2024 |
8.0.2-pre.2 | 70 | 2/21/2024 |
8.0.2-pre.1 | 50 | 2/19/2024 |
8.0.1 | 3,976 | 2/13/2024 |
8.0.1-pre.7 | 72 | 2/12/2024 |
8.0.1-pre.6 | 69 | 2/7/2024 |
8.0.1-pre.5 | 76 | 2/5/2024 |
8.0.1-pre.4 | 61 | 1/31/2024 |
8.0.1-pre.3 | 62 | 1/26/2024 |
8.0.1-pre.2 | 57 | 1/25/2024 |
8.0.1-pre.1 | 68 | 1/18/2024 |
8.0.0 | 385 | 1/17/2024 |
8.0.0-pre.45 | 56 | 1/17/2024 |
8.0.0-pre.44 | 74 | 1/16/2024 |
8.0.0-pre.43 | 66 | 1/16/2024 |
8.0.0-pre.42 | 198 | 1/10/2024 |
8.0.0-pre.41 | 142 | 1/2/2024 |
8.0.0-pre.40 | 123 | 12/27/2023 |
8.0.0-pre.39 | 72 | 12/21/2023 |
8.0.0-pre.38 | 158 | 12/6/2023 |
8.0.0-pre.37 | 67 | 12/6/2023 |
8.0.0-pre.36 | 70 | 12/3/2023 |
8.0.0-pre.35 | 72 | 11/28/2023 |
8.0.0-pre.34 | 96 | 11/24/2023 |
8.0.0-pre.33 | 68 | 11/24/2023 |
8.0.0-pre.32 | 60 | 11/23/2023 |
8.0.0-pre.31 | 74 | 11/23/2023 |
8.0.0-pre.30 | 66 | 11/23/2023 |
8.0.0-pre.29 | 154 | 11/11/2023 |
8.0.0-pre.28 | 70 | 11/8/2023 |
8.0.0-pre.27 | 172 | 10/23/2023 |
8.0.0-pre.26 | 79 | 10/19/2023 |
8.0.0-pre.25 | 71 | 10/18/2023 |
8.0.0-pre.24 | 85 | 10/13/2023 |
8.0.0-pre.23 | 75 | 10/13/2023 |
8.0.0-pre.22 | 80 | 10/13/2023 |
8.0.0-pre.21 | 71 | 10/12/2023 |
8.0.0-pre.20 | 76 | 10/11/2023 |
8.0.0-pre.19 | 77 | 10/9/2023 |
8.0.0-pre.18 | 73 | 10/9/2023 |
8.0.0-pre.17 | 77 | 10/7/2023 |
8.0.0-pre.16 | 74 | 10/6/2023 |
8.0.0-pre.15 | 75 | 10/6/2023 |
8.0.0-pre.14 | 74 | 10/5/2023 |
8.0.0-pre.13 | 64 | 10/5/2023 |
8.0.0-pre.12 | 68 | 10/4/2023 |
8.0.0-pre.11 | 69 | 10/3/2023 |
8.0.0-pre.10 | 75 | 10/3/2023 |
8.0.0-pre.9 | 78 | 10/3/2023 |
8.0.0-pre.8 | 74 | 10/2/2023 |
8.0.0-pre.7 | 72 | 10/2/2023 |
8.0.0-pre.6 | 80 | 9/29/2023 |
8.0.0-pre.5 | 75 | 9/28/2023 |
8.0.0-pre.4 | 71 | 9/28/2023 |
8.0.0-pre.3 | 70 | 9/27/2023 |
8.0.0-pre.2 | 54 | 9/26/2023 |
8.0.0-pre.1 | 73 | 9/22/2023 |
'## [9.1.4](https://github.com/buehler/dotnet-operator-sdk/compare/v9.1.3...v9.1.4) (2024-08-26)
### Bug Fixes
* **leader-election:** introduce delay before attempting to reacquire leadership ([#794](https://github.com/buehler/dotnet-operator-sdk/issues/794)) ([0965d23](https://github.com/buehler/dotnet-operator-sdk/commit/0965d2317fe4dab422893a76ff0a22297bb9dfae)), closes [#785](https://github.com/buehler/dotnet-operator-sdk/issues/785)
* Use namespace and name for requeueing of entities ([#801](https://github.com/buehler/dotnet-operator-sdk/issues/801)) ([de986bf](https://github.com/buehler/dotnet-operator-sdk/commit/de986bf8dc9548bfeaccdd2fbe6cb174c302fe5f)), closes [#800](https://github.com/buehler/dotnet-operator-sdk/issues/800)
'