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:
  # The name of the user who created the policy. Optional.
  createdBy:
  # The name of the user who last updated the policy. Optional.
  modifiedBy:
  # The hash of the policy spec block after the last modification made. Optional.
  lastModifyHash:
  # 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
      # 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
  # 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
      # 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
    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"
      # 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 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'