├── .cctemplate ├── .github ├── CODEOWNERS ├── dependabot.yml └── trusted-contribution.yml ├── .gitignore ├── CONTRIBUTING.md ├── LICENSE ├── README.md ├── pom.xml ├── project.toml ├── renovate.json └── src ├── main ├── java │ └── com │ │ └── cloudrun │ │ └── microservicetemplate │ │ ├── MicroserviceController.java │ │ ├── MicroserviceTemplateApplication.java │ │ └── util │ │ └── Metadata.java └── resources │ ├── application.properties │ └── logback-spring.xml └── test ├── java └── com │ └── cloudrun │ └── microservicetemplate │ ├── MicroserviceControllerTest.java │ └── MicroserviceTemplateIT.java └── resources ├── advance.cloudbuild.yaml └── common.sh /.cctemplate: -------------------------------------------------------------------------------- 1 | { 2 | "name": "cloud-run-microservice-template-java", 3 | "metadata": { 4 | "version": "0.1.0" 5 | }, 6 | "templates": [ 7 | { 8 | "path": "./", 9 | "name": "Cloud Run Microservice Template - Java", 10 | "description": "Basic microservice template for Cloud Run", 11 | "languages": [ 12 | "Java" 13 | ] 14 | } 15 | ] 16 | } 17 | -------------------------------------------------------------------------------- /.github/CODEOWNERS: -------------------------------------------------------------------------------- 1 | * @GoogleCloudPlatform/team-egg 2 | -------------------------------------------------------------------------------- /.github/dependabot.yml: -------------------------------------------------------------------------------- 1 | # To get started with Dependabot version updates, you'll need to specify which 2 | # package ecosystems to update and where the package manifests are located. 3 | # Please see the documentation for all configuration options: 4 | # https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates 5 | 6 | version: 2 7 | updates: 8 | - package-ecosystem: "maven" 9 | directory: "/" 10 | commit-message: 11 | prefix: "chore(deps): " 12 | rebase-strategy: "disabled" 13 | schedule: 14 | interval: "monthly" 15 | ignore: 16 | - dependency-name: "*" 17 | update-types: ["version-update:semver-patch"] # Security updates are unaffected by this setting 18 | -------------------------------------------------------------------------------- /.github/trusted-contribution.yml: -------------------------------------------------------------------------------- 1 | annotations: 2 | - type: comment 3 | text: "/gcbrun" 4 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Copyright 2021 Google LLC 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # https://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | 15 | # A gitignore file specifies intentionally untracked files that Git should ignore. 16 | 17 | ### Maven ### 18 | # https://github.com/github/gitignore/blob/master/Maven.gitignore 19 | 20 | target/ 21 | pom.xml.tag 22 | pom.xml.releaseBackup 23 | pom.xml.versionsBackup 24 | pom.xml.next 25 | release.properties 26 | dependency-reduced-pom.xml 27 | buildNumber.properties 28 | .mvn/timing.properties 29 | # https://github.com/takari/maven-wrapper#usage-without-binary-jar 30 | .mvn/wrapper/maven-wrapper.jar 31 | 32 | ### Java ### 33 | # https://github.com/github/gitignore/blob/master/Java.gitignore 34 | 35 | # Compiled class file 36 | *.class 37 | 38 | # Log file 39 | *.log 40 | 41 | # BlueJ files 42 | *.ctxt 43 | 44 | # Mobile Tools for Java (J2ME) 45 | .mtj.tmp/ 46 | 47 | # Package Files # 48 | *.jar 49 | *.war 50 | *.nar 51 | *.ear 52 | *.zip 53 | *.tar.gz 54 | *.rar 55 | 56 | # virtual machine crash logs, see http://www.java.com/en/download/help/error_hotspot.xml 57 | hs_err_pid* 58 | 59 | ### VS Code ### 60 | # https://github.com/github/gitignore/blob/master/Global/VisualStudioCode.gitignore 61 | .vscode/* 62 | !.vscode/settings.json 63 | !.vscode/tasks.json 64 | !.vscode/launch.json 65 | !.vscode/extensions.json 66 | *.code-workspace 67 | 68 | # Local History for Visual Studio Code 69 | .history/ 70 | 71 | ### Eclipse ### 72 | # https://github.com/github/gitignore/blob/master/Global/Eclipse.gitignore 73 | 74 | .metadata 75 | bin/ 76 | tmp/ 77 | *.tmp 78 | *.bak 79 | *.swp 80 | *~.nib 81 | local.properties 82 | .settings/ 83 | .loadpath 84 | .recommenders 85 | 86 | # External tool builders 87 | .externalToolBuilders/ 88 | 89 | # Locally stored "Eclipse launch configurations" 90 | *.launch 91 | 92 | # PyDev specific (Python IDE for Eclipse) 93 | *.pydevproject 94 | 95 | # CDT-specific (C/C++ Development Tooling) 96 | .cproject 97 | 98 | # CDT- autotools 99 | .autotools 100 | 101 | # Java annotation processor (APT) 102 | .factorypath 103 | 104 | # PDT-specific (PHP Development Tools) 105 | .buildpath 106 | 107 | # sbteclipse plugin 108 | .target 109 | 110 | # Tern plugin 111 | .tern-project 112 | 113 | # TeXlipse plugin 114 | .texlipse 115 | 116 | # STS (Spring Tool Suite) 117 | .springBeans 118 | 119 | # Code Recommenders 120 | .recommenders/ 121 | 122 | # Annotation Processing 123 | .apt_generated/ 124 | .apt_generated_test/ 125 | 126 | # Scala IDE specific (Scala & Java development for Eclipse) 127 | .cache-main 128 | .scala_dependencies 129 | .worksheet 130 | 131 | # Comment this line if you wish to track the project description file. 132 | # Typically, this file would be tracked if it contains build/dependency configurations: 133 | .project 134 | .classpath 135 | 136 | # macOS 137 | **/.DS_STORE -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # How to become a contributor and submit your own code 2 | ## Contributor License Agreements 3 | We'd love to accept your sample apps and patches! Before we can take them, we 4 | have to jump a couple of legal hurdles. 5 | Please fill out either the individual or corporate Contributor License Agreement 6 | (CLA). 7 | * If you are an individual writing original source code and you're sure you 8 | own the intellectual property, then you'll need to sign an [individual CLA] 9 | (https://developers.google.com/open-source/cla/individual). 10 | * If you work for a company that wants to allow you to contribute your work, 11 | then you'll need to sign a [corporate CLA] 12 | (https://developers.google.com/open-source/cla/corporate). 13 | Follow either of the two links above to access the appropriate CLA and 14 | instructions for how to sign and return it. Once we receive it, we'll be able to 15 | accept your pull requests. 16 | ## Contributing A Patch 17 | 1. Submit an issue describing your proposed change to the repo in question. 18 | 1. The repo owner will respond to your issue promptly. 19 | 1. If your proposed change is accepted, and you haven't already done so, sign a 20 | Contributor License Agreement (see details above). 21 | 1. Fork the desired repo, develop and test your code changes. 22 | 1. Ensure that your code adheres to the existing style in the sample to which 23 | you are contributing. Refer to the 24 | [Google Cloud Platform Samples Style Guide] 25 | (https://github.com/GoogleCloudPlatform/Template/wiki/style.html) for the 26 | recommended coding standards for this organization. 27 | 1. Ensure that your code has an appropriate set of unit tests which all pass. 28 | 1. Submit a pull request. 29 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | 2 | Apache License 3 | Version 2.0, January 2004 4 | http://www.apache.org/licenses/ 5 | 6 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 7 | 8 | 1. Definitions. 9 | 10 | "License" shall mean the terms and conditions for use, reproduction, 11 | and distribution as defined by Sections 1 through 9 of this document. 12 | 13 | "Licensor" shall mean the copyright owner or entity authorized by 14 | the copyright owner that is granting the License. 15 | 16 | "Legal Entity" shall mean the union of the acting entity and all 17 | other entities that control, are controlled by, or are under common 18 | control with that entity. For the purposes of this definition, 19 | "control" means (i) the power, direct or indirect, to cause the 20 | direction or management of such entity, whether by contract or 21 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 22 | outstanding shares, or (iii) beneficial ownership of such entity. 23 | 24 | "You" (or "Your") shall mean an individual or Legal Entity 25 | exercising permissions granted by this License. 26 | 27 | "Source" form shall mean the preferred form for making modifications, 28 | including but not limited to software source code, documentation 29 | source, and configuration files. 30 | 31 | "Object" form shall mean any form resulting from mechanical 32 | transformation or translation of a Source form, including but 33 | not limited to compiled object code, generated documentation, 34 | and conversions to other media types. 35 | 36 | "Work" shall mean the work of authorship, whether in Source or 37 | Object form, made available under the License, as indicated by a 38 | copyright notice that is included in or attached to the work 39 | (an example is provided in the Appendix below). 40 | 41 | "Derivative Works" shall mean any work, whether in Source or Object 42 | form, that is based on (or derived from) the Work and for which the 43 | editorial revisions, annotations, elaborations, or other modifications 44 | represent, as a whole, an original work of authorship. For the purposes 45 | of this License, Derivative Works shall not include works that remain 46 | separable from, or merely link (or bind by name) to the interfaces of, 47 | the Work and Derivative Works thereof. 48 | 49 | "Contribution" shall mean any work of authorship, including 50 | the original version of the Work and any modifications or additions 51 | to that Work or Derivative Works thereof, that is intentionally 52 | submitted to Licensor for inclusion in the Work by the copyright owner 53 | or by an individual or Legal Entity authorized to submit on behalf of 54 | the copyright owner. For the purposes of this definition, "submitted" 55 | means any form of electronic, verbal, or written communication sent 56 | to the Licensor or its representatives, including but not limited to 57 | communication on electronic mailing lists, source code control systems, 58 | and issue tracking systems that are managed by, or on behalf of, the 59 | Licensor for the purpose of discussing and improving the Work, but 60 | excluding communication that is conspicuously marked or otherwise 61 | designated in writing by the copyright owner as "Not a Contribution." 62 | 63 | "Contributor" shall mean Licensor and any individual or Legal Entity 64 | on behalf of whom a Contribution has been received by Licensor and 65 | subsequently incorporated within the Work. 66 | 67 | 2. Grant of Copyright License. Subject to the terms and conditions of 68 | this License, each Contributor hereby grants to You a perpetual, 69 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 70 | copyright license to reproduce, prepare Derivative Works of, 71 | publicly display, publicly perform, sublicense, and distribute the 72 | Work and such Derivative Works in Source or Object form. 73 | 74 | 3. Grant of Patent License. Subject to the terms and conditions of 75 | this License, each Contributor hereby grants to You a perpetual, 76 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 77 | (except as stated in this section) patent license to make, have made, 78 | use, offer to sell, sell, import, and otherwise transfer the Work, 79 | where such license applies only to those patent claims licensable 80 | by such Contributor that are necessarily infringed by their 81 | Contribution(s) alone or by combination of their Contribution(s) 82 | with the Work to which such Contribution(s) was submitted. If You 83 | institute patent litigation against any entity (including a 84 | cross-claim or counterclaim in a lawsuit) alleging that the Work 85 | or a Contribution incorporated within the Work constitutes direct 86 | or contributory patent infringement, then any patent licenses 87 | granted to You under this License for that Work shall terminate 88 | as of the date such litigation is filed. 89 | 90 | 4. Redistribution. You may reproduce and distribute copies of the 91 | Work or Derivative Works thereof in any medium, with or without 92 | modifications, and in Source or Object form, provided that You 93 | meet the following conditions: 94 | 95 | (a) You must give any other recipients of the Work or 96 | Derivative Works a copy of this License; and 97 | 98 | (b) You must cause any modified files to carry prominent notices 99 | stating that You changed the files; and 100 | 101 | (c) You must retain, in the Source form of any Derivative Works 102 | that You distribute, all copyright, patent, trademark, and 103 | attribution notices from the Source form of the Work, 104 | excluding those notices that do not pertain to any part of 105 | the Derivative Works; and 106 | 107 | (d) If the Work includes a "NOTICE" text file as part of its 108 | distribution, then any Derivative Works that You distribute must 109 | include a readable copy of the attribution notices contained 110 | within such NOTICE file, excluding those notices that do not 111 | pertain to any part of the Derivative Works, in at least one 112 | of the following places: within a NOTICE text file distributed 113 | as part of the Derivative Works; within the Source form or 114 | documentation, if provided along with the Derivative Works; or, 115 | within a display generated by the Derivative Works, if and 116 | wherever such third-party notices normally appear. The contents 117 | of the NOTICE file are for informational purposes only and 118 | do not modify the License. You may add Your own attribution 119 | notices within Derivative Works that You distribute, alongside 120 | or as an addendum to the NOTICE text from the Work, provided 121 | that such additional attribution notices cannot be construed 122 | as modifying the License. 123 | 124 | You may add Your own copyright statement to Your modifications and 125 | may provide additional or different license terms and conditions 126 | for use, reproduction, or distribution of Your modifications, or 127 | for any such Derivative Works as a whole, provided Your use, 128 | reproduction, and distribution of the Work otherwise complies with 129 | the conditions stated in this License. 130 | 131 | 5. Submission of Contributions. Unless You explicitly state otherwise, 132 | any Contribution intentionally submitted for inclusion in the Work 133 | by You to the Licensor shall be under the terms and conditions of 134 | this License, without any additional terms or conditions. 135 | Notwithstanding the above, nothing herein shall supersede or modify 136 | the terms of any separate license agreement you may have executed 137 | with Licensor regarding such Contributions. 138 | 139 | 6. Trademarks. This License does not grant permission to use the trade 140 | names, trademarks, service marks, or product names of the Licensor, 141 | except as required for reasonable and customary use in describing the 142 | origin of the Work and reproducing the content of the NOTICE file. 143 | 144 | 7. Disclaimer of Warranty. Unless required by applicable law or 145 | agreed to in writing, Licensor provides the Work (and each 146 | Contributor provides its Contributions) on an "AS IS" BASIS, 147 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 148 | implied, including, without limitation, any warranties or conditions 149 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 150 | PARTICULAR PURPOSE. You are solely responsible for determining the 151 | appropriateness of using or redistributing the Work and assume any 152 | risks associated with Your exercise of permissions under this License. 153 | 154 | 8. Limitation of Liability. In no event and under no legal theory, 155 | whether in tort (including negligence), contract, or otherwise, 156 | unless required by applicable law (such as deliberate and grossly 157 | negligent acts) or agreed to in writing, shall any Contributor be 158 | liable to You for damages, including any direct, indirect, special, 159 | incidental, or consequential damages of any character arising as a 160 | result of this License or out of the use or inability to use the 161 | Work (including but not limited to damages for loss of goodwill, 162 | work stoppage, computer failure or malfunction, or any and all 163 | other commercial damages or losses), even if such Contributor 164 | has been advised of the possibility of such damages. 165 | 166 | 9. Accepting Warranty or Additional Liability. While redistributing 167 | the Work or Derivative Works thereof, You may choose to offer, 168 | and charge a fee for, acceptance of support, warranty, indemnity, 169 | or other liability obligations and/or rights consistent with this 170 | License. However, in accepting such obligations, You may act only 171 | on Your own behalf and on Your sole responsibility, not on behalf 172 | of any other Contributor, and only if You agree to indemnify, 173 | defend, and hold each Contributor harmless for any liability 174 | incurred by, or claims asserted against, such Contributor by reason 175 | of your accepting any such warranty or additional liability. 176 | 177 | END OF TERMS AND CONDITIONS 178 | 179 | APPENDIX: How to apply the Apache License to your work. 180 | 181 | To apply the Apache License to your work, attach the following 182 | boilerplate notice, with the fields enclosed by brackets "[]" 183 | replaced with your own identifying information. (Don't include 184 | the brackets!) The text should be enclosed in the appropriate 185 | comment syntax for the file format. We also recommend that a 186 | file or class name and description of purpose be included on the 187 | same "printed page" as the copyright notice for easier 188 | identification within third-party archives. 189 | 190 | Copyright [yyyy] [name of copyright owner] 191 | 192 | Licensed under the Apache License, Version 2.0 (the "License"); 193 | you may not use this file except in compliance with the License. 194 | You may obtain a copy of the License at 195 | 196 | http://www.apache.org/licenses/LICENSE-2.0 197 | 198 | Unless required by applicable law or agreed to in writing, software 199 | distributed under the License is distributed on an "AS IS" BASIS, 200 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 201 | See the License for the specific language governing permissions and 202 | limitations under the License. 203 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Cloud Run Template Microservice 2 | 3 | A template repository for a Cloud Run microservice, written in Java. 4 | 5 | [![Run on Google Cloud](https://deploy.cloud.run/button.svg)](https://deploy.cloud.run) 6 | 7 | ## Prerequisite 8 | 9 | * Enable the Cloud Run API via the [console](https://console.cloud.google.com/apis/library/run.googleapis.com?_ga=2.124941642.1555267850.1615248624-203055525.1615245957) or CLI: 10 | 11 | ```bash 12 | gcloud services enable run.googleapis.com 13 | ``` 14 | 15 | ## Features 16 | 17 | * **Spring Boot**: Web server framework 18 | * **Jib Maven Plugin**: Tooling to build production-ready container images from source code and without a Dockerfile 19 | * **SIGTERM handler**: Catch termination signal for cleanup before Cloud Run stops the container 20 | * **Service metadata**: Access service metadata, project Id and region, at runtime 21 | * **Local development utilities**: Auto-restart with changes and prettify logs 22 | * **Structured logging w/ Log Correlation**: JSON formatted logger, parsable by Cloud Logging, with [automatic correlation of container logs to a request log](https://cloud.google.com/run/docs/logging#correlate-logs). 23 | * **Unit and System tests**: Basic unit and system tests setup for the microservice 24 | 25 | ## Local Development 26 | 27 | ### Cloud Code 28 | 29 | This template works with [Cloud Code](https://cloud.google.com/code), an IDE extension 30 | to let you rapidly iterate, debug, and run code on Kubernetes and Cloud Run. 31 | 32 | Learn how to use Cloud Code for: 33 | 34 | * Local development - [VSCode](https://cloud.google.com/code/docs/vscode/developing-a-cloud-run-service), [IntelliJ](https://cloud.google.com/code/docs/intellij/developing-a-cloud-run-service) 35 | 36 | * Local debugging - [VSCode](https://cloud.google.com/code/docs/vscode/debugging-a-cloud-run-service), [IntelliJ](https://cloud.google.com/code/docs/intellij/debugging-a-cloud-run-service) 37 | 38 | * Deploying a Cloud Run service - [VSCode](https://cloud.google.com/code/docs/vscode/deploying-a-cloud-run-service), [IntelliJ](https://cloud.google.com/code/docs/intellij/deploying-a-cloud-run-service) 39 | * Creating a new application from a custom template (`.template/templates.json` allows for use as an app template) - [VSCode](https://cloud.google.com/code/docs/vscode/create-app-from-custom-template), [IntelliJ](https://cloud.google.com/code/docs/intellij/create-app-from-custom-template) 40 | 41 | ### CLI tooling 42 | 43 | #### Local development 44 | 45 | 1. Start the server with hot reload: 46 | ```bash 47 | mvn spring-boot:run 48 | ``` 49 | * Note: uncomment the JSON formatter in [logback-spring.xml](src/main/resources/logback-spring.xml) 50 | for Pretty Printed logging during development 51 | 52 | #### Deploying a Cloud Run service 53 | 54 | 1. Set Project Id: 55 | ```bash 56 | export GOOGLE_CLOUD_PROJECT= 57 | ``` 58 | 59 | 1. Enable the Artifact Registry API: 60 | ```bash 61 | gcloud services enable artifactregistry.googleapis.com 62 | ``` 63 | 64 | 1. Create an Artifact Registry repo: 65 | ```bash 66 | export REPOSITORY="samples" 67 | export REGION=us-central1 68 | gcloud artifacts repositories create $REPOSITORY --location $REGION --repository-format "docker" 69 | ``` 70 | 71 | 1. Use the gcloud credential helper to authorize Docker to push to your Artifact Registry: 72 | ```bash 73 | gcloud auth configure-docker 74 | ``` 75 | 76 | 1. Build the container: 77 | ```bash 78 | mvn clean compile jib:build -Dimage=$REGION-docker.pkg.dev/$GOOGLE_CLOUD_PROJECT/$REPOSITORY/microservice-template 79 | ``` 80 | 81 | 1. Deploy to Cloud Run: 82 | ```bash 83 | gcloud run deploy microservice-template \ 84 | --image $REGION-docker.pkg.dev/$GOOGLE_CLOUD_PROJECT/$REPOSITORY/microservice-template \ 85 | --region $REGION 86 | ``` 87 | 88 | ### Run sample tests 89 | 90 | 1. Run unit tests 91 | ```bash 92 | mvn test 93 | ``` 94 | 95 | 2. Run system tests 96 | ```bash 97 | gcloud builds submit \ 98 | --config src/test/resources/advance.cloudbuild.yaml \ 99 | --substitutions 'COMMIT_SHA=manual,REPO_NAME=cloud-run-microservice-template-java' 100 | ``` 101 | The Cloud Build configuration file will build and deploy the containerized service 102 | to Cloud Run, run tests managed by Maven, then clean up testing resources. This configuration restricts public 103 | access to the test service. Therefore, service accounts need to have the permission to issue Id tokens for request authorization: 104 | * Enable Cloud Run, Cloud Build, Artifact Registry, and IAM APIs: 105 | ```bash 106 | gcloud services enable run.googleapis.com cloudbuild.googleapis.com iamcredentials.googleapis.com artifactregistry.googleapis.com 107 | ``` 108 | 109 | * Set environment variables. 110 | ```bash 111 | export PROJECT_ID="$(gcloud config get-value project)" 112 | export PROJECT_NUMBER="$(gcloud projects describe $(gcloud config get-value project) --format='value(projectNumber)')" 113 | ``` 114 | 115 | * Create an Artifact Registry repo (or use another already created repo): 116 | ```bash 117 | export REPOSITORY="samples" 118 | export REGION=us-central1 119 | gcloud artifacts repositories create $REPOSITORY --location $REGION --repository-format "docker" 120 | ``` 121 | 122 | * Create service account `token-creator` with `Service Account Token Creator` and `Cloud Run Invoker` roles. 123 | ```bash 124 | gcloud iam service-accounts create token-creator 125 | 126 | gcloud projects add-iam-policy-binding $PROJECT_ID \ 127 | --member="serviceAccount:token-creator@$PROJECT_ID.iam.gserviceaccount.com" \ 128 | --role="roles/iam.serviceAccountTokenCreator" 129 | gcloud projects add-iam-policy-binding $PROJECT_ID \ 130 | --member="serviceAccount:token-creator@$PROJECT_ID.iam.gserviceaccount.com" \ 131 | --role="roles/run.invoker" 132 | ``` 133 | 134 | * Add `Service Account Token Creator` role to the Cloud Build service account. 135 | ```bash 136 | gcloud projects add-iam-policy-binding $PROJECT_ID \ 137 | --member="serviceAccount:$PROJECT_NUMBER@cloudbuild.gserviceaccount.com" \ 138 | --role="roles/iam.serviceAccountTokenCreator" 139 | ``` 140 | 141 | ## Maintenance & Support 142 | 143 | This repo performs basic periodic testing for maintenance. Please use the issue tracker for bug reports, features requests and submitting pull requests. 144 | 145 | ## Contributions 146 | 147 | Please see the [contributing guidelines](CONTRIBUTING.md) 148 | 149 | ## License 150 | 151 | This library is licensed under Apache 2.0. Full license text is available in [LICENSE](LICENSE). -------------------------------------------------------------------------------- /pom.xml: -------------------------------------------------------------------------------- 1 | 2 | 14 | 15 | 4.0.0 16 | com.cloudrun 17 | microservice-template 18 | 0.0.1-SNAPSHOT 19 | microservice-template 20 | Microservice Template 21 | 22 | 23 | 17 24 | 17 25 | 26 | 27 | 28 | org.springframework.boot 29 | spring-boot-starter-parent 30 | 3.5.0 31 | 32 | 33 | 34 | 35 | 36 | 37 | org.springframework.cloud 38 | spring-cloud-dependencies 39 | 2024.0.0 40 | pom 41 | import 42 | 43 | 44 | 45 | 46 | 47 | 48 | org.springframework.boot 49 | spring-boot-starter-web 50 | 51 | 52 | org.springframework.cloud 53 | spring-cloud-gcp-starter-logging 54 | 1.2.8.RELEASE 55 | 56 | 57 | 58 | 59 | com.google.cloud 60 | spring-cloud-gcp-starter 61 | 5.8.0 62 | 63 | 64 | 65 | 66 | 67 | org.springframework.boot 68 | spring-boot-devtools 69 | runtime 70 | true 71 | 72 | 73 | 74 | ch.qos.logback.contrib 75 | logback-jackson 76 | 0.1.5 77 | runtime 78 | true 79 | 80 | 81 | 82 | com.squareup.okhttp3 83 | okhttp 84 | 4.12.0 85 | test 86 | 87 | 88 | org.springframework.boot 89 | spring-boot-starter-test 90 | test 91 | 92 | 93 | org.junit.vintage 94 | junit-vintage-engine 95 | 96 | 97 | 98 | 99 | 100 | 101 | 102 | 103 | 104 | org.springframework.boot 105 | spring-boot-maven-plugin 106 | 3.4.0 107 | 108 | 109 | 110 | repackage 111 | 112 | 113 | 114 | 115 | 116 | 117 | com.google.cloud.tools 118 | jib-maven-plugin 119 | 3.4.5 120 | 121 | 122 | gcr.io/$PROJECT_ID/microservice-template:manual 123 | 124 | 125 | 126 | 127 | 128 | org.apache.maven.plugins 129 | maven-checkstyle-plugin 130 | 3.6.0 131 | 132 | 133 | com.puppycrawl.tools 134 | checkstyle 135 | 10.25.0 136 | 137 | 138 | 139 | google_checks.xml 140 | UTF-8 141 | true 142 | 143 | 144 | 145 | 146 | 147 | 148 | -------------------------------------------------------------------------------- /project.toml: -------------------------------------------------------------------------------- 1 | # Default version is Java 11 2 | # - See https://cloud.google.com/docs/buildpacks/java#specify_a_java_version 3 | # Match the version required in pom.xml by setting it here 4 | # - See https://cloud.google.com/docs/buildpacks/set-environment-variables#build_the_application_with_environment_variables 5 | 6 | [[build.env]] 7 | name = "GOOGLE_RUNTIME_VERSION" 8 | value = "17" 9 | -------------------------------------------------------------------------------- /renovate.json: -------------------------------------------------------------------------------- 1 | { 2 | "extends": [ 3 | "config:recommended", 4 | ":separateMajorReleases", 5 | ":combinePatchMinorReleases", 6 | ":ignoreUnstable", 7 | ":prImmediately", 8 | ":updateNotScheduled", 9 | ":automergeDisabled" 10 | ], 11 | "packageRules": [ 12 | { 13 | "semanticCommitType": "deps", 14 | "semanticCommitScope": null, 15 | "matchPackageNames": [ 16 | "*" 17 | ] 18 | }, 19 | { 20 | "semanticCommitType": "test", 21 | "semanticCommitScope": "deps", 22 | "matchPackageNames": [ 23 | "/^org.springframework.boot:spring-boot-starter-test/", 24 | "/^com.squareup.okhttp3:okhttp/" 25 | ] 26 | }, 27 | { 28 | "ignoreUnstable": false, 29 | "matchPackageNames": [ 30 | "/^com.google.cloud:google-cloud-/" 31 | ] 32 | } 33 | ], 34 | "labels": [ 35 | "automerge" 36 | ], 37 | "rebaseWhen": "never", 38 | "dependencyDashboard": true, 39 | "semanticCommits": "enabled" 40 | } 41 | -------------------------------------------------------------------------------- /src/main/java/com/cloudrun/microservicetemplate/MicroserviceController.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2021 Google LLC 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * http://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package com.cloudrun.microservicetemplate; 18 | 19 | import org.slf4j.Logger; 20 | import org.slf4j.LoggerFactory; 21 | import org.slf4j.MDC; 22 | import org.springframework.web.bind.annotation.GetMapping; 23 | import org.springframework.web.bind.annotation.ResponseBody; 24 | import org.springframework.web.bind.annotation.RestController; 25 | 26 | /** Example REST controller to demonstrate structured logging. */ 27 | @RestController 28 | public class MicroserviceController { 29 | // 'spring-cloud-gcp-starter-logging' module provides support for 30 | // associating a web request trace ID with the corresponding log entries. 31 | // https://cloud.spring.io/spring-cloud-gcp/multi/multi__stackdriver_logging.html 32 | private static final Logger logger = LoggerFactory.getLogger(MicroserviceController.class); 33 | 34 | /** Example endpoint handler. */ 35 | @GetMapping("/") 36 | public @ResponseBody String index() { 37 | // Example of structured logging - add custom fields 38 | MDC.put("logField", "custom-entry"); 39 | MDC.put("arbitraryField", "custom-entry"); 40 | // Use logger with log correlation 41 | // https://cloud.google.com/run/docs/logging#correlate-logs 42 | logger.info("Structured logging example."); 43 | return "Hello World!"; 44 | } 45 | } 46 | -------------------------------------------------------------------------------- /src/main/java/com/cloudrun/microservicetemplate/MicroserviceTemplateApplication.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2021 Google LLC 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * http://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package com.cloudrun.microservicetemplate; 18 | 19 | import javax.annotation.PreDestroy; 20 | import org.slf4j.Logger; 21 | import org.slf4j.LoggerFactory; 22 | import org.springframework.boot.SpringApplication; 23 | import org.springframework.boot.autoconfigure.SpringBootApplication; 24 | 25 | /** Microservice template for Cloud Run. */ 26 | @SpringBootApplication 27 | public class MicroserviceTemplateApplication { 28 | private static final Logger logger = 29 | LoggerFactory.getLogger(MicroserviceTemplateApplication.class); 30 | 31 | public static void main(String[] args) { 32 | SpringApplication.run(MicroserviceTemplateApplication.class, args); 33 | } 34 | 35 | /** Register shutdown hook to listen for termination signal. */ 36 | @PreDestroy 37 | public void tearDown() { 38 | // Clean up resources on shutdown 39 | logger.info(MicroserviceTemplateApplication.class.getSimpleName() + ": received SIGTERM."); 40 | // Flush async logs if needed - current Logback config does not buffer logs 41 | } 42 | } 43 | -------------------------------------------------------------------------------- /src/main/java/com/cloudrun/microservicetemplate/util/Metadata.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2021 Google LLC 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * http://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package com.cloudrun.microservicetemplate.util; 18 | 19 | import com.google.cloud.MetadataConfig; 20 | import com.google.cloud.ServiceOptions; 21 | 22 | /** 23 | * Utilities to access service metadata from the metadata server. 24 | * https://cloud.google.com/run/docs/reference/container-contract#metadata-server 25 | */ 26 | public class Metadata { 27 | 28 | /** 29 | * Fetch an ID token. This token can be appended to the `Authorization: Bearer` header for 30 | * authenticated requests. 31 | * 32 | * @param aud the audience claim or receiving service 33 | * @return an ID token 34 | */ 35 | public static String getIdToken(String aud) { 36 | String token = 37 | MetadataConfig.getAttribute("instance/service-accounts/default/identity?audience=" + aud); 38 | return token; 39 | } 40 | 41 | /** 42 | * Fetch the Cloud Run service region. 43 | * 44 | * @return region in format: projects/PROJECT_NUMBER/regions/REGION 45 | */ 46 | public static String getServiceRegion() { 47 | return MetadataConfig.getZone(); 48 | } 49 | 50 | /** 51 | * Fetch the GCP Project ID. 52 | * 53 | * @return the project ID of the Cloud Run service 54 | */ 55 | public static String getProjectId() { 56 | return ServiceOptions.getDefaultProjectId(); 57 | } 58 | } 59 | -------------------------------------------------------------------------------- /src/main/resources/application.properties: -------------------------------------------------------------------------------- 1 | # Copyright 2021 Google LLC 2 | # 3 | # Licensed under the Apache License, Version 2.0 (the "License"); 4 | # you may not use this file except in compliance with the License. 5 | # You may obtain a copy of the License at 6 | # 7 | # http://www.apache.org/licenses/LICENSE-2.0 8 | # 9 | # Unless required by applicable law or agreed to in writing, software 10 | # distributed under the License is distributed on an "AS IS" BASIS, 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | # See the License for the specific language governing permissions and 13 | # limitations under the License. 14 | 15 | # Listen on PORT env var 16 | server.port=${PORT:8080} 17 | 18 | # Uncomment to disable auto-restart 19 | # spring.devtools.restart.enabled=false -------------------------------------------------------------------------------- /src/main/resources/logback-spring.xml: -------------------------------------------------------------------------------- 1 | 2 | 17 | 18 | 20 | 21 | 22 | 23 | 24 | true 25 | true 26 | true 27 | false 28 | false 29 | false 30 | true 31 | 32 | 35 | 36 | 37 | 38 | 39 | > 40 | 41 | -------------------------------------------------------------------------------- /src/test/java/com/cloudrun/microservicetemplate/MicroserviceControllerTest.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2021 Google LLC 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * http://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package com.cloudrun.microservicetemplate; 18 | 19 | import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get; 20 | import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post; 21 | import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status; 22 | 23 | import org.junit.jupiter.api.Test; 24 | import org.springframework.beans.factory.annotation.Autowired; 25 | import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc; 26 | import org.springframework.boot.test.context.SpringBootTest; 27 | import org.springframework.test.web.servlet.MockMvc; 28 | 29 | @SpringBootTest 30 | @AutoConfigureMockMvc 31 | public class MicroserviceControllerTest { 32 | 33 | @Autowired private MockMvc mvc; 34 | 35 | @Test 36 | public void returns_ok() throws Exception { 37 | this.mvc.perform(get("/")).andExpect(status().isOk()); 38 | } 39 | 40 | @Test 41 | public void returns_notFount() throws Exception { 42 | this.mvc.perform(post("/")).andExpect(status().isMethodNotAllowed()); 43 | } 44 | } 45 | -------------------------------------------------------------------------------- /src/test/java/com/cloudrun/microservicetemplate/MicroserviceTemplateIT.java: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2021 Google LLC 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * http://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | 17 | package com.cloudrun.microservicetemplate; 18 | 19 | import static org.junit.jupiter.api.Assertions.assertEquals; 20 | 21 | import java.io.IOException; 22 | import java.util.concurrent.TimeUnit; 23 | import okhttp3.OkHttpClient; 24 | import okhttp3.Request; 25 | import okhttp3.Response; 26 | import org.junit.jupiter.api.BeforeAll; 27 | import org.junit.jupiter.api.Test; 28 | import org.springframework.boot.test.context.SpringBootTest; 29 | 30 | @SpringBootTest 31 | class MicroserviceTemplateIT { 32 | // Retrieve Cloud Run service test config 33 | static String idToken = System.getenv("ID_TOKEN"); 34 | static String baseURL = System.getenv("BASE_URL"); 35 | 36 | @BeforeAll 37 | public static void setup() throws Exception { 38 | if (baseURL == null || baseURL == "") throw new Exception("Cloud Run service URL not found."); 39 | if (idToken == null || idToken == "") throw new Exception("Unable to acquire an ID token."); 40 | } 41 | 42 | public Response authenticatedRequest(String url) throws IOException { 43 | OkHttpClient ok = 44 | new OkHttpClient.Builder() 45 | .readTimeout(30, TimeUnit.SECONDS) 46 | .writeTimeout(30, TimeUnit.SECONDS) 47 | .build(); 48 | 49 | // Instantiate HTTP request 50 | Request request = 51 | new Request.Builder() 52 | .url(url) 53 | .addHeader("Authorization", "Bearer " + idToken) 54 | .get() 55 | .build(); 56 | 57 | Response response = ok.newCall(request).execute(); 58 | return response; 59 | } 60 | 61 | @Test 62 | public void returns_ok() throws IOException { 63 | Response response = authenticatedRequest(baseURL); 64 | assertEquals(response.code(), 200); 65 | assertEquals(response.body().string(), "Hello World!"); 66 | } 67 | } 68 | -------------------------------------------------------------------------------- /src/test/resources/advance.cloudbuild.yaml: -------------------------------------------------------------------------------- 1 | # Copyright 2021 Google LLC 2 | # Licensed under the Apache License, Version 2.0 (the "License"); 3 | # you may not use this file except in compliance with the License. 4 | # You may obtain a copy of the License at 5 | # http://www.apache.org/licenses/LICENSE-2.0 6 | # Unless required by applicable law or agreed to in writing, software 7 | # distributed under the License is distributed on an "AS IS" BASIS, 8 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 9 | # See the License for the specific language governing permissions and 10 | # limitations under the License. 11 | 12 | steps: 13 | - id: "Lint" 14 | name: maven:3-openjdk-17 15 | args: ["mvn", "compile", "checkstyle:check"] 16 | 17 | - id: "Run Unit Tests" 18 | name: maven:3-openjdk-17 19 | args: ["mvn", "test"] 20 | 21 | # Setup resources for system tests 22 | - id: "Build Container Image" 23 | name: "gcr.io/k8s-skaffold/pack" 24 | entrypoint: pack 25 | args: 26 | - build 27 | - "$_GCR_HOSTNAME/$PROJECT_ID/$_REPOSITORY/$REPO_NAME/$_SERVICE_NAME:$COMMIT_SHA" # Tag docker image with git commit SHA 28 | - "--builder=gcr.io/buildpacks/builder:latest" 29 | - "--path=." 30 | 31 | - id: "Push Container Image" 32 | name: "gcr.io/cloud-builders/docker:latest" 33 | entrypoint: /bin/bash 34 | timeout: 60s 35 | args: 36 | - "-c" 37 | - | 38 | while ! docker push "$_GCR_HOSTNAME/$PROJECT_ID/$_REPOSITORY/$REPO_NAME/$_SERVICE_NAME:$COMMIT_SHA"; do 39 | sleep 2 40 | done 41 | 42 | - id: "Deploy to Cloud Run" 43 | name: "gcr.io/cloud-builders/gcloud:latest" 44 | entrypoint: /bin/bash 45 | args: 46 | - "-c" 47 | - | 48 | gcloud run deploy ${_SERVICE_NAME}-$BUILD_ID \ 49 | --image $_GCR_HOSTNAME/$PROJECT_ID/$_REPOSITORY/$REPO_NAME/$_SERVICE_NAME:$COMMIT_SHA \ 50 | --region ${_DEPLOY_REGION} \ 51 | --no-allow-unauthenticated 52 | 53 | - id: "Retrieve Service URL" 54 | name: "gcr.io/cloud-builders/gcloud:latest" 55 | entrypoint: /bin/bash 56 | args: 57 | - "-c" 58 | - | 59 | set -e 60 | source /workspace/src/test/resources/common.sh 61 | echo $(get_url ${BUILD_ID}) > _service_url 62 | echo "Cloud Run URL for ${_SERVICE_NAME}-$BUILD_ID is $(cat _service_url)" 63 | echo $(get_idtoken) > _id_token 64 | env: 65 | - "_SERVICE_NAME=${_SERVICE_NAME}" 66 | - "_DEPLOY_REGION=${_DEPLOY_REGION}" 67 | - "PROJECT_ID=${PROJECT_ID}" 68 | 69 | - id: "Run System Tests" 70 | name: maven:3-openjdk-17 71 | entrypoint: /bin/bash 72 | args: 73 | - "-c" 74 | - | 75 | export BASE_URL=$(cat _service_url) 76 | export ID_TOKEN=$(cat _id_token) 77 | mvn failsafe:integration-test failsafe:verify 78 | 79 | # Clean up system test resources 80 | - id: "Delete image and service" 81 | name: "gcr.io/cloud-builders/gcloud" 82 | entrypoint: "/bin/bash" 83 | args: 84 | - "-c" 85 | - | 86 | gcloud artifacts docker images delete $_GCR_HOSTNAME/$PROJECT_ID/$_REPOSITORY/$REPO_NAME/$_SERVICE_NAME:$COMMIT_SHA --quiet 87 | gcloud run services delete ${_SERVICE_NAME}-$BUILD_ID --region ${_DEPLOY_REGION} --quiet 88 | 89 | substitutions: 90 | _GCR_HOSTNAME: us-central1-docker.pkg.dev 91 | _SERVICE_NAME: microservice-template 92 | _DEPLOY_REGION: us-central1 93 | _REPOSITORY: samples 94 | -------------------------------------------------------------------------------- /src/test/resources/common.sh: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env bash 2 | ## 3 | # common.sh 4 | # Provides utility functions commonly needed across Cloud Build pipelines. 5 | # 6 | # This is expected to be used from cloud-run-template.cloudbuild.yaml and 7 | # should be "forked" into an individual sample that does not provide the same 8 | # environment variables and workspace. 9 | # 10 | # It is kept separate for two reasons: 11 | # 1. Simplicity of cloudbuild.yaml files. 12 | # 2. Easier evaluation of security implications in changes to get_idtoken(). 13 | # 14 | # Usage 15 | # If you do not need to fork this script, directly source it in your YAML file: 16 | # 17 | # ``` 18 | # . /testing/cloudbuild-templates/common.sh 19 | # echo $(get_url) > _service_url 20 | # ``` 21 | ## 22 | 23 | # Retrieve Cloud Run service URL - 24 | # Cloud Run URLs are not deterministic. 25 | get_url() { 26 | bid=$(test "$1" && echo "$1" || cat _short_id) 27 | gcloud run services describe ${_SERVICE_NAME}-${bid} \ 28 | --format 'value(status.url)' \ 29 | --region ${_DEPLOY_REGION} \ 30 | --platform managed 31 | } 32 | 33 | # Retrieve Id token to make an aunthenticated request - 34 | # Impersonate service account, token-creator@, since 35 | # Cloud Build does not natively mint identity tokens. 36 | get_idtoken() { 37 | curl -X POST -H "content-type: application/json" \ 38 | -H "Authorization: Bearer $(gcloud auth print-access-token)" \ 39 | -d "{\"audience\": \"$(cat _service_url)\"}" \ 40 | "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/token-creator@${PROJECT_ID}.iam.gserviceaccount.com:generateIdToken" | \ 41 | python3 -c "import sys, json; print(json.load(sys.stdin)['token'])" 42 | } --------------------------------------------------------------------------------