Update the Backup Configuration
/paas/api/v1.1/instancemgmt/{identityDomainId}/services/jaas/instances/{serviceId}/backupconfig
- Schedule for full and incremental backups
- Default retention time for incremental backups and full on-demand backups; note that full scheduled backups are retained until their last related incremental backup is no longer available, if any
- URI and user name for the object storage container or bucket that is used to store backups
To disable a scheduled full or incremental backup, set the fullBackupSchedule
or incrementalBackupSchedule
value, respectively, to null
. For example: {"fullBackupSchedule": null}
.
To disable and renable the backup service for a service instance, use the backups
parameter. When disabled, on-demand backups cannot be performed and scheduled backups will not run. When the backup service is reenabled, scheduled backups will resume at the next scheduled time. In other words, missed scheduled backups are not run.
If you specified a notification email address when you created the service instance, Oracle Java Cloud Service automatically disables backups and notifies you after three consecutive scheduled backups failures of the same error. If you did not specify an email, Oracle Java Cloud Service automatically disables backups after seven consecutive failures of scheduled backups. When updating the backup configuration, correct the cause of the failure and also re-enable backups using the backups
parameter.
For complete information about scheduled automated backups, contents of backups, and where backups are stored, see About Backup and Restoration in Administering Oracle Java Cloud Service.
Request
- application/json
-
identityDomainId: string
Identity domain ID for the Oracle Java Cloud Service account.
-
serviceId: string
Name of the Oracle Java Cloud Service instance.
-
Authorization: string
Base64 encoded user name and password separated by a colon or OAuth access token obtained from Oracle Identity Cloud Service. See Authenticate.
-
X-ID-TENANT-NAME: string
Identity domain ID for the Oracle Java Cloud Service account.
object
backups
parameter to disable or reenable the backup service for the specified service instance.-
backups(optional):
string
State of the backup service you want to set for the specified Oracle Java Cloud Service instance. Valid value:
DISABLE
,ENABLE
, orUNCHANGED
(default).When the backup service is disabled, both on-demand and scheduled backups are disabled. The following operations are also not permitted on the service instance when the backup service is disabled:
- Update the backup configuration (except to reenable)
- Restore from an existing backup
- Apply a patch
- Rollback a patch
Scheduled backups do not run when the backup service is disabled. Upon reenabling the backup service, scheduled backups will resume at the next scheduled time. In other words, missed scheduled backups are not run.
-
cloudStorageContainer(optional):
string
Where to store service instance backups.
This is the URI of an existing object storage container or bucket.
On Oracle Cloud Infrastructure Classic and Oracle Cloud at Customer, specify the container using one of the following formats:
Storage-<identitydomainid>/<containername>
<storageservicename>-<identitydomainid>/<containername>
<restEndPointURL>/<containerName>
On Oracle Cloud Infrastructure, specfiy the object storage bucket using the following format:
https://swiftobjectstorage.<region>.oraclecloud.com/v1/<namespace>/<bucket>
To find out your namespace, sign in to the Oracle Cloud Infrastructure web console, click the tenancy name, and look for the Object Storage Namespace field.
Example:
https://swiftobjectstorage.us-phoenix-1.oraclecloud.com/v1/acme/mybucket
Also note the following on all cloud deployments:
- If you change the object storage container or bucket name, any existing backups in the previous container or bucket will remain there and be available for service restoration until the retention period has elapsed.
- If you try to change the name and the object storage user credentials (
cloudStorageUser
andcloudStoragePassword
), the URI will not be updated to the new value if at least one existing backup in the old container or bucket cannot be used (because the old container or bucket cannot be accessed with the new credentials).
-
cloudStoragePassword(optional):
string
Password for the object storage user.
On Oracle Cloud Infrastructure Classic and Oracle Cloud at Customer, this is the password for the Oracle Cloud Infrastructure Object Storage Classic user who has read and write access to the container that is specified in
cloudStorageContainer
.If a service instance on Oracle Cloud Infrastructure Classic is using Oracle Identity Cloud Service, this attribute is not required if the current cloud user is entitled to use Oracle Cloud Infrastructure Object Storage Classic.
On Oracle Cloud Infrastructure, this is the Auth token generated in Oracle Cloud Infrastructure for the user specified in
cloudStorageUser
. -
cloudStorageUser(optional):
string
User name for the object storage user.
On Oracle Cloud Infrastructure Classic and Oracle Cloud at Customer, this is the user name for the Oracle Cloud Infrastructure Object Storage Classic user who has read and write access to the container that is specified in
cloudStorageContainer
.If a service instance on Oracle Cloud Infrastructure Classic is using Oracle Identity Cloud Service, this attribute is not required if the current cloud user is entitled to use Oracle Cloud Infrastructure Object Storage Classic.
On Oracle Cloud Infrastructure, this is the user name for the Oracle Cloud Infrastructure Object Storage user.
-
defaultRetention(optional):
string
Number of days incremental backups and full on-demand backups are retained. This value defaults to
30
. Full scheduled backups are retained until their last related incremental backup is no longer available, if any.Any change to the default retention value will affect new backups as well as existing backups. This means if you change the value to a smaller number, existing backups that meet the updated retention policy will be deleted during the next backup or next scheduled maintenance cycle.
-
disabledScheduledCoordinatedBackups(optional):
boolean
Flag that specifies whether a scheduled Oracle Java Cloud Service instance backup will include a backup of the associated database deployment.
A value of
false
means a backup of the associated database deployment is coordinated and enabled. A value oftrue
means a coordinated database deployment backup is not performed (disabled) during a scheduled backup of this service instance.If the Oracle Java Cloud Service instance has
backupDestination
set toBOTH
and the instance is associated with a database deployment that hasbackupDestination
set toNONE
, a scheduled Oracle Java Cloud Service instance backup does not include a backup of the associated database.Note: This attribute is not applicable to an Oracle Java Cloud Service instance that uses Oracle Database Exadata Cloud Service for the required infrastructure schema. The attribute is ignored if it is specified in the service instance backup configuration. This attribute is also not applicable to service instances that use an Oracle Autonomous Transaction Processing database or Oracle Cloud Infrastructure Database (DB system) to host the infrastructure schema. Coordinated backups are not available for such service instances.
-
fullBackupSchedule(optional):
array fullBackupSchedule
Schedule for the next full backup.
By default, full backups are initiated weekly starting 12 hours after an instance was created, rounded to the nearest five-minute interval.
Note: Though not recommended, you can disable full backups temporarily by setting this attribute to
null
. -
incrementalBackupSchedule(optional):
array incrementalBackupSchedule
Schedule for the next incremental backup.
By default, incremental backups are initiated every day except the day that full backups are initiated.
Note: Though not recommended, you can disable incremental backups temporarily by setting this attribute to
null
. -
localRetention(optional):
string
Number of days to retain the copies of backups on a dedicated storage volume. Default is 7 days.
The local retention value cannot be larger than the default retention value (specified by
defaultRetention
).Copies of full scheduled backups are retained until the local copy of their last related incremental backup is no longer available, if any.
Any change to the local retention value will affect new backup copies as well as existing copies. This means if you change the value to a smaller number, existing backup copies that meet the updated retention policy will be deleted during the next backup or next scheduled maintenance cycle.
array
By default, full backups are initiated weekly starting 12 hours after an instance was created, rounded to the nearest five-minute interval.
Note: Though not recommended, you can disable full backups temporarily by setting this attribute to null
.
-
Array of:
object backupschedule
Attributes for
fullBackupSchedule
andincrementalBackupSchedule
.
array
By default, incremental backups are initiated every day except the day that full backups are initiated.
Note: Though not recommended, you can disable incremental backups temporarily by setting this attribute to null
.
-
Array of:
object backupschedule
Attributes for
fullBackupSchedule
andincrementalBackupSchedule
.
object
fullBackupSchedule
and incrementalBackupSchedule
.-
dayOfMonth(optional):
string
Day of the month. This value is not configurable. It defaults to all days of the month (*).
-
dayOfWeek(optional):
string
Day of the week. Valid values are: Mon, Tue, Wed, Thu, Fri, Sat, Sun. For full backups, only one value (day) is allowed. For incremental backups, one or more values (days) are allowed. If a value is not specified for incremental backups, the default value is calculated as all days except the day that full backups are initiated.
-
hour(optional):
string
Hours. Valid values are 0 to 23.
-
minute(optional):
string
Minutes. Valid values are 0 to 59.
-
month(optional):
string
Month. This value is not configurable. It defaults to all months (*).
-
second(optional):
string
Seconds. This value is not configurable. It defaults to 0.
-
year(optional):
string
Year. This value is not configurable. It defaults to all years (*).
Response
- application/json
202 Response
Location
header returns a URI that can be used to view the job status, as described in View the Status of an Operation by Job Id.object
-
job_id(optional):
string
Job ID for the operation.
-
operationName(optional):
string
Operation performed. For example,
start-backup
,backup-config-update
, and so on. -
target_uri(optional):
string
URI of the resource.
400 Response
Examples
The following example shows how to update the backup configuration for an Oracle Java Cloud Service instance by submitting a POST request on the REST resource using cURL.
Note: The command in this example uses the URL structure https://rest_server_url/resource-path
, where rest_server_url
is the REST server to contact for your identity domain (or Cloud Account). See Send Requests.
cURL Command
curl -i -X POST -u username:password -d @backupconfig.json -H "Content-type:application/json" -H "X-ID-TENANT-NAME:ExampleIdentityDomain" https://rest_server_url/paas/api/v1.1/instancemgmt/ExampleIdentityDomain/services/jaas/instances/ExampleInstance/backupconfig
Example of Request Body
The following shows an example of the request document in JSON format to change the automatic backup schedule. Include only those parameters that you want changed.
{
"fullBackupSchedule":
{
"hour":"5",
"dayOfWeek":"Sun"
},
"incrementalBackupSchedule":
{
"hour":"3"
}
}
Note: You cannot change the backup configuration when the backup service for the specified service instance is in a DISABLED
state.
The following shows an example of the request document in JSON format to disable the backup service for the specified service instance.
Note that the request payload should not include other parameters as supported in the backup configuration because you are disabling the backup service.
{
"backups": "DISABLE"
}
The following shows an example of the request document in JSON format to enable the backup service for the specified service instance.
{
"backups": "ENABLE",
"cloudStorageUser":"<username for jcs backup>",
"cloudStoragePassword":"<Auth token to access OCI object storage bucket>"
}
Note that the request payload can include other parameters as supported in the backup configuration when you re-enable the backup service. For example, if Oracle Java Cloud Service automatically disabled backups on the service instance after consecutive failures, then also correct the cause of the failure.
Example of Response Header and Body
The following shows an example of the response. The Location
header returns the URI that can be used to view the job status. See View the Status of an Operation by Job Id.
HTTP/1.1 202 Accepted
Date: Sat, 22 Apr 2017 19:38:50 GMT
Location: https://rest_server_url/paas/api/v1.1/activitylog/ExampleIdentityDomain/job/1882092
Content-Type: application/json
...
{
"operationName":"backup-config-update",
"target_uri":"https:\/\/rest_server_url\/paas\/api\/v1.1\/instancemgmt\/ExampleIdentityDomain\/services\/jaas\/instances\/ExampleInstance\/backupconfig",
"job_id":"1882092"
}