appinstance

The egosh appinstance sub-command registers and manages application instances in your cluster.

Note: The ascd web server is by default set up for SSL communication during installation. To manage application instances using the egosh appinstance command with SSL, define the environment variables required for SSL based on your certificate type. These variables are defined by default in the environment profile scripts ($EGO_TOP/ascd/conf/profile.ascd and $EGO_TOP/ascd/conf/cshrc.ascd) on Linux® hosts.

EGO_SSL_EGOSH_CAINFO: Specify the path to the CA-signed certificate. The supported file format is PEM.
If you are using the default self-signed certificate, this variable is set by default to $EGO_TOP/wlp/usr/shared/resources/security/cacert.pem.
EGO_SSL_EGOSH_VERIFYHOST: Enables or disables verification of the Common Name (CN) field in the certificate against the host name (displayed in the Description field of the egosh client view ASCD_REST_BASE_URL_1 command). This variable is set by default to Y.
If the CN field in the CA-signed certificate does not match the host name or if you want to avoid untrusted connection issues when using the default self-signed certificate, set this variable to N to disable verification. Disabling SSL verification is not secure and is not recommended.
EGO_SSL_EGOSH_VERIFYPEER: Enables or disables verification of the peer SSL certificate. This variable is set by default to Y.
To disable verification of the peer SSL certificate or if you want to avoid untrusted connection issues when using the default self-signed certificate, set this variable to N. Disabling SSL verification is not secure and is not recommended.

appinstance add -a `app_instance_name` -c `consumer_name` -f `app_template_file` [-p `parameter` [-p `parameter`]]

Adds a new application instance. To add a new application instance, you must be a cluster administrator or have the Application Instance Configure, the Resource Groups View, and the Resource Plans View permissions. Resource Groups View is required for slot-based scheduling and Resource Plans View is required for multidimensional scheduling.

While creating a new application instance, if you specify packages to be deployed, your application instance moves to the Registered state and is ready to be deployed. If you do not require any packages to be deployed, your application instance moves directly from the Registered to the Ready state.

-a app_instance_name

Specifies a name to identify the application instance.

-p consumer_name

Specifies the top-level consumer to be associated with the application instance.

Specify the unique consumer name, or the full path to the consumer name, as follows:

/top-level_consumer_name/. . . /leaf_consumer_name

-f app_template_file

Specifies the application template (in YAML) containing the parameter, resource, and output definitions to register the application instance.

Note: If you define a service package in your application template, remember to upload your package to the repository server (using egodeploy) before running this command.

-p parameter

Specifies optional parameters to add the application instance, such as packages to be associated with the application instance. Once your package is deployed, your application instance moves from the Registered to Deploying to the Ready state.

To specify a (.bin) package to be associated with the application instance, enter (for example):
-p bin-package-name=package1

Before you specify the package, ensure that the package is uploaded to the top-level consumer or its parent consumer.
To specify a resource group for the application instance, enter (for example):
–p zk-rg=ComputeHosts

appinstance delete {-a `app_instance_name` | -i `uuid`} [-U [-t `timeout`]]

Deletes an application instance. To delete an application instance, you must be a cluster administrator or have the Application Instance Configure and EGO Services Manage permissions.

You can delete an application instance which is in the Registered, Register Error, Ready, or Deploy Error states. If your application instance includes packages and is in the Ready or Deploy Error state, you can delete it as well as undeploy it.

-a app_instance_name: Specifies the name of the application instance to delete.
-i uuid: Specifies the UUID of the application instance to delete.
-U: When your application instance includes packages and is in the Ready or Deploy Error state, specifies that the application instance be deleted as well as undeployed.
-t timeout: When -U is specified, optionally specifies a timeout (in seconds) for the undeploy operation. If the undeploy does not complete within the specified timeout, the operation is terminated.

appinstance deploy {-a `app_instance_name` | -i `uuid`} [-t `timeout`]

Deploys an application instance (associated with a package). To deploy an application instance, you must be a cluster administrator or have the Application Instance Control permission.

Deploy an application instance with packages again if you want to add new hosts or if you are upgrading your application to deploy any new packages. You can deploy an application instance in the Registered, Deploy Error, Processing, Started, or Ready state.

-a app_instance_name: Specifies the name of the application instance to deploy.
-i uuid: Specifies the UUID of the application instance to deploy.
-t timeout: Optionally specifies a timeout (in seconds) for the deploy operation. If the deploy does not complete within the specified timeout, the operation is terminated.

appinstance export {-a `app_instance_name` | -i `uuid`} -t `app_template_name` [-f]

Exports the application template of an existing application instance. To export an application template, you must be a cluster administrator or have the Application Instance View permission.

If you make changes to the application instance during runtime, those changes will not reflect in the exported template. For example, any changes involving resource requirements after the application instance is started, scaling services belonging to the application instance, and updating service properties using the service profile or RESTful APIs will not appear in the exported template.

-a app_instance_name: Specifies the name of the application instance whose application template is to be exported.
-i uuid: Specifies the UUID of the application instance whose application template is to be exported.
-t app_template_name: Specifies the name of the application template to be exported as an .yaml file.
-f: Specifies that the application template to be exported overwrite an application template of the same name that exists on the user's computer. If you do not specify this option, the system will prompt you for confirmation.

appinstance list [-l] [-ll]

Lists all application instances in the cluster. To view a list of application instances, you must be a cluster administrator or have the Application Instance View permission.

-l: Optionally provides the same information with a longer name field if some are truncated when -l is not specified.
-ll: Optionally provides the same information as the -l option, in comma-separated values (CSV) format.

appinstance modify {-a `app_instance_name` | -i `uuid`} -f `app_template_name` [-p `parameter`[-p `parameter`]] [-d[-t `timeout`]]

Modifies definitions for an application instance that is in the Registered, Ready, or Deploy Error state. To modify an existing application instance, you must be a cluster administrator or have the Application Instance Configure, Resource Groups View, and Resource Plans View permissions. This subcommand is not supported when your cluster is installed to a shared file system.

While you can modify most parameter, resource, and output definitions for an existing application instance, you cannot modify its name, top-level consumer, and execution user.

-a app_instance_name

Specifies the name of the application instance to modify.

-i uuid

Specifies the UUID of the application instance to modify.

-f app_template_name

Specifies the application template (in YAML) with updated definitions for the application instance.

-p parameter

Specifies optional parameters, such as resource groups or packages to be associated with the application instance, to modify for the application instance.

To specify a (.bin) package to be associated with the application instance, enter (for example):
-p bin-package-name=package3

Before you specify the package, ensure that the updated package is uploaded to the top-level consumer or its parent consumer.
To specify a resource group for the application instance, enter (for example):
-p zk-rg=ComputeHosts

-d

If the application instance includes packages and those packages are modified to use either new or updated ones, specifies to start deploying the application instance. If you do not specify this parameter, ensure that you manually deploy the application instance later.

-t timeout

When -d is specified, optionally specifies a timeout (in seconds) for deployment. If deployment does not complete within the specified timeout, the operation is terminated.

appinstance scale {-a `app_instance_name` | -i `uuid`} -s `service_name` [-f] {-m `min` | -M `max`} [-t `terminate_instance`[,`terminate_instance`...]]

Scale an application instance service. To scale an application instance service, you must be a cluster administrator or have the Application Instance Configure and Services Manage permissions.

Scale a service to adjust the load during peak and low periods by increasing or decreasing the maximum or minimum number of service instances. You can scale a service in the Started, Tentative, Frozen, or Allocating states.

-a app_instance_name: Specifies the name of the application instance for scaling.
-i uuid: Identifies the UUID of the application instance for scaling.
-s service_name: Specifies the name of the application instance service to be scaled.
-f: Specifies the service to be scaled down even if decommissioning of the stateful service to remove its data fails.
-m min: Specifies the minimum number of allocated service instances, as an integer or as a percentage of the total number of slots in the resource group. To specify the minimum number as a percentage, add % to the end of the integer. For minimum and maximum number, at least one must be specified.
-M max: Specifies the maximum number of allocated service instances, as an integer or as a percentage of the total number of slots in the resource group. To specify the maximum number as a percentage, add % to the end of the integer.
-t terminate_instance: Optionally specifies the sequence number of the service instance to terminate in order to scale down.

appinstance start {-a `app_instance_name` | -i `uuid`}

Starts an application instance. To start an application instance, you must be a cluster administrator or have the Application Instance Control and Services Control permissions.

You can start an application instance in the Ready state. Once an application instance is started, it moves to the Processing state; then to either the Started or Error states.

-a app_instance_name: Specifies the name of the application instance to start.
-i uuid: Specifies the UUID of the application instance to start.

appinstance stop {-a `app_instance_name` | -i `uuid`}

Stops an application instance. To stop an application instance, you must be a cluster administrator or have the Application Instance Control and Services Control permissions.

You can stop an application instance in the Processing, Started, and Error states.

-a app_instance_name: Specifies the name of the application instance to stop.
-i uuid: Specifies the UUID of the application instance to stop.

appinstance view {-a `app_instance_name` | -i `uuid`}

Lists details of an application instance in a .json file. To view details of an application instance, you must be a cluster administrator or have the Application Instance View permission.

-a app_instance_name: Specifies the name of the application instance to view.
-i uuid: Specifies the UUID of the application instance to view. You can specify the entire UUID string, or a subset of it.

appinstance

appinstance add -a app_instance_name -c consumer_name -f app_template_file [-p parameter [-p parameter]]

appinstance delete {-a app_instance_name | -i uuid} [-U [-t timeout]]

appinstance deploy {-a app_instance_name | -i uuid} [-t timeout]

appinstance export {-a app_instance_name | -i uuid} -t app_template_name [-f]

appinstance list [-l] [-ll]

appinstance modify {-a app_instance_name | -i uuid} -f app_template_name [-p parameter[-p parameter]] [-d[-t timeout]]

appinstance scale {-a app_instance_name | -i uuid} -s service_name [-f] {-m min | -M max} [-t terminate_instance[,terminate_instance...]]

appinstance start {-a app_instance_name | -i uuid}

appinstance stop {-a app_instance_name | -i uuid}

appinstance view {-a app_instance_name | -i uuid}