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:
# Expiration timestamp in ``RFC3339`` format. Optional.
# Garbage collector will automatically retire expired backups.
expiresAt: "2002-10-02T15:00:00Z"
# 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
# Action execution progress represented as an integer percentage value in range between 0 and 100. Optional.
progress: 88
# 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"
# Last updated time of the phase.
updatedTime: "2019-02-11T03:03:48Z"
# 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.
# get the state of action 'restore-mysql-afr823' created in the 'mysql' namespace
$ kubectl get -n mysql restoreaction 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 the '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 with the addition of the volume operation details in the 'actionDetails.phases' section
phases:
- attempt: 1
endTime: '2024-05-28T22:01:35Z'
name: Restoring Application Components
startTime: '2024-05-28T21:59:42Z'
state: succeeded
updatedTime: '2024-05-28T22:01:35Z'
volumeOperations:
- namespace: mysql
pvcName: pvc0
operation: Download
dataFormat: Block
driver: openshift-storage.rbd.csi.ceph.com
storageClass: ocs-storagecluster-ceph-rbd
storageType: CSI
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 overwrite existing resources to their
# state in the restore point.
# Default: false
overwriteExisting: false
# Optional: set to true to only restore the application data to its original location
# by overwriting existing PVC and re-scaling workloads.
# Must be false if filters are specified.
# Default: false
dataOnly: false
# Optional: set to true to only restore the application data as a cloned volume
# without overwriting existing PVC and re-scaling workloads.
# Can be true if filters are specified.
# Default: false
volumeClones: false
# Optional: Request for Instant Recovery process. The restored application
# will run from network volumes. Available only for block mode exports
# in VBR 11+ when using a supported vSphere CSI driver.
# The operation will fail if these requirements are not met.
instantRecovery: false
# Optional for normal RestoreActions but required if 'instantRecovery'
# is set to 'true'. Defines the name or Id of a datastore where the FCD
# volumes will be migrated after a successful Instant Recovery process.
targetVsphereStorage:
# 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
# The list of transforms. Optional.
# Each transform can be defined inline or in a referenced transform set.
transforms:
# Specifies which resource artifacts to apply this transform to. Required.
# At least one filter should be set.
- subject:
# Resource group. Optional.
group: apps
# Resource version. Optional.
version: v1
# Resource type. Optional.
resource: deployments
# Resource name. Optional.
name: my-app
# The name of the transform. Optional.
name: 'copyRelease'
# An array of RFC-6902 JSON patch-like operations. Required.
# It can be an empty array if the transform references a transform set.
json:
# Operation name. Required.
# Transforms support six command operations:
# # 'test' - checks that an element exists (and equals the value / matches the regexp if specified)
# # 'add' - inserts a new element to the resource definition
# # 'remove' - deletes an existing element from the resource definition
# # 'copy' - duplicates an element, overwriting the value in the new path if it already exists
# # 'move' - relocates an element, overwriting the value in the new path if it already exists
# # 'replace' - replaces an existing element with a new element
- op: copy
# Source reference for operation. Optional.
# Required and valid only for 'move' and 'copy' operations.
from: '/metadata/labels/release'
# Target reference for operation. Required for every operation.
path: '/spec/template/metadata/labels/release'
# Regex to match expression. Optional.
# When used with 'copy', 'move' or 'replace' operation,
# the transform will match the target text against the `regex`
# and substitute regex capturing groups with `value`.
# When used with 'test' operation,
# the transform will match the target text against the `regex`.
regex: 'prod-v.*'
# Value is any valid JSON. Optional.
# Required for 'add' and 'replace' operations.
# Required for 'copy' and 'move' operations only when used along with `regex`.
# 'test' operation can use either `regex` or `value`.
value: 'prod'
# Transform set to be used instead of in-place JSON specification. Optional.
transformSetRef:
name: copy-release-transformset
namespace: kasten-io
# 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.
BatchRestoreAction
Batch restore actions are used to restore multiple applications to a known-good state from their restore points.
Create BatchRestoreAction Example
The following example illustrates how to initiate a batch restore for multiple applications from their latest restore points.
Note
Batch restore actions can be created only
in the namespace where K10 is installed.
$ cat > sample-batch-restore-action.yaml <<EOF
apiVersion: actions.kio.kasten.io/v1alpha1
kind: BatchRestoreAction
metadata:
generateName: batchrestore-
namespace: kasten-io
spec:
subjects:
- namespace: mysql
- namespace: nginx
- namespace: sample-app
EOF
$ kubectl create -f sample-batch-restore-action.yaml
batchrestoreactions.actions.kio.kasten.io/batchrestore-z82gt created
Check Status of BatchRestoreAction Example
After creating a BatchRestoreAction, K10 will validate the action and proceed with execution. The action can be used to verify the execution status.
$ kubectl get batchrestoreactions.actions.kio.kasten.io batchrestore-z82gt --namespace kasten-io -o jsonpath="{.status.state}{'\n'}"
Running
Check Status of actions subordinate to BatchRestoreAction Example
Once started, a BatchRestoreAction will attempt to create a subordinate restore action for each specified subject. These can be retrieved by filtering on the label k10.kasten.io/batchRestoreActionName.
$ kubectl get restoreactions.actions.kio.kasten.io -l 'k10.kasten.io/batchRestoreActionName=batchrestore-z82gt' -o jsonpath="{range .items[*]}{.metadata.name}:{.metadata.namespace} {.status.state}{'\n'}{end}"
scheduled-lsj8x:mysql Running
scheduled-ir29k:nginx Complete
scheduled-p9ako:sample-app Failed
BatchRestoreAction Details Example
In addition to checking the status of a BatchRestoreAction, it may be useful to query the details associated with the action. For this purpose, use the details sub-resource, which includes quantitative statistics on subordinate actions, a list of successfully restored applications, and a list of applications that failed to be restored.
# get the details for action 'batchrestore-z82gt'
# yq only used for readability
$ kubectl get --raw /apis/actions.kio.kasten.io/v1alpha1/namespaces/kasten-io/batchrestoreactions/batchrestore-z82gt/details | yq -y .status.actionDetails
actions:
total: 3
cancelled: 0
running: 1
failed: 1
skipped: 0
completed: 1
pending: 0
subjectsCount: 3
restoredApplications:
- nginx
failedApplications:
- sample-app
BatchRestoreAction List Example
The following example illustrates listing all BatchRestoreActions.
$ kubectl get batchrestoreactions.actions.kio.kasten.io --all-namespaces
NAMESPACE NAME CREATED AT STATE PCT SUBJECTS
kasten-io batchrestore-z82gt 2023-10-03T18:33:42Z Complete 100 3
kasten-io batchrestore-jtjwg 2023-10-03T16:21:37Z Complete 100 7
BatchRestoreAction Delete Example
Once a BatchRestoreAction is complete, successfully or otherwise, it is possible to delete the action. Deleting the action has no effect on the underlying operations performed during the execution.
$ kubectl delete batchrestoreactions.actions.kio.kasten.io batchrestore-z82gt --namespace kasten-io
batchrestoreactions.kio.kasten.io/batchrestore-z82gt deleted
BatchRestoreAction API Type
The following is a complete specification of the BatchRestoreAction API.
# Standard Kubernetes API Version declaration. Required.
apiVersion: actions.kio.kasten.io/v1alpha1
# Standard Kubernetes Kind declaration. Required.
kind: BatchRestoreAction
metadata:
# BatchRestoreAction name. May be any valid Kubernetes object name.
# Required if generateName (below) is not specified.
# BatchRestoreAction name is not mutable once created.
name: batchrestore-example
# BatchRestoreAction names must be unique and as an alternative to name above
# one can take advantage of Kubernetes auto name generation.
generateName: batchrestore-
# BatchRestoreAction namespace. Required.
# Must be the namespace where K10 is installed.
namespace: kasten-io
# BatchRestoreAction spec. Required.
spec:
# Prefix to be added to the namespace
# where the application is to be restored. Optional.
# If used and the target namespace does not yet exist,
# the user creating the resource will need to have
# create permission on namespaces.
targetNamespacePrefix: copy-
# Suffix to be added to the namespace
# where the application is to be restored. Optional.
# If used and the target namespace does not yet exist,
# the user creating the resource will need to have
# create permission on namespaces.
targetNamespaceSuffix: -1
# List of applications to be restored. Required.
subjects:
# Namespace of the application. Required.
# The user creating the resource needs to have create permission
# for the RestoreAction API in the target namespace.
# To restore cluster-scoped resources, use a special value `kasten-io-cluster`.
- namespace: mysql
# Name of the restore point to use. Optional.
# If used, the user creating the resource will need to have
# get permission on this restore point.
# If not provided, K10 will use the latest restore point available
# for the specified namespace and the user will need to have list
# permission on RestorePoint API in the specified namespace.
restorePointName: scheduled-m8zkn
# Name of the restore point content to use. Optional.
# Useful when restoring a deleted application for which
# a restore point was once created and then deleted
# along with the application namespace.
# If used, the user creating the resource will need to have
# get permission on this restore point content.
# If the specified restore point content is in an `Unbound` state
# (references a restore point that does not exist),
# the user creating the resource will also need to have
# create permission on RestorePoint API in the target namespace.
# If not provided and the namespace being restored does not exist,
# the user will need to have list permission on RestorePointContent API.
restorePointContentName: mysql-scheduled-m8zkn
# Date range in which K10 will search for the latest restore point
# (or restore point content) for subjects that specify
# neither restore point name nor restore point content name. Optional.
restorePointsDiscoveryRange:
# Start of the date range. Optional.
- start: "2023-10-01T08:00:00Z"
# End of the date range. Optional.
- end: "2023-10-02T11:00:00Z"
# Set to true to overwrite existing resources to their
# state in the restore point. Optional.
# Default: false.
overwriteExisting: false
# Optional: set to true to only restore the application data to its original location
# by overwriting existing PVC and re-scaling workloads.
# Must be false if filters are specified.
# Default: false.
dataOnly: false
# Optional: set to true to only restore the application data as a cloned volume
# without overwriting existing PVC and re-scaling workloads.
# Can be true if filters are specified.
# Default: false.
volumeClones: false
# Filters describe which Kubernetes resources should be restored
# from the RestorePoint. If no filters are specified, all the artifacts
# in the RestorePoint are restored. Optional.
# Check RestoreAction API Type for more details.
#
# 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 GVRNs 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 GVRNs 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>
# The list of transforms. Optional.
# Each transform can be defined inline or in a referenced transform set.
transforms:
# Specifies which resource artifacts to apply this transform to. Required.
# At least one filter should be set.
- subject:
# Resource group. Optional.
group: apps
# Resource version. Optional.
version: v1
# Resource type. Optional.
resource: deployments
# Resource name. Optional.
name: my-app
# The name of the transform. Optional.
name: 'copyRelease'
# An array of RFC-6902 JSON patch-like operations. Required.
# It can be an empty array if the transform references a transform set.
json:
# Operation name. Required.
# Transforms support six command operations:
# # 'test' - checks that an element exists (and equals the value / matches the regexp if specified)
# # 'add' - inserts a new element to the resource definition
# # 'remove' - deletes an existing element from the resource definition
# # 'copy' - duplicates an element, overwriting the value in the new path if it already exists
# # 'move' - relocates an element, overwriting the value in the new path if it already exists
# # 'replace' - replaces an existing element with a new element
- op: copy
# Source reference for operation. Optional.
# Required and valid only for 'move' and 'copy' operations.
from: '/metadata/labels/release'
# Target reference for operation. Required for every operation.
path: '/spec/template/metadata/labels/release'
# Regex to match expression. Optional.
# When used with 'copy', 'move' or 'replace' operation,
# the transform will match the target text against the `regex`
# and substitute regex capturing groups with `value`.
# When used with 'test' operation,
# the transform will match the target text against the `regex`.
regex: 'prod-v.*'
# Value is any valid JSON. Optional.
# Required for 'add' and 'replace' operations.
# Required for 'copy' and 'move' operations only when used along with `regex`.
# 'test' operation can use either `regex` or `value`.
value: 'prod'
# Transform set to be used instead of in-place JSON specification. Optional.
transformSetRef:
name: copy-release-transformset
namespace: kasten-io
# Specifies whether the subordinate restore actions should wait for all
# workloads (Deployments, StatefulSets or DeploymentConfigs)
# to be ready before completing. Optional.
# Default: false.
skipWaitForWorkloadReady: false
# Hooks are Kanister actions executed first or last in each subordinate 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. Optional.
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 (no any application has been restored)
# Complete - action has completed successfully
state: Complete
# Initial start time of action. Always present.
startTime: "2023-02-10T15:12:35Z"
# End time of action. Can be 'null' if action still running. Always present.
endTime: "2023-02-10T15:13:04Z"
# Error associated with the action.
# Only included if the action does not succeed.
error:
message: <error message>
# List of exceptions associated with the action.
# Only included if exceptions are present.
exceptions:
- message: <exception message>
# Action execution progress represented as an integer
# percentage value in range between 0 and 100. Optional.
progress: 100
BatchRestoreAction Details API Type
The following is a complete specification of the status.actionDetails section of the BatchRestoreAction API. These fields are only available in the BatchRestoreAction API when the details sub-resource is used, as shown in the example above.
apiVersion: actions.kio.kasten.io/v1alpha1
kind: BatchRestoreAction
...
spec:
...
status:
...
# Details section of the action resource.
# Included when the details sub-resource is queried.
actionDetails:
# Amount of subordinate actions per their state.
actions:
total: 3
cancelled: 0
running: 0
failed: 1
skipped: 0
completed: 2
pending: 0
# Amount of subjects specified for this action.
subjectsCount: 3
# List of successfully restored applications. Always present.
restoredApplications:
- mysql
- nginx
# List of applications that failed to be restored.
# Only included when there are such applications.
failedApplications:
- sample-app
ExportAction
Export actions are used to initiate an export of an application to a different cluster using an existing restore point.
Note
The snapshot creation process completes without generating output artifacts if all the resources are deselected. Attempting to export the snapshot fails with the error message "No artifacts provided." Therefore, for a successful export, including at least one resource is crucial when creating a snapshot.
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:
# Expiration timestamp in ``RFC3339`` format. Optional.
# Garbage collector will automatically retire expired exports if this field is set.
expiresAt: "2002-10-02T15:00:00Z"
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
Snapshot data from a volume provisioned by the vSphere CSI driver
in a supported vSphere cluster
can be exported to a
Veeam Repository
by adding a reference to a
Veeam Repository Location Profile
in the blockModeProfile field.
The remaining data associated with the K10 restore point is saved
in the location profile identified by the profile field.
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 -n mysql 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 receiveString that is generated to identify the export. This will be used when initiating an import on the other cluster.
# get the receive string for action 'export-mysql-brd911' created in the 'mysql' namespace
$ kubectl get -n mysql exportactions.actions.kio.kasten.io export-mysql-brd911 -ojsonpath="{.spec.receiveString}{'\n'}"
bIzAPpoanmFUkXV/lh1KoM...Cg5Mov3xvqgpCbL73levOuISe553w
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 the 'mysql' namespace
# yq only used for readability
$ kubectl get --raw /apis/actions.kio.kasten.io/v1alpha1/namespaces/mysql/exportactions/export-mysql-brd911/details | yq -y .status.actionDetails
# output is analogous to that for BackupAction with the addition of volume operation details in the 'actionDetails.phases' section
phases:
- attempt: 1
endTime: '2024-05-28T21:29:51Z'
name: Exporting RestorePoint
startTime: '2024-05-28T21:28:35Z'
state: succeeded
updatedTime: '2024-05-28T21:29:51Z'
volumeOperations:
- namespace: mysql
pvcName: pvc0
operation: Upload
dataFormat: Block
exportDirective: FileSystemMayExportInBlockMode
driver: openshift-storage.rbd.csi.ceph.com
storageClass: ocs-storagecluster-ceph-rbd
storageType: CSI
snapshotId: k10-csi-snap-jdn2znqhlqvcck4c
volumeSnapshotClass: ocs-storagecluster-rbdplugin-snapclass
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 receiveString 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 be the namespace where K10 is installed.
namespace: kasten-io
# The blockModeProfile is a reference to a profile that supports block based backup.
# Optional: If set then a block mode backup of snapshot data will be performed
# instead of a filesystem backup.
# This should only be used when the infrastructure also supports block based backup.
blockModeProfile:
# Name of the location profile supporting block mode. Required.
name: my-block-mode-profile
# Namespace of the location profile. Required.
# Must be in 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
# Action execution progress represented as an integer percentage value in range between 0 and 100. Optional.
progress: 88
# Action execution progress details, containing information about amounts of data.
# Progress details are available for export only.
# Export process consists of three operations:
# - reading from disk (readBytes value reflects how much data was read from disk)
# - calculating changes between data on disk and previously exported data (processedBytes value reflects how much data was analyzed).
# Data known to be unchanged since the last export will not be read from disk but will still count as being processed.
# - uploading newly added data (transferredBytes value reflects how much data was uploaded to the export location for the namespace being exported)
progressDetails:
# Total size of the volumes containing data to be exported.
totalBytes: 10000
# Number of bytes which were read.
readBytes: 9000
# Number of bytes which were processed.
processedBytes: 8000
# Number of bytes which were transferred.
transferredBytes: 5000
# Number of bytes processed per second
processingRate: 8000
# Number of volumes to be exported
totalVolumes: 3
# Number of already exported volumes
completedVolumes: 1
# Time stamp when progress details were updated
updatedTime: "2019-02-11T05:13:10Z"
# 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>
# The list of transforms. Optional.
# Each transform can be defined inline or in a referenced transform set.
transforms:
# Specifies which resource artifacts to apply this transform to. Required.
# At least one filter should be set.
- subject:
# Resource group. Optional.
group: apps
# Resource version. Optional.
version: v1
# Resource type. Optional.
resource: deployments
# Resource name. Optional.
name: my-app
# The name of the transform. Optional.
name: 'copyRelease'
# An array of RFC-6902 JSON patch-like operations. Required.
# It can be an empty array if the transform references a transform set.
json:
# Operation name. Required.
# Transforms support six command operations:
# # 'test' - checks that an element exists (and equals the value / matches the regexp if specified)
# # 'add' - inserts a new element to the resource definition
# # 'remove' - deletes an existing element from the resource definition
# # 'copy' - duplicates an element, overwriting the value in the new path if it already exists
# # 'move' - relocates an element, overwriting the value in the new path if it already exists
# # 'replace' - replaces an existing element with a new element
- op: copy
# Source reference for operation. Optional.
# Required and valid only for 'move' and 'copy' operations.
from: '/metadata/labels/release'
# Target reference for operation. Required for every operation.
path: '/spec/template/metadata/labels/release'
# Regex to match expression. Optional.
# When used with 'copy', 'move' or 'replace' operation,
# the transform will match the target text against the `regex`
# and substitute regex capturing groups with `value`.
# When used with 'test' operation,
# the transform will match the target text against the `regex`.
regex: 'prod-v.*'
# Value is any valid JSON. Optional.
# Required for 'add' and 'replace' operations.
# Required for 'copy' and 'move' operations only when used along with `regex`.
# 'test' operation can use either `regex` or `value`.
value: 'prod'
# Transform set to be used instead of in-place JSON specification. Optional.
transformSetRef:
name: copy-release-transformset
namespace: kasten-io
# 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.
Note
Manual policy runs are not subject to Policy Retention
Create RunAction Example
The following example illustrates how to initiate a manual execution
of a policy called backup-policy``in namespace ``app-ns.
$ cat > sample-run-action.yaml <<EOF
apiVersion: actions.kio.kasten.io/v1alpha1
kind: RunAction
metadata:
generateName: run-backup-
namespace: app-ns
spec:
subject:
kind: Policy
name: backup-policy
namespace: app-ns
EOF
$ kubectl create -f sample-run-action.yaml -n app-ns
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 -n app-ns -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 -n app-ns
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 -n app-ns
NAME CREATED AT STATE PCT
run-backup-th7z23 2024-04-03T19:34:06Z Complete 100
run-backup-t99ha8 2024-04-02T19:34:06Z Complete 100
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 namespace must be the same as the policy it references in
# spec.subject.namespace
namespace: app-ns
# RunAction spec. Required.
spec:
# Expiration timestamp in ``RFC3339`` format. Optional.
# Garbage collector will automatically retire expired backups and exports created by this RunAction.
expiresAt: "2002-10-02T15:00:00Z"
# 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: app-ns
# 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, Garbage Collector 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
# RunAction
# RetireAction (not namespaced)
# BackupClusterAction (not namespaced)
# RestoreClusterAction (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
UpgradeAction
An UpgradeAction resource is created to upgrade the backup data and metadata associated with a given Export Policy or Repository.
UpgradeAction API Type
The following is a complete specification for the UpgradeAction API.
# Standard Kubernetes API Version declaration. Required.
apiVersion: actions.kio.kasten.io/v1alpha1
# Standard Kubernetes Kind declaration. Required.
# Must be 'UpgradeAction'
kind: UpgradeAction
metadata:
# Action name. May be any valid Kubernetes object name.
# Name or generateName is required.
name: upgrade-action-example
# UpgradeAction names must be unique and as an alternative to
# name above one can take advantage of Kubernetes name auto-generation.
generateName: upgrade-action-
# UpgradeAction specification. Required.
spec:
# Subject specifies the Policy or StorageRepository to be upgraded. Required.
subject:
# Standard kubernetes kind declaration. Required.
# Must be 'StorageRepository' or 'Policy'.
kind: StorageRepository
# Name of the upgrade's subject. Required.
name: storage-repository-example
# Namespace of the upgrade's subject. Required.
namespace: kasten-io
# Profile specifies the location profile with which the
# subject (StorageRepository or Policy) is associated. Required.
profile:
# Name of the profile. Required.
name: aws-location-profile-example
# Namespace of the profile. Required.
# Must be the same namespace K10 is installed in.
namespace: kasten-io
status:
# 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
# Start time and end time of the upgrade action.
startTime: "2004-02-29T21:08:07Z"
endTime: "2004-02-29T21:13:07Z"
# State of the upgrade action: "Running", "Complete" or "Failed"
state: Complete