Skip to content

docs(cds-connect): add UPSI binding section and cross-link from cds-env #2973

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mariayord wants to merge 3 commits into
base: main
Choose a base branch
from
Open

docs(cds-connect): add UPSI binding section and cross-link from cds-env #2973

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ace7a41
docs(cds-connect): add UPSI binding section and cross-link from cds-env
mariayord Oct 29, 2026
d9fa5ec
Merge branch 'main' into vcap-upsi-binding
mariayord Oct 29, 2026
4d2cc7c
Update node.js/cds-env.md
mariayord Oct 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
154 changes: 154 additions & 0 deletions node.js/cds-connect.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -503,6 +503,160 @@ cds env get requires.<servicename>
```
:::

#### User-Provided Service Instances { #vcap-upsi }

[User-Provided Service Instances (UPSIs)](https://docs.cloudfoundry.org/devguide/services/user-provided.html) always appear in `VCAP_SERVICES` under the `"user-provided"` key, regardless of what service they hold credentials for. A common use case is cross-account service instance sharing.

Because all UPSIs share the same key, matching by kind label or type does not apply — only name and tag matching works. Use an explicit `vcap` config to override auto-matching:

<style scoped>
.no-stripes tr:nth-child(2n) {
background-color:unset;
}
</style>

<table class="no-stripes">
<thead>
<tr>
<th>CAP config</th>
<th>VCAP_SERVICES</th>
</tr>
</thead>
<tbody>
<tr>
<td>

```json
{
"cds": {
"requires": {
"my-service": {}
}
}
}
```
</td>
<td>

```json
{
"user-provided": [{
"name": "my-service",
"tags": []
}]
}
```
</td>
</tr>
<tr>
<td>

```json
{
"cds": {
"requires": {
"my-service": {}
}
}
}
```
</td>
<td>

```json
{
"user-provided": [{
"name": "my-upsi",
"tags": ["cds:my-service"]
}]
}
```
</td>
</tr>
<tr>
<td>

```json
{
"cds": {
"requires": {
"my-service": {
"kind": "my-kind"
}
}
}
}
```
</td>
<td>

```json
{
"user-provided": [{
"name": "my-upsi",
"tags": ["my-kind"]
}]
}
```
</td>
</tr>
Comment on lines +526 to +602

@sjvans sjvans Oct 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<tr>
<td>
```json
{
"cds": {
"requires": {
"my-service": {}
}
}
}
```
</td>
<td>
```json
{
"user-provided": [{
"name": "my-service",
"tags": []
}]
}
```
</td>
</tr>
<tr>
<td>
```json
{
"cds": {
"requires": {
"my-service": {}
}
}
}
```
</td>
<td>
```json
{
"user-provided": [{
"name": "my-upsi",
"tags": ["cds:my-service"]
}]
}
```
</td>
</tr>
<tr>
<td>
```json
{
"cds": {
"requires": {
"my-service": {
"kind": "my-kind"
}
}
}
}
```
</td>
<td>
```json
{
"user-provided": [{
"name": "my-upsi",
"tags": ["my-kind"]
}]
}
```
</td>
</tr>

<tr>
<td>

```json
{
"cds": {
"requires": {
"my-service": {
"vcap": { "name": "my-upsi" }
}
}
}
}
```
</td>
<td>

```json
{
"user-provided": [{
"name": "my-upsi",
"tags": []
}]
}
Comment on lines +621 to +626

@sjvans sjvans Oct 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
{
"user-provided": [{
"name": "my-upsi",
"tags": []
}]
}
{
"VCAP_SERVICES": {
"user-provided": [{
"name": "my-upsi"
}]
}
}

@mariayord mariayord Oct 30, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@sjvans If you want to point only one option, than it make sense to delete also the clarification:
Because all UPSIs share the same key, matching by kind label or type does not apply — only name and tag matching works. Use an explicit vcap config to override auto-matching

Here the point is that not all rules(1-7) listed above are valid for user-provided case.

@sjvans sjvans Oct 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

right, it's only rule 7: "The service's vcap.name is matched against the name property". i don't like the tag option because they are not unique → error prone. maybe we say we recommend matching by name above the example?

@sjvans sjvans Oct 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

but i'd defer to @renejeglinsky and @smahati :)

```
</td>
</tr>
<tr>
<td>

```json
{
"cds": {
"requires": {
"my-service": {
"vcap": { "tag": "my-tag" }
}
}
}
}
```
</td>
<td>

```json
{
"user-provided": [
{ "name": "other-upsi", "tags": ["other-tag"] },
{ "name": "my-upsi", "tags": ["my-tag"] }
]
}
```
</td>
</tr>
Comment on lines +630 to +656

@sjvans sjvans Oct 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<tr>
<td>
```json
{
"cds": {
"requires": {
"my-service": {
"vcap": { "tag": "my-tag" }
}
}
}
}
```
</td>
<td>
```json
{
"user-provided": [
{ "name": "other-upsi", "tags": ["other-tag"] },
{ "name": "my-upsi", "tags": ["my-tag"] }
]
}
```
</td>
</tr>

</tbody>
</table>

### In Kubernetes / Kyma { #in-kubernetes-kyma}

CAP supports [servicebinding.io](https://servicebinding.io/) service bindings and SAP BTP service bindings created by the [SAP BTP Service Operator](https://github.com/SAP/sap-btp-service-operator).
Expand Down
2 changes: 1 addition & 1 deletion node.js/cds-env.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -325,7 +325,7 @@ add them to the `cds.requires` section.

### In `cds.requires.<service>` Settings

Here, you can configure the services. Find details about the individual options in the documentation of [`cds.connect`](cds-connect#cds-env-requires).
Here, you can configure the services. Find details about the individual options in the documentation of [`cds.connect`](cds-connect), specifically [Configuring Required Services](cds-connect#configuring-required-services) for how the service behaves and [Service Bindings](cds-connect#service-bindings) for how credentials are resolved.

### Prototype-Chained Along `.kind` References

Expand Down
Loading