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.

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 as inventory object (alpha) #1357

Merged
merged 1 commit into from
Jan 20, 2021
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
2 changes: 2 additions & 0 deletions site/content/en/reference/live/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,4 +20,6 @@ description: >

Live contains the next-generation versions of apply related commands for
deploying local configuration packages to a cluster.

Inventory object upgrade [instructions (alpha)](./alpha).
<!--mdtogo-->
169 changes: 169 additions & 0 deletions site/content/en/reference/live/alpha.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,169 @@
---
title: "Inventory Object Upgrade (alpha)"
linkTitle: "inventory object upgrade (alpha)"
weight: 3
type: docs
description: >
Instructions (alpha) to upgrade to next generation inventory object
---
<!--mdtogo:Short
Instructions (alpha) to upgrade to next generation inventory object
-->

### 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**](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)
objects omitted locally.

#### What is a Next Generation Inventory Object

The next generation inventory object is a **ResourceGroup** custom resource
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.

#### Upgrade Scenario 1: New (Uninitialized) Packages

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

1. `export RESOURCE_GROUP_INVENTORY=1`
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 it 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>`.

### New (Alpha) Commands

#### Migrate

[kpt live migrate](./migrate)

#### Install Resource Group

[kpt live install-resource-group](./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

[kpt live init](./init)

### Troubleshooting and Verifying
Copy link
Contributor

Choose a reason for hiding this comment

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

Is there an error case when running kpt live apply that tells the user to fall back to manual install of CRD? (Related to comment above)

Copy link
Contributor Author

Choose a reason for hiding this comment

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

OK, I used the kpt live apply instead of kpt live install-resource-group to illustrate the error. I added the command to manually install the CRD as the way to fix and verify the error. Please let me know what you think.


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

```sh
$ 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:

```sh
$ 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):

```sh
$ 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**](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
```
64 changes: 64 additions & 0 deletions site/content/en/reference/live/init.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
---
title: "Init (alpha)"
linkTitle: "init (alpha)"
type: docs
description: >
Initialize a package with a object to track previously applied resources
---
<!--mdtogo:Short
Initialize a package with a object to track previously applied resources
-->

{{< asciinema key="live-init" rows="10" preload="1" >}}

**NOTE**: This alpha version of the command is for the new ResourceGroup as
inventory object functionality. The alpha version of this command is not
available unless 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`](./migrate) and
[`install-resource-group`](./install-resource-group) for more information. A Kptfile
is required in the package directory.

The inventory object is required by other live commands
such as apply, preview and destroy.

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

```sh
# initialize a package with a specific name for the group of resources
export RESOURCE_GROUP_INVENTORY=1
kpt live init --namespace=test-namespace my-dir/
```
<!--mdtogo-->

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

#### Args

```
DIR:
Path to a package directory. The package directory must contain a Kptfile.
```

#### Flags

```
--inventory-id:
Identifier for group of applied resources. Must be composed of valid label characters.
--namespace:
namespace for the inventory object. If not provided, kpt will check if all the resources
in the package belong in the same namespace. If they are, that namespace will be used. If
they are not, the namespace in the user's context will be chosen.
```
<!--mdtogo-->
46 changes: 46 additions & 0 deletions site/content/en/reference/live/install-resource-group.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
---
title: "Install-resource-group (alpha)"
linkTitle: "install-resource-group (alpha)"
type: docs
description: >
Apply ResourceGroup custom resource definition to the cluster
---
<!--mdtogo:Short
Apply ResourceGroup custom resource definition to the cluster
-->

**NOTE**: This is an alpha command for the new ResourceGroup as inventory object
functionality. This alpha 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-->
89 changes: 89 additions & 0 deletions site/content/en/reference/live/migrate.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
---
title: "Migrate (alpha)"
linkTitle: "migrate (alpha)"
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 is an alpha command for the new ResourceGroup as inventory object
functionality. This alpha 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
Copy link
Contributor

Choose a reason for hiding this comment

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

Thanks for the detailed docs and examples. They're clear and helpful.

<!--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-->