Inventory Object Upgrade (alpha)
How to Upgrade to the Next Generation Inventory Object (Alpha)
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
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)
objects omitted locally.
What is a Next Generation Inventory Object
The next generation inventory object is a ResourceGroup custom resource replacing the current ConfigMap. Because the new inventory object is a custom resource, you must have permissions to add a custom resource definition (CRD) to the cluster.
Upgrade Scenario 1: New (Uninitialized) Packages
Packages which are newly downloaded and uninitialized should follow the following steps:
export RESOURCE_GROUP_INVENTORY=1kpt 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 it has not
already been applied.
Upgrade Scenario 2: Existing (Initialized) Packages
Existing packages which have already been initialized, should follow the following steps:
export RESOURCE_GROUP_INVENTORY=1kpt live migrate <PACKAGE DIR>
Initially, the migrate command applies the ResourceGroup CRD.
Then the migrate command replaces the
ConfigMap
inventory object in the cluster (if it exists) with a ResourceGroup
custom resource. The migrate command also deletes the local inventory
ConfigMap
config file (usually inventory-template.yaml). If this local
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>.
New (Alpha) Commands
Migrate
Install Resource Group
kpt live install-resource-group The ResourceGroup
CRD is added to the cluster as a side effect of kpt live apply. However, this
install-resource-group command allows the user to only apply the
ResourceGroup CRD without applying other resources.
Updated Existing Commands
Init
Troubleshooting and Verifying
- Error: unable to apply ResourceGroup CRD
$ kpt live apply <PACKAGE_DIR>
error: unable to add resourcegroups.kpt.dev
This message means the user does not have permissions to add the ResourceGroup CRD to the cluster. Once the RBAC permissions have been updated, the user can manually install the CRD with the following command:
$ kpt live install-resource-group
installing ResourceGroup custom resource definition...success
The user can verify the CRD was successfully added with the following command (using default namespace):
$ kubectl get resourcegroups.kpt.dev
No resources found in default namespace.
Until the user is able to update permissions to apply the CRD, the user can continue to use the previous ConfigMap inventory object by unsetting the environment variable:
unset RESOURCE_GROUP_INVENTORY
- Error: configuration already created initialization error
$ 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
$ 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:
$ 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
$ 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
$ kubectl get cm -n <PKG NAMESPACE> --selector='cli-utils.sigs.k8s.io/inventory-id' -o name
configmap/inventory-62308923