VOL-3265: Documentation for image managment and moving images to images subdir
Change-Id: I220a8db8d4fc604ad0a431b416627a9c23691818
diff --git a/docs/DeviceImageManagement.md b/docs/DeviceImageManagement.md
new file mode 100644
index 0000000..0396ad2
--- /dev/null
+++ b/docs/DeviceImageManagement.md
@@ -0,0 +1,37 @@
+# Software Image Management
+
+The software image management that this interface addresses are for devices that can be managed over IP directly.
+
+The below diagram shows the message flows for the different Image management RPCs.
+
+
+
+``` protobuf
+service NativeSoftwareManagementService {
+ // Get the software version information of the Active and Standby images
+ rpc GetSoftwareVersion(HardwareID) returns(SoftwareVersionInformation);
+
+ // Downloads and installs the image in the standby partition, returns the status/progress of the Install
+ rpc DownloadImage(DownloadImageRequest) returns(stream ImageStatus);
+
+ // Activates and runs the OLT with the image in the standby partition. If things are fine this image will
+ // henceforth be marked as the Active Partition. The old working image would remain on the Standby partition.
+ // Any possibly required (sub-)steps like "commit" are left to the "Device Manager"
+ rpc ActivateImage(HardwareID) returns(stream ImageStatus);
+
+ // Marks the image in the Standby as Active and reboots the device, so that it boots from that image which was in the standby.
+ // This API is to be used if operator wants to go back to the pervious software
+ rpc RevertToStandbyImage(HardwareID) returns(stream ImageStatus);
+}
+```
+The download of the image always happens on the standby. As of now the support is for one active image/partition and one standby image/partition. The download procedure would encompass the download as well as installation of the image and also any required configurations to be applied.
+
+The ActivateImage RPC always would activate the standby image/partition. This will trigger a reboot of the device to boot from the standby partition/image. After the boot of the new image, some tests are expected to run to validate if the activation was successful or not and only then would the image be committed. How such tests are run are upto the implementation of the device manager. If it's not able to activate the image, then it should fall back to the previous image automatically. This is especially important for devices which are in-band managed, as there is a possiblity that management plane could lose connectivity to the device in such a state.
+
+The RevertToStandbyImage is different from ActivateImage; it assumes that the standby image/partition was already a working version and so it would not run the image activation sanity checks (the same checks which are run when during the ActivateIamge RPC) when booted from the standby image. This would help the human operator to intervene and break a loop if boot up tests keep failing.
+
+As the image activation sanity checks are not run in this case, it is upto to operator to ensure that the image on the standby is a good working version. Additionally implementations can cross check if the image on the standby is a good already committed version else give an error response for this rpc.
+
+The status of the download, activation or reverting are also sent to the kafka bus in addition to the return of the grpc stream. This would help other components in the system which would want to monitor the progress of such processes.
+
+In the case when an OLT device gets upgraded; for other external systems like vOLTHA, it would just be a reboot of the OLT and should be handled exactly the same way. ***If*** OLT/adapter/agent implementations stores **presistent** config on the OLT then it needs to be ensured that this is available with the upgraded image so that vOLTHA does not see any difference compared to a reboot.
diff --git a/docs/EventsMetrics.md b/docs/EventsMetrics.md
index 06c6fc2..89c1e22 100644
--- a/docs/EventsMetrics.md
+++ b/docs/EventsMetrics.md
@@ -4,7 +4,7 @@
Kafka has been chosen as a means to export from the device manager as it is suitable for handling asynchronous events. Persistence for the events and metrics can be easily achieved using kafka. Moreover kafka gives the flexibilites of handling and processing of the events and metrics by different/mulitple north-bound components/processes. Implementations could choose to have different services (with potentially multiple instances) handling the events and metrics.
-
+
The kafka topics to which these are written should be configurable at startup of the components, so that different deployments have the flexibility of choosing those.
The recomendation is to use **dm.events** for the events and **dm.metrics** for the metrics as the names of the kafka topics.
diff --git a/docs/ManagingDevice.md b/docs/ManagingDevice.md
index d5ad632..0d9f0c2 100644
--- a/docs/ManagingDevice.md
+++ b/docs/ManagingDevice.md
@@ -3,7 +3,7 @@
The first API that a NEM would need to excute to start managing a hardware is the StartManagingDevice.
## StartManagingDevice
-
+
``` protobuf
service NativeHWManagementService {
// Initializes context for a device and sets up required states
diff --git a/docs/images/device_image_management.drawio b/docs/images/device_image_management.drawio
new file mode 100755
index 0000000..5c01d87
--- /dev/null
+++ b/docs/images/device_image_management.drawio
@@ -0,0 +1 @@
+<mxfile host="app.diagrams.net" modified="2020-06-29T11:48:53.626Z" agent="5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/83.0.4103.106 Safari/537.36" etag="qwyU_s7QNBXzcsea6F3X" version="13.3.0" type="device"><diagram id="sCnCeIqNfmzJz7ndoayB" name="Page-1">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</diagram></mxfile>
\ No newline at end of file
diff --git a/docs/images/device_image_management.png b/docs/images/device_image_management.png
new file mode 100755
index 0000000..48dbab3
--- /dev/null
+++ b/docs/images/device_image_management.png
Binary files differ
diff --git a/docs/events_metrics.drawio b/docs/images/events_metrics.drawio
similarity index 100%
rename from docs/events_metrics.drawio
rename to docs/images/events_metrics.drawio
diff --git a/docs/events_metrics.png b/docs/images/events_metrics.png
similarity index 100%
rename from docs/events_metrics.png
rename to docs/images/events_metrics.png
Binary files differ
diff --git a/docs/managing_device.drawio b/docs/images/managing_device.drawio
similarity index 100%
rename from docs/managing_device.drawio
rename to docs/images/managing_device.drawio
diff --git a/docs/managing_device.png b/docs/images/managing_device.png
similarity index 100%
rename from docs/managing_device.png
rename to docs/images/managing_device.png
Binary files differ
