Policies¶
A Policy custom resource (CR) is used to perform operations on K10 Policies. K10 Policies allow you to manage application protection and migration at scale. You can learn more about using K10 Policies in the Protecting Applications section.
Example Policy Operations¶
Create Backup Policy¶
The following example illustrates how to create a backup policy which executes
hourly and retains 24 hourly and 7 daily snapshots. The policy covers an
application running in the namespace sampleApp.
$ cat > sample-backup-policy.yaml <<EOF
apiVersion: config.kio.kasten.io/v1alpha1
kind: Policy
metadata:
name: sample-backup-policy
namespace: kasten-io
spec:
comment: My sample backup policy
frequency: '@hourly'
retention:
hourly: 24
daily: 7
actions:
- action: backup
selector:
matchLabels:
k10.kasten.io/appNamespace: sampleApp
EOF
$ kubectl apply -f sample-backup-policy.yaml
policy.config.kio.kasten.io/sample-backup-policy created
# make sure it initializes and validates properly
$ kubectl get policies.config.kio.kasten.io --namespace kasten-io -w
NAME STATUS
sample-backup-policy Running
sample-backup-policy Success
For complete documentation of the Policy CR, refer to Policy API Type.
Create Import Policy¶
The following example illustrates how to create a policy which executes hourly and imports an application that was previously exported to the application-imports Profile.
$ cat > sample-import-policy.yaml <<EOF
apiVersion: config.kio.kasten.io/v1alpha1
kind: Policy
metadata:
name: sample-import-policy
namespace: kasten-io
spec:
comment: My sample import policy
frequency: '@hourly'
actions:
- action: import
importParameters:
profile:
namespace: kasten-io
name: application-imports
receiveString: <encoded string received on Export>
EOF
$ kubectl apply -f sample-import-policy.yaml
policy.config.kio.kasten.io/sample-import-policy created
# make sure it initializes and validates properly
$ kubectl get policies.config.kio.kasten.io --namespace kasten-io -w
NAME STATUS
sample-import-policy Running
sample-import-policy Success
For complete documentation of the Policy CR, refer to Policy API Type.
Update Policy¶
To update a Policy, edit the spec portion of a Policy CR using your preferred method of submitting resource changes with kubectl.
$ kubectl apply -f sample-backup-policy-changed.yaml
policy.config.kio.kasten.io/sample-backup-policy configured
Once the change is submitted, K10 will re-validate the Policy and update .status.validation accordingly.
$ kubectl get policies.config.kio.kasten.io -w
NAME STATUS
sample-backup-policy Running
sample-backup-policy Success
Since K10 processes API object changes asynchronously, to avoid confusion with a previous Policy status, it is recommended as convention that the status portion of the Policy is omitted when submitting changes.
Delete Policy¶
You can delete a Policy using the following command.
# delete policy "sample-backup-policy" for K10 installed in "kasten-io"
$ kubectl delete policies.config.kio.kasten.io sample-backup-policy --namespace kasten-io
policy.config.kio.kasten.io "sample-backup-policy" deleted
# delete policy "sample-import-policy" for K10 installed in "kasten-io"
$ kubectl delete policies.config.kio.kasten.io sample-import-policy --namespace kasten-io
policy.config.kio.kasten.io "sample-import-policy" deleted
Policy Scheduling¶
Within the Policy API Type, K10 provides control of:
How often the primary snapshot or import action should be performed
How often snapshots should be exported into backups
Which and how many snapshots and backups to retain
When the primary snapshot or import action should be performed
Frequency¶
The frequency portion of the policy spec indicates how often the primary policy action should be performed.
The optional frequency portion of exportParameters indicates how often snapshots should be exported into backups. If not specified, every snapshot is to be exported.
Retention¶
The retention portion of the policy spec indicates which and how many snapshots to retain.
The optional retention portion of the export action allows exported backups to be retained independently from snapshots. If not specified, exported backups are retained with the same schedule as snapshots.
SubFrequency¶
By default:
Policies run once within the period of the frequency.
Hourly policies run at the top of the hour.
Daily policies run at midnight UTC.
Weekly policies run at midnight Sunday UTC.
Monthly policies run at midnight on the 1st of the month UTC.
Yearly policies run at midnight on the 1st of January UTC.
Snapshots and backups at those times are retained by the corresponding retention counts.
The optional subFrequency portion of the policy spec provides fine-grained control of when to run a policy, how many times to run a policy within a frequency, and which snapshots and backups are retained.
The frequency, subFrequency, and retention interact as follows:
subFrequency entries within the frequency indicate when the policy is to run
e.g. the minutes and hours subFrequency entries indicate the minutes and hours at which a policy with a daily frequency runs
subFrequency entries immediately within the frequency may have multiple values to run multiple times within the frequency
multiple minutes may be specified for an hourly frequency
multiple hours may be specified for a daily frequency
subFrequency entries indicate which snapshots and backups graduate to higher retention tiers
e.g. for a policy with an hourly frequency, the hours subFrequency entry indicates the hour of day that will graduate and be retained as a daily
For subFrequency entries with multiple values, the first value indicates the time of the snapshot or backup to be retained by higher tiers
e.g. an hourly frequency with subFrequency minutes entry of [45, 15] will run twice an hour at 15 and 45 minutes after the hour, will retain both according to the hourly retention count, and will graduate the hourly taken at 45 minutes after the hour designated by the subFrequency hour entry to the daily tier and higher
All time values in subFrequency entries in the API are in UTC.
If a subFrequency entry is omitted, it defaults as above.
Advanced Backup Policy Example¶
The following example illustrates how to use frequency, subFrequency, and retention to create a backup policy that
creates snapshots twice daily at 07:30 and 22:30
exports the snapshot created at 22:30 on the fifteenth of the month
including exporting snapshot data to create a durable and portable backup
retains 14 daily snapshots (2 per day for 7 days)
retains 4 weekly snapshots from 22:30 each Friday
retains 6 monthly snapshots from 22:30 on the fifteenth of each month
retains 12 exported monthly backups from 22:30 on the fifteenth of each month
retains 5 exported yearly backups from 22:30 on the fifteenth of January each year
This policy covers an application running in the namespace sampleApp.
apiVersion: config.kio.kasten.io/v1alpha1
kind: Policy
metadata:
name: sample-custom-backup-policy
namespace: kasten-io
spec:
comment: My sample custom backup policy
frequency: '@daily'
subFrequency:
minutes: [30]
hours: [22,7]
weekdays: [5]
days: [15]
retention:
daily: 14
weekly: 4
monthly: 6
actions:
- action: backup
- action: export
exportParameters:
frequency: '@monthly'
profile:
name: my-profile
namespace: kasten-io
exportData:
enabled: true
retention:
monthly: 12
yearly: 5
selector:
matchLabels:
k10.kasten.io/appNamespace: sampleApp
For complete documentation of the Policy CR, refer to Policy API Type.
Policy API Type¶
The following is a complete specification of the Policy CR.
# Standard Kubernetes API Version declaration. Required.
apiVersion: config.kio.kasten.io/v1alpha1
# Standard Kubernetes Kind declaration. Required.
kind: Policy
# Standard Kubernetes metadata. Required.
metadata:
# Policy name. May be any valid Kubernetes object name. Required.
# Policy name is not mutable once created.
name: sample-backup-policy
# Policy names must be unique and as an alternative to name above
# one can take advantage of Kubernetes auto name generation.
generateName: backup-policy-
# Policy namespace. Required. Can be namespace where K10 is installed
# or the namespace of the application. If the namesace of the application
# is selected, then the policy can protect only that application.
namespace: kasten-io
# Policy parameters. Required.
spec:
# User friendly comment describing the policy. Optional.
comment:
# Selector for the application that the backup policy applies to.
# Required for backup policy.
selector:
# Standard Kubernetes set-based selector. Optional.
# One of matchExpressions or matchLabels required.
# When the namespace of the policy is the application's namespace,
# the value in a matchExpression, matchLabel or both must match the
# application's namespace. Only a single selector can be defined in
# the matchExpression or matchLabel for application-scoped policies.
matchExpressions:
# Standard Kubernetes set-based selector key.
# 'k10.kasten.io/appNamespace' is a special label indicating that
# the selector is targeting an application namespace
# `kasten-io-cluster` is a special value for `k10.kasten.io/appNamespace`
# that indicates that cluster-scoped resources should be backed up.
- key: k10.kasten.io/appNamespace
# Standard Kubernetes set-based selector operator.
# Only In is supported
operator: In
# Array of values (labels on app names or wildcards) to use in the selector.
# With this construct ANY value of the label key will match
# Use this construct if creating a policy for multiple applications.
values:
- myApp
- myApp-* (will select all apps beginning with myApp-)
# Standard Kubernetes label selector. Optional.
# One of matchExpressions or matchLabels required.
#
# NOTE: Label selector that resolves to a given Kubernetes resource
# will have the effect of selecting the entire application that the
# resource belongs to
matchLabels:
# Map of label key and value pairs to match
# 'k10.kasten.io/appNamespace' special label described above is supported
# With this construct ALL labels must match for an object
myLabelKey1: myLabelValue1
myLabelKey2: myLabelValue2
# Execution frequency. Required.
# Allowable values: '@hourly', '@daily', '@weekly', '@monthly', '@yearly'
frequency: '@hourly'
# Execution frequency modifier. Optional.
# subFrequency specifies when to run and how many times to run within frequency.
subFrequency:
# minutes within hour (0-59). Optional.
# Multiple minutes valid only for '@hourly' frequency.
# Multiple minutes values must all be multiples of 5 minutes.
# First entry determines minute of daily and longer retention.
minutes: [0,30]
# hours within day (0-23). Optional.
# Multiple hours valid only for '@daily' frequency.
# First entry determines hour of weekly and longer retention.
hours: [0]
# days within week (0-7 (Sun-Sun)). Optional.
# weekdays not valid for '@monthly' or '@yearly' frequencies.
# Multiple weekdays valid only for '@weekly' frequency. With '@weekly'
# frequency, first entry determines day of monthly and yearly retention.
weekdays: [0]
# days within month (1-31). Optional.
# days not valid for '@weekly' frequency.
# Multiple days valid only for '@monthly' frequency.
# First entry determines day of monthly and yearly retention.
days: [1]
# months within year (1-12). Optional.
# Multiple months valid only for '@yearly' frequency.
# First entry determines month of yearly retention.
# Valid for '@yearly' frequency.
months: [1]
# Pause scheduled policy runs. Optional.
paused: false
retention:
# Number of retained artifacts for different frequencies. Required.
# The number of retained artifacts can only be specified for frequencies
# of the same or lower granularity than the policy frequency. For example,
# if the policy frequency is '@daily', then retention can have values for
# 'daily', 'weekly', 'monthly' and 'yearly', but not for 'hourly'.
# If the policy frequency is 'hourly', then all retention values are
# allowed.
hourly: 24
daily: 7
weekly: 4
monthly: 12
yearly: 5
# Actions executed by the policy. Required: at least one of backup or import.
actions:
# Backup policy action.
- action: backup
# Optional backup parameters
backupParameters:
# 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 BackupActions created by this Policy.
#
# 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 BackupActions, K10 automatically
# includes associated PVCs and PVs when a statefulset, deployment, or
# deploymentconfig is included by includeResources unless the PVC is
# excluded by excludeResources.
#
# Backup policy that selects cluster-scoped resources may provide
# optional filters that apply to any BackupClusterAction.
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>
# Include only matching cluster-scoped resources
includeClusterResources:
# Include individual resource
- name: <resource3 resource name>
group: <resource3 group>
version: <resource3 version>
resource: <resource3 type name>
# Include resource type
- group: <resource4 group>
version: <resource4 version>
resource: <resource4 type name>
# Exclude matching cluster-scoped resources
excludeClusterResources:
# Exclude specific instance of resource4 type
- name: <resource4 resource name>
group: <resource4 group>
version: <resource4 version>
resource: <resource4 type name>
# Optional: K10 Location Profile that is used for this backup
# Profile used for Kanister-enabled operations and
# Generic Storage Backups
profile:
name: my-profile
namespace: kasten-io
# Optional: Ignore exceptions and continue if possible.
# Snapshots with exceptions will be flagged as potentially flawed.
# Default: false
ignoreExceptions: false
# Export action. Export can only be specified after a backup action.
- action: export
exportParameters:
# How often should a backup be exported. This frequency has to be less
# or equal than the policy frequency.
frequency: '@hourly'
# K10 Location Profile that is used for this export. Required.
profile:
name: my-profile
namespace: kasten-io
# 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
# Volume snapshot destination region and account. Optional, or
# with one of awsEbs or azure only. Non-portable export only.
volumeSnapshots:
awsEbs:
regions:
- us-east-1
# Destination Account name.
destinationAccount: sample-destination-account
azure:
regions:
- eastus
retention:
# Optional exported artifact retention. If not provided, exported
# artifacts are retained by the policy retention table.
# Number of retained export artifacts for different frequencies.
# The number of retained artifacts can only be specified for frequencies
# of the same or lower granularity than the exportParameters frequency.
hourly: 24
daily: 7
weekly: 4
monthly: 12
yearly: 5
# Import action.
- action: import
# Parameters available to import actions. Required.
importParameters:
# K10 Location Profile that is used for this import. Required.
profile:
# Profile name. Required.
name: sample-profile
# Namespace where the Profile CR resides. Required.
namespace: kasten-io
# Encoded string generated on Export. Required.
receiveString: VGhpcyBpcyBhIHNhbXBsZSBleHBvcnQgc3RyaW5nLgo=
# Restore action. Restore can only be specified after an import action.
- action: restore
# Optional restore parameters
restoreParameters:
# Optional: set to true to only restore the application data.
# Must be false if filters are specified.
# Default: false
dataOnly: false
# Optional: set to true to restore imported cluster-scope resources
# Default: false
restoreClusterResources: 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 RestoreActions, K10 only restores resources that
# are explicitly included by includeResources. For RestoreActions, when a
# statefulset, deployment, or deploymentconfig is included by includeResources,
# K10 does not restore associated PVCs unless the PVC is included by
# includeResources.
#
# Restore action that selects cluster-scoped resources may provide
# optional filters that apply to any imported ClusterRestorePoint.
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>
# Include only matching cluster-scoped resources
includeClusterResources:
# Include individual resource
- name: <resource3 resource name>
group: <resource3 group>
version: <resource3 version>
resource: <resource3 type name>
# Include resource type
- group: <resource4 group>
version: <resource4 version>
resource: <resource4 type name>
# Exclude matching cluster-scoped resources
excludeClusterResources:
# Exclude specific instance of resource4 type
- name: <resource4 resource name>
group: <resource4 group>
version: <resource4 version>
resource: <resource4 type name>
# Optional: Namespace where the application is to be restored.
# Defaults to the namespace of the application in the imported
# RestorePoint.
targetNamespace: mysql
# Only used with Kanister blueprints that support point-in-time restore
# Value is the desired timestamp. Optional.
pointInTime: "2019-02-11T05:13:10Z"
# Status of the Policy. Users should not set any data here.
status:
# Validation status of the Policy
# Valid values are:
# # Pending - policy has been created
# # Running - undergoing initialization and validation
# # Success - successfully initialized and validated
# # Failed - not properly initialized on validated
# Only policies which have status of Success will be used by the system
validation: Success
# If action: ExportAction was specified and properly validate policy
exportString: 'export string to use in import comes here'