Working with the Kubernetes UI

This document explains how to work with the Kubernetes UI. For information on how to access and use it, see docs/ui.md.

Installing dependencies

There are two kinds of dependencies in the UI project: tools and frameworks. The tools help us manage and test the application. They are not part of the application. The frameworks, on the other hand, become part of the application, as described below.

We get the tools via npm, the node package manager.
We get the frameworks via bower, a client-side package manager.

Before you build the application for the first time, run this command from the master directory:

npm install

It creates a new directory, master/node_modules, which contains the tool dependencies.

Building and serving the app

Building the app for development

To build the application for development, run this command from the master directory:

npm start

It runs bower install to install and/or update the framework dependencies, and then gulp, a JavaScript build system, to generate a development version of the application.

Bower creates a new directory, third_party/ui/bower_components, which contains the framework dependencies. Each of them should be referenced in one of the vendor.json files below:

master/vendor.base.json - 3rd party vendor javascript files required to start the app. All of the dependencies referenced by this file are compiled into base.js and loaded before app.js.
master/vendor.json - 3rd party vendor js or css files required to make the app work, usually by lazy loading. All of the dependencies referenced by this file are compiled into app/vendor. (Note: some framework dependencies have been hand edited and checked into source control under master/shared/vendor.)

The default gulp target builds the application for development (e.g., without uglification of js files or minification of css files), and then starts a file watcher that rebuilds the generated files every time the source files are updated. (Note: the file watcher does not support adding or deleting files. It must be stopped and restarted to pick up additions or deletions).

The app directory and its contents are generated by the build. All of the other files are source or project files, such as tests, scripts, documentation and package manifests. (Note: the build output checked into source control is the production version, built with uglification and minification, as described below, so expect the build output to change if you build for development.)

Serving the app during development

For development you can serve the files locally by installing a web server as follows:

sudo npm install -g http-server

The server can then be launched from the app directory as follows:

cd app
http-server -a localhost -p 8001

http-server is convenient, since we're already using npm, but any web server hosting the app directory should work.

Note that you'll need to tell the application where to find the api server by setting the value of the k8sApiServer configuration parameter in master/shared/config/development.json and then rebuilding the application. For example, for a cluster running locally at localhost:8080, as described here, you'll want to set it as follows:

"k8sApiServer": "http://localhost:8080/api/v1beta3"

Building the app for production

To build the application for production, run this command from the master directory:

npm run build

Like npm start, it runs bower install to install and/or update the framework dependencies, but then it runs gulp build to generate a production version of the application. The build target builds the application for production (e.g., with uglification of js files and minification of css files), and does not run a file watcher, so that it can be used in automated build environments.

Serving the app in production

The app is served in production by kube-apiserver at:

https://<kubernetes-master>/ui/

which redirects to:

https://<kubernetes-master>/api/v1/proxy/namespaces/kube-system/services/kube-ui/

Configuration

Configuration settings

A json file can be used by gulp to automatically create angular constants. This is useful for setting per environment variables such as api endpoints.

master/shared/config/development.json and master/shared/config/production.json are used for application wide configuration in development and production, respectively.

master/shared/config/production.json is kept under source control with default values for production.
master/shared/config/development.json is not kept under source control. Each developer can create a local version of the file by copy, paste and rename from master/shared/config/development.example.json, which is kept under source control with default values for development.

The configuration files for the current build environment are compiled into the intermediary master/shared/config/generated-config.js, which is then compiled into app.js.

Component configuration added to master/components/<component name>/config/<environment>.json is combined with the application wide configuration during the build.

The generated angular constant is named ENV. The shared configuration and component configurations each generate a nested object within it. For example:

master
├── shared/config/development.json
└── components
    ├── dashboard/config/development.json
    └── my_component/config/development.json

generates the following in master/shared/config/generated-config.js:

angular.module('kubernetesApp.config', [])
.constant('ENV', {
  '/': <master/shared/config/development.json>,
  'dashboard': <master/components/dashboard/config/development.json>,
  'my_component': <master/components/my_component/config/development.json>
});

Kubernetes server configuration

RECOMMENDED: The Kubernetes api server does not enable CORS by default, so kube-apiserver must be started with --cors_allowed_origins=http://<your host here> or --cors_allowed_origins=.*.

NOT RECOMMENDED: If you don't want to/cannot restart the Kubernetes api server, you can start your browser with web security disabled. For example, you can launch Chrome with flag --disable-web-security. Be careful not to visit untrusted web sites when running your browser in this mode.

Building a new visualizer or component

See master/components/README.md.

Testing

Currently, the UI project includes both unit-testing with Karma and end-to-end testing with Protractor.

Unit testing with Karma

To run the existing Karma tests:

Install the Karma CLI (Note: it needs to be installed globally, so the sudo below may be needed. The other Karma packages, such as karma, karma-jasmine, and karma-chrome-launcher, should be installed automatically by the build).

sudo npm install -g karma-cli

Edit the Karma configuration in master/karma.config.js, if necessary.
Run the tests. The console should show the test results.

cd master
karma start karma.conf.js

To run new Karma tests for a component, put new *.spec.js files under the appropriate master/components/**/test/modules/* directories.

To test the chrome, put new *.spec.js files under the appropriate master/test/modules/* directories.

End-to-end testing with Protractor

To run the existing Protractor tests:

Install the CLIs.

sudo npm install -g protractor

Edit the test configuration in master/protractor/conf.js, if necessary.
Start the webdriver server.

sudo webdriver-manager start

Start the application (see instructions above), running at port 8000.
Run the tests. The console should show the test results.

cd master/protractor
protractor conf.js

To run new protractor tests for a component, put new *.spec.js files in the appropriate master/components/**/protractor/* directories.

To test the chrome, put new *.spec.js files under the master/protractor/chrome directory.

mikedanese/kube-ui