-
Notifications
You must be signed in to change notification settings - Fork 705
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
update user documentation for using Helm chart (#449)
* update README for Helm chart installation instructions * add chart documentation * fix incorrect ingress.annotations default value * link to chart readme for installation instructions * update getting started docs for helm chart * don't manually format lines * fix bitnami chart repo url * move installation instructions link up in readme * link for more detailed instructions * add kubeapps CLI migration notice
- Loading branch information
Showing
6 changed files
with
175 additions
and
103 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,142 @@ | ||
| # <img src="https://github.com/kubeapps/kubeapps/raw/master/docs/img/logo.png" width="40" align="left"> Kubeapps | ||
|
|
||
| [](https://travis-ci.org/kubeapps/kubeapps) | ||
|
|
||
| [Kubeapps](https://kubeapps.com) is a web-based UI for deploying and managing applications in Kubernetes clusters. Kubeapps allows you to: | ||
|
|
||
| - Browse and deploy [Helm](https://github.com/helm/helm) charts from chart repositories | ||
| - Inspect, upgrade and delete Helm-based applications installed in the cluster | ||
| - Add custom and private chart repositories (supports [ChartMuseum](https://github.com/helm/chartmuseum) and [JFrog Artifactory](https://www.jfrog.com/confluence/display/RTF/Helm+Chart+Repositories)) | ||
| - Browse and provision external services from the [Service Catalog](https://github.com/kubernetes-incubator/service-catalog) and available Service Brokers | ||
| - Connect Helm-based applications to external services with Service Catalog Bindings | ||
| - Secure authentication and authorization based on Kubernetes [Role-Based Access Control](docs/user/access-control.md) | ||
|
|
||
| ## TL;DR; | ||
|
|
||
| ```bash | ||
| helm repo add bitnami https://charts.bitnami.com/bitnami | ||
| helm install --name kubeapps --namespace kubeapps bitnami/kubeapps | ||
| ``` | ||
|
|
||
| ## Introduction | ||
|
|
||
| This chart bootstraps a [Kubeapps](https://kubeapps.com) deployment on a [Kubernetes](http://kubernetes.io) cluster using the [Helm](https://helm.sh) package manager. | ||
|
|
||
| It also packages the [Bitnami MongoDB chart](https://github.com/helm/charts/tree/master/stable/mongodb) which is required for bootstrapping a MongoDB deployment for the database requirements of the Kubeapps application. | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| - Kubernetes 1.8+ (tested with Azure Kubernetes Service, Google Kubernetes Engine, minikube and Docker for Desktop Kubernetes) | ||
| - Helm 2.9.1+ | ||
| - PV provisioner support in the underlying infrastructure | ||
| - Administrative access to the cluster to create and update RBAC ClusterRoles | ||
|
|
||
| ## Installing the Chart | ||
|
|
||
| To install the chart with the release name `kubeapps`: | ||
|
|
||
| ```console | ||
| $ helm repo add bitnami https://charts.bitnami.com/bitnami | ||
| $ helm install --name kubeapps --namespace kubeapps bitnami/kubeapps | ||
| ``` | ||
|
|
||
| The command deploys Kubeapps on the Kubernetes cluster in the `kubeapps` namespace. The [configuration](#configuration) section lists the parameters that can be configured during installation. | ||
|
|
||
| > **Tip**: List all releases using `helm list` | ||
| ## Upgrading Kubeapps | ||
|
|
||
| To upgrade Kubeapps, first ensure you have the updated your local chart repository cache: | ||
|
|
||
| ```console | ||
| $ helm repo update | ||
| ``` | ||
|
|
||
| Now upgrade Kubeapps: | ||
|
|
||
| ```console | ||
| $ export RELEASE_NAME=kubeapps | ||
| $ export NAMESPACE=kubeapps | ||
| $ export MONGODB_ROOT_PASSWORD=$(kubectl get secret --namespace $NAMESPACE $RELEASE_NAME-mongodb -o jsonpath="{.data.mongodb-root-password}" | base64 --decode) | ||
| $ helm upgrade $RELEASE_NAME bitnami/kubeapps --set mongodb.mongodbRootPassword=$MONGODB_ROOT_PASSWORD | ||
| ``` | ||
|
|
||
| The above commands ensure the MongoDB password is set to the existing password and not regenerated by the chart. | ||
|
|
||
| ## Uninstalling Kubeapps | ||
|
|
||
| To uninstall/delete the `kubeapps` deployment: | ||
|
|
||
| ```console | ||
| $ helm delete --purge kubeapps | ||
| ``` | ||
|
|
||
| The command removes all the Kubernetes components associated with the chart and deletes the release. | ||
|
|
||
| ## Configuration | ||
|
|
||
| For a full list of configuration parameters of the Kubeapps chart, see the [values.yaml](values.yaml) file. | ||
|
|
||
| Specify each parameter using the `--set key=value[,key=value]` argument to `helm install`. For example, | ||
|
|
||
| ```console | ||
| $ helm install --name kubeapps --namespace kubeapps \ | ||
| --set chartsvc.service.port=9090 \ | ||
| bitnami/kubeapps | ||
| ``` | ||
|
|
||
| The above command sets the port for the chartsvc Service to 9090. | ||
|
|
||
| Alternatively, a YAML file that specifies the values for parameters can be provided while installing the chart. For example, | ||
|
|
||
| ```console | ||
| $ helm install --name kubeapps --namespace kubeapps -f custom-values.yaml bitnami/kubeapps | ||
| ``` | ||
|
|
||
| ### Configuring Initial Repositories | ||
|
|
||
| By default, Kubeapps will track the [community Helm charts](https://github.com/helm/charts) and the [Kubernetes Service Catalog charts](https://github.com/kubernetes-incubator/service-catalog). To change these defaults, override the `apprepository.initialRepos` object: | ||
|
|
||
| ```console | ||
| $ cat > custom-values.yaml <<EOF | ||
| apprepository: | ||
| initialRepos: | ||
| - name: example | ||
| url: https://charts.example.com | ||
| EOF | ||
| $ helm install --name kubeapps --namespace kubeapps bitnami/kubeapps -f custom-values.yaml | ||
| ``` | ||
|
|
||
| ### Exposing Externally | ||
|
|
||
| #### LoadBalancer Service | ||
|
|
||
| The simplest way to expose the Kubeapps Dashboard is to assign a LoadBalancer type to the Kubeapps frontend Service. For example: | ||
|
|
||
| ```console | ||
| $ helm install --name kubeapps --namespace kubeapps bitnami/kubeapps --set frontend.service.type=LoadBalancer | ||
| ``` | ||
|
|
||
| Wait for your cluster to assign a LoadBalancer IP or Hostname to the `kubeapps` Service and access it on that address: | ||
|
|
||
| ```console | ||
| $ kubectl get services --namespace kubeapps --watch | ||
| ``` | ||
|
|
||
| #### Ingress | ||
|
|
||
| This chart provides support for ingress resources. If you have an ingress controller installed on your cluster, such as [nginx-ingress](https://hub.kubeapps.com/charts/stable/nginx-ingress) or [traefik](https://hub.kubeapps.com/charts/stable/traefik) you can utilize the ingress controller to expose Kubeapps. | ||
|
|
||
| To enable ingress integration, please set `ingress.enabled` to `true` | ||
|
|
||
| ##### Hosts | ||
|
|
||
| Most likely you will only want to have one hostname that maps to this Kubeapps installation, however, it is possible to have more than one host. To facilitate this, the `ingress.hosts` object is an array. | ||
|
|
||
| ##### Annotations | ||
|
|
||
| For annotations, please see [this document](https://github.com/kubernetes/ingress-nginx/blob/master/docs/annotations.md). Not all annotations are supported by all ingress controllers, but this document does a good job of indicating which annotation is supported by many popular ingress controllers. Annotations can be set using `ingress.annotations`. | ||
|
|
||
| ##### TLS | ||
|
|
||
| TLS can be configured using the `ingress.tls` object in the same format that the Kubernetes Ingress requests. Please see [this example](https://github.com/kubernetes/contrib/tree/master/ingress/controllers/nginx/examples/tls) for more information. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,57 +1,3 @@ | ||
| # Installation | ||
|
|
||
| Kubeapps assumes a working Kubernetes cluster (v1.8+) and [`kubectl`](https://kubernetes.io/docs/tasks/tools/install-kubectl/) installed and configured to talk to your Kubernetes cluster. Kubeapps binaries are available for Linux, OS X and Windows, and Kubeapps has been tested with Azure Kubernetes Service (AKS), Google Kubernetes Engine (GKE), `minikube` and Docker for Desktop Kubernetes. Kubeapps works on RBAC-enabled clusters and this configuration is encouraged for a more secure install. | ||
|
|
||
| > On GKE, you must either be an "Owner" or have the "Container Engine Admin" role in order to install Kubeapps. | ||
| ## Install pre-built binary | ||
|
|
||
| * Download a binary version of the latest Kubeapps Installer for your platform from the [release page](https://github.com/kubeapps/kubeapps/releases). Currently, the Kubeapps Installer is distributed in binary form for Linux, OS X and Windows (64-bit). | ||
| * Make the binary executable. | ||
|
|
||
| For example, to install the latest binary release on Linux or OS X, use this command: | ||
|
|
||
| ``` | ||
| curl -s https://api.github.com/repos/kubeapps/kubeapps/releases/latest | grep -i $(uname -s) | grep browser_download_url | cut -d '"' -f 4 | wget -i - | ||
| sudo mv kubeapps-$(uname -s| tr '[:upper:]' '[:lower:]')-amd64 /usr/local/bin/kubeapps | ||
| sudo chmod +x /usr/local/bin/kubeapps | ||
| ``` | ||
|
|
||
| ## Build binary from source | ||
|
|
||
| Please refer to the [Kubeapps Build Guide](../developer/build.md) for instructions on setting up the build environment and building Kubeapps from source. | ||
|
|
||
| # Next Steps | ||
|
|
||
| Confirm that [`kubectl`](https://kubernetes.io/docs/tasks/tools/install-kubectl/) is installed and verify the Kubernetes version: | ||
|
|
||
| ``` | ||
| 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"} | ||
| ``` | ||
|
|
||
| Use the Kubeapps Installer to deploy Kubeapps and launch a browser with the Kubeapps dashboard. | ||
|
|
||
| ``` | ||
| kubeapps up | ||
| kubeapps dashboard | ||
| ``` | ||
|
|
||
| To remove Kubeapps, use this command: | ||
|
|
||
| ``` | ||
| kubeapps down | ||
| ``` | ||
|
|
||
| # Exposing Externally | ||
|
|
||
| The main Kubernetes Service used to access Kubeapps is the `kubeapps` Service in the `kubeapps` namespace. To expose the dashboard for external access, you should setup an Ingress resource to point to the `kubeapps` Service and use an [Ingress Controller](https://kubernetes.io/docs/concepts/services-networking/ingress/#ingress-controllers) to expose it. | ||
|
|
||
| An alternative way is to edit the `kubeapps` Service and change it's type from `ClusterIP` to `LoadBalancer`, if your cloud platform supports provisioning LoadBalancer IPs or Hostnames for Services. This solution is not recommended as updates to Kubeapps will likely revert the Service back to a `ClusterIP` type. | ||
|
|
||
| # Useful Resources | ||
|
|
||
| * [Walkthrough for new users](getting-started.md) | ||
| * [Kubeapps Dashboard documentation](dashboard.md) | ||
| * [Kubeapps components](../architecture/overview.md) | ||
| For detailed information on installing and configuring Kubeapps, checkout the [chart README](../../chart/kubeapps/README.md). |