Skip to content

Add docu for TP loader #2290

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
wants to merge 2 commits into
base: main
Choose a base branch
from
+127 −20
Open

Add docu for TP loader #2290

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b7729d2
Add docu for TP loader
VladislavAtanasov95 Oct 24, 2025
767b7b1
Separate approaches
VladislavAtanasov95 Oct 31, 2025
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
61 changes: 57 additions & 4 deletions docs-java/environments/kyma.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -563,6 +563,7 @@ Other scenarios are currently not supported.

### Background Information

The Transparent Proxy handles the protocols HTTP(s), LDAP(s), MAIL (SMTP(s), IMAP(s), POP3(s)), and TCP.
When using the Transparent Proxy, your app performs requests against the Transparent Proxy without explicit authentication, relying on the secure network communication provided by Kyma via Istio.
The Transparent Proxy will obtain the relevant destination from the SAP Destination service and use it to forward the request via the Connectivity Proxy to the On-Premise system.
Consequently, your app itself does not interact with Destination or Connectivity services at all and thus your application pods do not require bindings to these two services.
Expand Down Expand Up @@ -659,7 +660,20 @@ Apply the YAML with `kubectl apply -n` into the namespace of your application po

### Executing Requests

In your application you can now configure a destination to execute requests:
The SAP Cloud SDK offers two distinct approaches for executing requests through the Transparent Proxy in Kyma. Choose the approach that best fits your application's architecture and requirements.

## Approach 1: TransparentProxyDestination Builder (Recommended)

The **TransparentProxyDestination Builder** approach provides explicit, fine-grained control over individual destination configurations. This is the recommended approach for most use cases as it offers maximum flexibility and clear configuration management.

### When to Use This Approach

- You need specific control over individual destination configurations
- You want to set custom headers or properties per destination
- You prefer explicit destination management
- You want to consume a destination with fragment or chain

### Implementation Examples

<Tabs
groupId="dynamic-dest"
Expand All @@ -670,6 +684,10 @@ In your application you can now configure a destination to execute requests:
]}>
<TabItem value="single">

**For Concrete SAP Destinations:**

Use this when connecting to a specific, pre-configured destination with a dedicated Destination Custom Resource.

```java
TransparentProxyDestination destination = TransparentProxyDestination
.destination(<destination-custom-resource-name>.<destination-custom-resource-namespace>)
Expand All @@ -684,6 +702,10 @@ List<SalesArea> execute = new DefaultSalesAreaService().getAllSalesArea() // exa
</TabItem>
<TabItem value="gateway">

**For Gateway:**

Use this when you need to connect to arbitrary destinations dynamically using a [Gateway Destination Custom Resource](https://help.sap.com/docs/connectivity/sap-btp-connectivity-cf/dynamic-lookup-of-destinations).

```java
TransparentProxyDestination destination = TransparentProxyDestination
.gateway("my-destination", <destination-custom-resource-name>.<destination-custom-resource-namespace>)
Expand All @@ -701,11 +723,42 @@ List<SalesArea> execute = new DefaultSalesAreaService().getAllSalesArea() // exa
`<destination-custom-resource-namespace>` can be omitted if the destination custom resource is created in the same namespace as the application workload.
:::

The code above shows an example how you can then use the `destination` object to perform an OData request against the system.
## Approach 2: Transparent Proxy Loader

The **Transparent Proxy Loader** approach provides centralized proxy configuration where **all destination requests** are automatically routed through a single registered gateway without requiring explicit destination builders.

### When to Use This Approach

- You want all destinations to automatically route through a single [Dynamic Destination Custom Resource](https://help.sap.com/docs/connectivity/sap-btp-connectivity-cf/dynamic-lookup-of-destinations)
- You prefer a centralized, "set-it-and-forget-it" configuration approach
- You have many destinations that should all use the same proxy configuration
- You want to minimize code changes when migrating from traditional destination access

### Implementation Examples

**Step 1: Register the Transparent Proxy (typically during application startup):**

```java
// Register with default port 80
TransparentProxy.register("<destination-gateway-host>");

// OR register with custom port
TransparentProxy.register("http://<destination-gateway-host>", 8080);
```

**Step 2: Use destinations normally - they will automatically route through the registered proxy:**

```java
// All subsequent destination requests will be routed through the registered gateway
// No explicit TransparentProxyDestination creation needed
Destination destination = DestinationAccessor.getDestination("my-destination");

List<SalesArea> execute = new DefaultSalesAreaService().getAllSalesArea() // example OData request
.execute(destination);
```

:::tip Connecting to Cloud systems
The above approach is not limited to destinations of proxy type `ON_PREMISE`.
`INTERNET` destinations are equally supported.
Both approaches support destinations of any proxy type including `ON_PREMISE` and `INTERNET` destinations.
:::

### Troubleshooting
Expand Down
86 changes: 70 additions & 16 deletions docs-java/features/connectivity/008-transparent-proxy.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,18 +46,22 @@ Refer to [Transparent Proxy in Kyma environment](https://help.sap.com/docs/conne

The **Transparent Proxy** is a SAP BTP Connectivity component that acts as an intermediary between your application and target systems.
The Transparent Proxy simplifies and unifies how your Kubernetes workloads connect to remote systems using SAP BTP destinations.
The Transparent Proxy handles the protocols HTTP(s), LDAP(s), MAIL (SMTP(s), IMAP(s), POP3(s)), and TCP.
It provides authentication, principal propagation, SOCKS5 handshake, and easy access to the destination target systems by exposing them as [Kubernetes Services](https://kubernetes.io/docs/concepts/services-networking/service).

The Transparent Proxy obtains relevant destination configuration from the SAP Destination service.
It uses this destination to forward the request to the target system or to the Connectivity Proxy for On-Premise destinations.
Consequently, your app does not interact with SAP Destination service or Connectivity service.
This means your application do not require bindings to these two services, everything is handled by the Transparent Proxy.

## Creating Transparent Proxy Destinations
## Approach 1: TransparentProxyDestination Builder

The `TransparentProxyDestination` class provides two types of builders for different use cases:
The `TransparentProxyDestination` class provides explicit destination builders for direct control over transparent proxy connections.
This approach gives you fine-grained control over individual destination configurations and is recommended for most use cases.

### 1. Destination
### Creating Destinations

#### Concrete SAP Destination

Allows you to connect to a concrete SAP destination.
Setting generic headers is allowed but dynamic properties like destination name or fragments is not.
Expand All @@ -76,7 +80,7 @@ TransparentProxyDestination destination = TransparentProxyDestination
`<destination-custom-resource-namespace>` can be omitted if the destination custom resource is created in the same namespace as the application workload.
:::

### 2. Gateway
#### Gateway

Allows you to connect to arbitrary SAP destinations you have access to.
As a prerequisite, you have to create a Gateway Destination Custom Resource inside the Kubernetes cluster.
Expand All @@ -89,25 +93,26 @@ TransparentProxyDestination destination = TransparentProxyDestination
.build();
```

## Tenant Configuration
### Configuration Options

#### Tenant Configuration

The SAP Cloud SDK automatically sets the current tenant as tenant ID on a **per-request** basis.

In case a fixed tenant should be used, you can manually set it as follows:

### Destination
**For Concrete Destinations:**

```java
// Using a fixed tenant ID (automatically set by SAP Cloud SDK if not specified)
// alternatively, .tenantSubdomain("..") can be used, but only one of the two options may be set

```java
TransparentProxyDestination destination = TransparentProxyDestination
.destination(<destination-custom-resource-name>.<destination-custom-resource-namespace>)
.tenantId("my-tenant-id")
.build();
```

### Gateway
**For Gateway Destinations:**

```java
// Using a fixed tenant ID (automatically set by SAP Cloud SDK if not specified)
Expand All @@ -118,13 +123,13 @@ TransparentProxyDestination destination = TransparentProxyDestination
.build();
```

## Authorization Header Configuration
#### Authorization Header Configuration

The SAP Cloud SDK automatically sets the current user's authorization token in the `Authorization` header on a **per-request** basis.

In case a fixed authorization token should be used, you can manually set it as follows:

### Destination
**For Concrete Destinations:**

```java
TransparentProxyDestination destination = TransparentProxyDestination
Expand All @@ -133,7 +138,7 @@ TransparentProxyDestination destination = TransparentProxyDestination
.build();
```

### Gateway
**For Gateway Destinations:**

```java
TransparentProxyDestination destination = TransparentProxyDestination
Expand All @@ -144,18 +149,18 @@ TransparentProxyDestination destination = TransparentProxyDestination

**Note**: When you manually set authorization, it will override the SAP Cloud SDK automatic token handling.

## Migration from Traditional Destinations
### Migration from Traditional Destinations

Migrating from traditional destination configurations:

### Before (Traditional Destination)
#### Before (Traditional Destination)

```java
Destination destination = DestinationAccessor.getDestination("my-destination");
HttpClient client = ApacheHttpClient5Accessor.getHttpClient(destination);
```

### After (Transparent Proxy - Gateway)
#### After (Transparent Proxy - Gateway)

```java
TransparentProxyDestination destination = TransparentProxyDestination
Expand All @@ -164,7 +169,7 @@ TransparentProxyDestination destination = TransparentProxyDestination
HttpClient client = ApacheHttpClient5Accessor.getHttpClient(destination);
```

### After (Transparent Proxy - Destination)
#### After (Transparent Proxy - Concrete Destination)

```java
TransparentProxyDestination destination = TransparentProxyDestination
Expand All @@ -173,6 +178,55 @@ TransparentProxyDestination destination = TransparentProxyDestination
HttpClient client = ApacheHttpClient5Accessor.getHttpClient(destination);
```

## Approach 2: Transparent Proxy Loader

The `TransparentProxy` class provides a `DestinationLoader` that enables routing **all destination traffic** through a single registered gateway host.
This approach provides centralized proxy configuration where all destination requests are automatically routed through the configured gateway without requiring explicit destination builders.

### When to Use This Approach

Use the Transparent Proxy Loader when:

- You want all destinations to automatically route through a single transparent proxy gateway
- You prefer a centralized configuration approach

### Registration Methods

#### Register with Default Port

Register a transparent proxy gateway using the default port 80:

```java
// Register with default port 80
// Note: <destination-gateway-host> - the host is a combination of the Gateway Destination Custom Resource name and namespace
TransparentProxy.register("<destination-gateway-host>");
```

The host will be verified if it is reachable and must not contain any path components.
If no scheme is provided, HTTP will be used by default.

#### Register with Custom Port

Register a transparent proxy gateway with a specified port:

```java
// Register with custom port when using a non-default port defined in the Destination CR's .service.port field
TransparentProxy.register("http://<destination-gateway-host>", <port>);
```

The final URI will be constructed as: `<normalized-host>:<port>`

### Usage Example

```java
// Register the transparent proxy during application initialization
TransparentProxy.register("<destination-gateway-host>", 8080);

// All subsequent destination requests will be routed through the registered gateway
// Note: returns TransparentProxyDestination which implements Destination
Destination destination = DestinationAccessor.getDestination("my-destination");
```

## Troubleshooting

### Common Issues
Expand Down