VeritasOS · abhijithda · May 1, 2021 · Jun 6, 2021 · Jun 6, 2021 · May 1, 2021
diff --git a/.github/workflows/go.yml b/.github/workflows/go.yml
@@ -2,9 +2,9 @@ name: Go
 
 on:
   push:
-    branches: [ main ]
+    branches: [ v1]
   pull_request:
-    branches: [ main ]
+    branches: [ v1]
 
 jobs:
 

diff --git a/Makefile b/Makefile
@@ -8,6 +8,7 @@ help:	## Display this help message.
 
 TOP=$(CURDIR)
 BUILDDATE ?= $(shell /usr/bin/date -u +%Y%m%d%H%M%S)
+TAR = /bin/tar
 
 # Go build related variables
 GOSRC=$(TOP)
@@ -19,11 +20,13 @@ GOTOOLSBIN=$(TOP)/tools/go/
 
 # SUM SDK related variables
 SDK_NAME = sum-sdk
-# Keep the SDK_VERSION same as ASUM_RPM_FORMAT_VERSION.
+# Keep the SDK_VERSION same as RPM_FORMAT_VERSION.
 SDK_VERSION = 2.0
 SDK_REVERSION = 1
 SDK_SOURCE_PATH	= $(TOP)/sdk
 
+TAR       = /bin/tar
+
 .SILENT:
 
 .PHONY: all
@@ -124,24 +127,177 @@ go-race: 	## Run Go tests with race detector enabled
 
 .PHONY: .copy_update_binaries
 .copy_update_binaries: build
-	echo "Copying ASUM SDK related binaries...";
+	echo "Copying SUM SDK related binaries...";
 	cp -prf $(GOBIN)/* $(SDK_SOURCE_PATH)/scripts/; \
 	if [ $$? -ne 0 ]; then \
  		echo "ERROR: $${f} failed to copy to $(SDK_SOURCE_PATH)/scripts/"; \
 		exit 1; \
 	fi;
 
-.PHONY: ship-asum-sdk
-ship-asum-sdk: .copy_update_binaries
-	@echo "Creating ASUM SDK tar..."
+SUM_PATH = $(TOP)/
+SAMPLE_UPDATE= $(SUM_PATH)/sample/update/
+PRODUCT_VERSION = 1.0
+tmp_SUM_SDK = $(TOP)/tmp/sum-sdk
+tmp_SHIP_DIR = $(TOP)/tmp/ship
+
+# Ship SDK and create sample update RPM
+SUM_PATH = $(TOP)/
+SAMPLE_UPDATE = $(SUM_PATH)/sample/update
+PRODUCT_VERSION = 1.0
+tmp_SUM_SDK = $(TOP)/tmp/sum-sdk
+tmp_SHIP_DIR = $(TOP)/tmp/ship
+
+.PHONY: ship-sum-sdk
+ship-sum-sdk: .copy_update_binaries
+	@echo "Creating SUM SDK tar..."
 	# cp $(TOP)/tools/mkrpm.sh $(SDK_SOURCE_PATH)/;
 	ship_dir=$(TOP); \
 	if [ -n "$(SHIP_DIR)" ]; then \
 		ship_dir=$(SHIP_DIR); \
 		mkdir -p $${ship_dir} || exit 1; \
 	fi; \
-	asum_sdk_tar="$${ship_dir}/$(SDK_NAME)-$(SDK_VERSION)-$(SDK_REVERSION)-$(BUILDDATE).tar.gz"; \
-	/bin/tar -czf $${asum_sdk_tar} -C $(SDK_SOURCE_PATH) .; \
-	echo "Successfully created ASUM SDK at $${asum_sdk_tar}.";
+	sum_sdk_tar="$${ship_dir}/$(SDK_NAME)-$(SDK_VERSION)-$(SDK_REVERSION)-$(BUILDDATE).tar.gz"; \
+	/bin/tar -czf $${sum_sdk_tar} -C $(SDK_SOURCE_PATH) .; \
+	echo "Successfully created SUM SDK at $${sum_sdk_tar}.";
+
+.PHONY: getsumsdk
+getsumsdk:
+	# NOTE: Usually the SUM SDK will be extracted from an already built tar.
+	#       But here, in this case, we need to first build the
+	#       SUM SDK tar and then consume it here.
+	echo "=============== Get SUM SDK ===============";
+	ship_dir=$(tmp_SHIP_DIR); \
+	rm -rf $${ship_dir}; \
+	$(MAKE) -C $(SUM_PATH) ship-sum-sdk SHIP_DIR=$${ship_dir}; \
+	echo "===============  extracting sum-sdk tar file =========================="; \
+	mkdir -p $(tmp_SUM_SDK); \
+	$(TAR) -xzvf $${ship_dir}/sum-sdk-*.tar.gz -C $(tmp_SUM_SDK); \
+	if [ $$? -ne 0 ]; then \
+		echo "ERROR: Failed to extract sum-sdk to $(tmp_SUM_SDK)"; \
+		exit 1; \
+	fi;
+
+# TODO: Update below target to download from github.
+.PHONY: get_remote_sum_sdk
+get_remote_sum_sdk:
+	# Avoid downloading it again when it's already present. Run `get_latest_asum_sdk` to get latest.
+ifeq ($(shell ls $(tmp_SUM_SDK)/.no-latest 2> /dev/null),) 
+	$(ECHO) "===== Downloading ASUM RPM Generation utility (asum-sdk) $(tmp_SUM_SDK) =====";
+	$(RM) -rf $(tmp_SUM_SDK); 
+	$(MKDIR) -p $(tmp_SUM_SDK);
+	px_api_url="$(HTTP_ARTIFACTORY)/api/storage/release/platformx/main"; \
+	px_ver=$$($(CURL) $${px_api_url} | jq -c '.children[] | select(.folder)' | sort -V | tail -2 | head -1 | jq .uri); \
+	px_ver=$${px_ver:2:-1}; \
+	px_buildtag=$${px_ver##*-}; \
+	$(ECHO) "PlatformX latest version-buildtag: $${px_ver}"; \
+	rpm_name=$$($(CURL) $(HTTP_ARTIFACTORY)/api/storage/release/platformx/main/$${px_ver}/ \
+		| jq '.children[].uri' | grep asum-sdk); \
+	rpm_name=$${rpm_name%\"}; \
+	rpm_name=$${rpm_name#\"}; \
+	$(ECHO) "RPM: $${rpm_name}"; \
+	$(ECHO) "===== Downloading $${rpm_name} ====="; \
+	asum_url="$(HTTP_ARTIFACTORY)/release/platformx/main/$${px_ver}/"; \
+	$(WGET) $${asum_url}/$${rpm_name} -P $(tmp_SUM_SDK); \
+	if [ $$? -ne 0 ] ; then \
+		$(ECHO) "ERROR: $(WGET) $${rpm_name} failed to download."; \
+		exit 1; \
+	fi ; \
+	$(ECHO) Successfully downloaded $${rpm_name} into $(tmp_SUM_SDK);
+
+	echo "===============  Extracting asum-sdk =========================="; \
+	$(TAR) -xzvf $(tmp_SUM_SDK)/asum-sdk-*.tar.gz -C $(tmp_SUM_SDK); \
+	if [ $$? -ne 0 ]; then \
+	    echo "ERROR: Failed to extract asum-sdk to $(tmp_SUM_SDK)"; \
+		exit 1; \
+	fi;
+	$(ECHO) "To avoid downloading latest SUM SDK again and again on local " \
+		"builds, you can touch $(tmp_SUM_SDK)/.no-latest file. "
+	# touch $(tmp_SUM_SDK)/.no-latest
+endif
+
+.PHONY: sampleupdate_usinglocalsdk
+sampleupdate_usinglocalsdk: getsumsdk
+	echo "===============  Creating a sample update RPM   ===============";
+	git checkout -- $(TOP)/sample/update/library/version/version.install $(TOP)/sample/update/rpm-info.json
+	myVersion=$(PRODUCT_VERSION).9; \
+	sed -i -e "s%__VERSION__%$${myVersion}%g" $(TOP)/sample/update/library/version/version.install; \
+	sed -i -e "s%__PRODUCT_VERSION__%$(PRODUCT_VERSION)%g" $(TOP)/sample/update/rpm-info.json; \
+	JenkinsOptions=""; \
+	ship_dir=$(tmp_SHIP_DIR); \
+	if [ -n "$(JENKINS_URL)" ]; then \
+		JenkinsOptions="BUILDDATE=$${BUILDTAG##*-}"; \
+		ship_dir=$(JENKINS_UPLOAD_DEST); \
+	fi; \
+	$(MAKE) -C $(SAMPLE_UPDATE) update \
+		SUM_SDK_PATH=$(tmp_SUM_SDK) \
+		SHIP_DIR=$${ship_dir} \
+		UPDATE_VERSION=$${myVersion} \
+		$${JenkinsOptions};
+	git checkout -- $(TOP)/sample/update/library/version/version.install $(TOP)/sample/update/rpm-info.json
+
+
+.PHONY: sampleupdates
+sampleupdates: sampleupdate_usinglocalsdk sampleupdate sampleupdate_reboot_commit sampleupdate_no_version_change
+
+.PHONY: sampleupdate
+sampleupdate: get_remote_sum_sdk
+	$(ECHO) "======== Generating sample update RPM using SUM SDK..."; \
+	git checkout -- samples/update/library/node-version/node-version.install
+	myVersion=$(VERSION).0.9; \
+	sed -i -e "s%__VERSION__%$${myVersion}%g" $(TOP)/samples/update/library/node-version/node-version.install; \
+	ship_dir=$(TOP); \
+	if [ -n "$(JENKINS_URL)" ]; then \
+		Options="RPM_RELEASE=$${BUILDTAG##*-}"; \
+		ship_dir=$(TOP)/$(PRODUCT)/$(BRANCH)/$(BUILDTAG); \
+	fi; \
+	$(MAKE) -C $(tmp_SUM_SDK) generate \
+		PLUGINS_LIBRARY=$(TOP)/samples/update/library/ \
+		RPM_INFO_FILE=$(TOP)/samples/update/rpm-info.json \
+		RPM_URL=https://github.com/VeritasOS/software-update-manager \
+		RPM_VERSION=$${myVersion} \
+		SHIP_DIR=$${ship_dir} \
+		$${Options} || exit $$?
+	git checkout -- samples/update/library/node-version/node-version.install
+
+.PHONY: sampleupdate_reboot_commit
+sampleupdate_reboot_commit: get_remote_sum_sdk
+	$(ECHO) "======== Generating sample update RPM requiring reboot using SUM SDK...";
+	git checkout -- samples/update-reboot-commit/library/node-version/node-version.install
+	myVersion=$(VERSION).9; \
+	sed -i -e "s%__VERSION__%$${myVersion}%g" $(TOP)/samples/update-reboot-commit/library/node-version/node-version.install; \
+	ship_dir=$(TOP); \
+	if [ -n "$(JENKINS_URL)" ]; then \
+		Options="RPM_RELEASE=$${BUILDTAG##*-}"; \
+		ship_dir=$(TOP)/$(PRODUCT)/$(BRANCH)/$(BUILDTAG); \
+	fi; \
+	$(MAKE) -C $(tmp_SUM_SDK) generate \
+		PLUGINS_LIBRARY=$(TOP)/samples/update-reboot-commit/library/ \
+		RPM_INFO_FILE=$(TOP)/samples/update-reboot-commit/rpm-info.json \
+		RPM_URL=https://github.com/VeritasOS/software-update-manager \
+		RPM_VERSION=$${myVersion} \
+		SHIP_DIR=$${ship_dir} \
+		$${Options} || exit $$?
+	git checkout -- samples/update-reboot-commit/library/node-version/node-version.install
+
+.PHONY:sampleupdate_no_version_change
+sampleupdate_no_version_change:
+	$(ECHO) "======== Generating sample update RPM using SUM SDK..."; \
+	myVersion=2.0.0.0.$${BUILDTAG##*-}; \
+	ship_dir=$(tmp_SHIP_DIR); \
+	if [ -n "$(JENKINS_URL)" ]; then \
+		Options="RPM_RELEASE=$${BUILDTAG##*-}"; \
+		ship_dir=$(TOP)/$(PRODUCT)/$(BRANCH)/$(BUILDTAG); \
+	fi; \
+	$(MAKE) -C $(tmp_SUM_SDK) generate \
+		PLUGINS_LIBRARY=$(TOP)/samples/update-no-version-change/library/ \
+		RPM_INFO_FILE=$(TOP)/samples/update-no-version-change/rpm-info.json \
+		RPM_URL=https://github.com/VeritasOS/software-update-manager \
+		RPM_VERSION=$${myVersion} \
+		SHIP_DIR=$${ship_dir} \
+		$${Options} || exit $$?
+
+.PHONY: clean-update
+clean-update:
+	$(RM) -rf $(tmp_SUM_SDK)
 
 .NOTPARALLEL:
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 # Software Update Manager (SUM)
 
-[![Go](https://github.com/VeritasOS/software-update-manager/actions/workflows/go.yml/badge.svg)](https://github.com/VeritasOS/software-update-manager/actions/workflows/go.yml)
+[![Go](https://github.com/VeritasOS/software-update-manager/actions/workflows/go.yml/badge.svg?branch=v1)](https://github.com/VeritasOS/software-update-manager/actions/workflows/go.yml)
 
 The Software Update Manager (SUM) provides ability to update a system. It could be used to perform major or minor updates. The main difference of major and minor updates is whether the update RPM contains the entire ISO contents or not. The SUM framework can be used to perform live update or an offline update (i.e., utilitizing a separate partition). It relies on [Plugin Manager](https://"github.com/VeritasOS/plugin-manager) & Plugins to drive or replay any required configuration. The SUM architecture & workflow can be found in the following sections.
 
@@ -9,19 +9,26 @@ The Software Update Manager (SUM) provides ability to update a system. It could
 <!-- TOC -->
 
 - [Software Update Manager (SUM)](#software-update-manager-sum)
-- [Architecture](#architecture)
-- [Workflow](#workflow)
-  - [Plugins](#plugins)
-    - [Install](#install)
-    - [Reboot](#reboot)
-    - [Rollback](#rollback)
-    - [Commit](#commit)
-- [Generating Update RPM](#generating-update-rpm)
-- [Sample Update](#sample-update)
+  - [Architecture](#architecture)
+  - [Workflow](#workflow)
+    - [Plugins](#plugins)
+      - [Install](#install)
+      - [Reboot](#reboot)
+      - [Rollback](#rollback)
+      - [Commit](#commit)
+  - [Generating Update RPM](#generating-update-rpm)
+  - [Sample Update](#sample-update)
+  - [Usage](#usage)
+    - [Add software to repository](#add-software-to-repository)
+    - [List software](#list-software)
+    - [Delete software](#delete-software)
+    - [Install ${software_type} RPM](#install-software_type-rpm)
+    - [Commit ${software_type} RPM](#commit-software_type-rpm)
+    - [Rollback ${software_type} RPM](#rollback-software_type-rpm)
 
 <!-- /TOC -->
 
-# Architecture
+## Architecture
 
 At a high-level, the SUM architecture is as shown below.
 
@@ -36,13 +43,13 @@ At a high-level, the SUM architecture is as shown below.
 
 > NOTE: SUM is designed to update system locally. The rolling updates in case of cluster, should be handled by the orchestration layer.
 
-# Workflow
+## Workflow
 
 This section details out the design of the SUM Update Framework.
 
 ![SUM Update Framework](./docs/imgs/Update_Framework.svg)
 
-## Plugins
+### Plugins
 
 The SUM Framework uses [Plugin Manager (PM)](./pm.md) to perform several of it's actions, and defines the types of plugins to perform following user actions: install, reboot, rollback and commit in the below sections.
 The framework also defines certain variables to enable plugins to access following paths:
@@ -52,14 +59,14 @@ The framework also defines certain variables to enable plugins to access followi
 | `${PM_LIBRARY}` | Plugins library path. |
 | `${VXAPP_UPGRADE_ROOT}` | Alternate root volume path for doing offline updates. |
 
-### Install
+#### Install
 
 | Types | File extensions | Examples |
 | --- | --- | --- |
 | Pre-install update actions | `.preinstall` | - Bind mount required file systems inside update volume before installing RPM/ISO, to share configuration that could be used during install step. One could have say `mountfs.preinstall` plugin to perform the same action. <br> - Check whether application is stopped. |
 | Install update actions | `.install` | VUF install could be used with appropriate arguments to perform either live or offline update. |
 
-### Reboot
+#### Reboot
 
 | Types | File extensions | Examples |
 | --- | --- | --- |
@@ -68,15 +75,15 @@ The framework also defines certain variables to enable plugins to access followi
 
 > **NOTE:** If an action can be performed before the reboot, then it is recommended to do it in the `.prereboot` plugin rather than a `.postreboot` plugin, so that if there are any failures, it can be caught before reboot which helps in avoiding downtime for customers.
 
-### Rollback
+#### Rollback
 
 | Types | File extensions | Examples |
 | --- | --- | --- |
 | Prechecks before starting rollback | `.rollback-precheck` | - Check whether node is updated. <br> - Check whether instances are stopped. |
 | Pre rollback actions | `.prerollback` | - Set Grub to boot to old version in case of using offline update approach. <br> - Revert snapshot. |
 | Rollback actions | `.rollback` | - Remove new version container images. |
 
-### Commit
+#### Commit
 
 | Types | File extensions | Examples |
 | --- | --- | --- |
@@ -90,13 +97,78 @@ The framework also defines certain variables to enable plugins to access followi
 The update plugins must be deployed into a plugin folder under plugins library path i.e., `${PM_LIBRARY}/<plugin-folder>/`.
 To access this path in plugins, one must use environment variable `${PM_LIBRARY}` to access the plugins library location.
 
-# Generating Update RPM
+## Generating Update RPM
 
 An update RPM should be SUM format compliant in order for one to successfully
 install the update. In order to generate such an RPM, one should use SUM SDK.
 For more details about SDK, refer to [SUM SDK](./sdk/README.md).
 
-# Sample Update
+## Sample Update
 
 A example usage of the framework can be found here:
 [sample-update](sample/update/Makefile).
+
+## Usage
+
+The following sub-sections detail out the software update manager command tool usage. The default values of some of the optional parameters are as follows:
+
+- `repo`: `"/system/software/repository/"`
+- `output_format`: `"yaml"`
+
+### Add software to repository
+
+```bash
+$ ${sum_binary} repo add -filepath=${software_staging_area}/${software_name}
+[ -repo=${software_repo} ]
+```
+
+### List software
+
+```bash
+$ ${sum_binary} repo list 
+[ -repo=${software_repo} ]
+[ -type=${software_type} ]
+[ -filename=${software_name} ]
+```
+
+### Delete software
+
+```bash
+$ ${sum_binary} repo remove
+-type=${software_type}
+-filename=${software_name}
+[ -repo=${software_repo} ]
+[ -output-file=${output_file} ]
+[ -output-format=${output_format} ]
+```
+
+### Install ${software_type} RPM
+
+```bash
+$ ${sum_binary} install
+-filename=${software_name}
+-type=${software_type}
+[ -repo=${software_repo} ]
+```
+
+### Commit ${software_type} RPM
+
+```bash
+$ ${sum_binary} commit
+-filename=${software_name}
+-type=${software_type}
+[ -repo=${software_repo} ]
+[ -output-file=${output_file} ]
+[ -output-format=${output_format} ]
+```
+
+### Rollback ${software_type} RPM
+
+```bash
+$ ${sum_binary} rollback
+-filename=${software_name}
+-type=${software_type}
+[ -repo=${software_repo} ]
+[ -output-file=${output_file} ]
+[ -output-format=${output_format} ]
+```