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, Microsoft 365, SQL, Oracle, Db2, MongoDB, IBM Spectrum Protect Plus Catalog, and Windows File Systems
- Type 2
Kubernetes, OpenShift
- 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, Microsoft 365, SQL, Oracle, Db2, MongoDB, Catalog, and Windows File Systems (Type 1) |
|
Kubernetes, OpenShift (Type 2) |
|
Amazon EC2 (Type 3) |
|
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 or OpenShift 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 |
|
Not available |
Required |
Required |
Backup policy |
|
Required |
Optional |
Not available |
Replication policy |
|
Optional |
Optional |
Not available |
Incremental copy to standard object storage |
|
Optional |
Optional |
Not available |
Full copy to archive object storage |
|
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:
|
Minimum
|
Maximum
|
Description |
---|---|---|---|
|
5 |
60 |
Between 5 minutes and 60 minutes |
|
1 |
24 |
Between 1 hour and 24 hours |
|
15 |
30 |
Between 1 day and 30 days |
|
1 |
4 |
Between 1 week and 4 weeks |
|
1 |
60 |
Between 1 month and 12 months |
|
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 |
|
Hour |
|
Day |
|
Week |
|
Month |
|
Year |
|
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 |
|
Replication policy destination |
|
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 Simple Storage Service (S3) |
|
IBM Cloud Object Storage |
|
Microsoft Azure Blob Storage |
|
S3 compatible object storage |
|
IBM Spectrum Protect |
|
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 and OpenShift (Type 2), and Amazon EC2 (Type 3).
Restriction: SLA policies for Kubernetes and OpenShift (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, Microsoft 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: 1 June 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: 1 July 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: 20 June 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=...)

Figure 15 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.¶

Figure 16 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: 1 June 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: 1 June 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: 1 July 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: 20 June 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=...)

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

Figure 18 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: 25 June 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": "Emerald",
"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=...)

Figure 19 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.