[[Singleton_deployments]]
= Singleton deployments

ifdef::env-github[]
:tip-caption: :bulb:
:note-caption: :information_source:
:important-caption: :heavy_exclamation_mark:
:caution-caption: :fire:
:warning-caption: :warning:
endif::[]

WildFly 10 resurrected the ability to start a given deployment on a
single node in the cluster at any given time. If that node shuts down,
or fails, the application will automatically start on another node on
which the given deployment exists. Long time users of JBoss AS will
recognize this functionality as being akin to the
https://docs.jboss.org/jbossclustering/cluster_guide/5.1/html/deployment.chapt.html#d0e1220[HASingletonDeployer],
a.k.a. "
https://docs.jboss.org/jbossclustering/cluster_guide/5.1/html/deployment.chapt.html#d0e1220[deploy-hasingleton]",
feature of AS6 and earlier.

[[usage-singleton-deployments]]
== Usage

A deployment indicates that it should be deployed as a singleton via a
deployment descriptor. This can either be a standalone
`/META-INF/singleton-deployment.xml` file or embedded within an existing
jboss-all.xml descriptor. This descriptor may be applied to any
deployment type, e.g. JAR, WAR, EAR, etc., with the exception of a
subdeployment within an EAR. +
e.g.

[source,xml,options="nowrap"]
----
<singleton-deployment xmlns="urn:jboss:singleton-deployment:1.0" policy="foo"/>
----

The singleton deployment descriptor defines which
<<Singleton_subsystem,singleton policy>> should be used to deploy the
application. If undefined, the default singleton policy is used, as
defined by the singleton subsystem.

Using a standalone descriptor is often preferable, since it may be
overlaid onto an existing deployment archive. +
e.g.

[source,options="nowrap"]
----
deployment-overlay add --name=singleton-policy-foo --content=/META-INF/singleton-deployment.xml=/path/to/singleton-deployment.xml --deployments=my-app.jar --redeploy-affected
----


[[singleton-deployment-metrics]]
== Singleton Deployment metrics ==

The singleton subsystem registers a set of runtime metrics for each singleton deployment installed on the server.

is-primary:: Indicates whether the node on which the operation was performed is the primary provider of the given singleton deployment
primary-provider:: Identifies the node currently operating as the primary provider for the given singleton deployment
providers:: Identifies the set of nodes on which the given singleton deployment is installed.

e.g.

[source,options="nowrap"]
----
/subsystem=singleton/singleton-policy=foo/deployment=bar.ear:read-attribute(name=primary-provider)
----
