KIALI-686: Adding documentation to validation system

handlers/services.go

@@ -91,7 +91,9 @@ func ServiceHealth(w http.ResponseWriter, r *http.Request) {
 	RespondWithJSON(w, http.StatusOK, health)
 }
 
-// ServiceIstioValidations is the API handler to get istio validations of a single service
+// ServiceIstioValidations is the API handler to get istio validations of a single service that returns
+// an IstioValidation object which contains for each object type (i.e.: routerule, pod, destinationpolicy,...)
+// one validation per each detected object in the current cluster that have an error/warning in its configuration.
 func ServiceIstioValidations(w http.ResponseWriter, r *http.Request) {
 	// Get business layer
 	business, err := business.Get()

services/business/checkers/pod_checker.go

@@ -12,12 +12,12 @@ type PodChecker struct {
 
 const podsCheckerType = "pod"
 
+// Runs all checkers for Pod objects passed into the PodChecker
 func (checker PodChecker) Check() *models.IstioTypeValidations {
-	// The only available checker test for missing
-	// sidecars in a service. Only individual checks makes sense for now.
 	return checker.runIndividualChecks()
 }
 
+// Runs individual checks for each pod in pod checker.
 func (checker PodChecker) runIndividualChecks() *models.IstioTypeValidations {
 	typeValidations := models.IstioTypeValidations{}
 	if len(checker.Pods) == 0 {
@@ -47,6 +47,7 @@ func (checker PodChecker) runIndividualChecks() *models.IstioTypeValidations {
 	return &typeValidations
 }
 
+// Returns a list of all individual enabled checkers
 func (checker *PodChecker) enabledCheckersFor(object *v1.Pod) []Checker {
 	return []Checker{
 		pods.SidecarPresenceChecker{Pod: object},

services/business/checkers/pods/sidecar_presence_checker.go

@@ -12,6 +12,8 @@ type SidecarPresenceChecker struct {
 	Pod *v1.Pod
 }
 
+// A Checker checks individual objects and builds an IstioCheck whenever the check fails.
+// SidecarPresenceChecker checks if the current Pod has an Istio Sidecar installed.
 func (checker SidecarPresenceChecker) Check() ([]*models.IstioCheck, bool) {
 	for _, container := range checker.Pod.Spec.Containers {
 		if strings.HasPrefix(container.Image, SidecarContainerImage) {

services/business/checkers/route_rule_checker.go

@@ -18,6 +18,10 @@ type RouteRuleChecker struct {
 	RouteRules []kubernetes.IstioObject
 }
 
+// An Object Checker runs all checkers for an specific object type (i.e.: pod, route rule,...)
+// It run two kinds of checkers:
+// 1. Individual checks: validating individual objects.
+// 2. Group checks: validating behaviour between configurations.
 func (in RouteRuleChecker) Check() *models.IstioTypeValidations {
 	typeValidations := models.IstioTypeValidations{}
 
@@ -27,6 +31,7 @@ func (in RouteRuleChecker) Check() *models.IstioTypeValidations {
 	return &typeValidations
 }
 
+// Runs individual checks for each route rule
 func (in RouteRuleChecker) runIndividualChecks() *models.IstioTypeValidations {
 	typeValidations := models.IstioTypeValidations{}
 	var wg sync.WaitGroup
@@ -42,17 +47,20 @@ func (in RouteRuleChecker) runIndividualChecks() *models.IstioTypeValidations {
 	return &typeValidations
 }
 
+// runGroupChecks runs group checks for all route rules
 func (in *RouteRuleChecker) runGroupChecks() *models.IstioTypeValidations {
 	return &models.IstioTypeValidations{}
 }
 
+// enabledCheckersFor returns the list of all individual enabled checkers
 func enabledCheckersFor(object kubernetes.IstioObject) []Checker {
 	return []Checker{
 		route_rules.RouteChecker{object},
 		route_rules.PrecedenceChecker{object},
 	}
 }
 
+// runChecks runs all the individual checks for a single route rule and it appends the result into typeValidations
 func runChecks(routeRule kubernetes.IstioObject, typeValidations *models.IstioTypeValidations, wg *sync.WaitGroup) {
 	defer (*wg).Done()
 	var checkersWg sync.WaitGroup
@@ -74,6 +82,7 @@ func runChecks(routeRule kubernetes.IstioObject, typeValidations *models.IstioTy
 	checkersWg.Wait()
 }
 
+// runChecker runs the specific checker and store its result into nameValidations under objectName map.
 func runChecker(checker Checker, objectName string, nameValidations *models.IstioNameValidations, wg *sync.WaitGroup) {
 	defer (*wg).Done()
 

services/business/checkers/route_rules/precedence_checker.go

@@ -10,6 +10,8 @@ import (
 
 type PrecedenceChecker struct{ kubernetes.IstioObject }
 
+// Check returns both an array of IstioCheck objects and a boolean telling if the route rule is valid.
+// Each IstioCheck represent an error or warning detected when validating the precedence field.
 func (route PrecedenceChecker) Check() ([]*models.IstioCheck, bool) {
 	valid := true
 	validations := make([]*models.IstioCheck, 0)

services/business/checkers/route_rules/route_checker.go

@@ -11,6 +11,12 @@ import (
 
 type RouteChecker struct{ kubernetes.IstioObject }
 
+// Check returns both an array of IstioCheck and a boolean indicating if the current route rule is valid.
+// The array of IstioChecks contains the result of running the following validations:
+// 1. All weights with a numeric number.
+// 2. All weights have value between 0 and 100.
+// 3. Sum of all weights are 100 (if only one weight, then it assumes that is 100).
+// 4. All the route has to have weight label.
 func (route RouteChecker) Check() ([]*models.IstioCheck, bool) {
 	validations := make([]*models.IstioCheck, 0)
 

services/business/istio_validations.go

@@ -16,6 +16,8 @@ type ObjectChecker interface {
 	Check() *models.IstioTypeValidations
 }
 
+// GetServiceValidations returns an IstioTypeValidations object with all the checks found when running
+// all the enabled checkers.
 func (in *IstioValidationsService) GetServiceValidations(namespace, service string) (models.IstioTypeValidations, error) {
 	// Get all the Istio objects from a Namespace and service
 	istioDetails, err := in.k8s.GetIstioDetails(namespace, service)
@@ -49,10 +51,11 @@ func (in *IstioValidationsService) GetServiceValidations(namespace, service stri
 		objectTypeValidations.MergeValidations(<-validation)
 	}
 
-	// Get groupal validations for same kind istio objects
 	return objectTypeValidations, nil
 }
 
+// enabledCheckersFor returns the list of ObjectCheckers that will be run for istioDetails and pods
+// objects passed by parameters
 func enabledCheckersFor(istioDetails *kubernetes.IstioDetails, pods *v1.PodList) []ObjectChecker {
 	return []ObjectChecker{
 		checkers.RouteRuleChecker{istioDetails.RouteRules},

services/models/istio_validation.go

@@ -1,6 +1,6 @@
 package models
 
-// IstioTypeValidations represents a set of IstioNameValidations grouper per Istio ObjectType.
+// IstioTypeValidations represents a set of IstioNameValidations grouped per Istio ObjectType.
 // It is possible that different object types have same name, but names per ObjectType are unique.
 type IstioTypeValidations map[string]*IstioNameValidations
 
@@ -9,16 +9,16 @@ type IstioTypeValidations map[string]*IstioNameValidations
 type IstioNameValidations map[string]*IstioValidation
 
 type IstioValidation struct {
-	Name       string        `json:"name"`
-	ObjectType string        `json:"object_type"`
-	Valid      bool          `json:"valid"`
-	Checks     []*IstioCheck `json:"checks"`
+	Name       string        `json:"name"`        // Name of the object itself
+	ObjectType string        `json:"object_type"` // Type of the object
+	Valid      bool          `json:"valid"`       // Represents validity of the object: in case of warning, validity remainds as true
+	Checks     []*IstioCheck `json:"checks"`      // Array of checks
 }
 
 type IstioCheck struct {
-	Message  string `json:"message"`
-	Severity string `json:"severity"`
-	Path     string `json:"path"`
+	Message  string `json:"message"`  // Description of the check
+	Severity string `json:"severity"` // Indicates the level of importance: error or warning
+	Path     string `json:"path"`     // String that describes where in the yaml file is the check located
 }
 
 func BuildCheck(message, severity, path string) IstioCheck {