From e61b5081d05b129c08bf8f38dcf45a86298bb156 Mon Sep 17 00:00:00 2001 From: Lagom Build Server Date: Sat, 23 Mar 2019 20:18:26 -0700 Subject: [PATCH] Updating 1.5.x documentation --- src/docs/1.5.x/java/Migration15.html | 18 ++++++++------ .../java/resources/releases/Migration15.md | 24 ++++++++++++------- src/docs/1.5.x/scala/Migration15.html | 18 ++++++++------ .../scala/resources/releases/Migration15.md | 24 +++++++++++++------ 4 files changed, 55 insertions(+), 29 deletions(-) diff --git a/src/docs/1.5.x/java/Migration15.html b/src/docs/1.5.x/java/Migration15.html index db7faf7f6ac..6623f52f35c 100644 --- a/src/docs/1.5.x/java/Migration15.html +++ b/src/docs/1.5.x/java/Migration15.html @@ -35,25 +35,29 @@

§Application extensions

-

Starting with Lagom 1.5 your application will include Akka management HTTP out of the box with health checks enabled by default. Akka management HTTP is a supporting tool for health checks, cluster bootstrap and a few other new features in Lagom 1.5.

-

Cluster formation now also supports Cluster Bootstrapping as a new way to form a cluster.

-

These new defaults may require at least two changes on your codebase. First, if you want to opt-in to cluster bootstrapping you must make sure you don’t set seed-nodes. seed-nodes always takes precedence over any other cluster formation mechanism. Second, if you use Cluster Bootstrapping, you will have to setup a discovery mechanism (see the Lagom Cluster reference guide for more details).

§Service Location

+

Starting with Lagom 1.5 your application will include Akka management HTTP out of the box with health checks enabled by default. Akka management HTTP is a supporting tool for health checks, cluster bootstrap and a few other new features in Lagom 1.5.

+

Cluster formation now also supports Cluster Bootstrapping as a new way to form a cluster.

+

These new defaults may require at least two changes on your codebase. First, if you want to opt-in to cluster bootstrapping you must make sure you don’t set seed-nodes. seed-nodes always takes precedence over any other cluster formation mechanism. Second, if you use Cluster Bootstrapping, you will have to setup a discovery mechanism (see the Lagom Cluster reference guide for more details).

§Service Location

You no longer have a ServiceLocator provided by the tooling libraries so you will have to provide one of your choice. We recommend using the new lagom-akka-discovery-service-locator which is implemented using Akka Service Discovery implementations.

-

Read the docs of the new lagom-akka-discovery-service-locator for details on how to setup the Akka Service Discovery method. For example,

+

Read the docs of the new lagom-akka-discovery-service-locator for details on how to setup the Akka Service Discovery method. For example,

akka {
   discovery {
    method = akka-dns
   }
 }

§Docker images and deployment specs

-

With the removal of ConductR or Lightbend Orchestration, the docker images and deployment specs will have to be maintained manually. Therefore the recommended migration is to take ownership of the Dockerfile, deployment scripts and orchestration specs.

-

We have written a comprehensive guide on how to deploy a Lagom application in Kubernetes or OpenShift.

+

With the removal of ConductR or Lightbend Orchestration, the docker images and deployment specs will have to be maintained manually. Therefore the recommended migration is to take ownership of the Dockerfile, deployment scripts and orchestration specs.

+

We have written a comprehensive guide on how to deploy a Lagom application in Kubernetes or OpenShift.

We also found that such maintenance can be made easier by using kustomize.

§Secrets

Lightbend Orchestration supported declaring secrets on build.sbt which user’s code could then read from a file in the pod. Starting from Lagom 1.5 there is no specific support for secrets and the recommendation is to use the default option suggested by each target orchestrator. For example, when deploying to Kubernetes or OpenShift declare the secret as an environment variable on your Deployment and inject the environment variable in your application.conf. For example:

my-database {
   password = "${DB_PASSWORD}"
 }

§Service Discovery

-

When opting in to Akka Cluster Bootstrapping as a mechanism for Cluster formation you will have to setup a Service Discovery method for nodes to locate each other.

§Upgrading a production system

+

When opting in to Akka Cluster Bootstrapping as a mechanism for Cluster formation you will have to setup a Service Discovery method for nodes to locate each other.

§Production Settings

+

New defaults have been added to the Lagom clustering configuration.

+

The first default configuration concerns how long a node should try to join an cluster. This is configured by the setting akka.cluster.shutdown-after-unsuccessful-join-seed-nodes. Lagom will default this value to 60 seconds. After that period, the Actor System will shutdown if it fails to join a cluster.

+

The second important change is the default value for lagom.cluster.exit-jvm-when-system-terminated. This was previously off, but we always recommended it to be on in production environments. As of Lagom 1.5.0, that setting defaults to on. When enabled, Lagom will exit the JVM when the application leave the cluster or fail to join the cluster. In Dev and Test mode, this setting is automatically set to off.

+

These two properties together are essential for recovering applications in production environments like Kubernetes. Without them, a Lagom node could reach a zombie state in which it wouldn’t provide any functionality but stay around consuming resources. The desired behavior for a node that is not participating on a cluster is to shut itself down and let the orchestration infrastructure re-start it.

§Upgrading a production system

There are no changes affecting a Production Upgrade. If you are running a Lagom 1.4 cluster you can perform a rolling upgrade, just make sure you are using the latest version on the 1.4.x series and, from that, you migrate to the latest version available of the 1.5.x series.

§Downtime upgrade

If you still haven’t adopted ddata as the cluster sharding mode and your application can tolerate a one time only downtime upgrade, we recommend you to enable ddata. Taking advantage of that downtime we recommend you also enable the serializers for akka.Done, akka.actor.Address and akka.remote.UniqueAddress. Once this upgrade is complete, further downtime is not required. Read all the details of this migration on the 1.4 Migration Guide

\ No newline at end of file diff --git a/src/docs/1.5.x/java/resources/releases/Migration15.md b/src/docs/1.5.x/java/resources/releases/Migration15.md index 113bf11a4ef..6f8c6ce1362 100644 --- a/src/docs/1.5.x/java/resources/releases/Migration15.md +++ b/src/docs/1.5.x/java/resources/releases/Migration15.md @@ -76,17 +76,17 @@ In particular, ConductR tooling and Lightbend Orchestration handled some or all #### Application extensions -Starting with Lagom 1.5 your application will include [[Akka management HTTP|Cluster#Akka-Management]] out of the box with [[health checks|Cluster#Health-Checks]] enabled by default. Akka management HTTP is a supporting tool for health checks, cluster bootstrap and a few other new features in Lagom 1.5. +Starting with Lagom 1.5 your application will include [[Akka management HTTP|Cluster#Akka-Management]] out of the box with [[health checks|Cluster#Health-Checks]] enabled by default. Akka management HTTP is a supporting tool for health checks, cluster bootstrap and a few other new features in Lagom 1.5. -Cluster formation now also supports [[Cluster Bootstrapping|Cluster#Joining-during-production-(Akka-Cluster-Bootstrap)]] as a new way to form a cluster. +Cluster formation now also supports [[Cluster Bootstrapping|Cluster#Joining-during-production-(Akka-Cluster-Bootstrap)]] as a new way to form a cluster. -These new defaults may require at least two changes on your codebase. First, if you want to opt-in to cluster bootstrapping you must make sure you don't set `seed-nodes`. `seed-nodes` always takes precedence over any other cluster formation mechanism. Second, if you use Cluster Bootstrapping, you will have to setup a [discovery](https://doc.akka.io/docs/akka/2.5/discovery/index.html) mechanism (see the [[Lagom Cluster reference guide|Cluster#Akka-Discovery]] for more details). +These new defaults may require at least two changes on your codebase. First, if you want to opt-in to cluster bootstrapping you must make sure you don't set `seed-nodes`. `seed-nodes` always takes precedence over any other cluster formation mechanism. Second, if you use Cluster Bootstrapping, you will have to setup a [discovery](https://doc.akka.io/docs/akka/2.5/discovery/index.html) mechanism (see the [[Lagom Cluster reference guide|Cluster#Akka-Discovery]] for more details). #### Service Location You no longer have a `ServiceLocator` provided by the tooling libraries so you will have to provide one of your choice. We recommend using the new [`lagom-akka-discovery-service-locator`](https://github.com/lagom/lagom-akka-discovery-service-locator) which is implemented using [Akka Service Discovery](https://doc.akka.io/docs/akka/current/discovery/index.html) implementations. -Read the [docs](https://github.com/lagom/lagom-akka-discovery-service-locator) of the new `lagom-akka-discovery-service-locator` for details on how to setup the Akka Service Discovery [method](https://doc.akka.io/docs/akka/current/discovery/index.html). For example, +Read the [docs](https://github.com/lagom/lagom-akka-discovery-service-locator) of the new `lagom-akka-discovery-service-locator` for details on how to setup the Akka Service Discovery [method](https://doc.akka.io/docs/akka/current/discovery/index.html). For example, ``` akka { @@ -98,9 +98,9 @@ akka { #### Docker images and deployment specs -With the removal of ConductR or Lightbend Orchestration, the docker images and deployment specs will have to be maintained manually. Therefore the recommended migration is to take ownership of the `Dockerfile`, deployment scripts and orchestration specs. +With the removal of ConductR or Lightbend Orchestration, the docker images and deployment specs will have to be maintained manually. Therefore the recommended migration is to take ownership of the `Dockerfile`, deployment scripts and orchestration specs. -We have written a [comprehensive guide](https://developer.lightbend.com/guides/openshift-deployment/lagom/index.html) on how to deploy a Lagom application in Kubernetes or OpenShift. +We have written a [comprehensive guide](https://developer.lightbend.com/guides/openshift-deployment/lagom/index.html) on how to deploy a Lagom application in Kubernetes or OpenShift. We also found that such maintenance can be made easier by using [kustomize](https://github.com/kubernetes-sigs/kustomize). @@ -114,12 +114,20 @@ my-database { } ``` - - ## Service Discovery When opting in to Akka Cluster Bootstrapping as a mechanism for Cluster formation you will have to setup a [[Service Discovery|Cluster#Akka-Discovery]] method for nodes to locate each other. +## Production Settings + +New defaults have been added to the Lagom clustering configuration. + +The first default configuration concerns how long a node should try to join an cluster. This is configured by the setting `akka.cluster.shutdown-after-unsuccessful-join-seed-nodes`. Lagom will default this value to 60 seconds. After that period, the Actor System will shutdown if it fails to join a cluster. + +The second important change is the default value for `lagom.cluster.exit-jvm-when-system-terminated`. This was previously `off`, but we always recommended it to be `on` in production environments. As of Lagom 1.5.0, that setting defaults to `on`. When enabled, Lagom will exit the JVM when the application leave the cluster or fail to join the cluster. In Dev and Test mode, this setting is automatically set to `off`. + +These two properties together are essential for recovering applications in production environments like Kubernetes. Without them, a Lagom node could reach a zombie state in which it wouldn't provide any functionality but stay around consuming resources. The desired behavior for a node that is not participating on a cluster is to shut itself down and let the orchestration infrastructure re-start it. + ## Upgrading a production system There are no changes affecting a Production Upgrade. If you are running a Lagom 1.4 cluster you can perform a rolling upgrade, just make sure you are using the latest version on the 1.4.x series and, from that, you migrate to the latest version available of the 1.5.x series. diff --git a/src/docs/1.5.x/scala/Migration15.html b/src/docs/1.5.x/scala/Migration15.html index 081f16b5aec..75524b4c8ed 100644 --- a/src/docs/1.5.x/scala/Migration15.html +++ b/src/docs/1.5.x/scala/Migration15.html @@ -30,12 +30,12 @@

§Application extensions

-

Starting with Lagom 1.5 your application will include Akka management HTTP out of the box with health checks enabled by default. Akka management HTTP is a supporting tool for health checks, cluster bootstrap and a few other new features in Lagom 1.5.

-

Cluster formation now also supports Cluster Bootstrapping as a new way to form a cluster.

-

These new defaults may require at least two changes on your codebase. First, if you want to opt-in to cluster bootstrapping you must make sure you don’t set seed-nodes. seed-nodes always takes precedence over any other cluster formation mechanism. Second, if you use Cluster Bootstrapping, you will have to setup a discovery mechanism (see the Lagom Cluster reference guide for more details).

§Service Location

+

Starting with Lagom 1.5 your application will include Akka management HTTP out of the box with health checks enabled by default. Akka management HTTP is a supporting tool for health checks, cluster bootstrap and a few other new features in Lagom 1.5.

+

Cluster formation now also supports Cluster Bootstrapping as a new way to form a cluster.

+

These new defaults may require at least two changes on your codebase. First, if you want to opt-in to cluster bootstrapping you must make sure you don’t set seed-nodes. seed-nodes always takes precedence over any other cluster formation mechanism. Second, if you use Cluster Bootstrapping, you will have to setup a discovery mechanism (see the Lagom Cluster reference guide for more details).

§Service Location

You no longer have a ServiceLocatorprovided by the tooling libraries so you will have to provide one of your choice. We recommend using the new lagom-akka-discovery-service-locator which is implemented using Akka Service Discovery implementations.

This means you will have to change you Loader code:

-
// before 
+
// before
   import com.lightbend.rp.servicediscovery.lagom.scaladsl.LagomServiceLocatorComponents
   override def load(context: LagomApplicationContext) =
     new MyApplication(context) with LagomServiceLocatorComponents
@@ -53,14 +53,18 @@ 
docs of the new lagom-akka-discovery-service-locator for more details.
§Docker images and deployment specs

-
With the removal of ConductR or Lightbend Orchestration, the docker images and deployment specs will have to be maintained manually. Therefore the recommended migration is to take ownership of the Dockerfile, deployment scripts and orchestration specs. 

-
We have written a comprehensive guide on how to deploy a Lagom application in Kubernetes or OpenShift. 

+
With the removal of ConductR or Lightbend Orchestration, the docker images and deployment specs will have to be maintained manually. Therefore the recommended migration is to take ownership of the Dockerfile, deployment scripts and orchestration specs.

+
We have written a comprehensive guide on how to deploy a Lagom application in Kubernetes or OpenShift.

 
We also found that such maintenance can be made easier by using kustomize.
§Secrets

 
Lightbend Orchestration supported declaring secrets on build.sbt which user’s code could then read from a file in the pod. Starting from Lagom 1.5 there is no specific support for secrets and the recommendation is to use the default option suggested by each target orchestrator. For example, when deploying to Kubernetes or OpenShift declare the secret as an environment variable on your Deployment and inject the environment variable in your application.conf. For example:

 
my-database {
   password = "${DB_PASSWORD}"
 }
 
§Service Discovery

-
When opting in to Akka Cluster Bootstrapping as a mechanism for Cluster formation you will have to setup a Service Discovery method for nodes to locate each other.
§Upgrading a production system

+
When opting in to Akka Cluster Bootstrapping as a mechanism for Cluster formation you will have to setup a Service Discovery method for nodes to locate each other.
§Production Settings

+
New defaults have been added to the Lagom clustering configuration.

+
The first default configuration concerns how long a node should try to join an cluster. This is configured by the setting akka.cluster.shutdown-after-unsuccessful-join-seed-nodes. Lagom will default this value to 60 seconds. After that period, the Actor System will shutdown if it fails to join a cluster.

+
The second important change is the default value for lagom.cluster.exit-jvm-when-system-terminated. This was previously off, but we always recommended it to be on in production environments. As of Lagom 1.5.0, that setting defaults to on. When enabled, Lagom will exit the JVM when the application leave the cluster or fail to join the cluster. In Dev and Test mode, this setting is automatically set to off.

+
These two properties together are essential for recovering applications in production environments like Kubernetes. Without them, a Lagom node could reach a zombie state in which it wouldn’t provide any functionality but stay around consuming resources. The desired behavior for a node that is not participating on a cluster is to shut itself down and let the orchestration infrastructure re-start it.
§Upgrading a production system

 
There are no changes affecting a Production Upgrade. If you are running a Lagom 1.4 cluster you can perform a rolling upgrade, just make sure you are using the latest version on the 1.4.x series and, from that, you migrate to the latest version available of the 1.5.x series.
§Downtime upgrade

 
If you still haven’t adopted ddata as the cluster sharding mode and your application can tolerate a one time only downtime upgrade, we recommend you to enable ddata. Taking advantage of that downtime we recommend you also enable the serializers for akka.Done, akka.actor.Address and akka.remote.UniqueAddress. Once this upgrade is complete, further downtime is not required. Read all the details of this migration on the 1.4 Migration Guide

\ No newline at end of file
diff --git a/src/docs/1.5.x/scala/resources/releases/Migration15.md b/src/docs/1.5.x/scala/resources/releases/Migration15.md
index f886e7c883b..a6b89bc67cc 100644
--- a/src/docs/1.5.x/scala/resources/releases/Migration15.md
+++ b/src/docs/1.5.x/scala/resources/releases/Migration15.md
@@ -1,4 +1,4 @@
-# Lagom 1.5 Migration Guide
+#  Lagom 1.5 Migration Guide
 
 This guide explains how to migrate from Lagom 1.4 to Lagom 1.5. If you are upgrading from an earlier version, be sure to review previous migration guides.
 
@@ -67,11 +67,11 @@ In particular, ConductR tooling and Lightbend Orchestration handled some or all
 
 #### Application extensions
 
-Starting with Lagom 1.5 your application will include [[Akka management HTTP|Cluster#Akka-Management]] out of the box with [[health checks|Cluster#Health-Checks]] enabled by default.  Akka management HTTP is a supporting tool for health checks, cluster bootstrap and a few other new features in Lagom 1.5. 
+Starting with Lagom 1.5 your application will include [[Akka management HTTP|Cluster#Akka-Management]] out of the box with [[health checks|Cluster#Health-Checks]] enabled by default.  Akka management HTTP is a supporting tool for health checks, cluster bootstrap and a few other new features in Lagom 1.5.
 
-Cluster formation now also supports [[Cluster Bootstrapping|Cluster#Joining-during-production-(Akka-Cluster-Bootstrap)]] as a new way to form a cluster. 
+Cluster formation now also supports [[Cluster Bootstrapping|Cluster#Joining-during-production-(Akka-Cluster-Bootstrap)]] as a new way to form a cluster.
 
-These new defaults may require at least two changes on your codebase. First, if you want to opt-in to cluster bootstrapping you must make sure you don't set `seed-nodes`. `seed-nodes` always takes precedence over any other cluster formation mechanism. Second, if you use Cluster Bootstrapping, you will have to setup a [discovery](https://doc.akka.io/docs/akka/2.5/discovery/index.html) mechanism (see the [[Lagom Cluster reference guide|Cluster#Akka-Discovery]] for more details). 
+These new defaults may require at least two changes on your codebase. First, if you want to opt-in to cluster bootstrapping you must make sure you don't set `seed-nodes`. `seed-nodes` always takes precedence over any other cluster formation mechanism. Second, if you use Cluster Bootstrapping, you will have to setup a [discovery](https://doc.akka.io/docs/akka/2.5/discovery/index.html) mechanism (see the [[Lagom Cluster reference guide|Cluster#Akka-Discovery]] for more details).
 
 #### Service Location
 
@@ -80,7 +80,7 @@ You no longer have a `ServiceLocator `provided by the tooling libraries so you w
 This means you will have to change you `Loader` code:
 
 ```scala
-// before 
+// before
   import com.lightbend.rp.servicediscovery.lagom.scaladsl.LagomServiceLocatorComponents
   override def load(context: LagomApplicationContext) =
     new MyApplication(context) with LagomServiceLocatorComponents
@@ -107,9 +107,9 @@ Read the [docs](https://github.com/lagom/lagom-akka-discovery-service-locator) o
 
 #### Docker images and deployment specs
 
-With the removal of ConductR or Lightbend Orchestration, the docker images and deployment specs will have to be maintained manually. Therefore the recommended migration is to take ownership of the `Dockerfile`, deployment scripts and orchestration specs.  
+With the removal of ConductR or Lightbend Orchestration, the docker images and deployment specs will have to be maintained manually. Therefore the recommended migration is to take ownership of the `Dockerfile`, deployment scripts and orchestration specs.
 
-We have written a [comprehensive guide](https://developer.lightbend.com/guides/openshift-deployment/lagom/index.html) on how to deploy a Lagom application in Kubernetes or OpenShift. 
+We have written a [comprehensive guide](https://developer.lightbend.com/guides/openshift-deployment/lagom/index.html) on how to deploy a Lagom application in Kubernetes or OpenShift.
 
 We also found that such maintenance can be made easier by using [kustomize](https://github.com/kubernetes-sigs/kustomize).
 
@@ -127,6 +127,16 @@ my-database {
 
 When opting in to Akka Cluster Bootstrapping as a mechanism for Cluster formation you will have to setup a [[Service Discovery|Cluster#Akka-Discovery]]  method for nodes to locate each other.
 
+## Production Settings
+
+New defaults have been added to the Lagom clustering configuration.
+
+The first default configuration concerns how long a node should try to join an cluster. This is configured by the setting `akka.cluster.shutdown-after-unsuccessful-join-seed-nodes`. Lagom will default this value to 60 seconds. After that period, the Actor System will shutdown if it fails to join a cluster.
+
+The second important change is the default value for `lagom.cluster.exit-jvm-when-system-terminated`. This was previously `off`, but we always recommended it to be `on` in production environments. As of Lagom 1.5.0, that setting defaults to `on`. When enabled, Lagom will exit the JVM when the application leave the cluster or fail to join the cluster. In Dev and Test mode, this setting is automatically set to `off`.
+
+These two properties together are essential for recovering applications in production environments like Kubernetes. Without them, a Lagom node could reach a zombie state in which it wouldn't provide any functionality but stay around consuming resources. The desired behavior for a node that is not participating on a cluster is to shut itself down and let the orchestration infrastructure re-start it.
+
 ## Upgrading a production system
 
 There are no changes affecting a Production Upgrade. If you are running a Lagom 1.4 cluster you can perform a rolling upgrade, just make sure you are using the latest version on the 1.4.x series and, from that, you migrate to the latest version available of the 1.5.x series.