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:

Please also refer to these related topics before proceeding with the Upgrade Stack process: Before Upgrading a Previously Upgraded Stack, 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
19.3.0.0.2	Run the script upgrade-metadata-19c02.sh. Collect extended-metadata.
19.3.0.2.3	Run the script upgrade-metadata-19c23.sh. Collect extended-metadata.
19.3.0.3.4	Run the script upgrade-metadata-19c.sh. Collect extended-metadata.
19.3.0.4.5	Run the script upgrade-metadata-19c.sh. Collect extended-metadata.
19.3.0.5.6	Collect extended-metadata.
19.3.0.6.0	Collect extended-metadata.
21.1	Collect extended-metadata.
21.2	Collect extended-metadata.
21.3	Collect extended-metadata.
21.4	Collect extended-metadata.
21.5	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.

The following are supported in 21.5 upgrade:

Source instances on Essbase on OCI stack versions: 19.3.0.0.2 or above, 21.1 or above
Only source instances using Autonomous Database
Only Essbase components created during the source instance deployment

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 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. Otherwise, use the appropriate 19c version, for your Source instance, from the drop down menu.
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. [Optional] [Mandatory for 19.3.0.0.2 upgrade] In the fields: Database Admin User Password, Essbase System Admin Password, and IDCS Application Client Secret (if using IDCS), enter OCIDs of the corresponding vault-secrets. Although these fields are displayed as optional, if not provided for 19.3.0.0.2 upgrade, Upgrade Stack will fail.
  
  Note:
  These fields and names are subject to change depending on the latest software version.
6. 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 or Source Instances on Essbase Version 19.3.0.n.n or Previously Upgraded Stack apply to your upgrade - if so, they must be .
For Source instances on Essbase on OCI stack versions 19.3.0 3.4 or 19.3.0.4.5, then before upgrade, you must run the script mentioned in Source Instances on Essbase Version 19.3.0.n.n.
For Source instances on Essbase on OCI stack versions 19.3.0.2.3, then, before upgrade, you must upgrade pip as oracle user, and then upgrade oci cli on 19.3.0.2.3 source instance (before running upgrade metadata script for 19.3.0.2.3).
To upgrade pip as oracle user:
```
sudo su oracle
pip install --upgrade pip
```
To upgrade oci cli as oracle user:
```
sudo su oracle
pip install oci-cli --upgrade
```

Source Instances on Essbase Version 19.3.0.n.n

If your source instance is running on Essbase version 19.3.0.0.2, 19.3.0.2.3, 19.3.0.3.4 or 19.3.0.4.5, perform the following steps.

Log into the source instance using ssh.
Change to oracle user:
```
sudo su oracle
```
Copy the script from the appropriate link below, and save it as directed:
- For 19.3.0.0.2, copy the script from the link below and save it as upgrade-metadata-19c02.sh
```
https://github.com/oracle-quickstart/oci-essbase/tree/main/scripts/upgrade-metadata-19c02.sh
```
- For 19.3.0.2.3, copy the script from the link below and save it as upgrade-metadata-19c23.sh
```
https://github.com/oracle-quickstart/oci-essbase/tree/main/scripts/upgrade-metadata-19c23.sh
```
- For 19.3.0.3.4 or 19.3.0.4.5, copy the script from the link below and save it as upgrade-metadata-19c.sh
```
https://github.com/oracle-quickstart/oci-essbase/tree/main/scripts/upgrade-metadata-19c.sh
```
Note:
Before running the script, ensure that you have added policy to manage keys. This script modifies and create secrets in the vault associated with the source instance on which it is being run.
```
Allow group <group> to manage keys in compartment <compartment name>
```
Run the script as follows:
- For 19.3.0.0.2, run the script using:
```
sudo su oracle
bash -e upgrade-metadata-19c02.sh
```
- For 19.3.0.2.3, run the script using:
```
sudo su oracle
bash -e upgrade-metadata-19c23.sh
```
- For 19.3.0.3.4 or 19.3.0.4.5, run the script using:
```
bash -e upgrade-metadata-19c.sh
```
Note:
This script changes the source instance metadata. The original instance metadata is available in the following files after you run the script. Please copy and keep it for reference after the initial run of the script. These can be used to restore the original metadata of the instance, if there are any errors during script execution.
```
/tmp/upgrade/core_metadata.json 
/tmp/upgrade/extended_metadata.json
```
Note:
This script can only be run once. Subsequent runs will result in an error, if the original metadata has not been restored.
Proceed to collect metadata, as shown in Collect Source Instance Metadata.

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 19.3.0.0.2 or 19.3.0.2.3

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

for 19.3.0.3.4 or 19.3.0.4.5

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

for 19.3.0.5.6 or 19.3.0.6.0

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

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.

Previously Upgraded Stack

This is a prerequisite for upgrading a previously upgraded stack from Essbase 19.3.0.0.2, 19.3.0.2.3, 19.3.0.3.4, and 19.3.0.4.5. The object storage bucket to be used for backup must be configured for Upgrade Stack to succeed.

After having upgraded the stack from the above-mentioned versions, to 21.4 or above, and before attempting to upgrade again to 21.5.x, perform the following steps to edit the instance metadata to prepare the instance for upgrade.

Change to a working directory and create the following file:

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

Edit file ext_metadata.json to add a JSON field for bucket information, for example:
```
{
...
...
...
"backup_bucket": {
"id": "n/<namespace>/b/essbase_xxxx_backup",
"name": "essbase_xxxx_backup",
"namespace": <namespace>"},
...
...
...
}
```
Replace "xxxx" above with the bucket details of any bucket in your tenancy.

Note:
Regardless of how the existing backup bucket attribute appears in the ext_metadata.json file, such as null, empty block, or inside or outside the database attribute, you must add the above details as a separate attribute in the ext_metadata.json file.

Execute the following command in the current source instance of the stack, which is about to be upgraded.

oci compute instance update --instance-id $(oci-metadata -j | jq -r '.instance.id') --extended-metadata file://./ext_metadata.json --auth instance_principal --force

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.