@spec apply_descendants(t(), Keyword.t()) :: t()

Applies the dependants to the cluster in groups. If :create_events is true, will create an event for each successful apply. Always creates events upon failed applies.

Options

:create_events - Whether events should be created upon success. Defaults to true

All further options are passed to K8s.Client.apply/2

@spec apply_status(t(), Keyword.t()) :: t()

Applies the status to the resource's status subresource in the cluster. If no status was specified, :noop is returned.

@spec clear_events(t()) :: t()

Empties the list of events without emitting them.

@spec emit_events(t()) :: t()

Emits the events created for this Axn.

@spec failure_event(t(), Keyword.t()) :: t()

Registers a failure event to the %Axn{} token to be emitted by Bonny.

@spec identifier(t()) ::
  {namespace_name :: binary(), api_version :: binary(), kind_action :: binary()}

Returns an identifier of an action event (resource and action) as tuple. Can be used in logs and similar.

@spec register_after_processed(t(), (t() -> t())) :: t()

Registers a callback to be invoked at the very end of an action event's processing by the operator.

Callbacks are invoked in the reverse order they are defined (callbacks defined first are invoked last).

Examples

To log a message after the an event was processed by the operator:

Bonny.Axn.register_after_processed(axn, fn axn ->
  Logger.info("done")
  axn
end)

@spec register_before_apply_descendants(t(), ([Bonny.Resource.t()], t() ->
                                          [Bonny.Resource.t()])) :: t()

Registers a callback to be invoked before descendants are applied to the cluster.

Callbacks are invoked in the reverse order they are defined (callbacks defined first are invoked last).

Examples

To log a message:

require Logger
Bonny.Axn.register_before_apply_status(axn, fn descendants, axn ->
  Enum.each(descendants, &Logger.info("Descending #{&1["kind"]} named #{&1["name"]} is applied to namespace #{&1["metadata"]["namespace"]}"))
  descendants
end)

@spec register_before_apply_status(t(), (Bonny.Resource.t(), t() ->
                                     Bonny.Resource.t())) :: t()

Registers a callback to be invoked before a status is applied to the status subresource.

Callbacks are invoked in the reverse order they are defined (callbacks defined first are invoked last).

Examples

To log a message for the status being applied:

require Logger
Bonny.Axn.register_before_apply_status(axn, fn resource, axn ->
  Logger.info("Status of the #{resource["kind"]} named #{resource["metadata"]["name"]} is applied to namespace #{resource["metadata"]["namespace"]}")
  resource
end)

@spec register_before_emit_event(t(), (Bonny.Event.t(), t() -> Bonny.Event.t())) ::
  t()

Registers a callback to be invoked before events are emitted to the cluster.

Callbacks are invoked in the reverse order they are defined (callbacks defined first are invoked last).

Examples

To log a message:

require Logger
Bonny.Axn.register_before_apply_status(axn, fn events, axn ->
  Logger.info("Event of type #{event.event_type} is emitted")
  events
end)

@spec register_descendant(t(), Bonny.Resource.t(), Keyword.t()) :: t()

Registers a decending object to be applied. Owner reference will be added automatically unless disabled through the option omit_owner_ref or if the resource is cluster-scoped.

If you need some resources to be applied before others, use the group option to indicate which group a resourceis added. Groups are applied in ascending order. Resources within a group are applied simultaneously.

Options

• omit_owner_ref - when true, adding the owner reference is omitted. Default: false. Note: This is automatically set to true for cluster-scoped resources.
• group - Integer (posittive or negative). Controls the order in which descendants are applied to the cluster. Default: 0

Examples

The following code registers a namespace and a pod as descendants. The namespace is assigned to group -1 as it needs to exist when the pod is created within it. The namespace is cluster-scoped so owner references are automatically omitted.

ns = %{
  "apiVersion" => "v1",
  "kind" => "Namespace",
  "metadata" => %{"name" => "my_ns"}
}
pod = %{
  "apiVersion" => "v1",
  "kind" => "Pod",
  "metadata" => %{"namespace" => "my_ns", "name" => "my_pod"},
  ...
}

axn
|> Bonny.Axn.register_descendant(resource, ns, group: -1)
|> Bonny.Axn.register_descendant(resource, pod)

# Cluster-scoped resource like PersistentVolume automatically omits owner ref
pv = %{
  "apiVersion" => "v1",
  "kind" => "PersistentVolume",
  "metadata" => %{"name" => "my-pv"},
  "spec" => %{"capacity" => %{"storage" => "1Gi"}}
}

axn |> Bonny.Axn.register_descendant(resource, pv)  # No owner ref added

@spec register_event(
  t(),
  Bonny.Resource.t() | nil,
  Bonny.Event.event_type(),
  binary(),
  binary(),
  binary()
) :: t()

Registers a Kubernetes event to the %Axn{} token to be emitted by Bonny.

@spec safe_apply_status(t(), Keyword.t()) :: t()

Applies the status to the resource's status subresource in the cluster, gracefully handling "NotFound" errors.

This is useful for operators where a resource may be deleted while reconciliation is still in progress. When the status update fails because the resource no longer exists, a warning is logged and the unmodified axn is returned instead of raising.

All other errors still raise as in apply_status/2.

Options

Same as apply_status/2: :field_manager, :force, etc.

Examples

# In a controller step
Bonny.Axn.safe_apply_status(axn, field_manager: "MyOperator", force: true)

@spec set_condition(
  axn :: t(),
  type :: binary(),
  status :: boolean(),
  message :: binary() | nil
) :: t()

Sets the condition in the resource status.

The field .status.conditions, if configured in the CRD, nolds a list of conditions, their status with a message and two timestamps. On the resource this could look something like this (taken from a Pod):

kind: Pod
status:
  conditions:
    - lastTransitionTime: "2019-10-22T16:29:24Z"
      status: "True"
      type: PodScheduled
    - lastTransitionTime: "2019-10-22T16:29:24Z"
      status: "True"
      type: Initialized
    - lastTransitionTime: "2019-10-22T16:29:31Z"
      status: "True"
      type: ContainersReady
    - lastTransitionTime: "2019-10-22T16:29:31Z"
      status: "True"
      type: Ready

@spec success_event(t(), Keyword.t()) :: t()

Registers a asuccess event to the %Axn{} token to be emitted by Bonny.

@spec update_status(t(), (map() -> map())) :: t()

Executes fun for the resource status and applies the new status subresource. This can be called multiple times.

fun should be a function of arity 1. It will be passed the current status object and expected to return the updated one.

If no current status exists, an empty map is passed to fun