soamdeploy

The command to deploy, remove, and display information about service packages for consumers. This command is not applicable to IBM® Spectrum Conductor.

Important: The egodeploy command is also available for working with service packages for consumers. For IBM Spectrum Symphony, use the soamdeploy command instead, as described here. For IBM Spectrum Conductor, use the egodeploy command instead.

Synopsis

soamdeploy
soamdeploy subcommand [options ]
soamdeploy subcommand -h
soamdeploy -h
soamdeploy -V

Description

Use the soamdeploy command to deploy, verify, and delete service packages.
-h
Prints command usage to stdout and exits.
-V
Prints product version to stdout and exits.

Subcommand synopsis

add package_name -p package_file | -c consumer_ID [-f ] [-n ] [-u  user_name ] [-x  password ]
push package_name -c package_consumer_ID [[-r resource_group] | [-C deploy_ consumer_ID -r resource_group]] [-t host_name] [-T timeout] [-l limit] [-b] [-n] [-U] [-u user_name] [-x password ]
remove package_name -c consumer_ID [-f ] [-u user_name ] [-x password ]
view package_name -c consumer_ID [-d] [-u user_name ] [-x password ]

add package_name -p package_file -c consumer_ID [-f] [-n] [-u user_name] [-x password]

Copies the specified package to the central repository.

When you add a package with a new package name to the repository, the package file is stored in the repository. When you add a package with an existing package name:

Note: If a package is shared among multiple applications, then the following points apply to each applications.
  • The package in the repository is replaced.
  • If the package is being used by an enabled application, workload continues to run with the next scheduled task using the updated service package.

When a new session requests the service in the package, the package is deployed and uncompressed on to compute hosts on-demand.

package_name
Name you want to assign to the service package. The service package name must be unique within a consumer, with a maximum of 120 characters. Valid characters are alphanumeric characters, periods, underscores (_), and n-dashes (-). Spaces are not allowed.
Notes:
  • To ensure service package deployment does not fail because of file name issues, verify that files in the /tmp directory do not have the same name as the consumer.
  • On Windows, the maximum length for a directory path is 260 characters. Do not use too long a value for package_name since the repository service uses the Installation_top\eservice\rs\.cache\consumer_ID\package_name.pkg\ directory as the work directory for the package.
-p package_file
Path and file of the service package to deploy.
-c consumer_ID
Consumer for which to deploy the service packages. Only applications registered to this consumer and sub-consumers in the consumer tree can use the service packages.

Enclose the consumer ID in double quotation marks (" ") if it contains spaces.

If a service package is deployed to the root consumer ("/"), the package is shared by the leaf consumers.

Note: For IBM Spectrum Symphony Developer Edition, -a application profile file name can be used instead of -c consumer_ID.
-f
Forcefully deploys the service package without prompting for confirmation. Note that if you use this option and the package was previously deployed, any running workload is terminated without prompting. Use this option when you are issuing soamdeploy add from within a script, and do not want the script to stop running to respond to prompts.
-n
Turns off package verification during deployment. Use this option if you are deploying the same package repeatedly and you know it is valid, and deployment takes a long time because of the verification process.
-u user_name
Specifies the name of the user to connect to IBM Spectrum Symphony for this command. If you are already logged on to IBM Spectrum Symphony using soamlogon, for this command only the user name specified here overrides the user name entered in soamlogon.

To add packages at the root consumer level, you must be a cluster administrator. To add packages to a leaf consumer, you can be a cluster administrator or consumer administrator. If the package must be added to a leaf on the consumer tree, the consumer administrator can be given access rights to this leaf.

-x password
Specifies the user password to connect to IBM Spectrum Symphony for this command.

Examples: Windows

Deploy a service package

Deploy the service package for consumer /SampleApplications/SOASamples:
soamdeploy add Mypackage -p sampleService.zip -c /SampleApplications/SOASamples

Examples: Linux®

Deploy a service package

Deploy the service package for consumer /SampleApplications/SOASamples:
soamdeploy add Mypackage -p sampleService.tar.gz -c /SampleApplications/SOASamples

Update a service package

Update and replace the service package:
soamdeploy add Mypackage -p sampleService.tar.gz -c /SampleApplications/SOASamples

push package_name -c package_consumer_ID [[-r resource_group] | [-C deploy_consumer_ID -r resource_group]] [-t host_name] [-T timeout] [-l limit] [-b] [-n] [-U] [-u user_name] [-x password]

Initiates deployment of the package and its dependencies to the specified resource group.

This is an administrative subcommand. You must log on as cluster or consumer administrator before you can issue this subcommand.

This command runs a remote command (soamdeploy download) on all target hosts to download service packages on hosts which are running unrelated workload without using workload slots. Use this command to pre-deploy service packages to the cluster, enabling large packages to be predeployed during off hours to prevent network bandwidth issues for other users.

Restriction:
  • Only one instance of soamdeploy push can run at a time in the cluster. If multiple push operations are required, they must be done in series.
  • The soamdeploy push command runs only on available hosts in the cluster. If new hosts become available, the command must be re-run to deploy the package to these hosts.
package_name
Name of the service package to be downloaded to the specified compute hosts.
-c package_consumer_ID
Consumer to which the package is to be deployed. Only applications registered to this consumer and sub-consumers in the consumer tree can use the service packages. Enclose the consumer ID in double quotation marks (" ") if it contains spaces.
-r resource_group
Resource group containing all target hosts.

If -r is specified with –C, this resource group is used for allocation. If -r is specified without –C, it is used only to get the host lists.

If -r and -t are not specified, the package is pushed to all hosts in this resource group.

-C deploy_consumer_ID
Consumer from which to get slots to run the remote command. Requires the full consumer path, which must be to a leaf consumer and must be preceded by a slash (for example, /ClusterServices/EGOClusterServices).
Note: Ensure that the consumer has the appropriate privileges/permissions to run the command on a remote host. Only cluster administrators have access to all target hosts.

If this -C option is specified, also specify a resource group by using -r resource_group.

-t host_name
Host on which to install the package.
-T timeout
Maximum time (in seconds) that the soamdeploy download command can take to download and install the package on each compute host, beyond which the package installation times out. By default, a timeout is not configured.
-l limit
Maximum number of concurrent hosts which are actively downloading and installing packages. By default, the number of concurrent downloads is 4.

This option limits the number of soamdeploy download commands running on the cluster at a time. Keep this number low to avoid blocking workload from running soamdeploy download, as only one instance of the command can run at a time.

-b
Pushes the service package to all compute hosts in the background (non-blocking) mode.
  • In the blocking mode (default), soamdeploy push exits only after the remote deployment command runs on all available hosts in the specified resource group and all download commands are complete. It uses the deploy_consumer_ID /ClusterServices/EGOClusterServices to get slots and provides the execution user for the creation of the package directory. To change the deploy consumer ID, specify the -C option.

    As an administrator, you can leverage this blocking behavior to string together a series of push deployment commands in a script that run sequentially. The blocking operation lists the final run status for all hosts: an exit status of 0 if all soamdeploy operations were successful and -1 if there was at least one error.

  • In the non-blocking mode (specified with -b), soamdeploy push exits once the remote operation is initiated at the repository server. In this case, use rsdeploy status to check the status of this operation and rsdeploy remove to remove the deployment package from the repository server. It returns an exit status of 0 if the operation was initiated successfully and -1 if there was an error.
-n
Turns off dependency deployment for push deploy. For example, if package A depends on package B, and package A is being pushed deployed, by default, package B will be push deployed. The -n option is optional; if specified, package B will not be push deployed.
-U
Undoes the push operation so that a package and its dependencies are removed. For example, if you have two packages, by default, both package A and package B will be removed with this option. Note that if you specify both the -n and -U options, only the package, not its dependency, will be removed (that is, only package A will be removed).
-u user_name
Name of the user to connect to IBM Spectrum Symphony for this command. If you are already logged on to IBM Spectrum Symphony using soamlogon, for this command only the user name specified here overrides the user name entered in soamlogon.
-x password
User password to connect to IBM Spectrum Symphony for this command. If you are already logged on to IBM Spectrum Symphony using soamlogon, for this command only the password specified here overrides the password entered in soamlogon.

Examples

Push deploy a service package in default blocking mode

  1. Add the package to the repository:
    soamdeploy add MyPackage -p MyPackage.zip -c /SampleApplications/SOASamples
  2. Push deploy the service package for consumer /SampleApplications/SOASamples: 
    soamdeploy push MyPackage -c /SampleApplications/SOASamples
    Logging on to RS server with user Admin and consumer /SampleApplications/SOASamples.
    Successfully logged on to RS server.
    Starting to install package MyPackage
    Successfully started package install
    HOST                 STATUS
    host1.example.com    INSTALLED
    host2.example.com    INSTALLED

Push deploy a service package in non-blocking mode

  1. Add the package to the repository:
    soamdeploy add MyPackage -p MyPackage.zip -c /SampleApplications/SOASamples
  2. Push deploy the service package for consumer /SampleApplications/SOASamples:
    soamdeploy push MyPackage -c /SampleApplications/SOASamples -b
    Logging on to RS server with user Admin and consumer /SampleApplications/SOASamples.
     Successfully logged on to RS server.
     Starting to install package MyPackage
     Successfully started package install

View status of package deployment in non-blocking mode

  1. Run the rsdeploy status command:
    C:\EGO>rsdeploy status MyPackage
  2. (Optional) Use the status filter to list all errors:
    C:\EGO>rsdeploy status MyPackage -s error

Remove package in non-blocking mode

  • Run the rsdeploy remove command to remove the package and status information from the repository server:
    C:\EGO>rsdeploy remove MyPackage
  • Run the soamdeploy remove command to remove the package from the compute host:
    C:\EGO>soamdeploy remove MyPackage

remove package_name -c consumer_ID [-f] [-u user_name] [-x password]

Deletes the specified service package from the central repository under the specified consumer.
Attention: The package is removed only from the central repository and is not removed from the remote deploy directory until another package is uploaded to the same consumer on that host.

You cannot remove a package if registered applications are using the package. Unregister the applications with soamunreg before attempting to remove the package.

Note: If your application no longer needs to reference the service package and you do not want to unregister it, you can remove reference to the package in the application profile and update the application profile with the soamreg command.
package_name
Name you assigned to the service package during deployment.
-c consumer_ID
Consumer from which to remove the service package.

Enclose the consumer ID in double quotation marks (" ") if it contains spaces.

-f
Forcefully removes the service package without prompting for confirmation. Use this option when you are issuing soamdeploy remove from within a script, and do not want the script to stop running to respond to prompts.
-u user_name
Specifies the name of the user to connect to IBM Spectrum Symphony for this command. If you are already logged on to IBM Spectrum Symphony using soamlogon, for this command only the user name specified here overrides the user name entered in soamlogon.

To remove packages from the root consumer level, you must be a cluster administrator. To remove packages from a leaf consumer, you can be a cluster administrator or a consumer administrator. If the package must be removed from a leaf on the consumer tree, the consumer administrator can be given access rights to this leaf.

-x password
Specifies the user password to connect to IBM Spectrum Symphony for this command. If you are already logged on to IBM Spectrum Symphony using soamlogon, for this command only the password specified here overrides the password entered in soamlogon.

Remove a service package

Remove the service package for consumer /SampleApplications/SOASamples

soamdeploy remove Mypackage -c /SampleApplications/SOASamples

view [package_name] -c consumer_ID [-d ] [-u user_name] [-x password]

Lists all deployed service packages for the specified consumer.
package_name
Name you assigned to the service package during deployment.
-d
Displays the dependencies for the package under the consumer. For example, if package A depends on package B, or if package B depends on package A, specifying the -d option displays this information. If there are no dependencies for any packages under the consumer, this command does not display any dependency information.
-c consumer_ID
Displays a list of all deployed service packages for the specified consumer. Enclose the consumer ID in double quotation marks (" ") if it contains spaces.
Note: For IBM Spectrum Symphony Developer Edition, -c consumer_ID is optional.
-u user _name
Specifies the name of the user to connect to IBM Spectrum Symphony for this command. If you are already logged on to IBM Spectrum Symphony using soamlogon, for this command only the user name specified here overrides the user name entered in soamlogon.
-x password
Specifies the user password to connect to IBM Spectrum Symphony for this command. If you are already logged on to IBM Spectrum Symphony using soamlogon, for this command only the password specified here overrides the password entered in soamlogon.

View deployed packages for consumer /SampleApplications/SOASamples

soamdeploy view -c /SampleApplications/SOASamples