3.1 Instance Lifecycle Scenarios

1.2

For clarity these scenarios are only showing one instance clusters.

Reference: domain.xml snippet in design spec.

Scenario 1: DAS managed: Remote instance: SSH node: (create-node-ssh/create-instance/start-instance)

MS3

1) Prerequisite: SSH configured such that the user that the DAS is running as can connect to remote nodes via SSH using key authentication and key file is in default location ($user.home/.ssh/id_[rd]sa). Run the following commands:

asadmin create-cluster c1
asadmin create-node-ssh --nodehost glassfish1.sfbay.sun.com --installdir /export/glassfish3 n1
asadmin create-instance --node n1 --cluster c1 i1
asadmin start-cluster c1
asadmin list-instances
asadmin stop-cluster c1

domain.xml snippet:

<server . . . name="i1" node-ref="n1">
. . .
</server>

<node name="n1" type="SSH" node-host="glassfish1.sfbay.sun.com" install-dir="/export/glassfish3">
    <ssh-connector port=22>
        <ssh-auth type="key" username="${user.name}" keyfile="${user.home}/.ssh/id_dsa" />
    </ssh-connector>
</node>

Notes:

1. create-instance runs: "_create-instance-filesystem i1" over SSH.

Scenario 2: DAS  managed: Local instance: localhost node: (create-instance/start-instance)

MS3

1) No SSH required

2) Run the following commands:

asadmin create-cluster c1
asadmin create-instance --node localhost --cluster c1 i1
asadmin start-cluster c1
asadmin list-instances
asadmin stop-cluster c1

domain.xml snippet:

<server . . . name="i1" node-ref="localhost">
. . .
</server>

<node name="localhost" type="CONFIG" node-host="localhost-domain1" install-dir=${com.sun.aas.productRoot}">
</node>

Notes

1. Supported in MS3
2. "localhost" is a node that ships pre-defined in domain.xml
3. In earlier builds create-instance defaulted --node to "localhost", but the correct behavior is for it to be required.

Scenario 3: Locally managed: Remote instance: autonode creation: (create-local-instance/start-local-instance)

MS3

1) No SSH

2) Create cluster on DAS

asadmin create-cluster c1

3) On glassfish1.sfbay create instance

asadmin --host dashost create-local-instance --cluster c1 i1
asadmin start-local-instance i1

This implicitly create nodes as shown in domain.xml snippet

4) Can't start/stop cluster/instance via DAS since not SSH.

domain.xml snippet:

<server . . . name="i1" node-ref="glassfish1.sfbay.sun.com">
. . .
</server>

<node name="glassfish1.sfbay.sun.com" type="CONFIG" node-host="glassfish1.sfbay.sun.com"
 install-dir="/export/glassfish3">
</node>

Notes:

1. Supported in MS3 except that create-local-instance does not validate an existing node has matching parameters (issue 12550).
2. create-local-instance implicitly creates the node by calling: "_create-node-implicit --name glassfish1.sfbay.sun.com --nodehost glassfish1.sfbay.sun.com --nodehome /export/glassfishv3".  Issue 12422 covers this.
3. _create-node-implicit will succeed if the node does not exist and it creates a new one, or the node already exists and has values that match the values passed by create-local-instance.
4. Note from Byron - your mileage may vary. If you try it with a computer sitting on VPN you will NOT get the same value for name and nodehost

Scenario 4: DAS Managed: Remote instance: SSH node: Local instance creation: (create-ssh-node/create-local-instance/start-instance)

MS4

1) Prerequisite: SSH configured such that the user that the DAS is running as can connect to remote nodes via SSH using key authentication and key file is in default location ($user.home/.ssh/id_[rd]sa).

2) Run the following commands on the DAS:

asadmin create-cluster c1
asadmin create-node-ssh --nodehost glassfish1.sfbay.sun.com --installdir /export/glassfish3 n1

3) On glassfish1.sfbay create instance

asadmin create-local-instance --node n1 --cluster c1 i1

4) On DAS

asadmin start-cluster c1
asadmin list-instances
asadmin stop-cluster c1

domain.xml snippet:

<server . . . name="i1" node-ref="n1">
. . .
</server>

<node name="n1" type="SSH" node-host="glassfish1.sfbay.sun.com" install-dir="/export/glassfish3">
    <ssh-connector port=22>
        <ssh-auth type="key" username="${user.name}" keyfile="${user.home}/.ssh/id_dsa" />
    </ssh-connector>
</node>

Notes:

1. Supported in MS3 except create-local-instance does not validate node information (issue(12544).
2. If the user specifies an invalid node for "--node" (that is a node that does not exist in domain.xml) to create-local-instance then _register-instance should fail and cause the command to fail and the filesystem to not be created.
3. create-local-instance does not try to implicitly create node.
4. create-local-instance should validate the node information by calling _validate-node and passing nodehost, nodehome and nodedir (_validate-node does not exist in MS2/MS3). "_validate-node --node name --nodehost host  --nodehome homepath --nodedir pathdir" ensures there is a node with values that match those that are passed. If the existing node is a config node then it will update the missing attributes to contain the passed values (see Scenario 5).

Scenario 5: Locally managed: Remote instance: config node: Local instance creation: (create-node-config/create-local-instance/start-local-instance)

MS4

1) No SSH

2) Run the following commands:

asadmin create-cluster c1
asadmin create-node-config n1

This creates a node that looks like:

<node name="n1">
</node>

3) On glassfish1.sfbay create instance

asadmin create-local-instance --node n1 --cluster c1 i1
asadmin start-local-instance i1

4) Can't start/stop cluster/instance via DAS since not SSH.

domain.xml snippet:

<server . . . name="i1" node-ref="n1">
. . .
</server>

<node name="n1" type="CONFIG" node-host="glassfish1.sfbay.sun.com" node-home="/export/glassfish3">
</node>

Notes:

1. Supported in MS4 (see issue 12544
2. Like in Scenario 4 create-local-insance calls "_validate-node --node name --nodehost host  --nodehome homepath --nodedir pathdir" to ensure the node exists and in this case it will also populate missing attributes.

Scenario 6: Upgrade non SSH node to SSH node

MS4

1) Start with Scenario 3 (you have a non SSH node)

2) Upgrade node to SSH node

asadmin update-node-ssh glassfish1.sfbay.sun.com

domain.xml snippet:

<server . . . name="i1" node-ref="glassfish1.sfbay.sun.com">
. . .
</server>

<node name="glassfish1.sfbay.sun.com" type="SSH" node-host="glassfish1.sfbay.sun.com" node-home="/export/glassfish3">
    <ssh-connector port=22>
        <ssh-auth type="key" username="${user.name}" keyfile="${user.home}/.ssh/id_dsa" />
    </ssh-connector>
</node>

1. Supported in MS4
2. update-node-ssh does not exist in MS2/MS3
3. Only the nodename is required. All other attributes are optional. Supports same options as create-node-ssh.

Scenario 7: Upgrade v2 to 3.1

MS5

In this case all nodeagents are converted to CONFIG nodes using default values for everything and we have this:

<server . . . name="i1" node-ref="n1">
. . .
</server>

<node name="n1"  node-host="gf2.sfbay.sun.com" node-home="${com.sun.aas.productRoot}">
</node>

If the user wished to manage the instances from a central location then he must run update-node-ssh to convert the node to type SSH:

asadmin update-node-ssh --nodehome /export/glassfish3 n1

1. Supported in MS5

Scenario 8: Centrally managed: Remote instance: SSH node: Central instance configuration creation: (create-node-ssh/create-instance/start-instance) with master password set to something other than changeit.

1) SSH setup

2) Create and start a domain with the master-password set to "welcome1" using the command :

asadmin create-domain --savemasterpassword true domain2 
asadmin start-domain domain2

3) Create an SSH node

asadmin create-node-ssh --nodehost glassfish1.sfbay.sun.com --installdir /export/glassfish3 node2

4) create instance
This creates the instance configuration information and the instance file system.

asadmin create-instance --node node2 ins2

5) At this point the instance is created but it can not be started by the start-instance command because there is no master-password file in the instance node directory. That file must exist and it must have the same password as the master password on the DAS. To create that file run the following command on the instance machine:

asadmin change-master-password --savemasterpassword true --nodedir /export/glassfish3/glassfish/nodes node2

At the prompt I have to enter the master password which is what I had set when I created domain2 on the DAS. It is not the default master password 'changeit' The keystore was copied over when the instance was created and it is encrypted with the master password from the DAS. So the passwords are the same but start-instance is looking for a file called master-password in the agents dir to access the keystores. Once that file is created start-instance can be run centrally (from the DAS). The master-password file is associated with a node and not with an instance.

6) Start the instance from the DAS

asadmin start-instance ins2

Scenario 9: Offline configuration:

User can create the configuration information for a node and then when the host information is know, he can create the instance using the create-local-instance on the instance machine. If the node host information is known and the config node has nodehost set to that host then create-instance will create the instance file system under the GlassFish installation dir on the instance host.

1) Create the empty config node:

asadmin create-node-config node1

2) Complete creating the instance using create-local-instance command:

asadmin --host glassfish1.sfbay.sun.com --port 4848 create-local-instance --node node1 instance1

OR

2) Complete creating the instance by updating the config node with the node host information and then running create-instance (this assumes the instance should be created in the GlassFish installation dir):

asadmin update-node-config --nodehost glassfish1.sfbay.sun.com node1
asadmin create-instance --node node1 instance1