From ea0338638442f7a7250621610ad6cc7c7fb54265 Mon Sep 17 00:00:00 2001 From: Yuwen Ma Date: Wed, 17 Nov 2021 15:04:58 -0800 Subject: [PATCH] resolve comments --- ... => 01-live_Inventory-to-ResourceGroup.md} | 89 ++++++++++++++----- 1 file changed, 68 insertions(+), 21 deletions(-) rename docs/design-docs/{01-kpt-live-stdin.md => 01-live_Inventory-to-ResourceGroup.md} (71%) diff --git a/docs/design-docs/01-kpt-live-stdin.md b/docs/design-docs/01-live_Inventory-to-ResourceGroup.md similarity index 71% rename from docs/design-docs/01-kpt-live-stdin.md rename to docs/design-docs/01-live_Inventory-to-ResourceGroup.md index 6c77b46a37..7dfd2cf06c 100644 --- a/docs/design-docs/01-kpt-live-stdin.md +++ b/docs/design-docs/01-live_Inventory-to-ResourceGroup.md @@ -28,19 +28,25 @@ to use ResourceGroup only. ### Read standard input resources -We will add a reserved keyword “-” as a special kpt directory. This "-" accepts resources -from the standard input. For example, `kustomize build | kpt live apply -` +We will change the existing `kpt live apply` from STDIN to not require the existence of Kptfile ( +to be more specific, the `inventory` file from Kptfile). As long as the STDIN contains +one and only one valid ResourceGroup, `kpt live apply` should be able to create/match the +ResourceGroup in cluster. ### Initialize a `ResourceGroup` object -`kpt live init` will create a ResourceGroup CR in resourcegroup.yaml. Only three fields -should be given to the CR. +`kpt live init` will create a ResourceGroup CR in resourcegroup.yaml. + +By default, the ResoureGroup will have name and namespace assigned as below. And users can +override via existing flags "--name" and "--namespace". - metadata.name: A client-provided valid RFC 1123 DNS subdomain name. Default value has prefix “inventory-” with - 8 digit numbers. E.g. “inventory-02014045” -- metadata.namespace: a valid namespace. default to value “default” -- metadata.labels.cli-utils.sigs.k8s.io/inventory-id: A client-provided valid label. - Default value is a UUID e.g. 7c5af957-a3e2-4d68-8c0f-6c1864a66050 + 8 digit numbers. E.g. "inventory-02014045" +- metadata.namespace: a valid namespace. default to value "default" + +If users want to reuse an existing inventory (from Kptfile) or ResourceGroup (which has been deployed to the cluster), +they shall provide the value of the inventory's inventory-id or the ResourceGroup's "metadata.labels[0].cli-utils.sigs.k8s.io/inventory-id" +via "--inventory-id" flag. ### Convert Inventory to ResourceGroup @@ -50,12 +56,12 @@ the ResourceGroup is unique. This requires Kptfile to exist to use `kpt live app To split the Inventory from Kptfile to resourcegroup.yaml and convert the Inventory to ResourceGroup, `kpt live migrate` should be extended to map the inventory.name, -inventory.namespace, inventory.inventoryID to ResourceGroup CR metadata.name, +inventory.namespace, inventory.inventoryID to ResourceGroup CR metadata.name, metadata.namespace, metadata.labels.cli-utils.sigs.k8s.io/inventory-id correspondingly. Inventory in Kptfile ```yaml -apiVersion: kpt.dev/v1betaX +apiVersion: kpt.dev/v1 kind: Kptfile inventory: name: @@ -73,9 +79,20 @@ metadata cli-utils.sigs.k8s.io/inventory-id: ``` +### Simplify the Inventory + +Current inventory contains inventory-id which is required to match the label `cli-utils.sigs.k8s.io/inventory-id`. + +For new users, they should no longer need to be exposed to the inventory-id, but kpt will +build one composed by `name-namespace` on the fly. + +For existing users, the inventory-id is still +required in the standalone ResourceGroup file to guarantee the adoption matches, unless they use "--inventory-policy=adopt" +to override the label. This flag is only required as a one-off via `kpt live apply -` to override the label to `name-namespace`. + ### ResourceGroup as a singleton object -`kpt live apply [--resourcegroup-path] -` from STDIN accepts and only accepts a single +`kpt live apply [--resourcegroup-file] -` from STDIN accepts and only accepts a single ResourceGroup, including the ResourceGroup provided by the flag. It detects 1. If more than one ResourceGroup is found, raise errors and display all the ResourceGroup objects. 2. If no ResourceGroup is found in STDIN and and Kptfile inventory does not exists, raise errors and suggest users to @@ -83,23 +100,53 @@ ResourceGroup, including the ResourceGroup provided by the flag. It detects 3. If no ResourceGroup is found in STDIN and Kptfile inventory exists, raise errors and suggest users to run kpt live migrate +### New flags + +#### `--resourcegroup-file` + +- description: The file path to the ResourceGroup CR, default to `resourcegroup.yaml` +- short form `--rg` +- This flag will be added to `kpt live init`, `kpt live migrate` and `kpt live apply` + +#### `--name` for inventory + +- description: The name for the ResourceGroup +- This flag will continue to be used by `kpt live init`. Rather than overriding the + inventory.name in Kptfile, it will override the default metadata.name in the standalone ResourceGroup file. + +#### `--namespace` for inventory + +- description: The namespace for the ResourceGroup +- This flag will continue to be used by `kpt live init`, Rather than overriding the + inventory.namespace in Kptfile, it will override the default metadata.namespace in the standalone ResourceGroup file. + +#### `--inventory-id` for inventory + +- description: Inventory identifier. This is used to detect overlap between + two sets of ResourceGroup managed resources that might use the same name and namespace. +- This flag will continue to be accepted by `kpt live init` for backward compatibility reasons. + If given, ResourceGroup will store the inventory-id value in "metadata.labels[0].cli-utils.sigs.k8s.io/inventory-id" + of the ResourceGroup. + If not given, the ResourceGroup labels will be empty and the value of "-" will be + used as the "cli-utils.sigs.k8s.io/inventory-id" label in `kpt live apply` from STD. + ## User Guide ### To hydrate via kustomize and deploy via kpt #### Day 1 -For new users to start from scratch (no Kptfile) -User can run `kpt live init [--resourcegroup-file=CUSTOM_RG.yaml]` to create a +##### For new users to start from scratch (no Kptfile) +User can run `kpt live init [--resourcegroup-file=resourcegroup.yaml]` to create a ResourceGroup object and store it in a resourcegroup.yaml file. Users can customize the file path with the flag “--resourcegroup-file”. -For existing kpt users to migrate from Kptfile -Users run `kpt live migrate [--resourcegroup-file=CUSTOM_RG.yaml]` to convert the +##### For existing kpt users to migrate from Kptfile +Users run `kpt live migrate [--resourcegroup-file=resourcegroup.yaml]` to convert the Inventory object from Kptfile to a standalone resourcegroup.yaml file. Users can customize the file path with the flag “--resourcegroup-file”. -[optional]: Add shareable ResourceGroup to kustomize resources +##### [optional]: Add shareable ResourceGroup to kustomize resources If the ResourceGroup is expected to be shared in the Gitops workflow, users can add the resourcegroup.yaml file path to the .resources field in kustomization.yaml. This simplifies the Day N deployment by omitting the “–resourcegroup-file“ flag. @@ -110,17 +157,17 @@ This simplifies the Day N deployment by omitting the “–resourcegroup-file“ - Users can run `kustomize build | kpt live apply -` to hydrate and deploy the kustomize-managed configurations. If resourcegroup.yaml is not added to kustomize .resources field, users should provide the “–resourcegroup-file“ flag. - `kustomize build | kpt live apply –resourcegroup-file -` + `kustomize build | kpt live apply –resourcegroup-file -` ### To hydrate via helm and deploy via kpt #### Day 1 -For new users to start from scratch (no Kptfile) +##### For new users to start from scratch (no Kptfile) User can run `kpt live init --resourcegroup-file=/resourcegroup.yaml` to create a ResourceGroup object and store it in the helm template . -For existing kpt users to migrate from Kptfile +##### For existing kpt users to migrate from Kptfile Users run `kpt live migrate --resourcegroup-file=/resourcegroup.yaml` to convert the Inventory object from Kptfile to a standalone resourcegroup.yaml file. @@ -180,7 +227,7 @@ the ResourceGroup unintentionally (e.g. via kubectl apply). inventory.yaml ```yaml -apiVersion: kpt.dev/v1betaX +apiVersion: kpt.dev/v1 kind: Inventory metadata: name: @@ -205,7 +252,7 @@ inventoryID: inventory.yaml ```yaml -apiVersion: kpt.dev/v1betaX +apiVersion: kpt.dev/v1 kind: Inventory spec: resourceGroup: