This repository has been archived by the owner on Jul 16, 2021. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 220
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Update chart and documentation (#286)
* Update chart and documentation * document releasesEnabled option
- Loading branch information
Showing
11 changed files
with
141 additions
and
160 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 |
|---|---|---|
| @@ -1 +1 @@ | ||
| Documentation moved [/docs/deployment.md](/docs/deployment.md) | ||
| Documentation moved [/deployment/monocular/README.md](/deployment/monocular/README.md) |
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 |
|---|---|---|
| @@ -0,0 +1,119 @@ | ||
| # Monocular | ||
|
|
||
| [Monocular](https://github.com/helm/monocular) is web-based UI for managing Kubernetes applications packaged as Helm Charts. It allows you to search and discover available charts from multiple repositories, and install them in your cluster with one click. | ||
|
|
||
| ## TL;DR; | ||
|
|
||
| ```console | ||
| $ helm repo add monocular https://helm.github.io/monocular | ||
| $ helm install monocular/monocular | ||
| ``` | ||
|
|
||
| ## Introduction | ||
|
|
||
| This chart bootstraps a [Monocular](https://github.com/helm/monocular) deployment on a [Kubernetes](http://kubernetes.io) cluster using the [Helm](https://helm.sh) package manager. | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| ### [Nginx Ingress controller](https://github.com/kubernetes/ingress) | ||
|
|
||
| To avoid issues with Cross-Origin Resource Sharing, the Monocular chart sets up an Ingress resource to serve the frontend and the API on the same domain. This is used to route requests made to `<host>:<port>/` to the frontend pods, and `<host>:<port>/api` to the backend pods. | ||
|
|
||
| It is possible to run Monocular on separate domains and without the Nginx Ingress controller, see the [configuration](#serve-monocular-frontend-and-api-on-different-domains) section on how to do this. | ||
|
|
||
| ## Installing the Chart | ||
|
|
||
| First, ensure you have added the Monocular chart repository: | ||
|
|
||
| ```console | ||
| $ helm repo add monocular https://helm.github.io/monocular | ||
| ``` | ||
|
|
||
| To install the chart with the release name `my-release`: | ||
|
|
||
| ```console | ||
| $ helm install --name my-release monocular | ||
| ``` | ||
|
|
||
| The command deploys Monocular on the Kubernetes cluster in the default configuration. The [configuration](#configuration) section lists the parameters that can be configured during installation. | ||
|
|
||
| > **Tip**: List all releases using `helm list` | ||
| ## Uninstalling the Chart | ||
|
|
||
| To uninstall/delete the `my-release` deployment: | ||
|
|
||
| ```console | ||
| $ helm delete my-release | ||
| ``` | ||
|
|
||
| The command removes all the Kubernetes components associated with the chart and deletes the release. | ||
|
|
||
| ## Configuration | ||
|
|
||
| See the [values](values.yaml) for the full list of configurable values. | ||
|
|
||
| ### Disabling Helm releases (deployment) management | ||
|
|
||
| If you want to run Monocular without giving the option to install and manage charts in your cluster, similar to [KubeApps](https://kubeapps.com) you can configure `api.config.releasesEnabled`: | ||
|
|
||
| ```console | ||
| $ helm install monocular/monocular --set api.config.releasedEnabled=false | ||
| ``` | ||
|
|
||
| ### Configuring chart repositories | ||
|
|
||
| You can configure the chart repositories you want to see in Monocular with the `api.config.repos` value, for example: | ||
|
|
||
| ```console | ||
| $ cat > custom-repos.yaml <<<EOF | ||
| api | ||
| config: | ||
| repos: | ||
| - name: stable | ||
| url: http://storage.googleapis.com/kubernetes-charts | ||
| source: https://github.com/kubernetes/charts/tree/master/stable | ||
| - name: incubator | ||
| url: http://storage.googleapis.com/kubernetes-charts-incubator | ||
| source: https://github.com/kubernetes/charts/tree/master/incubator | ||
| - name: monocular | ||
| url: https://helm.github.io/monocular | ||
| source: https://github.com/helm/monocular/tree/master/charts | ||
| EOF | ||
|
|
||
| $ helm install monocular/monocular -f custom-repos.yaml | ||
| ``` | ||
|
|
||
| ### Serve Monocular frontend and API on different domains | ||
|
|
||
| In order to serve the frontend and the API on different domains, you need to configure the frontend with the API location and configure CORS correctly for the API to accept requests from the frontend. | ||
|
|
||
| To do this, you can use the `ui.backendHostname` and `api.config.cors.allowed_origins` values. You should also disable the Ingress resource and manually configure each hostname to point to the pods. | ||
|
|
||
| ```console | ||
| $ cat > separate-domains.yaml <<<EOF | ||
| ingress: | ||
| enabled: false | ||
| api: | ||
| config: | ||
| cors: | ||
| allowed_origins: | ||
| - http://$FRONTEND_HOSTNAME | ||
| ui: | ||
| backendHostname: http://$API_HOSTNAME | ||
| EOF | ||
|
|
||
| $ helm install monocular/monocular -f separate-domains.yaml | ||
| ``` | ||
|
|
||
| Ensure that you replace `$FRONTEND_HOSTNAME` and `$API_HOSTNAME` with the hostnames you want to use. | ||
|
|
||
| ### Other configuration options | ||
|
|
||
| | Value | Description | Default | | ||
| |-----------------------------------------|---------------------------------------------------------------------------------------------|-----------------------| | ||
| | `api.livenessProbe.initialDelaySeconds` | Increase this if the API pods are crashing due to the chart repository sync taking too long | `180` | | ||
| | `api.config.releasesEnabled` | Enable installing and managing charts in the cluster | `3600` | | ||
| | `api.config.cacheRefreshInterval` | How often to sync with chart repositories | `3600` | | ||
| | `ui.googleAnalyticsId` | Google Analytics ID | `UA-XXXXXX-X` (unset) | | ||
| | `ui.appName` | Name to use in title bar and header | `Monocular` | |
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 was deleted.
Oops, something went wrong.
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,116 +1 @@ | ||
| # Deploying Monocular in Kubernetes | ||
|
|
||
| ## Quickstart | ||
|
|
||
| Monocular is packaged as a Helm Chart that can be found in the `/deployment/monocular` directory. | ||
|
|
||
| > **Prerequisites** | ||
| > | ||
| > The chart is configured and tested to be used alongside an NGINX Ingress controller. Please be sure that you have a running instance in your cluster before proceeding. More information [here](https://github.com/kubernetes/charts/tree/master/stable/nginx-ingress). | ||
| Install the Monocular chart: | ||
|
|
||
| ``` | ||
| helm install deployment/monocular | ||
| ``` | ||
|
|
||
| Visit [Using Helm](https://github.com/kubernetes/helm/blob/master/docs/using_helm.md) to learn more about how to use Helm. | ||
|
|
||
| Once deployed, your application should be available at `https://[nginx-ingress-controller-service-ip]`. | ||
|
|
||
| ### Chart details | ||
|
|
||
| The chart contains 3 tiers and one ingress resource. | ||
|
|
||
| #### Components | ||
|
|
||
| * UI: AngularJS web frontend. | ||
| * API: Golang based backend API. | ||
| * Prerederer: PhantomJS prerenderer for SEO purposes. More information [here](https://github.com/prerender/prerender). | ||
|
|
||
| #### Ingress resource | ||
|
|
||
| The chart includes an ingress resource that is configured to route the backend API via `[your-domain]/api` so it can be easily consumed by the UI avoiding any CORS issue or configuration. | ||
|
|
||
| You can configure many different settings from hosts, ingress-class to tls options using the `values.yaml` file. | ||
|
|
||
| # Configuration | ||
|
|
||
| You can customize settings like the chart repositories to pull from by modifying the `values.yaml` file. Click [here](configuration.md) to learn more. | ||
|
|
||
| # CI/CD scripts | ||
|
|
||
| In the `/deployment` directory you can find a set of convenience scripts helpful in CI/CD setups. | ||
|
|
||
| ## Deploy for the first time | ||
|
|
||
| You can deploy a new release of the operations service | ||
| using the `deploy_install.sh` script. | ||
|
|
||
| ### Arguments | ||
|
|
||
| #### Required | ||
|
|
||
| * `API_TAG`: Image tag to be used on the API tier, it will be appended to API_IMAGE | ||
| * `UI_TAG`: Image tag to be used on the API tier. It will be appended to UI_IMAGE | ||
|
|
||
| #### Optional | ||
|
|
||
| * `API_NAME` (default: `gcr.io/helm-ui/monocular-api`) | ||
| * `UI_NAME` (default: `gcr.io/helm-ui/monocular-ui`) | ||
| * `RELEASE_NAME` (default: `Helm's provided random name`) Helm release | ||
| name. | ||
| * `VALUES_OVERRIDE` (default: `api.image.repository=${API_IMAGE},api.image.tag=${API_TAG},ui.image.repository=${UI_IMAGE},ui.image.tag=${UI_TAG}`) Helm values to be overridden (`helm install --set $VALUES_OVERRIDE`) | ||
| * `HELM_OPTS` (default: no value) Extra options to be passed to the helm | ||
| command i.e --dry-run --debug | ||
|
|
||
| ### Examples | ||
|
|
||
| ``` | ||
| # Deploy the release | ||
| API_TAG=1 UI_TAG=1 ./deploy_install.sh | ||
| # Deploy setting the release name | ||
| API_TAG=1 UI_TAG=1 RELEASE_NAME='my_release' ./deploy_install.sh | ||
| # Deploy with helm debug and dry-run | ||
| API_TAG=1 UI_TAG=1 HELM_OPTS="--debug --dry-run" ./deploy_install.sh | ||
| # Deploy overridding default values | ||
| API_TAG=1 UI_TAG=1\ | ||
| VALUES_OVERRIDE="backend.image.repository=my-image,backend.service.type=LoadBalancer"\ | ||
| ./deploy_install.sh | ||
| ``` | ||
|
|
||
| ## Upgrade an existing release | ||
|
|
||
| You can upgrade an existing release of the operations service using the `deploy_upgrade.sh` script. | ||
|
|
||
| ### Arguments | ||
|
|
||
| #### Required | ||
|
|
||
| * `API_TAG`: Image tag to be used on the API tier, it will be appended to API_IMAGE | ||
| * `UI_TAG`: Image tag to be used on the API tier. It will be appended to UI_IMAGE | ||
| * `RELEASE_NAME`: Helm release name. | ||
|
|
||
| #### Optional | ||
|
|
||
| * `API_NAME` (default: `gcr.io/helm-ui/monocular-api`) | ||
| * `UI_NAME` (default: `gcr.io/helm-ui/monocular-ui`) | ||
| * `SKIP_UPGRADE_CONFIRMATION` (default: false) Skip the confirmation | ||
| prompt if an upgrade needs to be performed. Useful for unattended | ||
| name. | ||
| * `VALUES_OVERRIDE` (default: `api.image.repository=${API_IMAGE},api.image.tag=${API_TAG},ui.image.repository=${UI_IMAGE},ui.image.tag=${UI_TAG}`) Helm values to be overridden (`helm install --set $VALUES_OVERRIDE`) | ||
| * `HELM_OPTS` (default: no value) Extra options to be passed to the helm | ||
| command i.e --dry-run --debug | ||
|
|
||
| ### Examples | ||
|
|
||
| ``` | ||
| # Upgrade the release in attended mode | ||
| API_TAG=1 UI_TAG=1 RELEASE_NAME='my_release' ./deploy_upgrade.sh | ||
| # Upgrade in unattended mode | ||
| API_TAG=1 UI_TAG=1 RELEASE_NAME='my-release' SKIP_UPGRADE_CONFIRMATION=true ./deploy_upgrade.sh | ||
| ``` | ||
| See the chart [README](/deployment/monocular/README.md) to learn how to deploy and configure Monocular on your Kubernetes cluster. |
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