diff --git a/docs-source/site/docs/deploy/dbaccess.md b/docs-source/site/docs/deploy/dbaccess.md index 94c2a7490..5f112af79 100644 --- a/docs-source/site/docs/deploy/dbaccess.md +++ b/docs-source/site/docs/deploy/dbaccess.md @@ -16,19 +16,23 @@ Create a secret with database access information. This secret is used by the app For example if you have the following information: -- name: `Your database name`. For example `helmdb` -- username: `Your database user name`. For example `phonebook` -- password: `Your database user password`. For example `Welcome-12345` -- service: `Your servicename`. For example `helmdb_tp` +- `db.name:` Your database name. For example `helmdb` +- `db.username:` Your database user name. For example `phonebook` +- `db.password:` Your database user password. For example `Welcome-12345` +- `db.service:` Your servicename. For example `helmdb_tp` +- `db.lb_username` Your Liquibase username. +- `db.lb_password` Your Liquibase user password. Create a Kubernetes secret (in this example, `phonebook-db-secrets` in the `obaas-dev` namespace): ```bash kubectl -n obaas-dev create secret generic phonebook-db-secrets \ - --from-literal=name=helmdb \ - --from-literal=username=phonebook \ - --from-literal=password=Welcome-12345 \ - --from-literal=service=helmdb_tp + --from-literal=db.name=helmdb \ + --from-literal=db.username=phonebook \ + --from-literal=db.password=Welcome-12345 \ + --from-literal=db.service=helmdb_tp \ + --from-literal=db.lb_username=phonebook \ + --from-literal=db.lb_password=Welcome-12345 ``` You can verify the values by running the following command (this is for the `username` value): @@ -70,7 +74,7 @@ args: sql $(DB_USER)/$(DB_PASSWORD)@$(TNS_ALIAS) @/tmp/run.sql ``` -Update the `env:` section to reference the correct secret and keys (here using `obaas-db-secrets`): +Update the `env:` section to reference the correct secret and keys (here using `obaas-db-secrets`, this is not the same secret as been created above.): ```yaml env: diff --git a/docs-source/site/docs/observability/acces.md b/docs-source/site/docs/observability/acces.md index 5ad21016e..ad6e90802 100644 --- a/docs-source/site/docs/observability/acces.md +++ b/docs-source/site/docs/observability/acces.md @@ -4,14 +4,14 @@ sidebar_position: 2 --- ## How to access SigNoz -1. Get the _admin_ email and password for SigNoz +1. Get the _admin_ email and password for SigNoz. Replace the example namespace `observability` with the namespace where SigNoz is deployed. ```shell kubectl -n observability get secret signoz-authn -o jsonpath='{.data.email}' | base64 -d kubectl -n observability get secret signoz-authn -o jsonpath='{.data.password}' | base64 -d ``` -1. Expose the SigNoz user interface (UI) using this command: +1. Expose the SigNoz user interface (UI) using this command. Replace the example namespace `observability` with the namespace where SigNoz is deployed: ```shell kubectl -n observability port-forward svc/obaas-signoz-frontend 3301:3301 diff --git a/docs-source/site/docs/platform/adminserver.md b/docs-source/site/docs/platform/adminserver.md new file mode 100644 index 000000000..c2ddf5dd6 --- /dev/null +++ b/docs-source/site/docs/platform/adminserver.md @@ -0,0 +1,25 @@ +--- +title: Spring Boot Admin +sidebar_position: 9 +--- +## Spring Boot Admin + +Spring Boot Admin works by registering Spring Boot applications that expose Actuator endpoints. Each application's health and metrics data is polled by Spring Boot Admin Server, which aggregates and displays this information in a web dashboard. The registered applications can either self-register or be discovered using service discovery tools like Eureka or Consul. Through the dashboard, users can monitor the health, memory usage, logs, and more for each application, and even interact with them via management endpoints for tasks like restarting or updating configurations. + +[Spring Boot Admin Documentation](https://docs.spring-boot-admin.com/3.5.5/docs/installation-and-setup/) + +### Installing Spring Boot Admin + +Spring Boot Admin will be installed if the `admin-server.enabled` is set to `true` in the `values.yaml` file. The default namespace for Spring Boot Admin is `admin-server`. + +### Access Spring Boot Admin Web Interface + +To access the Spring Boot Admin Web Interface, use kubectl port-forward to create a secure channel to `service/admin-server`. Run the following command to establish the secure tunnel (replace the example namespace `obaas-dev` with the namespace where the Spring Boot Admin Server is deployed): + +```shell +kubectl port-forward -n obaas-dev svc/admin-server 8989 +``` + +Open the [Spring Boot Admin dashboard](http://localhost:8989) + +![Spring Boot Admin Server](images/admin-server.png) diff --git a/docs-source/site/docs/platform/apisix.md b/docs-source/site/docs/platform/apisix.md new file mode 100644 index 000000000..3c9446f1b --- /dev/null +++ b/docs-source/site/docs/platform/apisix.md @@ -0,0 +1,35 @@ +--- +title: Apache APISIX +sidebar_position: 1 +--- +## Apache APISIX + +[Apache APISIX](https://apisix.apache.org) is an open source cloud native API platform that supports the full lifecycle of API management including publishing, traffic management, deployment strategies, and circuit breakers. + +### Installing APISIX + +Apache APISIX will be installed if the `apisix.enabled` is set to `true` in the `values.yaml` file. The default namespace for Apache APISIX is `apisix`. + +### Accessing Apache APISIX + +Oracle Backend for Microservices and AI deploys the Apache APISIX Gateway and Dashboard in the `apisix` namespace by default. The gateway is exposed via an external load balancer and an ingress controller. + +To access the Apache APISIX APIs, use kubectl port-forward to create a secure channel to `service/apisix-admin`. Run the following command to establish the secure tunnel (replace the example namespace `obaas-dev` with the namespace where APISIX is deployed): + +```shell +kubectl port-forward -n obaas-dev svc/apisix-admin 9180 +``` + +### Retrieving admin key + +To access the APISIX APIs, you need the admin key. Retrieve it with the following command (replace the example namespace `obaas-dev` with the namespace where APISIX is deployed): + +```shell +export admin_key=$(kubectl -n obaas-dev get configmap apisix -o yaml | yq '.data."config.yaml"' | yq '.deployment.admin.admin_key[] | select(.name == "admin") | .key') +``` + +Test the admin key by running a simple curl command; it should return the list of configured routes. + +```shell +curl http://127.0.0.1:9180/apisix/admin/routes -H "X-API-key: $admin_key" -X GET +``` diff --git a/docs-source/site/docs/platform/conductor.md b/docs-source/site/docs/platform/conductor.md new file mode 100644 index 000000000..092070ade --- /dev/null +++ b/docs-source/site/docs/platform/conductor.md @@ -0,0 +1,93 @@ +--- +title: Conductor Workflow Orchestration +sidebar_position: 2 +--- +## Conductor + +:::important +Conductor will be replaced with Oracle Transaction Manager for Microservices, which will include the Conductor Server as a component of the product +::: + +Conductor is a workflow orchestration platform, originally developed at Netflix, designed to coordinate long-running, distributed workflows across microservices by defining tasks, dependencies, and retries, while providing scalability, fault tolerance, and operational visibility through a centralized engine. + +[Conductor OSS Documentation](https://docs.conductor-oss.org) + +### Installing Conductor + +Conductor will be installed if the `conductor-server.enabled` is set to `true` in the `values.yaml` file. The default namespace for Conductor is `conductor-server`. + +### API Specification + +[API Specification](https://docs.conductor-oss.org/documentation/api/index.html) + +### Accessing Conductor APIs + +To access the Conductor APIs, use kubectl port-forward to create a secure channel to `service/conductor-server`. Run the following command to establish the secure tunnel (replace the example namespace `obaas-dev` with the namespace where the Conductor Server is deployed): + +```shell +kubectl port-forward -n obaas-dev svc/conductor-server 8080 +``` + +### Testing the Conductor service + +You can test the Conductor service by running the sample workflow provided. Save the content into a file called `first_simple_workflow.json` and then execute the following command: + +```shell +curl -X POST 'http://localhost:8080/api/metadata/workflow' \ +-H 'Content-Type: application/json' \ +-d @first_sample_workflow.json +``` + +```json + + { + "name": "first_sample_workflow", + "description": "First Sample Workflow", + "version": 1, + "tasks": [ + { + "name": "get_population_data", + "taskReferenceName": "get_population_data", + "inputParameters": { + "http_request": { + "uri": "https://restcountries.com/v3.1/name/united%20states?fields=name,population", + "method": "GET" + } + }, + "type": "HTTP" + } + ], + "inputParameters": [], + "outputParameters": { + "data": "${get_population_data.output.response.body.data}", + "source": "${get_population_data.output.response.body.source}" + }, + "schemaVersion": 2, + "restartable": true, + "workflowStatusListenerEnabled": false, + "ownerEmail": "example@email.com", + "timeoutPolicy": "ALERT_ONLY", + "timeoutSeconds": 0 + } + +``` + +Execute the workflow by using this command and capture the Workflow ID: + +```shell +WORKFLOW_ID=$(curl -s -X POST 'http://localhost:8080/api/workflow/first_sample_workflow' \ +-H 'Content-Type: application/json' \ +-d '{}' | tr -d '"') +``` + +Check the Workflow IS, should return a string similar to this `46cbbaef-7133-451b-9334-2ccfc4e270c5` + +```shell +echo "Workflow ID: $WORKFLOW_ID" +``` + +Check status of the Workflow, will return the data from https://restcountries.com/v3.1/name/united%20states?fields=name,population. + +```shell +curl -s -X GET "http://localhost:8080/api/workflow/$WORKFLOW_ID" | jq +``` diff --git a/docs-source/site/docs/platform/dbexporter.md b/docs-source/site/docs/platform/dbexporter.md new file mode 100644 index 000000000..842e364f4 --- /dev/null +++ b/docs-source/site/docs/platform/dbexporter.md @@ -0,0 +1,21 @@ +--- +title: Oracle Database Metrics Exporter +sidebar_position: 3 +--- +## Oracle Database Metrics Exporter + +This project provides observability for Oracle Database, helping users understand performance and diagnose issues across applications and the database. Over time, it will expand beyond metrics to include logging, tracing, and integrations with popular frameworks such as Spring Boot. It targets both cloud and on-premises deployments, including databases running in Kubernetes and containers + +[Full documentation](https://github.com/oracle/oracle-db-appdev-monitoring). + +### Installing Oracle Database Metrics Exporter + +Oracle Database Metrics Exporter will be installed if the `oracle-database-exporter.enabled` is set to `true` in the `values.yaml` file. The default namespace for Conductor is `oracle-database-exporter`. + +### Oracle Database Grafana Dashboard + +![Oracle Database Dashboard](images/exporter-running-against-basedb.png) + +### Transactional Event Queue Grafana Dashboard + +![Oracle Database Dashboard](images/txeventq-dashboard-v2.png) diff --git a/docs-source/site/docs/platform/dboperator.md b/docs-source/site/docs/platform/dboperator.md new file mode 100644 index 000000000..ac8369c44 --- /dev/null +++ b/docs-source/site/docs/platform/dboperator.md @@ -0,0 +1,15 @@ +--- +title: Oracle Database Operator for Kubernetes +sidebar_position: 4 +--- +## Oracle Database Operator for Kubernetes + +The Oracle Database Operator for Kubernetes (_OraOperator_, or simply the _operator_) extends the Kubernetes API with custom resources and controllers to automate Oracle Database lifecycle management. + +[Full Documentation](https://github.com/oracle/oracle-database-operator). + +Learn about using the OraOperator in the Livelab [Microservices and Kubernetes for an Oracle DBA](https://apexapps.oracle.com/pls/apex/dbpm/r/livelabs/view-workshop?wid=3734) + +### Installing the Oracle Database Operator for Kubernetes + +Oracle Database Operator for Kubernetes will be installed if the `oracle-database-operator.enabled` is set to `true` in the `values.yaml` file. The default namespace for Conductor is `oracle-database-exporter-system`. diff --git a/docs-source/site/docs/platform/esooperator.md b/docs-source/site/docs/platform/esooperator.md new file mode 100644 index 000000000..1d2b6f640 --- /dev/null +++ b/docs-source/site/docs/platform/esooperator.md @@ -0,0 +1,20 @@ +--- +title: External Secrets Operator +sidebar_position: 5 +--- +## External Secrets Operator + +:::important +The External Secrets Operator is a pre-requisite for Oracle Backend for Microservices and AI +::: + +External Secrets Operator is a Kubernetes operator that integrates external secret management systems like OCI Vault, AWS Secrets Manager, +HashiCorp Vault, Google Secrets Manager, Azure Key Vault and many more. The operator reads information from external APIs and automatically injects the values into a Kubernetes Secret. + +Full [documentation](https://external-secrets.io/latest/) + +![External Secrets Operator](images/diagrams-high-level-simple.png) + +### Installing External Secrets Operator + +External Secrets Operator will be installed if the `external-secrets.enabled` is set to `true` in the `values.yaml` file. The default namespace for External Secrets Operator is `external-secrets`. diff --git a/docs-source/site/docs/platform/eureka.md b/docs-source/site/docs/platform/eureka.md new file mode 100644 index 000000000..3b253d9f7 --- /dev/null +++ b/docs-source/site/docs/platform/eureka.md @@ -0,0 +1,72 @@ +--- +title: Spring Boot Eureka Server +sidebar_position: 6 +--- +## Spring Boot Eureka Server + +Oracle Backend for Microservices and AI includes the Spring Boot Eureka service registry, which stores information about client services. Typically, each microservice registers with Eureka at startup. Eureka maintains a list of all active service instances, including their IP addresses and ports. Other services can look up this information using a well-known key, enabling service-to-service communication without hardcoding addresses at development or deployment time. + +### Installing Spring Boot Eureka Server + +Spring Boot Eureka Server will be installed if the `eureka.enabled` is set to `true` in the `values.yaml` file. The default namespace for Spring Boot Eureka Server is `eureka`. + +### Access Eureka Web User Interface + +To access the Eureka Web User Interface, use kubectl port-forward to create a secure channel to `service/eureka`. Run the following command to establish the secure tunnel (replace the example namespace `obaas-dev` with the namespace where the Spring Boot Eureka Server is deployed): + +```shell +kubectl port-forward -n obaas-dev svc/eureka 8761 +``` + +Open the [Eureka web user interface](http://localhost:8761) + +![Eureka Web User Interface](images/eureka-web.png) + +### Enable a Spring boot application for Eureka + +To Spring boot application you need to add the following dependency + +```xml + + org.springframework.cloud + spring-cloud-starter-netflix-eureka-client + +``` + +And to configure the application to register with Eureka add the following to the `application.yaml` file. The variables in this configuration are automatically injected to your deployment and pods you deploy applications to Oracle Backend for Microservices and AI using the OBaaS deployment Helm chart. + +```yaml +eureka: + instance: + hostname: ${spring.application.name} + preferIpAddress: true + client: + service-url: + defaultZone: ${eureka.service-url} + fetch-registry: true + register-with-eureka: true + enabled: true +``` + +### Enable a Helidon application for Eureka + +To Spring boot application you need to add the following dependency + +```xml + + io.helidon.integrations.eureka + helidon-integrations-eureka + runtime + +``` + +And to configure the application to register with Eureka add the following to the `aaplication.yaml` file: + +```properties +server.features.eureka.enabled=true +server.features.eureka.instance.name=${eureka.instance.hostname} +server.features.eureka.client.base-uri=${eureka.client.service-url.defaultZone} +server.features.eureka.client.register-with-eureka=true +server.features.eureka.client.fetch-registry=true +server.features.eureka.instance.preferIpAddress=true +``` diff --git a/docs-source/site/docs/platform/images/admin-server.png b/docs-source/site/docs/platform/images/admin-server.png new file mode 100644 index 000000000..6736c6216 Binary files /dev/null and b/docs-source/site/docs/platform/images/admin-server.png differ diff --git a/docs-source/site/docs/platform/images/diagrams-high-level-simple.png b/docs-source/site/docs/platform/images/diagrams-high-level-simple.png new file mode 100644 index 000000000..460003eb9 Binary files /dev/null and b/docs-source/site/docs/platform/images/diagrams-high-level-simple.png differ diff --git a/docs-source/site/docs/platform/images/eureka-web.png b/docs-source/site/docs/platform/images/eureka-web.png new file mode 100644 index 000000000..179f9e5a9 Binary files /dev/null and b/docs-source/site/docs/platform/images/eureka-web.png differ diff --git a/docs-source/site/docs/platform/images/exporter-running-against-basedb.png b/docs-source/site/docs/platform/images/exporter-running-against-basedb.png new file mode 100755 index 000000000..a8c99d4df Binary files /dev/null and b/docs-source/site/docs/platform/images/exporter-running-against-basedb.png differ diff --git a/docs-source/site/docs/platform/images/txeventq-dashboard-v2.png b/docs-source/site/docs/platform/images/txeventq-dashboard-v2.png new file mode 100755 index 000000000..9418bf2f1 Binary files /dev/null and b/docs-source/site/docs/platform/images/txeventq-dashboard-v2.png differ diff --git a/docs-source/site/docs/platform/kafka.md b/docs-source/site/docs/platform/kafka.md new file mode 100644 index 000000000..4468647c7 --- /dev/null +++ b/docs-source/site/docs/platform/kafka.md @@ -0,0 +1,29 @@ +--- +title: Apache Kafka +sidebar_position: 7 +--- +## Apache Kafka + +[Apache Kafka](https://kafka.apache.org) is an open-source, distributed streaming platform designed for high-throughput, fault-tolerant, and scalable real-time data processing. It acts as a messaging system that enables applications to publish, subscribe to, store, and process streams of data (events or messages) efficiently. + +### Installing Apache Kafka + +Apache Kafka will be installed if the `kafka.enabled` is set to `true` in the `values.yaml` file. The default namespace for Apache Kafka is `kafka` + +### Access the Kafka cluster + +The address to the boot strap servers in Oracle Backend for Microservices and AI is: + +`kafka-cluster-kafka-bootstrap.kafka.svc.cluster.local:9092` + +An example Spring Boot application.yaml could look like this: + +```yaml +spring: + kafka: + bootstrap-servers: kafka-cluster-kafka-bootstrap.kafka.svc.cluster.local:9092 +``` + +### Strimzi Operator + +The Kafka cluster is deployed using the [Strimzi](https://strimzi.io) operator. The cluster is using Zookeeper. diff --git a/docs-source/site/docs/platform/otmm.md b/docs-source/site/docs/platform/otmm.md new file mode 100644 index 000000000..b46263161 --- /dev/null +++ b/docs-source/site/docs/platform/otmm.md @@ -0,0 +1,47 @@ +--- +title: Oracle Transaction Manager for Microservices +sidebar_position: 8 +--- +## Oracle Transaction Manager for Microservices + +[Oracle Transaction Manager for Microservices](https://www.oracle.com/database/transaction-manager-for-microservices/), also known as "MicroTx", simplifies application development and operations by enabling distributed transactions to ensure consistency across microservices deployed in Kubernetes. + +Oracle Backend for Microservices and AI includes the free version of MicroTx, which has all of the functionality of the commercial version, but limits the number of transactions and only persists data in memory. It is recommended for evaluations and application development purposes. + +MicroTx supports the following consistency models: + +- Extended Architecture (XA) +- Long Running Actions (LRA) +- Try-Confirm/Cancel (TCC) + +### Installing Oracle Transaction Manager for Microservices + +### Use Oracle Transaction Manager for Microservices with Spring Boot + +To use MicroTx in your Spring Boot applications, include the following dependency in your `pom.xml` or equivalent: + +```xml + + com.oracle.microtx.lra + microtx-lra-spring-boot-starter-3x + +``` + +Add the following configuration to your Spring application configuration. The variables in this configuration are automatically injected to your deployment and pods you deploy applications to Oracle Backend for Microservices and AI using the OBaaS deployment Helm chart. + +```yaml +spring: + microtx: + lra: + coordinator-url: ${MP_LRA_COORDINATOR_URL} + propagation-active: true + headers-propagation-prefix: "{x-b3-, oracle-tmm-, authorization, refresh-}" + +lra: + coordinator: + url: ${MP_LRA_COORDINATOR_URL} +``` + +## Upgrading to the commercial version + +If you have licensed Oracle Transaction Manager for Microservices Enterprise Edition, please see the [documentation](https://docs.oracle.com/en/database/oracle/transaction-manager-for-microservices/23.4.1/index.html) for details of how to install and configure MicroTx. Oracle recommends that you perform a new installation rather than attempting to upgrade the provided MicroTx Free installation to the commercial version. \ No newline at end of file diff --git a/docs-source/site/docs/platform/platform.md b/docs-source/site/docs/platform/platform.md deleted file mode 100644 index 46ae84f74..000000000 --- a/docs-source/site/docs/platform/platform.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: Platform Services -sidebar_position: 1 ---- - -:::important -This content is TBD -::: diff --git a/docs-source/site/docs/setup/database.md b/docs-source/site/docs/setup/database.md index 3eb00f642..db8574011 100644 --- a/docs-source/site/docs/setup/database.md +++ b/docs-source/site/docs/setup/database.md @@ -20,7 +20,7 @@ You must edit the **values.yaml** file as follows: **Important note**: Please pause to double check all of the values are correct. If there are any errors here, the database provisioning will fail. -Install the Helm chart using the following command (The `--debug` flag is optional and enables verbose output from Helm). +Install the Helm chart using the following command (The `--debug` flag is optional and enables verbose output from Helm). - global.obaasName="obaas-dev" - Sets the OBaaS instance name. - global.targetNamespace="obaas-dev" - Specifies the target namespace (*OPTIONAL*, only needed if you want to override the default namespace).