Skip to content

Commit 681415d

Browse files
andytaelandytael
authored
Initial deploy docs and fixes (#1106)
Signed-off-by: Andy Tael <[email protected]>
1 parent 6f97c55 commit 681415d

File tree

13 files changed

+366
-99
lines changed

13 files changed

+366
-99
lines changed

‎docs-source/site/docs/deploy/buildapp.md‎

Lines changed: 0 additions & 15 deletions
This file was deleted.

‎docs-source/site/docs/deploy/buildpushapp.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
---
2+
title: Build and Push the application
3+
sidebar_position: 3
4+
---
5+
## Build and Push the application
6+
7+
:::important
8+
This content is TBD
9+
:::
10+
11+
This section explains how to build and push the container image for deployment on OBaaS. The following are required:
12+
13+
- Access to a container image repository (e.g., OCIR or another approved registry)
14+
- Docker running locally (and authenticated to your registry)
15+
16+
## Add JKube to the `pom.xml`
17+
18+
The image will be built using JKube and Maven. Add the following plugin into the `pom.xml` for the application.
19+
20+
The following needs to be updated to reflect your environment:
21+
22+
- Image configuration, a mandatory, unique docker repository name. This can include registry and tag parts, but also placeholder parameters. example below has the following value `region/tenancy/repository/phonebook:${project.version}`
23+
- The base image which should be used for this image. In this example `ghcr.io/oracle/openjdk-image-obaas:21` is used.
24+
- assembly, mode how the assembled files should be collected. In this example files are simple copied, `dir`
25+
- cmd, A command to execute by default. in the example below `java -jar /deployments/${project.artifactId}-${project.version}.jar` will be executed.
26+
27+
Refer to the [documentation for JKube](https://eclipse.dev/jkube/docs/kubernetes-maven-plugin/) for more configuration options.
28+
29+
```xml
30+
<plugin>
31+
<groupId>org.eclipse.jkube</groupId>
32+
<artifactId>kubernetes-maven-plugin</artifactId>
33+
<version>1.18.1</version>
34+
<configuration>
35+
<images>
36+
<image>
37+
<name>sjc.ocir.io/maacloud/repository/phonebook:${project.version}</name>
38+
<build>
39+
<from>ghcr.io/oracle/openjdk-image-obaas:21</from>
40+
<assembly>
41+
<mode>dir</mode>
42+
<targetDir>/deployments</targetDir>
43+
</assembly>
44+
<cmd>java -jar /deployments/${project.artifactId}-${project.version}.jar</cmd>
45+
</build>
46+
</image>
47+
</images>
48+
</configuration>
49+
</plugin>
50+
```
51+
52+
## Build and push the application
53+
54+
To build and push the application execute the following command:
55+
56+
```shell
57+
mvn clean package k8s:build k8s:push
58+
```
59+
60+
If the build and push is successful then you shuould get a message similar to this:
61+
62+
```log
63+
[INFO] k8s: Pushed sjc.ocir.io/maacloud/phonebook/phonebook:0.0.1-SNAPSHOT in 4 minutes and 2 seconds
64+
[INFO] ------------------------------------------------------------------------
65+
[INFO] BUILD SUCCESS
66+
[INFO] ------------------------------------------------------------------------
67+
[INFO] Total time: 04:07 min
68+
[INFO] Finished at: 2025-09-24T12:18:53-05:00
69+
[INFO] ------------------------------------------------------------------------
70+
```

‎docs-source/site/docs/deploy/dbaccess.md‎

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
---
2+
title: Application Database Access
3+
sidebar_position: 2
4+
---
5+
## Application Database Access
6+
7+
:::note
8+
This step is only necessary if your application is connecting to a database.
9+
:::
10+
11+
If your application needs database access, first obtain the database user credentials. Then create a Kubernetes secret containing those credentials. The secret is referenced in your application deployment.
12+
13+
### Create the secret for the application
14+
15+
Create a secret with database access information. This secret is used by the application configuration and is injected during deployment.
16+
17+
For example if you have the following information:
18+
19+
- name: `Your database name`. For example `helmdb`
20+
- username: `Your database user name`. For example `phonebook`
21+
- password: `Your database user password`. For example `Welcome-12345`
22+
- service: `Your servicename`. For example `helmdb_tp`
23+
24+
Create a Kubernetes secret (in this example, `phonebook-db-secrets` in the `obaas-dev` namespace):
25+
26+
```bash
27+
kubectl -n obaas-dev create secret generic phonebook-db-secrets \
28+
--from-literal=name=helmdb \
29+
--from-literal=username=phonebook \
30+
--from-literal=password=Welcome-12345 \
31+
--from-literal=service=helmdb_tp
32+
```
33+
34+
You can verify the values by running the following command (this is for the `username` value):
35+
36+
```bash
37+
kubectl -n obaas-dev get secret phonebook-sb-secrets -o jsonpath='{.data.username}' | base64 -d
38+
```
39+
40+
### Create database user using `sqljob.yaml` k8s job
41+
42+
Use this job to run SQL statements against the database with the credentials stored in the secret above.
43+
44+
Set the namespace to where the `obaas-db-secret` secret resides (example uses `obaas-dev`):
45+
46+
```yaml
47+
metadata:
48+
generateName: sqlcl-runner-job-
49+
namespace: obaas-dev
50+
```
51+
52+
Update the `args:` section with your SQL:
53+
54+
```yaml
55+
args:
56+
- |
57+
export TNS_ADMIN=/etc/oracle/wallet
58+
59+
# Create the SQL script inline
60+
cat > /tmp/run.sql << 'EOF'
61+
SET SERVEROUTPUT ON;
62+
WHENEVER SQLERROR EXIT SQL.SQLCODE;
63+
64+
<<SQL STATEMENTS>>
65+
66+
EXIT;
67+
EOF
68+
69+
# Execute the SQL script
70+
sql $(DB_USER)/$(DB_PASSWORD)@$(TNS_ALIAS) @/tmp/run.sql
71+
```
72+
73+
Update the `env:` section to reference the correct secret and keys (here using `obaas-db-secrets`):
74+
75+
```yaml
76+
env:
77+
- name: DB_USER
78+
valueFrom:
79+
secretKeyRef:
80+
name: obaas-db-secret
81+
key: db.username
82+
- name: DB_PASSWORD
83+
valueFrom:
84+
secretKeyRef:
85+
name: obaas-db-secret
86+
key: db.password
87+
- name: TNS_ALIAS
88+
valueFrom:
89+
secretKeyRef:
90+
name: obaas-db-secret
91+
key: db.service
92+
```
93+
94+
Set the TNS Admin wallet secret name to match your OBaaS installation:
95+
96+
```yaml
97+
volumes:
98+
- name: db-wallet-volume
99+
secret:
100+
secretName: obaas-adb-tns-admin-1
101+
```
102+
103+
Execute `kubectl create -f sqljob.yaml` to create the kubernetes job.
104+
105+
```log
106+
job.batch/sqlcl-runner-job-2vcrq created
107+
```
108+
109+
You can verify that the Job ran successfully by checking its logs.
110+
111+
#### Example `sqljob.yaml`
112+
113+
This is an example of a kubernetes job that creates a `phonebook` user and assigns roles to the user.
114+
115+
```yaml
116+
# The Job to run the SQLcl container with embedded SQL
117+
apiVersion: batch/v1
118+
kind: Job
119+
metadata:
120+
generateName: sqlcl-runner-job-
121+
namespace: obaas-dev
122+
spec:
123+
backoffLimit: 2
124+
template:
125+
spec:
126+
restartPolicy: Never
127+
containers:
128+
- name: sqlcl-container
129+
image: container-registry.oracle.com/database/sqlcl:latest
130+
command: ["/bin/sh", "-c"]
131+
args:
132+
- |
133+
export TNS_ADMIN=/etc/oracle/wallet
134+
135+
# Create the SQL script inline
136+
cat > /tmp/run.sql << 'EOF'
137+
SET SERVEROUTPUT ON;
138+
WHENEVER SQLERROR EXIT SQL.SQLCODE;
139+
140+
create user if not exists phonebook identified by "Welcome-12345";
141+
grant db_developer_role to phonebook;
142+
grant unlimited tablespace to phonebook;
143+
commit;
144+
145+
/
146+
EXIT;
147+
EOF
148+
149+
# Execute the SQL script
150+
sql $(DB_USER)/$(DB_PASSWORD)@$(TNS_ALIAS) @/tmp/run.sql
151+
env:
152+
- name: DB_USER
153+
valueFrom:
154+
secretKeyRef:
155+
name: obaas-db-secret
156+
key: db.username
157+
- name: DB_PASSWORD
158+
valueFrom:
159+
secretKeyRef:
160+
name: obaas-db-secret
161+
key: db.password
162+
- name: TNS_ALIAS
163+
valueFrom:
164+
secretKeyRef:
165+
name: obaas-db-secret
166+
key: db.service
167+
volumeMounts:
168+
- name: db-wallet-volume
169+
mountPath: /etc/oracle/wallet
170+
readOnly: true
171+
volumes:
172+
- name: db-wallet-volume
173+
secret:
174+
secretName: obaas-adb-tns-admin-1
175+
```

‎docs-source/site/docs/deploy/deployapp.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,3 +7,64 @@ sidebar_position: 4
77
:::important
88
This content is TBD
99
:::
10+
11+
## Modify the `Chart.yaml`
12+
13+
Modify the `Chart.yaml` file to reflect your application.
14+
15+
```yaml
16+
apiVersion: v2
17+
name: <your application name> # Replace with your application name
18+
```
19+
20+
## Modify the `values.yaml`
21+
22+
Modify the `values.yaml` file to match your application’s requirements—for example, set image.repository and pullPolicy, configure a service account, enable ingress, define resources and autoscaling, and specify volumes and volumeMounts etc.
23+
24+
The `obaas` section is unique for Oracle Backed for Microservices and AI. It has the following settings:
25+
26+
```yaml
27+
obaas:
28+
29+
# Framework selection: SPRING_BOOT or HELIDON
30+
framework: SPRING_BOOT
31+
32+
namespace: obaas-dev
33+
database:
34+
credentialsSecret: phonebook-db-secrets
35+
walletSecret: obaas-adb-tns-admin-1
36+
37+
# Opentelemetry monitoring
38+
otel:
39+
enabled: true
40+
41+
# MicroProfile LRA
42+
mp_lra:
43+
enabled: false
44+
45+
# Spring Boot applications
46+
springboot:
47+
enabled: true
48+
49+
# Eureka discovery
50+
eureka:
51+
enabled: true
52+
```
53+
54+
- OBaaS supports both `SPRING_BOOT` or `HELIDON`. This is set via the `obaas.framework` parameter.
55+
- When `otel.enabled` is true, the `OTEL_EXPORTER_OTLP_ENDPOINT` environment variable is set to the appropriate value and injected into the deployment for application use. This is the URL of the OpenTelemetry (OTLP protocol) collector which can be used by your application to send observability data to the the SigNoz platform.
56+
- When `mp_lra.enabled` is true, the following environment variables are set to the appropriate value and injected into the deployment for application usee:
57+
- `MP_LRA_COORDINATOR_URL` This is the URL for the *transaction manager* which is required when using Eclipse Microprofile Long Running Actions in your application.
58+
- `MP_LRA_PARTICIPANT_URL` This is the *participant* URL which is required when using Eclipse Microprofile Long Running Actions in your application.
59+
- When `springboot.enabled` is true, the following environment variables are set to the appropriate value and injected into the deployment for application use:
60+
- `SPRING_PROFILES_ACTIVE` This sets the Spring profiles that will be active in the application. The default value is `default`.
61+
- `SPRING_DATASOURCE_URL` This sets the data source URL for your application to use to connect to the database, for example `jdbc:oracle:thin:@$(DB_SERVICE)?TNS_ADMIN=/oracle/tnsadmin`.
62+
- `SPRING_DATASOURCE_USERNAME` Set to the value of the key `username` in secret you may have created for your application.
63+
- `SPRING_DATASOURCE_PASSWORD` Set to the value of the key `password` in secret you may have created for your application.
64+
- `DB_SERVICE` Set to the value of the key `service` in secret you may have created for your application.
65+
- When `eureka.enabled` is true, the following environment variables are set to the appropriate value and injected into the deployment for the application and the application will register with Eureka.
66+
- `EUREKA_INSTANCE_PREFER_IP_ADDRESS`
67+
- `EUREKA_CLIENT_REGISTER_WITH_EUREKA`
68+
- `EUREKA_CLIENT_FETCH_REGISTRY`
69+
- `EUREKA_CLIENT_SERVICE_URL_DEFAULTZONE`
70+
- `EUREKA_INSTANCE_HOSTNAME`

‎docs-source/site/docs/deploy/introflow.md‎

Lines changed: 10 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -8,24 +8,25 @@ sidebar_position: 1
88
This content is TBD
99
:::
1010

11-
This guide explains how to deploy an application to OBaaS using Eclipse [Eclipse JKube](https://eclipse.dev/jkube/) to build and push a container image, and Helm to install and configure the application on a Kubernetes cluster.
11+
This guide explains how to deploy an application to OBaaS using Eclipse [Eclipse JKube](https://eclipse.dev/jkube/) to build and push a container image, and using Helm to install and configure the application on a Kubernetes cluster.
1212

1313
### Prerequisites
1414

1515
- Access to a container image repository (e.g., OCIR or another approved registry).
16+
- Docker running locally (and authenticated to your registry)
1617
- Kubernetes cluster access with the correct context set.
1718
- Helm installed locally.
1819
- Maven build configured for your project.
1920

2021
### High Level Installation Flow
2122

22-
Too deploy an application to OBaaS, you will follow this high-level flow:
23+
To deploy an application to OBaaS, follow this high-level workflow:
2324

24-
- Obtain Image Repository metadata or Create the repository needed for the deployment.
25-
- Add [Eclipse JKube](https://eclipse.dev/jkube/) to the pom.xml file.
26-
- Build the Application using Maven.
27-
- Obtain the deployment Helm chart.
28-
- If you're using a database, create a secret with database credentials etc.
29-
- Create the database application user using the 'sqljob.yaml' file. **Add to Helm dir with 'if' statement**
30-
- Edit the `Chart.yaml` file to reflect the application name.
25+
- Obtain image repository metadata or create the required repository.
26+
- Configure database access and run the SQL job, if needed.
27+
- Add Eclipse JKube to the pom.xml.
28+
- Build and push the application with Maven.
29+
- Retrieve the deployment Helm chart.
30+
- Update Chart.yaml with the application name.
31+
- Update values.yaml to match your configuration.
3132
- Install the Helm chart.

‎docs-source/site/docs/deploy/sqljob.md‎

Lines changed: 0 additions & 23 deletions
This file was deleted.

0 commit comments

Comments
 (0)