Trigger upgrade-series-prepare hook.

api/uniter/unit.go

@@ -642,6 +642,48 @@ func (u *Unit) WatchActionNotifications() (watcher.StringsWatcher, error) {
 	return w, nil
 }
 
+// WatchActionNotifications returns a StringsWatcher for observing the state of
+// a series upgrade.
+func (u *Unit) WatchUpgradeSeriesNotifications() (watcher.NotifyWatcher, error) {
+	var results params.NotifyWatchResults
+	args := params.Entities{
+		Entities: []params.Entity{{Tag: u.tag.String()}},
+	}
+	err := u.st.facade.FacadeCall("WatchUpgradeSeriesNotifications", args, &results)
+	if err != nil {
+		return nil, err
+	}
+	if len(results.Results) != 1 {
+		return nil, errors.Errorf("expected 1 result, got %d", len(results.Results))
+	}
+	result := results.Results[0]
+	if result.Error != nil {
+		return nil, result.Error
+	}
+	w := apiwatcher.NewNotifyWatcher(u.st.facade.RawAPICaller(), result)
+	return w, nil
+}
+
+// UpgradeSeriesStatus returns the upgrade series status of a unit from remote state
+func (u *Unit) UpgradeSeriesStatus() (string, error) {
+	var results params.UpgradeSeriesStatusResults
+	args := params.Entities{
+		Entities: []params.Entity{{Tag: u.tag.String()}},
+	}
+	err := u.st.facade.FacadeCall("UpgradeSeriesStatus", args, &results)
+	if err != nil {
+		return "", err
+	}
+	if len(results.Results) != 1 {
+		return "", errors.Errorf("expected 1 result, got %d", len(results.Results))
+	}
+	result := results.Results[0]
+	if result.Error != nil {
+		return "", result.Error
+	}
+	return result.Status, nil
+}
+
 // RequestReboot sets the reboot flag for its machine agent
 func (u *Unit) RequestReboot() error {
 	machineId, err := u.AssignedMachine()

api/uniter/unit_test.go

@@ -684,6 +684,44 @@ func (s *unitSuite) TestWatchActionNotificationsMoreResults(c *gc.C) {
 	c.Assert(err.Error(), gc.Equals, "expected 1 result, got 2")
 }
 
+func (s *unitSuite) TestWatchUpgradeSeriesNotifications(c *gc.C) {
+	watcher, err := s.apiUnit.WatchUpgradeSeriesNotifications()
+	c.Assert(err, jc.ErrorIsNil)
+
+	notifyWatcher := watchertest.NewNotifyWatcherC(c, watcher, s.BackingState.StartSync)
+	defer notifyWatcher.AssertStops()
+
+	// Why do I have two initial events?!?
+	_, ok := <-notifyWatcher.Watcher.Changes()
+	notifyWatcher.Assert(ok, jc.IsTrue)
+
+	notifyWatcher.AssertOneChange()
+
+	err = s.wordpressMachine.CreateUpgradeSeriesLock()
+	c.Assert(err, jc.ErrorIsNil)
+
+	// Expect a notification that the document was created (i.e. a lock was placed)
+	notifyWatcher.AssertOneChange()
+
+	err = s.wordpressMachine.RemoveUpgradeSeriesLock()
+	c.Assert(err, jc.ErrorIsNil)
+
+	// A notification that the document was removed (i.e. the lock was released)
+	notifyWatcher.AssertOneChange()
+}
+
+func (s *unitSuite) TestUpgradeSeriesStatus(c *gc.C) {
+	// First we create the prepare lock
+	err := s.wordpressMachine.CreateUpgradeSeriesLock()
+	c.Assert(err, jc.ErrorIsNil)
+
+	// Then we check to see the status of our upgrade. We note that creating
+	// the lock essentially kicks off an upgrade for the perspective of assigned units.
+	status, err := s.apiUnit.UpgradeSeriesStatus()
+	c.Assert(err, jc.ErrorIsNil)
+	c.Assert(status, gc.Equals, "preparing")
+}
+
 func (s *unitSuite) TestApplicationNameAndTag(c *gc.C) {
 	c.Assert(s.apiUnit.ApplicationName(), gc.Equals, s.wordpressApplication.Name())
 	c.Assert(s.apiUnit.ApplicationTag(), gc.Equals, s.wordpressApplication.Tag())

apiserver/facades/agent/uniter/uniter.go

@@ -984,6 +984,77 @@ func (u *UniterAPI) WatchActionNotifications(args params.Entities) (params.Strin
 	return common.WatchActionNotifications(args, canAccess, watchOne), nil
 }
 
+// WatchActionNotifications returns a StringsWatcher for observing the status of an Upgrade Series
+func (u *UniterAPI) WatchUpgradeSeriesNotifications(args params.Entities) (params.NotifyWatchResults, error) {
+	result := params.NotifyWatchResults{
+		Results: make([]params.NotifyWatchResult, len(args.Entities)),
+	}
+	canAccess, err := u.accessUnit()
+	if err != nil {
+		return params.NotifyWatchResults{}, err
+	}
+	for i, entity := range args.Entities {
+		tag, err := names.ParseUnitTag(entity.Tag)
+		if err != nil {
+			result.Results[i].Error = common.ServerError(common.ErrPerm)
+			continue
+		}
+		watcherId := ""
+		if !canAccess(tag) {
+			result.Results[i].Error = common.ServerError(common.ErrPerm)
+			continue
+		}
+		unit, err := u.getUnit(tag)
+		if err != nil {
+			result.Results[i].Error = common.ServerError(err)
+			continue
+		}
+		w, err := unit.WatchUpgradeSeriesNotifications()
+		if err != nil {
+			result.Results[i].Error = common.ServerError(err)
+			continue
+		}
+		watcherId = u.resources.Register(w)
+		result.Results[i].NotifyWatcherId = watcherId
+	}
+	return result, nil
+}
+
+func (u *UniterAPI) UpgradeSeriesStatus(args params.Entities) (params.UpgradeSeriesStatusResults, error) {
+	result := params.UpgradeSeriesStatusResults{
+		Results: make([]params.UpgradeSeriesStatusResult, len(args.Entities)),
+	}
+	canAccess, err := u.accessUnit()
+	if err != nil {
+		return params.UpgradeSeriesStatusResults{}, err
+	}
+	for i, entity := range args.Entities {
+		tag, err := names.ParseUnitTag(entity.Tag)
+		if err != nil {
+			result.Results[i].Error = common.ServerError(common.ErrPerm)
+			continue
+		}
+
+		if !canAccess(tag) {
+			result.Results[i].Error = common.ServerError(common.ErrPerm)
+			continue
+		}
+		unit, err := u.getUnit(tag)
+		if err != nil {
+			result.Results[i].Error = common.ServerError(err)
+			continue
+		}
+		status, err := unit.UpgradeSeriesStatus()
+		if err != nil {
+			result.Results[i].Error = common.ServerError(err)
+			continue
+		}
+		result.Results[i].Status = status
+	}
+
+	return result, nil
+}
+
 // ConfigSettings returns the complete set of application charm config
 // settings available to each given unit.
 func (u *UniterAPI) ConfigSettings(args params.Entities) (params.ConfigSettingsResults, error) {

apiserver/params/params.go

@@ -1276,3 +1276,12 @@ type DumpModelRequest struct {
 	Entities   []Entity `json:"entities"`
 	Simplified bool     `json:"simplified"`
 }
+
+type UpgradeSeriesStatusResult struct {
+	Error  *Error `json:"error,omitempty"`
+	Status string `json:"status,omitempty"`
+}
+
+type UpgradeSeriesStatusResults struct {
+	Results []UpgradeSeriesStatusResult `json:"results,omitempty"`
+}

state/machine.go

@@ -2203,6 +2203,11 @@ func (m *Machine) RemoveUpgradeSeriesLock() error {
 	return nil
 }
 
+// UpgradeSeriesStatus returns the status of a series upgrade.
+func (m *Machine) UpgradeSeriesStatus() (string, error) {
+	return "preparing", nil
+}
+
 func createUpgradeSeriesLockTxnOps(machineDocId string, data *upgradeSeriesLock) []txn.Op {
 	return []txn.Op{
 		{

state/watcher.go

@@ -1636,6 +1636,25 @@ func (u *Unit) WatchMeterStatus() NotifyWatcher {
 	})
 }
 
+// WatchUpgradeStatus returns a watcher that observes the status of a series
+// upgrade by monitoring changes to its parent machine's upgrade series lock.
+func (u *Unit) WatchUpgradeSeriesNotifications() (NotifyWatcher, error) {
+	machine, err := u.machine()
+	if err != nil {
+		return nil, err
+	}
+	return newEntityWatcher(machine.st, machineUpgradeSeriesLocksC, machine.doc.DocID), nil
+}
+
+// UpgradeSeriesStatus returns the upgrade status of the units assigned machine.
+func (u *Unit) UpgradeSeriesStatus() (string, error) {
+	machine, err := u.machine()
+	if err != nil {
+		return "", err
+	}
+	return machine.UpgradeSeriesStatus()
+}
+
 func newEntityWatcher(backend modelBackend, collName string, key interface{}) NotifyWatcher {
 	return newDocWatcher(backend, []docKey{{collName, key}})
 }

worker/uniter/hook/hook.go

@@ -48,7 +48,7 @@ func (hi Info) Validate() error {
 		}
 		fallthrough
 	case hooks.Install, hooks.Start, hooks.ConfigChanged, hooks.UpgradeCharm, hooks.Stop, hooks.RelationBroken,
-		hooks.CollectMetrics, hooks.MeterStatusChanged, hooks.UpdateStatus:
+		hooks.CollectMetrics, hooks.MeterStatusChanged, hooks.UpdateStatus, hooks.UpgradeSeriesPrepare:
 		return nil
 	case hooks.Action:
 		return fmt.Errorf("hooks.Kind Action is deprecated")

worker/uniter/remotestate/mock_test.go

@@ -204,6 +204,7 @@ type mockUnit struct {
 	addressesWatcher                 *mockNotifyWatcher
 	configSettingsWatcher            *mockNotifyWatcher
 	applicationConfigSettingsWatcher *mockNotifyWatcher
+	upgradeSeriesWatcher             *mockNotifyWatcher
 	storageWatcher                   *mockStringsWatcher
 	actionWatcher                    *mockStringsWatcher
 	relationsWatcher                 *mockStringsWatcher
@@ -261,6 +262,14 @@ func (u *mockUnit) WatchRelations() (watcher.StringsWatcher, error) {
 	return u.relationsWatcher, nil
 }
 
+func (u *mockUnit) WatchUpgradeSeriesNotifications() (watcher.NotifyWatcher, error) {
+	return u.upgradeSeriesWatcher, nil
+}
+
+func (u *mockUnit) UpgradeSeriesStatus() (string, error) {
+	return "prepare", nil
+}
+
 type mockApplication struct {
 	tag                   names.ApplicationTag
 	life                  params.Life

worker/uniter/remotestate/snapshot.go

@@ -71,6 +71,9 @@ type Snapshot struct {
 
 	// Series is the current series running on the unit
 	Series string
+
+	// UpgradeSeriesStatus is the status of any currently running series upgrade
+	UpgradeSeriesStatus string
 }
 
 type RelationSnapshot struct {

worker/uniter/remotestate/state.go

@@ -42,11 +42,13 @@ type Unit interface {
 	WatchAddresses() (watcher.NotifyWatcher, error)
 	WatchConfigSettings() (watcher.NotifyWatcher, error)
 	WatchTrustConfigSettings() (watcher.NotifyWatcher, error)
+	WatchUpgradeSeriesNotifications() (watcher.NotifyWatcher, error)
 	WatchStorage() (watcher.StringsWatcher, error)
 	WatchActionNotifications() (watcher.StringsWatcher, error)
 	// WatchRelation returns a watcher that fires when relations
 	// relevant for this unit change.
 	WatchRelations() (watcher.StringsWatcher, error)
+	UpgradeSeriesStatus() (string, error)
 }
 
 type Application interface {

worker/uniter/remotestate/watcher.go

@@ -170,7 +170,7 @@ func (w *RemoteStateWatcher) CommandCompleted(completed string) {
 }
 
 func (w *RemoteStateWatcher) setUp(unitTag names.UnitTag) (err error) {
-	// TODO(dfc) named return value is a time bomb
+	// TODO(dfc) named return value is a time bomb (externalreality) I second the notion
 	// TODO(axw) move this logic.
 	defer func() {
 		cause := errors.Cause(err)
@@ -317,6 +317,17 @@ func (w *RemoteStateWatcher) loop(unitTag names.UnitTag) (err error) {
 	// returned by the leadership tracker.
 	requiredEvents++
 
+	// TODO(externalreality) This pattern should probably be extracted
+	var seenUpgradeSeriesChange bool
+	upgradeSeriesw, err := w.unit.WatchUpgradeSeriesNotifications()
+	if err != nil {
+		return errors.Trace(err)
+	}
+	if err := w.catacomb.Add(upgradeSeriesw); err != nil {
+		return errors.Trace(err)
+	}
+	requiredEvents++
+
 	var eventsObserved int
 	observedEvent := func(flag *bool) {
 		if flag != nil && !*flag {
@@ -407,6 +418,12 @@ func (w *RemoteStateWatcher) loop(unitTag names.UnitTag) (err error) {
 			if err != nil {
 				return err
 			}
+		case _, ok := <-upgradeSeriesw.Changes():
+			logger.Debugf("got upgrade series change")
+			if !ok {
+				return errors.New("upgrades series watcher closed")
+			}
+			observedEvent(&seenUpgradeSeriesChange)
 		case _, ok := <-addressesChanges:
 			logger.Debugf("got address change: ok=%t", ok)
 			if !ok {
@@ -845,3 +862,14 @@ func (w *RemoteStateWatcher) watchStorageAttachment(
 	w.storageAttachmentWatchers[tag] = innerSAW
 	return nil
 }
+
+func (w *RemoteStateWatcher) watchUpgradeSeries() error {
+	w.mu.Lock()
+	defer w.mu.Unlock()
+	status, err := w.unit.UpgradeSeriesStatus()
+	if err != nil {
+		return errors.Trace(err)
+	}
+	w.current.UpgradeSeriesStatus = status
+	return nil
+}

worker/uniter/remotestate/watcher_test.go

@@ -60,6 +60,7 @@ func (s *WatcherSuite) SetUpTest(c *gc.C) {
 			addressesWatcher:                 newMockNotifyWatcher(),
 			configSettingsWatcher:            newMockNotifyWatcher(),
 			applicationConfigSettingsWatcher: newMockNotifyWatcher(),
+			upgradeSeriesWatcher:             newMockNotifyWatcher(),
 			storageWatcher:                   newMockStringsWatcher(),
 			actionWatcher:                    newMockStringsWatcher(),
 			relationsWatcher:                 newMockStringsWatcher(),
@@ -151,6 +152,7 @@ func (s *WatcherSuite) TestInitialSignal(c *gc.C) {
 	s.st.unit.addressesWatcher.changes <- struct{}{}
 	s.st.unit.configSettingsWatcher.changes <- struct{}{}
 	s.st.unit.applicationConfigSettingsWatcher.changes <- struct{}{}
+	s.st.unit.upgradeSeriesWatcher.changes <- struct{}{}
 	s.st.unit.storageWatcher.changes <- []string{}
 	s.st.unit.actionWatcher.changes <- []string{}
 	if s.st.unit.application.applicationWatcher != nil {
@@ -167,6 +169,7 @@ func (s *WatcherSuite) signalAll() {
 	s.st.unit.unitWatcher.changes <- struct{}{}
 	s.st.unit.configSettingsWatcher.changes <- struct{}{}
 	s.st.unit.applicationConfigSettingsWatcher.changes <- struct{}{}
+	s.st.unit.upgradeSeriesWatcher.changes <- struct{}{}
 	s.st.unit.actionWatcher.changes <- []string{}
 	s.st.unit.application.leaderSettingsWatcher.changes <- struct{}{}
 	s.st.unit.relationsWatcher.changes <- []string{}
@@ -276,6 +279,9 @@ func (s *WatcherSuite) TestRemoteStateChanged(c *gc.C) {
 	s.st.unit.relationsWatcher.changes <- []string{}
 	assertOneChange()
 
+	s.st.unit.upgradeSeriesWatcher.changes <- struct{}{}
+	assertOneChange()
+
 	s.clock.Advance(5 * time.Minute)
 	assertOneChange()
 }

worker/uniter/resolver.go

@@ -278,6 +278,11 @@ func (s *uniterResolver) nextOp(
 		return opFactory.NewRunHook(hook.Info{Kind: hooks.ConfigChanged})
 	}
 
+	if localState.UpgradeSeriesStatus != remoteState.UpgradeSeriesStatus &&
+		remoteState.UpgradeSeriesStatus == "preparing" {
+		return opFactory.NewRunHook(hook.Info{Kind: hooks.UpgradeSeriesPrepare})
+	}
+
 	op, err := s.config.Relations.NextOp(localState, remoteState, opFactory)
 	if errors.Cause(err) != resolver.ErrNoOperation {
 		return op, err

worker/uniter/resolver/interface.go

@@ -98,4 +98,8 @@ type LocalState struct {
 	// Series is the current series running on the unit from remotestate.Snapshot
 	// for which a config-changed hook has been committed.
 	Series string
+
+	// UpgradeSeriesStatus is the current state of any currently running
+	// series upgrade or the empty string if no series upgrade has been started.
+	UpgradeSeriesStatus string
 }