Skip to content

Commit ed0c89e

Browse files
fmeheustfmeheust
authored
Merge branch 'main' into observability-provider
2 parents 1157aa3 + f10284a commit ed0c89e

29 files changed

+3500
-458
lines changed

‎.github/workflows/run-tests.yaml

+11
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,9 @@ jobs:
1010
AZURE_USERNAME: ${{ secrets.TEST_AZURE_USERNAME }}
1111
AZURE_PASSWORD: ${{ secrets.TEST_AZURE_PASSWORD }}
1212
AZURE_CLIENT_CERTIFICATE_PATH: ${{ secrets.TEST_AZURE_CLIENT_CERTIFICATE_PATH }}
13+
AWS_REGION: ${{ secrets.TEST_AWS_REGION }}
14+
AWS_ACCESS_KEY_ID: ${{ secrets.TEST_AWS_ACCESS_KEY_ID }}
15+
AWS_SECRET_ACCESS_KEY: ${{ secrets.TEST_AWS_SECRET_ACCESS_KEY }}
1316
steps:
1417
- name: Checkout the repository
1518
uses: actions/checkout@v4
@@ -125,6 +128,11 @@ jobs:
125128
OBSERVABILITY_PASSWORD=${{ secrets.TEST_JACKSON_OSON_PASSWORD }}\n
126129
" >> ojdbc-provider-observability/test.properties
127130
131+
# Generate ojdbc-provider-aws/test.properties
132+
echo -e "AWS_S3_URL=${{ secrets.TEST_AWS_S3_URL }}\n
133+
AWS_SECRETS_MANAGER_URL=${{ secrets.TEST_AWS_SECRETS_MANAGER_URL }}\n
134+
" >> ojdbc-provider-aws/test.properties
135+
128136
- name: Run tests with Maven
129137
run: mvn -B test --file pom.xml
130138

@@ -139,4 +147,7 @@ jobs:
139147
rm ojdbc-provider-azure/test.properties
140148
141149
rm ojdbc-provider-jackson-oson/test.properties
150+
142151
rm ojdbc-provider-observability/test.properties
152+
153+
rm ojdbc-provider-aws/test.properties

‎ojdbc-provider-aws/README.md

+188
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
# Oracle JDBC Providers for AWS
2+
3+
This module contains providers for integration between Oracle JDBC and
4+
Amazon Web Services (AWS).
5+
6+
## Centralized Config Providers
7+
8+
<dl>
9+
<dt><a href="#aws-s3-configuration-provider">AWS S3 Configuration
10+
Provider</a></dt>
11+
<dd>Provides connection properties managed by the S3 service</dd>
12+
<dt><a href="#aws-secrets-manager-config-provider">AWS Secrets Manager Configuration
13+
Provider</a></dt>
14+
<dd>Provides connection properties managed by the Secrets Manager service</dd>
15+
<dt><a href="#common-parameters-for-centralized-config-providers">Common Parameters for Centralized Config Providers</a></dt>
16+
<dd>Common parameters supported by the config providers</dd>
17+
<dt><a href="#caching-configuration">Caching configuration</a></dt>
18+
<dd>Caching mechanism adopted by Centralized Config Providers</dd>
19+
</dl>
20+
21+
Visit any of the links above to find information and usage examples for a
22+
particular provider.
23+
24+
## Installation
25+
26+
All providers in this module are distributed as single jar on the Maven Central
27+
Repository. The jar is compiled for JDK 8, and is forward compatible with later
28+
JDK versions. The coordinates for the latest release are:
29+
```xml
30+
<dependency>
31+
<groupId>com.oracle.database.jdbc</groupId>
32+
<artifactId>ojdbc-provider-aws</artifactId>
33+
<version>1.0.2</version>
34+
</dependency>
35+
```
36+
37+
## AWS S3 Configuration Provider
38+
The Oracle DataSource uses a new prefix `jdbc:oracle:thin:@config-awss3:` to be able to identify that the configuration parameters should be loaded using AWS S3.
39+
Users only need to indicate the S3 URI of the object that contains the JSON payload.
40+
41+
A URL with either of the following formats is valid:
42+
<pre>
43+
jdbc:oracle:thin:@config-awss3://{S3-URI}
44+
</pre>
45+
or
46+
<pre>
47+
jdbc:oracle:thin:@config-aws{S3-URI}
48+
</pre>
49+
50+
The {S3-URI} can be obtained from the Amazon S3 console and follows this naming convention: s3://bucket-name/file-name.
51+
52+
### JSON Payload format
53+
54+
There are 3 fixed values that are looked at the root level.
55+
56+
- connect_descriptor (required)
57+
- user (optional)
58+
- password (optional)
59+
60+
The rest are dependent on the driver, in our case `/jdbc`. The key-value pairs that are with sub-prefix `/jdbc` will be applied to a DataSource. The key values are constant keys which are equivalent to the properties defined in the [OracleConnection](https://docs.oracle.com/en/database/oracle/oracle-database/23/jajdb/oracle/jdbc/OracleConnection.html) interface.
61+
62+
For example, let's suppose an url like:
63+
64+
<pre>
65+
jdbc:oracle:thin:@config-awss3://s3://mybucket/payload_ojdbc_objectstorage.json
66+
</pre>
67+
68+
And the JSON Payload for the file **payload_ojdbc_objectstorage.json** in **mybucket** as following:
69+
70+
```json
71+
{
72+
"connect_descriptor": "(description=(retry_count=20)(retry_delay=3)(address=(protocol=tcps)(port=1521)(host=adb.us-phoenix-1.oraclecloud.com))(connect_data=(service_name=xsxsxs_dbtest_medium.adb.oraclecloud.com))(security=(ssl_server_dn_match=yes)))",
73+
"user": "scott",
74+
"password": {
75+
"type": "awssecretsmanager",
76+
"value": "test-secret"
77+
},
78+
"jdbc": {
79+
"oracle.jdbc.ReadTimeout": 1000,
80+
"defaultRowPrefetch": 20,
81+
"autoCommit": "false"
82+
}
83+
}
84+
```
85+
86+
The sample code below executes as expected with the previous configuration.
87+
88+
```java
89+
OracleDataSource ds = new OracleDataSource();
90+
ds.setURL("jdbc:oracle:thin:@config-awss3://s3://mybucket/payload_ojdbc_objectstorage.json");
91+
Connection cn = ds.getConnection();
92+
Statement st = cn.createStatement();
93+
ResultSet rs = st.executeQuery("select sysdate from dual");
94+
if (rs.next())
95+
System.out.println("select sysdate from dual: " + rs.getString(1));
96+
```
97+
98+
### Password JSON Object
99+
100+
For the JSON type of provider (AWS S3, AWS Secrets Manager, HTTP/HTTPS, File) the password is an object itself with the following spec:
101+
102+
- type
103+
- Mandatory
104+
- Possible values
105+
- ocivault
106+
- azurevault
107+
- base64
108+
- awssecretsmanager
109+
- value
110+
- Mandatory
111+
- Possible values
112+
- OCID of the secret (if ocivault)
113+
- Azure Key Vault URI (if azurevault)
114+
- Base64 Encoded password (if base64)
115+
- AWS Secret name (if awssecretsmanager)
116+
- authentication
117+
- Optional
118+
- Possible Values
119+
- method
120+
- optional parameters (depends on the cloud provider).
121+
122+
## AWS Secrets Manager Config Provider
123+
Apart from AWS S3, users can also store JSON Payload in the content of AWS Secrets Manager secret. Users need to indicate the secret name:
124+
125+
<pre>
126+
jdbc:oracle:thin:@config-awssecretsmanager://{secret-name}
127+
</pre>
128+
129+
The JSON Payload retrieved by AWS Secrets Manager Provider follows the same format in [AWS S3 Configuration Provider](#json-payload-format).
130+
131+
## Common Parameters for Centralized Config Providers
132+
AWS S3 Configuration Provider and AWS Secrets Manager Configuration Provider
133+
share the same sets of parameters for authentication configuration.
134+
135+
### Configuring Authentication
136+
137+
The Centralized Config Providers in this module use the
138+
[Default credentials provider chain](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/credentials-chain.html) to provide authorization and authentication to S3 and Secrets Manager services.
139+
The user can provide an optional parameter `AUTHENTICATION` (case-ignored) which is mapped with the following Credential Class.
140+
141+
<table>
142+
<thead><tr>
143+
<th>'AUTHENTICATION' Param Value</th>
144+
<th>Method</th>
145+
<th>Optional Configuration</th>
146+
<th>Optional Parameters</th>
147+
</tr></thead>
148+
<tbody>
149+
<tr>
150+
<td><b>AWS_DEFAULT</b> or &lt;Empty&gt;</td>
151+
<td>Default Credentials Provider Chain</td>
152+
<td>see below Default Credentials Provider Chain</td>
153+
<td>AWS_REGION (see AWS Region below)</td>
154+
</tr>
155+
</tbody>
156+
</table>
157+
158+
### Default Credentials Provider Chain
159+
160+
The default credentials provider chain provided by AWS SDK is implemented by the
161+
[DefaultCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/DefaultCredentialsProvider.html) class,
162+
which searches for credentials in one of the following locations using a predefined sequence:
163+
164+
1. Java system properties
165+
2. Environment variables
166+
3. Web identity token from AWS Security Token Service
167+
4. The shared credentials and config files
168+
5. Amazon ECS container credentials
169+
6. Amazon EC2 instance IAM role-provided credentials
170+
171+
For more details, please refer to [Default credentials provider chain](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/credentials-chain.html).
172+
173+
### AWS Region
174+
175+
In this project, region can be specified from two places:
176+
1. `AWS_REGION` as an optional parameter in URL
177+
2. [Default region provider chain](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/region-selection.html#automatically-determine-the-aws-region-from-the-environment).
178+
179+
If `AWS_REGION` is specified in the URL, the provider uses it as the value of Region for authentication. Otherwise, the value from default region provider chain will be applied.
180+
181+
## Caching configuration
182+
183+
Config providers in this module store the configuration in caches to minimize
184+
the number of RPC requests to remote location. See
185+
[Caching configuration](../ojdbc-provider-azure/README.md#caching-configuration) for more
186+
details of the caching mechanism.
187+
188+

0 commit comments

Comments
 (0)