Red Hat Training

A Red Hat training course is available for Red Hat OpenShift Application Runtimes

Release Notes for Thorntail 2

Red Hat OpenShift Application Runtimes 1

For use with Thorntail 2.5.0

Red Hat Customer Content Services

Abstract

This Release Note contains important information related to Thorntail 2.5.0

Preface

Date of release: 2019-10-15

Chapter 1. Required Infrastructure Component Versions

Red Hat does not provide support for components listed below, with the exception of components explicitly designated as supported.

Component nameVersion

Maven

3.6.0

Fabric8 Maven Plugin

4.3.0

JDK[a][b]

OpenJDK 8, OpenJDK 11[c]

Red Hat Enterprise Linux 7[d]

7.7

Red Hat Enterprise Linux 8[e]

8.0

OpenShift Container Platform (OCP)[f]

3.11, 4.1

Minishift

1.34.1 or later

CDK[g]

3.8.0

git

2.0 or later

oc command line tool

3.11 or later[h]

[a] A full JDK installation is required, as JRE does not provide tools for compiling Java applications from source.
[b] Red Hat OpenJDK is supported by Red Hat
[c] OpenJDK 9 is not supported by Red Hat.
[d] For deploying RHOAR-based applications on stand-alone RHEL in a production environment.
[e] For deploying RHOAR-based applications on stand-alone RHEL in a production environment.
[f] OCP is supported by Red Hat
[g] CDK is supported by Red Hat
[h] The version of the oc CLI tool should correspond to the version of OCP that you are using.

Chapter 2. Supported Thorntail Runtime Component Configurations and Integrations

The following resources define the supported configurations and integrations of Red Hat products with RHOAR Thorntail:

Chapter 3. Release components

3.1. Supported artifacts introduced in this release

The following supported artifacts are introduced in this release:

  • io.thorntail:ejb-mdb
  • org.jboss.resteasy:resteasy-client-microprofile

3.2. Technology Preview artifacts introduced in this release

No technology preview artifacts have been introduced in this release.

3.3. Artifacts removed in this release

The following artifact is removed in this release.

  • io.smallrye:smallrye-rest-client

3.4. Artifacts deprecated in this release

No artifacts have been declared deprecated in this release.

Chapter 4. Features

4.1. New features

MicroProfile 3.0 support

This release implements MicroProfile 3.0 by including the latest SmallRye artifacts. The following specifications have been upgraded to the versions listed below:

  • Health Check 2.0

    • This release introduces the @Liveness and @Readiness annotations, replacing the @Health annotation that is now deprecated (see also the Changed and deprecated features section below).
    • The /health/live and /health/ready endpoints are introduced in this release. The /health endpoint now serves as the unified endpoint for the @Health, @Liveness and @Readiness checks.
  • Metrics 2.0

    • The @ConcurrentGauge annotation is introduced in this release, as a replacement of the @Counter(monotonic = false) annotation (see also the Changed and deprecated features section below).
  • Rest Client 1.3

    • The Rest Client interfaces can now extend Closeable and AutoCloseable interfaces.
    • The RestClientBuilder now includes methods for SSL configuration.
MicroProfile JWT improvements

The microprofile-jwt fraction has received a number of improvements in this release. The changes are backwards compatible and not expected to break your application code.

  • The @LoginConfig annotation is no longer required, if you set the thorntail.microprofile.jwt.token.realm configuration property in your application. If you use the @LoginConfig annotation with the thorntail.microprofile.jwt.token.realm property set, ensure that the value of the realmName property of the @LoginConfig annotation matches the of the thorntail.microprofile.jwt.token.realm configuration property.
  • You can set thorntail.microprofile.jwt.enable configuration property value to false to disable the MicroProfile JWT authentication mechanism. The default value of the thorntail.microprofile.jwt.enable configuration property is true.
  • You must use the thorntail.microprofile.jwt.token.signer-pub-key-location to specify external key assets. Previously available alternate methods are deprecated. (For details, see Changed and deprecated features below.)
  • The thorntail.microprofile.jwt.path.groups configuration property can be used to select an arbitrary claim inside a JWT token to function as the groups claim expected by MicroProfile JWT. This is useful if no groups claim is present in the JWT token, but some other claim exists that contains the groups information. Unless the custom claim is a standard scope claim, its value must be formatted as an array of strings. Use the following syntax to reference a claim: path/to/claim.
  • You can use the thorntail.microprofile.jwt.claims.groups configuration property to provide a default value for the groups claim if the JWT token contains no groups information at all.
  • You can use the thorntail.microprofile.jwt.token.roles.map configuration property to inline the roles configuration in the Thorntail YAML configuration.
ejb-mdb fraction introduced
This release introduces the ejb-mdb fraction. This fraction enables you to deploy Message-Driven Beans, but it does not provide all the components required to set up a messaging infrastructure for your application. This means that you can not use this fraction to create a messaging server, but you can use it connect to an existing external messaging server, if you also provide the correct resource adapter.
Red Hat JBoss EAP 7.2.4.GA
EAP dependencies used by Thorntail have been updated and aligned with the 7.2.4.GA release of Red Hat JBoss Enterprise Application Platform.
Red Hat SSO 7.3.3.GA
This Thorntail release uses components provided by Red Hat Single Sign-On release version 7.3.3.GA.
Jaeger 0.34.0
The Jaeger client components have been updated to version 0.34.0 in this release of Thorntail.

4.2. Changed and deprecated features

Microprofile 3.0
  • Health Check 2.0

    • The @Health annotation is now deprecated. Use the @Liveness and @Readiness annotations instead.
    • The outcome and state fields in the JSON response format are replaced by the status field.

      Caution

      This is a breaking change. Ensure that you update your application code and external monitoring to avoid encountering issues with your applications after upgrading to the latest release of Thorntail.

  • Metrics 2.0

    • Some of the base metrics (defined by the MicroProfile Metrics 2.0 specification) changed their type from Counter to Gauge.
    • Some of the base metrics as well as some of the vendor metrics (provided by Thorntail) were renamed. Notably, the names of all accumulating counters now contain the suffix total.
    • In the OpenMetrics output format (formerly known as the Prometheus format), the metric scope and name are now separated by an underscore (_) symbol. This replaces the colon (:) symbol used as the separator in previous releases.
    • Metrics are no longer identified by their String name, but by a MetricID class. The MetricID consists of a String name and a set of key-value pairs called tags. In application code, this set of tags is represented as Map<String, String>.
    • The @Counted annotation no longer includes the monotonic parameter. Previously, the default value of the monotonic parameter was false. Now, the @Counter annotation always behaves as if the monotonic parameter was set to true. When you want your annotation to behave as when monotonic is set to false, use the @ConcurrentGauge annotation instead.

      Caution

      These are breaking changes. Ensure that you update your application code and external monitoring configuration to avoid encountering issues with your applications after upgrading to the latest release of Thorntail.

  • Rest Client 1.3

    • In this release, Thorntail replaces the MicroProfile Rest Client implementation from the SmallRye project, with the MicroProfile Rest Client implementation from RESTEasy. As a result of this change, all public APIs and SPIs that were previously present in the io.smallrye.restclient package, such as RestClientProxy, are now part of the org.jboss.resteasy.microprofile.client package. Ensure that you use the new package name in your code and logging configuration.
    • The specification now mandates that application/json is used as a default media type, if the Rest Client interface does not include the @Produces/@Consumes annotations. If you do not use the @Produces/@Consumes annotations in your client interfaces, this change might break your application.

      Caution

      These are breaking changes. Ensure that you update your application code and logging configuration to avoid encountering issues with your applications after upgrading to the latest release of Thorntail.

MicroProfile JWT

When specifying external key assets, the following referencing methods are now deprecated:

  • Using the file: and classpath: prefixes in the value of the thorntail.microprofile.jwt.token.signer-pub-key configuration property to point to the location of an external key asset.
  • Using the thorntail.microprofile.jwt.token.jwks-uri configuration property to refer to an external JWK Set.

Instead, use thorntail.microprofile.jwt.token.signer-pub-key-location configuration property to reference external key assets.

Using configuration properties in the thorntail.microprofile.jwtauth namespace is now deprecated. While this is not a breaking change, you are encouraged to update your configuration to use properties from the thorntail.microprofile.jwt namespace.

The wildfly-swarm.useUberJar system property

The wildfly-swarm.useUberJar system property previously used by the Thorntail Maven plugin is no longer recognized. To ensure that Thorntail Maven plugin runs in uberjar mode (as opposed to classpath mode), use the thorntail.useUberJar system property.

Caution

This is a breaking change. Ensure that you use the new name when running Maven to avoid encountering issues with your applications after upgrading to the latest release of Thorntail.

4.3. Technology preview

No technology preview features have been introduced in this release.

Chapter 5. Fixed issues

This RHOAR Thorntail release incorporates all bugfixes from the community release of Thorntail 2.5.0. Issues resolved in the community release are listed in the Thorntail 2.5.0 Release Notes.

5.1. Notable fixed non-security issues

5.1.1. MicroProfile Metrics: Application metric behavior does not conform to metrics specification

Description

Prior to this release, metrics would not be registered upon deployment, but would instead be registered when the metric method was first called. This issue was fixed and metrics are now registered correctly.

5.1.2. MicroProfile RestClient fails when using CompletionStage and @PathParam

Description

Prior to this release, invoking a MicroProfile RestClient interface method that returns CompletionStage and has a @PathParam parameters would result in an error. This issue was fixed and asynchronous MicroProfile RestClient invocations now work correctly.

5.1.3. SmallRye Config: Incorrect interpretation of escaped backslash ('\\') character sequence

Description

Due to a bug in the SmallRye Config component in the previous release, it wasn’t possible to use a backslash character to escape another backslash character. This could even result in wrong array conversion, if there was a comma character right after the double backslash sequence. See the example below for details. This issue has been resolved in this release and the behavior no longer occurs.

Example

thorntail:
  microprofile:
    config:
      config-sources:
        propertiesSource:
          properties:
            arrayProperty: element1,element2\\,element3,element41\,element42,ele\\ment5

The expected interpretation of the value entered in the arrayProperty in the example above is: element1, element2\, element3, element41,element42, ele\ment5

Instead, the arrayProperty value entered as shown in the example above was interpreted as: element1, element2\,element3, element41\,element42, ele\\ment5

5.1.4. Thorntail Topology OpenShift fraction does not work on OpenShift 4.1

Description

Prior to this release, using the Thorntail Topology fraction on an OpenShift 4.1 cluster resulted in the following exception at runtime:

Exception in thread "OkHttp Dispatcher" io.fabric8.kubernetes.clnt.v4_0.KubernetesClientException: Failure executing: GET at: https://xxx.xxx.xxx.xxx/apis/apps.openshift.io/v1/namespaces/xxxxxxxxx/deploymentconfigs/xxxxxxxxxxx?resourceVersion=1234567&watch=true. Message: Not Found

The behavior was caused by an issue with the OpenShift Java REST Client. The issues has been resolved in the 8.0 release of the OpenShift Java REST Client, and Thorntail now includes the new version.

5.2. Fixed security issues

For a list of resolved security issues, see Advisories related to this release.

Chapter 6. Known issues

6.1. MicroProfile Fault Tolerance: CDI contexts available in @Timeout methods

Description

If your application contains a @Timeout method that uses a contextual service , such as the @RequestScoped MyService shown in the example below, the contexts are not activated for that service.

@Inject
private MyService service;

@Timeout
public String doSomething() throws InterruptedException {
    return "Hello " + service.call();
}

The method is not @Asynchronous and should, therefore, be executed on the caller thread, which would make the Context and Dependency Injection (CDI) contexts available. However, the following debug message indicates that the contexts are not available:

2018-04-03 21:16:35,976 ERROR [io.undertow.request] (default task-1) UT005023: Exception handling request to /: org.jboss.weld.context.ContextNotActiveException: WELD-001303: No active contexts for scope type javax.enterprise.context.RequestScoped

Cause

This issue is caused by @Timeout methods always being invoked on a separate thread, even if they are not @Asynchronous.

Workaround

At the time of this release, there is no workaround available for this issue.

6.2. Harmless error message in application log: Missing org.glassfish:javax.el-api:3.0.1.b08-redhat-1

Description

If your application, or any of its dependencies, depends on the Java Expression Language, it will display the following warning message during startup.

Failed downloading org/glassfish/javax.el-api/3.0.1.b08-redhat-1/javax.el-api-3.0.1.b08-redhat-1.pom from https://repository.jboss.org/nexus/content/groups/public/. Reason:
org.eclipse.aether.transfer.ArtifactNotFoundException: Could not find artifact org.glassfish:javax.el-api:pom:3.0.1.b08-redhat-1 in jboss-public-repository-group (https://repository.jboss.org/nexus/content/groups/public/)
Failed downloading org/glassfish/javax.el-api/3.0.1.b08-redhat-1/javax.el-api-3.0.1.b08-redhat-1.pom from http://repo.gradle.org/gradle/libs-releases-local/. Reason:
org.eclipse.aether.transfer.ArtifactNotFoundException: Could not find artifact org.glassfish:javax.el-api:pom:3.0.1.b08-redhat-1 in gradle (http://repo.gradle.org/gradle/libs-releases-local)
Failed downloading org/glassfish/javax.el-api/3.0.1.b08-redhat-1/javax.el-api-3.0.1.b08-redhat-1.pom from https://repo.maven.apache.org/maven2/. Reason:
org.eclipse.aether.transfer.ArtifactNotFoundException: Could not find artifact org.glassfish:javax.el-api:pom:3.0.1.b08-redhat-1 in central (https://repo.maven.apache.org/maven2)
Failed downloading org/glassfish/javax.el-api/3.0.1.b08-redhat-1/javax.el-api-3.0.1.b08-redhat-1.pom from http://repo1.maven.org/maven2/. Reason:
org.eclipse.aether.transfer.ArtifactNotFoundException: Could not find artifact org.glassfish:javax.el-api:pom:3.0.1.b08-redhat-1 in central (http://repo1.maven.org/maven2)

The message is harmless and does not impact the functionality of the application.

Cause

The likely cause of this issue is related to the way dependency resolution works in Thorntail. During the dependency resolution phase, Thorntail ignores dependency exclusions, and thus pulls in javax.el-api, despite javax.el-api being excluded in the EAP BOM. Because it is interpreted as a valid dependency, it is indicated as missing due to being absent form the repository, which causes the error messages displayed in the build log.

Workaround

At the time of this release, there is no workaround available for this issue.

6.3. Connection between a RHEL 8-based database application and a RHEL 7-based MySQL 5.7 database fails due to TLS protocol version mismatch

Description

Attempting to open a TLS-secured connection using OpenSSL between an application container built on a RHEL 8-based OpenJDK builder image and a database container built on a RHEL 7-based MySQL 5.7 container image results in a connection failure due to a javax.net.ssl.SSLHandshakeException at runtime: For more detail, view the issue in JIRA.

...
Caused by: javax.net.ssl.SSLHandshakeException: No appropriate protocol (protocol is disabled or cipher suites are inappropriate)
...

Cause

The issue occurs due to a difference in the latest supported TLS protocol version between RHEL 7 and RHEL 8. The TLS implementation on RHEL 7 supports TLS protocol versions 1.0 (deprecated), 1.1, and 1.2. The TLS implementation on RHEL 8 also supports TLS protocol version 1.3, which is also the default TLS version used in RHEL 8-based builder images. This discrepancy may cause a TLS protocol version mismatch between application components while negotiating a TLS handshake, which in turn causes the connection between the application and database containers to fail.

Workaround

To prevent the issue described above, manually specify a TLS protocol version that is supported on both operating system versions in your database connection string. For example:

jdbc:mysql://testdb-mysql:3306/testdb?enabledTLSProtocols=TLSv1.2

6.4. Thorntail Arquillian Adapter ignores mvn -s settings.xml

Description

When attempting to pass additional repositories referenced in the setting.xml file to the Thorntail Arquillian adapter when executing integration tests and unit tests, the settings.xml file is not recognized and the additional repositories are not configured. This issue results in build failure due to missing artifacts, which, in turn, causes the tests to fail.

Workaround

To avoid this issue, manually edit the <configuration> sections under the Maven Surefire and/or Maven Failsafe plugin entries in the pom.xml file of your Maven project, manually specifying the <org.apache.maven.user-settings>${session.request.userSettingsFile.path}</org.apache.maven.user-settings> property to be exported when testing your application. See example for details:

pom.xml

<project>
  ...
  <build>
    <plugins>
      ...
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-failsafe-plugin</artifactId>
        <configuration>
          <org.apache.maven.user-settings>${session.request.userSettingsFile.path}</org.apache.maven.user-settings>
        </configuration>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-plugin</artifactId>
        <configuration>
          <systemPropertyVariables>
            <org.apache.maven.user-settings>${session.request.userSettingsFile.path}</org.apache.maven.user-settings>
          </systemPropertyVariables>
        </configuration>
      </plugin>
      ...
    </plugins>
  </build>
  ...
</project>

Chapter 7. Known issues affecting required infrastructure components

  • Fabric8 Maven Plugin Issue #1640: Pushing an image into a custom repository during an s2i build with FMP 4.1.0 results in a DuplicateKeyException.

    Affected components and component versions
    This issues affects Fabric8 Maven Plugin 4.1.0.
    Description
    Fabric8 Maven Plugin does not process ImageConfiguration unless ImageConfiguration also contains a BuildImageConfiguration. Without a recognizable BuildImageConfiguration, Fabric8 Maven Plugin repeatedly calls the s2i image generators to create another default ImageConfiguration that contains the expected BuildImageConfiguration. This results in more than one ImageConfiguration being specified for the given s2i build, which in turn results in a DuplicateKeyException when FMP attempts to push the image to the registry specified in the pom.xml configuration file. This leads to image build failures when a new image build is triggered by a change in the deployment configuration of a pod on OpenShift.
    Workaround

    To prevent Fabric8 Maven Plugin form generating a duplicate ImageConfiguration, place the image configuration inside a build section in the pom.xml configuration file of your project, as shown in the examples below. This in turn prevents the DuplicateKeyException when new image build is triggered by a change in the deployment configuration of the pod.

    <configuration>
      <images>
        <image>
          <name>
            artifactrepository.somecompany.com:18444/demo-boot/demo-boot:1.0
          </name>
            <build>
              <from>
                fabric8/S2I_BASE_IMAGE_NAME
              </from>
              <assembly>
                <basedir>
                  /deployments
                </basedir>
                <descriptorRef>
                  artifact-with-dependencies
                </descriptorRef>
              </assembly>
              <env>
                <JAVA_LIB_DIR>
                  /deployments
                </JAVA_LIB_DIR>
                <JAVA_MAIN_CLASS>
                  org.example.class.name.Main
                </JAVA_MAIN_CLASS>
              </env>
            </build>
          ...
        </image>
      </images>
      ...
    </configurtation>

Legal Notice

Copyright © 2019 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.