Adding an SLA policy

You can add an SLA policy by using the REST API. There are three types of SLA policies. Use one of the following types based on the backup target objects:

Type 1

VMware, Hyper-V, Exchange, Office 365, SQL, Oracle, Db2, MongoDB, IBM Spectrum Protect Plus Catalog, and Windows File Systems

Type 2

Kubernetes

Type 3

Amazon EC2

Method and URI

To add an SLA policy, use a POST method with a URI:

POST    https://{hostname|IPv4}/ngp/slapolicy

Parameters

None.

Data

Data 1: name

The name of the SLA policy.

  • Example value: Diamond

  • Type: String. Required. Available in the web user interface.

Data 2: type

The type of the SLA policies.

  • Value: Use one of the following values:

Backup targets

Value

VMware, Hyper-V, Exchange, Office 365, SQL, Oracle, Db2, MongoDB, Catalog, and Windows File Systems (Type 1)

backup

Kubernetes (Type 2)

snapshot_backup

Amazon EC2 (Type 3)

snapshot

  • Type: System string. Required. Available in the web user interface.

Data 2: spec

Configuration settings for the SLA policy.

  • Value: {"subpolicy": ...}

  • Type: JSON object. Required. Available in the web user interface.

Data 2.1: spec > subpolicy

Configuration settings for the SLA policy by topics: Snapshot protection, a backup policy , a replication policy, making incremental copies to standard object storage, and making full copies to archive object storage.

  • Example value 1: Define configuration settings in a JSON object for each topic. Some topics are optional. For example, assume that you want to make an SLA policy for VMware instances and Db2 instances (Type 1); and make the SLA policy has only the backup policy topic. In this case, the subpolicy value has the following structure:

[
    {
        "type":     "SNAPSHOT",
        ...
    }
]
  • Example value 2: To create another SLA policy for Kubernetes instances (Type 2), and define configuration settings for all topics, the subpolicy value has the following structure:

[
    {
        "type":     "SNAPSHOT",
        ...
    },
    {
        "type":     "REPLICATION",
        "software": true,
        ...
    },
    {
        "type":     "REPLICATION",
        "software": false,
        ...
    },
    {
        "type":     "SPPOFLOAD",
        ...
    },
    {
        "type":     "SPPARCHIVE",
        ...
    }
]
  • Type: Array. Required. Available in the web user interface.

Data 2.1.1: spec > subpolicy > type

The topics of the configuration settings. Available topics differ by the type of SLA policies.

  • Value: Use one of the following values:

Topic

Value

Type 1

Type 2

Type 3

Snapshot protection

SNAPSHOT

Not available

Required

Required

Backup policy

REPLICATION with software

Required

Optional

Not available

Replication policy

REPLICATION without software

Optional

Optional

Not available

Incremental copy to standard object storage

SPPOFFLOAD

Optional

Optional

Not available

Full copy to archive object storage

SPPARCHIVE

Optional

Optional

Not available

When the value REPLICATION is used, you must define the Boolean value software which is described next.

  • Type: System string. Required. Available in the browser user inteface.

Data 2.1.2: spec > subpolicy > software

When the value REPLICATION is used for the Data key-value pair, spec > subpolicy > type, you must define the Boolean value software.

If software is true, the backup policy topic is used for the subpolicy JSON object. If the value of software is false, the replication policy topic is used.

  • Type: Boolean. Available in the web user interface.

Data 2.1.3: spec > subpolicy > retention

The period to retain backup snapshots. Any backup snapshots that exceed the retention period will be purged.

Attention

Be careful about the retention period when you edit SLA policies. If you update an SLA policy with a shorter retention period, IBM Spectrum Protect Plus purges all backup snapshots that are older than that retention period.

For example, assume that you add an SLA policy with the retention period of 90 days to make a backup snapshot every day. Use this policy for 3 months. Update it with the new retention period of 3 days. Then, IBM Spectrum Protect Plus deletes 87 daily backup snapshots immediately and retains 3 snapshots that were created in the past 3 days.

  • Example value: The following retention value can be used to retain backup snapshots for 365 days (1 year).

{
    "age": 365
}
  • Type: JSON object. Required. Available in the web user interface.

Data 2.1.3.1: spec > subpolicy > retention > age

The number of days to retain backup snapshots.

  • Type: Integer. Required. Available in the web user interface.

Data 2.1.4: spec > subpolicy > useEncryption

An indication of whether using only encrypted disk storage on external vSnap servers. This key-value pair is available for the backup policy topic only.

  • Example value: false to allow IBM Spectrum Protect Plus to store backup snapshots on vSnap servers with unencrypted disks.

  • Type: Boolean. Required. Available in the web user interface.

Data 2.1.5: spec > subpolicy > trigger

Define the frequency, start date and time, and the timezone for the web user interface.

  • Example value 1: The following trigger value can be used to make a backup snapshot every 15 minutes, start the SLA policy from 1590987600 UNIX time (June 1, 2020 at 0:00 AM CDT); and the timezone for the web user interface is set to CDT:

{
    "frequency":    15,
    "type":         "SUBHOURLY",
    "activateDate": 1590987600000,
    "timezone":     "America/Chicago"
}
  • Example value 2: The following trigger value is the same as Example value 1, except the frequency being set to one time every two hours:

{
    "frequency":    2,
    "type":         "HOURLY",
    "activateDate": 1590987600000,
    "timezone":     "America/Chicago"
}
  • Example value 3: The following trigger value is the same as Example value 1, except the frequency being set to one time every two days:

{
    "frequency":    2,
    "type":         "DAILY",
    "activateDate": 1590987600000,
    "timezone":     "America/Chicago"
}
  • Example value 4: The following trigger value is the same as Example value 1, except the frequency being set to one time every Sunday and Friday:

{
    "frequency":    1,
    "type":         "WEEKLY",
    "dowList": [ false,
        true,  false, false, false, false, true,  false
    ],
    "activateDate": 1590987600000,
    "timezone":     "America/Chicago"
}
  • Example value 5: The following trigger value is the same as Example value 1, except the frequency being set to one time on the 1st day and on the 15th day every other month:

{
    "frequency":    2,
    "type":         "MONTHLY",
    "domList":      [ false,
        true,  false, false, false, false, false, false,
        false, false, false, false, false, false, false,
        true,  false, false, false, false, false, false,
        false, false, false, false, false, false, false,
        false, false, false, false
    ],
    "activateDate": 1590987600000,
    "timezone":     "America/Chicago"
}
  • Example value 6: The following trigger value is the same as Example value 1, except the frequency being set to one time every three years, and the timezone for the web user interface being set to UTC:

{
    "frequency":    3,
    "type":         "YEARLY",
    "activateDate": 1590987600000,
    "timezone":     "UTC"
}
  • Type: JSON object. Required. Available in the web user interface.

Data 2.1.5.1: spec > subpolicy > trigger > frequency

A number of unit periods that are defined by the type value to run a job that are associated with the SLA policy. The range of the number varies by the type value:

type

Minimum frequency

Maximum frequency

Description

SUBHOURLY

5

60

Between 5 minutes and 60 minutes

HOURLY

1

24

Between 1 hour and 24 hours

DAILY

15

30

Between 1 day and 30 days

WEEKLY

1

4

Between 1 week and 4 weeks

MONTHLY

1

60

Between 1 month and 12 months

YEARLY

15

60

Between 1 year and 60 years

  • Type: Integer. Required. Available in the web user interface.

Data 2.1.5.2: spec > subpolicy > trigger > type

The time unit.

  • Value: Use one of the following values for the time unit you want to use:

Time unit

Value

Minute

SUBHOURLY

Hour

HOURLY

Day

DAILY

Week

WEEKLY

Month

MONTHLY

Year

YEARLY

  • Type: System string. Required. Available in the web user interface.

Data 2.1.5.3: spec > subpolicy > trigger > dowList

The days in a week to trigger the SLA policy. Use this key-value pair when you use WEEKLY for type.

The dowList is a list that contains 8 Boolean objects. The item in index 0 is reserved for the system, and it must be false. The item in index 1 is Sunday, the item in index 2 is Monday, and so on.

  • Example: You can make multiple days to trigger the SLA policy. For example, to trigger every Sunday and Saturday, use the following list:

[   false,
    true,  false, false, false, false, false, true
]
  • Restriction: In the web user interface, you can define only one day in a week.

  • Type: System list (length 8, Boolean). Partially available in the web user interface.

Data 2.1.5.4: spec > subpolicy > trigger > domList

The days in a month to trigger the SLA policy. Use this key-value pair when you use MONTHLY for type.

The domList is a list that contains 33 Boolean objects. The item in index 0 is reserved for the system, and it must be false. The item in index 1 is the 1st day of a month, the item in index 2 is the 2nd day of a month, and so on. The item in index 33 is the last day of a month.

Tip

It is advised not to use the items between index 28 and 31 because some months do not have days between 28 and 31.

Example value: The following list can be used to select the last day of every month (for example, January 31, February 28, and so on):

[   false,
    false, false, false, false, false, false, false,
    false, false, false, false, false, false, false,
    false, false, false, false, false, false, false,
    false, false, false, false, false, false, false,
    false, false, false, true
]
  • Restriction: In the web user interface, you can define only one day in a month.

  • Type: System list (length 33, Boolean). Partially available in the web user interface.

Data 2.1.5.5: spec > subpolicy > trigger > activateDate

The start time to activate the SLA policy. Use the UNIX timestamp format followed by three digits, which represent milliseconds.

  • Type: Integer. Required. Available in the web user interface.

Data 2.1.5.6: spec > subpolicy > trigger > timezone

The Time Zone database name for the web user interface. This value does not affect the activateDate value in the UNIX time format for the start time. You can use UTC too.

Tip

Use UTC for UTC. To get a full list of TZ database names, see the web user interface or log in to IBM Spectrum Protect Plus via SSH and run the timedatectl list-timezones command.

  • Type: System string. Required. Available in the web user interface.

Data 2.1.6: spec > subpolicy > source

The source for the incremental copy to standard object storage topic and the full copy to archive object storage topic. Use one of the following values:

Source

Value

Backup policy destination

backup

Replication policy destination

replication

  • Type: System string. Required. Available in the web user interface.

Data 2.1.7: spec > subpolicy > site

The name of the site. This key-value pair is only available for the snapshot protection topic, the backup policy topic, and the replication policy topic.

  • Example value: Primary

  • Type: String. Required. Available in the web user interface.

Data 2.1.8: spec > subpolicy > target

Specify the object storage server or the repository server to store the backup snapshots. This key-value pair is only available for the incremental copy to standard object storage topic and the full copy to archive object storage topic.

  • Example value:

{
    "href":         "https://10.0.0.100/api/cloud/3",
    "resourceType": "cos",
    "id":           "3"
}
  • Type: JSON object. Required. Available in the web user interface.

Data 2.1.8.1: spec > subpolicy > target > href

The {cloudProviderInfoHref} of the object storage server or the repository server.

Tip

To get a {cloudProviderInfoHref} by the name of the storage server or the repository server, follow the instructions in Getting a {cloudProviderInfoHref}.

  • Type: String. Required.

Data 2.1.8.2: spec > subpolicy > target > resourceType

The type of the object storage server or the repository server.

  • Value: Use one of the following values:

Provider

Value

Amazon S3

aws

IBM Cloud Object Storage

cos

Microsoft Azure Blob Storage

azure

S3 compatible object storage

generic

IBM Spectrum Protect

sp

  • Type: System string. Required.

Data 2.1.8.3: spec > subpolicy > target > id

The {cloudProviderInfoId} of the object storage server or the repository server.

Tip

To get a {cloudProviderInfoId} by the name of the storage server or the repository server, follow the instructions in Getting a {cloudProviderInfoId}.

  • Type: String. Required.

Data 2.1.9: spec > subpolicy > label

The prefix for snapshot names. This key-value pair is available in SLA policies for Kubernetes (Type 2) and Amazon EC2 (Type 3).

  • Restriction: SLA policies for Kubernetes (Type 2) support only lowercase characters (a-z) or digits (0-9). SLA policies for Amazon EC2 does not have this restriction.

  • Example value: daily

  • Type: String. Available in the web user interface.

Example 1: Add an SLA policy for VMware instances (Type 1)

Assume that you want to add an SLA policy with the following properties:

  • Name: Diamond

  • Type: VMware, Hyper-V, Exchange, Office 365, SQL Server, Oracle Database, Db2, MongoDB, IBM Spectrum Protect Plus Catalog, and Windows File Systems (Type 1)

  • Backup policy: Required

    • Retention: 7 days

    • Frequency: every 2 hours

    • Start time: June 1, 2020 at 0:00 US Central Time (1590987600 UNIX time)

    • Target Site: Dallas

    • Only use encrypted disk storage: No

  • Replication policy: Enable

    • Retention: 30 days

    • Frequency: every 1 day

    • Start time: July 1, 2020 at 13:00 Singapore Time (1593579600 UNIX time)

    • Target Site: Singapore

    • Only use encrypted disk storage: No

  • Incremental copy to standard object storage: Enable

    • Retention: 7 days

    • Frequency: every 1 week, every Sunday

    • Start time: June 10, 2020 at 0:00 US Central Time (1591765200 UNIX time)

    • Source: Backup policy destination

      • Destination and target: Cloud services, BlueMachines IBM COS - Dallas ({cloudProviderInfoId} 2)

  • Full copy to archive object storage: Enable

    • Retention: 5 years

    • Frequency: every 1 month, the 20th day of every month

    • Start time: June 20, 2020 at 2:15 US Central Time (1592637300 UNIX time)

    • Source: Backup policy destination

      • Destination and target: Repository Server: BlueMachines Spectrum Protect - Dallas 1 ({cloudProviderInfoId} 6)

A Python snippet that is similar to the following example can be used to create an SLA policy:

_data = f'''{{
   "name": "Diamond",
   "type": "backup",
   "spec": {{
      "subpolicy": [
         {{
            "type":          "REPLICATION",
            "software":      true,
            "retention":     {{
               "age": 7
            }},
            "useEncryption": false,
            "trigger":       {{
               "frequency":    2,
               "type":         "HOURLY",
               "activateDate": 1590987600000,
               "timezone":     "America/Chicago"
            }},
            "site":          "Dallas"
         }},
         {{
            "type":          "REPLICATION",
            "software":      false,
            "retention":     {{
               "age": 30
            }},
            "useEncryption": false,
            "trigger":       {{
               "frequency":    1,
               "type":         "DAILY",
               "activateDate": 1593579600000,
               "timezone":     "Asia/Singapore"
            }},
            "site":"Primary"
         }},
         {{
            "type":      "SPPOFFLOAD",
            "retention": {{
                "age": 7
            }},
            "trigger":   {{
               "frequency":    1,
               "type":         "WEEKLY",
               "dowList":      [ false,
                   true, false, false, false, false, false, false
               ],
               "activateDate": 1591765200000,
               "timezone":     "America/Chicago"
            }},
            "source":    "backup",
            "target":    {{
               "href":         "https://10.0.0.100/api/cloud/2",
               "resourceType": "cos",
               "id":           "2"
            }}
         }},
         {{
            "type":      "SPPARCHIVE",
            "retention": {{
               "age": 1825
            }},
            "trigger":   {{
               "frequency":    1,
               "type":         "WEEKLY",
               "dowList":      [ false,
                   true, false, false, false, false, false, false
               ],
               "activateDate": 1592637300000,
               "timezone":     "America/Chicago"
            }},
            "source":    "backup",
            "target":    {{
               "href":         "https://10.0.0.100/api/cloud/6",
               "resourceType": "sp",
               "id":           "6"
            }}
         }}
      ]
   }}
}}'''

requests.post('https://' + spp_ipv4 + '/ngp/slapolicy',
    headers={...}, data=_data, verify=...)
_images/reference_sla_create01regular.png

Figure 14 The same action can be taken in the IBM Spectrum Protect Plus web user interface: In the navigation pane, click Manage Protection > Policy Overview, and see the SLA Policies section. Click Add SLA Policy. Enter the name. Click VMware, Hyper-V, … to create an SLA policy Type 1. Fill in the required fields for a backup policy. Optionally, you can define a replication policy.

_images/reference_sla_create02regular.png

Figure 15 Scroll down the page. Optionally, you can define the incremental copy to standard object storage and full copy to archive object storage too. Click Save.

The request prompts a response with the HTTP status of 201 (Created). The response body is similar to the JSON object for the SLA policy, Diamond, as shown in Getting information about SLA policies. Review the response to ensure that the new SLA policy, Diamond, was created.

Example 2: Add an SLA policy for Kubernetes instances (Type 2)

Assume that you want to add an SLA policy with the following properties:

  • Name: Sapphire

  • Type: Kubernetes (Type 2)

  • Snapshot protection: Required

    • Retention: 7 days

    • Frequency: every 30 minutes

    • Start time: June 1, 2020 at 0:00 US Central Time (1589778000 UNIX time)

    • Snapshot prefix: sapphire

  • Backup policy: Enable

    • Retention: 1 month

    • Frequency: every 1 day

    • Start time: June 1, 2020 at 1:00 US Central Time (1589778000 UNIX time)

    • Target Site: Dallas

    • Only use encrypted disk storage: No

  • Replication policy: Enable

    • Retention: 30 days

    • Frequency: every 1 day

    • Start time: July 1, 2020 at 13:00 Singapore Time (1593579600 UNIX time)

    • Target Site: Singapore

    • Only use encrypted disk storage: No

  • Incremental copy to standard object storage: Yes

    • Retention: 1 month

    • Frequency: every 1 day

    • Start time: June 10, 2020 at 0:00 US Central Time (1591765200 UNIX time)

    • Source: Replication policy destination

      • Destination and target: Cloud services, BlueMachines Amazon S3 US-East1 ({cloudProviderInfoId} 4)

  • Full copy to archive object storage: Yes

    • Retention: 5 years

    • Frequency: every 1 month, the 20th day of every month

    • Start time: June 20, 2020 at 2:15 US Central Time (1592637300 UNIX time)

    • Source: Backup policy destination

      • Destination and target: Cloud services: BlueMachines Azure US-East ({cloudProviderInfoId} 3)

A Python snippet that is similar to the following example can be used to create an SLA policy:

_data = f'''{{
    "name": "Sapphire",
    "type": "snapshot_backup",
    "spec": {{
        "subpolicy": [
            {{
                "name":      "Storage Snapshot",
                "type":      "SNAPSHOT",
                "retention": {{
                    "age": 7
                }},
                "trigger":   {{
                    "frequency":    30,
                    "type":         "SUBHOURLY",
                    "activateDate": 1589778000000,
                    "timezone":     "America/Chicago"
                }},
                "label":     "sapphire"
            }},
            {{
                "type":          "REPLICATION",
                "software":      true,
                "retention":     {{
                    "age": 30
                }},
                "useEncryption": false,
                "trigger": {{
                    "frequency":    1,
                    "type":         "DAILY",
                    "activateDate": 1589778000000,
                    "timezone":     "America/Chicago"
                }},
                "site":          "Dallas"
            }},
            {{
                "type":          "REPLICATION",
                "retention":     {{
                    "age": 30
                }},
                "useEncryption": false,
                "software":      false,
                "trigger": {{
                    "frequency":    1,
                    "type":        "DAILY",
                    "activateDate": 1593579600000,
                    "timezone":     "Asia/Singapore"
                }},
                "site":          "Primary"
            }},
            {{
                "type":         "SPPOFFLOAD",
                "retention":    {{
                    "age": 30
                }},
                "trigger":      {{
                    "frequency":    1,
                    "type":         "DAILY",
                    "activateDate": 1591765200000,
                    "timezone": "America/Chicago"
                }},
                "source":       "replication",
                "target":       {{
                    "href":         "https://10.0.0.100/api/cloud/4",
                    "resourceType": "aws",
                    "id":           "4"
                }}
            }},
            {{
                "type":            "SPPARCHIVE",
                "retention":        {{
                    "age": 1825
                }},
                "trigger":          {{
                    "frequency": 1,
                    "type":      "MONTHLY",
                    "domList":   [ false,
                        false, false, false, false, false,
                        false, false, false, false, false,
                        false, false, false, false, false,
                        false, false, false, false, true,
                        false, false, false, false, false,
                        false, false, false, false, false,
                        false, false
                    ],
                    "activateDate": 1592637300000,
                    "timezone":     "America/Chicago"
                }},
                "source":           "replication",
                "target": {{
                    "href":         "https://10.0.0.100/api/cloud/3",
                    "resourceType": "azure",
                    "id":           "3"
                }}
            }}
        ]
    }}
}}'''

requests.post('https://' + spp_ipv4 + '/ngp/slapolicy',
    headers={...}, data=_data, verify=...)
_images/reference_sla_create03kube.png

Figure 16 To create an SLA policy for Kubernetes (Type 2), click Kubernetes and fill in the required fields.

_images/reference_sla_create04kube.png

Figure 17 Scroll down the page. Optionally, you can define the incremental copy to standard object storage and full copy to archive object storage too. Click Save.

The request prompts a response with the HTTP status of 201 (Created). The response body is similar to the JSON object for the SLA policy, Sapphire, as shown in Getting information about SLA policies. Review the response to ensure that the new SLA policy, Sapphire, was created.

Example 3: Add an SLA policy for Amazon EC2 instances (Type 3)

Assume that you want to add an SLA policy with the following properties:

  • Name: Emerald

  • Type: Amazon EC2 (Type 3)

  • Snapshot protection: Required

    • Retention: 6 months

    • Frequency: every 2 weeks on Sunday

    • Start time: June 25, 2020 at 0:00 US Central Time

    • Snapshot prefix: Emerald:

A Python snippet that is similar to the following example can be used to create an SLA policy:

_data = f'''{{
   "name": "Emerald2",
   "type": "snapshot",
   "spec": {{
      "subpolicy": [
         {{
            "type":      "SNAPSHOT",
            "retention": {{
               "age": 180
            }},
            "trigger":   {{
               "frequency":    2,
               "type":         "WEEKLY",
               "dowList":      [ false,
                  true,  false, false, false, false, false, false
               ],
               "activateDate": 1593061200000,
               "timezone":     "America/Chicago"
            }},
            "label":     "Emerald:"
         }}
      ]
   }}
}}'''

requests.post('https://' + spp_ipv4 + '/ngp/slapolicy',
    headers={...}, data=_data, verify=...)
_images/reference_sla_create05ec2.png

Figure 18 Create an SLA policy (Type 3) for Amazon EC2.

The request prompts a response with the HTTP status of 201 (Created). The response body is similar to the JSON object for the SLA policy, Emerald, as shown in Getting information about SLA policies. Review the response to ensure that the new SLA policy, Emerald, was created.