feat: get official field doc

cmd/analyze/analyze.go

@@ -32,6 +32,7 @@ var (
 	namespace      string
 	anonymize      bool
 	maxConcurrency int
+	withDoc        bool
 )
 
 // AnalyzeCmd represents the problems command
@@ -45,7 +46,7 @@ var AnalyzeCmd = &cobra.Command{
 
 		// AnalysisResult configuration
 		config, err := analysis.NewAnalysis(backend,
-			language, filters, namespace, nocache, explain, maxConcurrency)
+			language, filters, namespace, nocache, explain, maxConcurrency, withDoc)
 		if err != nil {
 			color.Red("Error: %v", err)
 			os.Exit(1)
@@ -91,4 +92,6 @@ func init() {
 	AnalyzeCmd.Flags().StringVarP(&language, "language", "l", "english", "Languages to use for AI (e.g. 'English', 'Spanish', 'French', 'German', 'Italian', 'Portuguese', 'Dutch', 'Russian', 'Chinese', 'Japanese', 'Korean')")
 	// add max concurrency
 	AnalyzeCmd.Flags().IntVarP(&maxConcurrency, "max-concurrency", "m", 10, "Maximum number of concurrent requests to the Kubernetes API server")
+	// kubernetes doc flag
+	AnalyzeCmd.Flags().BoolVarP(&withDoc, "with-doc", "d", false, "Give me the official documentation of the involved field")
 }

go.mod

@@ -75,7 +75,7 @@ require (
 	github.com/gogo/protobuf v1.3.2 // indirect
 	github.com/golang/protobuf v1.5.3 // indirect
 	github.com/google/btree v1.1.2 // indirect
-	github.com/google/gnostic v0.6.9 // indirect
+	github.com/google/gnostic v0.6.9
 	github.com/google/go-cmp v0.5.9 // indirect
 	github.com/google/go-containerregistry v0.14.0 // indirect
 	github.com/google/gofuzz v1.2.0 // indirect

pkg/analysis/analysis.go

@@ -23,6 +23,7 @@ import (
 	"sync"
 
 	"github.com/fatih/color"
+	openapi_v2 "github.com/google/gnostic/openapiv2"
 	"github.com/k8sgpt-ai/k8sgpt/pkg/ai"
 	"github.com/k8sgpt-ai/k8sgpt/pkg/analyzer"
 	"github.com/k8sgpt-ai/k8sgpt/pkg/cache"
@@ -45,6 +46,7 @@ type Analysis struct {
 	Explain            bool
 	MaxConcurrency     int
 	AnalysisAIProvider string // The name of the AI Provider used for this analysis
+	WithDoc            bool
 }
 
 type AnalysisStatus string
@@ -63,7 +65,7 @@ type JsonOutput struct {
 	Results  []common.Result `json:"results"`
 }
 
-func NewAnalysis(backend string, language string, filters []string, namespace string, noCache bool, explain bool, maxConcurrency int) (*Analysis, error) {
+func NewAnalysis(backend string, language string, filters []string, namespace string, noCache bool, explain bool, maxConcurrency int, withDoc bool) (*Analysis, error) {
 	var configAI ai.AIConfiguration
 	err := viper.UnmarshalKey("ai", &configAI)
 	if err != nil {
@@ -128,6 +130,7 @@ func NewAnalysis(backend string, language string, filters []string, namespace st
 		Explain:            explain,
 		MaxConcurrency:     maxConcurrency,
 		AnalysisAIProvider: backend,
+		WithDoc:            withDoc,
 	}, nil
 }
 
@@ -136,11 +139,23 @@ func (a *Analysis) RunAnalysis() {
 
 	coreAnalyzerMap, analyzerMap := analyzer.GetAnalyzerMap()
 
+	// we get the openapi schema from the server only if required by the flag "with-doc"
+	openapiSchema := &openapi_v2.Document{}
+	if a.WithDoc {
+		var openApiErr error
+
+		openapiSchema, openApiErr = a.Client.Client.Discovery().OpenAPISchema()
+		if openApiErr != nil {
+			a.Errors = append(a.Errors, fmt.Sprintf("[KubernetesDoc] %s", openApiErr))
+		}
+	}
+
 	analyzerConfig := common.Analyzer{
-		Client:    a.Client,
-		Context:   a.Context,
-		Namespace: a.Namespace,
-		AIClient:  a.AIClient,
+		Client:        a.Client,
+		Context:       a.Context,
+		Namespace:     a.Namespace,
+		AIClient:      a.AIClient,
+		OpenapiSchema: openapiSchema,
 	}
 
 	semaphore := make(chan struct{}, a.MaxConcurrency)

pkg/analysis/output.go

@@ -78,6 +78,9 @@ func (a *Analysis) textOutput() ([]byte, error) {
 			color.YellowString(result.Name), color.CyanString(result.ParentObject)))
 		for _, err := range result.Error {
 			output.WriteString(fmt.Sprintf("- %s %s\n", color.RedString("Error:"), color.RedString(err.Text)))
+			if err.KubernetesDoc != "" {
+				output.WriteString(fmt.Sprintf("  %s %s\n", color.RedString("Kubernetes Doc:"), color.RedString(err.KubernetesDoc)))
+			}
 		}
 		output.WriteString(color.GreenString(result.Details + "\n"))
 	}

pkg/analyzer/cronjob.go

@@ -18,16 +18,26 @@ import (
 	"time"
 
 	"github.com/k8sgpt-ai/k8sgpt/pkg/common"
+	"github.com/k8sgpt-ai/k8sgpt/pkg/kubernetes"
 	"github.com/k8sgpt-ai/k8sgpt/pkg/util"
 	cron "github.com/robfig/cron/v3"
 	v1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/apimachinery/pkg/runtime/schema"
 )
 
 type CronJobAnalyzer struct{}
 
 func (analyzer CronJobAnalyzer) Analyze(a common.Analyzer) ([]common.Result, error) {
 
 	kind := "CronJob"
+	apiDoc := kubernetes.K8sApiReference{
+		Kind: kind,
+		ApiVersion: schema.GroupVersion{
+			Group:   "batch",
+			Version: "v1",
+		},
+		OpenapiSchema: a.OpenapiSchema,
+	}
 
 	AnalyzerErrorsMetric.DeletePartialMatch(map[string]string{
 		"analyzer_name": kind,
@@ -43,8 +53,11 @@ func (analyzer CronJobAnalyzer) Analyze(a common.Analyzer) ([]common.Result, err
 	for _, cronJob := range cronJobList.Items {
 		var failures []common.Failure
 		if cronJob.Spec.Suspend != nil && *cronJob.Spec.Suspend {
+			doc := apiDoc.GetApiDocV2("spec.suspend")
+
 			failures = append(failures, common.Failure{
-				Text: fmt.Sprintf("CronJob %s is suspended", cronJob.Name),
+				Text:          fmt.Sprintf("CronJob %s is suspended", cronJob.Name),
+				KubernetesDoc: doc,
 				Sensitive: []common.Sensitive{
 					{
 						Unmasked: cronJob.Namespace,
@@ -59,8 +72,11 @@ func (analyzer CronJobAnalyzer) Analyze(a common.Analyzer) ([]common.Result, err
 		} else {
 			// check the schedule format
 			if _, err := CheckCronScheduleIsValid(cronJob.Spec.Schedule); err != nil {
+				doc := apiDoc.GetApiDocV2("spec.schedule")
+
 				failures = append(failures, common.Failure{
-					Text: fmt.Sprintf("CronJob %s has an invalid schedule: %s", cronJob.Name, err.Error()),
+					Text:          fmt.Sprintf("CronJob %s has an invalid schedule: %s", cronJob.Name, err.Error()),
+					KubernetesDoc: doc,
 					Sensitive: []common.Sensitive{
 						{
 							Unmasked: cronJob.Namespace,
@@ -78,9 +94,11 @@ func (analyzer CronJobAnalyzer) Analyze(a common.Analyzer) ([]common.Result, err
 			if cronJob.Spec.StartingDeadlineSeconds != nil {
 				deadline := time.Duration(*cronJob.Spec.StartingDeadlineSeconds) * time.Second
 				if deadline < 0 {
+					doc := apiDoc.GetApiDocV2("spec.startingDeadlineSeconds")
 
 					failures = append(failures, common.Failure{
-						Text: fmt.Sprintf("CronJob %s has a negative starting deadline", cronJob.Name),
+						Text:          fmt.Sprintf("CronJob %s has a negative starting deadline", cronJob.Name),
+						KubernetesDoc: doc,
 						Sensitive: []common.Sensitive{
 							{
 								Unmasked: cronJob.Namespace,

pkg/analyzer/deployment.go

@@ -18,8 +18,10 @@ import (
 	"fmt"
 
 	v1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/apimachinery/pkg/runtime/schema"
 
 	"github.com/k8sgpt-ai/k8sgpt/pkg/common"
+	"github.com/k8sgpt-ai/k8sgpt/pkg/kubernetes"
 	"github.com/k8sgpt-ai/k8sgpt/pkg/util"
 )
 
@@ -31,6 +33,14 @@ type DeploymentAnalyzer struct {
 func (d DeploymentAnalyzer) Analyze(a common.Analyzer) ([]common.Result, error) {
 
 	kind := "Deployment"
+	apiDoc := kubernetes.K8sApiReference{
+		Kind: kind,
+		ApiVersion: schema.GroupVersion{
+			Group:   "apps",
+			Version: "v1",
+		},
+		OpenapiSchema: a.OpenapiSchema,
+	}
 
 	AnalyzerErrorsMetric.DeletePartialMatch(map[string]string{
 		"analyzer_name": kind,
@@ -45,8 +55,11 @@ func (d DeploymentAnalyzer) Analyze(a common.Analyzer) ([]common.Result, error)
 	for _, deployment := range deployments.Items {
 		var failures []common.Failure
 		if *deployment.Spec.Replicas != deployment.Status.Replicas {
+			doc := apiDoc.GetApiDocV2("spec.replicas")
+
 			failures = append(failures, common.Failure{
-				Text: fmt.Sprintf("Deployment %s/%s has %d replicas but %d are available", deployment.Namespace, deployment.Name, *deployment.Spec.Replicas, deployment.Status.Replicas),
+				Text:          fmt.Sprintf("Deployment %s/%s has %d replicas but %d are available", deployment.Namespace, deployment.Name, *deployment.Spec.Replicas, deployment.Status.Replicas),
+				KubernetesDoc: doc,
 				Sensitive: []common.Sensitive{
 					{
 						Unmasked: deployment.Namespace,

pkg/analyzer/hpa.go

@@ -17,17 +17,27 @@ import (
 	"fmt"
 
 	"github.com/k8sgpt-ai/k8sgpt/pkg/common"
+	"github.com/k8sgpt-ai/k8sgpt/pkg/kubernetes"
 	"github.com/k8sgpt-ai/k8sgpt/pkg/util"
 	appsv1 "k8s.io/api/apps/v1"
 	corev1 "k8s.io/api/core/v1"
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/apimachinery/pkg/runtime/schema"
 )
 
 type HpaAnalyzer struct{}
 
 func (HpaAnalyzer) Analyze(a common.Analyzer) ([]common.Result, error) {
 
 	kind := "HorizontalPodAutoscaler"
+	apiDoc := kubernetes.K8sApiReference{
+		Kind: kind,
+		ApiVersion: schema.GroupVersion{
+			Group:   "autoscaling",
+			Version: "v1",
+		},
+		OpenapiSchema: a.OpenapiSchema,
+	}
 
 	AnalyzerErrorsMetric.DeletePartialMatch(map[string]string{
 		"analyzer_name": kind,
@@ -76,8 +86,11 @@ func (HpaAnalyzer) Analyze(a common.Analyzer) ([]common.Result, error) {
 		}
 
 		if podInfo == nil {
+			doc := apiDoc.GetApiDocV2("spec.scaleTargetRef")
+
 			failures = append(failures, common.Failure{
-				Text: fmt.Sprintf("HorizontalPodAutoscaler uses %s/%s as ScaleTargetRef which does not exist.", scaleTargetRef.Kind, scaleTargetRef.Name),
+				Text:          fmt.Sprintf("HorizontalPodAutoscaler uses %s/%s as ScaleTargetRef which does not exist.", scaleTargetRef.Kind, scaleTargetRef.Name),
+				KubernetesDoc: doc,
 				Sensitive: []common.Sensitive{
 					{
 						Unmasked: scaleTargetRef.Name,
@@ -94,8 +107,11 @@ func (HpaAnalyzer) Analyze(a common.Analyzer) ([]common.Result, error) {
 			}
 
 			if containers <= 0 {
+				doc := apiDoc.GetApiDocV2("spec.scaleTargetRef.kind")
+
 				failures = append(failures, common.Failure{
-					Text: fmt.Sprintf("%s %s/%s does not have resource configured.", scaleTargetRef.Kind, a.Namespace, scaleTargetRef.Name),
+					Text:          fmt.Sprintf("%s %s/%s does not have resource configured.", scaleTargetRef.Kind, a.Namespace, scaleTargetRef.Name),
+					KubernetesDoc: doc,
 					Sensitive: []common.Sensitive{
 						{
 							Unmasked: scaleTargetRef.Name,

pkg/analyzer/ingress.go

@@ -17,15 +17,25 @@ import (
 	"fmt"
 
 	"github.com/k8sgpt-ai/k8sgpt/pkg/common"
+	"github.com/k8sgpt-ai/k8sgpt/pkg/kubernetes"
 	"github.com/k8sgpt-ai/k8sgpt/pkg/util"
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/apimachinery/pkg/runtime/schema"
 )
 
 type IngressAnalyzer struct{}
 
 func (IngressAnalyzer) Analyze(a common.Analyzer) ([]common.Result, error) {
 
 	kind := "Ingress"
+	apiDoc := kubernetes.K8sApiReference{
+		Kind: kind,
+		ApiVersion: schema.GroupVersion{
+			Group:   "networking",
+			Version: "v1",
+		},
+		OpenapiSchema: a.OpenapiSchema,
+	}
 
 	AnalyzerErrorsMetric.DeletePartialMatch(map[string]string{
 		"analyzer_name": kind,
@@ -46,8 +56,11 @@ func (IngressAnalyzer) Analyze(a common.Analyzer) ([]common.Result, error) {
 		if ingressClassName == nil {
 			ingClassValue := ing.Annotations["kubernetes.io/ingress.class"]
 			if ingClassValue == "" {
+				doc := apiDoc.GetApiDocV2("spec.ingressClassName")
+
 				failures = append(failures, common.Failure{
-					Text: fmt.Sprintf("Ingress %s/%s does not specify an Ingress class.", ing.Namespace, ing.Name),
+					Text:          fmt.Sprintf("Ingress %s/%s does not specify an Ingress class.", ing.Namespace, ing.Name),
+					KubernetesDoc: doc,
 					Sensitive: []common.Sensitive{
 						{
 							Unmasked: ing.Namespace,
@@ -68,8 +81,11 @@ func (IngressAnalyzer) Analyze(a common.Analyzer) ([]common.Result, error) {
 		if ingressClassName != nil {
 			_, err := a.Client.GetClient().NetworkingV1().IngressClasses().Get(a.Context, *ingressClassName, metav1.GetOptions{})
 			if err != nil {
+				doc := apiDoc.GetApiDocV2("spec.ingressClassName")
+
 				failures = append(failures, common.Failure{
-					Text: fmt.Sprintf("Ingress uses the ingress class %s which does not exist.", *ingressClassName),
+					Text:          fmt.Sprintf("Ingress uses the ingress class %s which does not exist.", *ingressClassName),
+					KubernetesDoc: doc,
 					Sensitive: []common.Sensitive{
 						{
 							Unmasked: *ingressClassName,
@@ -86,8 +102,11 @@ func (IngressAnalyzer) Analyze(a common.Analyzer) ([]common.Result, error) {
 			for _, path := range rule.HTTP.Paths {
 				_, err := a.Client.GetClient().CoreV1().Services(ing.Namespace).Get(a.Context, path.Backend.Service.Name, metav1.GetOptions{})
 				if err != nil {
+					doc := apiDoc.GetApiDocV2("spec.rules.http.paths.backend.service")
+
 					failures = append(failures, common.Failure{
-						Text: fmt.Sprintf("Ingress uses the service %s/%s which does not exist.", ing.Namespace, path.Backend.Service.Name),
+						Text:          fmt.Sprintf("Ingress uses the service %s/%s which does not exist.", ing.Namespace, path.Backend.Service.Name),
+						KubernetesDoc: doc,
 						Sensitive: []common.Sensitive{
 							{
 								Unmasked: ing.Namespace,
@@ -106,8 +125,11 @@ func (IngressAnalyzer) Analyze(a common.Analyzer) ([]common.Result, error) {
 		for _, tls := range ing.Spec.TLS {
 			_, err := a.Client.GetClient().CoreV1().Secrets(ing.Namespace).Get(a.Context, tls.SecretName, metav1.GetOptions{})
 			if err != nil {
+				doc := apiDoc.GetApiDocV2("spec.tls.secretName")
+
 				failures = append(failures, common.Failure{
-					Text: fmt.Sprintf("Ingress uses the secret %s/%s as a TLS certificate which does not exist.", ing.Namespace, tls.SecretName),
+					Text:          fmt.Sprintf("Ingress uses the secret %s/%s as a TLS certificate which does not exist.", ing.Namespace, tls.SecretName),
+					KubernetesDoc: doc,
 					Sensitive: []common.Sensitive{
 						{
 							Unmasked: ing.Namespace,

pkg/analyzer/netpol.go

@@ -17,15 +17,25 @@ import (
 	"fmt"
 
 	"github.com/k8sgpt-ai/k8sgpt/pkg/common"
+	"github.com/k8sgpt-ai/k8sgpt/pkg/kubernetes"
 	"github.com/k8sgpt-ai/k8sgpt/pkg/util"
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/apimachinery/pkg/runtime/schema"
 )
 
 type NetworkPolicyAnalyzer struct{}
 
 func (NetworkPolicyAnalyzer) Analyze(a common.Analyzer) ([]common.Result, error) {
 
 	kind := "NetworkPolicy"
+	apiDoc := kubernetes.K8sApiReference{
+		Kind: kind,
+		ApiVersion: schema.GroupVersion{
+			Group:   "networking",
+			Version: "v1",
+		},
+		OpenapiSchema: a.OpenapiSchema,
+	}
 
 	AnalyzerErrorsMetric.DeletePartialMatch(map[string]string{
 		"analyzer_name": kind,
@@ -45,8 +55,11 @@ func (NetworkPolicyAnalyzer) Analyze(a common.Analyzer) ([]common.Result, error)
 
 		// Check if policy allows traffic to all pods in the namespace
 		if len(policy.Spec.PodSelector.MatchLabels) == 0 {
+			doc := apiDoc.GetApiDocV2("spec.podSelector.matchLabels")
+
 			failures = append(failures, common.Failure{
-				Text: fmt.Sprintf("Network policy allows traffic to all pods: %s", policy.Name),
+				Text:          fmt.Sprintf("Network policy allows traffic to all pods: %s", policy.Name),
+				KubernetesDoc: doc,
 				Sensitive: []common.Sensitive{
 					{
 						Unmasked: policy.Name,