******************************** Managing Namespace Snapshots ******************************** A namespace snapshot is a point-in-time copy of the complete namespace. You can take a namespace snapshot manually or schedule when you have multiple dependent applications in the namespace. Robin CNS does not allow you to take a snapshot of an empty namespace. You can restore namespaces when required to a point-in-time state. When you restore, Robin software restores all the components of the namespace. Using Robin CNS, you can also back up the namespace snapshots to supported cloud storage for future use, and you can also clone a namespace snapshot. As the namespace snapshot is a snapshot of the complete namespace, individual application snapshots are not part of the namespace snapshot. --------------- Snapshot names --------------- All the snapshot names are prefixed with an internally generated unique name within a namespace. For example, if you create a namespace snapshot with the name ``testsnapshot``, the namespace snapshot name would be ``testnamespacexfcey_testsnapshot``. In the above example: - ``testnamespace`` is the namespace name. - ``xfcey`` are the random characters that are appended to the namespace name to form the unique name (``testnamespacexfcey``). - ``testsnapshot`` is the name of the snapshot that you provided .. Note:: To identify a namespace snapshot from the list of snapshots, you should run ``robin snapshot info`` command. For the namespace snapshot, you can find the Applications section in the command output. ---------------------------- Namespace snapshot and RBAC ---------------------------- In an RBAC environment, you must consider the following points: - A super admin cannot take namespace snapshots other than Administrators tenant namespaces. - A tenant administrator can perform namespace snapshot and restore only on the namespaces with that tenant. - A namespace owner can perform a namespace snapshot/restore he owns (user must be logged in to the right tenant). - A user who has been provided the shared access of a namespace can perform a snapshot/restore of that namespace. ------------------------------------------ Points to consider for Namespace Snapshot ------------------------------------------ The following are important points you should consider when working with namespace snapshots: - If you register two Helm apps with the same name in different namespaces, Robin CNS does not auto-register the second app with the same name. You must manually register the second app using the ``robin app register helm/ -n `` command. - When you delete or uninstall Helm apps from a namespace and later if you try to restore the apps using namespace snapshot, the ``helm list -A`` command output will be empty. However, the apps will be there in the namespace. The restored apps will be Flex apps and not Helm apps. App users can use them as any regular app. However, as a Robin admin, only you know that they are not the helm app but the Flex app. - A namespace snapshot is a snapshot of the whole namespace. So, individual application snapshots are not part of the namespace snapshot. **Topics covered in this chapter:** ============================================== ==================================================================================== ``robin namespace snapshot`` Create snapshot of all components of a namespace manually ``robin namespace snapshot-schedule`` Schedule namespace snapshots ``robin namespace backup-create`` Create an external storage repo to push namespace snapshots ``robin namespace attach-repo`` Attach a repo for backup purposes ``robin namespace detach-repo`` Detach a repo from a namespace ``robin namespace backup-schedule`` Schedule backups for namespace snapshots ``robin namespace restore`` Restore a namespace from a namespace snapshot ``robin namespace clone`` Clone a namespace snapshot ============================================== ==================================================================================== --------------------------- Create a Namespace Snapshot --------------------------- .. tabs:: .. tab:: CLI In order to capture all the objects contained within a namespace via a snapshot, issue the following command: .. code-block:: text # robin namespace snapshot --desc ===================================== ============================================================ ``name`` Name of the namespace being snapshotted ``snapname`` A name that would be assigned to the snapshot being taken ``--desc `` Description of the snapshot being taken ===================================== ============================================================ **Example:** .. code-block:: text # robin namespace snapshot ns1 demo Job: 857 Name: NamespaceSnapshot State: VALIDATED Error: 0 Job: 857 Name: NamespaceSnapshot State: WAITING Error: 0 Job: 857 Name: NamespaceSnapshot State: COMPLETED Error: 0 .. Note:: You can run the ``robin snapshot list --level namespace`` command to view the snapshot created. More details on the aforementioned command can be found `here `_. .. tab:: API Creates a namespace snapshot. **End Point:** /api/v3/robin_server/namespaces/ **Method:** PUT **URL Parameters:** None **Data Parameters:** - ``action: snapshot`` - This mandatory field within the payload specifies the snapshot operation is to be performed. - ``snapname: `` - This mandatory field within the payload specifies the name of the snapshot. - ``desc: `` - Utilizing this parameter by specifiying a string based description results in it being associated with the snapshot to be taken. **Port:** RCM Port (default value is 29442) **Headers:** - ``Authorization: `` : Authorization token to identify which user is sending the request. The token can be acquired from the login API. **Success Response Code:** 202 **Error Response Code:** 500 (Internal Server Error), 404 (Not Found Error), 401 (Unauthorized Error), 400 (Invalid Api Usage Error) **Example Response:** .. raw:: html
Output .. code-block:: text { "jobid":18947 } .. raw:: html
------------------------- List Namespace Snapshots ------------------------- As namespace based snapshots are treated as similarly to application based snapshot, they too can be listed via the ``robin snapshot list`` command. In order to exclusively list only namespace based snapshot the ``level`` filter can be used with its value set to ``namespace``. More details on the aforementioned command can be found `here `_. ------------------------------- Schedule Namespace Snapshots ------------------------------- .. tabs:: .. tab:: CLI Robin CNS enables you to schedule to take namespace snapshots automatically and set retention policies. You can set the schedule using a JSON file or a CRON string. You can enable or disable a namespace snapshot schedule as per your requirements. Note: You must first set up a namespace snapshot schedule first if you want to set up a back schedule for a namespace snapshots. To set up a namespace snapshot schedule, run the following command: .. code-block:: text # robin namespace snapshot-schedule --snapshot-schedule --snapshot-schedule-cron --retain --disable --enable ================================================== ============================================================ ``name`` Name of namespace to snapshot ``--snapshot-schedule `` Snapshot schedule specified as JSON ``--snapshot-schedule-cron `` Snapshot schedule specified as CRON string ``--retain `` Number of snapshots to retain with the specified schedule ``--disable`` Disable the specified schedule ``--enable`` Enable the specified schedule ================================================== ============================================================ The fields that can be specified in the JSON file describing a schedule are: =============== =========================================================================================== ``frequency`` The overall frequency at which to take snapshots. Valid values include: 'hourly', 'daily', 'weekly', 'monthly'. ``minute`` An integer between 1-59 representing the minute at which the operation should be run. This field is optional, and the default value is 1 if not specified. ``hour`` An integer between 0-23 representing the hour at which the operation should be run. This field is optional, and the default value is 0 if not specified. ``weekday`` An integer between 0-6 representing the day of the week on which the operation should be run. Sunday is represented by 0 and so on and so forth. This field is optional, and the default value is 0 if not specified. ``monthday`` An integer between 1-28 representing the day of the month on which the operation should be run. This field is optional, and the default value is 1 if not specified. =============== =========================================================================================== .. Note:: Only one snapshot schedule of each frequency type can be created. You cannot set 2 different hourly snapshot schedules. However, 1 hourly and 1 weekly schedule is a supported combination. **Snapshot Schedule as a JSON:** Here's an example of a JSON file describing a snapshot schedule: .. code-block:: json { "frequency": "weekly", "weekday": 3, "hour": 5, "minute": 30, } The above JSON will configure a snapshot schedule running every week on Wednesday at 05:30 AM. .. code-block:: text # robin namespace snapshot-schedule a1 --snapshot-schedule demo_sched.json --retain 2 --enable --wait Job: 116 Name: NamespaceSnapshotSchedule State: PREPARED Error: 0 Job: 116 Name: NamespaceSnapshotSchedule State: COMPLETED Error: 0 **Snapshot Schedule as a CRON:** Robin allows one to specify a snapshot schedule via a CRON string with the standardised format. However there are three caveats. First the minute parameter of the string must always be set as minutely snapshot schedules are not supported. In a similar vein the parameter indicating the month must also be set (if applicable) as yearly schedules are not supported either. Finally one cannot specify both a day of the month and a day of the week as it is not a support configuration. Here's an example of a CRON string describing a snapshot schedule: .. code-block:: text 30 5 * * 3 The above CRON string configures a snapshot schedule running every week on Wednesday at 05:30 AM. .. code-block:: text # robin namespace snapshot-schedule a1 --snapshot-schedule-cron "30 5 * * 3" --retain 2 --enable --wait Job: 116 Name: NamespaceSnapshotSchedule State: PREPARED Error: 0 Job: 116 Name: NamespaceSnapshotSchedule State: COMPLETED Error: 0 ------------------------------------------------ Attach an External Storage Repo to a Namespace ------------------------------------------------ .. tabs:: .. tab:: CLI Robin CNS allows entire namespaces, plus the applications and the data associated with them to be backed up to an external storage device or service such as AWS S3, Google GCS object stores, etc. Repo management is explained at length `here `_. Issue the following command to attach a repo to a namespace: .. code-block:: text # robin namespace attach-repo ============================== ========================================================= ``namespace`` Name of the namespace ``repo_name`` Name of the storage repo ============================== ========================================================= **Example:** .. code-block:: text # robin namespace attach-repo ns1 repo1 --wait Job: 115 Name: NamespaceAddRepo State: VALIDATED Error: 0 Job: 115 Name: NamespaceAddRepo State: COMPLETED Error: 0 .. tab:: API Attaches a repo to a namespace in order to enable backups for it. **End Point:** /api/v3/robin_server/namespaces/ **Method:** PUT **URL Parameters:** None **Data Parameters:** - ``action: add_repo`` - This mandatory field within the payload specifies that the repo attach operation is to be performed. - ``repo_name: `` - This mandatory field within the payload specifies the repo to be attached to the namespace. **Port:** RCM Port (default value is 29442) **Headers:** - ``Authorization: `` : Authorization token to identify which user is sending the request. The token can be acquired from the login API. **Success Response Code:** 202 **Error Response Code:** 500 (Internal Server Error), 404 (Not Found Error), 401 (Unauthorized Error), 400 (Invalid API Usage Error) **Example Response:** .. raw:: html
Output .. code-block:: text { "jobid":19286 } .. raw:: html
------------------------------------------------ Detach an External Storage Repo from a Namespace ------------------------------------------------ .. tabs:: .. tab:: CLI A previously attached storage repo can be detached from namespace using the following command: .. code-block:: text # robin namespace detach-repo --yes ============================== ================================================================= ``name`` Name of namespace to detach repo from ``repo_name`` Name of the storage repo ``--yes`` Do not prompt the user for confirmation ============================== ================================================================= **Example:** .. code-block:: text # robin namespace detach-repo ns1 repo1 --wait Job: 116 Name: NamespaceRemoveRepo State: PREPARED Error: 0 Job: 116 Name: NamespaceRemoveRepo State: COMPLETED Error: 0 .. tab:: API Detaches a previously attached repo from a namespace. **End Point:** /api/v3/robin_server/namespaces/ **Method:** PUT **URL Parameters:** None **Data Parameters:** - ``action: remove_repo`` - This mandatory field within the payload specifies that the repo detach operation is to be performed. - ``repo_name: `` - This mandatory field within the payload specifies the repo to be detached from the namespace. - ``name: `` - This mandatory field within the payload specifies the namespace from which the aforementioned repo should be detached. **Port:** RCM Port (default value is 29442) **Headers:** - ``Authorization: `` : Authorization token to identify which user is sending the request. The token can be acquired from the login API. **Success Response Code:** 202 **Error Response Code:** 500 (Internal Server Error), 404 (Not Found Error), 401 (Unauthorized Error), 400 (Invalid API Usage Error) **Example Response:** .. raw:: html
Output .. code-block:: text { "jobid":19285 } .. raw:: html
-------------------------- Create a Namespace Backup -------------------------- .. tabs:: .. tab:: CLI In order to create a backup of a namespace, issue the following command: .. code-block:: text # robin namespace backup-create --snapshotid --backupname --purge-snapshot ======================= ================================================================================================================================================== ``name`` Name of the namespace being backed up ``reponame`` Name of the repo where the backup will be pushed ``--snapshotid`` Unique ID of snapshot to be backed up. If not provided a snapshot will be created implicitly ``--backupname`` Name to assign to backup ``--purge-snapshot`` Delete the snapshot pushed to the repo after successfully creating the backup.This option is only valid when a snapshot ID is not provided. ======================= ================================================================================================================================================== **Example:** .. code-block:: text # robin namespace backup-create ns1 repo1 --wait Creating namespace backup 'ns1_nsbackup-1581809777' Job: 213 Name: NamespaceBackupCreate State: PROCESSED Error: 0 Job: 213 Name: NamespaceBackupCreate State: WAITING Error: 0 Job: 213 Name: NamespaceBackupCreate State: AGENT_WAIT Error: 0 Job: 213 Name: NamespaceBackupCreate State: COMPLETED Error: 0 .. note:: The ability to create a backup is subject to Robin Role Based Access Control (RBAC). By default, all Cluster Users (users having the user role) have permission to create backups, provided they can access the underlying Namespace snapshot. Cluster Administrators (users having the **superadmin** role) have permission to create backups from all Namespace snapshots. See the section on :ref:`UserManagement` for details on how Robin RBAC works. Before creating a backup, the underlying namespace must be attached to the target repo. .. tab:: API Creates a namespace backup. **End Point:** /api/v3/robin_server/namespaces/ **Method:** PUT **URL Parameters:** None **Data Parameters:** - ``action: backup`` - This mandatory field within the payload specifies the backup operation is to be performed. - ``repo: `` - This mandatory field within the payload specifies the name of the repo in which the backup should be stored. - ``backupname: `` - This mandatory field within the payload specifies the name of the backup to be created. - ``snapshotid: `` - Utilizing this parameter, by specifying a snapshot ID, results in the associated snapshot being backed up. - ``purge_snapshot: true`` - Utilizing this parameter results in the snapshot being deleted once it has successfully been pushed to the repo. This option is only valid when a snapshot ID is not provided. **Port:** RCM Port (default value is 29442) **Headers:** - ``Authorization: `` : Authorization token to identify which user is sending the request. The token can be acquired from the login API. **Success Response Code:** 202 **Error Response Code:** 500 (Internal Server Error), 404 (Not Found Error), 401 (Unauthorized Error), 400 (Invalid Api Usage Error) **Example Response:** .. raw:: html
Output .. code-block:: text { "jobid":19289 } .. raw:: html
-------------------------- Schedule Namespace Backup -------------------------- .. tabs:: .. tab:: CLI You can set up automatic backup schedules for backing up namespace snapshots and set retention periods. Using the backed-up snapshots you can restore namespaces of a required state. .. Note:: You must set a namespace snapshot schedule before you set up a backup schedule. You can set the schedule using a JSON file or a CRON string. .. code-block:: text # robin namespace backup-schedule --backup-schedule --backup-schedule-cron --retain --filter --disable --enable ================================================== ========================================================= ``name`` Name of namespace to backup ``--backup-schedule `` Backup schedule specified as JSON ``--backup-schedule-cron `` Backup schedule specified as CRON string ``--retain `` Number of backups to retain with the specified schedule ``--filter `` Frequency of snapshot schedule to backup ``--disable`` Disable the specified schedule ``--enable`` Enable the specified schedule ================================================== ========================================================= The fields that can be specified in the JSON file describing a schedule are: =============== =========================================================================================== ``frequency`` The overall frequency at which to take backups. Valid values include: 'hourly', 'daily', 'weekly', 'monthly'. ``minute`` An integer between 1-59 representing the minute at which the operation should be run. This field is optional, and the default value is 1 if not specified. ``hour`` An integer between 0-23 representing the hour at which the operation should be run. This field is optional, and the default value is 0 if not specified. ``weekday`` An integer between 0-6 representing the day of the week on which the operation should be run. Sunday is represented by 0 and so on and so forth. This field is optional, and the default value is 0 if not specified. ``monthday`` An integer between 1-28 representing the day of the month on which the operation should be run. This field is optional, and the default value is 1 if not specified. =============== =========================================================================================== .. Note:: Only one backup schedule of each frequency type can be created. You cannot set 2 different hourly backup schedules. However, 1 hourly and 1 weekly schedule is a supported combination. **Backup Schedule as a JSON:** Here's an example of a JSON file describing a backup schedule: .. code-block:: json { "frequency": "weekly", "weekday": 0, "hour": 7, "minute": 15, } The above JSON will configure a backup schedule running every week on Sunday at 07:15 AM. .. code-block:: text # robin namespace backup-schedule ns1 --backup-schedule demo_sched.json --retain 3 --enable --filter daily --wait Job: 116 Name: NamespaceBackupSchedule State: PREPARED Error: 0 Job: 116 Name: NamespaceBackupSchedule State: COMPLETED Error: 0 **Backup Schedule as a CRON:** Robin allows one to specify a backup schedule via a CRON string with the standardised format. However there are three caveats. First the minute parameter of the string must always be set as minutely backup schedules are not supported. In a similar vein the parameter indicating the month must also be set (if applicable) as yearly schedules are not supported either. Finally one cannot specify both a day of the month and a day of the week as it is not a support configuration. Here's an example of a CRON string describing a snapshot schedule: .. code-block:: text 15 7 * * 0 The above CRON string will configure a backup schedule running every week on Sunday at 07:15 AM. .. code-block:: text # robin namespace backup-schedule ns1 --backup-schedule-cron "15 7 * * 0" --retain 2 --enable --filter daily --wait Job: 116 Name: NamespaceBackupSchedule State: PREPARED Error: 0 Job: 116 Name: NamespaceBackupSchedule State: COMPLETED Error: 0 ----------------------------- Restore a Namespace Snapshot ----------------------------- .. tabs:: .. tab:: CLI A namespace can be restored to the point-in-time state saved within an associated snapshot or backup (a snapshot that has been pushed to a storage repo). Issue the following command to recover a namespace to a specific point-in-time: .. code-block:: text # robin namespace restore --snapshotid --backupid --skip-rx-pvcs --include-rx-pvcs ================================================== ========================================================= ``name`` Name of the namespace to be restored ``--snapshotid `` ID of snapshot to restore to ``--backupid `` ID of backup to restore to ``--skip-rx-pvcs`` Skip restoring RWX and ROX PVCs ``--include-rx-pvcs`` Include the restoration of RWX and ROX PVCs ================================================== ========================================================= .. note:: Some caveats to take note of include: - One of ``--snapshotid`` or ``--backupid`` must be provided. - If the namespace is restored to a point in time where it was empty, the underlying Kubernetes objects associated with the applications currently within the namespace will be deleted. However the applications will still be registered with their deployment source i.e. helm applications will still show via the ``helm list`` command. This behavior is consistent with regards to operators as well. Moreover this will also be the case whenever an application's objects are deleted as part of a restoration operation. - The opposite of the above point is also true. That is to say, if an application's Kubernetes objects are created as part of the restoration operation, the application itself will not be registered with the deployment source i.e. eventhough objects for a helm application will be recreated the application will not be available via the ``helm list`` command. This behavior is consistent with regards to operators as well. Moreover the objects will be registered to Robin as part of a FlexApp which is treated as normal application in most cases. **Example:** .. code-block:: text # robin namespace restore z1 --snapshotid 3f44de78ff7211eb846f2b80971dc0e5 --wait Job: 116 Name: NamespaceRollback State: PREPARED Error: 0 Job: 116 Name: NamespaceRollback State: COMPLETED Error: 0 .. tab:: API Restore a namespace to the point-in-time state saved within an associated snapshot or backup (a snapshot that has been pushed to a storage repo). **End Point:** /api/v3/robin_server/namespaces/ **Method:** PUT **URL Parameters:** None **Data Parameters:** - ``action: rollback`` - This mandatory field within the payload specifies the restore operation is to be performed. - ``backupid: `` - Utilizing this parameter, by specifying a backup ID, results in the specified namespace being restored to the state stored in the associated backup. - ``snapshotid: `` - Utilizing this parameter, by specifying a snapshot ID, results in the specified namespace being restored to the state stored in the associated snapshot. - ``skip_rx_pvcs: true`` - Utilizing this parameter results in the RWX and ROX volumes associated with the namespace not being restored. - ``include_rx_pvcs: true`` - Utilizing this parameter results in the RWX and ROX volumes associated with the namespace being restored. .. Note:: At least one of the ``snapshotid`` or ``backupid`` parameters must be specified. **Port:** RCM Port (default value is 29442) **Headers:** - ``Authorization: `` : Authorization token to identify which user is sending the request. The token can be acquired from the login API. **Success Response Code:** 202 **Error Response Code:** 500 (Internal Server Error), 404 (Not Found Error), 401 (Unauthorized Error), 400 (Invalid Api Usage Error) **Example Response:** .. raw:: html
Output .. code-block:: text { "jobid":19291 } .. raw:: html
------------------- Clone a Namespace ------------------- .. tabs:: .. tab:: CLI Robin CNS provides a native method to create a copy of a namespace and all of the applications within it using a namespace snapshot or backup. A cloned namespace behaves similarly to a cloned application thus having similar properties and advantages. More details on this can be found `here `_. In order to clone a namespace, run the following command: .. code-block:: text robin namespace clone --snapshotid --backupid --start-hydration ================================ ==================================================================================================================================== ``name`` Destination namespace to which applications are to be cloned ``clonename`` Name to be prefixed to cloned applications ``--snapshotid `` ID of the snapshot to be cloned ``--backupid `` ID of the backup to be cloned ``--start-hydration`` Start the hydration of cloned applications in the background. Note this option is only valid when cloning a namespace via a backup ================================ ==================================================================================================================================== **Example:** .. code-block:: text # robin namespace clone u1n1 cl-u1 --snapshotid fc0e74ba0fc611ec90008fd9e303c008 Job: 1010 Name: NamespaceClone State: VALIDATED Error: 0 Job: 1010 Name: NamespaceClone State: WAITING Error: 0 Job: 1010 Name: NamespaceClone State: COMPLETED Error: 0 .. tab:: API Creates a copy of a namespace and all of the applications within it using a namespace snapshot or backup. **End Point:** /api/v3/robin_server/namespaces/ **Method:** PUT **URL Parameters:** None **Data Parameters:** - ``action: clone`` - This mandatory field within the payload specifies the clone operation is to be performed. - ``backupid: `` - Utilizing this parameter, by specifying a backup ID, results in the cloned namespace having the equivalent state as that stored in the associated backup. - ``snapshotid: `` - Utilizing this parameter, by specifying a snapshot ID, results in the cloned namespace having the equivalent state as that stored in the associated snapshot. - ``hydrate: true`` - Utilizing this parameter results in the hydration of the cloned applications within the namespace being started. Note this option is only valid when the ``backupid`` parameter is utilized. .. Note:: At least one of the ``snapshotid`` or ``backupid`` parameters must be specified. **Port:** RCM Port (default value is 29442) **Headers:** - ``Authorization: `` : Authorization token to identify which user is sending the request. The token can be acquired from the login API. **Success Response Code:** 202 **Error Response Code:** 500 (Internal Server Error), 404 (Not Found Error), 401 (Unauthorized Error), 400 (Invalid Api Usage Error) **Example Response:** .. raw:: html
Output .. code-block:: text { "jobid":19297 } .. raw:: html
-------------------------- Delete Namespace Snapshot -------------------------- As namespace based snapshots are treated similarly to application based snapshots, the ``robin snapshot delete`` command can be used to delete namespace based snapshots. More details on the aforementioned command can be found `here `_.