Operations

Operations can be used to interact with the Operators of a service. They have two levels of API:

• The interaction with the Operation resource
• The service specific procedure API

An operator offers a list of procedures which can be called in an Operation, so each Operation is basically a procedure call on the operator.

Operation Setup

Operations must be created with specific metadata so the operator subscribed to those can pick up the operation request.

Once automation for operation procedure references have been implemented, the available procedures documentation and required metadata will be available in the Settings spec of the service.

Right now the required metadata are two label fields:

To reduce orphaned resources it is advisable to set OwnerReferences for garbage collection, so if the owners are deleted this operation is automatically deleted as well.

apiVersion: aep.asag.io/v1alpha1
kind: Operation
metadata:
  namespace: test
  generateName: psql-
  labels:
    aep.asag.io/servicedefinition: psql
    serviceflag.aep.asag.io/operator_identifier: psql-operator
  ownerReferences:
  - apiVersion: service.aep.asag.io/v1
    kind: Provision
    name: psql1-test
    uid: af221758-d79a-4f17-8f99-6cb54689390f
spec:
  procedure: service::make_backup
  arguments:
    foo: bar

Feel free to add any additional metadata for your use-case.

Watch/Wait Operation execution

You can use the usual kubectl commands to watch the operation or wait for the operation to have reached a specific condition. The operation is completed when .status.closed is true, whether the procedure was successful or not.

• To watch for changes in the operation use kubectl get with the -w flag, e.g. kubectl get operation psql-abcde -w
• To wait until the operation has finished use kubectl wait with the --for argument, e.g. kubectl wait operation psql-abcde --for=jsonpath='{.status.closed}'=true

The status condition of type: "Output" contains live-ish output of the operation, if the procedure provides any.

Operation timeout/cancellation

Operations have no timeout, it is the callers responsibility to cancel or delete the operation once his timeout is reached. To cancel the procedure forcefully set the field .spec.cancel to true - deleting the Operation while a procedure is running has the same effect. All operators should forcefully shut down the execution of the procedure immediately.

Results of the Operation

If everything went fine, the .status.phase field is set to done. If the procedure provides return values they are now available in the .status.values map. If something went wrong, the .status.phase field is set to error. It’s the callers responsibility to decide whether to try again by setting up a new operation or to raise the error further upstream in his call stack.

It is recommended to delete the operation after processing to keep the list of operations tidy unless it is beneficial to keep those around (e.g. as history).

Never create, edit or delete AEP specific operations (containing procedures with “aep”-like prefix)! Permission checks on whether a caller can execute specific procedures are not ready and active yet.