Documentation for ResourceGroup inventory and migration #1269

seans3 · 2020-12-09T04:28:30Z

Adds documentation in the live command to migrate to the next generation ResourceGroup inventory object.
Adds documentation for the kpt live migrate command
Adds documentation for the kpt live install-resource-group command
Updates the documentation for the kpt live init command to add new information about initialization for the ResourceGroup inventory object.

Liujingfang1 · 2020-12-09T18:59:58Z

/lgtm

frankfarzan

First round just focusing on high level positioning of this feature.

frankfarzan · 2020-12-10T18:15:44Z

site/content/en/reference/live/_index.md

@@ -20,4 +20,129 @@ description: >

 Live contains the next-generation versions of apply related commands for
 deploying local configuration packages to a cluster.
+
+### How to Upgrade to the Next Generation Inventory Object


Note that once the next branch graduates, the new way using ResourceGroup will be the default (not opt-in). So in terms of positioning this, we want to just present the ResourceGroup first and then dedicate a section on 'migrating from legacy'.

I think this is currently assuming the change is being introduced to master.

@mortent Please comment

I believe there are basically four phases to this ResourceGroup rollout. My belief might not align with your expectations. I do not believe we will have ResourceGroup as the default for a couple months (Phase Two)--is that your expectation?

(Phase Zero) This is the current phase. The ResourceGroup functionality is hidden behind an environment variable (RESOURCE_GROUP_INVENTORY). We have not announced this functionality, and we do not expect any customers to use it. Once the environment variable is exported, new packages will use the ResourceGroup inventory object, but previously initialized packages must be manually migrated. The legacy kpt live still works using the ConfigMap inventory object.

(Phase One): This is the next phase that these docs are targeting. It is the same as phase zero, but we announce the new functionality for customers to experiment with (opt in). I'm guessing this can be rolled out the first week in the new year.

(Phase Two): We remove the environment variable gate, and the ResourceGroup functionality for new/uninitialized packages is the default. Legacy ConfigMap inventory continues to work, but there is a warning (which can be turned off) which urges customers to upgrade to the new inventory object. Migration is still manual. We will probably move to this phase a few releases after Phase One, once we are confident of the ResourceGroup functionality. I'm guessing this phase would be possible a few releases after Phase One (maybe end of February/early March).

(Phase Three): We automatically migrate packages using the legacy inventory group to the ResourceGroup inventory object. I'm guessing this would be several months after Phase Two rolls out.

So unless the next branch is not going to graduate for a few months, I do not think we are on the same page.

I think by the time we integrate ConfigSync with kpt, the ResourceGroup inventory should be the default inventory object used by kpt. Before ResourceGroup is the default one, giving a period for users to know the upcoming change is reasonable. We can document it clearly that after some (or 1-2) releases, the default inventory type will change.

frankfarzan · 2020-12-10T18:18:01Z

site/content/en/reference/live/_index.md

+#### What is an Inventory Object
+
+An inventory object is the automatically generated object which keeps track
+of the set of objects applied together. The current inventory object type


Goes back to comment above, these docs need to be future looking, so when they're released, the 'current way' will be using ResourceGroup and the 'old way' will be using ConfigMap.

frankfarzan · 2020-12-10T18:20:27Z

site/content/en/reference/live/_index.md

+**ResourceGroup** CRD is:
+
+```
+export RESOURCE_GROUP_INVENTORY=1


Given we forked a next branch, do we still want to support both mechanisms in the same version of kpt CLI? Instead we can say that version N-1 uses ConfigMap and version N uses ResourceGroup. version N provides migration tools.

Until we force customers off the legacy ConfigMap inventory object by automatically migrating them, we must allow them to run kpt live on these packages which the legacy mechanism. I do not believe we will be at that point (Phase Four) for at least six months, and probably longer.

site/content/en/reference/live/_index.md

runewake2 · 2020-12-10T19:53:40Z

site/content/en/reference/live/_index.md

+of the set of objects applied together. The current inventory object type
+is a ConfigMap, and it is usually defined in a package file called
+**inventory-template.yaml**. This file is created from an invocation of
+`kpt live init`. A typical use of the inventory object is to prune (delete)


Why do you need to delete objects omitted locally? Can you provide an example, use case or more depth on what an inventory object tracks and why? Part of this confusion may come from this being the landing page for live commands, including more context about the purpose of that set of commands may help clarify here.

site/content/en/reference/live/_index.md

runewake2 · 2020-12-10T20:01:35Z

site/content/en/reference/live/_index.md

+Packages which are newly downloaded and uninitialized should follow the
+following steps:
+
+1. `export RESOURCE_GROUP_INVENTORY=1`


This RESOURCE_GROUP_INVENTORY has been referenced multiple times but not documented yet on this page. Can you include info about what this is here or link to ./init/_index.md?

runewake2 · 2020-12-10T20:03:31Z

site/content/en/reference/live/_index.md

+
+#### What is a Next Generation Inventory Object
+
+The next generation inventory object is a **ResourceGroup** custom resource


Same comment as ConfigMap for ResourceGroup. Where do I go to find out more about this object/type, can we make that path easier?

site/content/en/reference/live/init/_index.md

runewake2 · 2020-12-10T20:19:14Z

site/content/en/reference/live/init/_index.md

+object (**ResourceGroup** custom resource). See commands `migrate` and
+`install-resource-group` for more information.
+
+The inventory object is required by other live commands


There is an inconsistency here. Some commands are formatted like migrate above but here they are not formatted like apply, preview, destroy etc. Can we make this consistent?

Can you give a bit more information about the inconsistency--thanks.

How commands are highlighted. apply, preview and destroy are not emphasized but others like migrate (above) are.

runewake2 · 2020-12-10T20:47:39Z

site/content/en/reference/live/_index.md

+kpt live install-resource-group
+```
+
+#### Upgrade Scenario 1: New (Uninitialized) Packages


I'm not sure I understand what this is upgrading. In scenario 2 certain files are migrated, but here it seems like this is getting started with the new ResourceGroup object with a new project for example.

mikebz · 2021-02-10T19:07:07Z

curious about the state of this. Seems like this hasn't been touched since December. Is this still relevant?

mikebz · 2021-03-30T03:11:47Z

bump 👋

seans3 · 2021-03-30T17:09:45Z

This was superseded by: #1357

Closing

seans3 requested review from mortent and frankfarzan December 9, 2020 04:28

seans3 added area/live documentation Improvements or additions to documentation labels Dec 9, 2020

seans3 requested a review from Liujingfang1 December 9, 2020 04:29

seans3 mentioned this pull request Dec 9, 2020

Docs for ResourceGroup inventory object (alpha) #1186

Closed

frankfarzan reviewed Dec 10, 2020

View reviewed changes

runewake2 reviewed Dec 10, 2020

View reviewed changes

seans3 force-pushed the inventory-rg-docs branch 8 times, most recently from 191ea83 to 3827a44 Compare December 14, 2020 06:14

First pass at ResourceGroup inventory docs

ada953a

seans3 force-pushed the inventory-rg-docs branch from 3827a44 to ada953a Compare December 14, 2020 06:16

seans3 closed this Mar 30, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Documentation for ResourceGroup inventory and migration #1269

Documentation for ResourceGroup inventory and migration #1269

seans3 commented Dec 9, 2020

Liujingfang1 commented Dec 9, 2020

frankfarzan left a comment

frankfarzan Dec 10, 2020

seans3 Dec 14, 2020 •

edited

Loading

Liujingfang1 Dec 14, 2020

frankfarzan Dec 10, 2020 •

edited

Loading

frankfarzan Dec 10, 2020 •

edited

Loading

seans3 Dec 14, 2020

runewake2 Dec 10, 2020

runewake2 Dec 10, 2020

runewake2 Dec 10, 2020

runewake2 Dec 10, 2020

seans3 Dec 14, 2020

runewake2 Dec 14, 2020

runewake2 Dec 10, 2020

mikebz commented Feb 10, 2021

mikebz commented Mar 30, 2021

seans3 commented Mar 30, 2021


		#### What is a Next Generation Inventory Object

		The next generation inventory object is a ResourceGroup custom resource

Documentation for ResourceGroup inventory and migration #1269

Documentation for ResourceGroup inventory and migration #1269

Conversation

seans3 commented Dec 9, 2020

Liujingfang1 commented Dec 9, 2020

frankfarzan left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

seans3 Dec 14, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

frankfarzan Dec 10, 2020 • edited Loading

Choose a reason for hiding this comment

frankfarzan Dec 10, 2020 • edited Loading

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

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

mikebz commented Feb 10, 2021

mikebz commented Mar 30, 2021

seans3 commented Mar 30, 2021

seans3 Dec 14, 2020 •

edited

Loading

frankfarzan Dec 10, 2020 •

edited

Loading

frankfarzan Dec 10, 2020 •

edited

Loading