Documentation Updates (#834)

* Doc updates

docs-source/spring/content/infrastructure/database/_index.md

@@ -0,0 +1,110 @@
+---
+title: "Database"
+description: "Database Options and Configuration"
+keywords: "database spring springboot microservices oracle"
+
+---
+The Oracle Backend for Spring Boot and Microservices uses the Oracle Database as a persistent data store for metadata and the Spring Cloud Config Server.  This documentation will refer to this database as the **Metadata Database**.
+
+> **NOTE:** Oracle recommends that you install an addition Container Database (CDB) and Pluggable Databases (PDBs) for your production applications inline with the Database-Per-Service pattern.  This document will refer to these databases as the [**Application Database**](#application-databases).  
+
+By default, the Oracle Autonomous Database - Serverless (ADB-S) is used for the  **Metadata Database**, however, there are other options including Bring Your Own (BYO).
+
+The following chart presents the options for the Metadata Database, based on the installation type:
+
+| Installation  | ADB-S | BYO ADB-S  | BYO BaseDB | BYO Containerized | BYO External |
+|---------------|-------|------------|------------|-------------------|--------------|
+| OCI Community | x     |            |            |                   |              |
+| OCI Standard  | x     | x          | x          |                   | x            |
+| Custom        | x     | x          | x          | x                 | x            |
+
+> For **custom installations**, including on-premises, it is the responsibility of the user to ensure network access controls to provide both operational access and security.  The Oracle Cloud Infrastructure (OCI) [Networking](../networking) setup can be used as a general template.
+
+# Bring Your Own Database - Standard Edition
+
+If you select the **Standard Edition** during installation, you can use a pre-created Oracle Database for the Oracle Backend for Spring Boot and Microservices **Metadata Database**.  
+
+The following are the minimum requirements for a BYO Oracle Database:
+
+* Version: 19c+
+* Bring Your Own Network with access to the Database Listener
+* Database User with appropriate privileges (see below)
+
+## Database User Privileges
+
+The database user for the the Oracle Backend for Spring Boot and Microservices **Metadata Database** is used to create other users and allow them to proxy through this user for database access.  While the `SYSTEM` or `ADMIN` (for ADB-S) will work, they are over-privileged and should not be used in production environments.
+
+It is recommended to create a user, in this example, named `OBAAS` with a default tablespace of `DATA`:
+
+```sql
+CREATE USER OBAAS IDENTIFIED BY "Welcome_12345";
+ALTER USER OBAAS QUOTA UNLIMITED ON DATA;
+GRANT ALTER USER TO OBAAS;
+GRANT CREATE USER TO OBAAS;
+GRANT CONNECT TO OBAAS WITH ADMIN OPTION;
+GRANT CREATE SESSION TO OBAAS WITH ADMIN OPTION;
+GRANT RESOURCE TO OBAAS WITH ADMIN OPTION;
+GRANT SELECT ON DBA_USERS TO OBAAS;
+GRANT CREATE ANY INDEX TO OBAAS;
+GRANT ALTER ANY TABLE TO OBAAS;
+GRANT COMMENT ANY TABLE TO OBAAS;
+GRANT CREATE ANY TABLE TO OBAAS;
+GRANT INSERT ANY TABLE TO OBAAS;
+GRANT SELECT ANY TABLE TO OBAAS;
+GRANT UPDATE ANY TABLE TO OBAAS;
+GRANT CREATE ANY SEQUENCE TO OBAAS;
+GRANT SELECT ANY SEQUENCE TO OBAAS;
+GRANT CREATE ANY TRIGGER TO OBAAS;
+-- Additional AQ perms
+GRANT AQ_USER_ROLE TO OBAAS WITH ADMIN OPTION;
+GRANT EXECUTE ON DBMS_AQ TO OBAAS WITH GRANT OPTION;
+GRANT EXECUTE ON DBMS_AQADM TO OBAAS WITH GRANT OPTION;
+GRANT EXECUTE ON DBMS_AQIN TO OBAAS WITH GRANT OPTION;
+GRANT EXECUTE ON DBMS_AQJMS TO OBAAS WITH GRANT OPTION;
+GRANT EXECUTE ON DBMS_AQJMS_INTERNAL TO OBAAS WITH GRANT OPTION;
+-- Additional for PARSE
+GRANT SODA_APP TO OBAAS WITH ADMIN OPTION;
+GRANT CREATE TABLE TO OBAAS WITH ADMIN OPTION;
+```
+
+## Configuration
+
+1. During the configuration of the Oracle Backend for Spring Boot and Microservices, ensure that the **Edition** is set to **Standard**:
+
+    ![Standard Edition](../images/standard_edition.png "Standard Edition")
+
+1. Enable and Configure *Bring Your Own Virtual Network*
+
+1. Tick the "Bring Your Own Database" checkbox and, depending on the *Bring Your Own Database - Type*, provide the appropriate values.
+
+### Autonomous Database - Serverless (ADB-S)
+
+   - `BYO ADB-S Compartment` : The compartment of the existing ADB-S.
+   - `Bring Your Own Database - Autonomous Database` : The ADB-S name (this will automatically translate the name to an OCID).
+   - `Bring Your Own Database - Username` : The existing database user with the appropriate privileges.
+   - `Bring Your Own Database - Password` : The password for the existing database user.
+
+        ![Bring Your Own Database - ADB-S](./images/byo-db-adb-s.png "Bring Your Own Database - ADB-S")
+
+### Other
+
+   - `Bring Your Own Database - Connect String` : The connect string for the database (PDB) in Long Format.
+   - `Bring Your Own Database - Username` : The existing database user with the appropriate privileges.
+   - `Bring Your Own Database - Password` : The password for the existing database user.
+
+        ![Bring Your Own Database - Other](./images/byo-db-other.png "Bring Your Own Database - Other")
+
+   The *Connect String* should be in Long Format, for example:
+   ```bash
+   (DESCRIPTION=(ADDRESS=(host=oracle://somedb.example.com)(protocol=TCP)(port=1521))
+      (CONNECT_DATA=(SERVICE_NAME=orclpdb)))
+   ```
+
+# Application Databases
+
+Oracle recommends that additional pluggable databases are used for your applications, following the database-per-service microservice pattern.  However, the **Metadata Database** can be used, especially for development purposes, with a schema-per-service model.
+
+The [Oracle Database Operator for Kubernetes](https://github.com/oracle/oracle-database-operator) is provided with the Oracle Backend for Spring Boot and Microservices and can be used:
+* Bind to additional ADB-S
+* Bind to an OCI BaseDB and create PDBs
+* Create a Single Instance Container Database in the Kubernetes Cluster

docs-source/spring/content/infrastructure/networking/_index.md

@@ -0,0 +1,131 @@
+---
+title: "Networking"
+description: "Networking Options and Configuration"
+keywords: "network spring springboot microservices oracle"
+---
+The Oracle Backend for Spring Boot and Microservices has specific networking requirements to ensure resource communication while providing security through isolation and networking rules.  
+
+The **standard installation** will provision a new Virtual Cloud Network (VCN) with the required subnets and all networking rules to get you started using the Oracle Backend for Spring Boot and Microservices quickly.  To use an existing VCN, please follow the [Bring Your Own VCN](#bring-your-own-oci-vcn) instructions.
+
+> For **custom installations**, including On-Premises, it is the responsibility of the customer to ensure network access controls to provide both operational access and security.  The Oracle Cloud Infrastructure (OCI) **standard installation** setup can be used as a general template.
+
+# Network Infrastructure Overview
+
+![OCI Network Infrastructure](images/network_infra.png "OCI Network Infrastructure")
+
+## OCI Network Infrastructure
+
+All infrastructure resources are split between two subnets: one public and one private subnet with access restricted by Network Security Groups (Firewalls).  All access is blocked by default with specific IP and port opened, as documented below, for proper operation.
+
+> Note minimum CIDRs are based on an Oracle Cloud Infrastructure (OCI) deployments.  Other cloud vendors reserve usable IPs within a CIDR reducing the usable IPs that can be used by the infrastructure.
+
+### Public Subnet
+
+The public subnet allows external access to the Oracle Backend for Spring Boot and Microservices resources.  Ingress/Egress to the public subnet and from the Internet is provided by an Internet Gateway.
+
+At a minimum, the public subnet requires two usable IP Addresses.  In OCI this equates to a 30-bit network identifier (`/30`).
+
+ICMP traffic is allowed between the public and private Subnets for resource discovery.
+
+> **NOTE**: Resources within the public subnet are not inherently accessible from the internet.  The public subnet *allows* the resources in it to obtain a public IP address, however assigning a public IP is not required.  When a public IP is not assigned to the resource, it is only accessible from within the subnet itself.  All access to resources in the public subnet are restricted by configurable Network Security Groups (Firewalls). 
+
+#### Load Balancer
+
+An external Load Balancer is used in conjunction with Ingress resources to expose Services to the internet.  Ingress to the Load Balancer should be restricted by CIDR and ports (default: `0.0.0.0/0`; `80`,`443`).  All TLS communications terminate at the LoadBalancer.  For more information on the certificate for TLS, please see [OCI Load Balancer TLS Certificate Setup](#oci-loadbalancer-tls-certificate-setup).
+
+#### Kubernetes API Endpoint
+
+The Kubernetes API Endpoint, within the Control Plane, is used to manage the Kubernetes Cluster as well as providing access to Kubernetes services that are not exposed to the Load Balancer via Port Forwarding.  Ingress to the Endpoint is restricted to port `6443` and should be further restricted by CIDR (default: `0.0.0.0/0`).
+
+In Oracle Cloud Infrastructure (OCI), the Oracle Kubernetes Engine (OKE) Control Plane is allowed egress to OCI services via port `443`.  Access to these services are required for the OKE Managed Control Plane.
+
+### Private Subnet
+
+The private subnet isolates its resources from direct external access by prohibiting the allocation of public IP address to those resources.  Ingress to resources in the private subnet is restricted to the Load Balancer and Kubernetes API Endpoint via specific Network Security Group (Firewall) rules.  Optionally, a Bastion Service, within the Private subnet, can provide additional non-restricted access to the resources in the private subnet.
+
+Egress to the Internet is provided by a NAT Gateway, while Egress to other Cloud Services (such as a Container Repository) is provided by a Service Gateway.
+
+The CIDR of the Private Subnet is dependent on the number of Kubernetes Work Nodes and other resources, such as databases.  It is recommended to specify a CIDR providing at least six usable IP Addresses.  In OCI, this equates to a 29-bit network identifier (`/29`).
+
+ICMP traffic is allowed between the public and private subnets for resource discovery. 
+
+#### Kubernetes Worker Nodes
+
+The worker nodes are allowed to communicate with other worker nodes on all ports.
+
+#### Worker Nodes and Load Balancer
+
+The Worker Nodes and Load Balancer are allowed to communicate on port `10256` for Health Check/Availability purposes and ports `30000-32767` for forwarding external internet access to exposed services.
+
+#### Worker Nodes and Kubernetes API Endpoint
+
+Worker Nodes are allowed to communicate with the API Endpoint on port `6443`.
+
+#### Worker Nodes and Control Plane
+
+The Kubernetes Control Plane is allowed to communicate to Worker Nodes on all ports.  The Worker Nodes are allowed to communicate with the Control Plane on port `12250`.
+
+#### Oracle Database
+
+It is recommended to place the Oracle Databases inside the Private Subnet.  Worker Nodes and the Oracle Database will be allowed to communicate freely within the Private Subnet.
+
+When using the Oracle Autonomous Database (ADB), it can either be placed in the Private Subnet with a *Private Endpoint*, or outside the Virtual Cloud Network with *Secured Access*.  When the ADB is configured for *Secured Access*, access is allowed from the Virtual Cloud Network and additional, configurable IPs.
+
+# Bring Your Own OCI VCN
+
+Using the **Standard Edition** you can use a pre-created VCN for the Oracle Backend for Spring Boot and Microservices resources.  
+
+The following are minimum requirements for a BYO VCN:
+
+* *Public Subnet*
+    * Minimum CIDR: `/30`
+    * Route Table:
+        * Internet Gateway to `0.0.0.0/0`
+* *Private Subnet*
+    * Minimum CIDR: `/29`
+    * Route Table:
+        * Service Gateway to "All `<Region>` Services in the Oracle Services Network"
+        * NAT Gateway to `0.0.0.0/0`
+
+## Configuration
+
+During the configuration of the Oracle Backend for Spring Boot and Microservices, ensure that the **Edition** is set to **Standard**:
+
+![Standard Edition](../images/standard_edition.png "Standard Edition")
+
+Tick the "Bring Your Own Virtual Network" checkbox and fill in the appropriate values for the VCN Compartment/Name, Public Subnet Compartment/Name, and Private Subnet Compartment/Name:
+
+   - `Virtual Cloud Network Compartment` : The compartment of the existing VCN.
+   - `Virtual Cloud Network (VCN)` : The VCN name.
+   - `Private Subnet Compartment` : The compartment of the existing Private Subnet in the VCN.
+   - `Private Subnet` : The Private Subnet name (this will automatically translate the name to an OCID).
+   - `Public Subnet Compartment` : The compartment of the existing Public Subnet in the VCN.
+   - `Public Subnet` : The Public Subnet name (this will automatically translate the name to an OCID).
+
+![BYO VCN](images/byo_vcn.png "BYO VCN")
+
+# OCI LoadBalancer TLS Certificate Setup
+
+In OCI, example self-signed certificates are used for TLS communication to the Load Balancer.  The self-signed certificates should be replaced with certificates signed by a publicly trusted certificate authority (CA).
+
+## Setup
+
+1. Ensure your Domain Name System (DNS) entry points to the public IP address associated with the `service/ingress-nginx-controller` in the `ingress-nginx` namespace:
+
+    ![LoadBalancer IP](images/lb_ip.png "LoadBalancer IP")
+
+2. Obtain a new TLS certificate. In a production environment, the most common scenario is to use a public certificate that has been signed by a certificate authority.
+
+3. Create a new Kubernetes secret in the `ingress-nginx` namespace.  For example:
+
+    ```bash
+    kubectl -n ingress-nginx create secret tls my-tls-cert --key new-tls.key --cert new-tls.crt
+    ```
+
+4. Modify the service definition to reference the new Kubernetes secret by changing the `service.beta.kubernetes.io/oci-load-balancer-tls-secret` annotation in the service configuration. For example:
+
+    ```bash
+    kubectl patch service ingress-nginx-controller -n ingress-nginx \
+        -p '{"metadata":{"annotations":{"service.beta.kubernetes.io/oci-load-balancer-tls-secret":"my-tls-cert"}}}' \
+        --type=merge
+    ```