|
| 1 | +<!-- |
| 2 | +Copyright (c) 2025 Oracle and/or its affiliates. |
| 3 | +
|
| 4 | +The Universal Permissive License (UPL), Version 1.0 |
| 5 | +
|
| 6 | +Subject to the condition set forth below, permission is hereby granted to any |
| 7 | +person obtaining a copy of this software, associated documentation and/or data |
| 8 | +(collectively the "Software"), free of charge and under any and all copyright |
| 9 | +rights in the Software, and any and all patent rights owned or freely |
| 10 | +licensable by each licensor hereunder covering either (i) the unmodified |
| 11 | +Software as contributed to or provided by such licensor, or (ii) the Larger |
| 12 | +Works (as defined below), to deal in both |
| 13 | +
|
| 14 | +(a) the Software, and |
| 15 | +(b) any piece of software and/or hardware listed in the lrgrwrks.txt file if |
| 16 | +one is included with the Software (each a "Larger Work" to which the Software |
| 17 | +is contributed by such licensors), |
| 18 | +
|
| 19 | +without restriction, including without limitation the rights to copy, create |
| 20 | +derivative works of, display, perform, and distribute the Software and make, |
| 21 | +use, sell, offer for sale, import, export, have made, and have sold the |
| 22 | +Software and the Larger Work(s), and to sublicense the foregoing rights on |
| 23 | +either these or other terms. |
| 24 | +
|
| 25 | +This license is subject to the following condition: |
| 26 | +The above copyright notice and either this complete permission notice or at |
| 27 | +a minimum a reference to the UPL must be included in all copies or |
| 28 | +substantial portions of the Software. |
| 29 | +
|
| 30 | +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR |
| 31 | +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, |
| 32 | +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE |
| 33 | +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER |
| 34 | +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, |
| 35 | +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE |
| 36 | +SOFTWARE. |
| 37 | +--> |
| 38 | + |
| 39 | +# A Java Hello World function accessing ATP database with local dev and then building and deploying to OCI Functions |
| 40 | + |
| 41 | +Reviewed: 14.04.2025 |
| 42 | + |
| 43 | +# When to use this asset? |
| 44 | + |
| 45 | +Anyone who wants to develop Functions with Autonomous Database access and this example shows how I'm doing this locally using Fn (<a href="https://fnproject.io">https://fnproject.io</a>) on my mac with Apple silicon that uses mainly ARM architecture and then building and then deploying the same to Functions in OCI. |
| 46 | + |
| 47 | +# Author |
| 48 | +<a href="https://github.com/mikarinneoracle">mikarinneoracle</a> |
| 49 | + |
| 50 | +# How to use this asset? |
| 51 | + |
| 52 | +## Local Dev |
| 53 | + |
| 54 | +I've installed maven and <code>Fn cli</code> on my mac. This is how to do the <a href="https://docs.oracle.com/en-us/iaas/Content/Functions/Tasks/functionsinstallfncli.htm">Fn cli install</a> or like in here <a href="https://fnproject.io/tutorials/install/">following the Fn tutorial</a>. |
| 55 | + |
| 56 | +<p> |
| 57 | + |
| 58 | +To develop functions locally I'm running the Fn server. Normally you would start it with <code>fn start</code> command but I'm using this command with Rancher Desktop that works for me: |
| 59 | + |
| 60 | +<pre> |
| 61 | +docker run --rm -i --name fnserver \ |
| 62 | +-v /tmp/iofs:/iofs \ |
| 63 | +-e FN_IOFS_DOCKER_PATH=/tmp/iofs \ |
| 64 | +-e FN_IOFS_PATH=/iofs \ |
| 65 | +-v /tmp/data:/app/data \ |
| 66 | +-v /var/run/docker.sock:/var/run/docker.sock \ |
| 67 | +--privileged \ |
| 68 | +-p 8080:8080 \ |
| 69 | +--entrypoint ./fnserver \ |
| 70 | +-e FN_LOG_LEVEL=DEBUG fnproject/fnserver:latest |
| 71 | +</pre> |
| 72 | + |
| 73 | +<p> |
| 74 | +Now that the Fn server is running create an application for our function using the cli: |
| 75 | + |
| 76 | +<pre> |
| 77 | +fn create app hellofunction |
| 78 | +</pre> |
| 79 | + |
| 80 | +<p> |
| 81 | + |
| 82 | +Then clone this repo and project and cd to the project root directory under <code>/files</code>. Then run Fn cli command to build and deploy the function locally: |
| 83 | + |
| 84 | +<pre> |
| 85 | +fn --verbose deploy --app hellofunction --local |
| 86 | +</pre> |
| 87 | + |
| 88 | +## Testing |
| 89 | + |
| 90 | +Create new ATP database instance (eg. "fntest") with a public VCN/subnet and <i>Access type</i> <code>Allow secure access from specified IPs and VCNs</code> and set the <i>Mutual TLS (mTLS) authentication</i> to <code>Not required</code>. |
| 91 | + |
| 92 | +<p> |
| 93 | + |
| 94 | +To access the ATP database from local dev your <i>IP address</i> needs to be <b>whitelisted</b> in the ATP instance Network configuration. |
| 95 | + |
| 96 | +<p> |
| 97 | +Before running the function config for the ATP connection needs to be set: |
| 98 | + |
| 99 | +<pre> |
| 100 | +fn config app hellofunction DB_USER admin |
| 101 | +fn config app hellofunction DB_PASSWORD <YOUR ATP PASSWORD HERE> |
| 102 | +fn config app hellofunction DB_URL (description= (retry_count=20)(retry_delay=3)(address=(protocol=tcps)(port=1521)(host=adb.eu-frankfurt-1.oraclecloud.com))(connect_data=(service_name=g90....6d8_fntest_tp.adb.oraclecloud.com))(security=(ssl_server_dn_match=yes))) |
| 103 | +</pre> |
| 104 | + |
| 105 | +<code>DB_URL</code> can be found by clicking the <i>Database Connection</i> -button on ATP database instance in the Cloud UI, e.g. : |
| 106 | + |
| 107 | +<img src="./files/ATP_connection_url.png" with="1200" /> |
| 108 | + |
| 109 | +<p> |
| 110 | + |
| 111 | +After this you are ready to call the function to test it and get the SYSDATE from ATP: |
| 112 | + |
| 113 | +<pre> |
| 114 | +fn invoke hellofunction hellofunc |
| 115 | +2025-04-14 08:49:13 |
| 116 | +</pre> |
| 117 | + |
| 118 | +## OCI |
| 119 | + |
| 120 | +Now that the function is properly working locally let's build and deploy it to OCI. |
| 121 | + |
| 122 | +<p> |
| 123 | + |
| 124 | +First create a OCIR repo for the container in your OCI tenancy <code>compartment</code> you want push the container into. Unless you do this first the container will be pushed to the <code>root</code> comaprtment that is not a good idea and will usually lead to 404 or 502 errors when the OCI Function pulling the container due to missing OCI policies. You can create the OCIR repo from the Cloud UI or using the <a href="https://docs.oracle.com/en-us/iaas/tools/oci-cli/3.41.0/oci_cli_docs/cmdref/artifacts/container/repository/create.html">oci cli</a>. |
| 125 | + |
| 126 | +<p> |
| 127 | + |
| 128 | +Next, let's build the Docker container for the function using <code>docker build</code>, let's not use Fn this time (that is also possible), using the FRA region: |
| 129 | + |
| 130 | +<pre> |
| 131 | +docker build -t fra.ocir.io/<YOUR OCI TENANCY NAMESPACE>/helloworld-java:1 . |
| 132 | +</pre> |
| 133 | + |
| 134 | +In the docker build command above replace the <code>region</code> if necessary and the <code><YOUR OCI TENANCY NAMESPACE></code> with yours. |
| 135 | +<p> |
| 136 | + |
| 137 | +After building let's do <code>docker login</code> and <code>docker push</code> to push the container to the OCIR repo: |
| 138 | + |
| 139 | +<p> |
| 140 | + |
| 141 | +<pre> |
| 142 | +docker login ams.ocir.io -u '<YOUR OCI TENANCY NAMESPACE>/oracleidentitycloudservice/<YOUR USERNAME>' -p '<YOUR ACCESS TOKEN>' |
| 143 | +docker push fra.ocir.io/<YOUR OCI TENANCY NAMESPACE>/helloworld-java:1 |
| 144 | +</pre> |
| 145 | + |
| 146 | +<p> |
| 147 | +The same as above but using OCI cli to get the <YOUR OCI TENANCY NAMESPACE> which is especially handy in scripting: |
| 148 | + |
| 149 | +<pre> |
| 150 | +export namespace=$(oci os ns get | jq .data | tr -d '"') |
| 151 | +docker build -t fra.ocir.io/$namespace/helloworld-java:1 . |
| 152 | +docker push fra.ocir.io/$namespace/helloworld-java:1 |
| 153 | +</pre> |
| 154 | + |
| 155 | +<p> |
| 156 | +The last step is to create the Function Application and the function deployment for it. This can be easily done using the Cloud UI. |
| 157 | + |
| 158 | +<p> |
| 159 | + |
| 160 | +To create a mac binary compatible Function Application use the <code>shape GENERIC_ARM</code>. Let's name this <code>hello-arm</code>. |
| 161 | + |
| 162 | +<p> |
| 163 | + |
| 164 | +Using the application create a function for it from the container image that was pushed to the OCIR repo e.g. <code>fra.ocir.io/<YOUR OCI TENANCY NAMESPACE>/helloworld-java:1</code>. Let's name this <code>helloworld-java-arm</code>. |
| 165 | + |
| 166 | +<p> |
| 167 | + |
| 168 | +Like previously add the configuration for the ATP database connection, either on the application or function level (both will work with our example function) using the Cloud UI: |
| 169 | + |
| 170 | +<pre> |
| 171 | +DB_USER admin |
| 172 | +DB_PASSWORD <YOUR ATP PASSWORD HERE> |
| 173 | +DB_URL (description= (retry_count=20)(retry_delay=3)(address=(protocol=tcps)(port=1521)(host=adb.eu-frankfurt-1.oraclecloud.com))(connect_data=(service_name=g90....6d8_fntest_tp.adb.oraclecloud.com))(security=(ssl_server_dn_match=yes))) |
| 174 | +</pre> |
| 175 | + |
| 176 | +<p> |
| 177 | +To access the ATP database from the OCI Function the <i>function application VCN</i> needs to be <b>whitelisted</b> in the ATP instance Network configuration either by using it's <code>OCID</code> or <code>CIDR block</code>. |
| 178 | +<p> |
| 179 | + |
| 180 | +After deployment the Function can be easily tested in Cloud Shell following the Getting Started guide for the Application and giving: |
| 181 | + |
| 182 | +<pre> |
| 183 | +fn invoke hello-arm helloworld-java-arm |
| 184 | +2025-04-14 08:49:13 |
| 185 | +</pre> |
| 186 | + |
| 187 | +<p> |
| 188 | + |
| 189 | +Optionally can create API Gateway for the function that will assign a public endpoint to it over HTTPS that can be easily tested with curl: |
| 190 | + |
| 191 | +<pre> |
| 192 | +curl https://n3yu.....ghhi.apigateway.eu-frankfurt-1.oci.customer-oci.com/ |
| 193 | +2025-04-14 08:49:13 |
| 194 | +</pre> |
| 195 | + |
| 196 | +# Useful Links |
| 197 | + |
| 198 | +- [OCI Functions](https://docs.oracle.com/en-us/iaas/Content/Functions/Concepts/functionsoverview.htm) |
| 199 | + - Learn how the Functions service lets you create, run, and scale business logic without managing any infrastructure |
| 200 | +- [Fn](https://fnproject.io/) |
| 201 | + - The Fn project is an open-source container-native serverless platform that you can run anywhere -- any cloud or on-premise. It’s easy to use, supports every programming language, and is extensible and performant |
| 202 | +- [Autonomous Database](https://www.oracle.com/autonomous-database/) |
| 203 | + - Develop scalable AI-powered apps with any data using built-in AI capabilities. Use your choice of large language model (LLM) and deploy in the cloud or your data center |
| 204 | +- [Oracle](https://www.oracle.com/) |
| 205 | + - Oracle Website |
| 206 | + |
| 207 | +## License |
| 208 | + |
| 209 | +Copyright (c) 2025 Oracle and/or its affiliates. |
| 210 | + |
| 211 | +Licensed under the Universal Permissive License (UPL), Version 1.0. |
| 212 | + |
| 213 | +See [LICENSE](LICENSE) for more details. |
| 214 | + |
| 215 | +ORACLE AND ITS AFFILIATES DO NOT PROVIDE ANY WARRANTY WHATSOEVER, EXPRESS OR IMPLIED, FOR ANY SOFTWARE, MATERIAL OR CONTENT OF ANY KIND CONTAINED OR PRODUCED WITHIN THIS REPOSITORY, AND IN PARTICULAR SPECIFICALLY DISCLAIM ANY AND ALL IMPLIED WARRANTIES OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY, AND FITNESS FOR A PARTICULAR PURPOSE. FURTHERMORE, ORACLE AND ITS AFFILIATES DO NOT REPRESENT THAT ANY CUSTOMARY SECURITY REVIEW HAS BEEN PERFORMED WITH RESPECT TO ANY SOFTWARE, MATERIAL OR CONTENT CONTAINED OR PRODUCED WITHIN THIS REPOSITORY. IN ADDITION, AND WITHOUT LIMITING THE FOREGOING, THIRD PARTIES MAY HAVE POSTED SOFTWARE, MATERIAL OR CONTENT TO THIS REPOSITORY WITHOUT ANY REVIEW. USE AT YOUR OWN RISK. |
0 commit comments