doc: add document pouch_with_upgrade.md #2346

HusterWan · 2018-10-23T08:38:23Z

Signed-off-by: Michael Wan zirenwan@gmail.com

Ⅰ. Describe what this PR did

Add introduction document for upgrade interface.

You can get information about the design of upgrade interface, of cause about how to use the upgrade cli tools from the document.

Ⅱ. Does this pull request fix one issue?

fixes #968

Ⅲ. Why don't you add test cases (unit test/integration test)? (你真的觉得不需要加测试吗？)

add a doc

Ⅳ. Describe how to verify it

Ⅴ. Special notes for reviews

codecov · 2018-10-23T08:38:25Z

Codecov Report

Merging #2346 into master will decrease coverage by 14.91%.
The diff coverage is n/a.

@@             Coverage Diff             @@
##           master    #2346       +/-   ##
===========================================
- Coverage   67.85%   52.94%   -14.92%     
===========================================
  Files         265      265               
  Lines       18211    18211               
===========================================
- Hits        12357     9641     -2716     
- Misses       4421     7499     +3078     
+ Partials     1433     1071      -362

Flag	Coverage Δ
#criv1alpha1test	`?`
#criv1alpha2test	`?`
#integrationtest	`39.53% <ø> (+0.04%)`	⬆️
#nodee2etest	`?`
#unittest	`25.31% <ø> (ø)`	⬆️

Impacted Files	Coverage Δ
cri/v1alpha1/cri_types.go	`0% <0%> (-100%)`	⬇️
cri/v1alpha2/cri_types.go	`0% <0%> (-100%)`	⬇️
cri/v1alpha2/service/cri.go	`0% <0%> (-89.48%)`	⬇️
cri/v1alpha1/service/cri.go	`0% <0%> (-84.62%)`	⬇️
cri/stream/remotecommand/websocket.go	`0% <0%> (-81.54%)`	⬇️
cri/stream/remotecommand/exec.go	`0% <0%> (-80%)`	⬇️
daemon/containerio/streams.go	`20.68% <0%> (-79.32%)`	⬇️
cri/v1alpha2/server.go	`0% <0%> (-79.2%)`	⬇️
cri/v1alpha1/server.go	`0% <0%> (-79.2%)`	⬇️
daemon/containerio/cri_log_file.go	`11.76% <0%> (-76.48%)`	⬇️
... and 45 more

allencloud · 2018-10-23T14:59:46Z

docs/features/pouch_with_upgrade.md

+
+## Introduction
+
+Most containers within Alibaba are used in rich container mode. Some containers among the rich containers in traditional virtual machine O&M mode are still stateful. Updates and upgrades of stateful services are frequently performed daily operations within Alibaba. For the container technology that delivers images, the container operations corresponding to service update and upgrade include two steps: deletion of old image container and creation of the new image container.


I do not think it is a good way to mention Alibaba in the general technical documents. Since what you invent is quite a general feature for the whole industry, explicit explanation for you feature is enough to make it clear.

great advise

allencloud · 2018-10-23T15:02:27Z

I think upgrade feature is general for all kinds of containers, not only stateful containers with storage, but also other ip-fixed containers. So could we ignore the rich container mode in the upgrade document. With mentioning rich container, it will mislead end-users that only rich container mode needs upgrade feature you invented. @HusterWan WDYT?

allencloud · 2018-10-23T15:03:28Z

docs/features/pouch_with_upgrade.md

+
+* Customer Case 2: In a middleware service, the service registration mode is used. That is, the IP addresses of the scaled-up containers must be registered in the server list; otherwise, the containers are invalid. The new containers must inherit the IP addresses of old containers every time the service containers are upgraded; otherwise, the new services are invalid.
+
+## Design


With the design, could you add a graph to illustrate it clearly? 😆

already added

allencloud · 2018-10-23T15:04:54Z

docs/features/pouch_with_upgrade.md

+
+## Design
+
+Before using the `upgrade` interface, we should figure out which parameter of container you want to update ? If you want to update a container's [Resources](../../apis/types/resources.go), I think you should use the `update` interface. If you just want to update a container's image and inherit the volumes and network from the old container, now you should use the `upgrade` interface.


Here you need to the following part outlined:

Difference between UPDATE and UPGRADE

blabla

allencloud · 2018-10-23T15:10:28Z

docs/features/pouch_with_upgrade.md

+}
+```
+
+It is enough to update a container from a old image to a new one now. If anyone has new situation need to add more parameters into `ContainerUpgradeConfig`, we can create a new issue to discuss it.


s/a old/an old

When you are using upgrade feature, please try to use word upgrade rather than update.
I think this would reduce something ambiguous.

you are right

allencloud · 2018-10-23T15:11:46Z

docs/features/pouch_with_upgrade.md

+
+### About core logic
+
+#### Which cmd should be used to create the new container when upgrade


s/cmd/CMD

Which CMD is used when upgrading a container?

allencloud · 2018-10-23T15:16:17Z

docs/features/pouch_with_upgrade.md

+
+#### rollback of upgrade failure
+
+When occurred any error during upgrade, we should have the ability to rollback the upgrade and recover the old container just like it before.


When any errors occur during upgrade procedure, pouchd will automatically rollback the whole upgrade operation and the old container will be recovered just like it was.

allencloud · 2018-10-23T15:17:08Z

docs/features/pouch_with_upgrade.md

+
+When occurred any error during upgrade, we should have the ability to rollback the upgrade and recover the old container just like it before.
+
+### Show the upgrade feature


Quick Start

or

Example

HusterWan · 2018-10-25T02:17:59Z

I have updated this doc, PTAL thanks @allencloud

allencloud · 2018-10-25T17:07:34Z

docs/features/pouch_with_upgrade.md

+
+The following architecture graph shows how to upgrade a container:
+
+![pouch_with_upgrade](../static_files/pouch_with_upgrade.png)


why not take three steps to explain this graph? 😃

first, inherit container attributes from the old container in pouchd's memory;
second, replace container image via ......
third, just start the newly constructed command if needed.

Otherwise, people may not have sense of it. WDYT? @HusterWan

Sometimes, only sentence is not convincing. If only a graph, still not so convincing.
However if we combine sentences and graphs, it appears so clear.

allencloud · 2018-10-26T07:58:42Z

LGTM until the graph explanation part finishes. @HusterWan

HusterWan · 2018-10-26T08:09:11Z

LGTM until the graph explanation part finishes. @HusterWan

@allencloud I will updated right now

Signed-off-by: Michael Wan <zirenwan@gmail.com>

allencloud · 2018-10-26T09:52:21Z

Thanks for your update. @HusterWan
Merging...

pouchrobot added areas/docs size/L labels Oct 23, 2018

HusterWan force-pushed the zr/add-upgrade-doc branch from 738bcdb to 633cf57 Compare October 23, 2018 08:53

allencloud self-assigned this Oct 23, 2018

allencloud reviewed Oct 23, 2018

View reviewed changes

HusterWan force-pushed the zr/add-upgrade-doc branch 3 times, most recently from 7ff83dc to 549748b Compare October 24, 2018 04:17

allencloud reviewed Oct 25, 2018

View reviewed changes

pouchrobot added the LGTM one maintainer or community participant agrees to merge the pull reuqest. label Oct 26, 2018

HusterWan force-pushed the zr/add-upgrade-doc branch 2 times, most recently from 9ef8a80 to 9acb912 Compare October 26, 2018 08:46

doc: add document pouch_with_upgrade.md

5fadbaf

Signed-off-by: Michael Wan <zirenwan@gmail.com>

HusterWan force-pushed the zr/add-upgrade-doc branch from 9acb912 to 5fadbaf Compare October 26, 2018 08:53

allencloud merged commit 66c384a into AliyunContainerService:master Oct 26, 2018

This was referenced Oct 27, 2018

Weekly Report of PouchContainer from 2018-10-20 to 2018-10-27 #2368

Closed

WeeklyReport of PouchContainer from 2018-10-26 to 2018-11-02 #2412

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc: add document pouch_with_upgrade.md #2346

doc: add document pouch_with_upgrade.md #2346

HusterWan commented Oct 23, 2018

codecov bot commented Oct 23, 2018 •

edited

Loading

allencloud Oct 23, 2018

HusterWan Oct 24, 2018

allencloud commented Oct 23, 2018

allencloud Oct 23, 2018

HusterWan Oct 25, 2018

allencloud Oct 23, 2018

allencloud Oct 23, 2018

HusterWan Oct 24, 2018

allencloud Oct 23, 2018

allencloud Oct 23, 2018

allencloud Oct 23, 2018

HusterWan commented Oct 25, 2018

allencloud Oct 25, 2018 •

edited

Loading

allencloud commented Oct 26, 2018

HusterWan commented Oct 26, 2018

allencloud commented Oct 26, 2018


		## Introduction

		Most containers within Alibaba are used in rich container mode. Some containers among the rich containers in traditional virtual machine O&M mode are still stateful. Updates and upgrades of stateful services are frequently performed daily operations within Alibaba. For the container technology that delivers images, the container operations corresponding to service update and upgrade include two steps: deletion of old image container and creation of the new image container.


		* Customer Case 2: In a middleware service, the service registration mode is used. That is, the IP addresses of the scaled-up containers must be registered in the server list; otherwise, the containers are invalid. The new containers must inherit the IP addresses of old containers every time the service containers are upgraded; otherwise, the new services are invalid.

		## Design


		## Design

		Before using the `upgrade` interface, we should figure out which parameter of container you want to update ? If you want to update a container's [Resources](../../apis/types/resources.go), I think you should use the `update` interface. If you just want to update a container's image and inherit the volumes and network from the old container, now you should use the `upgrade` interface.


		### About core logic

		#### Which cmd should be used to create the new container when upgrade


		#### rollback of upgrade failure

		When occurred any error during upgrade, we should have the ability to rollback the upgrade and recover the old container just like it before.


		When occurred any error during upgrade, we should have the ability to rollback the upgrade and recover the old container just like it before.

		### Show the upgrade feature


		The following architecture graph shows how to upgrade a container:

		![pouch_with_upgrade](../static_files/pouch_with_upgrade.png)

doc: add document pouch_with_upgrade.md #2346

doc: add document pouch_with_upgrade.md #2346

Conversation

HusterWan commented Oct 23, 2018

Ⅰ. Describe what this PR did

Ⅱ. Does this pull request fix one issue?

Ⅲ. Why don't you add test cases (unit test/integration test)? (你真的觉得不需要加测试吗？)

Ⅳ. Describe how to verify it

Ⅴ. Special notes for reviews

codecov bot commented Oct 23, 2018 • edited Loading

Codecov Report

Choose a reason for hiding this comment

Choose a reason for hiding this comment

allencloud commented Oct 23, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Difference between UPDATE and UPGRADE

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

HusterWan commented Oct 25, 2018

allencloud Oct 25, 2018 • edited Loading

Choose a reason for hiding this comment

allencloud commented Oct 26, 2018

HusterWan commented Oct 26, 2018

allencloud commented Oct 26, 2018

codecov bot commented Oct 23, 2018 •

edited

Loading

allencloud Oct 25, 2018 •

edited

Loading