airshipui/DevelopersGuide.md

Octant Airship UI Plugin Developer's Guide

Step by step installation of the Airship UI

1. This installation requires a working kubernetes or minikube (single node) installation including the kubectl command.
2. Install Go v1.13 or newer
3. Install Octant
4. Install Argo CLI
5. Install Argo UI
6. Clone the AirshipUI repository and build the Airship UI plugin

   git clone https://opendev.org/airship/airshipui
   cd airshipui
   make build install-plugins
   

   Example output:

   $ make build install-plugins
   go build -o bin/airshipui -ldflags='-X opendev.org/airship/airshipui/internal/environment.version=7274339' cmd/airshipui/main.go
   go build -o bin/argoui -ldflags='-X opendev.org/airship/airshipui/internal/environment.version=7274339' cmd/argoui/main.go
   cp bin/argoui ~/.config/octant/plugins
   

7. Start Airship UI with the airship/bin/airshipui command

   $ bin/airshipui
   2020-01-09T13:52:14.260-0800    INFO    module/manager.go:79    registering action      {"component": "module-manager", "actionPath": "deployment/configuration", "module-name": "overview"}
   2020-01-09T13:52:14.261-0800    INFO    module/manager.go:79    registering action      {"component": "module-manager", "actionPath": "overview/containerEditor", "module-name": "overview"}
   2020-01-09T13:52:14.261-0800    INFO    module/manager.go:79    registering action      {"component": "module-manager", "actionPath": "overview/serviceEditor", "module-name": "overview"}
   2020-01-09T13:52:14.261-0800    INFO    module/manager.go:79    registering action      {"component": "module-manager", "actionPath": "octant/deleteObject", "module-name": "configuration"}
   2020-01-09T13:52:14.282-0800    INFO    plugin/manager.go:397   registered plugin "argoui"      {"plugin-name": "argoui", "cmd": "/home/gary/.config/octant/plugins/argoui", "metadata": {"Name":"argoui","Description":"Argo UI version 7274339","Capabilities":{"IsModule":true}}}
   2020-01-09T13:52:14.282-0800    INFO    plugin/manager.go:405   plugin supports navigation      {"plugin-name": "argoui"}
   2020-01-09T13:52:14.308-0800    INFO    plugin/manager.go:397   registered plugin "plugin-name" {"plugin-name": "octant-sample-plugin", "cmd": "/home/gary/.config/octant/plugins/octant-sample-plugin", "metadata": {"Name":"plugin-name","Description":"a description","Capabilities":{"SupportsPrinterConfig":[{"Group":"","Version":"v1","Kind":"Pod"}],"SupportsTab":[{"Group":"","Version":"v1","Kind":"Pod"}],"IsModule":true}}}
   2020-01-09T13:52:14.308-0800    INFO    plugin/manager.go:405   plugin supports navigation      {"plugin-name": "octant-sample-plugin"}
   2020-01-09T13:52:14.309-0800    INFO    dash/dash.go:381        Using embedded Octant frontend
   2020-01-09T13:52:14.315-0800    INFO    dash/dash.go:360        Dashboard is available at http://127.0.0.1:7777
   

8. If you're unable to open a browser on the machine running the Airship UI you can tunnel the connection over ssh and use a browser on your local machine

   ssh -L 7777:localhost:7777 -L 8001:localhost:8001 <id>@<remote_host>
   

9. The Argo UI should be available at http://127.0.0.1:7777/#/argo-ui

Working with the Airship UI

Airship UI utilizes the Octant plugin to drive some of the functionality. Octant has a plugin sample which is the basis of these instructions.

Write a hello world plugin of your very own

1. Clone the Airship UI repository (if not already done previously)

   git clone https://opendev.org/airship/airshipui
   

2. cd airshipui

3. Make a hello-world package under the cmd sub folder to contain your code

   mkdir cmd/hello-world
   

4. Create / edit main.go under the cmd/hello-world directory. This is modeled off the Octant sample plugin

   package main
   
   import (
   	"log"
   
   	"github.com/vmware-tanzu/octant/pkg/navigation"
   	"github.com/vmware-tanzu/octant/pkg/plugin"
   	"github.com/vmware-tanzu/octant/pkg/plugin/service"
   	"github.com/vmware-tanzu/octant/pkg/view/component"
   )
   
   var pluginName = "hello-world"
   
   // This is a sample plugin showing the features of Octant's plugin API.
   func main() {
   	// Remove the prefix from the go logger since Octant will print logs with timestamps.
   	log.SetPrefix("")
   
   	// Tell Octant to call this plugin when printing configuration or tabs for Pods
   	capabilities := &plugin.Capabilities{
   		IsModule: true,
   	}
   
   	// Set up what should happen when Octant calls this plugin.
   	options := []service.PluginOption{
   		service.WithNavigation(handleNavigation, initRoutes),
   	}
   
   	// Use the plugin service helper to register this plugin.
   	p, err := service.Register(pluginName, "The very smallest thing you can do", capabilities, options...)
   	if err != nil {
   		log.Fatal(err)
   	}
   
   	// The plugin can log and the log messages will show up in Octant.
   	log.Printf("hello-world-plugin is starting")
   	p.Serve()
   }
   
   // handleNavigation controls what is displayed on the navigation pane
   func handleNavigation(request *service.NavigationRequest) (navigation.Navigation, error) {
   	return navigation.Navigation{
   		Title:    "Hello World Plugin",
   		Path:     request.GeneratePath(),
   		IconName: "folder",
   	}, nil
   }
   
   // initRoutes routes for this plugin. In this example, there is a global catch all route
   // that will return the content for every single path.
   func initRoutes(router *service.Router) {
   	router.HandleFunc("*", func(request *service.Request) (component.ContentResponse, error) {
   		contentResponse := component.NewContentResponse(component.TitleFromString("Hello World Title"))
   		helloWorld := component.NewText("Hello World just some text on the page")
   		contentResponse.Add(helloWorld)
           // NOTE: this will print out messages only if the -v is added to the start of octent or airship
           log.Printf("Sample debugging message: %v\n", helloWorld)
   		return *contentResponse, nil
   	})
   }
   

5. Build the hello-world plugin

   Build the single plugin

   go build -o ~/.config/octant/plugins/hello-world-plugin cmd/hello-world/main.go
   

   Or build all by issuing a make command. Example output:

   $ make
   go build -o bin/airshipui -ldflags='-X opendev.org/airship/airshipui/internal/environment.version=7274339' cmd/airshipui/main.go
   go build -o bin/hello-world -ldflags='-X opendev.org/airship/airshipui/internal/environment.version=7274339' cmd/hello-world/main.go
   go build -o bin/argoui -ldflags='-X opendev.org/airship/airshipui/internal/environment.version=7274339' cmd/argoui/main.go
   

6. Restart the airshipgui with the -v flag so you can see the debug output (~/airshipui/bin/airshipui -v). Open your browser to http://127.0.0.1:7777/#/configuration/plugins to make sure the hello-world plugin showed up. You will see example of the debug message added to the initRoutes function in the log:

   2020-01-15T19:00:11.530Z        DEBUG   hello-world-plugin      plugin/logger.go:33     2020/01/15 19:00:11 Sample debugging message: Hello World just some text on the page
   

7. You should be able to explore the basic plugin functionality by clicking on it in the navigation pane.

8. You can add other components for fun from the Octant documentation for further enhancement to the page

Appendix

Minikube

Minikube runs a single-node Kubernetes cluster for users looking to try out Kubernetes or develop with it day-to-day. Installation instructions are available on the kubernetes website: https://kubernetes.io/docs/tasks/tools/install-minikube/). If you are running behind a proxy it may be necessary to follow the steps outlined in the How to use an HTTP/HTTPS proxy with minikube website.

Optional proxy settings

Environment settings for wget or curl

If your network has a proxy that prevents successful curls or wgets you may need to set the proxy environment variables. The local ip is included in the no_proxy setting to prevent any local running process that may attempt api calls against it from being sent through the proxy for the request:

```
export http_proxy=<proxy_host>:<proxy_port>
export HTTP_PROXY=<proxy_host>:<proxy_port>
export https_proxy=<proxy_host>:<proxy_port>
export HTTPS_PROXY=<proxy_host>:<proxy_port>
export no_proxy=localhost,127.0.0.1,<LOCAL_IP>
export NO_PROXY=localhost,127.0.0.1,<LOCAL_IP>
```