PostgreSQL on SAP BTP - Instance sharing | 'reference' service plan

[antoniojmnunes]

PostgreSQL instances can be shared between different environments and different accounts to enable reuse of instances in various scenarios.

The mechanism leverages a configuration parameter for service instance creation/update and supports different scenarios:

• Sharing a Service instance between different sub-accounts.
• Sharing a Service instance between Kyma and Cloud Foundry.
• Sharing a Service instance between Cloud Foundry and Kyma.

In this blog post we will try to explain the steps to create a "reference" instance pointing to a shared PostgreSQL instance. We will touch the below topics:

1. Update an already active instance as ‘sharable’ using BTP Cockpit
2. Create a new ‘virtual’ instance referencing a source instance
3. Cloud Foundry (CF) CLI operations for updating and creating shared instances
4. Kyma environment: allowing access to PostgreSQL shared instances

Please note:

• You can only share service instances of the service plan ’standard’ or ’premium’. It only works in between sub-accounts inside the same BTP region, the sharing works also between different global accounts, but the sub-accounts need to be both in same region (e.g. EU10).
• A reference service instance can be used like any "standard", "premium” instance, to be able to create it you need to use ‘reference’ service plan as entitlements.
• You can bind or unbind it, create service keys etc., however, to modify database settings or configurations, you still need to use the source instance.

1️⃣  Update an active instance as ‘sharable’ using BTP Cockpit

A Postgres instance can be shared between different accounts in the same landscape, the source instance needs to be shared explicitly to be able to create a "reference" instance afterwards.
As a first step to use shared instances you need to setup the source instance with the list of sub-accounts that you allow to share the instances.
So, you need to have already available at least one target sub-account to add to the instance shares list

Configure your instance as ‘sharable’:

To be able to share an instance you need to add the list of sub-accounts that who want to share with.
An instance can only be share via an update process and not during the creation.
Go to the source sub-account where you have the instance and update the parameter ‘instance_shares’ with the list of sub-accounts where you want to created new instances referencing the shared one. To create the "reference" instance use the 'reference' service plan entitlement.

Below the JSON block that you need to use to update the the instance share list:

{
"instance_shares":{
"op": "add",
"values": [<”suba-account1”>]
}
}

The list of sub-accounts is additive, so you do not need to always provide the complete list of sub-accounts IDs. You can use the operations “op” to update the list of sub-accounts:

• “add” – add sub-account
• “delete” – delete sub-account

In the update command parameters you need to provide the list of subs-accounts, see below example:

{
"instance_shares":{
"op": "add",
"values": [”1b73a8a4-357b-xxxx-8a37-1c245b83c443"]
}
}

In the source sub-account, go to your instance and select update option and add the above JSON block.

Note: 

• The update operation can only include this parameter (including more parameters in the JSON block will result in an update error).
• A new extension api endpoint is available to retrieve shared status ('instance_share_status') and the list of all shared sub-accounts for an instance ('shared_subaccounts'), please refer to the official product documentation on the SAP Help Portal.

2️⃣  Create a new ‘virtual’ instance referencing a source instance using BTP Cockpit

Create a new ‘virtual’ instance in the target sub-account:

By "virtual" instance we mean an instance that is referencing a "physical" instance deployed as shared with the sub-account where you want to create a "reference" instance.

To be able to create a instance using as reference a shared instance, you need to have the proper entitlements in your target sub-account ('reference' service plan). Please verify if you have the “reference” service plan available, as shown below:

Check your entitlements (‘reference’ service plan). 

After selecting the “reference” service plan, you need to fill the rest of the inputs as a normal instance creation.

Select “next” as you will need to add the source instance ID. Check the source instance ID that you want to use as reference in the source sub-account, using the BTP Cockpit instance details, then use it in the 'source_instance_id' JSON block parameter, for creating the "reference" instance.

After adding the 'source_instance_id', you can select 'Create'. After you can check the new instance details and you will be able to see that was created using the ‘reference’ service plan.

The 'source_instance_id 'parameter is visible in the instance parameters via BTP Cockpit or you can retrieve it via be below Cloud Foundry command line (CLI):

cf service <instance name> --params

3️⃣  CF CLI operations for updating and reference shared instances

Alternative to BTP Cockpit operations you can use also the Cloud Foundry CLI operations to execute the necessary steps to create and update the instance configurations.

Share a service instance

To share a service instance to a sub-account you can share the source instance using the below CF CLI command:

cf update-service ${source-instance-name} -c '{"instance_shares":{"op": "add", "values": ["<subaccount1>"]}}'

If the reference service instance has been deleted, you can also unshare the previously shared instance from the sub-account, using the below command:

cf update-service ${source-instance-name} -c '{"instance_shares":{"op": "delete", "values": ["<subaccount2>"]}}'

Create a new ‘virtual’ service instance

To create a reference instance for the Postgres instance with the instance ID <source-instance-id>, please leverage the following CF CLI command:

cf create-service postgresql-db reference reference-example -c '{"source_instance_id": "<source-instance-id>"}'

‘reference’ is the service plan | ‘reference-example’ is the name of the new "virtual" instance to be created.

4️⃣  Kyma environment: Allowing access to PostgreSQL shared instances

Sharing a Service Instance between Kyma and Cloud Foundry

A PostgreSQL instance created in Kyma can also be shared to a Cloud Foundry environment in the same sub-account, but you need to share the service instance from Kyma, even if you stay in the same sub-account <subaccount_id>.

You can do it via BTP Cockpit using the Kyma dashboard, and updating the service instance parameters. Don’t forget that to share the instance you need to add to the instance parameters in kyma the ‘instance_shares’ values:

parameters: instance_shares: op: add values: - <subaccount_id>

For this scenario, you need to explicitly add your CF domain <cf_domain> to the ’allow_list’ parameter of your PostgreSAL in Kyma to allow access from Cloud Foundry.

A Postgres instance created in Cloud Foundry can also be shared to a Kyma environment in the same sub-account

Be aware that sharing a CF private instance with Kyma is not supported, as the it needs to be accessible from Kyma and the CF instance needs to be created with the ‘public_access' parameter set to true.

Note: ‘allow_access’ - per default an instance with public access enabled is accessible from any Cloud Foundry app in the CF landscape it was provisioned. Any additional IP to be allowlisted need to be added into this allowlist. Each time you provide here a new IP/domain, it will overwrite the existing settings, so always provide the complete list of IPs if you update 'allow_access' parameter.

For this scenario, you need to explicitly add your Kyma cluster-ip <cluster_ip> to the ’allow_list’ of your PostgreSQL instance in Cloud Foundry to make sure access from Kyma is possible.

We hope the information provided above assists you in taking full advantage of the shared instance feature in PostgreSQL on SAP BTP.

Please check out the blog post below, where we've shared a list of key topics from the product team.

• PostgreSQL on SAP BTP - Are you looking for official blog posts? Blog INDEX

For other relevant product updates and features refer always to the product official documentation at SAP Help Portal.

Thanks for your reading,

SAP BTP Backing Services – Product Management