Skip to content

Commit

Permalink
Updating 1.5.x documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
Lagom Build Server authored and Play Team committed Mar 24, 2019
1 parent c225032 commit e61b508
Show file tree
Hide file tree
Showing 4 changed files with 55 additions and 29 deletions.
18 changes: 11 additions & 7 deletions src/docs/1.5.x/java/Migration15.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -35,25 +35,29 @@ <h1 id="Lagom-1.5-Migration-Guide"><a class="section-marker" href="#Lagom-1.5-Mi
<li>preparing the deployment specs for the target orchestrator</li>
<li>Secrets</li>
</ol><h4 id="Application-extensions"><a class="section-marker" href="#Application-extensions">§</a>Application extensions</h4>
<p>Starting with Lagom 1.5 your application will include <a href="Cluster.html#Akka-Management">Akka management HTTP</a> out of the box with <a href="Cluster.html#Health-Checks">health checks</a> 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. </p>
<p>Cluster formation now also supports <a href="Cluster.html#Joining-during-production-(Akka-Cluster-Bootstrap)">Cluster Bootstrapping</a> as a new way to form a cluster. </p>
<p>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&rsquo;t set <code>seed-nodes</code>. <code>seed-nodes</code> always takes precedence over any other cluster formation mechanism. Second, if you use Cluster Bootstrapping, you will have to setup a <a href="https://doc.akka.io/docs/akka/2.5/discovery/index.html">discovery</a> mechanism (see the <a href="Cluster.html#Akka-Discovery">Lagom Cluster reference guide</a> for more details). </p><h4 id="Service-Location"><a class="section-marker" href="#Service-Location">§</a>Service Location</h4>
<p>Starting with Lagom 1.5 your application will include <a href="Cluster.html#Akka-Management">Akka management HTTP</a> out of the box with <a href="Cluster.html#Health-Checks">health checks</a> 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.</p>
<p>Cluster formation now also supports <a href="Cluster.html#Joining-during-production-(Akka-Cluster-Bootstrap)">Cluster Bootstrapping</a> as a new way to form a cluster.</p>
<p>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&rsquo;t set <code>seed-nodes</code>. <code>seed-nodes</code> always takes precedence over any other cluster formation mechanism. Second, if you use Cluster Bootstrapping, you will have to setup a <a href="https://doc.akka.io/docs/akka/2.5/discovery/index.html">discovery</a> mechanism (see the <a href="Cluster.html#Akka-Discovery">Lagom Cluster reference guide</a> for more details).</p><h4 id="Service-Location"><a class="section-marker" href="#Service-Location">§</a>Service Location</h4>
<p>You no longer have a <code>ServiceLocator</code> provided by the tooling libraries so you will have to provide one of your choice. We recommend using the new <a href="https://github.com/lagom/lagom-akka-discovery-service-locator"><code>lagom-akka-discovery-service-locator</code></a> which is implemented using <a href="https://doc.akka.io/docs/akka/current/discovery/index.html">Akka Service Discovery</a> implementations.</p>
<p>Read the <a href="https://github.com/lagom/lagom-akka-discovery-service-locator">docs</a> of the new <code>lagom-akka-discovery-service-locator</code> for details on how to setup the Akka Service Discovery <a href="https://doc.akka.io/docs/akka/current/discovery/index.html">method</a>. For example, </p>
<p>Read the <a href="https://github.com/lagom/lagom-akka-discovery-service-locator">docs</a> of the new <code>lagom-akka-discovery-service-locator</code> for details on how to setup the Akka Service Discovery <a href="https://doc.akka.io/docs/akka/current/discovery/index.html">method</a>. For example,</p>
<pre class="prettyprint"><code>akka {
discovery {
method = akka-dns
}
}
</code></pre><h4 id="Docker-images-and-deployment-specs"><a class="section-marker" href="#Docker-images-and-deployment-specs">§</a>Docker images and deployment specs</h4>
<p>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 <code>Dockerfile</code>, deployment scripts and orchestration specs. </p>
<p>We have written a <a href="https://developer.lightbend.com/guides/openshift-deployment/lagom/index.html">comprehensive guide</a> on how to deploy a Lagom application in Kubernetes or OpenShift. </p>
<p>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 <code>Dockerfile</code>, deployment scripts and orchestration specs.</p>
<p>We have written a <a href="https://developer.lightbend.com/guides/openshift-deployment/lagom/index.html">comprehensive guide</a> on how to deploy a Lagom application in Kubernetes or OpenShift.</p>
<p>We also found that such maintenance can be made easier by using <a href="https://github.com/kubernetes-sigs/kustomize">kustomize</a>.</p><h4 id="Secrets"><a class="section-marker" href="#Secrets">§</a>Secrets</h4>
<p>Lightbend Orchestration supported declaring <a href="https://developer.lightbend.com/docs/lightbend-orchestration/current/features/secrets.html">secrets</a> on <code>build.sbt</code> which user&rsquo;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 <a href="https://kubernetes.io/docs/concepts/configuration/secret/#using-secrets-as-environment-variables">declare the secret as an environment variable</a> on your <code>Deployment</code> and inject the environment variable in your <code>application.conf</code>. For example:</p>
<pre class="prettyprint"><code>my-database {
password = &quot;${DB_PASSWORD}&quot;
}
</code></pre><h2 id="Service-Discovery"><a class="section-marker" href="#Service-Discovery">§</a>Service Discovery</h2>
<p>When opting in to Akka Cluster Bootstrapping as a mechanism for Cluster formation you will have to setup a <a href="Cluster.html#Akka-Discovery">Service Discovery</a> method for nodes to locate each other.</p><h2 id="Upgrading-a-production-system"><a class="section-marker" href="#Upgrading-a-production-system">§</a>Upgrading a production system</h2>
<p>When opting in to Akka Cluster Bootstrapping as a mechanism for Cluster formation you will have to setup a <a href="Cluster.html#Akka-Discovery">Service Discovery</a> method for nodes to locate each other.</p><h2 id="Production-Settings"><a class="section-marker" href="#Production-Settings">§</a>Production Settings</h2>
<p>New defaults have been added to the Lagom clustering configuration.</p>
<p>The first default configuration concerns how long a node should try to join an cluster. This is configured by the setting <code>akka.cluster.shutdown-after-unsuccessful-join-seed-nodes</code>. Lagom will default this value to 60 seconds. After that period, the Actor System will shutdown if it fails to join a cluster.</p>
<p>The second important change is the default value for <code>lagom.cluster.exit-jvm-when-system-terminated</code>. This was previously <code>off</code>, but we always recommended it to be <code>on</code> in production environments. As of Lagom 1.5.0, that setting defaults to <code>on</code>. 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 <code>off</code>.</p>
<p>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&rsquo;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.</p><h2 id="Upgrading-a-production-system"><a class="section-marker" href="#Upgrading-a-production-system">§</a>Upgrading a production system</h2>
<p>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.</p><h3 id="Downtime-upgrade"><a class="section-marker" href="#Downtime-upgrade">§</a>Downtime upgrade</h3>
<p>If you still haven&rsquo;t adopted <code>ddata</code> as the cluster sharding mode and your application can tolerate a <em>one time only</em> downtime upgrade, we recommend you to enable <code>ddata</code>. Taking advantage of that downtime we recommend you also enable the serializers for <code>akka.Done</code>, <code>akka.actor.Address</code> and <code>akka.remote.UniqueAddress</code>. Once this upgrade is complete, further downtime is not required. Read all the details of this migration on the <a href="Migration14.html#Rolling-upgrade">1.4 Migration Guide</a></p>
24 changes: 16 additions & 8 deletions src/docs/1.5.x/java/resources/releases/Migration15.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand All @@ -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).

Expand All @@ -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.
Expand Down
Loading

0 comments on commit e61b508

Please sign in to comment.