diff --git a/docs-source/spring/content/_index.md b/docs-source/spring/content/_index.md index aba3f6588..60626820a 100644 --- a/docs-source/spring/content/_index.md +++ b/docs-source/spring/content/_index.md @@ -1,5 +1,7 @@ --- title: "Oracle Backend for Spring Boot and Microservices" +description: "Spring SpringBoot Spring Boot" +keywords: "spring springboot" --- Oracle Backend for Spring Boot and Microservices allows developers to build microservices in Spring Boot and provisions a "backend as a service" with @@ -7,9 +9,9 @@ Oracle Database and other infrastructure components that operate on multiple clo building, testing, and operating microservices platforms for reliable, secure, and scalable enterprise applications.   -{{< hint type=[warning] icon=gdoc_fire title="Version 1.0 (production) released October, 2023" >}} - Oracle Backend for Spring Boot and Microservices Version 1.0 is now generally available and suitable - for production use. This version supports and recommends Spring Boot 3.1.x, Spring 6.0 and Spring Cloud 2022.0.4, +{{< hint type=[warning] icon=gdoc_fire title="Version 1.1 (production) released February, 2024" >}} + Oracle Backend for Spring Boot and Microservices Version 1.1 is now generally available and suitable + for production use. This version supports and recommends Spring Boot 3.2.x, Spring 6.1 and Spring Cloud 2023.0.0, with limited backwards compatibility for Spring Boot 2.7.x. {{< /hint >}}   @@ -83,7 +85,6 @@ We'd love to hear from you! You can contact us in the [#oracle-db-microservices](https://oracledevs.slack.com/archives/C03ALDSV272) channel in the Oracle Developers slack workspace, or [open an issue in GitHub](https://github.com/oracle/microservices-datadriven/issues/new). -   {{< hint type=[warning] icon=gdoc_fire title="Interested in Mobile or web apps too?" >}} Check out [Oracle Backend for Parse Platform](https://oracle.github.io/microservices-datadriven/mbaas/) - our "MERN" diff --git a/docs-source/spring/content/azure/_index.md b/docs-source/spring/content/azure/_index.md index ef953acae..93e440259 100644 --- a/docs-source/spring/content/azure/_index.md +++ b/docs-source/spring/content/azure/_index.md @@ -1,5 +1,7 @@ --- title: "Azure/OCI Multicloud Installation" +description: "Multi-cloud Spring Boot Backend on Azure makes it easy for developers to build, deploy and operate microservices in a multicloud environment with Oracle Autonomous Database" +keywords: "spring springboot microservices multicloud azure oracle" --- The Oracle Backend for Spring Boot and Microservices is available to install in Multicloud (Microsoft Azure (Azure) and Oracle Cloud Infrastructure (OCI)). This installation diff --git a/docs-source/spring/content/blogs/_index.md b/docs-source/spring/content/blogs/_index.md index 58f9e275b..d0e96eece 100644 --- a/docs-source/spring/content/blogs/_index.md +++ b/docs-source/spring/content/blogs/_index.md @@ -1,5 +1,7 @@ --- title: "Read our blogs!" +description: "Read blog posts from the team that builds the Oracle Backend for Spring Boot and Microservices" +keywords: "blogs team spring springboot microservices mobile oracle" --- Our team members post blog articles and other content on various sites including [Medium](https://medium.com/@mark.x.nelson), LinkedIn ([Corrado de Bari](https://www.linkedin.com/in/corradodebari/), [Doug Drechsel](https://www.linkedin.com/in/dougdrechsel/)), [RedStack](https://redstack.wordpress.com), [DZone](https://dzone.com/users/4571557/paulparkinson.html), [Andy Tael](https://mr-a.org) and the [Oracle Developers Blog](https://blogs.oracle.com/developers). diff --git a/docs-source/spring/content/cluster-access/_index.md b/docs-source/spring/content/cluster-access/_index.md index 4056e5632..80bbd8a57 100644 --- a/docs-source/spring/content/cluster-access/_index.md +++ b/docs-source/spring/content/cluster-access/_index.md @@ -1,5 +1,7 @@ --- title: "Kubernetes Access" +description: "Access the Kubernetes cluster in the backend where your Spring Boot microservices applications are deployed" +keywords: "kubernetes cluster spring springboot microservices oracle" resources: - name: oci-cloud-shell src: "oci-cloud-shell.png" diff --git a/docs-source/spring/content/database/_index.md b/docs-source/spring/content/database/_index.md index 565362ab8..ad6d88164 100644 --- a/docs-source/spring/content/database/_index.md +++ b/docs-source/spring/content/database/_index.md @@ -1,5 +1,7 @@ --- title: "Database Access" +description: "Access the Oracle Autonomous Database in the backend where your Spring Boot microservices applications are deployed" +keywords: "database autonomous oracle spring springboot microservices backend" resources: - name: oci-adb-cloud-portal src: "oci-adb-cloud-portal.png" diff --git a/docs-source/spring/content/development/_index.md b/docs-source/spring/content/development/_index.md index 08c664e20..3a0ab04bd 100644 --- a/docs-source/spring/content/development/_index.md +++ b/docs-source/spring/content/development/_index.md @@ -1,38 +1,26 @@ -This section provides information about how to develop and deploy Spring Boot applications -with the Oracle Backend for Spring Boot and Microservices. +--- +title: "Development" +description: "How to develop and deploy Spring Boot applications with the Oracle Backend for Spring Boot and Microservices" +keywords: "spring springboot microservices development oracle backend" +--- -Spring Boot applications can be developed with no special requirements and -be deployed into Oracle Backend for Spring Boot and Microservices. However, if you do opt-in to the platform -services provided and the CLI, you can shorten your development time and avoid unnecessary -work. +This section provides information about how to develop and deploy Spring Boot applications with the Oracle Backend for Spring Boot and Microservices. -Oracle Backend for Spring Boot provides the following services that applications can use: +Spring Boot applications can be developed with no special requirements and be deployed into Oracle Backend for Spring Boot and Microservices. However, if you do opt-in to the platform services provided and the CLI, you can shorten your development time and avoid unnecessary work. -- An Oracle Autonomous Database instance in which applications can manage relational, - document, spatial, graph and other types of data, can use Transactional Event Queues for - messaging and events using Java Message Service (JMS), Apache Kafka or Representational - State Transfer (REST) interfaces, and even run machine learning (ML) models. -- A Kubernetes cluster in which applications can run with namespaces pre-configured with - Kubernetes Secrets and ConfigMaps for access to the Oracle Autonomous Database instance - associated with the backend. -- An Apache APISIX API Gateway that can be used to expose service endpoints outside the Kubernetes - cluster, to the public internet. All standard Apache APISIX features like traffic management, - monitoring, authentication, and so on, are available for use. -- Spring Boot Eureka Service Registry for service discovery. The API Gateway and monitoring - services are pre-configured to use this registry for service discovery. -- Spring Cloud Config Server to serve externalized configuration information to applications. - This stores the configuration data in the Oracle Autonomous Database - instance associated with the backend. -- Netflix Conductor OSS for running workflows to orchestrate your services. -- Hashicorp Vault for storing sensitive information. -- Spring Admin for monitoring your services. -- Prometheus and Grafana for collecting and visualizing metrics and for alerting. -- Jaeger for distributed tracing. Applications deployed with the Oracle Backend for - Spring Boot and Microservices CLI have the Open Telemetry Collector automatically added as a Java - agent to provide tracing from the application into the Oracle Database. +Oracle Backend for Spring Boot provides the following services that applications can use: -An integrated development environment is recommended for developing applications. Oracle -recommends Visual Studio Code or IntelliJ. +* An Oracle Autonomous Database instance in which applications can manage relational, document, spatial, graph and other types of data, can use Transactional Event Queues for messaging and events using Java Message Service (JMS), Apache Kafka or Representational State Transfer (REST) interfaces, and even run machine learning (ML) models. +* A Kubernetes cluster in which applications can run with namespaces pre-configured with Kubernetes Secrets and ConfigMaps for access to the Oracle Autonomous Database instance associated with the backend. +* An Apache APISIX API Gateway that can be used to expose service endpoints outside the Kubernetes cluster, to the public internet. All standard Apache APISIX features like traffic management, monitoring, authentication, and so on, are available for use. +* Spring Boot Eureka Service Registry for service discovery. The API Gateway and monitoring services are pre-configured to use this registry for service discovery. +* Spring Cloud Config Server to serve externalized configuration information to applications. This stores the configuration data in the Oracle Autonomous Database instance associated with the backend. +* Netflix Conductor OSS for running workflows to orchestrate your services. +* Hashicorp Vault for storing sensitive information. +* Spring Admin for monitoring your services. +* Prometheus and Grafana for collecting and visualizing metrics and for alerting. +* Jaeger and Open Telemetry (OTEL) for distributed tracing. Applications deployed to the Oracle Backend for Spring Boot may use Jaeger or OTEL for distributed tracing. See the [Environment Variables page](envvars) for variables that can be used. -Java, Maven or Gradle, a version control system (Oracle recommends git), and other -tools may be required during development. +An integrated development environment is recommended for developing applications. Oracle recommends Visual Studio Code or IntelliJ. + +Java, Maven or Gradle, a version control system (Oracle recommends git), and other tools may be required during development. diff --git a/docs-source/spring/content/development/cli/_index.md b/docs-source/spring/content/development/cli/_index.md index d4ff82556..88e1b09d5 100644 --- a/docs-source/spring/content/development/cli/_index.md +++ b/docs-source/spring/content/development/cli/_index.md @@ -1,5 +1,7 @@ --- title: "OBaaS CLI" +description: "Command Line Interface for Oracle Backend for Spring Boot and Microservices" +keywords: "cli tool deployment spring springboot microservices development oracle backend" --- The Oracle Backend for Spring Boot and Microservices offers a command-line interface (CLI), `oractl`. The CLI commands simplify the deployment of @@ -18,6 +20,8 @@ Table of Contents: * [Delete application namespace](#delete) * [Bind database schema/kubernetes secrets](#bind) * [Deploy a service](#deploy) + * [Create a horizontal pod autoscaler](#create-autoscaler) + * [Delete a horizontal pod autoscaler](#delete-autoscaler) * [List - show details about deployments](#list) * [Manage config server data](#config) * [GraalVM compile commands](#compile) @@ -44,13 +48,15 @@ Short descriptions for the available commands can be viewed by issuing the `help commands can be viewed by issuing `help [command-name]`. For example: ```cmd +oractl:>help AVAILABLE COMMANDS -Admin Server Commands - connect: Connect to the OBaaS Spring Cloud admin console. - Application/Namespace Commands - create: Create an application/namespace. + * create: Create an application/namespace. + +Autoscaler Commands + * create-autoscaler: Create an autoscaler. + * delete-autoscaler: Delete an autoscaler. Built-In Commands help: Display help about available commands @@ -62,19 +68,32 @@ Built-In Commands script: Read and execute commands from a file. GraalVM Compile Commands - compile-download: Download executable file compiled - compile: Compile a service with GraalVM - compile-purge: Delete a job launched - compile-logs: Compilation progress + * compile-download: Download executable file compiled + * compile: Compile a service with GraalVM + * compile-purge: Delete a job launched + * compile-logs: Compilation progress + +Identity and Access Management Service + * user list: Lists the users in your platform. + * user create: Creates a new user in your platform. + * user get: Gets the specified user’s information. + * user delete: Delete a user in your platform. + * user change-roles: Change the roles from the specified user. + connect: Connect to the OBaaS Admin Service. + * user change-password: Change password for the specified user. Informational Commands - list: list/show details of application services. + * list: list/show details of application services. Service Commands - bind: Create or Update a schema/user and bind it to service deployment. - delete: Delete a service or entire application/namespace. - config: View and modify Service configuration. - deploy: Deploy a service. + * bind: Create or Update a schema/user and bind it to service deployment. + * delete: Delete a service or entire application/namespace. + * config: View and modify Service configuration. + * deploy: Deploy a service. + + +Commands marked with (*) are currently unavailable. +Type `help ` to learn more. Ask for Help Slack: https://oracledevs.slack.com/archives/C03ALDSV272 @@ -91,6 +110,8 @@ The [`bind`](#bind) command results in the automatic creation of a database sche The [`deploy`](#deploy) command takes `service-name`, `app-name`, and `artifact-path` as the main arguments (`image-version` and `java-version` options are also provided). When the `deploy` command is issued, the microservice JAR file is uploaded to the backend and a container image is created for the JAR or microservice, and various Kubernetes resources such as **Deployment** and **Service** are also created. This is all done automatically to simplify the development process and the management of the microservices by the backend. +The [`create-autoscaler`](#create-autoscaler) and [`delete-autoscaler`](#delete-autoscaler) commands allow you to create and delete horizontal pod autoscalers for specific microservices. + The [`list`](#list) command shows the details of the deployed microservices. The [`config`](#config) command can also be used to add, view, update, and delete configurations managed by the Spring Cloud Config server. @@ -284,13 +305,9 @@ NAME deploy - Deploy a service. SYNOPSIS - deploy --redeploy boolean --bind String --app-name String [--service-name String] [--image-version String] --service-profile String --port String --java-version String --add-health-probe boolean --liquibase-db String [--artifact-path String] --initial-replicas int --graalvm-native boolean --help + deploy --bind String --app-name String [--service-name String] [--image-version String] --service-profile String --port String --java-version String --add-health-probe boolean --liquibase-db String [--artifact-path String] --initial-replicas int --cpu-request String --graalvm-native boolean --apigw boolean --route String --apikey String --help OPTIONS - --redeploy boolean - whether the service has already been deployed or not - [Optional, default = false] - --bind String automatically create and bind resources. possible values are [jms] [Optional] @@ -335,18 +352,39 @@ OPTIONS The initial number of replicas [Optional, default = 1] + --cpu-request String + The amount of CPU to request + [Optional, default = 500m] + --graalvm-native boolean Artifact is a graalvm native compiled by Oracle Backend [Optional, default = false] + --apigw boolean + open routing through APISIX + [Optional, default = false] + + --route String + set an APISIX route path + [Optional, default = /api/v1/] + + --apikey String + set APISIX API_KEY + [Optional] + --help or -h help for deploy [Optional] + + +CURRENTLY UNAVAILABLE + you are not signedIn. Please sign in to be able to use this command! + Ask for Help Slack: https://oracledevs.slack.com/archives/C03ALDSV272 E-mail: obaas_ww@oracle.com - ``` +``` For example: @@ -363,6 +401,104 @@ Ask for Help oractl:>deploy --app-name cloudn --service-name account --artifact-path obaas/myserv/target/accounts-0.0.1-SNAPSHOT.jar.exec --image-version 0.0.1 --graalvm-native --java-version container-registry.oracle.com/os/oraclelinux:7-slim ``` +### create-autoscaler + +Use the `create-autoscaler` command to create a horizontal pod autoscaler for a microservice you have deployed. You can specify the target scaling threshold using CPU percentage. Note that your microservice must have its CPU request set in order to use the autoscaler. It is set to `500m` (that is, half a core) by the `deploy` command if you did not override the default. + +```cmd +oractl:>help create-autoscaler +NAME + create-autoscaler - Create an autoscaler. + +SYNOPSIS + create-autoscaler --app-name String [--service-name String] --min-replicas int --max-replicas int --cpu-percent int --help + +OPTIONS + --app-name String + application/namespace + [Optional, default = application] + + --service-name String + Service Name + [Mandatory] + + --min-replicas int + The minimium number of replicas + [Optional, default = 1] + + --max-replicas int + The maximum number of replicas + [Optional, default = 4] + + --cpu-percent int + The CPU percent at which to scale + [Optional, default = 80] + + --help or -h + help for create-autoscaler + [Optional] + + +Ask for Help + Slack: https://oracledevs.slack.com/archives/C03ALDSV272 + E-mail: obaas_ww@oracle.com +``` + +For example: + +```cmd +oractl:>create-autoscaler --app-name application --service-name creditscore --cpu-percent 80 --min-replicas 2 --max-replicas 6 +obaas-cli [create-autoscaler]: Autoscaler was successfully created. +``` + +You can view the details of the autoscaler using `kubectl`, for example: + +```cmd +$ kubectl -n application get hpa +NAME REFERENCE TARGETS MINPODS MAXPODS REPLICAS AGE +creditscore Deployment/creditscore 0%/80% 2 6 2 26s +customer Deployment/customer 4%/80% 2 6 2 26h + +``` + +### delete-autoscaler + +Use the `delete-autoscaler` command to delete a horizontal pod autoscaler for a microservice you have deployed. + +```cmd +oractl:>help delete-autoscaler +NAME + delete-autoscaler - Delete an autoscaler. + +SYNOPSIS + delete-autoscaler --app-name String [--service-name String] --help + +OPTIONS + --app-name String + application/namespace + [Optional, default = application] + + --service-name String + Service Name + [Mandatory] + + --help or -h + help for delete-autoscaler + [Optional] + + +Ask for Help + Slack: https://oracledevs.slack.com/archives/C03ALDSV272 + E-mail: obaas_ww@oracle.com +``` + +For example: + +```cmd +oractl:>delete-autoscaler --app-name application --service-name creditscore +obaas-cli [delete-autoscaler]: Autoscaler was successfully deleted. +``` + ### list Use the `list` command to show details of the microservice deployed in the previous step. For example: diff --git a/docs-source/spring/content/development/envvars.md b/docs-source/spring/content/development/envvars.md new file mode 100644 index 000000000..4a1df6fe0 --- /dev/null +++ b/docs-source/spring/content/development/envvars.md @@ -0,0 +1,32 @@ +--- +title: "Predefined Variables" +description: "Predefined environment variables in Oracle Backend for Spring Boot and Microservices" +keywords: "predefined variables spring springboot microservices development oracle backend" +--- + +When you deploy a Spring Boot application using the Oracle Backend for Spring Boot and Microservices CLI or Visual Code extension, a number of predefined environment variables will be injected into the pod definition. You may reference any of these variables in your application. + +The predefined variables are as follows: + +Variable name | Example value | Notes +---------------------------------------|----------------|--------- +`app.container.port` | `8080` | This sets the listen port for the pod and service. The Spring Boot application will listen on this port. The default is `8080`. This can be set using the `--port` parameter on the `deploy` command in the CLI. +`spring.profiles.active` | `default` | This sets the Spring profiles that will be active in the application. The default value is `default`. This can be changed set the `--service-profile` parameter on the `deploy` command in the CLI. +`spring.config.label` | `0.0.1` | This is a label that can be used with Spring Config to look up externalized configuration from Spring Config Server, along with the application name and the profile. +`eureka.instance.preferIpAddress` | `true` | This tells the Eureka discovery client to use the `preferIpAddress` setting. This is required in Kubernetes so that service discover will work correctly. +`eureka.instance.hostname` | `customer32.application` | This sets the hostname that Eureka will use for this application. +`MP_LRA_COORDINATOR_URL` | `http://otmm-tcs.otmm.svc.cluster.local:9000/api/v1/lra-coordinator` | This is the URL for the transaction manager which is required when using Eclipse Microprofile Long Running Actions in your application. +`MP_LRA_PARTICIPANT_URL` | `http://customer32.application.svc.cluster.local:8080` | This is the participant URL which is required when using Eclipse Microprofile Long Running Actions in your application. +`eureka.client.register-with-eureka` | `true` | This tells the Eureka discovery client to register with the Eureka server. +`eureka.client.fetch-registry` | `true` | This tells the Eureka discovery client to make a local copy of the registry by fetching it from the Eureka server. +`eureka.client.service-url.defaultZone` | `http://eureka.eureka:8761/eureka` | This is the default zone for the Eureka discovery client. +`zipkin.base-url` | `http://jaegertracing-collector.observability.svc.cluster.local:9411/api/v2/spans` | This is the URL of the Zipkin-compatible trace collector which can be used by your application to send trace data to the platform. +`otel.exporter.otlp.endpoint` | `http://open-telemetry-opentelemetry-collector.open-telemetry:4318/v1/traces` | This is the URL of the OpenTelemetry (OTLP protocol) trace collector which can be used by your application to send trace data to the platform. +`config.server.url` | `http://config-server.config-server.svc.cluster.local:8080` | This is the URL of the Spring Config Server provided by the platform. +`liquibase.datasource.username` | set to the key `db.username` in secret `admin-liquibasedb-secrets` | This sets the (admin) user that should be used to run Liquibase, if used in your service. +`liquibase.datasource.password` | set to the key `db.password` in secret `admin-liquibasedb-secrets` | This sets the (admin) user's password that should be used to run Liquibase, if used in your service. +`spring.datasource.username` | set to the key `db.username` in secret `customer32-db-secrets` | This sets the (regular) user for your application to use to connect to the database (if you use JPA or JDBC in your application). +`spring.datasource.password`: | set to the key `db.password` in secret `customer32-db-secrets` | This sets the (regular) user's password for your application to use to connect to the database (if you use JPA or JDBC in your application). +`DB_SERVICE` | set to the key `db.service` in secret `customer32-db-secrets` | This sets the database service name (the TNS name) for your application to use to connect to the database (if you use JPA or JDBC in your application). +`spring.datasource.url` | `jdbc:oracle:thin:@$(DB_SERVICE)?TNS_ADMIN=/oracle/tnsadmin` | This sets the data source URL for your application to use to connect to the database (if you use JPA or JDBC in your application). +`CONNECT_STRING` | `jdbc:oracle:thin:@$(DB_SERVICE)?TNS_ADMIN=/oracle/tnsadmin` | This sets the data source URL for your application to use to connect to the database (if you use JPA or JDBC in your application). diff --git a/docs-source/spring/content/development/project.md b/docs-source/spring/content/development/project.md index f4586ef36..743692c6b 100644 --- a/docs-source/spring/content/development/project.md +++ b/docs-source/spring/content/development/project.md @@ -1,13 +1,15 @@ --- title: "Project Structure" +description: "How to structure your Spring Boot application for deployment in Oracle Backend for Spring Boot and Microservices" +keywords: "spring springboot microservices development oracle backend" --- To take advantage of the built-in platform services, Oracle recommends using the following project structure. Recommended versions: -* Spring Boot 3.1.6 -* Spring Cloud 2022.0.4 +* Spring Boot 3.2.x +* Spring Cloud 2023.x.x * Java 17 or 21 Table of Contents: @@ -18,6 +20,7 @@ Table of Contents: * [Liquibase](#liquibase) * [Oracle Transaction Manager for Microservices](#oracle-transaction-manager-for-microservices) * [Spring Config Server](#spring-config-server) + * [Tracing](#tracing) ## Dependencies @@ -27,8 +30,8 @@ Oracle recommends adding the following dependencies to your application so that UTF-8 17 - 3.1.6 - 2022.0.4 + 3.2.1 + 2023.0.0 @@ -78,8 +81,6 @@ Oracle recommends the following configuration in order for the application to ac spring: application: name: account - zipkin: - base-url: ${zipkin.base-url} eureka: instance: @@ -109,7 +110,29 @@ The variables in this configuration are automatically injected to your deploymen ### Data Sources -If your application uses a data source, then add the following configuration. Note that this example shows Java Persistence API (JPA). If you are using JDBC you should use the appropriate configuration. For example: +If your application uses an Oracle database as data source, then add the following to the 'pom.xml'. For more information about the [Oracle Spring Boot Starters](../starters/_index). + +```xml + + com.oracle.database.spring + oracle-spring-boot-starter-ucp + 23.4.0 + pom + +``` + +If the database requires a Wallet to access the database you must add the following to the `pom.xml` file: + +```xml + + com.oracle.database.spring + oracle-spring-boot-starter-wallet + 23.4.0 + pom + +``` + + Add the following to application configuration. Note that this example shows Java Persistence API (JPA). If you are using JDBC you should use the appropriate configuration. For example: ```yaml spring: @@ -144,7 +167,7 @@ If you are using Liquibase to manage your database schema and data, then you sho ```xml - 4.25.0 + 4.25.1 @@ -212,6 +235,67 @@ Add the following configuration to your Spring application configuration. The va ```yaml spring: + application: + name: config: - import=optional:configserver:${config.server.url} + import: optional:configserver:${config.server.url} + + cloud: + config: + label: + profile: + username: + password: +``` + +## Tracing + +### Application Tracing + +To enable Open Telemetry (OTEL) tracing you need to add the following dependencies to the `pom/xml` file. + +```xml + + io.micrometer + micrometer-tracing-bridge-otel + + + io.opentelemetry + opentelemetry-exporter-otlp + + + io.micrometer + micrometer-tracing + +``` + +In addition add the following to the application configuration. The variable in this configuration are automatically injected to your deployment and pods when you use the Oracle Backend for Spring Boot and Microservices CLI or the Visual Studio Code Extension to deploy your application. For example: + +```yaml +management: + tracing: + sampling: + probability: 1.0 + info: + os: + enabled: true + env: + enabled: true + java: + enabled: true + otlp: + tracing: + endpoint: ${otel.exporter.otlp.endpoint} +``` + +### Database tracing + +To get tracing for the database calls you need to add the following dependency to the `po.xml` file: + +```xml + + net.ttddyy.observation + datasource-micrometer-spring-boot + $1.0.2 + ``` diff --git a/docs-source/spring/content/development/setup.md b/docs-source/spring/content/development/setup.md index ba1d09229..aae5dca6b 100644 --- a/docs-source/spring/content/development/setup.md +++ b/docs-source/spring/content/development/setup.md @@ -1,6 +1,9 @@ +--- +description: "How to set up your development environment to build Spring Boot applications with the Oracle Backend for Spring Boot and Microservices" +keywords: "development environment setup spring springboot microservices oracle backend java maven gradle ide tools" +--- -This page provides details on how to set up your development environment to work with -Oracle Backend for Spring Boot and Microservices. +This page provides details on how to set up your development environment to work with Oracle Backend for Spring Boot and Microservices. The following platforms are recommended for a development environment: @@ -11,7 +14,7 @@ The following platforms are recommended for a development environment: The following tools are recommended for a development environment: - Integrated Development Environment, for example Visual Studio Code -- Java Development Kit, for example Oracle, OpenJDK, or GraalVM +- Java Development Kit, for example Oracle, OpenJDK, or GraalVM - Maven or Gradle for build and testing automation If you wish to test locally or offline, then the following additional tools are recommended: @@ -134,4 +137,4 @@ docker run --name free23c -d \ 1.19.2 test -``` \ No newline at end of file +``` diff --git a/docs-source/spring/content/getting-started/_index.md b/docs-source/spring/content/getting-started/_index.md index 27f30b479..bfe9d7d90 100644 --- a/docs-source/spring/content/getting-started/_index.md +++ b/docs-source/spring/content/getting-started/_index.md @@ -1,5 +1,7 @@ --- title: "Getting Started" +description: "Get started with Oracle Backend for Spring Boot and Microservices" +keywords: "spring springboot microservices demos videos samples cloudbank development oracle backend" --- There are a number of demonstrations (videos) and hands-on labs (Live Lab) that show how to use Oracle Backend for Spring Boot and Microservices (Spring Boot) and diff --git a/docs-source/spring/content/observability/_index.md b/docs-source/spring/content/observability/_index.md index 02d5963a8..6caed8994 100644 --- a/docs-source/spring/content/observability/_index.md +++ b/docs-source/spring/content/observability/_index.md @@ -1,5 +1,8 @@ --- title: "Observability" +Noindex: true +description: "Observability for Spring Boot applications with the Oracle Backend for Spring Boot and Microservices" +keywords: "observability metrics tracing spring springboot microservices development oracle backend" --- Oracle Backend for Spring Boot and Microservices includes a number of common open source components to provide application diff --git a/docs-source/spring/content/observability/metrics/_index.md b/docs-source/spring/content/observability/metrics/_index.md index 702606874..638535901 100644 --- a/docs-source/spring/content/observability/metrics/_index.md +++ b/docs-source/spring/content/observability/metrics/_index.md @@ -1,5 +1,7 @@ --- title: "Metrics" +description: "Prometheus metrics and Grafana dashboards for Spring Boot applications with the Oracle Backend for Spring Boot and Microservices" +keywords: "observability metrics prometheus grafana spring springboot microservices development oracle backend" resources: - name: metrics src: "metrics.png" @@ -25,20 +27,206 @@ resources: - name: obaas-grafana-dashboard src: "obaas-grafana-dashboard.png" title: "Grafana Dashboard" + - name: db-dashboard + src: "db-dashboard.png" + title: "Oracle Database Dashboard" + - name: spring-boot-observability-dashboard + src: "spring-boot-observability-dashboard.png" + title: "Spring Boot Observablity Dashboard" + - name: spring-boot-stats-dashboard + src: "spring-boot-stats-dashboard.png" + title: "Spring Boot Statistics Dashboard" + - name: kube-state-metrics-dashboard + src: "kube-state-metrics-dashboard.png" + title: "Kube State Metrics Dashboard" + - name: observability-overview + src: "observability-overview.png" + title: "Observability Overview" --- -The Oracle Backend for Spring Boot and Microservices metrics stack automates metrics aggregation and consists of Prometheus and Grafana components. -Metrics sources expose system and application metrics. The Prometheus components retrieve and store the metrics and Grafana provides -dashboards to visualize them. +Oracle Backend for Spring Boot and Microservices provides built-in platform services to collect metrics from system and application +workloads and pre-built Grafana dashboards to view and explore those metrics. + +On this page, you will find the following topics: + +- [Overview](#overview) +- [Pre-installed dashboards](#pre-installed-dashboards) + - [Spring Boot Observability](#spring-boot-observability) + - [Spring Boot Statistics](#spring-boot-statistics) + - [Oracle Datbase Dashboard](#oracle-database-dashboard) + - [Kube State Metrics Dashboard](#kube-state-metrics-dashboard) +- [How to have metrics collected for your applications](#how-to-have-metrics-collected-for-your-applications) +- [How to access Prometheus](#how-to-access-prometheus) +- [How to access Grafana](#how-to-access-grafana) + +## Overview + +Oracle Backend for Spring Boot and Microservices includes a number of pre-installed and pre-configured components to provide metrics for the platform itself and for your applications. + +The diagram below provides an overview of the components that play a role in metrics: + + +{{< img name="observability-overview" size="medium" lazy=false >}} + + +In the diagram above: + +- You may deploy applications into the platform and to have metrics collected these must either register with the Spring Eureka + Service Registry or you must create Service Monitor resources for your applications. +- Prometheus is configured to auto-discover services that register with the service registry and collect metrics for them. +- Prometheus is configured to collect metrics from application described by a Service Monitor. +- The [Oracle Database Exporter](https://github.com/oracle/oracle-db-appdev-monitoring) and Kube State Metrics are pre-installed + and Prometheus is configured to collect metrics from them. +- Grafana is pre-installed and populated with a set of dashboards (see below). A Prometheus data source is pre-configured. + + +## Pre-installed dashboards + +The following dashboards are pre-installed in Grafana: + +### Spring Boot Observability + +This dashboard provides details of one or more Spring Boot applications including the following: + +- The number of HTTP requests received by the application +- A breakdown of which URL paths requests were received for +- The average duration of requests by path +- The number of exceptions encountered by the application +- Details of 2xx (that is, successful) and 5xx (that is, exceptions) requests +- The request rate per second over time, by path +- Log messages from the service + +You may adjust the time period and to drill down into issues, and search the logs for particular messages. This dashboard is designed for Spring Boot 3.x applications. Some features may work for Spring Boot 2.x applications. + +Here is an example of this dashboard displaying data for a simple application: + + +{{< img name="spring-boot-observability-dashboard" size="medium" lazy=false >}} + + + +### Spring Boot Statistics + +This dashboard provides more in-depth information about services including the following: + +- JVM statistic like heap and non-heap memory usage, and details of garbage collection +- Load average and open files +- Database connection pool statistics (for HikariCP) +- HTTP request statistics +- Logging (logback) statistics + +You may adjust the time period and to drill down into issues, and search the logs for particular messages. This dashboard is designed for Spring Boot 3.x applications. Some features may work for Spring Boot 2.x applications. + +Here is an example of this dashboard displaying data for a simple application: + + +{{< img name="spring-boot-stats-dashboard" size="medium" lazy=false >}} + + +### Oracle Database Dashboard + +This dashboard provides details about the Oracle Database including: + +- Active sessions +- User commits +- Execute count +- Wait time statistics by class + +Here is an example of this dashboard: -{{< img name="metrics" size="small" lazy=false >}} +{{< img name="db-dashboard" size="medium" lazy=false >}} -## View Metrics From the Application in Prometheus +### Kube State Metrics Dashboard + +This dashboard provides details of the Kubernetes cluster including: + +- Pod capacity and requests for CPU and memory +- Node availability +- Deployment, Stateful Set, Pod, Job and Container statistics +- Details of horizontal pod autoscalers +- Details of persistent volume claims + +Here is an example of this dashboard: + + +{{< img name="kube-state-metrics-dashboard" size="medium" lazy=false >}} + -Prometheus is an open source monitoring and alerting system. Prometheus collects and stores metrics as time series data with the timestamp of -the time that they are recorded, and optional Key/Value pairs called labels. +## How to have metrics collected for your applications + +When you deploy an application with Oracle Backend for Spring Boot and Microservices CLI or Visual Code Extension, provided you included the Eureka Discovery Client and Actuator in your application, Prometheus will automatically find your application (using the service registry) and start collecting metrics. These metrics will be included in both the Spring Boot Observability dashboard and the Spring Boot Statistic dashboard automatically. + +To include the Eureka Discovery client in your application, add the following dependencies to your Maven POM or equivalent: + +```xml + + org.springframework.cloud + spring-cloud-starter-netflix-eureka-client + + + org.springframework.boot + spring-boot-starter-actuator + +``` + +You must also add the following configuration to your Spring `application.yaml`: + +```yaml +spring: + application: + name: my-app + +eureka: + instance: + hostname: ${spring.application.name} + preferIpAddress: true + client: + service-url: + defaultZone: ${eureka.service-url} + fetch-registry: true + register-with-eureka: true + enabled: true + +management: + endpoint: + health: + show-details: always + endpoints: + web: + exposure: + include: "*" + metrics: + tags: + application: ${spring.application.name} +``` + +Alternatively, if you do not want to include the Eureka client, you can instead create a `ServiceMonitor` resource for your service. This must be created in the namespace where your application is deployed, and you must specify the correct port and the path for Spring Boot Actuator. Your application must have Actuator and the `prometheus` endpoint enabled, as described above. + +Here is an example of a `ServiceMonitor` for an application: + +```yaml +apiVersion: monitoring.coreos.com/v1 +kind: ServiceMonitor +metadata: + labels: + app: my-app + name: my-app + namespace: application +spec: + endpoints: + - interval: 20s + path: /actuator/prometheus + port: 8080 + selector: + matchLabels: + app: my-app +``` + +## How to access Prometheus + +Prometheus is an open source monitoring and alerting system. Prometheus collects and stores metrics as time series data with the timestamp of the time that they are recorded, and optional Key/Value pairs called labels. 1. Expose the Prometheus user interface (UI) using this command: @@ -56,7 +244,7 @@ the time that they are recorded, and optional Key/Value pairs called labels. * In the search bar, search for `application_ready_time_seconds` and click on **Execute**. * You should see metrics for the Sample Applications. - + For example: @@ -72,11 +260,9 @@ the time that they are recorded, and optional Key/Value pairs called labels. {{< img name="obaas-prometheus-targets" size="large" lazy=false >}} -## View Details of the Application in Grafana +## How to access Grafana -[Grafana](https://grafana.com/docs/grafana/latest/introduction/) open source software enables you to query, visualize, alert, and explore your -metrics, logs, and traces wherever they are stored. Grafana open source software provides tools that turn your time series database (TSDB) data -into insightful graphs and visualizations. Take the following steps: +[Grafana](https://grafana.com/docs/grafana/latest/introduction/) open source software enables you to query, visualize, alert, and explore your metrics, logs, and traces wherever they are stored. Grafana open source software provides tools that turn your time series database (TSDB) data into insightful graphs and visualizations. Take the following steps: 1. Expose Grafana using this command: @@ -95,56 +281,9 @@ into insightful graphs and visualizations. Take the following steps: > **NOTE:** If you do not have `base64`, leave off the last part (`| base64 -d`) in the command, then copy the output, and use this website to decode it: . - - The password is a long string of characters that might be similar to `210BAqNzYkrcWjd58RKC2Xzerx9c0WkZi9LNsG4c`. For example: - - - {{< img name="obaas-grafana-login" size="small" lazy=false >}} - - -3. Set up the Prometheus data source: - - a. At the lower left, click on the system setup symbol and choose **Data Sources**. - - b. Click on the second data source called **Prometheus** and in the address (be careful to get the address field, not the name field), change - the address from to . - - c. At the bottom of the page, click **Save & Test** and wait for 2-3 seconds for the green icon which indicates that the data source is working. - - {{< img name="obaas-grafana-datasource" size="medium" lazy=false >}} - - -4. Set up the dashboard: - - a. In the upper left, find and click the **dasbhoards** link. - - b. Click on the blue button to the right to add a new dashboard. In the pull down menu, select **Import**. - - c. In the field for the Grafana dashboard ID, paste this value: `10280`. - - d. Click **Next**. - - e. In the data source field, select **Prometheus**. - - f. Click **Save**. - - - {{< img name="obaas-grafana-import-dashboard" size="medium" lazy=false >}} - - -5. Navigate the Spring Boot dashboard: - - a. You should see the new dashboard in the list called **Spring Boot Dashboard 2.1**. Click on it to open. - - b. You should automatically see details for the Sample Applications in the dashboard. - - c. Invoke the service. For example, use a `curl` command to create some traffic and observe the dashboard. You may need to repeat - the `curl` command. There is a refresh symbol in the top right corner that enables automatic refresh every 5 seconds (or, for - whatever length of time that you choose). + If you did not set your own password during installation, then the auto-generated password will be a long string of characters that might be similar to `210BAqNzYkrcWjd58RKC2Xzerx9c0WkZi9LNsG4c`. For example: - {{< img name="obaas-grafana-dashboard" size="medium" lazy=false >}} + {{< img name="obaas-grafana-login" size="small" lazy=false >}} - -Next, go to the [Tracing](../observability/tracing/) page to learn more. diff --git a/docs-source/spring/content/observability/metrics/db-dashboard.png b/docs-source/spring/content/observability/metrics/db-dashboard.png new file mode 100755 index 000000000..2dfbeedf5 Binary files /dev/null and b/docs-source/spring/content/observability/metrics/db-dashboard.png differ diff --git a/docs-source/spring/content/observability/metrics/kube-state-metrics-dashboard.png b/docs-source/spring/content/observability/metrics/kube-state-metrics-dashboard.png new file mode 100755 index 000000000..04da12881 Binary files /dev/null and b/docs-source/spring/content/observability/metrics/kube-state-metrics-dashboard.png differ diff --git a/docs-source/spring/content/observability/metrics/observability-overview.png b/docs-source/spring/content/observability/metrics/observability-overview.png new file mode 100755 index 000000000..5801db1c5 Binary files /dev/null and b/docs-source/spring/content/observability/metrics/observability-overview.png differ diff --git a/docs-source/spring/content/observability/metrics/spring-boot-observability-dashboard.png b/docs-source/spring/content/observability/metrics/spring-boot-observability-dashboard.png new file mode 100755 index 000000000..95bc0691a Binary files /dev/null and b/docs-source/spring/content/observability/metrics/spring-boot-observability-dashboard.png differ diff --git a/docs-source/spring/content/observability/metrics/spring-boot-stats-dashboard.png b/docs-source/spring/content/observability/metrics/spring-boot-stats-dashboard.png new file mode 100755 index 000000000..b23946d66 Binary files /dev/null and b/docs-source/spring/content/observability/metrics/spring-boot-stats-dashboard.png differ diff --git a/docs-source/spring/content/observability/tracing/_index.md b/docs-source/spring/content/observability/tracing/_index.md index 2f5919dbd..83ded930b 100644 --- a/docs-source/spring/content/observability/tracing/_index.md +++ b/docs-source/spring/content/observability/tracing/_index.md @@ -1,7 +1,8 @@ --- -title: "Jaeger Tracing" -linkTitle: Jaeger Tracing -description: "Configure Jaeger to capture application traces" +title: "Tracing" +linkTitle: Tracing +description: "Tracing with Open Telemetry for Spring Boot applications with the Oracle Backend for Spring Boot and Microservices" +keywords: "observability tracing opentelemetry spring springboot microservices development oracle backend" resources: - name: obaas-jaeger-ui src: "obaas-jaeger-ui.png" @@ -12,44 +13,126 @@ resources: - name: obaas-jaeger-customer-trace-details src: "obaas-jaeger-customer-trace-details.png" title: "Jaeger Customer Tracing Details" + - name: overview + src: "otel-flow-simple.png" + title: "Overview" weight: 1 draft: false --- -Jaeger is a distributed tracing system used for monitoring and troubleshooting Microservices. -For more information on Jaeger, see the [Jaeger website](https://www.jaegertracing.io/). +## Overview + +In a distributed system, it’s expected that occasional errors are bound to happen when serving requests. A central observability platform helps by capturing application traces/logs and provides an interface to query for a specific request. [OpenTelemetry](https://opentelemetry.io/) helps in standardizing the process of capturing and exporting telemetry data. + +[OpenTelemetry](https://opentelemetry.io/) (OTEL) is a collection of standardized vendor-agnostic tools, APIs, and SDKs. It’s a CNCF incubating project and is a merger of the OpenTracing and OpenCensus projects. + +OpenTracing is a vendor-neutral API for sending telemetry data over to an observability backend. The OpenCensus project provides a set of language-specific libraries that developers can use to instrument their code and send it to any supported backends. [OTEL](https://opentelemetry.io/) uses the same concept of trace and span to represent the request flow across microservices as used by its predecessor projects. + +[OTEL](https://opentelemetry.io/) allows us to instrument, generate, and collect telemetry data, which helps in analyzing application behavior or performance. Telemetry data can include logs, metrics, and traces. We can either automatically or manually instrument the code for HTTP, DB calls, and more. + + +{{< img name="overview" size="medium" lazy="false">}} + + +## How to enable tracing for your applications + +To enable tracing for your application you must include the following dependencies to your Maven POM or equivalent. + +```xml + + org.springframework.boot + spring-boot-starter-actuator + + + io.micrometer + micrometer-registry-prometheus + + + io.micrometer + micrometer-tracing-bridge-otel + + + io.opentelemetry + opentelemetry-exporter-otlp + + + io.micrometer + micrometer-tracing + +``` + +If you want to enable tracing for your database calls (Micrometer observability instrumentation for JDBC DataSource) you must include the following dependency too. You can find the latest version [here](https://mvnrepository.com/artifact/net.ttddyy.observation/datasource-micrometer-spring-boot). + +```xml + + net.ttddyy.observation + datasource-micrometer-spring-boot + 1.0.3 + +``` + +You must also add the following to your applications `application.yaml` file. + +```yaml +spring: + application: + name: customer + +management: + endpoint: + health: + show-details: always + endpoints: + web: + exposure: + include: "*" + metrics: + tags: + application: ${spring.application.name} + tracing: + sampling: + probability: 1.0 + info: + os: + enabled: true + env: + enabled: true + java: + enabled: true + otlp: + tracing: + endpoint: ${otel.exporter.otlp.endpoint} +``` ## View Application Traces in Jaeger Web User Interface +Jaeger is a distributed tracing system used for monitoring and troubleshooting Microservices. For more information on Jaeger, see the [Jaeger website](https://www.jaegertracing.io/). + 1. Expose the Jaeger web user interface using this command: ```shell kubectl -n observability port-forward svc/jaegertracing-query 16686:16686 ``` -2. Open the Jaeger web user interface URL: +1. Open the Jaeger web user interface URL: {{< img name="obaas-jaeger-ui" size="medium" lazy=false >}} -3. In the Jaeger web user interface, click the **Search** tab to find tracings using various search criteria. For example, to find - traces for the customer Microservice included in the Sample Applications: +1. In the Jaeger web user interface, click the **Search** tab to find tracings using various search criteria. For example, to find traces for the customer Microservice included in the Sample Application: + + a. If you deployed the [Sample Applications](../../sample-apps) and have accessed the REST endpoints you can find traces for it in Jaeger. For example: + + b. Select the **Service** `customer32` and the **Operation** `/api/v2/customers` . - a. If you deployed the [Sample Applications](../../sample-apps), exposing the customer service through the Apache APISIX Gateway and - called it at least once, you can find traces for it in Jaeger. - - b. Select the **Service** `customer` and the **Operation** `/api/v1/customers` . - c. Click on **Find Traces**. Several traces appear (one for each time that you invoked the service). {{< img name="obaas-jaeger-customer-tracing" size="medium" lazy=false >}} - d. Click on any one of them to view the trace that includes multiple services and extends into Oracle Database and Oracle - Advanced Queuing. For example: + d. Click on any one of them to view the trace that includes multiple services and extends into Oracle Database. For example: {{< img name="obaas-jaeger-customer-trace-details" size="medium" lazy=false >}} - diff --git a/docs-source/spring/content/observability/tracing/obaas-jaeger-customer-trace-details.png b/docs-source/spring/content/observability/tracing/obaas-jaeger-customer-trace-details.png index 0b2dca88e..a852cc786 100644 Binary files a/docs-source/spring/content/observability/tracing/obaas-jaeger-customer-trace-details.png and b/docs-source/spring/content/observability/tracing/obaas-jaeger-customer-trace-details.png differ diff --git a/docs-source/spring/content/observability/tracing/obaas-jaeger-customer-tracing.png b/docs-source/spring/content/observability/tracing/obaas-jaeger-customer-tracing.png index 43011166f..380557f54 100644 Binary files a/docs-source/spring/content/observability/tracing/obaas-jaeger-customer-tracing.png and b/docs-source/spring/content/observability/tracing/obaas-jaeger-customer-tracing.png differ diff --git a/docs-source/spring/content/observability/tracing/obaas-jaeger-ui.png b/docs-source/spring/content/observability/tracing/obaas-jaeger-ui.png index 1b5f9f807..c33b890ff 100644 Binary files a/docs-source/spring/content/observability/tracing/obaas-jaeger-ui.png and b/docs-source/spring/content/observability/tracing/obaas-jaeger-ui.png differ diff --git a/docs-source/spring/content/observability/tracing/otel-flow-simple.png b/docs-source/spring/content/observability/tracing/otel-flow-simple.png new file mode 100644 index 000000000..049063279 Binary files /dev/null and b/docs-source/spring/content/observability/tracing/otel-flow-simple.png differ diff --git a/docs-source/spring/content/on-premises/_index.md b/docs-source/spring/content/on-premises/_index.md index 921ae5e83..33708968f 100644 --- a/docs-source/spring/content/on-premises/_index.md +++ b/docs-source/spring/content/on-premises/_index.md @@ -1,12 +1,10 @@ --- -title: "On-Premises Installation" +title: "Custom Installations" +description: "Custom installations of Oracle Backend for Spring Boot and Microservices" +keywords: "installation onprem on-premises custom spring springboot microservices development oracle backend" --- -The Oracle Backend for Spring Boot and Microservices is available to install On-Premises. The On-Premises installation includes both a _Desktop_ installation -and an _Estate_ installation. - -The _Desktop_ installation can be used to explore in a non-production environment, while the _Estate_ installation is targeted for the -production infrastructure. +The Oracle Backend for Spring Boot and Microservices is available to install in your own "custom" environment, which may be an on-premises data center environment, a different cloud provider, or a developer's desktop. ## Prerequisites @@ -17,40 +15,39 @@ You must meet the following prerequisites to use the Oracle Backend for Spring B * Access to a Kubernetes cluster * [Python 3+](https://www.python.org/) -When installing on a _Desktop_, the previously mentioned pre-requisites are met through an additional Setup task, but there are additional -desktop system or software requirements. For example: +When installing in a _non-production_ environment, for example a developer's desktop, the previously mentioned pre-requisites may be met through an additional setup task, but there are additional desktop system or software requirements. For example: * 2 CPUs or more * 8 GB of free memory * 60 GB of free disk space (40 GB minikube and container images, 20 GB database) * Internet connection -* [Minikube](https://minikube.sigs.k8s.io/docs/start/) -* [Podman](https://podman.io/getting-started/)[^1] +* [Minikube](https://minikube.sigs.k8s.io/docs/start/) or similar +* [Podman](https://podman.io/getting-started/)[^1] or similar * Oracle Single Sign-On (SSO) account to download the database image ## Download -Download [Oracle Backend for Spring Boot and Microservices](https://github.com/oracle/microservices-datadriven/releases/download/OBAAS-1.0.0/onprem-ebaas_latest.zip). +Download the latest release of [Oracle Backend for Spring Boot and Microservices](https://github.com/oracle/microservices-datadriven/releases/download/OBAAS-1.1.0/onprem-ebaas_latest.zip). ## Setup -An On-Premises installation, whether _Desktop_ or _Estate_, consists of defining the infrastructure followed by running the Configuration +A custom installation, whether production or non-production, consists of defining the infrastructure followed by running the Configuration Management Playbook to build images and deploy the Microservices. -For an _Estate_ installation, you need to have a Kubernetes cluster and the `kubectl` command-line interface must be configured to +For a production installation, you need to have a Kubernetes cluster and the `kubectl` command-line interface must be configured to communicate with your cluster. -A Helper Playbook has been provided for the _Desktop_ installations to assist in defining the infrastructure. Review the -appropriate documentation for examples of installing and defining the _Desktop_ installation. For example: +A Helper Playbook has been provided for non-production installations to assist in defining the infrastructure. Review the +appropriate documentation for examples of installing and defining the non-production installation. For example: * [macOS Ventura (x86)](macos_ventura/_index.md) * [Oracle Linux 8 (x86)](ol8/_index.md) -The _Desktop_ playbook is run as part of the Configuration Management Playbook. +The non-production playbook is run as part of the Configuration Management Playbook. ## Download the Database or Oracle REST Data Services (ORDS) Images (Desktop Installation) -The _Desktop_ installation provisions an Oracle database to the Kubernetes cluster. The images must be downloaded +The non-production installation provisions an Oracle database to the Kubernetes cluster. The images must be downloaded from [Oracle's Container Registry](https://container-registry.oracle.com/) before continuing. After installing Podman, process these steps: @@ -67,7 +64,7 @@ After installing Podman, process these steps: `podman pull container-registry.oracle.com/database/ords:21.4.2-gh` -### Defining the Parse Application (Estate Installation) +### Defining the Parse Application (Production Installation) The application is defined in `ansible/vars/ebaas.yaml`. For example: @@ -90,7 +87,7 @@ oractl_user_password: "Correct-horse-Battery-staple-35" ... ``` -### Defining the Database (Estate Installation) +### Defining the Database (Production Installation) The database is defined in `ansible/roles/database/vars/main.yaml`. For example: @@ -110,7 +107,7 @@ The `oracle_dbs` and `default_db` key values should be the name of your Pluggabl name and Key/Values defining how to access the PDB. If using Mutual Transport Layer Security (mTLS) authentication, specify the full path of the wallet file. -### Defining the Container Repository (Estate Installation) +### Defining the Container Repository (Production Installation) The Container Repository is defined in `ansible/roles/registry/vars/main.yaml`. For example: @@ -153,11 +150,11 @@ and installs Ansible along with other additional modules. For example: source ./activate.env ``` -### Desktop Playbook +### Non-production Playbook -If this is an _Estate_ installation, then the infrastructure should be manually defined as previously stated. +If this is a production installation, then the infrastructure should be manually defined as previously stated. -If this is a _Desktop_ installation, then run the Helper Playbook to define the infrastructure. For example: +If this is a non-production installation, then run the Helper Playbook to define the infrastructure. For example: ```bash ansible-playbook ansible/desktop-apply.yaml @@ -165,7 +162,7 @@ ansible-playbook ansible/desktop-apply.yaml ### Build and Push Images to the Container Repository -For the _Desktop_ installation, start a new terminal and tunnel or port-forward to the Minikube cluster. Refer to the specific platform +For the non-production installation, start a new terminal and tunnel or port-forward to the Minikube cluster. Refer to the specific platform details for more information. For both installations, run the Images Playbook on the original terminal. For example: @@ -182,8 +179,6 @@ Install the Microservices by running this command: ansible-playbook ansible/k8s_apply.yaml -t full ``` -Next, go to the [macOS Ventura](../on-premises/macos_ventura/) page to learn more. - ## Footnotes [^1]: Certification has been performed against Podman. However, other container or virtual machine managers are available and may be diff --git a/docs-source/spring/content/on-premises/macos_ventura/_index.md b/docs-source/spring/content/on-premises/macos_ventura/_index.md index 7c916d2fe..0bd96f3bf 100644 --- a/docs-source/spring/content/on-premises/macos_ventura/_index.md +++ b/docs-source/spring/content/on-premises/macos_ventura/_index.md @@ -1,8 +1,10 @@ --- -title: On-Premises Installation - macOS Ventura (x86) +title: Developer Installation - macOS Ventura (x86) +description: "Custom installation on macOS for Oracle Backend for Spring Boot and Microservices" +keywords: "installation macos ventura nonproduction development on-premises custom spring springboot microservices development oracle backend" --- -This is a discussion of an installation on a macOS Ventura desktop. +This is a discussion of a non-production (developer desktop) installation on a macOS Ventura desktop. Read the [On-Premises](../../on-premises) documentation and ensure that your desktop meets the minimum system requirements. @@ -22,18 +24,18 @@ podman system connection default podman-machine-default-root ### Download the Database or Oracle REST Data Services (ORDS) Images -The _Desktop_ installation provisions an Oracle database into the Kubernetes cluster. The images must be downloaded +The non-production installation provisions an Oracle database into the Kubernetes cluster. The images must be downloaded from [Oracle Cloud Infrastructure Registry (Container Registry)](https://container-registry.oracle.com/) before continuing. -1. Log in to the Container Registry. For example: +1. Log in to the Container Registry. For example: `podman login container-registry.oracle.com` -2. Pull the database image. For example: +2. Pull the database image. For example: `podman pull container-registry.oracle.com/database/enterprise:21.3.0.0` -3. Pull the ORDS image. For example: +3. Pull the ORDS image. For example: `podman pull container-registry.oracle.com/database/ords:21.4.2-gh` @@ -48,13 +50,13 @@ minikube start --cpus 4 --memory max --container-runtime=containerd minikube addons enable ingress ``` -If Minikube fails to start and returns this `Failed kubeconfig update: could not read config` error, process this command and retry: +If Minikube fails to start and returns this `Failed kubeconfig update: could not read config` error, process this command and retry: `mv ~/.kube ~/.kube.bak` ### Download Oracle Backend for Spring Boot and Microservices -Download the [Oracle Backend for Spring Boot and Microservices](https://github.com/oracle/microservices-datadriven/releases/download/OBAAS-1.0.0/onprem-ebaas_latest.zip) and unzip into a new directory. +Download the latest version of [Oracle Backend for Spring Boot and Microservices](https://github.com/oracle/microservices-datadriven/releases/download/OBAAS-1.1.0/onprem-ebaas_latest.zip) and unzip into a new directory. ### Install Ansible @@ -73,7 +75,7 @@ Use the Helper Playbook to define the infrastructure. This Playbook also: * Creates a private Container Registry in the Kubernetes cluster. * Modifies the Microservices application to be desktop compatible. -Run this command: +Run this command: `ansible-playbook ansible/desktop_apply.yaml` @@ -111,6 +113,4 @@ Deploy the database and Microservices by running this command: ## VPN and Proxies -If you are behind a virtual private network (VPN) or proxy, see https://minikube.sigs.k8s.io/docs/handbook/vpn_and_proxy/ for more details -on additional tasks. - +If you are behind a virtual private network (VPN) or proxy, see [minikube VPN or Proxy](https://minikube.sigs.k8s.io/docs/handbook/vpn_and_proxy/) for more details on additional tasks. diff --git a/docs-source/spring/content/on-premises/ol8/_index.md b/docs-source/spring/content/on-premises/ol8/_index.md index 1207d38cb..717303548 100644 --- a/docs-source/spring/content/on-premises/ol8/_index.md +++ b/docs-source/spring/content/on-premises/ol8/_index.md @@ -1,5 +1,7 @@ --- -title: "On-Premises Installation - Oracle Linux 8 (x86)" +title: "Developer Installation - Oracle Linux 8 (x86)" +description: "Custom installation on Oracle Linux for Oracle Backend for Spring Boot and Microservices" +keywords: "installation ol oraclelinux nonproduction development onprem custom spring springboot microservices development oracle backend" --- This is an description of installing on a Oracle Linux 8 desktop. @@ -20,7 +22,7 @@ useradd obaas ### Download Oracle Backend for Spring Boot and Microservices -Download [Oracle Backend for Spring Boot](https://github.com/oracle/microservices-datadriven/releases/download/OBAAS-1.0.1/onprem-ebaas_latest.zip) and unzip into a new directory. +Download the latest version of [Oracle Backend for Spring Boot](https://github.com/oracle/microservices-datadriven/releases/download/OBAAS-1.1.0/onprem-ebaas_latest.zip) and unzip into a new directory. As the `obaas` user, run this command: @@ -81,7 +83,7 @@ The remaining steps require **direct login** as the `obaas` user without using ` ### Download the Database or Oracle REST Data Services (ORDS) Images -The _Desktop_ installation provisions an Oracle database into the Kubernetes cluster. The images must be downloaded from [Oracle Cloud Infrastructure Registry (Container Registry)](https://container-registry.oracle.com/) before continuing. +The non-production installation provisions an Oracle database into the Kubernetes cluster. The images must be downloaded from [Oracle Cloud Infrastructure Registry (Container Registry)](https://container-registry.oracle.com/) before continuing. While directly logged into the `obaas` user, process these steps: diff --git a/docs-source/spring/content/platform/_index.md b/docs-source/spring/content/platform/_index.md index 4dd08a3b0..a36331350 100644 --- a/docs-source/spring/content/platform/_index.md +++ b/docs-source/spring/content/platform/_index.md @@ -1,15 +1,19 @@ --- title: "Platform Services" +description: "Platform Services included in Oracle Backend for Spring Boot and Microservices" +keywords: "platform api apisix eureka config workflow vault spring springboot microservices development oracle backend" +Noindex: true --- Oracle Backend for Spring Boot and Microservices includes a number of Spring platform components that provide services to applications deployed to the platform. For more details, read about: - - [API Gateway](./apigw) - - [Service Discovery](./eureka) - - [Configuration](./config) - - [Workflow](./conductor) - - [Spring Admin](./spring-admin) - - [Using the CLI](../development/cli) - - [Vault](./vault/) +- [API Gateway](./apigw) +- [Service Discovery](./eureka) +- [Configuration](./config) +- [Workflow](./conductor) +- [Spring Admin](./spring-admin) +- [Using the CLI](../development/cli) +- [MicroTx](./microtx) +- [Vault](./vault/) diff --git a/docs-source/spring/content/platform/apigw/_index.md b/docs-source/spring/content/platform/apigw/_index.md index 67af83a43..25f724e38 100644 --- a/docs-source/spring/content/platform/apigw/_index.md +++ b/docs-source/spring/content/platform/apigw/_index.md @@ -1,5 +1,7 @@ --- title: "API Gateway" +description: "APISIX Gateway for API management in Oracle Backend for Spring Boot and Microservices" +keywords: "api apisix gateway traffic deployment circuitbreaker spring springboot microservices oracle backend" resources: - name: obaas-apisix-k8s src: "obaas-apisix-k8s.png" @@ -47,8 +49,7 @@ create a secure channel to `service/apisix-dashboard`. Process the following ste * username: `admin` * password: `admin` - **NOTE:** Oracle recommends that you change the default password when you log in the first time. Even though the dashboard is not - accessible externally, Oracle still recommends using strong passwords to maximize security. + **NOTE:** Oracle recommends that you change the default password when you log in the first time. Even though the dashboard is not accessible externally, Oracle still recommends using strong passwords to maximize security. {{< img name="obaas-apisix-login" size="tiny" lazy=false >}} @@ -62,17 +63,16 @@ API Gateway by processing these steps: 1. Create a route to the service. For example: - a. In the Apache APISIX Dashboard, click **Routes** in the menu on the left side. + 1. In the Apache APISIX Dashboard, click **Routes** in the menu on the left side. {{< img name="obaas-apisix-routes" size="medium" lazy=false >}} - b. Click **Create** to create a new route. - - c. Fill out the necessary details (anything not mentioned here can be left at the default value). For example, for the "slow service" - to be included in the [Sample Applications](../../sample-apps), provide these details: - + 1. Click **Create** to create a new route. + + 1. Fill out the necessary details (anything not mentioned here can be left at the default value). For example, for the "slow service" to be included in the [Sample Applications](../../sample-apps), provide these details: + * name = slow * path = /fruit* * method = get, options @@ -80,13 +80,7 @@ API Gateway by processing these steps: * discovery type = eureka * service name = SLOW (note that this is case sensitive, this is the key from the Eureka dashboard) - **NOTE:** The API Gateway is pre-configured with both "Eureka" and "Kubernetes" discovery types. For Eureka, the service name is the key used to - deploy the service in Eureka, which is normally the value from `spring.application.name` in the Spring Boot configuration - file (`src/main/resources/application.yaml`), in uppercase characters. For Kubernetes, the service name is in the - format `namespace/service:port` where `namespace` is the Kubernetes namespace in which the Spring Boot application is deployed, `service` is - the name of the Kubernetes service for that application, and `port` is the name of the port in that service. If you deployed your Spring Boot - application with the Oracle Backend for Spring Boot and Microservices CLI, the port name will be `spring`. For example, an application called `slow-service` deployed - in the `my-apps` namespace would be `my-apps/slow-service:spring`. + **NOTE:** The API Gateway is pre-configured with both "Eureka" and "Kubernetes" discovery types. For Eureka, the service name is the key used to deploy the service in Eureka, which is normally the value from `spring.application.name` in the Spring Boot configuration file (`src/main/resources/application.yaml`), in uppercase characters. For Kubernetes, the service name is in the format `namespace/service:port` where `namespace` is the Kubernetes namespace in which the Spring Boot application is deployed, `service` is the name of the Kubernetes service for that application, and `port` is the name of the port in that service. If you deployed your Spring Boot application with the Oracle Backend for Spring Boot and Microservices CLI, the port name will be `spring`. For example, an application called `slow-service` deployed in the `my-apps` namespace would be `my-apps/slow-service:spring`. {{< img name="obaas-apisix-routes-step1" size="medium" lazy=false >}} @@ -100,7 +94,7 @@ API Gateway by processing these steps: {{< img name="obaas-apisix-routes-step3" size="medium" lazy=false >}}
- + d. Save the route that you created. {{< img name="obaas-apisix-routes-step4" size="medium" lazy=false >}} @@ -126,5 +120,3 @@ API Gateway by processing these steps: ``` You should get "banana" or "fallback fruit is apple" back as the response. - - diff --git a/docs-source/spring/content/platform/conductor/_index.md b/docs-source/spring/content/platform/conductor/_index.md index b950b7b67..c27f1b115 100644 --- a/docs-source/spring/content/platform/conductor/_index.md +++ b/docs-source/spring/content/platform/conductor/_index.md @@ -1,5 +1,7 @@ --- title: "Workflow" +description: "Workflow for microservices orchestration using Netflix OSS Conductor in Oracle Backend for Spring Boot and Microservices" +keywords: "workflow conductor orchestration netflix development spring springboot microservices development oracle backend" resources: - name: conductor_ui_workflows src: "conductor_ui_workflows.png" @@ -21,7 +23,7 @@ Documentation on Conductor can be found here: kubectl port-forward services/conductor-server -n conductor-server 8080:8080 ``` -2. Access the Conductor server UI at this URL: +1. Access the Conductor server UI at this URL: ```shell http://localhost:8080 @@ -31,7 +33,7 @@ Documentation on Conductor can be found here: {{< img name="conductor_server_ui" size="medium" lazy=false >}} -3. Access the Swagger documentation at this URL: +1. Access the Swagger documentation at this URL: ```shell http://localhost:8080/swagger-ui/index.html @@ -46,4 +48,3 @@ Documentation on Conductor can be found here: The API Specification can be found here: * [API Specification](https://conductor.netflix.com/apispec.html) - diff --git a/docs-source/spring/content/platform/config/_index.md b/docs-source/spring/content/platform/config/_index.md index d5be498a5..96362996b 100644 --- a/docs-source/spring/content/platform/config/_index.md +++ b/docs-source/spring/content/platform/config/_index.md @@ -1,5 +1,7 @@ --- title: "Spring Config Server" +description: "Externalized configuration using Spring Config Server in Oracle Backend for Spring Boot and Microservices" +keywords: "config configserver springboot spring development microservices development oracle backend" --- Oracle Backend for Spring Boot and Microservices includes Spring Cloud Config which provides server- and client-side support for externalized configurations in a distributed system. The Spring Cloud Config server provides a central place to manage external properties for applications across all environments. @@ -17,8 +19,17 @@ When building applications using Spring Config Server, the Spring Cloud Config c ```yaml spring: + application: + name: config: - import: optional:configserver:${config.server.url} + import: optional:configserver:${config.server.url} + + cloud: + config: + label: + profile: + username: + password: ``` You also need to add the following dependency to your Spring Boot application `pom.xml`: diff --git a/docs-source/spring/content/platform/eureka/_index.md b/docs-source/spring/content/platform/eureka/_index.md index 9ab57b808..c0b112919 100644 --- a/docs-source/spring/content/platform/eureka/_index.md +++ b/docs-source/spring/content/platform/eureka/_index.md @@ -1,16 +1,14 @@ --- title: "Service Discovery" +description: "Service discovery with Spring Eureka Service Registry in Oracle Backend for Spring Boot and Microservices" +keywords: "service discovery registry eureka springboot spring development microservices oracle backend" resources: - name: obaas-eureka-dashboard src: "obaas-eureka-dashboard.png" title: "Eureka web user interface" --- -Oracle Backend for Spring Boot and Microservices includes the Spring Boot Eureka service registry, which is an application that stores information about -client services or applications. Typically, each Microservice registers with the Eureka server at startup and the Eureka server maintains -a list of all active instances of the service, including their ports and IP addresses. This information can be accessed by other services -using a well-known key. This allows services to interact with each other without needing to know the other addresses at development or -deployment time. +Oracle Backend for Spring Boot and Microservices includes the Spring Boot Eureka service registry, which is an application that stores information about client services or applications. Typically, each Microservice registers with the Eureka server at startup and the Eureka server maintains a list of all active instances of the service, including their ports and IP addresses. This information can be accessed by other services using a well-known key. This allows services to interact with each other without needing to know the other addresses at development or deployment time. ### Access the Eureka Web User Interface @@ -28,9 +26,6 @@ To access the Eureka web user interface, process these steps: {{< img name="obaas-eureka-dashboard" size="medium" lazy=false >}} - * On the web page, you see all of the services registered with Eureka. If you deployed the [sample applications](../../sample-apps), - look for an entry called **SLOW**. The presence of this entry confirms that the application successfully registered itself with the - service registry. - - * You should also see the **CONFIG-SERVER** and **ADMIN-SERVER** applications. These applications are deployed as part of the platform. + * On the web page, you see all of the services registered with Eureka. If you deployed the [sample applications](../../sample-apps), look for an entry called **SLOW**. The presence of this entry confirms that the application successfully registered itself with the service registry. + * You should also see the **CONFIG-SERVER** and **ADMIN-SERVER** applications. These applications are deployed as part of the platform. diff --git a/docs-source/spring/content/platform/microtx/_index.md b/docs-source/spring/content/platform/microtx/_index.md new file mode 100644 index 000000000..add863684 --- /dev/null +++ b/docs-source/spring/content/platform/microtx/_index.md @@ -0,0 +1,46 @@ +--- +title: "MicroTx" +description: "Transaction coordination and data consistency across microservices using MicroTx in Oracle Backend for Spring Boot and Microservices" +keywords: "transactions xz lra tcc microtx consistency coordination orchestration springboot spring development microservices development oracle backend" +--- + +[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 Spring Boot and Microservices 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) + +The [CloudBank sample application](../../#learn-more-try-it-out-with-cloudbank) includes a "Transfer" service which demonstrates how to use MicroTx to implement the Saga pattern using the Eclipse Microprofile Long Running Actions specification. + +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 + 23.4.1 + +``` + +Add the following configuration to your Spring application configuration. The variables in this configuration are automatically injected to your deployment and pods when you use the Oracle Backend for Spring Boot and Microservices CLI or the Visual Studio Code Extension to deploy your application. For example: + +```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. diff --git a/docs-source/spring/content/platform/spring-admin/_index.md b/docs-source/spring/content/platform/spring-admin/_index.md index f2bff8461..9f91b8db1 100644 --- a/docs-source/spring/content/platform/spring-admin/_index.md +++ b/docs-source/spring/content/platform/spring-admin/_index.md @@ -1,5 +1,7 @@ --- title: "Spring Boot Admin" +description: "Using Spring Boot Admin to manage applications in Oracle Backend for Spring Boot and Microservices" +keywords: "admin springboot spring development microservices development oracle backend" resources: - name: obaas-springadmin-apps src: "obaas-springadmin-apps.png" @@ -29,8 +31,7 @@ the applications: * username: `admin` * password: `admin` - **NOTE:** Oracle recommends that you change the default password when you log in for the first time. Even though the dashboard is not - accessible externally, Oracle still recommends using strong passwords to maximize security. + **NOTE:** Oracle recommends that you change the default password when you log in for the first time. Even though the dashboard is not accessible externally, Oracle still recommends using strong passwords to maximize security. {{< img name="obaas-springadmin-apps" size="medium" lazy=false >}} @@ -45,5 +46,3 @@ the applications: {{< img name="obaas-springadmin-svc-details" size="medium" lazy=false >}} - - diff --git a/docs-source/spring/content/platform/vault/_index.md b/docs-source/spring/content/platform/vault/_index.md index 40eafded1..adef22bce 100644 --- a/docs-source/spring/content/platform/vault/_index.md +++ b/docs-source/spring/content/platform/vault/_index.md @@ -1,5 +1,7 @@ --- title: "Vault" +description: "Securing secrets with Vault in Oracle Backend for Spring Boot and Microservices" +keywords: "vault secrets security springboot spring development microservices development oracle backend" resources: - name: vault-login src: "vault-login.png" diff --git a/docs-source/spring/content/platform/vscode-plugin/_index.md b/docs-source/spring/content/platform/vscode-plugin/_index.md index b89702781..81ff28f1f 100644 --- a/docs-source/spring/content/platform/vscode-plugin/_index.md +++ b/docs-source/spring/content/platform/vscode-plugin/_index.md @@ -1,5 +1,7 @@ --- title: "Oracle Backend for Spring Boot and Microservices Visual Studio Code Extension" +description: "Visual Studio Code extension for Oracle Backend for Spring Boot and Microservices" +keywords: "vscode code visualstudio extension springboot spring development microservices development oracle backend" --- **GA 1.0 - October, 2023** diff --git a/docs-source/spring/content/release-notes/_index.md b/docs-source/spring/content/release-notes/_index.md index cfb7c206c..17eac2b3d 100644 --- a/docs-source/spring/content/release-notes/_index.md +++ b/docs-source/spring/content/release-notes/_index.md @@ -1,7 +1,55 @@ --- title: "Release Notes" +description: "Release notes for Oracle Backend for Spring Boot and Microservices including details of additions, updates, deprecations and removals in each release" +keywords: "release notes additions updates deprecations removals springboot spring development microservices development oracle backend" --- +## Version 1.1.0, February 2, 2024 + +Notes: + +* Recommended versions for user applications updated Spring Boot 3.2.x, Java 17 or 21, Spring 6.1 and Spring Cloud 2023.0.0, with limited backwards compatibility for Spring Boot 2.7.x. +* Platform components are updated to Spring Boot 3.2.1 versions and matching Spring Cloud versions. +* A preview of a new "Spring Operations Center" feature is added, including a web user interface and additional Grafana dashboards. +* User Management using the CLI and REST Endpoints. +* Added support for auto-scaling of Spring Boot applications deployed in the platform. +* Changes to the custom installation to allow using existing resources including database, network and Kubernetes. +* Various platform services updated to use Database Resident Connection Pooling to improve performance. +* Improvements to collection of trace data using Open Telemetry, including migration to agentless approach, + uptake of Micrometer, and so on. +* Improvements for Spring Native/GraalVM native image compilation of Spring Boot services. +* Improvements to CLI to support scripting. +* Various components updated to newer releases. +* Bug fixes. + +The following components were added: + +| Component | Version | Description | +|-----------------------------------------|-----------|-------------------------------------------------| +| Oracle Database Observability Exporter | 1.1.2 | Provides observability for the Oracle Database. | +| Metrics server | 0.64 | Source of container resource metrics for Kubernetes built-in autoscaling pipeline | +| Kube State Metrics | 2.10.1 | Collects metrics for the Kubernetes cluster | + +The following components were updated: + +| Component | New Version | Replaced Version | +|-------------------------------------------------------------------------------|---------------|---------------------| +| APISIX API Gateway | 3.8.0 | 3.4.0 | +| Apache Kafka | 3.6.1 | 3.5.1 | +| Coherence Operator | 3.3.2 | 3.2.11 | +| Conductor Server | 3.13.8 | 3.13.2 | +| HashiCorp Vault | 1.15.2 | 1.14.0 | +| Netflix Conductor | 3.13.8 | 3.13.2 | +| OpenTelemetry Collector | 0.91.0 | 0.86.0 | +| Oracle Backend for Spring Boot and Microservices CLI | 1.1.0 | 1.0.1 | +| Oracle Backend for Spring Boot and Microservices Visual Studio Code extension | 1.1.0 | 1.0.1 | +| Oracle Transaction Manager for Microservices (MicroTx) | 23.4.1 | 22.3.2 | +| Spring Authorization Server | 3.2.1 | 2.7.5 | +| Spring Boot Admin dashboard | 3.2.0 | 3.1.3 | +| Spring Cloud Config server | 2023.0.0 | 2022.0.4 | +| Spring Cloud Eureka service registry | 2023.0.0 | 4.0.3 | +| Strimzi-Apache Kafka operator | 0.39.0 | 0.36.1 | + ## Version 1.0.1, November 2, 2023 Notes: diff --git a/docs-source/spring/content/sampleapp/_index.md b/docs-source/spring/content/sampleapp/_index.md new file mode 100644 index 000000000..3f0ce1f64 --- /dev/null +++ b/docs-source/spring/content/sampleapp/_index.md @@ -0,0 +1,9 @@ +--- +title: "Sample Application - CloudBank" +description: "Sample application for Oracle Backend for Spring Boot and Microservices" +keywords: "springboot spring development microservices development oracle backend" +--- + +Oracle provides a sample application called CloudBank that can be used to learn how to use Oracle Backed for Spring Boot and Microservices. + +CloudBank can be accessed [here](http://bit.ly/CloudBankOnOBaaS). diff --git a/docs-source/spring/content/security/_index.md b/docs-source/spring/content/security/_index.md index df8cb88cb..903651843 100644 --- a/docs-source/spring/content/security/_index.md +++ b/docs-source/spring/content/security/_index.md @@ -1,12 +1,14 @@ --- title: "Security" +description: "Security in Oracle Backend for Spring Boot and Microservices" +keywords: "security authentication authorization encryption certificates springboot spring development microservices development oracle backend" --- The Oracle Backend for Spring Boot and Microservices has the following security characteristics: - All access to the database is done using the Mutual Transport Layer Security (mTLS) database wallet. The user name, password, and URL are stored in Kubernetes secrets. -- Accessing the dashboards can only be done using port-forwarding. The passwords for the dashboards are provied by the installer or autogenerated and stored in Kubernetes secrets. +- Accessing the dashboards can only be done using port-forwarding. The passwords for the dashboards are provided by the installer or autogenerated and stored in Kubernetes secrets. - The only "public" exposure is the Apache APISIX Gateway (note that the dashboard is not exposed publicly). diff --git a/docs-source/spring/content/security/azn-server/_index.md b/docs-source/spring/content/security/azn-server/_index.md index b4a67266f..7e877f408 100644 --- a/docs-source/spring/content/security/azn-server/_index.md +++ b/docs-source/spring/content/security/azn-server/_index.md @@ -1,5 +1,7 @@ --- title: "Authentication and Authorization Server" +description: "Authentication and authorization using Spring Authorization Server in Oracle Backend for Spring Boot and Microservices" +keywords: "security authentication authorization springboot spring development microservices development oracle backend" resources: - name: azn-server-arch src: "azn-server-arch.png" diff --git a/docs-source/spring/content/setup/_index.md b/docs-source/spring/content/setup/_index.md index 77c867ed8..97da9ccdf 100644 --- a/docs-source/spring/content/setup/_index.md +++ b/docs-source/spring/content/setup/_index.md @@ -1,5 +1,7 @@ --- title: "Setup" +description: "Setup Oracle Backend for Spring Boot and Microservices" +keywords: "setup install springboot spring development microservices development oracle backend" resources: - name: oci-private-templates src: "oci-private-templates.png" @@ -109,7 +111,7 @@ Oracle Backend for Spring Boot and Microservices setup installs the following co | NGINX Ingress Controller | 1.8.1 | Provides traffic management solution for cloud‑native applications in Kubernetes. | | Prometheus | 2.40.2 | Provides event monitoring and alerts. | | Prometheus Operator | 0.63.0 | Provides management for Prometheus monitoring tools. | -| OpenTelemetry Collector | 0.86.0 | Collects process and export telemetry data. | +| OpenTelemetry Collector | 0.90.0 | Collects process and export telemetry data. | | Grafana | 9.2.5 | Provides the tool to examine, analyze, and monitor metrics. | | Jaeger Tracing | 1.45.0 | Provides distributed tracing system for monitoring and troubleshooting distributed systems. | | Apache APISIX | 3.4.0 | Provides full lifecycle API management. | diff --git a/docs-source/spring/content/starters/_index.md b/docs-source/spring/content/starters/_index.md index 91e320f50..ec76e9666 100644 --- a/docs-source/spring/content/starters/_index.md +++ b/docs-source/spring/content/starters/_index.md @@ -1,5 +1,7 @@ --- title: "Oracle Spring Boot Starters" +description: "Spring Boot Starters for Oracle Database" +keywords: "starter springboot spring development microservices development oracle database" --- Oracle provides a number of Spring Boot Starters that make it easy to use various Oracle technologies in Spring Boot projects. diff --git a/docs-source/spring/content/starters/aqjms.md b/docs-source/spring/content/starters/aqjms.md index ce1738917..a2754a298 100644 --- a/docs-source/spring/content/starters/aqjms.md +++ b/docs-source/spring/content/starters/aqjms.md @@ -1,5 +1,7 @@ --- title: "Oracle Spring Boot Starter for AQ/JMS" +description: "Spring Boot Starters for Advanced Queueing, Transactional Event Queues using JMS in Oracle Database" +keywords: "starter springboot jms aq txeventq queueing messaging asynchronous spring development microservices development oracle database" --- This starter provides support for Oracle Transactional Event Queues (TxEventQ) and Oracle Advanced Queuing (AQ) @@ -22,7 +24,7 @@ To add this starter to your project, add this Maven dependency: For Gradle projects, add this dependency: -``` +```gradle implementation 'com.oracle.database.spring:oracle-spring-boot-starter-aqjms:23.4.0' ``` @@ -62,27 +64,27 @@ import org.springframework.jms.support.converter.MessageType; @EnableJms public class JmsSampleApplication { - @Bean - public JmsListenerContainerFactory myFactory(ConnectionFactory connectionFactory, - DefaultJmsListenerContainerFactoryConfigurer configurer) { - DefaultJmsListenerContainerFactory factory = new DefaultJmsListenerContainerFactory(); - // This provides all Boot's defaults to this factory, including the message converter - configurer.configure(factory, connectionFactory); - // You could override some of Boot's defaults here if necessary - return factory; - } + @Bean + public JmsListenerContainerFactory myFactory(ConnectionFactory connectionFactory, + DefaultJmsListenerContainerFactoryConfigurer configurer) { + DefaultJmsListenerContainerFactory factory = new DefaultJmsListenerContainerFactory(); + // This provides all Boot's defaults to this factory, including the message converter + configurer.configure(factory, connectionFactory); + // You could override some of Boot's defaults here if necessary + return factory; + } - @Bean - public MessageConverter jacksonJmsMessageConverter() { - MappingJackson2MessageConverter converter = new MappingJackson2MessageConverter(); - converter.setTargetType(MessageType.TEXT); - converter.setTypeIdPropertyName("_type"); - return converter; - } + @Bean + public MessageConverter jacksonJmsMessageConverter() { + MappingJackson2MessageConverter converter = new MappingJackson2MessageConverter(); + converter.setTargetType(MessageType.TEXT); + converter.setTypeIdPropertyName("_type"); + return converter; + } - public static void main(String[] args) { - ConfigurableApplicationContext context = SpringApplication.run(JmsSampleApplication.class, args); - } + public static void main(String[] args) { + ConfigurableApplicationContext context = SpringApplication.run(JmsSampleApplication.class, args); + } } ``` @@ -123,4 +125,3 @@ details for the Oracle Database hosting the queues and topics. If you wish to u configuration, you must use a named configuration, for example `spring.datasource.txeventq` and use Java configuration (as shown for the [UCP starter](./ucp)) and annotate the configuration with the standard Spring `@Qualifier` annotation, specifying the correct name, for example `txevevntq`. - diff --git a/docs-source/spring/content/starters/ucp.md b/docs-source/spring/content/starters/ucp.md index 1eca29f25..86a469543 100644 --- a/docs-source/spring/content/starters/ucp.md +++ b/docs-source/spring/content/starters/ucp.md @@ -1,5 +1,7 @@ --- title: "Oracle Spring Boot Starter for Universal Connection Pool" +description: "Spring Boot Starters for Universal Connection Pooling with Oracle Database" +keywords: "starter ucp oracle database springboot spring development microservices development" --- This starter provides a connection (data source) to an Oracle Database using Universal Connection Pool, which provides an efficient way @@ -17,7 +19,7 @@ To add this starter to your project, add this Maven dependency: For Gradle projects, add this dependency: -``` +```gradle implementation 'com.oracle.database.spring:oracle-spring-boot-starter-ucp:23.4.0' ``` diff --git a/docs-source/spring/content/starters/wallet.md b/docs-source/spring/content/starters/wallet.md index b618cb5c0..026c6cf42 100644 --- a/docs-source/spring/content/starters/wallet.md +++ b/docs-source/spring/content/starters/wallet.md @@ -1,5 +1,7 @@ --- title: "Oracle Spring Boot Starter for Wallet" +description: "Spring Boot Starters for Oracle Database Wallet" +keywords: "starter wallet mtls oracle database springboot spring development microservices development" --- This starter provides support for wallet-based authentication for Oracle Database connections. It depends @@ -17,14 +19,14 @@ To add this starter to your project, add this Maven dependency: For Gradle projects, add this dependency: -``` +```gradle implementation 'com.oracle.database.spring:oracle-spring-boot-starter-wallet:23.4.0' ``` You need to provide the wallet to your application. You can specify the location in the `spring.datasource.url` as shown in the following example. -``` +```text jdbc:oracle:thin:@mydb_tp?TNS_ADMIN=/oracle/tnsadmin ``` diff --git a/docs-source/spring/content/uninstall/_index.md b/docs-source/spring/content/uninstall/_index.md index 686c9cea2..71de8cfce 100644 --- a/docs-source/spring/content/uninstall/_index.md +++ b/docs-source/spring/content/uninstall/_index.md @@ -1,6 +1,7 @@ --- title: "Uninstall" -description: Uninstall the Oracle BaaS from tenancy" +description: "Uninstall Oracle Backend for Spring Boot and Microservices" +keywords: "uninstall backend oracle springboot spring development microservices database" resources: - name: oci-stack-destroy src: "oci-stack-destroy.png" @@ -30,5 +31,3 @@ The OCI Resource Manager uses the stack definition to destroy all resources. For The destroy job takes about 20 minutes to complete. Review the logs when the job is done to ensure that it completed successfully. If there are any errors, run the **Destroy** job again. - - diff --git a/docs-source/spring/data/menu/main.yaml b/docs-source/spring/data/menu/main.yaml index 915665f7f..8c38d286c 100644 --- a/docs-source/spring/data/menu/main.yaml +++ b/docs-source/spring/data/menu/main.yaml @@ -3,7 +3,7 @@ main: ref: "/setup" - name: "Multi-Cloud (OCI/Azure) Installation" ref: "/azure" - - name: "On-Premises Installation" + - name: "Custom Installations" ref: "/on-premises" sub: - name: "MacOS Ventura (x86)" @@ -29,6 +29,8 @@ main: ref: "/platform/spring-admin" - name: OBaaS CLI ref: "/development/cli" + - name: MicroTx + ref: "/platform/microtx" - name: Vault ref: "/platform/vault" - name: VS Code plugin @@ -52,6 +54,8 @@ main: ref: "/development/setup" - name: Project Structure ref: "/development/project" + - name: Predefined Variables + ref: "/development/envvars" - name: Spring Boot Starters ref: "/starters" sub: @@ -65,6 +69,8 @@ main: ref: "/database" - name: Kubernetes Access ref: "/cluster-access" + - name: "Sample Application" + ref: "/sampleapp" - name: Uninstall ref: "/uninstall" - name: "Release Notes" diff --git a/docs-source/spring/themes/hugo-geekdoc/layouts/partials/head/meta.html b/docs-source/spring/themes/hugo-geekdoc/layouts/partials/head/meta.html index 4cc4ddb44..e99d43b4b 100644 --- a/docs-source/spring/themes/hugo-geekdoc/layouts/partials/head/meta.html +++ b/docs-source/spring/themes/hugo-geekdoc/layouts/partials/head/meta.html @@ -12,3 +12,17 @@ {{- with $keywords }} {{- end }} + +{{ if .Page.Params.Noindex }} + +{{ else }} + +{{ end }} + + + + + + + +