Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation for ResourceGroup inventory and migration #1269

Closed
wants to merge 1 commit into from
Closed

Documentation for ResourceGroup inventory and migration #1269

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
130 changes: 130 additions & 0 deletions site/content/en/reference/live/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,4 +20,134 @@ 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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

@seans3 seans3 Dec 14, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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?

  1. (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.

  2. (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.

  3. (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).

  4. (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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


#### 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
Copy link
Contributor

@frankfarzan frankfarzan Dec 10, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

is a [**ConfigMap**](https://kubernetes.io/docs/concepts/configuration/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)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

objects omitted locally.

#### What is a Next Generation Inventory Object

The next generation inventory object is a **ResourceGroup** custom resource
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

replacing the current [**ConfigMap**](https://kubernetes.io/docs/concepts/configuration/configmap/).
Because the new inventory object is a
custom resource, you must have permissions to add a custom resource
definition (CRD) to the cluster. The individual command to add the
**ResourceGroup** CRD is:

```sh
export RESOURCE_GROUP_INVENTORY=1
Copy link
Contributor

@frankfarzan frankfarzan Dec 10, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

kpt live install-resource-group
```

#### Upgrade Scenario 1: New (Uninitialized) Packages
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


Packages which are newly downloaded and uninitialized should follow the
following steps:

1. `export RESOURCE_GROUP_INVENTORY=1`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

2. `kpt live init <PACKAGE DIR>`

The `init` step adds an `inventory` section in the
package Kptfile. The package is now eligible to be applied
with `kpt live apply <PACKAGE DIR>`. This command will
automatically apply the **ResourceGroup** CRD if has not
already been applied.

#### Upgrade Scenario 2: Existing (Initialized) Packages

Existing packages which have already been initialized, should follow
the following steps:

1. `export RESOURCE_GROUP_INVENTORY=1`
2. `kpt live migrate <PACKAGE DIR>`

Initially, the `migrate` command applies the **ResourceGroup** CRD.
Then the `migrate` command replaces the
[**ConfigMap**](https://kubernetes.io/docs/concepts/configuration/configmap/)
inventory object in the cluster (if it exists) with a **ResourceGroup**
custom resource. The `migrate` command also deletes the local inventory
[**ConfigMap**](https://kubernetes.io/docs/concepts/configuration/configmap/)
config file (usually **inventory-template.yaml**). If this local
[**ConfigMap**](https://kubernetes.io/docs/concepts/configuration/configmap/)
file is stored in a github repository, the removal
needs to be committed to the repository to finalize the removal.
Finally, the `migrate` command adds an `inventory`
section to the Kptfile if it did not already exist. Updates to
the package can now be applied using `kpt live apply <PACKAGE DIR>`.

#### Troubleshooting and Verifying

* Error: unable to apply **ResourceGroup** CRD

```sh
$ kpt live install-resource-group
error: unable to add resourcegroups.kpt.dev
```

This message means the user does not have permissions to add the
**ResourceGroup** CRD to the cluster. Until the user is able to
find someone with sufficient privileges to apply the CRD, the
user can continue to use the previous
[**ConfigMap**](https://kubernetes.io/docs/concepts/configuration/configmap/)
inventory object by unsetting the environment variable:

```sh
unset RESOURCE_GROUP_INVENTORY
```

* Error: configuration already created initialization error

```sh
$ kpt live init <PACKAGE DIR>
error: ResourceGroup configuration has already been created. Changing
them after a package has been applied to the cluster can lead to
undesired results. Use the --force flag to suppress this error.
```

This message means the **ResourceGroup** initialization has
*already* happened. Unless, you want to `--force` new values,
this can safely be ignored.

* How to check if the **ResourceGroup** CRD has *not* been
successfully applied to the cluster

```sh
$ kubectl get resourcegroups.kpt.dev
error: the server doesn't have a resource type "resourcegroups"
```

If a `No resources found` message is returned, the
**ResourceGroup** CRD *has* been successfully applied,
but there are no **ResourceGroup** custom resources
found in the namespace. Example:

```sh
$ kubectl get resourcegroups.kpt.dev
No resources found in default namespace.
```

* How to check if the applied inventory object in the cluster has
been upgraded to a **ResourceGroup** custom resource

```sh
$ kubectl get resourcegroups.kpt.dev -n <PKG NAMESPACE> --selector='cli-utils.sigs.k8s.io/inventory-id' -o name
resourcegroup.kpt.dev/inventory-62308923
```

* How to check if the applied inventory object in the cluster is
not upgraded and is still a **ConfigMap**

```sh
$ kubectl get cm -n <PKG NAMESPACE> --selector='cli-utils.sigs.k8s.io/inventory-id' -o name
configmap/inventory-62308923
```

<!--mdtogo-->
17 changes: 15 additions & 2 deletions site/content/en/reference/live/init/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,12 @@ The init command initializes a package with a template resource which will
be used to track previously applied resources so that they can be pruned
when they are deleted.

The template resource is required by other live commands
Alternatively, if the `RESOURCE_GROUP_INVENTORY` environment variable is set,
the init command will initialize a package using the next generation inventory
object (**ResourceGroup** custom resource). See commands `migrate` and
`install-resource-group` for more information.

The inventory object is required by other live commands
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

such as apply, preview and destroy.

### Examples
Expand All @@ -29,6 +34,12 @@ kpt live init my-dir/
# initialize a package with a specific name for the group of resources
kpt live init --namespace=test my-dir/
```

```sh
# initialize a package with the next generation inventory metadata
export RESOURCE_GROUP_INVENTORY=1
kpt live init my-dir/
```
<!--mdtogo-->

### Synopsis
Expand All @@ -42,7 +53,9 @@ kpt live init DIRECTORY [flags]
```
DIR:
Path to a package directory. The directory must contain exactly
one ConfigMap with the grouping object annotation.
one ConfigMap with the grouping object annotation. If the
RESOURCE_GROUP_INVENTORY environment variable is set, the
package must have a Kptfile.
```

#### Flags
Expand Down
45 changes: 45 additions & 0 deletions site/content/en/reference/live/install-resource-group/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
---
title: "Install-resource-group"
linkTitle: "install-resource-group"
type: docs
description: >
Apply ResourceGroup custom resource definition to the cluster
---
<!--mdtogo:Short
Apply ResourceGroup custom resource definition to the cluster
-->

**NOTE**: This command is not available unless the `RESOURCE_GROUP_INVENTORY`
environment variable is set.

The `install-resource-group` command applies the **ResourceGroup**
custom resource definition (CRD) to the cluster. This CRD allows
**ResourceGroup** custom resources to be created, acting as inventory
objects. The **ResourceGroup** custom resource is the next generation
inventory object after the
[**ConfigMap**](https://kubernetes.io/docs/concepts/configuration/configmap/).

### Examples
<!--mdtogo:Examples-->
```sh
# install the ResourceGroup CRD
export RESOURCE_GROUP_INVENTORY=1
kpt live install-resource-group
```
<!--mdtogo-->

### Synopsis
<!--mdtogo:Long-->
```
kpt live install-resource-group
```

#### Args

None

#### Flags

None

<!--mdtogo-->
88 changes: 88 additions & 0 deletions site/content/en/reference/live/migrate/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,88 @@
---
title: "Migrate"
linkTitle: "migrate"
type: docs
description: >
Migrate the package inventory object to a ResourceGroup custom resource
---
<!--mdtogo:Short
Migrate the package inventory object to a ResourceGroup custom resource
-->

**NOTE**: This command is not available unless the `RESOURCE_GROUP_INVENTORY`
environment variable is set.

The migrate command upgrades the inventory object from a
[**ConfigMap**](https://kubernetes.io/docs/concepts/configuration/configmap/)
to a **ResourceGroup** custom resource. The migrate performs the following steps:

1. Applies the **ResourceGroup** custom resource definition (see
`kpt live install-resource-group`)
2. If a
[**ConfigMap**](https://kubernetes.io/docs/concepts/configuration/configmap/)
inventory object exists in the cluster, the inventory
object is upgraded to a **ResourceGroup** custom resource (deleting the
previous
[**ConfigMap**](https://kubernetes.io/docs/concepts/configuration/configmap/)
).
3. If it has not already been created, the Kptfile inventory section
is filled in. These values are used to create the **ResourceGroup**
custom resource inventory object when the package is applied.
4. Deletes the local
[**ConfigMap**](https://kubernetes.io/docs/concepts/configuration/configmap/)
file (usually **inventory-template.yaml**).

### Examples
<!--mdtogo:Examples-->
```sh
# migrate from ConfigMap to ResourceGroup inventory object
export RESOURCE_GROUP_INVENTORY=1
kpt live migrate my-dir/
```

```sh
# check the steps that will occur for the migrate, but
# do not actually run them.
export RESOURCE_GROUP_INVENTORY=1
kpt live migrate my-dir/ --dry-run
```

```sh
# migrate from ConfigMap to ResourceGroup inventory object, forcing
# new values for the inventory object to be written to the Kptfile.
export RESOURCE_GROUP_INVENTORY=1
kpt live migrate my-dir/ --force
```
<!--mdtogo-->

### Synopsis
<!--mdtogo:Long-->
```
kpt live migrate DIRECTORY [flags]
```

#### Args

```
DIR:
Path to a package directory. The package must contain a Kptfile.
If the package directory contains a ConfigMap inventory template
file (usually named inventory-template.yaml), then this file
will be deleted.
```

#### Flags

```
--dry-run:
Do not actually run the migrate; only print out the steps that
will occur.
--force:
Set inventory values even if already set in Kptfile.
--name:
Set the inventory object name, instead of default generated
name (e.g. inventory-62308923). The user must make sure the
inventory name does not collide with other inventory objects
in the same namespace.
```
<!--mdtogo-->