Skip to content

Commit

Permalink
doc: Add explanation for service binding options (#35)
Browse files Browse the repository at this point in the history
* Initial

* Minor

* Add suggested changes
  • Loading branch information
newtork authored Sep 9, 2024
1 parent 712949a commit 97b8012
Showing 1 changed file with 73 additions and 6 deletions.
79 changes: 73 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -478,14 +478,55 @@ DeploymentApi api = new DeploymentApi(client);

For more customization, creating a [HeaderProvider](https://sap.github.io/cloud-sdk/docs/java/features/connectivity/http-destinations#about-headerproviders) is also possible.

## Requirements and Setup
## Requirements and Setup for AI Core

### Set AI Core credentials as environment variable
For any AI Core service interaction, the SAP AI SDK requires credentials to be available at application runtime.
By default, the credentials are extracted automatically from a service instance of type "aicore" bound to the application.
Running the application locally without this service binding will throw an exception:

- Running the application locally without a service binding will throw:
```
Could not find any matching service bindings for service identifier 'aicore'
```

There are multiple options to register the service binding:
* Regular service binding in SAP BTP Cloud Foundry (resulting in `VCAP_SERVICES` env var entry).
* Set an environment variable explicitly: `AICORE_SERVICE_KEY`
* Define and use a _Destination_ in _BTP Destination Service_.
* (For CAP applications) use the [hybrid testing](https://cap.cloud.sap/docs/advanced/hybrid-testing#services-on-cloud-foundry) approach _(not recommended for production)_.
* For example: `cds bind --to aicore --exec mvn spring-boot:run`
* Leveraging `"user-provided"` service binding _(not recommended for production)_.
* Define and use a custom `ServiceBinding` or `ServiceBindingAccessor` declaration in application _(not recommended for production)_.

### Regular service binding in SAP BTP Cloud Foundry

* Bind an existing service instance of type `aicore` to your application.
[With SAP BTP multiple options are available](https://help.sap.com/docs/btp/sap-business-technology-platform/binding-service-instances-to-applications): using the web interface, the CLI, MTA or manifest.

<details><summary>After application restart, there should be an "aicore" entry in environment variable <code>VCAP_SERVICES</code>.</summary>

```json
{
"aicore": [
{
"clientid": "...",
"clientsecret": "...",
"url": "...",
"identityzone": "...",
"identityzoneid": "...",
"appname": "...",
"serviceurls": {
"AI_API_URL": "..."
}
}
]
}
```

</details>

### Set credentials as dedicated environment variable

`Could not find any matching service bindings for service identifier 'aicore'`
- Go into the BTP Cockpit
- Go into the SAP BTP Cockpit
- Instances and Subscriptions -> Instances -> AI Core -> View Credentials -> Copy JSON
- Set it as an environment variable `AICORE_SERVICE_KEY` in your IDE

Expand All @@ -494,7 +535,33 @@ For more customization, creating a [HeaderProvider](https://sap.github.io/cloud-
export AICORE_SERVICE_KEY='{ "serviceurls": { "AI_API_URL": ...'
```

### Run the Spring Boot application
### Define and use a Destination

* Lookup service-key credentials as explained in the previous step for `AICORE_SERVICE_KEY`.

* <details><summary>Define a new destination in the SAP BTP Destination Service using the service-key credentials</summary>

* (Destinations can be added on subaccount level and on service instance level.)
* (The URL field requires an additional path segment: `/v2`)
* **Name**: _my-aicore_
* **Type**: HTTP
* **URL**: _[serviceurls.AI_API_URL]/v2_
* **Proxy-Type**: Internet
* **Authentication**: _Oauth2ClientCredentials_
* **Client ID**: _[clientid]_
* **Client Secret**: _[clientsecret]_
* **Token Service URL Type**: Dedicated
* **Token Service URL**: _[url]_

</details>

* At application runtime the following can be executed:
```java
Destination destination = DestinationAccessor.getDestination("my-aicore");
ApiClient client = Core.getClient(destination);
```

### Run the Spring Boot test application

```shell
cd e2e-test-app
Expand Down

0 comments on commit 97b8012

Please sign in to comment.