control

README

Supergiant: Kubernetes Orchestration

---

Supergiant empowers developers and administrators through its simplified deployment and management of Kubernetes, in addition to easing the configuration and deployment of Helm charts, taking advantage of Kubernetes' power, flexibility, and abstraction.

Supergiant facilitates clusters on multiple cloud providers, striving for truly agnostic and impartial infrastructure--and it does this with an autoscaling system that cares deeply about efficiency. It asserts through downscaling and resource packing that unutilized infrastructure shouldn't be paid for (and, therefore, shouldn't be running).

Supergiant implements simple practices that abstract load-balancing, application deployment, basic monitoring, node deployment or destruction, and more, on a highly usable UI. Its efficient packing algorithm enables seamless auto-scaling of Kubernetes clusters, minimizing costs while maintaining the resiliency of applications. To dive into top-level concepts, see the documentation.

Features

• Fully compatible with native Kubernetes versions 1.5.7, 1.6.7, 1.7.7, and 1.8.7
• Easy management and deployment of multiple kubes in various configurations
• AWS, DigitalOcean, OpenStack, Packet, GCE, and on-premise kube deployment
• Easy creation of Helm releases, Pods, Services, LoadBalancers, etc.
• Automatic, resource-based node scaling
• Compatibility with multiple hardware architectures
• Role-based Users, Session-based logins, self-signed SSLs, and API tokens
• A clean UI and CLI, both built on top of an API (with importable Go client lib)

Resources

• Supergiant Website
• Top-level concepts
• Tutorials
• Slack Support Channel
• Installation ~ UI Usage ~ API Usage

Community and Contributing

We are grateful for any contribution to the Supergiant project, be it in the form of a GitHub issue, a Pull Request, or any social media engagement. Contributing to Supergiant requires familiarization with the Community and Contribution Guidelines. Please see these links to get started:

• Community Page
• Contribution Guidelines

Development

Setup

Note: These instructions are for setting up a local or custom environment and assume a "beginner" level of experience. For executable binaries, see the Releases Page. Before submitting a Pull Request, please see Community and Contributing above.

1. Install Dependencies:

• Git
• Go - version 1.7+
• govendor
• go-bindata
• npm & Node.js
• Angular - version 5.0+

Note: If a new package is imported and then used in Supergiant code, make sure to vendor the imports (the govendor binary is located in $GOPATH/bin/govendor):

govendor add +external

Note: New to any of these technologies? Here are a few basic, free resources:

• An introduction to Git
• A Golang tutorial playlist
• A guide to using npm
• A guide to Angular 5

2. Fork the Repo

Please make sure to fork the Supergiant project before getting started. Direct Pull Requests will not be accepted into the project.

To make the commands in subsequent steps copy-pastable, feel free to do the folowing:

GITHUB_USERNAME="github_username"

3. Clone the Fork

Clone the repo into a local Go project directory, and add an upstream remote to keep the fork synced:

git clone https://github.com/$GITHUB_USERNAME/supergiant.git $GOPATH/src/github.com/supergiant/supergiant
git remote add upstream https://github.com/supergiant/supergiant.git

Remember to checkout a branch to work on, or create a new branch.

4. Setup a Config File

Note: From now on, all specified directories have a root of $GOPATH/src/github.com/supergiant/.

Copy the example configuration from within ./supergiant/, or [create a custom one](LINK TO DOCS FOR CONFIG) as desired:

cp config/config.json.example config/config.json

5. Compile UI Assets

Run this from within ./supergiant/. It was once used to run the old UI, and, although the old UI is no longer in use, it is necessary to run the backend (the binary for go-bindata is found in $GOPATH/bin/):

go-bindata -pkg bindata -o bindata/bindata.go config/providers/... ui/assets/... ui/views/...

Operation

1. Running the Backend

From within `./supergiant/, run:

go run cmd/server/server.go --config-file config/config.json

The server will output as seen below:

INFO[0000] No Admin detected, creating new and printing credentials:

  ( ͡° ͜ʖ ͡°)  USERNAME: admin  PASSWORD: 0GYB4rIU8TaokNtJ

Note: The initial account login credentials will appear like this the first time that the server runs, and will not appear again. However, anyone with access to Supergiant's initial logs will have access to those credentials, but the credentials can be changed

2. Running the UI

Currently, Supergiant uses a UI developed with Angular 5 and higher. The Angular project directory is found in ./supergiant/cmd/ui/assets. The old UI is accessible on port 8080 when the Supergiant Server is running.

2.a. Install Node Modules

In ./supergiant/cmd/ui/assets, run:

npm install

Note: If the UI fails to initialize, package and dependency problems are often the cause. If there is a problem with the project's current package.json or package-lock.json, please open a GitHub issue.

2.b. Serve the UI

Within ./supergiant/cmd/ui/assets/, run:

ng serve

The UI will be accessible on port 4200 by default. The server must be running to interact properly with the UI.

Building

1. Building the Server

Note: The build processes for both the server binary and Docker image are currently under review.

2. Building the UI

Run ng build to build the project. The build artifacts will be stored in the dist/ directory. Use the -prod flag for a production build.

Note: The build processes for both the UI binary and Docker image are currently under review.

Testing

1. Testing the Server

Currently, tests are split up into two groups: unit tests and integration tests. Unit tests are in ./supergiant/pkg/, and integration tests are in ./supergiant/test.

1.a. Unit Testing

To run unit tests, simply run go test on all of the Supergiant-specific packages within ./supergiant/:

go test -v ./pkg/...

1.b. Integration Testing

Note: Before running integration tests, make sure to set the required environment variables noted in the code for each provider in ./supergiant/test/providers/

For integration tests, Golang build tags are used. This helps with separation of testing concerns. The tag used is // +build integration. Like unit tests, it is easy to run the tests from ./supergiant/:

go test -v -tags=integration ./test/...

2. Testing the UI

1.a. Unit Testing

Run ng test to execute the unit tests with Karma.

1.b. E2E Testing

Run ng e2e to execute the end-to-end tests with Protractor. Before running the tests, make sure to serve the app via ng serve.

License

Copyright 2016 Qbox, Inc., a Delaware corporation. All rights reserved.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.