WildFly CLI Deployment Operations: Difference between revisions

From NovaOrdis Knowledge Base
Jump to navigation Jump to search
 
(81 intermediate revisions by the same user not shown)
Line 6: Line 6:


* [[WildFly CLI Operations#Subjects|WildFly CLI Operations]]
* [[WildFly CLI Operations#Subjects|WildFly CLI Operations]]
* [[WildFly Deployment Concepts|WildFly Deployment Concepts]]


=Overview=
=Overview=


Deployments are executed with the <tt>deploy</tt> command.  
Deployments and upgrades are performed in CLI with <tt>deploy</tt> command. Undeployments are triggered by the <tt>undeploy</tt> command. Both commands come with in-line help:


Undeployments are executed with the <tt>undeploy</tt> command.
deploy --help


In-line usage details can be obtained with:
undeploy --help


<pre>
The concepts behind deployment operations in standalone and domain mode are explained in {{Internal|WildFly Deployment Concepts|Deployment Concepts}}
deploy --help
undeploy --help
</pre>


=Deploy Usage=
=Standalone Mode=


<font color=red>TODO</font>


<pre>
=Domain Mode=
    deploy (file_path [--script=script_name] [--name=deployment_name]
                      [--runtime-name=deployment_runtime_name]
                      [--force | --disabled] [--unmanaged])
                        | --name=deployment_name
                      [--server-groups=group_name (,group_name)* | --all-server-groups]
                      [--headers={operation_header (;operation_header)*}]
</pre>


==Listing Artifacts in the Deployment Repository==


<tt>deploy</tt>  deploys the application designated by the <tt>file_path</tt> or enables an already existing but disabled deployment.
deploy [-l]


If executed w/o arguments, will list all the existing deployments.
Also, for both standalone and domain instances, the content of the artifact repository can be viewed by visiting the /deployment management model node.


ARGUMENTS
Actual deployments on domain server nodes can be viewed by navigating to the corresponding management model node:


  file_path        - the path to the application to deploy. Required in case the
  /host=''<host-name>''/server=''<server-name>''/deployment
                    deployment doesn't exist in the repository.
                    The path can be either absolute or relative to the current
                    directory.


--name            - the unique name of the deployment. If the file path
==Addition of a New Artifact to Repository and Deployment to Server Nodes==
                    argument is specified the name argument is optional with
                    the file name been the default value. If the file path
                    argument isn't specified then the command is supposed to
                    enable an already existing but disabled deployment, and in
                    this case the name argument is required.


--runtime-name    - optional, the runtime name for the deployment. This will
Content can be added to the deployment repository and pushed to server nodes in a single step. For new artifacts, their content is not known to the repository, so the path to the file must be specified in the "deploy" command.
                    form the basis for such things as default Java EE
                    application and module names. This would typically be the
                    same as --name, and if not specified the value used for
                    --name will be used. In some cases users may wish to have
                    two deployments with the same 'runtime-name' (e.g. two
                    versions of "example.war") both available in the management
                    configuration, in which case the deployments would need to
                    have distinct 'name' values but would have the same
                    'runtime-name'. Within an individual server, only one
                    deployment with a given 'runtime-name' can deployed.
                    However, multiple deployments with the same 'runtime-name'
                    can exist in the configuration, so long as only one is
                    enabled.


  --force          - if the deployment with the specified name already exists,
  deploy ''<file-path>'' ''<server-group-specification>''
                    by default, deploy will be aborted and the corresponding
                    message will printed. Switch --force (or -f) will force the
                    replacement of the existing deployment with the one
                    specified in the command arguments.


--disabled      - indicates that the deployment has to be added to the
When deploying on server nodes, the server group specification is required in domain mode, and it can be either "--all-server-groups" or a comma-separated list of server group names: "--server-groups=group1, group2, ...".  
                    repository disabled.


--unmanaged      - if this argument is not specified, the deployment content
{{Warn|Note that if a deployment is to be deployed on multiple server groups, all server groups must be specified in the same deployment command, following the --server-groups option. If the artifact is deployed to a server group first, with one command, and to another server group with a subsequent command, the second deployment attempt will complain. }}
                    will be copied (i.e. uploaded) to the server's deployment
                    repository before it is deployed. If the argument is
                    present, the deployment content will remain at and be
                    deployed directly from its original location specified with
                    the file_path.
                    NOTE: exploded deployments are supported only as unmanaged.


  --server-groups  - comma separated list of server group names the deploy
  deploy /tmp/servlet-example.war --all-server-groups
                    command should apply to. Either server-groups or
                    all-server-groups is required in the domain mode. This
                    argument is not applicable in the standalone mode.


--all-server-groups  - indicates that deploy should apply to all the available
The command stores the content in the artifact repository and then immediately pushes content to server nodes, as explained in [[WildFly_Deployment_Concepts#Domain_Deployment_Mechanics|Domain Deployment Mechanics]].
                        server groups. Either server-groups or all-server-groups
                        is required in domain mode. This argument is not
                        applicable in the standalone mode.


-l              - in case none of the required arguments is specified the
If the deployment on the target server nodes fails for some reason - unsatisfied dependencies, etc. the CLI issues
                    command will print all of the existing deployments in the
JBAS010839: Operation failed or was rolled back on all servers.
                    repository. The presence of the -l switch will make the
and the content is not added to the artifact repository.
                    existing deployments printed one deployment per line,
                    instead of in columns (the default).


--headers        - a list of operation headers separated by a semicolon. For
==Addition of a New Artifact to Repository==
                    the list of supported headers, please, refer to the domain
                    management documentation or use tab-completion.


--script        - optional, can appear only if the file_path points a cli
Artifacts can be placed in the repository without being pushed to server nodes, with:
                    archive. The value is the name of the script contained in a
                    cli archive to execute. If not specified, defaults to
                    'deploy.scr'. A cli archive is a zip archive containing
                    script(s) as well as artifacts or applications to deploy.
                    To be recognized as a cli archive, the extension of the
                    archive file should be '.cli'. The deploy command will
                    execute the script given by the --script argument. All paths
                    in the scripts are relative to the root directory in the cli
                    archive. The script is executed as a batch.


</font>
deploy ''<file-path>'' --disabled


=Undeploy Usage=
This operation will upload the content in the repository, but won't push it to any server node. To do that, the content will need to be deployed with a [[#Deploying_New_Repository_Content_to_Server_Nodes|separate command]].


<font color=red>
==Deployment of a New Repository Artifact to Server Nodes==
[domain@172.31.17.207:9999 /] undeploy --help
SYNOPSIS


    undeploy name [--server-groups=group_name (,group_name)* |
Content that has already been added to the domain repository can be pushed to server nodes by identifying the artifact by name, and specifying the target nodes. If the content was never deployed to the server nodes, no additional deploy command options are needed:
                  --all-relevant-server-groups] [--keep-content]
                  [--headers={operation_header (;operation_header)*}]


DESCRIPTION
deploy --name=''<artifact-name>''  ''<server-group-specification>''


    Undeploys the deployment with the given name and, depending on the
deploy --name=servlet-example.war --server-groups=group1
    arguments, removes its content from the repository.
    If the deployment name isn't specified, prints the list of all the existing
    deployments.


ARGUMENTS
Note that the existing artifact was previously deployed on at least one of the nodes specified as target, a deployment error will occur:


  name             - the name of the deployment to undeploy.
  [domain@localhost:9999 /] deploy --name=servlet-example.war --all-server-groups
{"JBAS014653: Composite operation failed and was rolled back. Steps that failed:" => {"Operation step-1" => "JBAS014803: Duplicate resource [
    (\"server-group\" => \"group1\"),
    (\"deployment\" => \"servlet-example.war\")
]"}}


--server-groups  - comma separated list of server group names the undeploy
==Upgrade of an Artifact in Repository and All Server Nodes on which the Old Version was Deployed==
                    command should apply to. Either server-groups or
                    all-relevant-server-groups is required in the domain mode.
                    This argument is not applicable in the standalone mode.


--all-relevant-server-groups  - indicates that undeploy should apply to all
A new version of an existing artifact can be added to the deployment repository and pushed to server nodes ''that are already running the current version of the artifact'' as part of one atomic operation. The path of the file containing the new version of the artifact must be specified in the "deploy" command.
                                  the server groups in which the deployment is
                    enabled. Either server-groups or all-relevant-server-groups
                    is required in domain mode. This argument is not applicable
                    in the standalone mode.


  --keep-content  - by default undeploy, besides disabling the deployment, also
  deploy --force ''<file-path>''  
                    removes its content from the repository. The presence of
                    --keep-content will only disable the deployment w/o removing
                    its content from the repository. This argument can be used
                    in both standalone and domain modes.
-l              - in case the deployment name isn't specified, the presence of
                    the -l switch will make the existing deployments printed one
                    deployment per line, instead of in columns (the default).


  --headers        - a list of operation headers separated by a semicolon. For
  deploy --force /tmp/servlet-example.war
                    the list of supported headers, please, refer to the domain
                    management documentation or use tab-completion.
                         
--path          - optional, points to a cli archive. The path can be either
                    absolute or relative to the current directory. A cli archive
                    is a zip archive containing script(s) as well as artifacts
                    or applications to deploy. To be recognized as a cli
                    archive, the extension of the archive file should be '.cli'.
                    The undeploy command will execute the script given by the
                    --script argument.                         
                         
--script        - optional, can appear only if the file_path points a cli
                    archive. The value is the name of the script contained in a
                    cli archive to execute. If not specified, defaults to
                    'undeploy.scr'. All paths in the scripts are relative to the
                    root directory in the cli archive. The script is executed as
                    a batch.


</font>
This operation updates the content in the repository, by placing the content under a different location, as the hash of the artifact is different, and pushes the content to the ''servers nodes on which the artifact was already deployed''.


=Standalone Mode=
It is not possible to specify a different target server group as part of an upgrade operations:
 
=Domain Mode=


Connect to the domain controller.
[domain@localhost:9999 /] deploy --force /tmp/servlet-example.war --all-server-groups
--force only replaces the content in the deployment repository and can't be used in combination with any of --disabled, --server-groups or --all-server-groups.


<pre>
More details on concepts behind a domain deployment are available in [[WildFly_Deployment_Concepts#Domain_Deployment_Mechanics|Domain Deployment Mechanics]].
deploy /loca/path/to/the/applicaton/artifact/test.war [destination]
</pre>


where <tt>destination</tt> can be:
==Undeployment==


* <tt>--all-server-groups</tt>
undeploy example.war --all-relevant-server-groups
* <tt>--server-groups=...</tt>

Latest revision as of 16:20, 21 September 2017

External

Internal

Overview

Deployments and upgrades are performed in CLI with deploy command. Undeployments are triggered by the undeploy command. Both commands come with in-line help:

deploy --help
undeploy --help

The concepts behind deployment operations in standalone and domain mode are explained in

Deployment Concepts

Standalone Mode

TODO

Domain Mode

Listing Artifacts in the Deployment Repository

deploy [-l]

Also, for both standalone and domain instances, the content of the artifact repository can be viewed by visiting the /deployment management model node.

Actual deployments on domain server nodes can be viewed by navigating to the corresponding management model node:

/host=<host-name>/server=<server-name>/deployment

Addition of a New Artifact to Repository and Deployment to Server Nodes

Content can be added to the deployment repository and pushed to server nodes in a single step. For new artifacts, their content is not known to the repository, so the path to the file must be specified in the "deploy" command.

deploy <file-path> <server-group-specification>

When deploying on server nodes, the server group specification is required in domain mode, and it can be either "--all-server-groups" or a comma-separated list of server group names: "--server-groups=group1, group2, ...".


Note that if a deployment is to be deployed on multiple server groups, all server groups must be specified in the same deployment command, following the --server-groups option. If the artifact is deployed to a server group first, with one command, and to another server group with a subsequent command, the second deployment attempt will complain.

deploy /tmp/servlet-example.war --all-server-groups

The command stores the content in the artifact repository and then immediately pushes content to server nodes, as explained in Domain Deployment Mechanics.

If the deployment on the target server nodes fails for some reason - unsatisfied dependencies, etc. the CLI issues

JBAS010839: Operation failed or was rolled back on all servers.

and the content is not added to the artifact repository.

Addition of a New Artifact to Repository

Artifacts can be placed in the repository without being pushed to server nodes, with:

deploy <file-path> --disabled

This operation will upload the content in the repository, but won't push it to any server node. To do that, the content will need to be deployed with a separate command.

Deployment of a New Repository Artifact to Server Nodes

Content that has already been added to the domain repository can be pushed to server nodes by identifying the artifact by name, and specifying the target nodes. If the content was never deployed to the server nodes, no additional deploy command options are needed:

deploy --name=<artifact-name>  <server-group-specification>
deploy --name=servlet-example.war --server-groups=group1

Note that the existing artifact was previously deployed on at least one of the nodes specified as target, a deployment error will occur:

[domain@localhost:9999 /] deploy --name=servlet-example.war --all-server-groups
{"JBAS014653: Composite operation failed and was rolled back. Steps that failed:" => {"Operation step-1" => "JBAS014803: Duplicate resource [
    (\"server-group\" => \"group1\"),
    (\"deployment\" => \"servlet-example.war\")
]"}}

Upgrade of an Artifact in Repository and All Server Nodes on which the Old Version was Deployed

A new version of an existing artifact can be added to the deployment repository and pushed to server nodes that are already running the current version of the artifact as part of one atomic operation. The path of the file containing the new version of the artifact must be specified in the "deploy" command.

deploy --force <file-path> 
deploy --force /tmp/servlet-example.war

This operation updates the content in the repository, by placing the content under a different location, as the hash of the artifact is different, and pushes the content to the servers nodes on which the artifact was already deployed.

It is not possible to specify a different target server group as part of an upgrade operations:

[domain@localhost:9999 /] deploy --force /tmp/servlet-example.war --all-server-groups 
--force only replaces the content in the deployment repository and can't be used in combination with any of --disabled, --server-groups or --all-server-groups.

More details on concepts behind a domain deployment are available in Domain Deployment Mechanics.

Undeployment

undeploy example.war --all-relevant-server-groups