Upgrade Stack

Use this option to upgrade an existing stack to the listing version. Supported stack features, including Essbase VM, are upgraded to the listing version.

Note:

Starting with version 21.8.0.0.1, you cannot upgrade stacks from Essbase 19c using the Marketplace listing. To migrate from Essbase 19c to Essbase 21c, refer to Migrate Essbase to Latest Cloud Version.

Note:

The Upgrade Stack option is supported only for Essbase on OCI deployments where Autonomous AI Database is provisioned as the repository database during deployment.

Note:

Please also refer to these related topics before proceeding with the Upgrade Stack process: Before Upgrade of Stack, and After Upgrade of Stack.

Upgrade Stack option creates an Oracle Essbase Target instance based on the existing stack configuration of the Source instance on Oracle Cloud Infrastructure (OCI) stack deployment.

Supported Versions for Upgrade

Supported Versions	Required Tasks for Source Instance Before Upgrade
21.x	Collect extended-metadata.

Target Instance Creation

As part of the Target instance creation, the following occurs.

Source instance is shut down
Clones of the Source instance's block volumes are created
Target instance is created using the latest published image of Essbase on OCI:
- Using the same VCN as subnet of the Source instance
- Using the block volume clones of the Target instance
- Using the same database as the Source instance

After the initialization of the Target instance, Essbase is started on the Target instance. Essbase applications and data from the Source instance are then available for use on the Target instance. You can use the same ssh key, passwords and credentials used for logging in to the Source instance to log in and use the Target instance.

Supported Features

Note:

Features that are specific to the new upgrade version, and require additional configuration of the stack, are not available on Target instances created using Upgrade Stack. For example, Catalog Object Storage is not supported in 21.4, 21.5 and Smart View for Office 365 is not supported in 21.5.

Upgrade Stack Process

After you selected the Upgrade Stack option for deployment from Marketplace, the appropriate version of the source instance and compartment, and entered the name of your choice for the stack, perform the following steps.
Make sure that you reviewed Before Upgrade of Stack before proceeding.
1. Choose Source Instance Essbase Stack Version from the drop-down list. Use "Essbase 21c - 21.2 or above", if source instance is 21.2 or higher. Choose "Essbase 21c - 21.1", if source instance is 21.1.
2. Choose Source Instance from the drop down where the previous version was installed.
3. Copy the JSON output that you collected earlier (in Upgrade Stack) from the OCI command ran on the Source instance to be upgraded. Enter it in the Source Instance Metadata input field.
4. [Optional] Select Specify the Private IP for the target to specify a private IP for the new node, and then enter Target IP Value. Enter the available IP address from the same subnet as the source.
5. Choose Target Instance Shape from the drop down list. Choose "Upgrade to recommended Flex Shape", if you want to upgrade it to the recommended shape for this release. The recommended shape for 21.6 is VM.Standard.E5.Flex. Choose "Keep the same shape as Source Instance"(default) if you want to retain the same shape as the Source Instance's shape.
6. If you want to select secrets stored in different compartments, select the checkbox Show Advanced Secret Selection Options. On selecting the checkbox, three additional fields Compartment for Essbase System Admin Password, Compartment for Database Admin Password, and Compartment for IDCS/IAM Application Client Secret will be available. If the checkbox is not selected, you will be able to choose secrets only from the same compartment as deployment.
7. In the Compartment for Essbase System Admin Password field, choose the compartment where you have stored the secret for Essbase System Admin Password.
8. In the Compartment for Database Admin Password field, choose the compartment where you have stored the secret for Database Admin Password.
9. In the Compartment for IDCS/IAM Application Client Secret field, choose the compartment where the secret for IDCS/IAM Application Client is stored.
10. Click Next.
  
  Note:
  After you create the stack with the new image, the Source instance will go to a stopped state. The Source instance node should not be started while the new node is running.
  
  Note:
  The new node will use the same database, clones of the disk volumes, SSH key, shape, and so on, as used by the old (source) node.
Continue with the Review Page Step, towards the end of the Create Stack topic, and then proceed until the end of that topic.

Before Upgrade of Stack

Here are some tasks and considerations before you perform an upgrade.

Stop the Essbase server using stop.sh on the Source instance. This is recommended before you perform Upgrade Stack.
Record Load Balancer details, if your Source instance used Load Balancer. These details are used after Upgrade Stack, to add the new target node private IP to the load balancer backend set.
Record provisioned LDAP user/groups, if your Source instance included any, and make them available after the upgrade.
Name the Source instance components according to original deployment naming conventions, if they changed. Check the latest Release Notes for Known Issues that apply to your Source instance.

Add dynamic group policies:

Allow dynamic-group <dyn group> to manage instance-family in compartment <name>
Allow dynamic-group <dyn group> to manage virtual-network-family in compartment <name>

Check whether the steps mentioned in Source Instance Restored From Backup apply to your upgrade - if so, they must be .

Source Instance Restored From Backup

If your source instance is restored from backup or uses a disaster recovery instance, do the following.

Stop Essbase Source instance.

/u01/config/domains/essbase_domain/esstools/bin/stop.sh

Unmount data volume.
```
sudo umount /u01/data with opc user
```
Disconnect data volume using ISCSI commands.
Detach using OCI console:
1. Temporarily disable /etc/fstab config and data block volume entries.
  1. ssh to target compute (as opc user).
  2. Run the following.
```
sudo vi /etc/fstab
```
  3. Insert # in front of the /u01/config and /u01/data entries.
  4. Save the file.
2. Detach data and config block volumes from the target Essbase compute. Note the iSCSI caution and be sure to unmount and disconnect each volume before detaching using the OCI console.
  1. To unmount:
    1. ssh to target the compute (as opc user).
    2. Run the following.
```
lsblk
```
    3. Run the following.
```
sudo umount /u01/data
```
    4. Repeat these steps to unmount the data block volume.
  2. To disconnect iSCSI:
    1. In the OCI console, select the target compute.
    2. Select resources > attached block volumes.
    3. From the Actions menu , for the config block volume, select iSCSI Commands & Information.
    4. Copy iSCSI commands for disconnect.
    5. ssh to the target compute (as opc user).
    6. Paste the disconnect commands you copied and press enter.
    7. Repeat these steps to disconnect the data volume.
  3. To detach:
    1. In the OCI console, select the target compute.
    2. Select resources > attached block volumes.
    3. From the Actions menu , for the config block volume, select Detach.
    4. Repeat these steps to detach the data block volume.
Rename (clone) the data volume as tag-data-volume on OCI console page.

Reattach the data volume using the following OCI CLI command (as opc user).

for 21.1

oci compute volume-attachment attach-iscsi-volume --instance-id $instanceid
--volume-id $datavolumeid --display-name data-volume-attachment --auth
instance_principal

for 21.2 and higher

oci compute volume-attachment attach-iscsi-volume --instance-id $instanceid
--volume-id $datavolumeid --display-name data-volume --auth
instance_principal

Copy the ICSI commands from OCI console page, enter them in the session, and connect using ISCSI.
Update /etc/fstab with data volume UUID.
```
sudo vi /etc/fstab
```

Mount data volume.

sudo systemctl daemon-reload

sudo mount -a

Start server.

/u01/config/domains/essbase_domain/esstools/bin/start.sh

Proceed to collect metadata, as shown in Collect Source Instance Metadata.

Collect Source Instance Metadata

Here are steps to collect metadata for a source instance.

Access the source instance (to be upgraded) using SSH. Change to oracle user and stop the Essbase service using the commands:
```
sudo su oracle 
/u01/config/domains/essbase_domain/esstools/bin/stop.sh
```

After stop.sh is completed run the following command:

oci compute instance get --instance-id $(oci-metadata -j | jq -r '.instance.id') --auth instance_principal | jq '.data."extended-metadata"'

Note:

You can also run the above command as opc user.

The output from the above is in JSON format. Copy the entire output contents (including the braces {}), to be used later in Source Instance Metadata field during new upgrade stack creation.

After Upgrade of Stack

Here are some tasks and considerations after you perform an upgrade.

If any errors occur on the initial startup of the Target instance, try restarting the Essbase server processes using stop.sh and start.sh, or rebooting the compute instance.

Note:
While the Target instance is running, do not start the Source instance. Simultaneous operation of both the Target instance and the Source instance may lead to synchronization issues.
If you had LDAP users/groups provisioned in the Source instance, you must manually back them up and restore them on the Target instance
If you had Load Balancer in the Source instance, you must manually update the Load Balancer with the new private IP of the Target instance.
1. Go to Networking > Load Balancers, and select the load balancer you want to edit.
2. (In the left-side menu), under Resources,
  1. Select Backend Sets, and select the set essbase.
  2. Select Backends, and select Add backends.
3. Select the Target instance, set port to 443, and click Add.
4. Remove the private IP of the Source instance, from the backend list.
After the upgrade is completed, you can ssh to the new instance with the same private key.
Go to the confidential application – client configuration (of the previous stack) and update it with the new IP address, if necessary.

If you previously required: dynamic-group policy for “manage instance-family”, it can be removed.