major docs

Author: adiprerepa

cmd/analyze.go

@@ -18,6 +18,8 @@ var (
 	details     bool
 )
 
+// todo these should change to tetrate-hosted s3 files, with which we can send over cluster information
+// 	to track usage patterns.
 const (
 	gcpPricingLocation = "https://raw.githubusercontent.com/tetratelabs/istio-cost-analyzer/master/pricing/gcp/gcp_pricing.json"
 	awsPricingLocation = "https://raw.githubusercontent.com/tetratelabs/istio-cost-analyzer/master/pricing/aws/aws_pricing.json"
@@ -28,8 +30,8 @@ var analyzeCmd = &cobra.Command{
 	Short: "List all the pod to pod links in the mesh",
 	Long:  ``,
 	RunE: func(cmd *cobra.Command, args []string) error {
-		dapani, err := pkg.NewDapaniProm(prometheusEndpoint)
-		kubeClient := pkg.NewDapaniKubeClient()
+		analyzerProm, err := pkg.NewAnalyzerProm(prometheusEndpoint)
+		kubeClient := pkg.NewAnalyzerKube()
 		if err != nil {
 			return err
 		}
@@ -43,26 +45,32 @@ var analyzeCmd = &cobra.Command{
 				return errors.New("provide different cloud")
 			}
 		}
+		// initialize analyzer
 		cost, err := pkg.NewCostAnalysis(pricePath)
 		if err != nil {
 			return err
 		}
-		go dapani.PortForwardProm()
-		if err := dapani.WaitForProm(); err != nil {
+		// port-forward prometheus asynchronously and wait for it to be ready
+		go analyzerProm.PortForwardProm()
+		if err := analyzerProm.WaitForProm(); err != nil {
 			return err
 		}
 		duration, err := time.ParseDuration(queryBefore)
 		if err != nil {
 			return err
 		}
-		podCalls, err := dapani.GetPodCalls(duration)
+		// query prometheus for raw pod calls
+		podCalls, err := analyzerProm.GetPodCalls(duration)
 		if err != nil {
 			return err
 		}
+		// transform raw pod calls to locality information
 		localityCalls, err := kubeClient.GetLocalityCalls(podCalls, cloud)
 		if err != nil {
 			return err
 		}
+		//localityCalls[0].From = "us-west1-c"
+		// calculate egress given locality information
 		totalCost, err := cost.CalculateEgress(localityCalls)
 		if err != nil {
 			return err

pkg/call.go

@@ -49,7 +49,6 @@ func PrintCostTable(calls []*Call, total float64, details bool) {
 }
 
 func printMinifiedCostTable(calls []*Call) {
-	// collapse into set by source
 	// todo should we group by source & locality or just source
 	// 	foo in us-west1-b might be treated diff from foo in us-west1-a
 	//  right now we group by just source, so all localities are grouped in the same row
@@ -108,6 +107,7 @@ func kubernetesify(table *tablewriter.Table) {
 	table.SetBorder(false)
 }
 
+// PodCall represents raw pod data, not containing locality or cost information.
 type PodCall struct {
 	FromPod      string
 	FromWorkload string

pkg/kube.go

@@ -11,11 +11,19 @@ import (
 	"path/filepath"
 )
 
+// KubeClient just wraps the kubernetes API.
+// todo should we just do:
+//  ```
+//   type KubeClient kubernetes.ClientSet
+//  ```
+// if we get no value from just wrapping?
 type KubeClient struct {
 	clientSet *kubernetes.Clientset
 }
 
-func NewDapaniKubeClient() *KubeClient {
+// NewAnalyzerKube creates a clientset using the kubeconfig found in the home directory.
+// todo make kubeconfig a settable parameter in analyzer.go
+func NewAnalyzerKube() *KubeClient {
 	var kubeconfig *string
 	if home := homedir.HomeDir(); home != "" {
 		kubeconfig = flag.String("kubeconfig", filepath.Join(home, ".kube", "config"), "(optional) absolute path to the kubeconfig file")
@@ -40,10 +48,13 @@ func NewDapaniKubeClient() *KubeClient {
 	}
 }
 
+// GetLocalityCalls uses an array of PodCall to associate localities with these pods, getting this data
+// from the kubernetes API. We can get localities by going from pod -> node -> topology.
 func (k *KubeClient) GetLocalityCalls(podCalls []*PodCall, cloud string) ([]*Call, error) {
 	calls := make([]*Call, 0)
-	// key is just source/destination service/locality. No call size info
-	// value is full Call
+	// serviceCallMap's keys are just workload/locality links, without any call size information,
+	// while the value is the full, aggregated call value for that link. We do this because there may
+	// exist multiple pods that cause the same workload/locality link, and we don't want them to duplicate.
 	serviceCallMap := make(map[Call]*Call)
 	for i := 0; i < len(podCalls); i++ {
 		fromNode, err := k.getPodNode(podCalls[i].FromPod)
@@ -68,6 +79,7 @@ func (k *KubeClient) GetLocalityCalls(podCalls []*PodCall, cloud string) ([]*Cal
 			ToWorkload:   podCalls[i].ToWorkload,
 			To:           toLocality,
 		}
+		// either create a new entry, or add to an existing one.
 		if _, ok := serviceCallMap[serviceLocalityKey]; !ok {
 			serviceCallMap[serviceLocalityKey] = &serviceLocalityKey
 			serviceLocalityKey.CallSize = podCalls[i].CallSize
@@ -81,6 +93,7 @@ func (k *KubeClient) GetLocalityCalls(podCalls []*PodCall, cloud string) ([]*Cal
 	return calls, nil
 }
 
+// getPodNode gets the node associated with a given pod name in the default namespece.
 func (k *KubeClient) getPodNode(name string) (string, error) {
 	pod, err := k.clientSet.CoreV1().Pods("default").Get(context.TODO(), name, metav1.GetOptions{})
 	if err != nil {
@@ -90,6 +103,7 @@ func (k *KubeClient) getPodNode(name string) (string, error) {
 	return pod.Spec.NodeName, nil
 }
 
+// getNodeLocality gets the locality given by topology.kubernetes.io.
 func (k *KubeClient) getNodeLocality(name, cloud string) (string, error) {
 	// if we are on AWS, we want to just get region, because availability zones
 	// are not supported yet.

pkg/prom.go

@@ -11,28 +11,35 @@ import (
 	"time"
 )
 
-type DapaniProm struct {
+// CostAnalyzerProm holds the prometheus routines necessary to collect
+// service<->service traffic data.
+type CostAnalyzerProm struct {
 	promEndpoint string
 	errChan      chan error
 	client       api.Client
 }
 
-func NewDapaniProm(promEndpoint string) (*DapaniProm, error) {
+// NewAnalyzerProm creates a prometheus client given the endpoint,
+// and errors out if the endpoint is invalid.
+func NewAnalyzerProm(promEndpoint string) (*CostAnalyzerProm, error) {
 	client, err := api.NewClient(api.Config{
 		Address: promEndpoint,
 	})
 	if err != nil {
 		fmt.Printf("cannot initialize prom lib: %v", err)
 		return nil, err
 	}
-	return &DapaniProm{
+	return &CostAnalyzerProm{
 		promEndpoint: promEndpoint,
 		errChan:      make(chan error),
 		client:       client,
 	}, nil
 }
 
-func (d *DapaniProm) PortForwardProm() {
+// PortForwardProm will execute a kubectl port-forward command, forwarding the inbuild prometheus
+// deployment to port 9090 on localhost. This is executed asynchronously, and if there is an error,
+// it is sent into d.errChan.
+func (d *CostAnalyzerProm) PortForwardProm() {
 	cmd := exec.Command("kubectl", "-n", "istio-system", "port-forward", "deployment/prometheus", "9990:9090")
 	o, err := cmd.CombinedOutput()
 	if err != nil {
@@ -42,7 +49,9 @@ func (d *DapaniProm) PortForwardProm() {
 	}
 }
 
-func (d *DapaniProm) WaitForProm() error {
+// WaitForProm just pings the prometheus endpoint until it gets a code within [200, 300).
+// It selects for that event and an error coming in from d.errChan.
+func (d *CostAnalyzerProm) WaitForProm() error {
 	ticker := time.NewTicker(500 * time.Millisecond)
 	fmt.Println("Waiting for prometheus to be ready...")
 	for {
@@ -59,7 +68,10 @@ func (d *DapaniProm) WaitForProm() error {
 		}
 	}
 }
-func (d *DapaniProm) GetPodCalls(since time.Duration) ([]*PodCall, error) {
+
+// GetPodCalls queries the prometheus API for istio_request_bytes_sum, given a time range.
+// todo take an actual timerange, and not the hacky "since" parameter.
+func (d *CostAnalyzerProm) GetPodCalls(since time.Duration) ([]*PodCall, error) {
 	promApi := v1.NewAPI(d.client)
 	calls := make([]*PodCall, 0)
 	query := "istio_request_bytes_sum{destination_pod!=\"\", destination_pod!=\"unknown\"}"

pricing/aws/pull_aws_rate_prices.go

@@ -21,6 +21,8 @@ This doesn't work for all the regions (for some reason), but it works
 for the major ones, which is good enough for now (?)
 
 Don't use this in prod (please).
+
+Not even going to bother documenting.
 */
 
 var out string