Akka.Coordination.KubernetesApi 1.5.18-beta2

Prefix Reserved
This is a prerelease version of Akka.Coordination.KubernetesApi.
There is a newer version of this package available.
See the version list below for details.
dotnet add package Akka.Coordination.KubernetesApi --version 1.5.18-beta2                
NuGet\Install-Package Akka.Coordination.KubernetesApi -Version 1.5.18-beta2                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Akka.Coordination.KubernetesApi" Version="1.5.18-beta2" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Akka.Coordination.KubernetesApi --version 1.5.18-beta2                
#r "nuget: Akka.Coordination.KubernetesApi, 1.5.18-beta2"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Akka.Coordination.KubernetesApi as a Cake Addin
#addin nuget:?package=Akka.Coordination.KubernetesApi&version=1.5.18-beta2&prerelease

// Install Akka.Coordination.KubernetesApi as a Cake Tool
#tool nuget:?package=Akka.Coordination.KubernetesApi&version=1.5.18-beta2&prerelease                

Kubernetes Lease

This module is an implementation of an Akka Coordination Lease backed by a Custom Resource Definition (CRD) in Kubernetes. Resources in Kubernetes offer concurrency control and consistency that have been used to build a distributed lease/lock.

A lease can be used for:

  • Split Brain Resolver. An additional safety measure so that only one SBR instance can make the decision to remain up.
  • Cluster Singleton. A singleton manager can be configured to acquire a lease before creating the singleton.
  • Cluster Sharding. Each Shard can be configured to acquire a lease before creating entity actors.

In all cases the use of the lease increases the consistency of the feature. However, as the Kubernetes API server and its backing etcd cluster can also be subject to failure and network issues any use of this lease can reduce availability.

Lease Instances

  • With Split Brain Resolver there will be one lease per Akka Cluster
  • With multiple Akka Clusters using SBRs in the same namespace, you must ensure different ActorSystem names because they all need a separate lease.
  • With Cluster Sharding and Cluster Singleton there will be more leases
    • For Cluster Singleton there will be one per singleton.
    • For Cluster Sharding, there will be one per shard per type.

Configuring

Creating the Custom Resource Definition for the lease

This requires admin privileges to your Kubernetes / Open Shift cluster but only needs doing once.

Kubernetes:

kubectl apply -f lease.yml

Where lease.yml contains:

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  # name must match the spec fields below, and be in the form: <plural>.<group>
  name: leases.akka.io
spec:
  group: akka.io
  versions:
    - name: v1
      storage: true
      served: true
      schema:
        openAPIV3Schema:
          type: object
          properties:
            spec:
              type: object
              properties:
                owner:
                  type: string
                version:
                  type: string
                time:
                  type: integer
  scope: Namespaced
  names:
    # kind is normally the CamelCased singular type. Your resource manifests use this.
    kind: Lease
    listKind: LeaseList
    # singular name to be used as an alias on the CLI and for display
    singular: lease
    # plural name to be used in the URL: /apis/<group>/<version>/<plural>
    plural: leases

Role based access control

Each pod needs permission to read/create and update lease resources. They only need access for the namespace they are in.

An example RBAC that can be used:

kind: Role
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: lease-access
rules:
  - apiGroups: ["akka.io"]
    resources: ["leases"]
    verbs: ["get", "create", "update", "list"]
---
kind: RoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: lease-access
subjects:
  - kind: User
    name: system:serviceaccount:<YOUR NAMESPACE>:default
roleRef:
  kind: Role
  name: lease-access
  apiGroup: rbac.authorization.k8s.io

This defines a Role that is allows to get, create and update lease objects and a RoleBinding that gives the default service user this role in <YOUR NAMESPACE>.

Future versions may also require delete access for cleaning up old resources. Current uses within Akka only create a single lease so cleanup is not an issue.

To avoid giving an application the access to create new leases an empty lease can be created in the same namespace as the application with:

kubelctl create -f sbr-lease.yml -n <YOUR_NAMESPACE>

Where sbr-lease.yml contains:

apiVersion: "akka.io/v1"
kind: Lease
metadata:
  name: <YOUR_ACTORSYSTEM_NAME>-akka-sbr
spec:
  owner: ""
  time: 0

NOTE

The lease gets created only during an actual Split Brain.

Enable In SBR Using Akka.Cluster.Hosting

To enable Kubernetes lease inside SBR, you need to pass a LeaseMajorityOption instance into the second parameter of the WithClsutering() extension method and specify that you're using the Kubernetes lease implementation.

using var host = new HostBuilder()
    .ConfigureServices((context, services) =>
    {
        services.AddAkka("k8sLeaseDemo", (builder, provider) =>
        {
            builder
                .WithRemoting("", 4053)
                .WithClustering(sbrOption: new LeaseMajorityOption
                {
                    LeaseImplementation = KubernetesLeaseOption.Instance,
                    LeaseName = "myActorSystem-akka-sbr"
                });
        });
    }).Build();

await host.RunAsync();

Enable In SBR Using HOCON Configuration

To enable the lease for use within SBR:

akka.cluster {
    downing-provider-class = "Akka.Cluster.SBR.SplitBrainResolverProvider, Akka.Cluster"
    split-brain-resolver {
        active-strategy = lease-majority
        lease-majority {
            lease-implementation = "akka.coordination.lease.kubernetes"
        }
    }
}

Full configuration options

akka.coordination.lease.kubernetes {

    lease-class = "Akka.Coordination.KubernetesApi.KubernetesLease, Akka.Coordination.KubernetesApi"

    api-ca-path = "/var/run/secrets/kubernetes.io/serviceaccount/ca.crt"
    api-token-path = "/var/run/secrets/kubernetes.io/serviceaccount/token"

    api-service-host-env-name = "KUBERNETES_SERVICE_HOST"
    api-service-port-env-name = "KUBERNETES_SERVICE_PORT"

    # Namespace file path. The namespace is to create the lock in. Can be overridden by "namespace"
    #
    # If this path doesn't exist, the namespace will default to "default".
    namespace-path = "/var/run/secrets/kubernetes.io/serviceaccount/namespace"

    # Namespace to create the lock in. If set to something other than "<namespace>" then overrides any value
    # in "namespace-path"
    namespace = "<namespace>"

    # How often to write time into CRD so that if the holder crashes
    # another node can take the lease after a given timeout. If left blank then the default is
    # max(5s, heartbeat-timeout / 10) which will be 12s with the default heartbeat-timeout
    heartbeat-interval = ""

    # How long a lease must not be updated before another node can assume
    # the holder has crashed.
    # If the lease holder hasn't crashed its next heart beat will fail due to the version
    # having been updated
    heartbeat-timeout = 120s

    # The individual timeout for each HTTP request. Defaults to 2/5 of the lease-operation-timeout
    # Can't be greater than then lease-operation-timeout
    api-service-request-timeout = ""

    # Use TLS & auth token for communication with the API server
    # set to false for plain text with no auth
    secure-api-server = true

    # The amount of time to wait for a lease to be aquired or released. This includes all requests to the API
    # server that are required. If this timeout is hit then the lease *may* be taken due to the response being lost
    # on the way back from the API server but will be reported as not taken and can be safely retried.
    lease-operation-timeout = 5s
}
Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  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 was computed.  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 was computed.  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. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

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
1.5.31 417 11/11/2024
1.5.30 1,147 10/3/2024
1.5.29 145 10/1/2024
1.5.27 538 7/30/2024
1.5.26.1 846 7/16/2024
1.5.26 80 7/15/2024
1.5.26-beta3 99 7/2/2024
1.5.26-beta2 104 6/28/2024
1.5.26-beta1 87 6/27/2024
1.5.25.1 123 6/25/2024
1.5.25 139 6/17/2024
1.5.24 101 6/11/2024
1.5.19 730 4/17/2024
1.5.18-beta2 97 3/27/2024
1.5.18-beta1 144 3/20/2024
1.5.17.1 1,878 3/4/2024
1.5.15 521 1/12/2024
1.5.7 3,579 5/23/2023
1.5.5 156 5/8/2023
1.5.0 375 3/2/2023
1.5.0-beta6 135 3/1/2023
1.5.0-alpha4 129 2/17/2023
1.0.3 404 2/13/2023
1.0.2 254 2/8/2023
1.0.1 310 1/31/2023
1.0.0 323 1/18/2023
1.0.0-beta2 158 1/7/2023
1.0.0-beta1 132 1/6/2023
0.3.0-beta4 155 12/2/2022
0.3.0-beta3 183 11/7/2022
0.3.0-beta2 254 10/20/2022
0.3.0-beta1 146 10/6/2022
0.2.5-beta4 148 8/31/2022
0.2.5-beta3 189 8/16/2022
0.2.5-beta2 147 8/8/2022
0.2.5-beta1 155 8/1/2022
0.2.4-beta3 215 5/5/2022
0.2.4-beta2 211 4/14/2022
0.2.4-beta1 182 12/2/2021

[Discovery.KubernetesApi: Add option to query pods in all namespaces](https://github.com/akkadotnet/Akka.Management/pull/2421)
[Bump AWSSDK.CludFormation to 3.7.305.4](https://github.com/akkadotnet/Akka.Management/pull/2430)