IBM Cloud Docs
Sync associated resources

Sync associated resources

You can initiate a manual data synchronization request between root keys and other cloud resources, such as IBM Cloud Object Storage buckets or deployments of Cloud Databases, by using the IBM® Key Protect API, IBM Cloud console, or the Key Protect CLI plugin.

When you perform a key lifecycle action (for example rotate, restore, disable, enable, delete) on a root key that is associated with other IBM Cloud services, those IBM Cloud services are notified of the key lifecycle event and are encouraged to respond accordingly. In the case that the cloud services do not respond to the key lifecycle notification, you can use the sync API to initiate of a renotification of the key lifecycle event to those associated cloud services.

It can take up to four hours for services to respond to events and sync requests.

For example, you might delete a root key that has an association with IBM Cloud Object Storage (COS). After waiting 4 hours for changes to take effect, you notice that you are still able to access the key's resources despite expecting to be blocked from accessing those resources. In this case, you should call the sync API to notify COS of the deleted key lifecycle event so they can block access to the key's resources.

The sync API only initiates a request for synchronization. The IBM Cloud services associated with the key are responsible for managing all related associated resources and ensuring that the key state and key versions are up to date.

Syncing associated resources with the Key Protect console

  1. Log in to the IBM Cloud console.

  2. Go to Menu > Resource List to view a list of your resources.

  3. From your IBM Cloud resource list, select your provisioned instance of Key Protect.

  4. Click on the Associated Resources tab to see the list of resources.

  5. Click on the Manually sync resource icon.

  6. In the Manually sync associated resource dialog box, click on the button labeled, Manually sync to perform the synchronization.

Syncing associated resources with the Key Protect CLI plugin

This example shows how to synchronize a key and show the results. Before getting started, make sure to complete the required configuration for the Key Protect CLI plugin.

# synchronize the associated resources for a given key
$ ibmcloud kp key sync 94c06f9c-a07a-4961-8548-553cf7431f18

Synchronizing key...
OK
Key's associated resources are synchronized successfully

Required parameters

  • keyID_or_alias

    The ID or alias of the key that you want to sync.

  • -i, --instance-id

    The IBM Cloud instance ID that identifies your Key Protect instance.

    You can set an environment variable instead of specifying -i with the following command: $ export KP_INSTANCE_ID=<INSTANCE_ID>.

Optional parameters

  • -o, --output

    Set the CLI output format. By default, all commands print in table format. To change the output format to JSON, use --output json.

  • --key-ring

    A unique, human readable name for the key-ring. This is required if the user doesn't have permissions on the default key ring.

Syncing associated resources with the API

You can notify associated IBM cloud services of your Key Protect root key's lifecycle event by using the Key Protect API.

You can initiate the renotification of a key lifecycle event by making a POST call to the following endpoint.

https://<region>.kms.cloud.ibm.com/api/v2/keys/<keyID_or_alias>/actions/sync

  1. Retrieve your authentication credentials to work with the API.

  2. Initiate a manual data synchronization request by running the following curl command.

    $ curl -X POST \
    "https://<region>.kms.cloud.ibm.com/api/v2/keys/<keyID_or_alias>/actions/sync" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>"

    Replace the variables in the example request according to the following table.

Describes the variables that are needed to initiate a re-notification of a key lifecycle event
Variable Description
region Required. The region abbreviation, such as us-south or eu-gb, that represents the geographic area where your Key Protect instance resides.

For more information, see Regional service endpoints](/docs/key-protect?topic=key-protect-regions#service-endpoints).
keyID_or_alias Required. The identifier or alias for the root key that is associated with the cloud resources that you want to view.

For more information, see View Keys.
IAM_token Required. Your IBM Cloud access token. Include the full contents of the IAM token, including the Bearer value, in the curl request.

For more information, see Retrieving an access token.
instance_ID Required. The unique identifier that is assigned to your Key Protect service instance.

For more information, see Retrieving an instance ID.

A successful GET api/v2/keys/<keyID_or_alias>/actions/sync request returns an HTTP 204 No Content response, which indicates that the IBM cloud service that is associated with the specified key has been notified.

Synchronization considerations

The sync API can only be initialized if it has been longer than an hour since the last notification to the associated cloud services of the key. If you send a request to this API and the key has been synced or a key lifecycle action has been taken within the past hour, the API will return a 409 Conflict response.

You can view associated resources to determine which services are relevant to synchronization.