updated readme

devtron-labs · Aug 24, 2021 · 89a7248 · 89a7248
1 parent 038bc6b
commit 89a7248
Show file tree

Hide file tree

Showing 8 changed files with 101 additions and 30 deletions.
diff --git a/README.md b/README.md
@@ -1,21 +1,103 @@
 # Kubedd
 
-As kubernetes has come of its age, it has started deprecating and removing older kubernetes objects apiVersions.
+## Motivation
 
-`kubedd` is a tool to help specifically with the migration of kubernetes version, it detects
-1. Identify and provide recommendations for apiVersions which have been removed or deprecated
-2. Validates schema against current kubernetes version as well as target kubernetes version
-3. Warns in case it is not possible to migrate from current version to target kubernetes version
+https://github.com/kubernetes/kubernetes/issues/58131#issuecomment-403829566
 
-It does so using Kubernetes OpenAPI specification, and can validate schemas for multiple versions of Kubernetes.
+Currently there is no easy way to upgrade kubernetes objects in case of kubernetes upgrade. There are some tools
+which are available for this purpose, but we found then inadequate for migration requirements.
 
+`kubedd` is a tool to check issues in migration of kubernetes yaml objects from one kubernetes version to another. 
 
+It uses openapi spec provided by the kubernetes with releases, for eg. in case of target kubernetes version 1.22 openapi spec for [1.22](https://raw.githubusercontent.com/kubernetes/kubernetes/release-1.22/api/openapi-spec/swagger.json),
+ to validate the kubernetes objects for depreciation or non-conformity with openapi spec.
+
+Supported input formats
+1. Directory containing files to be validated
+2. Read kubernetes objects directly from cluster.Uses `kubectl.kubernetes.io/last-applied-configuration` to get
+   last applied configuration and in its absence uses the manifest itself. 
+
+It provides details of issues with the kubernetes object in case they are migrated to cluster with newer kubernetes
+version.
+
+## Install
+
+Download kubedd, and it is ready for use.
+
+## Usage
+
+```
+./kubedd 
+
+Results for cluster at version 1.12 to 1.22
+-------------------------------------------
+>>>> Removed API Version's <<<<
+ Namespace   Name                          Kind         API Version (Current Available)   Replace With API Version (Latest Available)   Migration Status                               
+ prod        demmoo-prod-ingress           Ingress      extensions/v1beta1                                                              Alert! cannot migrate kubernetes version  
+ prod        devtron-static-prod-ingress   Ingress      extensions/v1beta1                                                              Alert! cannot migrate kubernetes version  
+ prod        ghost-blog-dt-prod            Ingress      extensions/v1beta1                                                              Alert! cannot migrate kubernetes version  
+ prod        ghost-blog-dt-prod-auth       Ingress      extensions/v1beta1                                                              Alert! cannot migrate kubernetes version  
+ prod        ghost-devtron-blog-prod       Ingress      extensions/v1beta1                                                              Alert! cannot migrate kubernetes version  
+ prod        oauth2-proxy                  Ingress      extensions/v1beta1                                                              Alert! cannot migrate kubernetes version  
+ prod        telemetry-prod-ingress        Ingress      extensions/v1beta1                                                              Alert! cannot migrate kubernetes version  
+ prod        ghost-blog-dt-prod            Deployment   extensions/v1beta1                apps/v1                                       can be migrated with just apiVersion change    
+ prod        ghost-devtron-blog-prod       Deployment   extensions/v1beta1                apps/v1                                       can be migrated with just apiVersion change  
+```
+
+
+## Arguments
 
 ```
-$ ./bin/kubedd --target-kubernetes-version 1.22  
+./kubedd --help
+Validates migration of Kubernestes YAML file against specific kubernetes version, It provides details of issues with the kubernetes object in case they are migrated to cluster with newer kubernetes version
+
+Usage:
+  kubedd <file> [file...] [flags]
+
+Flags:
+  -d, --directories strings                   A comma-separated list of directories to recursively search for YAML documents
+      --force-color                           Force colored output even if stdout is not a TTY
+  -h, --help                                  help for kubedd
+      --ignore-keys-for-deprecation strings   A comma-separated list of keys to be ignored for depreciation check (default [metadata*,status*])
+      --ignore-keys-for-validation strings    A comma-separated list of keys to be ignored for validation check (default [status*,metadata*])
+      --ignore-kinds strings                  A comma-separated list of kinds to be skipped (default [event,CustomResourceDefinition])
+      --ignore-namespaces strings             A comma-separated list of namespaces to be skipped (default [kube-system])
+      --ignore-null-errors                    Ignore null value errors (default true)
+      --ignored-filename-patterns strings     An alias for ignored-path-patterns
+  -i, --ignored-path-patterns strings         A comma-separated list of regular expressions specifying paths to ignore
+      --insecure-skip-tls-verify              If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
+      --kubeconfig string                     Path of kubeconfig file of cluster to be scanned
+      --kubecontext string                    Kubecontext to be selected
+      --select-kinds strings                  A comma-separated list of kinds to be selected, if left empty all kinds are selected
+      --select-namespaces strings             A comma-separated list of namespaces to be selected, if left empty all namespaces are selected
+      --source-kubernetes-version string      Version of Kubernetes of the cluster on which kubernetes objects are deployed currently, ignored in case cluster is provided. In case of directory defaults to same as target-kubernetes-version.
+      --source-schema-location string         SourceSchemaLocation is the file path of kubernetes versions of the cluster on which manifests are deployed. Use this in air-gapped environment where it internet access is unavailable.
+      --target-kubernetes-version string      Version of Kubernetes to migrate to eg 1.22, 1.21, 1.12 (default "1.22")
+      --target-schema-location string         TargetSchemaLocation is the file path of kubernetes version of the target cluster for these manifests. Use this in air-gapped environment where it internet access is unavailable.
+      --version                               version for kubedd
 
 
 ```
 
+## Output
+
+It categorises kubernetes objects based on change in ApiVersion. Categories are
+1. Removed ApiVersion
+2. Deprecated ApiVersion
+3. Newer ApiVersion
+4. Unchanged ApiVersion
+
+Within each category it identifies migration path to newer ApiVersion, possible paths are
+1. It cannot be migrated as there are no common ApiVersions between source and target kubernetes version
+2. It can be migrated but has some issues which needs to be resolved
+3. It can be migrated with just ApiVersion change
+
+This activity is performed for both current and new ApiVersion.
+
+## Other Similar Tools
+
+1. [kubeval](https://github.com/instrumenta/kubeval) - most popular, only validates against the given kubernetes version, doesn't provide migration path
+2. [kube-no-trouble](https://github.com/doitintl/kube-no-trouble) - provides information about removed and deprecated api but doesnt validate schema
+3. [kubepug](https://github.com/rikatz/kubepug) - provides information based on deprecation comments in the schema, doesn't provide information
+
 
-For full usage and installation instructions see [devtron.ai](https://docs.devtron.ai/).
diff --git a/kubedd/kubedd_test.go b/kubedd/kubedd_test.go
@@ -7,7 +7,7 @@ import (
 )
 
 func TestValidateCluster(t *testing.T) {
-	cluster := pkg.NewCluster("/Users/pghildiy/Documents/devtronCode/kube-configs/prod-devtron", "")
+	cluster := pkg.NewCluster("", "")
 	config := pkg.NewDefaultConfig()
 	config.SelectKinds = []string{"ComponentStatus"}
 	config.TargetKubernetesVersion = "1.21"

diff --git a/main.go b/main.go
@@ -13,6 +13,8 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  *
+ * Certain portions in this file have been taken from kubeval and where ever
+ * they are, IP and licenses of kubeval are applicable.
  */
 
 package main
@@ -78,8 +80,8 @@ apps/v1 deployment - check
 
 // RootCmd represents the the command to run when kubedd is run
 var RootCmd = &cobra.Command{
-	Short:   "ValidateJson a Kubernetes YAML file against the relevant apiVersion and kind",
-	Long:    `ValidateJson a Kubernetes YAML file against the relevant apiVersion and kind, in case the apiVersion for the kind is deprecated or removed then it validates against the latest available apiVersion`,
+	Short:   "Validates migration of Kubernetes YAML file against specific kubernetes version",
+	Long:    `Validates migration of Kubernetes YAML file against specific kubernetes version, It provides details of issues with the kubernetes object in case they are migrated to cluster with newer kubernetes version`,
 	Version: fmt.Sprintf("Version: %s\nCommit: %s\nDate: %s\n", version, commit, date),
 	Run: func(cmd *cobra.Command, args []string) {
 		if config.IgnoreMissingSchemas && !config.Quiet {

diff --git a/pkg/Config.go b/pkg/Config.go
@@ -13,6 +13,8 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  *
+ * Certain portions in this file have been taken from kubeval and where ever
+ * they are, IP and licenses of kubeval are applicable.
  */
 
 package pkg

diff --git a/pkg/Output.go b/pkg/Output.go
@@ -13,6 +13,8 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  *
+ * Certain portions in this file have been taken from kubeval and where ever
+ * they are, IP and licenses of kubeval are applicable.
  */
 
 package pkg

diff --git a/pkg/Types.go b/pkg/Types.go
@@ -13,6 +13,8 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  *
+ * Certain portions in this file have been taken from kin-openapi and where ever
+ * they are, IP and licenses of kin-openapi are applicable.
  */
 
 package pkg

diff --git a/pkg/Validator.go b/pkg/Validator.go
@@ -136,23 +136,6 @@ func (ks *kubeSpec) applySchema(object map[string]interface{}, token string) (op
 		validationError = append(validationError, err)
 		return validationError, deprecated
 	}
-	//var scm *openapi3.Schema
-	//var err error
-	//for ; ; {
-	//	ok := false
-	//	if strings.Index(token, "/") > 0 {
-	//		parts := strings.Split(token, "/")
-	//		token = parts[len(parts) - 1]
-	//	}
-	//	dp, err := ks.Components.Schemas.JSONLookup(token)
-	//
-	//	if scm, ok = dp.(*openapi3.Schema); ok {
-	//		break
-	//	}
-	//	if ref, ok := dp.(*openapi3.Ref); ok {
-	//		token = ref.Ref
-	//	}
-	//}
 
 	opts := []openapi3.SchemaValidationOption{openapi3.MultiErrors()}
 	depError := VisitJSON(scm, object, SchemaSettings{MultiError: true})

diff --git a/pkg/Visitor.go b/pkg/Visitor.go
@@ -94,8 +94,6 @@ func visitJSONObject(schema *openapi3.Schema, object map[string]interface{}, set
 					return me
 				}
 			}
-		} else {
-			//fmt.Printf("not found key %s\n", k)
 		}
 	}
 	return me