chore: add connectivity sample for Java (GoogleCloudPlatform#185)

Co-authored-by: jackwotherspoon <jackwoth@google.com>
jsimonweb · Dec 8, 2022 · 7b9b7ba · 7b9b7ba
1 parent 30587d6
commit 7b9b7ba
Show file tree

Hide file tree

Showing 18 changed files with 1,408 additions and 1 deletion.
diff --git a/.github/renovate.json b/.github/renovate.json
@@ -4,6 +4,13 @@
     ":semanticCommitTypeAll(chore)"
   ],
   "ignorePresets": [":semanticPrefixFixDepsChoreOthers"],
+  "packageRules": [
+    {
+      "description": "Group all dependencies for Java sample",
+      "matchPaths": ["examples/java/**"],
+      "groupName": "Java sample dependencies"
+    }
+  ],
   "prConcurrentLimit": 0,
   "rebaseStalePrs": true,
   "dependencyDashboard": true,

diff --git a/.github/workflows/sample-tests.yaml b/.github/workflows/sample-tests.yaml
@@ -0,0 +1,113 @@
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+name: sample
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+  pull_request_target:
+    types: [labeled]
+  schedule:
+  - cron:  '0 2 * * *'
+jobs:
+  # job to run change detection
+  changes:
+    # run job on proper workflow event triggers (skip job for pull_request event from forks and only run pull_request_target for "tests: run" label)
+    if: |
+      "${{ (github.event.action != 'labeled' && github.event.pull_request.head.repo.full_name == github.event.pull_request.base.repo.full_name) || github.event.label.name == 'tests: run' }}" &&
+      ${{ github.event_name != 'schedule' }}
+    runs-on: ubuntu-latest
+    # Required permissions
+    permissions:
+      pull-requests: read
+    # Set job outputs to values from filter step
+    outputs:
+      java: ${{ steps.filter.outputs.java }}
+    steps:
+    - name: Remove PR label
+      if: "${{ github.event.action == 'labeled' && github.event.label.name == 'tests: run' }}"
+      uses: actions/github-script@v6
+      with:
+        github-token: ${{ secrets.GITHUB_TOKEN }}
+        script: |
+          try {
+            await github.rest.issues.removeLabel({
+              name: 'tests: run',
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.payload.pull_request.number
+            });
+          } catch (e) {
+            console.log('Failed to remove label. Another job may have already removed it!');
+          }
+    - uses: actions/checkout@v3
+    - uses: dorny/paths-filter@v2
+      id: filter
+      with:
+        filters: |
+          java:
+            - 'examples/java/**'
+  java:
+    # This ensures that the java job execute after the changes job, since it's dependent on
+    # that job's output.
+    needs: changes
+    if: ${{ needs.changes.outputs.java == 'true' || github.event_name == 'schedule' }}
+    runs-on: [self-hosted, linux, x64]
+    permissions:
+      contents: 'read'
+      id-token: 'write'
+    steps:
+      - name: Checkout code
+        uses: 'actions/checkout@v3'
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+          repository: ${{ github.event.pull_request.head.repo.full_name }}
+
+      - name: Setup Maven Action
+        uses: s4u/setup-maven-action@v1.2.1
+        with:
+          java-version: 17
+
+      - name: 'Authenticate to Google Cloud'
+        id: 'auth'
+        uses: 'google-github-actions/auth@v1.0.0'
+        with:
+          workload_identity_provider: ${{ secrets.PROVIDER_NAME }}
+          service_account: ${{ secrets.SERVICE_ACCOUNT }}
+
+      - name: 'Set up Cloud SDK'
+        uses: 'google-github-actions/setup-gcloud@v1.0.1'
+      - name: Get Secrets
+        id: 'secrets'
+        uses: 'google-github-actions/get-secretmanager-secrets@v0'
+        with:
+          secrets: |-
+            ALLOYDB_CONN_NAME:alloydb-connector-testing/ALLOYDB_CONN_NAME
+            ALLOYDB_CLUSTER_PASS:alloydb-connector-testing/ALLOYDB_CLUSTER_PASS
+
+      - name: Run lint
+        run: |
+          cd examples/java
+          mvn -P lint checkstyle:check
+
+      - name: Run tests
+        env:
+          DB_NAME: 'postgres'
+          DB_USER: 'postgres'
+          DB_PASS: '${{ steps.secrets.outputs.ALLOYDB_CLUSTER_PASS }}'
+          ALLOYDB_CONNECTION_NAME: '${{ steps.secrets.outputs.ALLOYDB_CONN_NAME }}'
+        run: |
+          ./examples/java/run_tests.sh
+
diff --git a/.gitignore b/.gitignore
@@ -2,10 +2,49 @@
 .envrc
 
 # IDEs
-.idea/
 .vscode/
 
 # Compiled binary
 /alloydb-auth-proxy
 
 /key.json
+
+
+
+### SAMPLES
+
+appengine-generated/
+*.class
+.mtj.tmp/
+*.jar
+*.war
+*.ear
+hs_err_pid*
+.java-version
+target/
+pom.xml.tag
+pom.xml.releaseBackup
+pom.xml.versionsBackup
+pom.xml.next
+release.properties
+dependency-reduced-pom.xml
+buildNumber.properties
+.checkstyle
+build/
+service-account.json
+secrets.env
+.idea/
+*.iml
+.project
+.classpath
+.settings
+[._]*.s[a-w][a-z]
+[._]s[a-w][a-z]
+Session.vim
+.netrwhist
+*~
+tags
+out/
+.gradle/
+.vscode/
+.DS_Store
diff --git a/examples/java/.env.yaml b/examples/java/.env.yaml
@@ -0,0 +1,20 @@
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+ALLOYDB_CONNECTION_NAME: ALLOYDB_CONNECTION_NAME='projects/<PROJECT>/locations/<REGION>/clusters/<CLUSTER>/instances/<INSTANCE>'
+DB_HOST: '127.0.0.1'
+DB_PORT: 5432
+DB_USER: <YOUR_DB_USER_NAME>
+DB_PASS: <YOUR_DB_PASSWORD>
+DB_NAME: <YOUR_DB_NAME>
diff --git a/examples/java/README.md b/examples/java/README.md
@@ -0,0 +1,118 @@
+# Connecting to AlloyDB
+
+## Before you begin
+
+1. Enable access to AlloyDB in your project by following these [instructions](https://cloud.google.com/alloydb/docs/project-enable-access)
+
+1. Create a VPC network and [configure Private Services Access for AlloyDB](https://cloud.google.com/alloydb/docs/configure-connectivity)
+
+1. Create an AlloyDB cluster and its primary instance by following these [instructions](https://cloud.google.com/alloydb/docs/cluster-create). Make note of the Cluster ID, Instance ID, IP Address and Password
+
+1. Create a database for your application by following these 
+[instructions](https://cloud.google.com/sql/docs/postgres/create-manage-databases). Note the database
+name. 
+
+1. Create a user in your database by following these 
+[instructions](https://cloud.google.com/alloydb/docs/database-users/about). Note the username. 
+
+1. Create a service account with the 'AlloyDB Client' permissions by following these 
+[instructions](https://cloud.google.com/sql/docs/postgres/connect-external-app#4_if_required_by_your_authentication_method_create_a_service_account).
+Download a JSON key to use to authenticate your connection. 
+
+1. Use the information noted in the previous steps:
+```bash
+export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service/account/key.json
+export DB_USER='my-db-user'
+export DB_PASS='my-db-pass'
+export DB_NAME='my_db'
+export DB_HOST='<IP Address of Cluster or 127.0.0.1 if using auth proxy>'
+export DB_POST=5432
+export ALLOYDB_CONNECTION_NAME='projects/<PROJECT>/locations/<REGION>/clusters/<CLUSTER>/instances/<INSTANCE>'
+```
+Note: Saving credentials in environment variables is convenient, but not secure - consider a more
+secure solution such as [Secret Manager](https://cloud.google.com/secret-manager/) to help keep secrets safe.
+
+
+## Google App Engine Standard
+
+To run on GAE-Standard, create an AppEngine project by following the setup for these 
+[instructions](https://cloud.google.com/appengine/docs/standard/java/quickstart#before-you-begin) 
+and verify that 
+[appengine-maven-plugin](https://cloud.google.com/java/docs/setup#optional_install_maven_or_gradle_plugin_for_app_engine)
+ has been added in your build section as a plugin.
+
+
+### Deploy to Google App Engine
+Before deploying the application, you will need to [configure a Serverless VPC Connector](https://cloud.google.com/vpc/docs/configure-serverless-vpc-access) to be able to connect to the VPC in which your AlloyDB cluster is running.
+
+First, update `src/main/webapp/WEB-INF/appengine-web.xml` with the correct values to pass the 
+environment variables into the runtime.
+
+Next, the following command will deploy the application to your Google Cloud project:
+```bash
+mvn clean package appengine:deploy
+```
+
+### Deploy to Cloud Run
+Before deploying the application, you will need to [configure a Serverless VPC Connector](https://cloud.google.com/vpc/docs/configure-serverless-vpc-access) to be able to connect to the VPC in which your AlloyDB cluster is running.
+
+1. Build the container image using [Jib](https://cloud.google.com/java/getting-started/jib):
+
+  ```sh
+mvn clean package com.google.cloud.tools:jib-maven-plugin:2.8.0:build \
+ -Dimage=gcr.io/[YOUR_PROJECT_ID]/run-postgres -DskipTests
+  ```
+
+2. Deploy the service to Cloud Run:
+
+  ```sh
+  gcloud run deploy run-postgres \
+    --image gcr.io/[YOUR_PROJECT_ID]/run-postgres \
+    --platform managed \
+    --allow-unauthenticated \
+    --region [REGION] \
+    --update-env-vars ALLOYDB_CONNECTION_NAME=[ALLOYDB_CONNECTION_NAME] \
+    --update-env-vars DB_USER=[MY_DB_USER] \
+    --update-env-vars DB_PASS=[MY_DB_PASS] \
+    --update-env-vars DB_NAME=[MY_DB]
+  ```
+
+  Replace environment variables with the correct values for your AlloyDB instance configuration.
+
+  Take note of the URL output at the end of the deployment process.
+
+  It is recommended to use the [Secret Manager integration](https://cloud.google.com/run/docs/configuring/secrets) for Cloud Run instead
+  of using environment variables for the SQL configuration. The service injects the Alloy credentials from
+  Secret Manager at runtime via an environment variable.
+
+  Create secrets via the command line:
+  ```sh
+  echo -n "projects/<PROJECT>/locations/<REGION>/clusters/<CLUSTER>/instances/<INSTANCE>" | \
+      gcloud secrets versions add ALLOYDB_CONNECTION_NAME_SECRET --data-file=-
+  ```
+
+  Deploy the service to Cloud Run specifying the env var name and secret name:
+  ```sh
+  gcloud beta run deploy SERVICE --image gcr.io/[YOUR_PROJECT_ID]/run-alloydb \
+      --update-secrets ALLOYDB_CONNECTION_NAME=[ALLOYDB_CONNECTION_NAME_SECRET]:latest,\
+        DB_USER=[DB_USER_SECRET]:latest, \
+        DB_PASS=[DB_PASS_SECRET]:latest, \
+        DB_NAME=[DB_NAME_SECRET]:latest
+  ```
+
+3. Navigate your browser to the URL noted in step 2.
+
+  For more details about using Cloud Run see http://cloud.run.
+  Review other [Java on Cloud Run samples](../../../run/).
+
+### Deploy to Google Cloud Functions
+Before deploying the application, you will need to [configure a Serverless VPC Connector](https://cloud.google.com/vpc/docs/configure-serverless-vpc-access) to be able to connect to the VPC in which your AlloyDB cluster is running.
+
+To deploy the application to Cloud Functions, first fill in the values for required environment variables in `.env.yaml`. Then run the following command
+```
+gcloud functions deploy alloydb-sample \
+  --trigger-http \
+  --entry-point com.example.alloydb.functions.Main \
+  --runtime java11 \
+  --env-vars-file .env.yaml
+```