docs: def stop_instance(self, instance_id):
          """Stops the instance gracefully.
  
          :param str instance_id: instance identifier
  
          :return: None
          """
          self._restore_from_storage(instance_id)
          if self._start_failed:
              raise Exception('stop_instance for node %s: failing due to'
                              ' previous errors.' % instance_id)
  
          with self._resource_lock:
              try:
                  v_m = self._qualified_name_to_vm(instance_id)
                  if not v_m:
                      err = "stop_instance: can't find instance %s" % instance_id
                      log.error(err)
                      raise Exception(err)
                  v_m._cloud_service._stop_vm(v_m)
                  # note: self._n_instances is a derived property, doesn't need
                  # to be updated
                  if self._n_instances == 0:
                      log.debug('last instance deleted, destroying '
                                'global resources')
                      self._delete_global_reqs()
                      self._delete_cloud_provider_storage()
              except Exception as exc:
                  log.error(traceback.format_exc())
                  log.error("error stopping instance %s: %s", instance_id, exc)
                  raise
          log.debug('stopped instance %s', instance_id)