Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Updated docs #67

Merged
merged 9 commits into from
Nov 30, 2017
Merged

Updated docs #67

Show file tree
Hide file tree
Changes from 8 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
06167e0
Updated README
vikram-bitnami Nov 28, 2017
4178f06
Moved content
vikram-bitnami Nov 28, 2017
ab3762b
Updated file names
vikram-bitnami Nov 28, 2017
4de2a81
Updated get started guide, added images
vikram-bitnami Nov 29, 2017
ad6b228
Updated text
vikram-bitnami Nov 29, 2017
ec6f3ac
Fixed links
vikram-bitnami Nov 29, 2017
0dadc37
Updated text
vikram-bitnami Nov 29, 2017
3d0084a
Added feedback
vikram-bitnami Nov 29, 2017
9d1f980
Fixed typo
vikram-bitnami Nov 29, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
kubeapps
generated
statik
*.*~
115 changes: 57 additions & 58 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,89 +1,88 @@
# Kubeapps
# <img src="./img/logo.png" width="40" align="left"> Kubeapps

[![Build Status](https://travis-ci.org/kubeapps/kubeapps.svg?branch=master)](https://travis-ci.org/kubeapps/kubeapps)

<img src="./img/logo.png" width="100">

Kubeapps is a set of tools written by [Bitnami](https://bitnami.com) to super-charge your Kubernetes cluster with:
* Your own applications [dashboard](https://kubeapps.com/), allowing you to deploy Kubernetes-ready applications into your cluster with a single click.
* [Kubeless](http://kubeless.io/) - a Kubernetes-native Serverless Framework, compatible with [serverless.com](https://serverless.com).
* [SealedSecrets](https://github.com/bitnami/sealed-secrets) - Encrypt your Secret into a SealedSecret, which is safe to store - even to a public repository.
* Your own application [dashboard](https://kubeapps.com/), allowing you to deploy Kubernetes-ready applications into your cluster with a single click.
* [Kubeless](http://kubeless.io/), a Kubernetes-native Serverless Framework, compatible with [serverless.com](https://serverless.com).
* [SealedSecrets](https://github.com/bitnami/sealed-secrets), a way to encrypt a Secret into a SealedSecret, which is safe to store...even for a public repository.

These tools are easily deployed into your cluster with just one command: ```kubeapps up```
## Quickstart

----
Kubeapps assumes a working Kubernetes (v1.7+) with RBAC enabled and [`kubectl`](https://kubernetes.io/docs/tasks/tools/install-kubectl/) installed and configured to talk to your Kubernetes cluster. Kubeapps binaries are available for both Linux and OS X, and Kubeapps has been tested with both `minikube` and Google Kubernetes Engine (GKE).

## Getting started
> On GKE, you must either be an "Owner" or have the "Container Engine Admin" role in order to install Kubeapps.

To get started, read our [Getting Started guide](docs/getting-started.md).
The simplest way to try Kubeapps is to deploy it with the Kubeapps Installer on [minikube](https://github.com/kubernetes/minikube). Assuming you are deploying a binary installer on Linux, here are the commands to run:

You can also browse the [full documentation](docs/).
```
sudo curl -s https://api.github.com/repos/kubeapps/kubeapps/releases/latest | grep linux | grep browser_download_url | cut -d '"' -f 4 | wget -i -
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm using this so the user always gets the latest release, rather than having the command hardcoded to a specific version (so there's less need to update it every time). I got the command from https://gist.github.com/steinwaywhw/a4cd19cda655b8249d908261a62687f8 and tested it, seems to work fine but please also test it yourself.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well, this is about building the latest source. For documentation on how to use, we have the rest of the documents. Please, leave here the documentation on how to build. Also, please, avoid having explicit reference to minikube on the docs.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added back in README, removed minikube commands

sudo mv kubeapps-linux-amd64 /usr/local/bin/kubeapps
chmod +x /usr/local/bin/kubeapps
kubeapps up
kubeapps dashboard
```

----
## Build the Kubeapps installer from source
These commands will deploy Kubeapps in your cluster and launch a browser with the Kubeapps dashboard.

The Kubeapps Installer is a CLI tool written in Go that will deploy all the Kubeapps components into your cluster.
You can build the latest Kubeapps Installer from source.
![Dashboard main page](img/dashboard-home.png)

### Installing Go
- Visit https://golang.org/dl/
- Download the most recent Go version (here we used 1.9) and unpack the file
- Check the installation process on https://golang.org/doc/install
- Set the Go environment variables
To remove Kubeapps form your cluster, simply run:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

s/form/from/


```
export GOROOT=/GoDir/go
export GOPATH=/GoDir/go
export PATH=$GOPATH/bin:$PATH
kubeapps down
```

### Create a working directory for the project
## Build from Source

```
working_dir=$GOPATH/src/github.com/kubeapps/
mkdir -p $working_dir
```
The Kubeapps Installer is a CLI tool written in Go that will deploy the Kubeapps components into your cluster.
You can build the latest Kubeapps Installer from source by following the steps below:

### Clone kubeapps/kubeapps repository
* Visit [the Go website](https://golang.org), download the most recent [binary distribution of Go](https://golang.org/dl/) and install it following the [official instructions](https://golang.org/doc/install).

```
cd $working_dir
git clone https://github.com/kubeapps/kubeapps
```
> The remainder of this section assumes that Go is installed in `/usr/local/go`. Update the paths in subsequent commands if you used a different location.

### Building local binary
* Set the Go environment variables:

```
cd kubeapps
make binary
```
```
export GOROOT=/usr/local/go
export GOPATH=/usr/local/go
export PATH=$GOPATH/bin:$PATH
```

## Testing Kubeapps Installer with minikube
* Create a working directory for the project:

The simplest way to try Kubeapps is deploying it with Kubeapps Installer on [minikube](https://github.com/kubernetes/minikube).
```
working_dir=$GOPATH/src/github.com/kubeapps/
mkdir -p $working_dir
```

Kubeapps Installer is now working with RBAC-enabled Kubernetes (v1.7+). You can choose to start minikube vm with your preferred VM driver (virtualbox xhyve vmwarefusion) and a proper Kubernetes version. For example, the [latest minikube](https://github.com/kubernetes/minikube/releases/tag/v0.23.0) will start a Kubernetes v1.8.0.
* Clone the Kubeapps source repository:

```
minikube start
```
```
cd $working_dir
git clone https://github.com/kubeapps/kubeapps
```

It's also required to have [Kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) installed on your machine. Verify Kubernetes version:
* Build the Kubeapps binary and move it to a location in your path:

```
kubectl version
Client Version: version.Info{Major:"1", Minor:"7", GitVersion:"v1.7.0", GitCommit:"d3ada0119e776222f11ec7945e6d860061339aad", GitTreeState:"clean", BuildDate:"2017-06-29T23:15:59Z", GoVersion:"go1.8.3", Compiler:"gc", Platform:"darwin/amd64"}
Server Version: version.Info{Major:"1", Minor:"8", GitVersion:"v1.8.0", GitCommit:"0b9efaeb34a2fc51ff8e4d34ad9bc6375459c4a4", GitTreeState:"dirty", BuildDate:"2017-10-17T15:09:55Z", GoVersion:"go1.8.3", Compiler:"gc", Platform:"linux/amd64"}
```
```
cd kubeapps
make binary
cp kubeapps /usr/local
```

Deploy Kubeapps with Kubeapps Installer
## Next Steps

```
kubeapps up
```
[Use the Kubeapps Dashboard](docs/dashboard.md) to easily manage the deployments created by Helm in your cluster and to manage your Kubeless functions, or [look under the hood to see what's included in Kubeapps](docs/components.md).

Remove Kubeapps
In case of difficulties installing Kubeapps, find [more detailed installation instructions](docs/install.md).

```
kubeapps down
```
For a more detailed and step-by-step introduction to Kubeapps, read our [introductory walkthrough](docs/getting-started.md).

## Useful Resources

* [Walkthrough for first-time users](docs/getting-started.md)
* [Detailed installation instructions](docs/install.md)
* [Kubeapps Dashboard documentation](docs/dashboard.md)
* [Kubeapps components](docs/components.md)
22 changes: 0 additions & 22 deletions docs/README.md
View file
Open in desktop

This file was deleted.

11 changes: 6 additions & 5 deletions docs/components.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,17 +2,18 @@

## Helm / Tiller

Kubeapps installs Tiller ([Helm](https://helm.sh/) in-cluster component) which will allow you to easily installed Kubernetes ready applications packaged as charts.
Tiller is [Helm](https://helm.sh/)'s in-cluster component that enables easy installation of Kubernetes-ready applications packaged as charts.

## Kubeless

[Kubeless](http://kubeless.io/) is a Kubernetes-native serverless framework. It runs on top of your Kubernetes cluster and allows you to deploy small unit of code without having to build container images. With Kubeless you can build advanced applications that tie together services using functions.
[Kubeless](http://kubeless.io/) is a Kubernetes-native serverless framework. It runs on top of a Kubernetes cluster and allows you to deploy small units of code without having to build container images. With Kubeless, you can build advanced applications that tie together services using functions.

## Kubeapps Dashboard

Kubeapps comes with an in-cluster web dashboard that allows you to easily deploy applications and functions packaged as charts and to create, edit and run Kubeless functions.
Check the [main documentation for the Kubeapps Dashboard](dashboard.md).
Kubeapps comes with an in-cluster web dashboard that allows you easy deployment of applications and functions packaged as charts and to create, edit and run Kubeless functions. [Learn more about the Kubeapps Dashboard](dashboard.md).

## Sealed Secrets

[Sealed Secrets](https://github.com/bitnami/sealed-secrets) are a "one-way" encrypted Secret that can be created by anyone, but can only be decrypted by the controller running in the target cluster. The Sealed Secret is safe to share publicly, upload to git repositories, post to twitter, etc. Once the SealedSecret is safely uploaded to the target Kubernetes cluster, the sealed secrets controller will decrypt it and recover the original Secret.
[Sealed Secrets](https://github.com/bitnami/sealed-secrets) are "one-way" encrypted Secrets that can be created by anyone, but can only be decrypted by the controller running in the target cluster. A Sealed Secret is safe to share publicly, upload to Git repositories, post to Twitter, etc. Once the SealedSecret is safely uploaded to the target Kubernetes cluster, the Sealed Secrets controller will decrypt it and recover the original Secret.

For more information, check the [latest version of the Kubernetes manifest](https://github.com/kubeapps/kubeapps/blob/master/static/kubeapps-objs.yaml) that Kubeapps will deploy for you.
82 changes: 45 additions & 37 deletions docs/dashboard.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,79 +4,87 @@ Kubeapps comes with an in-cluster dashboard that offers a web UI to easily manag

## Start the Dashboard

You can securely access the dashboard from your system by running:
Securely access the Kubeapps Dashboard from your system by running:

```
kubeapps dashboard
```

This will run a HTTP proxy to access the dashboard securely and will open your default browser to it.
This will start an HTTP proxy for secure access to the Kubeapps Dashboard and will launch your default browser to access it. Here's what you should see:

## Managing Charts
### Deploying new applications using the Dashboard
![Dashboard main page](../img/dashboard-home.png)

Once you have the Dashboard up and running, you can start deploying applications into your cluster.
The following sections walk you through some common tasks with the Kubeapps Dashboard.

![Dashboard Main Page](../img/dashboard.png)
## Work with Charts

Select one application from the list of charts in the official Kubernetes chart repository. In this example we will be deploying MariaDB.
### Deploy new applications using the Dashboard

![Dashboard MariaDB chart](../img/mariadb.png)
Once you have the Kubeapps Dashboard up and running, you can start deploying applications into your cluster.

Once you click on "Install mariadb" you will be able to select which namespace of your cluster you want this to be deployed:
* Start with the Dashboard welcome page:

![Dashboard Select Namespace](../img/namespace.png)
![Dashboard main page](../img/dashboard-home.png)

Now click on "Deploy" and you will be able to track your new Kubernetes Deployment directly from your browser.
* Use the "Charts" menu to select an application from the list of charts in the official Kubernetes chart repository. This example assumes you want to deploy MariaDB.

![Dashboard MariaDB deployment](../img/mariadb-deploy.png)
![MariaDB chart](../img/mariadb-install.png)

### Listing all the deployments managed by Helm
* Click the "Install" button. You will be prompted for the cluster namespace in which the application should be deployed.

On the "Deployments" menu you can get a list of the deployments in your cluster that are managed by Helm.
![Namespace selection](../img/mariadb-namespace.png)

![Dashboard Deployments list](../img/deployments.png)
* Click the "Deploy" button. The application will be deployed. You will be able to track the new Kubernetes deployment directly from the browser. The "Notes" section of the deployment page contains important information to help you use the application.

### Removing existing deployments
![MariaDB deployment](../img/mariadb-deployment.png)

You can remove any of the deployments that are managed by Helm, by clicking on the "Remove" button:
### List all the deployments managed by Helm

![Dashboard Remove Deployment](../img/delete-mariadb.png)
The "Deployments" menu displays a list of the deployments in the cluster that are managed by Helm.

### Adding addition charts repositories
![Deployment list](../img/dashboard-deployments.png)

By default, Kubeapps comes with the official Kubernetes chart repositories enabled. You can see the list of enabled chart repositories in the "Repositories" link:
### Remove existing deployments

![Dashboard Repositories List](../img/dashboard-repos.png)
You can remove any of the deployments that are managed by Helm by clicking the "Remove" button on a deployment detail page:

You can add new repositories (i.e. a special repository for your organization) by clicking on "Add repository":
![Deployment removal](../img/dashboard-delete-deployment.png)

![Dashboard Add Repository](../img/dashboard-add-repo.png)
### Add more chart repositories

- For ```Name``` you can add any identifier, as long as it is unique. Right now only alpha characters are accepted.
- For ```URL``` you should add the URL where the ```index.yaml``` file of your repository is available.
- For ```Source``` you can add the URL of the source code for your charts. This field is optional.
By default, Kubeapps comes with the official Kubernetes chart repositories enabled. You can see the list of enabled chart repositories in the "Repositories" menu:

## Functions Dashboard
![Repositories List](../img/dashboard-repos.png)

The Kubeapps Dashboard includes a [Kubeless](https://kubeless.io) UI to be able to create, edit and run your Kubeless functions directly from your browser.
Add new repositories (for example, your organization's chart repository) by clicking the "Add repository" button. Fill the "Add Repository" form using the guidelines below:

To access the Kubeless UI click on "Functions" in the Dashboard menu.
* Name: Use any unique identifier. Currently, only alphabetic characters are accepted.
* URL: Add the URL to the ```index.yaml``` file of the repository.
* Source: Add the URL to the source code for your charts. This field is optional.

![Kubeless UI](../img/kubeless-ui.png)
![Adding repository](../img/dashboard-add-repo.png)

## Work with Functions

The Kubeapps Dashboard includes a [Kubeless](https://kubeless.io) interface to be able to create, edit and run your Kubeless functions directly from your browser.

### Create a new function

To create a new Kubeless function from the web UI click on "Create Function". On the modal window that opens, select the runtime for your function, the name of the function object and the handler of your function:
To create a new Kubeless function from the Dashboard:

* Start with the "Functions" menu in the Dashboard.

![Kubeless interface](../img/dashboard-functions.png)

![Kubeless Create Function Modal](../img/kubeless-create.png)
* Click the "Create Function" button.
* In the resulting modal dialog, select the runtime for the function, the name of the function object and the handler for the function:

After clicking on create, Kubeless UI will load a sample function, so you can easily modify it for your needs:
![Kubeless function creation](../img/kubeless-create.png)

![Kubeless Hello World Function](../img/kubeless-hello.png)
* Click the "Create" button. The Kubeless interface will load a sample function, so you can easily modify it for your needs. Here's a simple "hello world" function example:

Clicking on "Run Function" will run your function using the selected runtime and will display the response of it. It may take some time to the function to be running.
![Kubeless Hello World function](../img/kubeless-hello.png)

### Beyond Hello World
* Clicking "Run Function" will run the function using the selected runtime and will display the response. It may take some time to the function to complete execution.

You can find many function examples for the different runtimes in the [examples folder in the Kubeless repository](https://github.com/kubeless/kubeless/tree/master/examples).
For more examples of functions using different runtimes, check out the [examples in the Kubeless repository](https://github.com/kubeless/kubeless/tree/master/examples).
Loading