Actions

An Action API resource is used to initiate K10 data management operations. The actions can either be associated with a Policy or be stand-alone on-demand actions. Actions also allow for tracking the execution status of the requested operations.

The K10 Platform exposes a number of different action types. You can find more information about each of the supported types.

BackupAction

Backup actions are used to initiate backup operations on applications. A backup action can be submitted as part of a policy or as a standalone action.

Create BackupAction Example

For an example of how to use a BackupAction in a policy see Create Backup Policy.

The following example illustrates how to create an on-demand backup action for an application called mysql which resides is in a namespace called mysql.

$ cat > sample-backup-action.yaml <<EOF
apiVersion: actions.kio.kasten.io/v1alpha1
kind: BackupAction
metadata:
  generateName: backup-mysql-
  namespace: mysql
  labels:
    # These labels are required for on-demand actions so that
    # actions can be filtered.
    # Label presence is validated.
    k10.kasten.io/appName: "mysql"
    k10.kasten.io/appNamespace: "mysql"
spec:
  subject:
    # Reference to the K10App CR for the application
    name: mysql
    namespace: mysql
EOF

$ kubectl create -f sample-backup-action.yaml
actions.kio.kasten.io/backup-mysql-ax34rt created

Check Status of BackupAction Example

After creating a BackupAction, K10 will validate the action and will proceed with execution. The action can be used to verify the execution status.

$ kubectl get backupactions.actions.kio.kasten.io backup-mysql-ax34rt -ojsonpath="{.status.state}{'\n'}"
Running

If the action has completed successfully, you can get the RestorePoint that will be created.

$ kubectl get backupactions.actions.kio.kasten.io backup-mysql-ax34rt -ojsonpath="{.status.restorePoint.name}{'\n'}"
backup-mysql-ax34rt-restore-point-02-10-2019-09-00

BackupAction Details Example

In addition to checking the status of a BackupAction, you can also query the details associated with the action. You would use the details sub-resource for that purpose.

# get the details for action 'backup-mysql-ax34rt' created in 'mysql' namespace
# yq only used for readability
$ kubectl get --raw /apis/actions.kio.kasten.io/v1alpha1/namespaces/mysql/backupactions/backup-mysql-ax34rt/details | yq -y .status.actionDetails
phases:
- name: Application configuration
  state: succeeded
  attempt: 1
  startTime: '2019-02-11T03:03:47Z'
  endTime: '2019-02-11T03:03:48Z'
  updatedTime: '2019-02-11T03:03:48Z'
- name: Stateful component mysql
  state: failed
  attempt: 2
  startTime: '2019-02-11T03:03:47Z'
  endTime:
  updatedTime: '2019-02-11T03:04:51Z'
  errors:
  - message: No profile found
artifacts:
  ...

BackupAction Delete Example

Once a BackupAction is complete, successfully or otherwise, it is possible to delete the action. For actions that have completed successfully, the restore point created by the action will be preserved.

$ kubectl delete backupactions.actions.kio.kasten.io backup-mysql-ax34rt
actions.kio.kasten.io/backup-mysql-ax34rt deleted

BackupAction List Example

The following example illustrates listing all BackupActions for a sample namespace.

# list backup actions in namespace 'sample-app'
$ kubectl get backupactions.actions.kio.kasten.io --namespace sample-app
NAME                              AGE
sample-app-backup-mysql-ax34rt    1h
sample-app-backup-mysql-bg54st    2h

For listing BackupActions in all namespaces use the --all-namespaces option

# list backup actions in all namespaces
$ kubectl get backupactions.actions.kio.kasten.io --all-namespaces
NAMESPACE         NAME                              AGE
sample-app        sample-app-backup-mysql-ax34rt    1h
sample-app        sample-app-backup-mysql-bg54st    2h

BackupAction API Type

The following is a complete specification of the BackupAction API.

# Standard Kubernetes API Version declaration. Required.
apiVersion: actions.kio.kasten.io/v1alpha1
# Standard Kubernetes Kind declaration. Required.
kind: BackupAction
metadata:
  # Kubernetes labels.
  # The following labels will be auto-populated upon creation.
  # These labels can be used for filtering when getting actions.
  # Any additional custom labels can be specified if desired.
  labels:
    # Populated for policy initiated BackupAction only.
    k10.kasten.io/policyName: "sample-originating-policy"
    k10.kasten.io/policyNamespace: "namespace-of-policy"
    # Populated for on-demand and policy initiated actions
    k10.kasten.io/appName: "sample-app"
    k10.kasten.io/appNamespace: "sample-app"
    # Populated for on-demand RunActions and policy initiated actions
    k10.kasten.io/runActionName: "run-lhr7n6j8dw"
  # BackupAction name. May be any valid Kubernetes object name. Required.
  # BackupAction name is not mutable once created.
  name: backup-action-example
  # BackupAction names must be unique and as an alternative to name above
  # one can take advantage of Kubernetes auto name generation
  generateName: backup-action-
  # BackupAction namespace. Required.
  # Must be namespace of the application being backed up. Should match subject.
  namespace: mysql
# BackupAction spec. Required.
spec:
  # Target application to be backed up. Required.
  subject:
    # Name of the K10App resource. Required.
    name: sample-app
    # Namespace of the application. Required.
    namespace: sample-app
  # Scheduled time of action when initiated by policy. Optional.
  scheduledTime: "2019-02-11T05:10:45Z"
  # Filters describe which Kubernetes resources should be included or excluded
  # in the backup. If no filters are specified, all the API resources in a
  # namespace are captured by the BackupAction.
  #
  # Resource types are identified by group, version, and resource type names,
  # or GVR, e.g. networking.k8s.io/v1/networkpolicies. Core Kubernetes types
  # do not have a group name and are identified by just a version and resource
  # type name, e.g. v1/configmaps.
  #
  # Individual resources are identified by their resource type and resource
  # name, or GVRN. In a filter, an empty or omitted group, version, resource
  # type or resource name matches any value.
  #
  # Filters reduce the resources in the backup by selectively including and
  # then excluding resources.
  # - If includeResources is not specified, all the API resources in a
  #   namespace are included in the set of resources to be backed up.
  # - If includeResources is specified, resources matching any GVRN entry in
  #   includeResources are included in the set of resources to be backed up.
  # - If excludeResources is specified, resources matching any GVRN entry in
  #   excludeResources are excluded from the set of resources to be backed up.
  #
  # For RestorePoint usefulness after the BackupAction, K10 automatically
  # includes associated PVCs and PVs when a statefulset, deployment, or
  # deploymentconfig is included by includeResources unless the PVC is
  # excluded by excludeResources.
  filters:
    # Include only resources that match any of the following NGVRs
    includeResources:
      # Include individual resource
    - name: <resource1 resource name>
      group: <resource1 group>
      version: <resource1 version>
      resource: <resource1 type name>
      # Include resource type
    - group: <resource2 group>
      version: <resource2 version>
      resource: <resource2 type name>
    # Exclude resources that match any of the following NGVRs
    excludeResources:
      # Exclude specific instance of resource2 type
    - name: <resource2 resource name>
      group: <resource2 group>
      version: <resource2 version>
      resource: <resource2 type name>
  # Optional: Ignore exceptions and continue if possible.
  # Snapshots with exceptions will be flagged as potentially flawed.
  # Default: false
  ignoreExceptions: false
  # Optional: Hooks are Kanister actions executed first or last in a BackupAction.
  # A Kanister ActionSet is created with the application namespace as its subject.
  # The Blueprint must be in the K10 namespace. Hooks do not use Location Profile.
  hooks:
    # The Kanister action referenced by preHook will be executed before
    # other phases of the BackupAction. Optional.
    preHook:
      blueprint: backup-hook-blueprint
      actionName: before-backup
    # The Kanister action referenced by onSuccess will be executed once all
    # other phases in the BackupAction have completed successfully. Optional.
    onSuccess:
      blueprint: backup-hook-blueprint
      actionName: on-success
    # The Kanister action referenced by onFailure will be executed only
    # when the BackupAction fails and exhausts all retries. Optional.
    onFailure:
      blueprint: backup-hook-blueprint
      actionName: on-failure
# Status of the action. Users should not set directly.
status:
  # State of the action. Always present.
  # Valid values are:
  # Pending - action has been created
  # Running - action has been validated and is running
  # AttemptFailed - at least one action phase needs to retry
  # Failed - action has failed (at least one phase failed permanently)
  # Complete - action has completed successfully
  # Skipped - action has been skipped
  # Deleting - action is being deleted
  state: Complete
  # Initial start time of action. Always present.
  startTime: "2019-02-11T05:10:45Z"
  # End time of action. Can be 'null' if action still running. Always present.
  endTime: "2019-02-11T05:13:10Z"
  # RestorePoint created by a successful action.
  # Always present when the action succeeds.
  restorePoint:
    # Name of the restore point.
    name: backup-action-example-restorepoint
    # Namespace of the restore point. Will be the same as action name space
    namespace: mysql
  # Error associated with the action.
  # Only included if the action does not succeed.
  error:
    message: Sample error message
  # List of exceptions associated with the action.
  # Only included if exceptions are present.
  exceptions:
    - message: Sample exception message

BackupAction Details API Type

The following is a complete specification of the actionDetails section of the BackupAction API. These fields are only available in the BackupAction API when the details sub-resource is used as shown in the example above.

apiVersion: actions.kio.kasten.io/v1alpha1
kind: BackupAction
...
spec:
...
status:
  ...
  # Details section of the action resource.
  # Included when the details sub-resource is queried.
  actionDetails:
    # List of phases associated with the action. Always present.
    phases:
        # Name of the phase.
      - name: "Application configuration"
        # State of the phase.
        state: "succeeded"
        # Number of attempts for the phase.
        attempt: 1
        # Start time of the phase.
        startTime: "2019-02-11T03:03:47Z"
        # End time of the phase. 'null' if still running.
        endTime: "2019-02-11T03:03:48Z"
        # Las updated time of the phase.
        updatedTime
        # List of errors associated with the phase attempts.
        # Only included attempt > 1 (phase has failed at lease once).
        errors:
          - message: "Sample error message"

RestoreAction

Restore actions are used to restore applications to a known-good state from a restore point.

Create RestoreAction Example

The following example illustrates how to initiate a restore for an application called mysql which resides is in a namespace called mysql.

$ cat > sample-restore-action.yaml <<EOF
apiVersion: actions.kio.kasten.io/v1alpha1
kind: RestoreAction
metadata:
  generateName: restore-mysql-
  namespace: mysql
spec:
  subject:
    kind: RestorePoint
    name: mysql-restore-point-02-11-2019-09-00PST
    namespace: mysql
  targetNamespace: mysql
EOF

$ kubectl create -f sample-restore-action.yaml
actions.kio.kasten.io/restore-mysql-afr823 created

Check Status of RestoreAction Example

After creating a RestoreAction, K10 will validate the action and will proceed with execution. The action can be used to verify the execution status.

$ kubectl get restoreactions.actions.kio.kasten.io restore-mysql-afr823 -ojsonpath="{.status.state}{'\n'}"
Running

RestoreAction Details Example

In addition to checking the status of a RestoreAction, you can also query the details associated with the action. You would use the details sub-resource for that purpose.

# get the details for action 'restore-mysql-afr823' created in 'mysql' namespace
# yq only used for readability
$ kubectl get --raw /apis/actions.kio.kasten.io/v1alpha1/namespaces/mysql/restoreactions/restore-mysql-afr823/details | yq -y .status.actionDetails

# output is analogous to that for BackupAction

RestoreAction Delete Example

Once a RestoreAction is complete, successfully or otherwise, it is possible to delete the action. Deleting the action has no effect on the underlying Restore Point that was used.

$ kubectl delete restoreactions.actions.kio.kasten.io restore-mysql-afr823
actions.kio.kasten.io/restore-mysql-afr823 deleted

RestoreAction List Example

The following example illustrates listing all RestoreActions for a sample namespace.

# list restore actions in namespace 'sample-app'
$ kubectl get restoreactions.actions.kio.kasten.io --namespace sample-app
NAME                              AGE
restore-mysql-afr823              1h
restore-mysql-fth675              2h

For listing RestoreActions in all namespaces use the --all-namespaces option

# list restore actions in all namespaces
$ kubectl get restoreactions.actions.kio.kasten.io --all-namespaces
NAMESPACE         NAME                              AGE
sample-app        restore-mysql-afr823              1h
sample-app        restore-mysql-fth675              2h

RestoreAction API Type

The following is a complete specification of the RestoreAction API.

# Standard Kubernetes API Version declaration. Required.
apiVersion: actions.kio.kasten.io/v1alpha1
# Standard Kubernetes Kind declaration. Required.
kind: RestoreAction
metadata:
  # Kubernetes labels.
  # The following labels will be auto-populated upon creation.
  # These labels can be used for filtering when getting actions.
  # Any additional custom labels can be specified if desired.
  labels:
    # Populated for policy initiated RestoreAction only.
    k10.kasten.io/policyName: "sample-originating-policy"
    k10.kasten.io/policyNamespace: "namespace-of-policy"
    # Populated for on-demand and policy initiated actions
    k10.kasten.io/appName: "sample-app"
    k10.kasten.io/appNamespace: "sample-app"
  # RestoreAction name. May be any valid Kubernetes object name. Required.
  # RestoreAction name is not mutable once created.
  name: restore-action-example
  # RestoreAction names must be unique and as an alternative to name above
  # one can take advantage of Kubernetes auto name generation
  generateName: restore-action-
  # RestoreAction namespace. Required.
  # The target namespace where the application is being restored.
  namespace: mysql
# RestoreAction spec. Required.
spec:
  # Target RestorePoint to be used. Required.
  # The caller needs to have read permission for the RestorePoint API
  # in the namespace below.
  subject:
    # Standard Kubernetes kind declaration. Required.
    # Must be 'RestorePoint'
    kind: RestorePoint
    # Name of the restore point to use. Required.
    name: sample-restore-point
    # Namespace of the restore point. Required.
    namespace: sample-app
  # Optional: set to true to only restore the application data.
  # Must be false if filters are specified.
  # Default: false
  dataOnly: false
  # Optional: Filters describe which Kubernetes resources should be restored
  # from the RestorePoint.  If no filters are specified, all the artifacts
  # in the RestorePoint are restored.
  #
  # Filters reduce the resources restored by selectively including and then
  # excluding resources.
  # - If includeResources is not specified, all resources in the RestorePoint
  #   are included in the set of resources to be restored.
  # - If includeResources is specified, resources matching any GVRN entry in
  #   includeResources are included in the set of resources to be restored.
  # - If excludeResources is specified, resources matching any GVRN entry in
  #   excludeResources are excluded from the set of resources to be restored.
  # - In a filter, an empty or omitted group, version, resource type or
  #   resource name matches any value.
  #
  # For precise control of RestoreAction, K10 only restores resources that
  # are explicitly included by includeResources. For RestoreAction, when a
  # statefulset,deployment, or deploymentconfig is included by includeResources,
  # K10 does not restore associated PVCs unless the PVC is included by
  # includeResources.
  filters:
    # Include only resources that match any of the following NGVRs or labels
    includeResources:
      # Include individual resource
    - name: <resource1 resource name>
      group: <resource1 group>
      version: <resource1 version>
      resource: <resource1 type name>
      # Include resource type
    - group: <resource2 group>
      version: <resource2 version>
      resource: <resource2 type name>
    - matchLabels:
        <label key>: <label value>
    # Exclude resources that match any of the following NGVRs or labels
    excludeResources:
      # Exclude specific instance of resource2 type
    - name: <resource2 resource name>
      group: <resource2 group>
      version: <resource2 version>
      resource: <resource2 type name>
    - matchLabels:
        <label key>: <label value>
  # Namespace where the application is to be restored.
  # This field will be REMOVED shortly as this will be controlled
  # by the namespace in which the RestoreAction resource is created
  targetNamespace: mysql
  # perform transformations on configMaps or kubernetes resources
  transforms:
  - subject:
      # Group, version, resource and/or name of the resource for transformation
      name: <resource name>
      group: <resource group>
      version: <resource version>
      resource: <resource type name>
    # perform JSON patch transformation
    json:
      # `json` JSON patch document object used to perform a JSON patch transform
      # supports the following transformations
      #
      # add - add a new element at the "path" with "value" to resource
      #       definition.  if element at "path" is an existing map element
      #       it will be replaced.
      # remove - remove element at "path" from resource definition.  path
      #          must exist.
      # replace - replace element at "path" with "value".  like 'remove' then 'add'
      # move - move the element at "from" to "path" replacing element at
      #        "path" if it exists
      # copy - copy the element at "from" to "path".  value will be replaced if
      #        if it is an existing map element
      # test - test that element at "path" equals "value"
    - op: test
      # reference for operation.  mandatory.
      path: 'metadata/labels/release'
    - op: copy
      # source reference for operation.  only valid for the 'move' and 'copy' operations
      from: 'metadata/labels/release'
      # target reference for operation.  mandatory.
      path: 'spec/template/metadata/labels/release'
      # apply regex to match expression.  Valid for 'remove', 'replace', 'move',
      # 'copy' and 'test'.
      regex: 'prod-v.*'
      # value is any json structure.  only valid for 'add', 'replace'
      # and 'test' operation
      value: 'prod'
  # Only used with Kanister blueprints that support point-in-time restore
  # Value is the desired timestamp. Optional.
  pointInTime: "2019-02-11T05:13:10Z"
  # Optional: Specifies whether the restore action should wait for all
  # workloads (Deployments, StatefulSets or DeploymentConfigs)
  # to be ready before completing.
  skipWaitForWorkloadReady: false
  # Optional: Specify an alternate profile to restore from. Use if restore
  # points have been copied or moved from their original export location.
  artifactOverrideProfile:
    name: <profile name>
  # Optional: Hooks are Kanister actions executed first or last in a RestoreAction.
  # A Kanister ActionSet is created with the target namespace as its subject.
  # The Blueprint must be in the K10 namespace. Hooks do not use Location Profile.
  hooks:
    # The Kanister action referenced by preHook will be executed before
    # other phases of the RestoreAction. Optional.
    preHook:
      blueprint: restore-hook-blueprint
      actionName: before-restore
    # The Kanister action referenced by onSuccess will be executed once all
    # other phases in the RestoreAction have completed successfully. Optional.
    onSuccess:
      blueprint: restore-hook-blueprint
      actionName: on-success
    # The Kanister action referenced by onFailure will be executed only
    # when the RestoreAction fails and exhausts all retries. Optional.
    onFailure:
      blueprint: restore-hook-blueprint
      actionName: on-failure
# Status of the action. Users should not set directly.
status:
  # State of the action. Always present.
  # Valid values are:
  # Pending - action has been created
  # Running - action has been validated and is running
  # AttemptFailed - at least one action phase needs to retry
  # Failed - action has failed (at least one phase failed permanently)
  # Complete - action has completed successfully
  # Skipped - action has been skipped
  # Deleting - action is being deleted
  state: Complete
  # Initial start time of action. Always present.
  startTime: "2019-02-11T05:10:45Z"
  # End time of action. Can be 'null' if action still running. Always present.
  endTime: "2019-02-11T05:13:10Z"
  # Error associated with the action.
  # Only included if the action does not succeed.
  error:
    message: Sample error message
  # List of exceptions associated with the action.
  # Only included if exceptions are present.
  exceptions:
    - message: Sample exception message

RestoreAction Details API Type

The specification for actionDetails for RestoreAction API is the same as the actionDetails section of the BackupAction API.

ExportAction

Export actions are used to initiate an export of an application to a different cluster using an existing restore point.

For scheduled operations, an export action will be included as part of a policy following a BackupAction. It is still possible to initiate an on-demand export.

Create ExportAction Example

The following example illustrates how to initiate an export for an application called mysql which resides is in a namespace called mysql.

On-demand export actions can only be initiated in by K10 admin users who have permissions to create an ExportAction in the namespace where K10 is installed.

# create on-demand export that exports RP 'mysql-restore-point-02-11-2019-09-00PST'
# from the 'mysql' namespace using 'sample-profile'.
# Assumes that K10 is installed in 'kasten-io' namespace.
$ cat > sample-export-action.yaml <<EOF
apiVersion: actions.kio.kasten.io/v1alpha1
kind: ExportAction
metadata:
  generateName: export-mysql-
  namespace: kasten-io
spec:
  subject:
    kind: RestorePoint
    name: mysql-restore-point-02-11-2019-09-00PST
    namespace: mysql
  profile:
    name: sample-profile
    namespace: kasten-io
EOF

$ kubectl create -f sample-export-action.yaml
actions.kio.kasten.io/export-mysql-brd911 created

Check Status of ExportAction Example

After creating an ExportAction, K10 will validate the action and will proceed with execution. The action can be used to verify the execution status.

$ kubectl get exportactions.actions.kio.kasten.io export-mysql-brd911 -ojsonpath="{.status.state}{'\n'}"
Running

Get Export String of ExportAction Example

In addition to checking the ExportAction status, you may need to retrieve the exportString that is generated to identify the export. This will be used when initiating an import on the other cluster.

$ kubectl get exportactions.actions.kio.kasten.io export-mysql-brd911 -ojsonpath="{.status.exportString}{'\n'}"
xbrd234sampleExportSting123==

ExportAction Details Example

In addition to checking the status of an ExportAction, you can also query the details associated with the action. You would use the details sub-resource for that purpose.

# get the details for action 'export-mysql-brd911' created in 'kasten-io' namespace
# yq only used for readability
$ kubectl get --raw /apis/actions.kio.kasten.io/v1alpha1/namespaces/kasten-io/exportactions/export-mysql-brd911/details | yq -y .status.actionDetails

# output is analogous to that for BackupAction

ExportAction Delete Example

Once an ExportAction is complete, successfully or otherwise, it is possible to delete the action. Deleting the action has no effect on the application that was exported.

Note

You will not be able to access the exportString after deleting the ExportAction so make sure to collect it before deleting.

$ kubectl delete exportactions.actions.kio.kasten.io restore-mysql-afr823
actions.kio.kasten.io/restore-mysql-afr823 deleted

ExportAction API Type

The following is a complete specification of the ExportAction API.

# Standard Kubernetes API Version declaration. Required.
apiVersion: actions.kio.kasten.io/v1alpha1
# Standard Kubernetes Kind declaration. Required.
# Must be ExportAction
kind: ExportAction
metadata:
  # Kubernetes labels.
  # The following labels will be auto-populated upon creation.
  # These labels can be used for filtering when getting actions.
  # Any additional custom labels can be specified if desired.
  labels:
    # Populated for policy initiated RestoreAction only.
    k10.kasten.io/policyName: "sample-originating-policy"
    k10.kasten.io/policyNamespace: "namespace-of-policy"
    # Populated for on-demand and policy initiated actions
    k10.kasten.io/appName: "sample-app"
    k10.kasten.io/appNamespace: "sample-app"
    # Populated for on-demand RunActions and policy initiated actions
    k10.kasten.io/runActionName: "run-lhr7n6j8dw"
  # ExportAction name may be any valid Kubernetes object name. Required.
  # ExportAction name is not mutable once created.
  name: export-action-example
  # ExportAction names must be unique and as an alternative to name above
  # one can take advantage of Kubernetes auto name generation
  generateName: export-action-
  # Action namespace. Required.
  # Namespace must be where K10 is installed.
  namespace: kasten-io
# ExportAction spec. Required.
spec:
  # Target RestorePoint to be used for export. Required.
  # The caller needs to have read permission for the RestorePoint API
  # in the namespace below.
  subject:
    # Standard Kubernetes kind declaration. Required.
    # Must be 'RestorePoint'
    kind: RestorePoint
    # Name of the restore point to use. Required.
    name: sample-restore-point
    # Namespace of the restore point. Required.
    namespace: sample-app
  # K10 Location Profile that is used for this export. Required.
  profile:
    # Name of the location profile. Required.
    name: sample-profile
    # Namespace of the location profile. Required.
    # Must the the namespace where K10 is installed.
    namespace: kasten-io

  # String to be used to initiate corresponding import.
  # Will be automatically populated. Do not explicitly specify.
  # This field will be move to 'status' in an upcoming release
  receiveString: "xbrd234sampleExportSting123=="

  # Backup portability setting.
  # Convert volume snapshots into an infrastructure-independent
  # format.
  exportData:
    # Default setting for all storage classes
    enabled: false
    # Optional: Storage class to use for any temporary PVCs created
    # during the snapshot conversion process. If not specified, the
    # storage class of the source volume is used.
    exporterStorageClassName: gp2
    # Overrides for the default exportData setting specified above.
    # Use this if you want to modify the defaults for a PVC that
    # has a specific storage class.
    overrides:
      # Override setting of a specific storage class.
      - storageClassName: gp2
        enabled: false
      - storageClassName: gp2-eu-west-1a
        enabled: true
        exporterStorageClassName: io1

  # Optional: Hooks are Kanister actions executed first or last in an ExportAction.
  # A Kanister ActionSet is created with the exported namespace as its subject.
  # The Blueprint must be in the K10 namespace. Hooks do not use Location Profile.
  hooks:
    # The Kanister action referenced by preHook will be executed before
    # other phases of the ExportAction. Optional.
    preHook:
      blueprint: export-hook-blueprint
      actionName: before-export
    # The Kanister action referenced by onSuccess will be executed once all
    # other phases in the ExportAction have completed successfully. Optional.
    onSuccess:
      blueprint: export-hook-blueprint
      actionName: on-success
    # The Kanister action referenced by onFailure will be executed only
    # when the ExportAction fails and exhausts all retries. Optional.
    onFailure:
      blueprint: export-hook-blueprint
      actionName: on-failure

# Status of the action. Users should not set directly.
status:
  # State of the action. Always present.
  # Valid values are:
  # Pending - action has been created
  # Running - action has been validated and is running
  # AttemptFailed - at least one action phase needs to retry
  # Failed - action has failed (at least one phase failed permanently)
  # Complete - action has completed successfully
  # Skipped - action has been skipped
  # Deleting - action is being deleted
  state: Complete
  # Initial start time of action. Always present.
  startTime: "2019-02-11T05:10:45Z"
  # End time of action. Can be 'null' if action still running. Always present.
  endTime: "2019-02-11T05:13:10Z"
  # Error associated with the action.
  # Only included if the action does not succeed.
  error:
    message: Sample error message
  # List of exceptions associated with the action.
  # Only included if exceptions are present.
  exceptions:
    - message: Sample exception message

ExportAction Details API Type

The specification for actionDetails for ExportAction API is the same as the actionDetails section of the BackupAction API.

ImportAction

Currently ImportAction can only be initiated as part of a policy. See Create Import Policy for details.

You can still use ImportAction to check status, get details, and delete completed actions the same way you would for any other action type.

ImportAction API Type

The following is a complete specification of the ImportAction API.

Note

This can only be created by policy at this point.

# Standard Kubernetes API Version declaration. Required.
apiVersion: actions.kio.kasten.io/v1alpha1
# Standard Kubernetes Kind declaration. Required.
# Must be ImportAction
kind: ImportAction
metadata:
  # Kubernetes labels.
  # The following labels will be auto-populated upon creation.
  # These labels can be used for filtering when getting actions.
  # Any additional custom labels can be specified if desired.
  labels:
    # Populated for policy initiated RestoreAction only.
    k10.kasten.io/policyName: "sample-originating-policy"
    k10.kasten.io/policyNamespace: "namespace-of-policy"
    # Populated for on-demand and policy initiated actions
    k10.kasten.io/appName: "sample-app"
    k10.kasten.io/appNamespace: "sample-app"
    # Populated for on-demand RunActions and policy initiated actions
    k10.kasten.io/runActionName: "run-lhr7n6j8dw"
  # Action name. May be any valid Kubernetes object name. Required.
  # Name is not mutable once created.
  name: import-action-example
  # Action namespace. Required.
  # Namespace will the namespace where K10 is installed.
  namespace: kasten-io
# ImportAction spec. Required.
spec:
  # K10 Location Profile that is used for this import. Required.
  profile:
    # Name of the location profile.
    name: sample-profile
    # Namespace of the location profile.
    # Will always be the the namespace where K10 is installed.
    namespace: kasten-io
  # The receiveString that was specified when initiating the policy.
  receiveString: "xbrd234sampleExportSting123=="
# Status of the action. Users should not set directly.
status:
  # State of the action. Always present.
  # Valid values are:
  # Pending - action has been created
  # Running - action has been validated and is running
  # AttemptFailed - at least one action phase needs to retry
  # Failed - action has failed (at least one phase failed permanently)
  # Complete - action has completed successfully
  # Skipped - action has been skipped
  # Deleting - action is being deleted
  state: Complete
  # Initial start time of action. Always present.
  startTime: "2019-02-11T05:10:45Z"
  # End time of action. Can be 'null' if action still running. Always present.
  endTime: "2019-02-11T05:13:10Z"
  # Reference to the RestorePointContent created by the import
  # Present on successful import.
  restorePointContent:
    # Name of the generated RestorePointContent
    name: imported-app-restore-point-content
    # Namespace for the RestorePointContent
    # All restore point contents reside in the K10 install namespace.
    namespace: kasten-io
  # Error associated with the action.
  # Only included if the action does not succeed.
  error:
    message: Sample error message
  # List of exceptions associated with the action.
  # Only included if exceptions are present.
  exceptions:
    - message: Sample exception message

ImportAction Details API Type

The specification for actionDetails for ImportAction API is the same as the actionDetails section of the BackupAction API.

BackupClusterAction

Backup cluster actions are used to initiate backup operations on cluster-scoped resources. A backup cluster action can be submitted as part of a policy or as a standalone action.

Backup cluster actions are non-namespaced.

BackupClusterAction List Example

The following example illustrates listing all BackupClusterActions.

# list backup cluster actions
$ kubectl get backupclusteractions.actions.kio.kasten.io
NAME                          CREATED AT
scheduled-6b5s8               2020-12-29T23:57:20Z
scheduled-szmhn               2020-12-28T23:57:16Z
backup-cluster-action-j2brg   2020-12-23T00:20:41Z
scheduled-h7qzd               2020-12-23T00:10:44Z

BackupClusterAction API Type

The following is a complete specification of the BackupClusterAction API.

# Standard Kubernetes API Version declaration. Required.
apiVersion: actions.kio.kasten.io/v1alpha1
# Standard Kubernetes Kind declaration. Required.
kind: BackupClusterAction
metadata:
  # Kubernetes labels.
  # The following labels will be auto-populated upon creation.
  # These labels can be used for filtering when getting actions.
  # Any additional custom labels can be specified if desired.
  labels:
    # Populated for policy initiated BackupClusterAction only.
    k10.kasten.io/policyName: "sample-originating-policy"
    k10.kasten.io/policyNamespace: "namespace-of-policy"
  # BackupClusterAction name. May be any valid Kubernetes object name. Required.
  # BackupClusterAction name is not mutable once created.
  name: backup-cluster-action-example
  # BackupClusterAction names must be unique and as an alternative to name above
  # one can take advantage of Kubernetes auto name generation
  generateName: backup-cluster-action-
# BackupClusterAction spec. Required.
spec:
  # Scheduled time of action when initiated by policy. Optional.
  scheduledTime: "2019-02-11T05:10:45Z"
  # Filters describe which Kubernetes resources should be included or excluded
  # in the backup. If no filters are specified, default cluster-scoped
  # resources are captured by the BackupClusterAction.
  #
  # Resource types are identified by group, version, and resource type names,
  # or GVR, e.g. rbac.authorization.k8s.io/v1/clusterroles.
  #
  # Individual resources are identified by their resource type and resource
  # name, or GVRN. In a filter, an empty or omitted group, version, resource
  # type or resource name matches any value.
  #
  # Filters reduce the resources in the backup by selectively including and
  # then excluding resources.
  # - If includeClusterResources is not specified, default cluster-scoped
  #   resources are included in the set of resources to be backed up.
  # - If includeClusterResources is specified, cluster-scoped resources
  #   matching any GVRN entry in includeClusterResources are included in
  #   the set of resources to be backed up.
  # - If excludeClusterResources is specified, cluster-scoped resources
  #   matching any GVRN entry in excludeClusterResources are excluded from
  #   the set of resources to be backed up.
  filters:
    # Include only resources that match any of the following NGVRs
    includeClusterResources:
      # Include individual resource
    - name: <resource1 resource name>
      group: <resource1 group>
      version: <resource1 version>
      resource: <resource1 type name>
      # Include resource type
    - group: <resource2 group>
      version: <resource2 version>
      resource: <resource2 type name>
    # Exclude resources that match any of the following NGVRs
    excludeClusterResources:
      # Exclude specific instance of resource2 type
    - name: <resource2 resource name>
      group: <resource2 group>
      version: <resource2 version>
      resource: <resource2 type name>
# Status of the action. Users should not set directly.
status:
  # State of the action. Always present.
  # Valid values are:
  # Pending - action has been created
  # Running - action has been validated and is running
  # AttemptFailed - at least one action phase needs to retry
  # Failed - action has failed (at least one phase failed permanently)
  # Complete - action has completed successfully
  # Skipped - action has been skipped
  # Deleting - action is being deleted
  state: Complete
  # Initial start time of action. Always present.
  startTime: "2019-02-11T05:10:45Z"
  # End time of action. Can be 'null' if action still running. Always present.
  endTime: "2019-02-11T05:13:10Z"
  # RestorePoint created by a successful action.
  # Always present when the action succeeds.
  restorePoint:
    # Name of the cluster restore point.
    name: backup-cluster-action-example-restorepoint
  # Error associated with the action.
  # Only included if the action does not succeed.
  error:
    message: Sample error message
  # List of exceptions associated with the action.
  # Only included if exceptions are present.
  exceptions:
    - message: Sample exception message

RestoreClusterAction

Restore cluster actions are used to restore cluster-scoped resources from a ClusterRestorePoint. A restore cluster action can be submitted as part of a policy or as a standalone action.

Restore cluster actions are non-namespaced.

RestoreClusterAction List Example

The following example illustrates listing all RestoreClusterActions.

# list restore cluster actions
$ kubectl get restoreclusteractions.actions.kio.kasten.io
NAME                          CREATED AT
scheduled-6b5s8               2020-12-29T23:57:20Z
scheduled-szmhn               2020-12-28T23:57:16Z
restore-cluster-action-j2brg  2020-12-23T00:20:41Z
scheduled-h7qzd               2020-12-23T00:10:44Z

RestoreClusterAction API Type

The following is a complete specification of the RestoreClusterAction API.

# Standard Kubernetes API Version declaration. Required.
apiVersion: actions.kio.kasten.io/v1alpha1
# Standard Kubernetes Kind declaration. Required.
kind: RestoreClusterAction
metadata:
  # Kubernetes labels.
  # The following labels will be auto-populated upon creation.
  # These labels can be used for filtering when getting actions.
  # Any additional custom labels can be specified if desired.
  labels:
    # Populated for policy initiated BackupClusterAction only.
    k10.kasten.io/policyName: "sample-originating-policy"
    k10.kasten.io/policyNamespace: "namespace-of-policy"
  # RestoreClusterAction name. May be any valid Kubernetes object name. Required.
  # RestoreClusterAction name is not mutable once created.
  name: restore-cluster-action-example
  # RestoreClusterAction names must be unique and as an alternative to name above
  # one can take advantage of Kubernetes auto name generation
  generateName: restore-cluster-action-
# RestoreClusterAction spec. Required.
spec:
  # Scheduled time of action when initiated by policy. Optional.
  scheduledTime: "2019-02-11T05:10:45Z"
  # Target ClusterRestorePoint to be used. Required.
  # The caller needs to have read permission for the ClusterRestorePoint
  # API object below.
  subject:
    # Standard Kubernetes kind declaration. Required.
    # Must be 'ClusterRestorePoint'
    kind: ClusterRestorePoint
    # Name of the cluster restore point to use. Required.
    name: sample-cluster-restore-point
  # Optional: Filters describe which Kubernetes resources should be restored
  # from the ClusterRestorePoint.  If no filters are specified, all the
  # artifacts in the ClusterRestorePoint are restored.
  #
  # Filters reduce the resources restored by selectively including and then
  # excluding resources.
  # - If includeClusterResources is not specified, all resources in the
  #   ClusterRestorePoint are included in the set of resources to be restored.
  # - If includeClusterResources is specified, resources matching any GVRN entry
  #   are included in the set of resources to be restored.
  # - If excludeClusterResources is specified, resources matching any GVRN entry
  #   are excluded from the set of resources to be restored.
  # - In a filter, an empty or omitted group, version, resource type or
  #   resource name matches any value.
  filters:
    # Include only resources that match any of the following NGVRs
    includeClusterResources:
      # Include individual resource
    - name: <resource1 resource name>
      group: <resource1 group>
      version: <resource1 version>
      resource: <resource1 type name>
      # Include resource type
    - group: <resource2 group>
      version: <resource2 version>
      resource: <resource2 type name>
    # Exclude resources that match any of the following NGVRs
    excludeClusterResources:
      # Exclude specific instance of resource2 type
    - name: <resource2 resource name>
      group: <resource2 group>
      version: <resource2 version>
      resource: <resource2 type name>
  # perform transformations on kubernetes resources
  transforms:
  - subject:
      # Group, version, resource and/or name of the resource for transformation
      name: <resource name>
      group: <resource group>
      version: <resource version>
      resource: <resource type name>
    # perform JSON patch transformation
    json:
      # `json` JSON patch document object used to perform a JSON patch transform
      # supports the following transformations
      #
      # add - add a new element at the "path" with "value" to resource
      #       definition.  if element at "path" is an existing map element
      #       it will be replaced.
      # remove - remove element at "path" from resource definition.  path
      #          must exist.
      # replace - replace element at "path" with "value".  like 'remove' then 'add'
      # move - move the element at "from" to "path" replacing element at
      #        "path" if it exists
      # copy - copy the element at "from" to "path".  value will be replaced if
      #        if it is an existing map element
      # test - test that element at "path" equals "value"
    - op: test
      # reference for operation.  mandatory.
      path: 'metadata/labels/release'
    - op: copy
      # source reference for operation.  only valid for the 'move' and 'copy' operations
      from: 'metadata/labels/release'
      # target reference for operation.  mandatory.
      path: 'spec/template/metadata/labels/release'
      # apply regex to match expression.  Valid for 'remove', 'replace', 'move',
      # 'copy' and 'test'.
      regex: 'prod-v.*'
      # value is any json structure.  only valid for 'add', 'replace'
      # and 'test' operation
      value: 'prod'
# Status of the action. Users should not set directly.
status:
  # State of the action. Always present.
  # Valid values are:
  # Pending - action has been created
  # Running - action has been validated and is running
  # AttemptFailed - at least one action phase needs to retry
  # Failed - action has failed (at least one phase failed permanently)
  # Complete - action has completed successfully
  # Skipped - action has been skipped
  # Deleting - action is being deleted
  state: Complete
  # Initial start time of action. Always present.
  startTime: "2019-02-11T05:10:45Z"
  # End time of action. Can be 'null' if action still running. Always present.
  endTime: "2019-02-11T05:13:10Z"
  # Error associated with the action.
  # Only included if the action does not succeed.
  error:
    message: Sample error message
  # List of exceptions associated with the action.
  # Only included if exceptions are present.
  exceptions:
    - message: Sample exception message

RunAction

RunActions are used for manual execution and monitoring of actions related to policy runs.

Create RunAction Example

The following example illustrates how to initiate a manual execution of a policy called backup-policy.

$ cat > sample-run-action.yaml <<EOF
apiVersion: actions.kio.kasten.io/v1alpha1
kind: RunAction
metadata:
  generateName: run-backup-
spec:
  subject:
    kind: Policy
    name: backup-policy
    namespace: kasten-io
EOF

$ kubectl create -f sample-run-action.yaml
actions.kio.kasten.io/run-backup-th7z23 created

Check Status of RunAction Example

Any execution of a policy will create a RunAction. After creating a RunAction, K10 will validate the action and will proceed with execution of the subject policy actions. The action can be used to verify the execution status.

$ kubectl get runactions.actions.kio.kasten.io run-backup-th7z23 -ojsonpath="{.status.state}{'\n'}"
Running

Check Status of actions subordinate to RunAction Example

Once started, a RunAction will create subordinate actions to perform the work outlined in the subject policy actions. These can be retrieved by filtering on the label k10.kasten.io/runActionName.

$ kubectl get backupactions.actions.kio.kasten.io -l 'k10.kasten.io/runActionName=run-backup-th7z23' -ojsonpath="{range .items[*]}{.metadata.name}:{.metadata.namespace} {.status.state}{'\n'}{end}"
scheduled-jrwp2:ns-f9e74035 Running
scheduled-prb5g:ns-697a6a0a Running
scheduled-r9sts:ns-5615d5f3 Complete
scheduled-w7q5p:ns-7a7d5da7 Complete
scheduled-2lcjk:ns-e96562c5 Running
scheduled-tchl4:ns-b6bf19f2 Complete

RunAction Delete Example

Once a RunAction is complete, successfully or otherwise, it is possible to delete the action. Deleting the action has no effect on the underlying operations performed by the policy execution

$ kubectl delete runactions.actions.kio.kasten.io run-backup-th7z23
actions.kio.kasten.io/run-backup-th7z23 deleted

RunAction List Example

The following example illustrates listing all RunActions

# list run actions
$ kubectl get runactions.actions.kio.kasten.io
NAME                              AGE
run-backup-th7z23                 1h
run-backup-t99ha8                 2h

RunAction API Type

The following is a complete specification of the RunAction API.

# Standard Kubernetes API Version declaration. Required.
apiVersion: actions.kio.kasten.io/v1alpha1
# Standard Kubernetes Kind declaration. Required.
kind: RunAction
metadata:
  # RunAction name. May be any valid Kubernetes object name. Required.
  # RunAction name is not mutable once created.
  name: run-action-example
  # RunAction names must be unique and as an alternative to name above
  # one can take advantage of Kubernetes auto name generation
  generateName: run-action-
# RunAction spec. Required.
spec:
  # Target Policy to be used. Required.
  # The caller needs to have read permission for the Policy API
  # in the namespace below.
  subject:
    # Standard Kubernetes kind declaration. Required.
    # Must be 'Policy'
    kind: Policy
    # Name of the policy to use. Required.
    name: sample-policy
    # Namespace of the policy. Required. Must be namespace where
    # K10 is installed
    namespace: kasten-io
# Status of the action. Users should not set directly.
status:
  # portions of the Policy used to construct subordinate actions (eg. BackupActions and ExportActions).
  # For complete structure of RunAction policy spec, refer to :ref:`Policy API Type<policy_api_type>`
  policySpec:
    actions:
    # Policy parameters used to construct subordinate actions
    - action: backup
    - action: export
    selector:
      matchLabels:
        k10.kasten.io/appNamespace: sampleApp
  # State of the action. Always present.
  # Valid values are:
  # Pending - action has been created
  # Running - action has been validated and is running
  # AttemptFailed - at least one action phase needs to retry
  # Failed - action has failed (at least one phase failed permanently)
  # Complete - action has completed successfully
  # Skipped - action has been skipped
  # Deleting - action is being deleted
  state: Complete
  # Initial start time of action. Always present.
  startTime: "2019-02-11T05:10:45Z"
  # End time of action. Can be 'null' if action still running. Always present.
  endTime: "2019-02-11T05:13:10Z"
  # Error associated with the action.
  # Only included if the action does not succeed.
  error:
    message: Sample error message
  # List of exceptions associated with the action.
  # Only included if exceptions are present.
  exceptions:
    - message: Sample exception message

RetireAction

Currently RetireAction can only be initiated by a policy or by the deletion of a RestorePointContent.

When a RestorePoint created by one or more policies is no longer retained by at least one policy or when a RestorePointContent is deleted using the API, a RetireAction is initiated.

See Create Backup Policy and RestorePointContent for more details.

You can use the RetireAction to check status and delete completed actions the same way you would for any other action type.

Retire actions are non-namespaced.

RetireAction List Example

The following example illustrates listing all RetireActions

$ kubectl get retireactions.actions.kio.kasten.io
NAME                                         CREATED AT
retire-mysql-manualbackup-n4xfs-rbfb9        2021-01-26T17:19:32Z
retire-mysql-manualbackup-n4xfsvlw54-k8d59   2021-01-26T17:15:06Z

Check Status of RetireAction Example

The following example illustrates querying one of the RetireActions for its current status.

$ kubectl get retireactions.actions.kio.kasten.io retire-mysql-manualbackup-n4xfs-rbfb9 -ojsonpath="{.status.state}{'\n'}"
Complete

RetireAction Details Example

The following example illustrates querying one of the RetireActions for more details.

# get the details for action 'retire-mysql-manualbackup-n4xfs-rbfb9'
# yq only used for readability
$ kubectl get --raw /apis/actions.kio.kasten.io/v1alpha1/retireactions/retire-mysql-manualbackup-n4xfs-rbfb9/details | yq -y .status.actionDetails

# output is analogous to that for BackupAction

RetireAction API Type

The following is a complete specification of the RetireAction API.

Note

This can only be created by a policy's retire action or deletion of a restore point content at this point.

# Standard Kubernetes API Version declaration. Required.
apiVersion: actions.kio.kasten.io/v1alpha1
# Standard Kubernetes Kind declaration. Required.
# Must be RetireAction
kind: RetireAction
metadata:
  # Kubernetes labels.
  # The following labels will be auto-populated upon creation.
  # These labels can be used for filtering when getting actions.
  # Any additional custom labels can be specified if desired.
  labels:
    # Populated for policy initiated RetireAction only.
    k10.kasten.io/policyName: "sample-originating-policy"
    k10.kasten.io/policyNamespace: "namespace-of-policy"
  # Action name. May be any valid Kubernetes object name. Required.
  # Name is not mutable once created.
  name: retire-action-example
# RetireAction spec. Required.
spec:
  # Scheduled time of the action that created the RestorePointContent
  scheduledTime: "2019-02-11T05:10:45Z"
# Status of the action. Users should not set directly.
status:
  # State of the action. Always present.
  # Valid values are:
  # Pending - action has been created
  # Running - action has been validated and is running
  # AttemptFailed - at least one action phase needs to retry
  # Failed - action has failed (at least one phase failed permanently)
  # Complete - action has completed successfully
  # Skipped - action has been skipped
  # Deleting - action is being deleted
  state: Complete
  # Initial start time of action. Always present.
  startTime: "2019-02-11T05:10:45Z"
  # End time of action. Can be 'null' if action still running. Always present.
  endTime: "2019-02-11T05:13:10Z"
  # Error associated with the action.
  # Only included if the action does not succeed.
  error:
    message: Sample error message
  # List of exceptions associated with the action.
  # Only included if exceptions are present.
  exceptions:
    - message: Sample exception message

RetireAction Details API Type

The specification for actionDetails for the RetireAction API is the same as the actionDetails section of the BackupAction API.

CancelAction

CancelActions are created to halt progress of another action and prevent any remaining retries. Cancellation is best effort and not every phase of an Action may be cancellable. When an action is cancelled, its state becomes Cancelled.

Note

CancelActions are limited API Objects. Only the create method is supported and CancelActions are not persisted. To see the effect of a CancelAction, check the status of the target action.

CancelAction API Type

The following is a complete specification of the CancelAction API.

# Standard Kubernetes API Version declaration. Required.
apiVersion: actions.kio.kasten.io/v1alpha1
# Standard Kubernetes Kind declaration. Required.
# Must be CancelAction
kind: CancelAction
metadata:
  # Action name. May be any valid Kubernetes object name.
  # Name or generateName is required.
  name: cancel-action-example
  generateName: cancel-action-
  # Action namespace. Required to be same as namespace
  # of action to be cancelled, if that action is namespaced.
  # Required to be K10 namespace if action to be cancelled
  # is not namespaced.
  namespace: sample-app
# CancelAction spec. Required.
spec:
  subject:
    # Kind of the Action to be cancelled. Required.
    # Valid values are:
    # BackupAction
    # RestoreAction
    # ImportAction
    # ExportAction
    # RetireAction (not namespaced)
    # RunAction (not namespaced)
    kind: BackupAction
    # Name of the Action to be cancelled. Required.
    name: sample-action
    # Namespace of the Action to be cancelled. Required.
    namespace: sample-app

ReportAction

A ReportAction resource is created to generate a K10 Report and provide insights into system performance and status. A successful ReportAction produces a K10 Report that contains information gathered at the time of the ReportAction.

ReportAction API Type

The following is a complete specification of the ReportAction API.

# Standard Kubernetes API Version declaration. Required.
apiVersion: actions.kio.kasten.io/v1alpha1
# Standard Kubernetes Kind declaration. Required.
kind: ReportAction
metadata:
  # Action name. May be any valid Kubernetes object name.
  # Name or generateName is required.
  name: report-action-example
  generateName: report-action-
  # Action namespace. Currently required to be K10 namespace.
  namespace: kasten-io
spec:
  # Subject specifies scope of Report to be generated.
  # Currently must specify K10 namespace for system Report.
  subject:
    name: kasten-io
    namespace: kasten-io
  # Scheduled time of action when initiated by policy. Optional.
  scheduledTime: "2021-10-11T05:10:45Z"
  # Reports include metrics collected by the K10 Prometheus service
  # and queried over an interval up to the time of the Report.
  # The query interval must be non-zero and is calculated to be
  # (24 * statsIntervalDays) + statsIntervalHours.
  statsIntervalDays: 1
  statsIntervalHours: 0