Skip to content

Commit aa87984

Browse files
isevdalinosapisevdalinosap
authored
Introducing Transparent Proxy Builder (#2220)
1 parent af779b1 commit aa87984

File tree

2 files changed

+193
-1
lines changed

2 files changed

+193
-1
lines changed

‎docs-java/features/connectivity/008-transparent-proxy.mdx‎

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
---
2+
id: transparent-proxy
3+
title: Transparent Proxy Destinations
4+
hide_title: false
5+
hide_table_of_contents: false
6+
sidebar_label: Transparent Proxy
7+
description: This article explains how to use Transparent Proxy Destinations to connect to systems through the SAP BTP Transparent Proxy.
8+
keywords:
9+
- sap
10+
- cloud
11+
- sdk
12+
- destination
13+
- transparent
14+
- proxy
15+
- java
16+
- connectivity
17+
- btp
18+
- kubernetes
19+
- kyma
20+
---
21+
22+
import Tabs from '@theme/Tabs';
23+
import TabItem from '@theme/TabItem';
24+
25+
The SAP Cloud SDK supports connecting to systems through the [**Transparent Proxy**](https://help.sap.com/docs/connectivity/sap-btp-connectivity-cf/transparent-proxy-for-kubernetes), which provides enhanced connectivity features and simplified on-premise access in Kubernetes-based environments like Kyma.
26+
The `TransparentProxyDestination` class enables applications to leverage these capabilities seamlessly.
27+
28+
## Prerequisites
29+
30+
:::info Kubernetes Only
31+
32+
The Transparent Proxy is currently **only available for Kubernetes-based environments** such as Kyma and Gardener.
33+
34+
:::
35+
36+
:::caution Installation Required
37+
38+
Before using `TransparentProxyDestination`, ensure that the **Transparent Proxy is installed and configured** in your Kubernetes cluster.
39+
Refer to the [official installation guide](https://help.sap.com/docs/connectivity/sap-btp-connectivity-cf/installation-47b8844e90be440881838a5d5d9f8a68) for setup instructions.
40+
41+
:::
42+
43+
## Background Information
44+
45+
The **Transparent Proxy** is a connectivity component provided by SAP BTP that acts as an intermediary between your application and target systems.
46+
When using the Transparent Proxy your app performs requests against the Transparent Proxy without explicit authentication.
47+
This relies on the secure network communication provided by Kyma via Istio.
48+
The Transparent Proxy will obtain the relevant destination from the destination service.
49+
It will then use this destination to forward the request to the target system or to the Connectivity Proxy for On-Premise destinations.
50+
Consequently, your app itself does not interact with destination or connectivity service at all.
51+
This means your application pods do not require bindings to these two services.
52+
53+
## Creating Transparent Proxy Destinations
54+
55+
The `TransparentProxyDestination` class provides two types of builders for different use cases:
56+
57+
### 1. Static Destinations
58+
59+
Static destinations connect directly to a specified URL.
60+
They allow setting generic headers but do not support dynamic properties like destination name or fragments.
61+
62+
```java
63+
TransparentProxyDestination destination = TransparentProxyDestination
64+
.staticDestination("https://my-service.com")
65+
.header("X-Custom-Header", "custom-value")
66+
.property("some-property-key", "some-value")
67+
.build();
68+
```
69+
70+
### 2. Dynamic Destinations
71+
72+
Dynamic destinations require both URL and destination name.
73+
They support dynamic properties like fragments.
74+
75+
```java
76+
TransparentProxyDestination destination = TransparentProxyDestination
77+
.dynamicDestination("my-destination", "https://proxy-gateway.com")
78+
.fragmentName("my-fragment")
79+
.build();
80+
```
81+
82+
## Tenant Configuration
83+
84+
The SAP Cloud SDK will automatically set the current tenant as tenant ID on a **per-request** basis.
85+
86+
In case a fixed tenant should be used, you can manually set it as follows:
87+
88+
```java
89+
// Using a fixed tenant ID (automatically set by SDK if not specified)
90+
// alternatively, .tenantSubdomain("..") can be used, but only one of the two options may be set
91+
TransparentProxyDestination destination = TransparentProxyDestination
92+
.dynamicDestination("my-destination", "https://proxy-gateway.com")
93+
.tenantId("my-tenant-id")
94+
.build();
95+
```
96+
97+
## Authorization Header Configuration
98+
99+
The SAP Cloud SDK will automatically set the current user's authorization token in the `Authorization` header on a **per-request** basis.
100+
101+
In case a fixed authorization token should be used, you can manually set it as follows:
102+
103+
```java
104+
// Dynamic destination with authorization method
105+
TransparentProxyDestination destination = TransparentProxyDestination
106+
.dynamicDestination("my-destination", "https://proxy-gateway.com")
107+
.authorization("Bearer my-fixed-token")
108+
.build();
109+
110+
// Static destination with authorization method
111+
TransparentProxyDestination destination = TransparentProxyDestination
112+
.staticDestination("https://my-service.com")
113+
.authorization("Bearer my-fixed-token")
114+
.build();
115+
```
116+
117+
**Note**: When you manually set authorization, it will override the SAP Cloud SDK automatic token handling.
118+
119+
## Migration from Traditional Destinations
120+
121+
When migrating from traditional destination configurations:
122+
123+
### Before (Traditional Destination)
124+
125+
```java
126+
Destination destination = DestinationAccessor.getDestination("my-destination");
127+
HttpClient client = ApacheHttpClient5Accessor.getHttpClient(destination);
128+
```
129+
130+
### After (Transparent Proxy - Dynamic)
131+
132+
```java
133+
TransparentProxyDestination destination = TransparentProxyDestination
134+
.dynamicDestination("my-destination", "https://proxy-gateway.com")
135+
.build();
136+
HttpClient client = ApacheHttpClient5Accessor.getHttpClient(destination);
137+
```
138+
139+
### After (Transparent Proxy - Static)
140+
141+
```java
142+
TransparentProxyDestination destination = TransparentProxyDestination
143+
.staticDestination("https://my-service.com")
144+
.build();
145+
HttpClient client = ApacheHttpClient5Accessor.getHttpClient(destination);
146+
```
147+
148+
## Troubleshooting
149+
150+
### Common Issues
151+
152+
1. **Missing destination name for dynamic destinations**: Ensure the destination name is provided as the first parameter to `.dynamicDestination("destination-name", "gateway-url")`
153+
2. **Tenant context not available**: Verify tenant information is properly set in the request context
154+
3. **Authentication failures**: Check that authentication headers and parameters are correctly configured
155+
4. **Network connectivity**: Verify that the Transparent Proxy is accessible from your environment
156+
157+
### Evaluating Transparent Proxy Headers
158+
159+
When using proxy servers it can be difficult to troubleshoot issues as it is often not obvious where exactly the error occurred.
160+
For example, with the Transparent Proxy errors might occur on the target system (e.g. OData service), the Destination Service or the Transparent Proxy itself.
161+
162+
To make troubleshooting easier the Transparent Proxy adds additional response headers to provide more information about where an error occurred.
163+
For the above example of executing OData requests you can access the response headers as follows:
164+
165+
```java
166+
try {
167+
// execute OData request
168+
} catch (ODataResponseException e) {
169+
System.out.println(e.getHttpCode());
170+
// the Transparent Proxy will attach additional response headers in case an error occurred
171+
System.out.println(e.getHttpHeaders());
172+
}
173+
```
174+
175+
#### List of headers added by the Transparent Proxy
176+
177+
- `X-Error-Origin` - the source of the error
178+
- `X-Proxy-Server` - the proxy server (Transparent Proxy)
179+
- `X-Error-Message` - thorough error message
180+
- `X-Error-Internal-Code` - set only when the source of the error is the XSUAA or Destination service. The value is the HTTP code returned from one of these services.
181+
- `X-Request-Id` is sent with the response in all requests, both successful and failed
182+
183+
## Related Documentation
184+
185+
- [HTTP Client](http-client) - For using destinations with HTTP clients
186+
- [Kubernetes Connectivity](/docs/java/environments/kubernetes-kyma#executing-requests)
187+
- [HTTP Destinations](http-destinations)
188+
- [On-Premise Connectivity](on-premise)
189+
- [SAP BTP Destination Service](btp-destination-service)
190+
191+
For more information about the Transparent Proxy itself, refer to the [official SAP documentation](https://help.sap.com/docs/connectivity/sap-btp-connectivity-cf/transparent-proxy-for-kubernetes).

‎sidebarsDocsJava.js‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,8 @@ module.exports = {
3737
'features/connectivity/http-destinations',
3838
'features/connectivity/http-client',
3939
'features/connectivity/running-locally',
40-
'features/connectivity/mtls'
40+
'features/connectivity/mtls',
41+
'features/connectivity/transparent-proxy'
4142
]
4243
},
4344
{

0 commit comments

Comments
 (0)