Backup & Restore IDHub

Pre-Requisites

To run the commands for backup and restore, it requires authorization header which is the Tenant Admin Secret encoded in Base64. Make sure you generate the Base64 encoded Tenant Admin Secret before running the backup and restore operations on your tenant.

Run the following command to get the tenant management password encoded in Base64:

echo -n ":$(kubectl get secret tenant-admin-user-password -o jsonpath='{.data.password}' -n [IDHUB_INSTANCE] | base64 -d)" | base64

Backup And Restore Operations

The following section illustrates the CURL commands for backing up and restoring tenant data using.

info

• Permissions: Anyone with the tenant admin password (as mentioned in the prerequisites above) can execute backup/restore commands.
• Please refer to the glossary section to know more about the variables being used in the commands.
• Please refer to the troubleshooting guide to diagnose and resolve errors during backup and restore operations efficiently.
• Cloud Provider Backups: Full cluster backups (GCP/Azure/AWS) do not include tenant-specific data. Use IDHub APIs for tenant-level granularity. Please consult your provider's documentation for full cluster backups and restore.

Back-up a specific tenant

Use the following cURL command to call the tenant management backup API from any terminal to backup a specific tenant.

curl --location --request POST 'https://[IDHUB_FQDN]/api/tenant-management/admin/backup' \ 
--header 'Authorization: Basic [TENANT_ADMIN_SECRET_BASE64]' \ 
--header 'Content-Type: application/json' \
--data-raw '{
    "tenantName": "[TENANT_ID]"
}'

Example Response:

{
    "message": "tenant 'sample' backed up successfully"
}

note

A compressed archive with a time stamp will be created in /apps/idhub/backups/ directory in IDHub server. This archive can be used to restore the tenant in the future

List backups

Use the following cURL command from any terminal to list all the backups created.

curl --location --request GET 'https://[IDHUB_FQDN]/api/tenant-management/admin/backups' \ 
--header 'Authorization: Basic [TENANT_ADMIN_SECRET_BASE64]'

Example Response

{
    "backups": [
        {
            "backupTime": "2025-02-07T23:55:32.767Z",
            "fileName": "azuree7k-2025-02-07T23:55:32.767Z.tar.gz",
            "tenantName": "azuree7k"
        },
        {
            "backupTime": "2025-02-08T23:55:28.998Z",
            "fileName": "azuree7k-2025-02-08T23:55:28.998Z.tar.gz",
            "tenantName": "azuree7k"
        }
    ]
}

info

• The response includes metadata for each backup (filename, tenant name, backup time).
• Empty arrays ("backups": []) indicate no backups exist

Restore a specific tenant

Use the following cURL command to call the tenant management restore API from any terminal in order to restore a specific tenant.

curl --location --request POST 'https://[IDHUB_FQDN]/api/tenant-management/admin/restore' \
--header 'Authorization: Basic [TENANT_ADMIN_SECRET_BASE64]' \
--header 'Content-Type: application/json' \
--data-raw '{
    "fileName": "[ARCHIVE_NAME]"}'

Example Response:

{
    "message": "tenant 'azuree7k' restored successfully"
}

Best Practices:

• Tenant name is automatically fetched from the backup file, therefore always validate the fileName before executing the restore.
• Use the List Backups command to confirm the backup’s metadata

Delete a backup

Use the following cURL command to delete a backup for a specific tenant.

curl --location --request POST 'https://[IDHUB_FQDN]/api/tenant-management/admin/backups/delete' \ 
--header 'Authorization: Basic [TENANT_ADMIN_SECRET_BASE64]' \ 
--header 'Content-Type: application/json' \
--data-raw '{
    "fileName": "[ARCHIVE_NAME]"
}'

Example Response

{
    "message": "backup 'azuree7k-2025-02-09T23:55:23.436Z.tar.gz' successfully deleted"
}

Glossary

The table below explains variables used in CURL commands throughout this documentation.

Variable	Description	Allowed Values/Format	Example	Notes
[IDHUB_FQDN]	FQDN of IDHub instance.	Valid domain	http://idhub.acme.com	Configured during deployment. See Setup Guide
[TENANT_ADMIN_SECRET_BASE64]	Base64 secret for tenant admin.	Base64 string	dGVuYW50Lk	Fetch using kubectl. See Pre-Reqs
[TENANT_ID]	Name of the tenant.	Lowercase, hyphens, numbers	alpha, beta-tenant	Max 24 characters
[ARCHIVE_NAME]	Backup archive filename.	<TENANT_ID>-<TIMESTAMP>.tar.gz	azuree7k-2025-02-09T23:55Z.tar.gz	Retrieve using List Backups
[IDHUB_INSTANCE]	Namespace for IDHub instance.	Lowercase, hyphens, numbers	idhub-prod, idhub-dev	No special characters allowed

Troubleshooting

This section maps common error codes encountered during backup, restore, and deletion operations.

Error Code	Command Affected	Description	Possible Causes	Resolution
401 Unauthorized	All CURL commands	Authentication failed.	Invalid [TENANT_ADMIN_SECRET_BASE64]	Regenerate the Base64 secret using valid credentials.
Could not resolve host	All CURL commands	Not able to resolve the host	Invalid [IDHUB_FQDN]	Verify the FQDN is correct and valid.
404 Not Found	Restore/Delete	Resource not found.	[ARCHIVE_NAME] does not exist.Typo in [ARCHIVE_NAME].	Use the List Backups command to confirm [ARCHIVE_NAME].
400 Bad Request	All CURL commands	Invalid request format.	Missing TENANT_ID or fileName in payload. Invalid JSON syntax.	Validate the payload structure and syntax.
500 Internal Error	All CURL commands	Server-side failure.	IDHub service disruption or misconfiguration.	Retry the operation. If persistent, contact IDHub Support.