diff --git a/docs-source/site/docs/deploy/_category_.json b/docs-source/site/docs/deploy/_category_.json new file mode 100644 index 000000000..3b6432ee8 --- /dev/null +++ b/docs-source/site/docs/deploy/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Deploy", + "position": 2, + "link": { + "type": "generated-index", + "description": "Deploy applications to OBaaS." + } +} diff --git a/docs-source/site/docs/deploy/buildapp.md b/docs-source/site/docs/deploy/buildapp.md new file mode 100644 index 000000000..28a56f492 --- /dev/null +++ b/docs-source/site/docs/deploy/buildapp.md @@ -0,0 +1,15 @@ +--- +title: Build and Deploy the application +sidebar_position: 2 +--- +## Build and Deploy the application + +:::important +This content is TBD +::: + +These are the steps to deploy the application to ak8s cluster using Helm. + +- Obtain the deployment Helm chart from [here](hhtp://where) +- Edit `Values.yaml` to refelct your application +- Install the Helm chart. diff --git a/docs-source/site/docs/deploy/deployapp.md b/docs-source/site/docs/deploy/deployapp.md new file mode 100644 index 000000000..ebc93961d --- /dev/null +++ b/docs-source/site/docs/deploy/deployapp.md @@ -0,0 +1,9 @@ +--- +title: Deploy the Application +sidebar_position: 4 +--- +## Deploy the application + +:::important +This content is TBD +::: diff --git a/docs-source/site/docs/deploy/introflow.md b/docs-source/site/docs/deploy/introflow.md new file mode 100644 index 000000000..d02adb94b --- /dev/null +++ b/docs-source/site/docs/deploy/introflow.md @@ -0,0 +1,31 @@ +--- +title: Introduction and Installation Flow +sidebar_position: 1 +--- +## Introduction and Installation flow + +:::important +This content is TBD +::: + +This guide explains how to deploy an application to OBaaS using Eclipse [Eclipse JKube](https://eclipse.dev/jkube/) to build and push a container image, and Helm to install and configure the application on a Kubernetes cluster. + +### Prerequisites + +- Access to a container image repository (e.g., OCIR or another approved registry). +- Kubernetes cluster access with the correct context set. +- Helm installed locally. +- Maven build configured for your project. + +### High Level Installation Flow + +Too deploy an application to OBaaS, you will follow this high-level flow: + +- Obtain Image Repository metadata or Create the repository needed for the deployment. +- Add [Eclipse JKube](https://eclipse.dev/jkube/) to the pom.xml file. +- Build the Application using Maven. +- Obtain the deployment Helm chart. +- If you're using a database, create a secret with database credentials etc. +- Create the database application user using the 'sqljob.yaml' file. **Add to Helm dir with 'if' statement** +- Edit the `Chart.yaml` file to reflect the application name. +- Install the Helm chart. diff --git a/docs-source/site/docs/deploy/sqljob.md b/docs-source/site/docs/deploy/sqljob.md new file mode 100644 index 000000000..306b33050 --- /dev/null +++ b/docs-source/site/docs/deploy/sqljob.md @@ -0,0 +1,23 @@ +--- +title: Run the SQL Job +sidebar_position: 3 +--- +## Run the SQL Job + +:::important +This content is TBD +::: + +:::note +This step is only necessary if your application is connecting to a database. +::: + +Open the `sqljob.yaml` file and edit the section ..... + +Execute `kubectl -f sqljob.yaml`. You can verify that the job executed properly by running the following commands (get the pod, look at the log) `l log -n .... ` + +```log +asdasd +asdasd +asd +``` diff --git a/docs-source/site/docs/intro.md b/docs-source/site/docs/intro.md index 960e12394..545a103c4 100644 --- a/docs-source/site/docs/intro.md +++ b/docs-source/site/docs/intro.md @@ -5,5 +5,3 @@ sidebar_position: 1 # Oracle Backend for Microservices and AI Oracle Backend for Microservices and AI allows developers to build microservices in Helidon and/or Spring Boot and provisions a “backend as a service” with Oracle Database and other infrastructure components that operate on multiple clouds. Oracle Backend for Microservices and AI vastly simplifies the task of building, testing, and operating microservices platforms for reliable, secure, and scalable enterprise applications. - -**Content TBD** diff --git a/docs-source/site/docs/platform/_category_.json b/docs-source/site/docs/platform/_category_.json new file mode 100644 index 000000000..52718fc1c --- /dev/null +++ b/docs-source/site/docs/platform/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Platform Services", + "position": 3, + "link": { + "type": "generated-index", + "description": "Oracle Backend for Microservices and AI includes a number of Spring platform components that provide services to applications deployed to the platform." + } +} diff --git a/docs-source/site/docs/platform/platform.md b/docs-source/site/docs/platform/platform.md new file mode 100644 index 000000000..46ae84f74 --- /dev/null +++ b/docs-source/site/docs/platform/platform.md @@ -0,0 +1,8 @@ +--- +title: Platform Services +sidebar_position: 1 +--- + +:::important +This content is TBD +::: diff --git a/docs-source/site/docs/setup/_category_.json b/docs-source/site/docs/setup/_category_.json index e084110a3..4ff3b5556 100644 --- a/docs-source/site/docs/setup/_category_.json +++ b/docs-source/site/docs/setup/_category_.json @@ -3,6 +3,6 @@ "position": 1, "link": { "type": "generated-index", - "description": "OBaaS setup and installation." + "description": "Oracle Backend for Microservices and AI (OBaaS) setup and installation." } } diff --git a/docs-source/site/docs/setup/database.md b/docs-source/site/docs/setup/database.md new file mode 100644 index 000000000..8b136d8c7 --- /dev/null +++ b/docs-source/site/docs/setup/database.md @@ -0,0 +1,64 @@ +--- +title: Prepare and Install the OBaaS Database Helm chart +sidebar_position: 9 +--- +## Prepare and Install the OBaaS Database Helm chart + +For this step, you will need the **obaas-db** directory in which you will see the following files: + +```bash +cd obaas-db/ +ls +Chart.yaml scripts templates values.yaml +``` + +You must edit the **values.yaml** file as follows: + +- If you are using a private repository, you must update each **image** entry to point to your private repository instead of the public repositories. + +- You must update the values in the **database.oci_config** section as follows: + + - The **oke** setting must be **false**. Setting this to true is not supported in 2.0.0-M3. + + - Supply your **tenancy**, **user** ocid, **fingerprint** and **region**. These must match the details you provided when you created the OCI configuration secret earlier. This information can be found in the OCI configuration file. + +- (Optional) If you want to install any components in this chart into their own separate namespace, you can override the global namespace by setting a value in the **namespace** property inside the section for that component. + +**Important note**: Please pause to double check all of the values are correct. If there are any errors here, the database provisioning will fail. + +Install the Helm chart using the following command: + +```bash +helm --debug install obaas-db --set global.obaasName="obaas-dev" --set global.targetNamespace="obaas-dev" ./ +NAME: obaas-db +LAST DEPLOYED: Sun Aug 17 13:09:20 2025 +NAMESPACE: default +STATUS: deployed +REVISION: 1 +TEST SUITE: None +``` + +When the installation has completed, you can use `helm ls` command to view the installed charts: + +```text +NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION +obaas-db default 1 2025-09-12 13:51:23.751199 -0500 CDT deployed OBaaS-db-0.1.0 2.0.0-M3 +obaas-observability default 1 2025-09-12 13:45:43.113298 -0500 CDT deployed OBaaS-observability-0.1.0 2.0.0-M3 +obaas-prereqs default 1 2025-09-12 13:37:16.026781 -0500 CDT deployed OBaaS-Prerequisites-0.0.1 2.0.0-M3 +``` + +If you overrode the namespace for this component, you will see a new namespace called **oracle-database-operator-system** (for example) and the following pods. Otherwise the pods will be in the **obaas-dev** namespace (or whatever name you chose). + +![DB Operator pods](media/image6.png) + +**Note**: If you are installing multiple OBaaS instances in your cluster, each one MUST have a different release name, `obaasName` and `targetNamespace`. For example: + +```bash +# for obaas-dev: +helm install obaas-db --set global.obaasName="obaas-dev" +--set global.targetNamespace="obaas-dev" ./ + +# for obaas-prod +helm install obaas-prod-db --set global.obaasName="obaas-prod" +--set global.targetNamespace="obaas-prod" ./ +``` diff --git a/docs-source/site/docs/setup/go-runtime.md b/docs-source/site/docs/setup/go-runtime.md deleted file mode 100644 index 57654a464..000000000 --- a/docs-source/site/docs/setup/go-runtime.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Installing OBaaS -sidebar_position: 1 ---- - -**Content TBD** diff --git a/docs-source/site/docs/setup/media/image6.png b/docs-source/site/docs/setup/media/image6.png new file mode 100644 index 000000000..b06eda3ef Binary files /dev/null and b/docs-source/site/docs/setup/media/image6.png differ diff --git a/docs-source/site/docs/setup/namespace.md b/docs-source/site/docs/setup/namespace.md new file mode 100644 index 000000000..e169729d2 --- /dev/null +++ b/docs-source/site/docs/setup/namespace.md @@ -0,0 +1,18 @@ +--- +title: Create Namespace(s) for OBaaS +sidebar_position: 6 +--- +## Create the namespace(s) for the OBaaS installation(s) + +EACH instance of OBaaS must be installed in its own dedicated/unique namespace. + +**Note**: You will only install the **obaas-prereqs** chart once per cluster, all other charts are installed once per OBaaS instance. The **obaas-prereqs** chart contains items that are cluster-wide and shared by all OBaaS instances in a cluster. If you are going to install multiple OBaaS instances (which is not supported in 2.0.0-M3) we recommend that you put the **obaas-prereqs** chart in its own namespace, separate from all OBaaS instances. + +To create the namespace(s), use the following command(s). For example, to create two installations called `obaas-dev` and `obbas-prod`: + +```bash +kubectl create ns obaas-dev +kubectl create ns obaas-prod +``` + +Change the value to the desired name(s). diff --git a/docs-source/site/docs/setup/obaas.md b/docs-source/site/docs/setup/obaas.md new file mode 100644 index 000000000..7a1db57ce --- /dev/null +++ b/docs-source/site/docs/setup/obaas.md @@ -0,0 +1,101 @@ +--- +title: Prepare and Install the OBaaS Helm chart +sidebar_position: 10 +--- +## Prepare and Install the OBaaS Helm chart + +For this step, you will need the **obaas** directory in which you will see the following files: + +```bash +cd obaas/ +ls +Chart.yaml LICENSE README.md crds templates values.yaml +``` + +You must edit the **values.yaml** file as follows: + +- If you are using a private repository, you must update each **image** entry to point to your private repository instead of the public repositories. + +- Optional. Each component listed in the file (e.g., apisix, kafka, coherence, etc.) has an **enabled: true** entry. If you want to omit a component, you must change the setting to **false**. + +- (Optional) If you want to install any components in this chart into their own separate namespace, you can override the global namespace by setting a value in the **namespace** property inside the section for that component. + +- You must provide the OCID of your ADB-S instance in the setting **database.oci_db.ocid.** + +- You must update the values in the **database.oci_config** section as follows: + + - The **oke** setting must be **false**. Setting this to true is not supported in 2.0.0-M3. + + - Supply your **tenancy**, **user** **ocid**, **fingerprint** and **region**. These must match the details you provided when you created the OCI configuration secret earlier. + +**Important note**: Please pause to double check all of the values are correct. If there are any errors here, the OBaaS provisioning will fail. + +Install the Helm chart using the following command: + +```bash +helm --debug install obaas --set global.obaasName="obaas-dev" --set global.targetNamespace="obaas-dev" ./ +I0817 13:21:41.363368 5981 warnings.go:110\] "Warning: unknown field +"spec.serviceName"" +I0817 13:21:41.439521 5981 warnings.go:110\] "Warning: unknown field +"spec.serviceName"" +I0817 13:21:41.439531 5981 warnings.go:110\] "Warning: unknown field +"spec.serviceName"" +NAME: obaas +LAST DEPLOYED: Sun Aug 17 13:21:15 2025 +NAMESPACE: default +STATUS: deployed +REVISION: 1 +TEST SUITE: None +``` + +You may see some warnings, as shown above, and they can be ignored in 2.0.0-M3. + +If you overrode the component namespaces, you will now see several new namespaces as requested (see example below). Otherwise all of the pods will be in the **obaas-dev** namespace (or whatever name you chose): + +```bash +kubectl get ns +NAME STATUS AGE +admin-server Active 32s +apisix Active 32s +application Active 32s +azn-server Active 32s +cert-manager Active 33m +coherence Active 32s +conductor-server Active 32s +config-server Active 32s +default Active 107m +eureka Active 32s +external-secrets Active 33m +ingress-nginx Active 34m +kafka Active 32s +kube-node-lease Active 107m +kube-public Active 107m +kube-state-metrics Active 33m +kube-system Active 107m +metrics-server Active 33m +obaas-admin Active 32s +observability Active 22m +oracle-database-exporter Active 32s +oracle-database-operator-system Active 12m +otmm Active 32s +``` + +And many new pods. Note that these will take about 5 minutes for them all to get to ready/running status: + +```bash +kubectl get pod -A +``` + +**Note**: If you are installing multiple OBaaS instances in your cluster, each one MUST have a different release name, `obaasName` and `targetNamespace`. For example: + +```bash +# for obaas-dev: +helm install obaas --set global.obaasName="obaas-dev" +--set global.targetNamespace="obaas-dev" ./ + +# for obaas-prod +helm install obaas-prod --set global.obaasName="obaas-prod" +--set global.targetNamespace="obaas-prod" ./ +``` + +**Note**: You MUST set different host names and/or ports for the APISIX ingress if you choose to install APISIX in both instances. diff --git a/docs-source/site/docs/setup/observability.md b/docs-source/site/docs/setup/observability.md new file mode 100644 index 000000000..79643a501 --- /dev/null +++ b/docs-source/site/docs/setup/observability.md @@ -0,0 +1,73 @@ +--- +title: Prepare and Install the OBaaS Observability Helm Chart +sidebar_position: 8 +--- +## Prepare and Install the OBaaS Observability Helm Chart + +**Note**: This step is **optional**. + +For this step, you will need the **obaas-observability** directory in +which you will see the following files: + +```bash +cd obaas-observability/ +ls +Chart.yaml LICENSE README.md admin dashboards templates values.yaml +``` + +You must edit the **values.yaml** file as follows: + +- If you are using a private repository, you must update each + **image** entry to point to your private repository instead of the + public repositories. + +- (Optional) If you want to install any components in this chart into + their own separate namespace, you can override the global namespace + by setting a value in the **namespace** property inside the section + for that component. + +Install the Helm chart using the following command: + +```bash +helm install obaas-observability --set global.obaasName="obaas-dev" +--set global.targetNamespace="obaas-dev" ./ +NAME: obaas-observability +LAST DEPLOYED: Sun Aug 17 13:00:00 2025 +NAMESPACE: default +STATUS: deployed +REVISION: 1 +TEST SUITE: None +``` + +When the installation has completed, you can use this command to view the installed charts: + +```bash +helm ls +``` + +```text +NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION +obaas default 1 2025-09-12 13:57:55.859836 -0500 CDT deployed OBaaS-0.0.1 2.0.0-M3 +obaas-db default 1 2025-09-12 13:51:23.751199 -0500 CDT deployed OBaaS-db-0.1.0 2.0.0-M3 +obaas-observability default 1 2025-09-12 13:45:43.113298 -0500 CDT deployed OBaaS-observability-0.1.0 2.0.0-M3 +``` + +If you overrode the namespace, you will see a new namespace, e.g., **observability**, and the following pods. Otherwise these pods will be in the **obaas-dev** namespace (of whatever name you chose). Note that it will take 5 to 10 minutes for all of these to reach ready/running status: + +```bash +kubectl get pods --n observability # or whatever namespace name you chose +``` + +Please wait for all of the pods to be ready before continuing to the next step. + +**Note**: If you are installing multiple OBaaS instances in your cluster, each one MUST have a different release name, `obaasName` and `targetNamespace`. For example: + +```bash +# for obaas-dev: +helm --debug install obaas-observability --set global.obaasName="obaas-dev" +--set global.targetNamespace="obaas-dev" ./ + +# for obaas-prod +helm --debug install obaas-prod-observability --set global.obaasName="obaas-prod" +--set global.targetNamespace="obaas-prod" ./ +``` diff --git a/docs-source/site/docs/setup/obtaining.md b/docs-source/site/docs/setup/obtaining.md new file mode 100644 index 000000000..c713f3713 --- /dev/null +++ b/docs-source/site/docs/setup/obtaining.md @@ -0,0 +1,25 @@ +--- +title: Obtaining installation package +sidebar_position: 3 +--- +## Obtaining the Installation Package + +The installation package is in the [helm](http://tbd) directory which contains the following directories: + +```text +. +├── obaas +├── obaas-db +├── obaas-observability +└── obaas-prereqs +``` + +Each of these directories contains a helm chart. In this milestone release, there are four helm charts: + +- **OBaaS Prerequisites** This chart contains components that are installed at the cluster level and would be shared by all OBaaS installations in a cluster. This chart can only be installed once per cluster. + +- **OBaaS Database**. This chart contains components that manage the OBaaS Database. + +- **OBaaS Observability**. This chart contains components for the option OBaaS observability stack (based on SigNoz). + +- **OBaaS**. This chart contains the remaining components of OBaaS, most notably the OBaaS Platform Services (like Eureka, Spring Config Server, Admin Server, etc.) diff --git a/docs-source/site/docs/setup/prereq-chart.md b/docs-source/site/docs/setup/prereq-chart.md new file mode 100644 index 000000000..97916ccb8 --- /dev/null +++ b/docs-source/site/docs/setup/prereq-chart.md @@ -0,0 +1,112 @@ +--- +title: Prepare then install OBaaS Prerequisites Helm chart +sidebar_position: 7 +--- +## Prepare then install OBaaS Prerequisites Helm chart + +For this step, you will need the **obaas-prereqs** directory, which contains the following files: + +```bash +cd obaas-prereqs/ +ls +Chart.yaml LICENSE README.md templates values.yaml +``` + +You must edit the **values.yaml** file as follows: + +- If you are using a private repository, you must update each + **image** entry to point to your private repository instead of the + public repositories. + +- Optional. Each component listed in the file (e.g., + kube-state-metrics, metrics-server, cert-manager, etc.) has an + **enabled: true** entry. If you want to omit a component, you must + change the setting to **false**. Please note the following + limitations: + + - Metrics-server is required if you wish to use the Horizontal Pod + Autoscaling feature. + + - Cert-manager is required. + +Choose a name for this OBaaS installation. In this document, we use **obaas-dev** as the name. Please note that the **targetNamespace** should match the namespace you created in the previous step, and that this namespace must already exist. + +Install the Helm chart using the following command: + +```bash +helm --debug install obaas-prereqs ./ +NAME: obaas-prereqs +LAST DEPLOYED: Sun Aug 17 12:47:51 2025 +NAMESPACE: default +STATUS: deployed +REVISION: 1 +TEST SUITE: None +``` + +In this command, note that **obaas-prereqs** is the name of the Helm release. Note that obaas-prereqs is shared across all instances in the cluster, so we recommend that you do NOT set the `obaasName` and `targetNamespace` for this chart/release. + +When the installation has completed, you can use this command to view the installed charts: + +```bash +helm ls +``` + +```text +NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION +obaas-prereqs default 1 2025-09-12 13:37:16.026781 -0500 CDT deployed OBaaS-Prerequisites-0.0.1 2.0.0-M3 +``` + +If you overrode the individual component namespaces, you should now see the requested namespaces have been added (for example see below). Otherwise, all of the pods will be in the **obaas-dev** namespace (or whatever name you chose). + +```bash +kubectl get ns +NAME STATUS AGE +cert-manager Active 3m37s +default Active 77m +external-secrets Active 3m37s +ingress-nginx Active 3m54s +kube-node-lease Active 77m +kube-public Active 77m +kube-state-metrics Active 3m37s +kube-system Active 77m +metrics-server Active 3m37s +``` + +And you should see the following pods running (note that they may take a few minutes to reach running and ready status): + +```bash +kubectl get pods --A +``` + +```text +NAMESPACE NAME READY STATUS RESTARTS AGE +cert-manager cert-manager-7fbd576ffd-tzkmj 1/1 Running 0 45s +cert-manager cert-manager-cainjector-68f4656fdc-hfdw8 1/1 Running 0 45s +cert-manager cert-manager-webhook-5cb89bf75b-h6sdr 1/1 Running 0 45s +external-secrets external-secrets-6687559cc7-5xjbx 1/1 Running 0 45s +external-secrets external-secrets-cert-controller-79785cb877-fjd59 1/1 Running 0 45s +external-secrets external-secrets-webhook-945df75bf-9zjqp 1/1 Running 0 45s +ingress-nginx ingress-nginx-controller-j9bdk 1/1 Running 0 45s +ingress-nginx ingress-nginx-controller-splg7 1/1 Running 0 45s +ingress-nginx ingress-nginx-controller-x2wpz 1/1 Running 0 45s +kube-state-metrics kube-state-metrics-784bc85fd8-9fn5k 1/1 Running 0 45s +kube-system coredns-5b559d56fd-772r7 1/1 Running 0 23h +kube-system coredns-5b559d56fd-m5hx7 1/1 Running 0 23h +kube-system coredns-5b559d56fd-w85nh 1/1 Running 0 23h +kube-system csi-oci-node-6qkgt 1/1 Running 0 23h +kube-system csi-oci-node-h4cnh 1/1 Running 0 23h +kube-system csi-oci-node-qxrqc 1/1 Running 0 23h +kube-system kube-dns-autoscaler-5bbc657c97-gr45f 1/1 Running 0 23h +kube-system kube-proxy-64h2t 1/1 Running 0 23h +kube-system kube-proxy-vcvhn 1/1 Running 0 23h +kube-system kube-proxy-zlzxd 1/1 Running 0 23h +kube-system proxymux-client-52pq8 1/1 Running 0 23h +kube-system proxymux-client-95jzz 1/1 Running 0 23h +kube-system proxymux-client-s54g9 1/1 Running 0 23h +kube-system vcn-native-ip-cni-5lqxn 2/2 Running 0 23h +kube-system vcn-native-ip-cni-chb42 2/2 Running 0 23h +kube-system vcn-native-ip-cni-d7thh 2/2 Running 0 23h +metrics-server metrics-server-77ff598cd8-b8nt8 1/1 Running 0 45s +metrics-server metrics-server-77ff598cd8-bnnld 1/1 Running 0 45s +metrics-server metrics-server-77ff598cd8-t6nx8 1/1 Running 0 45s +``` diff --git a/docs-source/site/docs/setup/prereqs.md b/docs-source/site/docs/setup/prereqs.md new file mode 100644 index 000000000..10dd8b5e4 --- /dev/null +++ b/docs-source/site/docs/setup/prereqs.md @@ -0,0 +1,24 @@ +--- +title: Prerequisites +sidebar_position: 2 +--- +## Prerequisites for Oracle Backend for Microservices and AI + +To install OBaaS 2.0.0-M3, you must meet the following prerequisites: + +- A CNCF-compliant Kubernetes cluster with working storage provider that provides a storage class for RWX PVs, and ingress. Version 1.33.1. At least 3 worker nodes. At least 2 OCPU and 32GB memory per worker node (this allows for ONE installation of OBaaS and some applications. As a general rule of thumb, double the number of worker nodes if you want to install TWO OBaaS instances. You may need more if you want to install additional applications). OKE "quick create/enhanced" cluster recommended. + +- An Oracle Database. Must be version 19c or later. If you want to use the AI features, it must be 23ai. Oracle Autonomous Database 23ai ATP with 2 ECPU and 1TB storage with "secure access from anywhere recommended. + +**Important note:** If your environment does not meet the prerequisites, the installation will fail. Please do not continue with installation until you have confirmed your environment meets the requirements. + +If you use the recommended OKE cluster, your cluster should contain the following namespaces: + +```bash +kubectl get ns +NAME STATUS AGE +default Active 4m52s +kube-node-lease Active 4m52s +kube-public Active 4m52s +kube-system Active 4m52s +``` diff --git a/docs-source/site/docs/setup/secrets.md b/docs-source/site/docs/setup/secrets.md new file mode 100644 index 000000000..7a7204b4f --- /dev/null +++ b/docs-source/site/docs/setup/secrets.md @@ -0,0 +1,208 @@ +--- +title: Create Required Secrets +sidebar_position: 5 +--- +## Create Required Secrets + +You must create a few secrets before starting the installation of Helm charts. These secrets contain authentication information that will be needed by the Helm charts. + +### Image Pull Secrets + +Create an image pull secret to allow pull access to your container repository. This is the repository where application images will be stored. If you are using the recommended OKE, this should be an OCI-R repository in the same compartment and region. This example assumes your tenancy is called **maacloud**, the region **phx.ocir.io** and that your tenancy uses IDCS authentication. Adjust the command to match your tenancy: + +```bash +kubectl create secret generic ocir + --from-literal=host=phx.ocir.io/maacloud + --from-literal=username=maacloud/oracleidentitycloudservice/bob.smith@oracle.com + --from-literal=password="xyz123xyz" + --from-literal=email=bob.smith@oracle.com +``` + +:::important +Your OCI-R password must be an Authentication Token, not the password you use to log into the OCI web console. +::: + +You can validate the token by performing a docker login using this command (with your own username and token): + +```bash +docker login phx.ocir.io + -u maacloud/oracleidentitycloudservice/bob.smith@company.com + -p 'xyz123xyz' +``` + +You can verify your secret using this command: + +```bash +kubectl get secret ocir -o yaml +apiVersion: v1 +data: + email: bWF... + host: cGh... + password: KE4... + username: bWF... +kind: Secret +metadata: + creationTimestamp: "2025-08-17T16:06:14Z" + name: ocir + namespace: default + resourceVersion: "9295" + uid: d5fe5b24-fcf1-42d2-a615-28d299acd645 + type: Opaque +``` + +Note that the values are base64 encoded. + +Create two additional secrets as shown below: + +```bash +kubectl create secret generic obaas-registry-login + --from-literal=registry.username="maacloud/oracleidentitycloudservice/mark.x.nelson@oracle.com" + --from-literal=registry.password="xyz123xyz" + --from-literal=registry.push_url="phx.ocir.io/maacloud/obaas-dev" + +kubectl create secret docker-registry obaas-registry-pull-auth + --docker-server="phx.ocir.io/maacloud" + --docker-username="maacloud/oracleidentitycloudservice/mark.x.nelson@oracle.com" + --docker-password="xyz123xyz" + --docker-email="mark.x.nelson@oracle.com" +``` + +Note that the first secret contains the registry prefix for images that would be created by OBaaS Admin. + +Confirm you have the following secrets before moving on: + +```bash +kubectl get secrets +NAME TYPE DATA AGE +obaas-registry-login Opaque 3 29s +obaas-registry-pull-auth kubernetes.io/dockerconfigjson 1 8s +ocir Opaque 4 13m +``` + +:::note +If you are planning to install multiple OBaaS instances, AND you want to use different private repositories, you need to create a set of these secrets for EACH instance, and they must have different names. +::: + +### OBaaS Password Secrets + +These secrets are used to set the passwords for various OBaaS components. Note that these are not optional in M3. In the final 2.0.0 release, these will be optional, and if you omit them, each component will have a different random password set for it. If you want to use random passwords, see below. + +Create the secrets using these commands: + +```bash +kubectl create secret generic signoz + --from-literal=email="admin@nodomain.com" + --from-literal=password=Welcome-12345 + +kubectl create secret generic clickhouse + --from-literal=username="clickhouse_operator" + --from-literal=password=Welcome-12345 + +kubectl create secret generic alertmanager + --from-literal=username="admin" + --from-literal=password="Welcome-12345" +``` + +To use random passwords, instead of specifying a password as shown above, use this form of the command instead: + +```bash +kubectl create secret generic signoz + --from-literal=email="admin@nodomain.com" + --from-literal=password=\$(openssl rand -base64 16) +``` + +:::note +If you are planning to install multiple OBaaS instances, AND you want to use different passwords, you need to create a set of these secrets for EACH instance, and they must have different names. +::: + +### Database Credentials Secret + +Create a secret to provide OBaaS with the credentials for your database. This example assumes your database is called **demo1**: + +```bash +kubectl create secret generic admin-user-authn + --from-literal=username=ADMIN + --from-literal=password="Welcome-12345" + --from-literal=service="demo1_tp" + --from-literal=dbname="demo1" +``` + +Be careful to get the correct database name and service name, since these will be injected into applications that you deploy using the client side helm chart. + +Verify your secret looks like this: + +```bash +kubectl get secret admin-user-authn -o yaml +apiVersion: v1 +data: + dbname: ZGV\... + password: V2V\... + service: ZGV\... + username: QUR\... +kind: Secret +metadata: + creationTimestamp: "2025-08-17T16:26:20Z" + name: admin-user-authn + namespace: default + resourceVersion: "14755" + uid: b71f045d-c2dc-4b25-ba6a-ab277ec2d00e + type: Opaque +``` + +:::note +If you are planning to install multiple OBaaS instances, AND you want to use different databases, you need to create one of these secrets for EACH instance, and they must have different names. +::: + +### OCI Credentials Secret + +Run the provided script to generate the appropriate command for you from your OCI configuration. Note: You must have a working OCI CLI configured with access to your tenancy and the region where you want to install, on the machine where you run this command. The python script generated a command that you need to execute. to create the key. + +```bash +python3 ./obaas-db/scripts/oci_config.py +echo 'apiVersion: v1 +kind: Secret +metadata: + name: oci-config-file + namespace: default + type: Opaque +data: + config: W0R\... + oci_api_key.pem: LS0\... +' \| kubectl apply -f - +``` + +:::important + +- The Python script reads the OCI config file and looks for the `DEFAULT` entry to determine the private key file. +- The OCI config file can not have more than one profile and needs to be named `DEFAULT`. +- This script requires your key file to be named **oci_api_key.pem** - if your key file has a different name, this script will produce an incorrect secret. In that case you would need to edit the name of the second key to make it **oci_api_key.pem** and update the value of the first key (config) to include that name. To update that value, you need to base64 decode it, update the plaintext, then base64 encode that. + +::: + +Once you have the correct command, run that command to create the secret. Then check your secret looks correct using this command: + +```bash +kubectl get secret oci-config-file -o yaml +apiVersion: v1 +data: + config: W0R\... + oci_api_key.pem: LS0\... +kind: Secret +... +``` + +You should also base64 decode the values to check that they are correct. For example: + +```bash +echo -n "W0R\... " \| base64 -d +[DEFAULT] +user=ocid1.user.oc1..aaaaaaaaxyzxyzxyz +fingerprint=d0:b5:60:bd:27:2b:... +tenancy=ocid1.tenancy.oc1..aaaaaaaaxyzxyzxyz +region=us-phoenix-1 +key_file=/app/runtime/.oci/oci_api_key.pem +``` + +**Important note**: We recommend taking extra care to ensure these are all correct before moving on to the next step. If there are any errors here, the injection of the Database configuration will fail. + +**Note**: If you are planning to install multiple OBaaS instances, AND you want to use different OCI credentials, you need to create one of these secrets for EACH instance, and they must have different names. diff --git a/docs-source/site/docs/setup/setup.md b/docs-source/site/docs/setup/setup.md new file mode 100644 index 000000000..9e090f230 --- /dev/null +++ b/docs-source/site/docs/setup/setup.md @@ -0,0 +1,48 @@ +--- +title: Introduction and Installation Flow +sidebar_position: 1 +--- +## Introduction and Installation flow + +:::important + +The installation flow is **VERY** important, you should follow the steps thoroughly. Do not move on to the next step if you have issues. + +::: + +Oracle Backend for Microservices and AI 2.0.0-M3 is an **internal-only** milestone release. It is not available externally. This release represents a milestone on the path to 2.0.0 -- it is not intended to be a "finished product" so you may encounter some minor issues, and this is expected. Please give feedback to the development team if you find +issues. + +The 2.0.0-M3 release has the following key differences from the previous production release (1.4.0): + +- Installation is performed with Helm instead of Ansible +- You may select which components you wish to install +- You may customize which namespaces you wish to install components into +- You may only install more than one OBaaS instance in a cluster with this release, but see the restrictions below + +Please note the following known issues in M3: + +- Instance principal authentication for OKE worker nodes, which allows the Oracle Database Operator to manage Autonomous Database instances, may not work in this release +- This release has been tested on OKE, it has not been tested on OCNE. + +The next release, 2.0.0-M4 is intended to be available approximately two weeks after M3 and to address some, if not all, of these limitations. + +**Important note:** Make sure that you have the correct kubectl config set. You can do this by exporting the KUBECONFIG variable and pointing to the correct config file. + +### High Level Installation Flow + +To install OBaaS, you will follow this high-level flow: + +- Confirm environment meets prerequisites. +- Create required secrets. +- Create the namespace(s) for the OBaaS installation(s). +- Prepare then install the OBaaS Prerequisites Helm chart and verify (once per cluster). +- These steps would be repeated once for EACH instance of OBaaS to install: + - Optionally prepare then install the OBaaS Observability Helm chart and verify. + - Prepare then install the OBaaS Database Helm chart and verify. + - Prepare then install the OBaaS Helm chart and verify. + - Optionally install the CloudBank sample application and verify. + +**Important note**: If you want to install in an environment that does not have access to public container repositories, you must first obtain the required images and push them into your private repository. + +The script file **private_repo_helper.sh** in the installation package can be used to pull all the required images and push them into your private repository. Note that you may need to run it once while off VPN to allow it to pull the images and ignore push errors. Then run it again on VPN and ignore the pull errors (if any). diff --git a/docs-source/site/docusaurus.config.ts b/docs-source/site/docusaurus.config.ts index 3225badef..5cf67119e 100644 --- a/docs-source/site/docusaurus.config.ts +++ b/docs-source/site/docusaurus.config.ts @@ -5,7 +5,7 @@ import type * as Preset from '@docusaurus/preset-classic'; // This runs in Node.js - Don't use client-side code here (browser APIs, JSX...) const config: Config = { - title: 'Oracle Backend for Microservices and AI', + title: 'Oracle Backend for Microservices and AI -- Draft documentation', tagline: 'Deploy AI microservices using a “backend as a service” with Oracle Database and other infrastructure components', favicon: 'img/favicon-32x32.png', @@ -18,7 +18,7 @@ const config: Config = { url: 'https://oracle.github.io', // Set the // pathname under which your site is served // For GitHub pages deployment, it is often '//' - baseUrl: '/microservices-datadriven/', + baseUrl: '/microservices-datadriven/obaas', // GitHub pages deployment config. // If you aren't using GitHub pages, you don't need these. diff --git a/docs-source/site/src/pages/index.tsx b/docs-source/site/src/pages/index.tsx index 466bc237a..3292534df 100644 --- a/docs-source/site/src/pages/index.tsx +++ b/docs-source/site/src/pages/index.tsx @@ -21,7 +21,7 @@ function HomepageHeader() { - Getting Started Tutorial + Documentation - Draft