Merge pull request #3 from opendevstack/feature/add-postgres-sidecar-…

…variant

Add a Postgres sidecar variant

Makefile

@@ -35,13 +35,23 @@ tasks: ## Render tasks. Use VERSION=1.0.0 make tasks to render specific version.
 		-data Version=$(VERSION) \
 		-template build/tasks/build.yaml \
 		-destination tasks/build.yaml
+	go run github.com/opendevstack/ods-pipeline/cmd/taskmanifest \
+		-data ImageRepository=ghcr.io/opendevstack/ods-pipeline-gradle \
+		-data Version=$(VERSION) \
+		-data PostgresSidecar=true \
+		-template build/tasks/build.yaml \
+		-destination tasks/build-with-postgres.yaml
 .PHONY: tasks
 
 docs: tasks ## Render documentation for tasks.
 	go run github.com/opendevstack/ods-pipeline/cmd/taskdoc \
 		-task tasks/build.yaml \
 		-description build/docs/build.adoc \
 		-destination docs/build.adoc
+	go run github.com/opendevstack/ods-pipeline/cmd/taskdoc \
+		-task tasks/build-with-postgres.yaml \
+		-description build/docs/build.adoc \
+		-destination docs/build-with-postgres.adoc
 .PHONY: docs
 
 ##@ Testing

README.md

@@ -19,6 +19,8 @@ tasks:
 
 See the [documentation](https://github.com/opendevstack/ods-pipeline-gradle/blob/main/docs/build.adoc) for details and available parameters.
 
+**TIP:** If you need a database to run alongside your tests, you can use the [`tasks/build-with-postgres.yaml`](https://github.com/opendevstack/ods-pipeline-gradle/blob/main/docs/build-with-postgres.adoc) variant of this task!
+
 ## About this repository
 
 `docs` and `tasks` are generated directories from recipes located in `build`. See the `Makefile` target for how everything fits together.

build/tasks/build.yaml

@@ -1,7 +1,7 @@
 apiVersion: tekton.dev/v1beta1
 kind: Task
 metadata:
-  name: ods-pipeline-gradle-build
+  name: ods-pipeline-gradle-build{{- if .PostgresSidecar }}-with-postgres{{- end}}
 spec:
   description: |
     Builds Gradle applications and libraries.
@@ -74,9 +74,47 @@ spec:
         Path to the directory into which Gradle publishes its build.
       type: string
       default: build
+    {{- if .PostgresSidecar }}
+    - name: postgres-image
+      description: >-
+        Container image to use for the PostgreSQL sidecar.
+      type: string
+      default: 'postgres'
+    - name: postgres-password
+      description: >-
+        Value to set for `POSTGRES_PASSWORD` (required).
+        This sets the superuser password for PostgreSQL.
+      type: string
+    - name: postgres-user
+      description: >-
+        Value to set for `POSTGRES_USER`.
+        This variable will create the specified user with superuser power
+        and a database with the same name.
+      type: string
+      default: 'postgres'
+    - name: postgres-db
+      description: >-
+        Value to set for `POSTGRES_DB`.
+        Can be used to define a different name for the default database
+        that is created when the image is first started.
+      type: string
+      default: 'postgres'
+    {{- end }}
   results:
     - description: The cache location that the build task used. If caching is not enabled this will be an empty string.
       name: build-reused-from-location
+  {{- if .PostgresSidecar }}
+  sidecars:
+    - image: $(params.postgres-image)
+      name: postgres-sidecar
+      env:
+        - name: POSTGRES_PASSWORD
+          value: $(params.postgres-password)
+        - name: POSTGRES_USER
+          value: $(params.postgres-user)
+        - name: POSTGRES_DB
+          value: $(params.postgres-db)
+  {{- end }}
   steps:
     - name: build-gradle
       # Image is built from build/images/Dockerfile.gradle-toolset.

docs/build-with-postgres.adoc

@@ -0,0 +1,181 @@
+// File is generated; DO NOT EDIT.
+
+= ods-pipeline-gradle-build-with-postgres
+
+Builds Gradle applications.
+
+The gradle build by default caches the downloaded version of the gradle wrapper and dependencies in the cache location of
+the PVC by setting the environment variable `GRADLE_USER_HOME` to `/workspace/source/.ods-cache/deps/gradle`. 
+
+The following steps are executed:
+
+- build gradle application, using `gradlew clean build`, which includes tests execution and coverage report generation
+
+Notes:
+
+- tests exclude the vendor directory.
+- test results are converted into xUnit format.
+
+Available environment variables:
+
+- `ODS_OUTPUT_DIR`: this environment variable points to the folder
+ that this build expects generated application artifacts to be copied to.
+ The gradle script should read it and copy there the generated artifacts.
+- `NEXUS_*` env vars: `NEXUS_URL`, `NEXUS_USERNAME` and `NEXUS_PASSWORD`
+ are available and should be read by the gradle script.
+ To enable the gradle script to copy the generated application artifacts script follow these steps:
+
+- read the environment variable `ODS_OUTPUT_DIR` in the buildscript section of the gradle script:
+```
+buildscript {
+    ext {
+      outputDir = System.getenv('ODS_OUTPUT_DIR')
+    }
+}
+```
+- customize the jar tasks to set the destination directory
+```
+jar {
+    println("Set application jar name to 'app'")
+    archiveBaseName = 'app'
+    if (outputDir != null) {
+        println("Set destinationDirectory to '${projectDir}/${outputDir}'")
+        destinationDirectory = file("${projectDir}/${outputDir}")
+    }
+}
+```
+
+To create a coverage report be sure that you add to `gradle.properties` the required
+configuration. For example to enable Jacoco coverage repot you will need to:
+
+- add `jacoco` plugin:
+```
+plugins {
+    id 'application'
+    id 'jacoco'
+}
+```
+- add task `jacocoTestReport`:
+```
+jacocoTestReport {
+    reports {
+        xml.required = true
+    }
+}
+```
+- add `finalizedBy jacocoTestReport` to the task `test`:
+```
+tasks.named('test') {
+    useJUnitPlatform()
+    finalizedBy jacocoTestReport
+}
+```
+
+The exact build recipe can be found at
+ link:https://github.com/opendevstack/ods-pipeline/blob/main/build/package/scripts/build-gradle.sh[build/package/scripts/build-gradle.sh].
+
+
+The following artifacts are generated by the build task and placed into `.ods/artifacts/`
+
+* `code-coverage/`
+  ** `coverage.xml`
+* `xunit-reports/`
+  ** `report.xml`
+Instead of the built-in script, one can also specify a build script located
+in the Git repository using the `build-script` task parameter. This allows
+full control of building and testing, including any generation of artifacts.
+Note that some other task parameters have no effect when a custom build
+script is used, unless they are handled properly in the script. At a
+minimum, the custom script should place its outputs in the directory
+identified by `output-dir`.
+
+
+== Parameters
+
+[cols="1,1,2"]
+|===
+| Parameter | Default | Description
+
+| working-dir
+| .
+| Working directory. The path must be relative to the root of the repository,
+without leading `./` and trailing `/`.
+
+
+
+| gradle-additional-tasks
+| 
+| Additional gradle tasks to be passed to the gradle build. (default tasks called are `clean` and `build`).
+
+
+| gradle-options
+| --no-daemon --stacktrace
+| Options to be passed to the gradle build. (See ref: https://docs.gradle.org/7.4.2/userguide/command_line_interface.html#sec:command_line_debugging)
+
+
+| gradle-opts-env
+| -Dorg.gradle.jvmargs=-Xmx512M
+| Will be exposed to the build via `GRADLE_OPTS` environment variable. Specifies JVM arguments to use when starting the Gradle client VM. The client VM only handles command line input/output, so it is rare that one would need to change its VM options. You can still use this to change the settings for the Gradle daemon which runs the actual build by setting the according Gradle properties by `-D`. If you want to set the JVM arguments for the actual build you would do this via `-Dorg.gradle.jvmargs=-Xmx1024M` (See ref: https://docs.gradle.org/7.4.2/userguide/build_environment.html#sec:gradle_configuration_properties).
+
+
+| output-dir
+| docker
+| Path to the directory into which the resulting Java application jar should be copied, relative to `working-dir`. This directory may then later be used as Docker context for example.
+
+
+| cache-build
+| true
+| If enabled tasks uses or populates cache with the output dir contents (and artifacts) so that a build can be skipped if the `working-dir` contents did not change. You must set this to `"false"` if the build can be affected by files outside `working-dir`. See ADR caching-build-tasks for more details and workarounds.
+
+
+| build-extra-inputs
+| 
+| List of build source directories (as colon separated string) which in addition working-dir influence the build. These directories are relative to the repository root. If the contents in these directories change the cache is invalidated so that the build task will rebuild from scratch.
+
+
+| cached-outputs
+| docker
+| List of build output directories (as colon separated string) to be cached. These directories are relative to `working-dir`.
+
+
+| build-script
+| /usr/local/bin/build-gradle
+| Build script to execute. The link:https://github.com/opendevstack/ods-pipeline-gradle/blob/main/build/package/scripts/build.sh[default script] is located in the container image. If you specify a relative path instead, it will be resolved from the workspace. See the task definition for details how the build script is invoked.
+
+
+| gradle-build-dir
+| build
+| Path to the directory into which Gradle publishes its build.
+
+
+| postgres-image
+| postgres
+| Container image to use for the PostgreSQL sidecar.
+
+
+| postgres-password
+| 
+| Value to set for `POSTGRES_PASSWORD` (required). This sets the superuser password for PostgreSQL.
+
+
+| postgres-user
+| postgres
+| Value to set for `POSTGRES_USER`. This variable will create the specified user with superuser power and a database with the same name.
+
+
+| postgres-db
+| postgres
+| Value to set for `POSTGRES_DB`. Can be used to define a different name for the default database that is created when the image is first started.
+
+|===
+
+== Results
+
+[cols="1,3"]
+|===
+| Name | Description
+
+| build-reused-from-location
+| The cache location that the build task used. If caching is not enabled this will be an empty string.
+
+|===