Internal api documentation (#101)

zivnevo · web-flow · commit 6d8c88aa5dbd · 2022-09-28T16:52:13.000+03:00
* avoid exporting deploymentConnectivity
* update supported versions
* inline documentation
* package upgrade
* example to show in docs
* fix lint issue
Signed-off-by: Ziv Nevo &lt;nevo@il.ibm.com&gt;
diff --git a/SECURITY.md b/SECURITY.md
@@ -4,7 +4,8 @@
 
 | Version | Supported          |
 | ------- | ------------------ |
-| 1.2.x   | :white_check_mark: |
+| 1.3.x   | :white_check_mark: |
+| 1.2.x   | :x:                |
 | 1.1.x   | :x:                |
 | 1.0.x   | :x:                |
 | < 1.0   | :x:                |
diff --git a/go.mod b/go.mod
@@ -17,7 +17,7 @@ require (
 	github.com/json-iterator/go v1.1.12 // indirect
 	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
 	github.com/modern-go/reflect2 v1.0.2 // indirect
-	golang.org/x/net v0.0.0-20220127200216-cd36cc0744dd // indirect
+	golang.org/x/net v0.0.0-20220722155237-a158d28d115b // indirect
 	golang.org/x/text v0.3.7 // indirect
 	gopkg.in/inf.v0 v0.9.1 // indirect
 	gopkg.in/yaml.v2 v2.4.0 // indirect
diff --git a/go.sum b/go.sum
@@ -310,8 +310,8 @@ golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v
 golang.org/x/net v0.0.0-20210316092652-d523dce5a7f4/go.mod h1:RBQZq4jEuRlivfhVLdyRGr576XBO4/greRjx4P4O3yc=
 golang.org/x/net v0.0.0-20210405180319-a5a99cb37ef4/go.mod h1:p54w0d4576C0XHj96bSt6lcn1PtDYWL6XObtHCRCNQM=
 golang.org/x/net v0.0.0-20211209124913-491a49abca63/go.mod h1:9nx3DQGgdP8bBQD5qxJ1jj9UTztislL4KSBs9R2vV5Y=
-golang.org/x/net v0.0.0-20220127200216-cd36cc0744dd h1:O7DYs+zxREGLKzKoMQrtrEacpb0ZVXA5rIwylE2Xchk=
-golang.org/x/net v0.0.0-20220127200216-cd36cc0744dd/go.mod h1:CfG3xpIq0wQ8r1q4Su4UZFWDARRcnwPjda9FqA0JpMk=
+golang.org/x/net v0.0.0-20220722155237-a158d28d115b h1:PxfKdU9lEEDYjdIzOtC4qFWgkU2rGHdKlKowJSMN9h0=
+golang.org/x/net v0.0.0-20220722155237-a158d28d115b/go.mod h1:XRhObCWvk6IyKnWLug+ECip1KBveYUHfp+8e9klMJ9c=
 golang.org/x/oauth2 v0.0.0-20180821212333-d2e6202438be/go.mod h1:N/0e6XlmueqKjAGxoOufVs8QHGRruUQn6yWY3a++T0U=
 golang.org/x/oauth2 v0.0.0-20190226205417-e64efc72b421/go.mod h1:gOpvHmFTYa4IltrdGE7lF6nIHvwfUNPOp7c8zoXwtLw=
 golang.org/x/oauth2 v0.0.0-20190604053449-0f29369cfe45/go.mod h1:gOpvHmFTYa4IltrdGE7lF6nIHvwfUNPOp7c8zoXwtLw=
@@ -380,7 +380,7 @@ golang.org/x/sys v0.0.0-20210423082822-04245dca01da/go.mod h1:h1NjWce9XRLGQEsW7w
 golang.org/x/sys v0.0.0-20210510120138-977fb7262007/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20210615035016-665e8c7367d1/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20210831042530-f4d43177bf5e/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.0.0-20211216021012-1d35b9e2eb4e/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.0.0-20220520151302-bc2c85ada10a/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
 golang.org/x/term v0.0.0-20210615171337-6886f2dfbf5b/go.mod h1:jbD1KX2456YbFQfuXm/mYQcufACuNUgVhRMnK/tPxf8=
 golang.org/x/term v0.0.0-20210927222741-03fcf44c2211/go.mod h1:jbD1KX2456YbFQfuXm/mYQcufACuNUgVhRMnK/tPxf8=
diff --git a/pkg/controller/error_types.go b/pkg/controller/error_types.go
@@ -5,6 +5,8 @@ import (
 	"fmt"
 )
 
+// FileProcessingError holds all information about a single error/warning that occurred during
+// the discovery and processing of the connectivity of a given K8s-app.
 type FileProcessingError struct {
 	err      error
 	filePath string
@@ -25,25 +27,30 @@ func newFileProcessingError(origErr error, msg, filePath string, lineNum, docID
 	return &fpe
 }
 
+// Error returns the actual error
 func (e *FileProcessingError) Error() error {
 	return e.err
 }
 
+// File returns the file in which the error occurred (or an empty string if no file context is available)
 func (e *FileProcessingError) File() string {
 	return e.filePath
 }
 
+// LineNo returns the file's line-number in which the error occurred (or 0 if not applicable)
 func (e *FileProcessingError) LineNo() int {
 	return e.lineNum
 }
 
+// DocumentID returns the file's YAML document ID (0-based) in which the error occurred (or an error if not applicable)
 func (e *FileProcessingError) DocumentID() (int, error) {
 	if e.docID < 0 {
 		return -1, errors.New("no document ID is available for this error")
 	}
 	return e.docID, nil
 }
 
+// Location returns file location (filename, line-number, document ID) of an error (or an empty string if not applicable)
 func (e *FileProcessingError) Location() string {
 	if e.filePath == "" {
 		return ""
@@ -59,10 +66,13 @@ func (e *FileProcessingError) Location() string {
 	return fmt.Sprintf("in file: %s%s", e.File(), suffix)
 }
 
+// IsFatal returns whether the error is considered fatal (no further processing is possible)
 func (e *FileProcessingError) IsFatal() bool {
 	return e.fatal
 }
 
+// IsFatal returns whether the error is considered severe
+// (further processing is possible, but results may not be useable)
 func (e *FileProcessingError) IsSevere() bool {
 	return e.severe
 }
diff --git a/pkg/controller/example_test.go b/pkg/controller/example_test.go
@@ -0,0 +1,123 @@
+package controller_test
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+
+	"github.com/np-guard/cluster-topology-analyzer/pkg/controller"
+)
+
+func ExamplePoliciesSynthesizer() {
+	logger := controller.NewDefaultLogger()
+	synth := controller.NewPoliciesSynthesizer(controller.WithLogger(logger))
+
+	netpols, err := synth.PoliciesFromFolderPath("../../tests/k8s_wordpress_example")
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "Error synthesizing policies: %v\n", err)
+		os.Exit(1)
+	}
+	buf, _ := json.MarshalIndent(netpols, "", "    ")
+	fmt.Printf("%v\n", string(buf))
+	// Output:
+	// [
+	//     {
+	//         "kind": "NetworkPolicy",
+	//         "apiVersion": "networking.k8s.io/v1",
+	//         "metadata": {
+	//             "name": "wordpress-netpol",
+	//             "creationTimestamp": null
+	//         },
+	//         "spec": {
+	//             "podSelector": {
+	//                 "matchLabels": {
+	//                     "app": "wordpress",
+	//                     "tier": "frontend"
+	//                 }
+	//             },
+	//             "ingress": [
+	//                 {
+	//                     "ports": [
+	//                         {
+	//                             "protocol": "TCP",
+	//                             "port": 80
+	//                         }
+	//                     ]
+	//                 }
+	//             ],
+	//             "egress": [
+	//                 {
+	//                     "ports": [
+	//                         {
+	//                             "protocol": "TCP",
+	//                             "port": 3306
+	//                         }
+	//                     ],
+	//                     "to": [
+	//                         {
+	//                             "podSelector": {
+	//                                 "matchLabels": {
+	//                                     "app": "wordpress",
+	//                                     "tier": "mysql"
+	//                                 }
+	//                             }
+	//                         }
+	//                     ]
+	//                 },
+	//                 {
+	//                     "ports": [
+	//                         {
+	//                             "protocol": "UDP",
+	//                             "port": 53
+	//                         }
+	//                     ]
+	//                 }
+	//             ],
+	//             "policyTypes": [
+	//                 "Ingress",
+	//                 "Egress"
+	//             ]
+	//         }
+	//     },
+	//     {
+	//         "kind": "NetworkPolicy",
+	//         "apiVersion": "networking.k8s.io/v1",
+	//         "metadata": {
+	//             "name": "wordpress-mysql-netpol",
+	//             "creationTimestamp": null
+	//         },
+	//         "spec": {
+	//             "podSelector": {
+	//                 "matchLabels": {
+	//                     "app": "wordpress",
+	//                     "tier": "mysql"
+	//                 }
+	//             },
+	//             "ingress": [
+	//                 {
+	//                     "ports": [
+	//                         {
+	//                             "protocol": "TCP",
+	//                             "port": 3306
+	//                         }
+	//                     ],
+	//                     "from": [
+	//                         {
+	//                             "podSelector": {
+	//                                 "matchLabels": {
+	//                                     "app": "wordpress",
+	//                                     "tier": "frontend"
+	//                                 }
+	//                             }
+	//                         }
+	//                     ]
+	//                 }
+	//             ],
+	//             "policyTypes": [
+	//                 "Ingress",
+	//                 "Egress"
+	//             ]
+	//         }
+	//     }
+	// ]
+}
diff --git a/pkg/controller/logger.go b/pkg/controller/logger.go
@@ -6,6 +6,7 @@ import (
 	"log"
 )
 
+// Verbosity is an enumerated type for defining the level of verbosity.
 type Verbosity int
 
 const (
@@ -14,47 +15,55 @@ const (
 	HighVerbosity
 )
 
+// The Logger interface defines the API for loggers in this package.
 type Logger interface {
 	Debugf(format string, o ...interface{})
 	Infof(format string, o ...interface{})
 	Warnf(format string, o ...interface{})
 	Errorf(err error, format string, o ...interface{})
 }
 
+// DefaultLogger is the package's built-in logger. It uses log.Default() as the underlying logger.
 type DefaultLogger struct {
 	verbosity Verbosity
 	l         *log.Logger
 }
 
+// NewDefaultLogger creates an instance of DefaultLogger with the highest verbosity.
 func NewDefaultLogger() *DefaultLogger {
 	return NewDefaultLoggerWithVerbosity(HighVerbosity)
 }
 
+// NewDefaultLoggerWithVerbosity creates an instance of DefaultLogger with a user-defined verbosity.
 func NewDefaultLoggerWithVerbosity(verbosity Verbosity) *DefaultLogger {
 	return &DefaultLogger{
 		verbosity: verbosity,
 		l:         log.Default(),
 	}
 }
 
+// Debugf writes a debug message to the log (only if DefaultLogger verbosity is set to HighVerbosity)
 func (df *DefaultLogger) Debugf(format string, o ...interface{}) {
 	if df.verbosity == HighVerbosity {
 		df.l.Printf(format, o...)
 	}
 }
 
+// Infof writes an informative message to the log (only if DefaultLogger verbosity is set to HighVerbosity)
 func (df *DefaultLogger) Infof(format string, o ...interface{}) {
 	if df.verbosity == HighVerbosity {
 		df.l.Printf(format, o...)
 	}
 }
 
+// Warnf writes a warning message to the log (unless DefaultLogger verbosity is set to LowVerbosity)
 func (df *DefaultLogger) Warnf(format string, o ...interface{}) {
 	if df.verbosity >= MediumVerbosity {
 		df.l.Printf(format, o...)
 	}
 }
 
+// Errorf writes an error message to the log (regardless of DefaultLogger's verbosity)
 func (df *DefaultLogger) Errorf(err error, format string, o ...interface{}) {
 	df.l.Printf("%s: %v", fmt.Sprintf(format, o...), err)
 }
diff --git a/pkg/controller/policies_synthesizer.go b/pkg/controller/policies_synthesizer.go
@@ -1,3 +1,7 @@
+// The controller package of cluster-topology-analyzer discovers the connectivity of a Kubernetes application
+// by analyzing its YAML manifests and looking for network addresses that match. It can output a set of
+// discovered connections or even Kubernetes NetworkPolicies to allow only these connections. For more
+// information, see https://github.com/np-guard/cluster-topology-analyzer.
 package controller
 
 import (
@@ -6,27 +10,38 @@ import (
 	"github.com/np-guard/cluster-topology-analyzer/pkg/common"
 )
 
+// A PoliciesSynthesizer provides API to recursively scan a directory for Kubernetes resources
+// and extract the required connectivity between the workloads of the K8s application managed in this directory.
+// It is possible to get either a slice with all the discovered connections or a slice with K8s NetworkPolicies
+// that allow only the discovered connections and nothing more.
 type PoliciesSynthesizer struct {
 	logger      Logger
 	stopOnError bool
 
 	errors []FileProcessingError
 }
 
+// PoliciesSynthesizerOption is the type for specifying options for PoliciesSynthesizer,
+// using Golang's Options Pattern (https://golang.cafe/blog/golang-functional-options-pattern.html).
 type PoliciesSynthesizerOption func(*PoliciesSynthesizer)
 
+// WithLogger is a functional option which sets the logger for a PoliciesSynthesizer to use.
+// The provided logger must conform with the package's Logger interface.
 func WithLogger(logger Logger) PoliciesSynthesizerOption {
 	return func(p *PoliciesSynthesizer) {
 		p.logger = logger
 	}
 }
 
+// WithStopOnError is a functional option which directs PoliciesSynthesizer to stop any processing after the
+// first severe error.
 func WithStopOnError() PoliciesSynthesizerOption {
 	return func(p *PoliciesSynthesizer) {
 		p.stopOnError = true
 	}
 }
 
+// NewPoliciesSynthesizer creates a new instance of PoliciesSynthesizer, and applies the provided functional options.
 func NewPoliciesSynthesizer(options ...PoliciesSynthesizerOption) *PoliciesSynthesizer {
 	// object with default behavior options
 	ps := &PoliciesSynthesizer{
@@ -41,10 +56,13 @@ func NewPoliciesSynthesizer(options ...PoliciesSynthesizerOption) *PoliciesSynth
 	return ps
 }
 
+// Errors returns a slice of FileProcessingError with all warnings and errors encountered during processing.
 func (ps *PoliciesSynthesizer) Errors() []FileProcessingError {
 	return ps.errors
 }
 
+// PoliciesFromFolderPath returns a slice of Kubernetes NetworkPolicies that allow only the connections discovered
+// while processing K8s resources under the provided directory or one of its subdirectories (recursively).
 func (ps *PoliciesSynthesizer) PoliciesFromFolderPath(dirPath string) ([]*networking.NetworkPolicy, error) {
 	connections, errs := extractConnections(dirPath, ps.stopOnError)
 	policies := []*networking.NetworkPolicy{}
@@ -60,6 +78,8 @@ func (ps *PoliciesSynthesizer) PoliciesFromFolderPath(dirPath string) ([]*networ
 	return policies, nil
 }
 
+// ConnectionsFromFolderPath returns a slice of Connections, listing the connections discovered
+// while processing K8s resources under the provided directory or one of its subdirectories (recursively).
 func (ps *PoliciesSynthesizer) ConnectionsFromFolderPath(dirPath string) ([]*common.Connections, error) {
 	connections, errs := extractConnections(dirPath, ps.stopOnError)
 	ps.errors = errs
diff --git a/pkg/controller/synth_netpols.go b/pkg/controller/synth_netpols.go

Original file line number	Diff line number	Diff line change
`@@ -5,6 +5,8 @@ import (`
`5`	`5`	`"fmt"`
`6`	`6`	`)`
`7`	`7`
	`8`	`+// FileProcessingError holds all information about a single error/warning that occurred during`
	`9`	`+// the discovery and processing of the connectivity of a given K8s-app.`
`8`	`10`	`type FileProcessingError struct {`
`9`	`11`	`err error`
`10`	`12`	`filePath string`
`@@ -25,25 +27,30 @@ func newFileProcessingError(origErr error, msg, filePath string, lineNum, docID`
`25`	`27`	`return &fpe`
`26`	`28`	`}`
`27`	`29`
	`30`	`+// Error returns the actual error`
`28`	`31`	`func (e *FileProcessingError) Error() error {`
`29`	`32`	`return e.err`
`30`	`33`	`}`
`31`	`34`
	`35`	`+// File returns the file in which the error occurred (or an empty string if no file context is available)`
`32`	`36`	`func (e *FileProcessingError) File() string {`
`33`	`37`	`return e.filePath`
`34`	`38`	`}`
`35`	`39`
	`40`	`+// LineNo returns the file's line-number in which the error occurred (or 0 if not applicable)`
`36`	`41`	`func (e *FileProcessingError) LineNo() int {`
`37`	`42`	`return e.lineNum`
`38`	`43`	`}`
`39`	`44`
	`45`	`+// DocumentID returns the file's YAML document ID (0-based) in which the error occurred (or an error if not applicable)`
`40`	`46`	`func (e *FileProcessingError) DocumentID() (int, error) {`
`41`	`47`	`if e.docID < 0 {`
`42`	`48`	`return -1, errors.New("no document ID is available for this error")`
`43`	`49`	`}`
`44`	`50`	`return e.docID, nil`
`45`	`51`	`}`
`46`	`52`
	`53`	`+// Location returns file location (filename, line-number, document ID) of an error (or an empty string if not applicable)`
`47`	`54`	`func (e *FileProcessingError) Location() string {`
`48`	`55`	`if e.filePath == "" {`
`49`	`56`	`return ""`
`@@ -59,10 +66,13 @@ func (e *FileProcessingError) Location() string {`
`59`	`66`	`return fmt.Sprintf("in file: %s%s", e.File(), suffix)`
`60`	`67`	`}`
`61`	`68`
	`69`	`+// IsFatal returns whether the error is considered fatal (no further processing is possible)`
`62`	`70`	`func (e *FileProcessingError) IsFatal() bool {`
`63`	`71`	`return e.fatal`
`64`	`72`	`}`
`65`	`73`
	`74`	`+// IsFatal returns whether the error is considered severe`
	`75`	`+// (further processing is possible, but results may not be useable)`
`66`	`76`	`func (e *FileProcessingError) IsSevere() bool {`
`67`	`77`	`return e.severe`
`68`	`78`	`}`
Original file line number	Diff line number	Diff line change
`@@ -6,6 +6,7 @@ import (`
`6`	`6`	`"log"`
`7`	`7`	`)`
`8`	`8`
	`9`	`+// Verbosity is an enumerated type for defining the level of verbosity.`
`9`	`10`	`type Verbosity int`
`10`	`11`
`11`	`12`	`const (`
`@@ -14,47 +15,55 @@ const (`
`14`	`15`	`HighVerbosity`
`15`	`16`	`)`
`16`	`17`
	`18`	`+// The Logger interface defines the API for loggers in this package.`
`17`	`19`	`type Logger interface {`
`18`	`20`	`Debugf(format string, o ...interface{})`
`19`	`21`	`Infof(format string, o ...interface{})`
`20`	`22`	`Warnf(format string, o ...interface{})`
`21`	`23`	`Errorf(err error, format string, o ...interface{})`
`22`	`24`	`}`
`23`	`25`
	`26`	`+// DefaultLogger is the package's built-in logger. It uses log.Default() as the underlying logger.`
`24`	`27`	`type DefaultLogger struct {`
`25`	`28`	`verbosity Verbosity`
`26`	`29`	`l *log.Logger`
`27`	`30`	`}`
`28`	`31`
	`32`	`+// NewDefaultLogger creates an instance of DefaultLogger with the highest verbosity.`
`29`	`33`	`func NewDefaultLogger() *DefaultLogger {`
`30`	`34`	`return NewDefaultLoggerWithVerbosity(HighVerbosity)`
`31`	`35`	`}`
`32`	`36`
	`37`	`+// NewDefaultLoggerWithVerbosity creates an instance of DefaultLogger with a user-defined verbosity.`
`33`	`38`	`func NewDefaultLoggerWithVerbosity(verbosity Verbosity) *DefaultLogger {`
`34`	`39`	`return &DefaultLogger{`
`35`	`40`	`verbosity: verbosity,`
`36`	`41`	`l: log.Default(),`
`37`	`42`	`}`
`38`	`43`	`}`
`39`	`44`
	`45`	`+// Debugf writes a debug message to the log (only if DefaultLogger verbosity is set to HighVerbosity)`
`40`	`46`	`func (df *DefaultLogger) Debugf(format string, o ...interface{}) {`
`41`	`47`	`if df.verbosity == HighVerbosity {`
`42`	`48`	`df.l.Printf(format, o...)`
`43`	`49`	`}`
`44`	`50`	`}`
`45`	`51`
	`52`	`+// Infof writes an informative message to the log (only if DefaultLogger verbosity is set to HighVerbosity)`
`46`	`53`	`func (df *DefaultLogger) Infof(format string, o ...interface{}) {`
`47`	`54`	`if df.verbosity == HighVerbosity {`
`48`	`55`	`df.l.Printf(format, o...)`
`49`	`56`	`}`
`50`	`57`	`}`
`51`	`58`
	`59`	`+// Warnf writes a warning message to the log (unless DefaultLogger verbosity is set to LowVerbosity)`
`52`	`60`	`func (df *DefaultLogger) Warnf(format string, o ...interface{}) {`
`53`	`61`	`if df.verbosity >= MediumVerbosity {`
`54`	`62`	`df.l.Printf(format, o...)`
`55`	`63`	`}`
`56`	`64`	`}`
`57`	`65`
	`66`	`+// Errorf writes an error message to the log (regardless of DefaultLogger's verbosity)`
`58`	`67`	`func (df *DefaultLogger) Errorf(err error, format string, o ...interface{}) {`
`59`	`68`	`df.l.Printf("%s: %v", fmt.Sprintf(format, o...), err)`
`60`	`69`	`}`