control

README

SUPERGIANT: Easy container orchestration using Kubernetes

---

---

Supergiant is an open-source container orchestration system that lets developers easily deploy and manage apps as Docker containers using Kubernetes.

We want to make Supergiant the easiest way to run Kubernetes in the cloud.

Quick start...

• How to Install Supergiant Container Orchestration Engine on AWS EC2
• Deploy a MongoDB Replica Set with Docker and Supergiant

---

Features

• Lets you manage microservices with Docker containers
• Lets you manage multiple users (OAUTH and LDAP coming soon)
• Web dashboard served over HTTPS/SSL by default
• Manages hardware like one, big self-healing resource pool
• Lets you easily scale stateful services and HA volumes on the fly
• Lowers costs by auto-scaling hardware when needed
• Lets you easily adjust RAM and CPU min and max values independently for each service
• Manages hardware topology organically within configurable constraints

Resources

• Supergiant Website
• Docs
• Tutorials
• Slack
• Install

Installation

The current release installs on Amazon Web Services EC2, using a publicly-available AMI. Other cloud providers and local installation are in development.

If you want to install Supergiant, follow the Supergiant Install Tutorial.

Top-Level Concepts

Supergiant makes it easy to run Dockerized apps as services in the cloud by abstracting Kubernetes resources. It doesn’t obscure Kubernetes in any way -- in fact you could simply use Supergiant to install Kubernetes.

Supergiant abstracts Kubernetes and cloud provider services into a few easily-managed resources, namely:

• Apps are what groups Components into Kubernetes Namespaces. An App is how to organize some collection of (micro)services in an environment, such as "my-app-production.”Organization is flexible and up to the user.

• Entrypoints allow Components to be reached through a public, internet-facing address. They are how Supergiant handles external load balancing. Kubernetes handles internal load balancing among containers brilliantly, so we use Entrypoints as a more efficient system for external load balancing among Nodes.

• A Component is child of an App and is synonymous with microservice; in that, a Component should ideally have one role or responsibility within an App. As a basic example: within an App named "wordpress-production", there might be two Components named "mysql" and "wordpress".

• A Release is a configuration of a Component, released at a certain time. Releases can be verbose, as they represent an entire topology of a Component, it’s storage volumes, its min and max allocated resources, etc. By managing Docker instances as Releases, HA storage volumes can be attached and reattached without losing statefulness.

Supergiant makes use of the Swagger API framework for documenting all resources. See the full Supergiant API documentation for the full reference.

• Supergiant Swagger API reference

Micro-Roadmap

Currently, the core team is working on the following:

• Add LDAP and OAUTH user authentication
• Add support for additional cloud providers
• Add support for local installations

Community and Contributing

We are very grateful of any contribution.

All Supergiant projects require familiarization with our Community and our Contribution Guidelines. Please see these links to get started.

• Community Page
• Contribution Guidelines

Development

If you would like to contribute changes to Supergiant, first see the pages in the section above, Community and Contributing.

Note: Supergiant cloud installers have dependencies pre-installed and configured and will generate a self-signed cert based on the server hostname. These instructions are for setting up a local or custom environment.

Supergiant dependencies:

• Git
• Go version 1.7 or more recent
• Govendor for running tests
• Supergiant as a Go package
• A certificate signing request file for serving over HTTPS

If you are missing any of these, see below to install or generate dependencies.

From the supergiant Go package folder (usually ~/.go/src/github.com/supergiant/supergiant) perform the following:

Initialize Config File

In config/config.json.example, there's a sample config file to get you started. Just duplicate and rename to config.json. Examples below assume the default configuration for localhost development.

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

Create an Admin User

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

Run Supergiant

go run main.go --config-file config/config.json

The default configuration expects HTTP requests on port 8080 and HTTPS requests on port 8081. These may be changed in config/config.json. Visiting http://localhost:8080/ will produce an insecure warning page by design.

Access the dashboard at https://localhost:8081/ui/ with the generated Admin username and password.

Run Tests

govendor test +local

Compiling UI templates and static assets

Supergiant uses go-bindata to compile assets directly into the code. You will need to run this command if you're making changes to the UI:

go-bindata -pkg ui -o pkg/ui/generated_assets.go ui/...

And this, if you're working with provider code:

PROVIDER=aws # whichever you're working with
go-bindata -pkg $PROVIDER -o pkg/provider/$PROVIDER/generated_assets.go config/providers/$PROVIDER/...

---

Installing/Generating Dependencies

How to Install Supergiant as a Go Package

go get github.com/supergiant/supergiant

This will install supergiant in your Go workspace package directory (usually something like ~/.go/src/github.com/supergiant/supergiant). Packages in this directory function like Git repositories that are aware of their upstream origin. From here, you can create your own branches and even checkout branches under development.

How to Generate a Certificate Signing Request File

You will need local RSA .key and .pem files. The default locations are in the Supergiant Go package tmp folder (usually ~/.go/src/github.com/supergiant/supergiant) as tmp/supergiant.key, tmp/supergiant.pem. If you wish to customize these locations, you will need to edit config/config.json. The following steps require no config editing.

Set the following env session variables:

SSL_KEY_FILE=tmp/supergiant.key
SSL_CRT_FILE=tmp/supergiant.pem

Generate the .key file

openssl genrsa -out $SSL_KEY_FILE 2048

Generate the CSR file. This step will ask you a few questions about the computer you are using to generate the file.

When you are asked to enter Common Name (e.g. server FQDN or YOUR name), enter localhost. This may be customized in config/config.json.

openssl req -new -x509 -sha256 -key $SSL_KEY_FILE -out $SSL_CRT_FILE -days 3650

---

License

This software is licensed under the Apache License, version 2 ("ALv2"), quoted below.

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.