Updating a deployed topology

After you deploy a topology, you might need to apply fixes, either to the IBM Cloud Manager with OpenStack services themselves or to how the IBM Cloud Manager with OpenStack services are deployed.

1. Log in to the deployment system as the root user. The deployment system is where IBM Cloud Manager with OpenStack was installed.
2. Locate the directory that contains the files for the topology that you deployed. Change your-deployment-name to the name for your deployment.

   $ cd your-deployment-name

3. Download the current environment for your deployment. Change your-environment-name to the name for your deployment. The name of your environment can be found in the topology file for your deployment.

   $ knife environment show your-environment-name -d -Fjson > your-environment-name.json

4. (This step is only required when you are using the VMware hypervisor and you are applying fixes as part of the update.) If your previous fix pack version is IBM Cloud Manager with OpenStack 4.3.0.4 or higher, you do not need to complete this step. Otherwise, if you are applying an incremental fix pack for IBM Cloud Manager with OpenStack 4.3 and you are using the VMware hypervisor, complete the following steps before the topology update:
   1. Ensure that the fix pack is installed on the Chef server.
   2. On the OpenStack network node (if you are using an all-in-one topology, this is the controller node), run the following commands:

      $> rpm -e neutron-vmware-driver
      $> yum install neutron-vmware-driver

   3. On the OpenStack compute node (if you are using an all-in-one topology, this is the controller node):

      $> rpm -e nova-vmware-driver
      $> yum install nova-vmware-driver

5. (This step is only required when you apply fixes as part of the update.) The environment file for your deployment has constraints on the cookbook versions used. These constraints must be updated to use the new cookbook versions. The knife os manage update environment command can be used to update the cookbook version constraints.
   • To update a JSON environment file that is named your-environment.json, run the following command:

     knife os manage update environment your-environment.json

     The file name must end with the .json extension. If the file refers to an existing chef environment, the file is uploaded to the chef server.

   A fix pack might also require other changes to the environment. Refer to the instructions in the IBM Cloud Manager with OpenStack fix pack.
6. Optional: You can change the configuration of your IBM Cloud Manager with OpenStack cloud environment after you deploy it.
   For information about the supported configuration changes, see Deployment customization options. Some cloud environments might not support certain customization options. In addition, some customization options are not supported after a topology is deployed.

   When you make configuration changes to your deployment environment, you can manually modify the environment JSON file that you downloaded in Step 3. Or, you can use the knife os manage set environment command to assist you.

   • Option 1: Manually edit your environment JSON file and then upload it after you complete the configuration changes.

     $ # Edit the environment JSON file, your-environment-name.json.
     $ knife environment from file your-environment-name.json

   • Option 2: Create an environment YAML configuration file that contains the configuration changes. Use the knife os manage set environment command to modify your environment. For information about the environment YAML configuration file that is used by the command, see Environment YAML Configuration File.

     $ touch your-environment-name-changes.yml
     $ # Add your environment changes to the environment YAML configuration file.
     $ knife os manage set environment --env-conf your-environment-name-changes.yml -y your-environment

     Note: Manual modifications to IBM Cloud Manager with OpenStack configuration files that are managed by Chef are overwritten when you update your cloud environment. Configuration files that are managed by Chef have a banner similar to the following example at the beginning of the file:

     # This file autogenerated by Chef
     # Do not edit, changes will be overwritten

     If you must manually modify such configuration files, the modification must be redone after the update.

     If you want to keep the modification after update, add the value in environment file if the value could be set, otherwise, you must redone the modification after the update.

7. Optional: The existing OpenStack configuration files are overwritten by the topology update. If you have any important manual changes in the OpenStack cloud configuration files of the topology that is going to be updated, take one of the following actions to avoid losing your manual changes.
   • Back up the manually modified configuration files before updating the topology. When the topology update is complete, you can copy the manual changes from the backups into the new configuration files.
     Important: Do not replace the new configuration file with the backup configuration file, because the backup configuration file might not support the updated OpenStack topology.

     For example, you added some LDAP customization in /etc/keystone/keystone.conf. Back up the configuration file to a safe place, for example /home/etc/backups/keystone/keystone.conf. After the topology update is complete, you can manually add the changes in the old configuration file, /home/backups/etc/keystone/keyston.conf, back into the new configuration file, /etc/keystone/keystone.conf .

   • Update the Chef environment by customizing the related attributes that represent your manual changes. For example, in your previous OpenStack deployment, you utilized LDAP in Keystone, and you used the LDAP server https://ldap.server1.com/. In the Chef environment, you have openstack.identity.ldap.url = 'https://ldap.server1.com/'. Later, you decided to change the LDAP server to https://ldap.server2.com/. You did a manual change in /etc/keystone/keystone.conf by changing the following configuration item: [ldap] url = https://ldap.server2.com/.

     Now you are about to update the topology. To avoid the manual changes from being lost, you can update your Chef environment by setting openstack.identity.ldap.url = 'https://ldap.server2.com/'. Your topology update will have 'https://ldap.server2.com/' set in the new keystone.conf.

8. Refresh the topology deployment.

   $ knife os manage update topology your-topology-name.json

   All of the nodes that are defined in the topology are refreshed. The following topology JSON items, which are required during a topology deployment, are optional during a topology update:

   Topology Keys: environment

   The environment to use with all nodes in the topology. The environment must exist on the Chef server.

   Node Keys: runlist

   The runlist for the node. The runlist is a list of roles and cookbook recipes to be applied to the node. The roles and cookbook recipes must exist on the Chef server.

   If the environment, or runlist values are specified in the topology JSON, they are set again for each node in the topology. If the environment is not specified in the topology JSON, it is not set on all nodes. If the runlist is not specified for a particular node in the topology JSON, it is not set on that node.

   For an HA topology, the controllers nodes are updated one by one. When one controller node is put in standby mode, updated, and then taken out of standby mode, the other two (or more) nodes are still up and running. Thus, the cloud can be used during updates. As services are moved from one controller node to another to allow updates, the services are unavailable briefly. The services include the virtual IP, DB2®, Dashboard, and so on. You might notice services that are being disconnected from the Dashboard, or tasks that are failing when they require database access. When the update is complete, all services are available.

   If there are nodes in the topology that you do not want to refresh, two options exist to prevent them from being updated (while still leaving them in the topology).

   • The knife os manage update topology command can be run in interactive mode by specifying the --interactive command-line option:

      $ knife os manage update topology your-topology-name.json --interactive

     When run in interactive mode, and choosing not to update all nodes, the command asks whether to update each node. You can then skip any nodes in the topology that you do not want to refresh.
   • If you do not want to refresh a node in the topology, you can set a key in the topology JSON file that is used to specify whether to update it.

     Node Keys: allow_update

     A Boolean value, which indicates whether to update the node. Set to true to update the node. Set to false if you do not want to update the node. The default is true.

9. (This step is only required when you apply fixes as part of the update. This step is not required for controller nodes in HA topologies. Each HA controller node is automatically put in standby mode before the update and then taken out of standby after the update, which restarts the services.) After you refresh the topology deployment, restart the IBM Cloud Manager with OpenStack services. For more information, see Managing IBM Cloud Manager with OpenStack services.