helm-broker

README

Helm Broker

Overview

The Helm Broker is a Service Broker which exposes Helm charts as Service Classes in the Service Catalog. To do so, the Helm Broker uses the concept of addons. An addon is an abstraction layer over a Helm chart which provides all information required to convert the chart into a Service Class.

For more information, read the Helm Broker documentation. If you want to use the Helm Broker with all dependencies, try out Kyma.

Learn more about Helm Broker release process in this document.

Prerequisites

To run the project, download these tools:

• kubectl 1.16
• Helm CLI 2.14
• Docker 19.03 (for local installation)
• Kind 0.5 (for local installation)

NOTE: For non-local installation, use Kubernetes v1.15.

Installation

To run the Helm Broker, you need a Kubernetes cluster with Tiller and Service Catalog. Run the ./hack/run-dev-kind.sh script, or follow these steps to set up the Helm Broker on Kind with all necessary dependencies:

1. Create a local cluster on Kind:

kind create cluster

1. Install Tiller into your cluster:

kubectl create serviceaccount --namespace kube-system tiller
kubectl create clusterrolebinding tiller-cluster-rule --clusterrole=cluster-admin --serviceaccount=kube-system:tiller
helm init --service-account tiller --upgrade --wait

1. Install Service Catalog as a Helm chart:

helm repo add svc-cat https://svc-catalog-charts.storage.googleapis.com
helm install svc-cat/catalog --name catalog --namespace catalog

1. Clone the Helm Broker repository:

git clone git@github.com:kyma-project/helm-broker.git

1. Install the Helm Broker chart from the cloned repository:

helm install charts/helm-broker --name helm-broker --namespace helm-broker

Usage

If you have installed the Helm Broker with the Service Catalog, you can add your addon repositories and provision ServiceInstances. Read this document to learn how. You can find more ready-to-use addons here. Follow this example to configure the Helm Broker and provision the Redis instance:

1. Configure the Helm Broker to use the addons repository that contains the Redis addon:

kubectl apply -f hack/examples/sample-addons.yaml

After the Helm Broker processes the addons' configuration, you can see the Redis ClusterServiceClass:

kubectl get clusterserviceclass

1. Provision the Redis instance:

kubectl apply -f hack/examples/redis-instance.yaml

1. Check the status of the Redis instance:

kubectl get serviceinstance

1. Create a binding for the Redis instance:

kubectl apply -f hack/examples/redis-binding.yaml

1. Check the Secret that contains Redis credentials:

kubectl get secret redis -o yaml

Use the following commands to see the decoded values:

kubectl get secret redis -o=jsonpath="{.data.HOST}" | base64 -D
kubectl get secret redis -o=jsonpath="{.data.PORT}" | base64 -D
kubectl get secret redis -o=jsonpath="{.data.REDIS_PASSWORD}" | base64 -D

Use environment variables

Use the following environment variables to configure the Broker component of the Helm Broker:

Name	Required	Default	Description
APP_PORT	No	8080	The port on which the HTTP server listens.
APP_KUBECONFIG_PATH	No		Provides the path to the kubeconfig file that you need to run an application outside of the cluster.
APP_CONFIG_FILE_NAME	No		Specifies the path to the configuration .yaml file.
APP_HELM_TILLER_TLS_ENABLED	No	true	Specifies the TLS configuration for the Tiller. If set to true, the TLS communication with Tiller is required.
APP_HELM_TILLER_HOST	No		Specifies the host address of the Tiller release server.
APP_HELM_TILLER_INSECURE	No	false	If set to true, the Broker verifies the Tiller's certificate.
APP_HELM_TILLER_KEY	No		Provides the path to the PEM-encoded private key file.
APP_HELM_TILLER_CRT	No		Provides the path to the PEM-encoded certificate file.

Use the following environment variables to configure the Controller component of the Helm Broker:

Name	Required	Default	Description
APP_CONFIG_FILE_NAME	No		Specifies the path to the configuration .yaml file.
APP_TMP_DIR	Yes		Provides a path to a temporary directory that is used to unpack addons archives or to clone Git repositories.
APP_KUBECONFIG_PATH	No		Provides the path to the kubeconfig file that you need to run an application outside of the cluster.
APP_NAMESPACE	Yes		Specifies the Namespace where the Helm Broker is installed.
APP_SERVICE_NAME	Yes		Specifies the name of the Kubernetes service that exposes the Broker.
APP_CLUSTER_SERVICE_BROKER_NAME	Yes		Specifies the name of the ClusterServiceBroker resource which registers the Helm Broker in the Service Catalog.
APP_DEVELOP_MODE	No	false	If set to true, you can use unsecured HTTP-based repositories URLs.
APP_DOCUMENTATION_ENABLED	No	false	If set to true, the Helm Broker uploads addons documentation to the Headless CMS.

Development

To set up the project, download these tools:

• Go 1.12
• Dep 0.5
• Docker

NOTE: The versions of Go and Dep are compliant with the buildpack used by Prow. For more details, read this document.

Project structure

The repository has the following structure:

  ├── .github                     # Pull request and issue templates    
  ├── charts                      # Charts to install by Helm
  ├── cmd                         # Main applications for project                                     
  ├── config                      # Configuration file templates or default configurations
  ├── deploy                      # Dockerfiles to build images
  ├── docs                        # Documentation files
  ├── hack                        # Scripts used by the Helm Broker developers
  ├── internal                    # Private application and library code
  ├── pkg                         # Library code to use by external applications
  └── test                        # Additional external test applications and test data

Run tests

Before each commit, use the before-commit.sh script. The script runs unit tests that check your changes and build binaries. If you want to run the Helm Broker locally, read this document.

You can also run integration tests that check if all parts of the Helm Broker work together. These are the prerequisites for integration tests:

• Kubebuilder 1.0.8
• Etcd 3.4
• Minio RELEASE.2019-10-12T01-39-57Z

Run integration tests using this command:

make integration-test

Update chart's images tag

To change the chart's tags version, run this command:

make VERSION=v0.0.1 DIR=/pr tag-chart-images

This command overrides the images tag in the charts/helm-broker/values.yaml file to:

eu.gcr.io/kyma-project/helm-broker/pr:v0.0.1

Build Docker images

If you want to build Docker images with your changes and push them to a registry, follow these steps:

1. Run tests and build binaries:

make build

1. Build Docker images:

make build-image

1. Configure environent variables pointing to your registry, for example:

export DOCKER_PUSH_REPOSITORY=eu.gcr.io/
export DOCKER_PUSH_DIRECTORY=your-project
export DOCKER_TAG=latest

1. Push the image to the registry:

make push-image

1. Install the Helm Broker with your custom image using the following command:

helm install charts/helm-broker \
 --name helm-broker \
 --namespace helm-broker \
 --set global.helm_broker.image="${DOCKER_PUSH_REPOSITORY}${DOCKER_PUSH_DIRECTORY}/helm-broker" \
 --set global.helm_broker.version=${DOCKER_TAG} \
 --set global.helm_controller.image="${DOCKER_PUSH_REPOSITORY}${DOCKER_PUSH_DIRECTORY}/helm-controller" \
 --set global.helm_controller.version=${DOCKER_TAG}

If you already have the Helm Broker installed, you can upgrade it to use new images:

helm upgrade helm-broker charts/helm-broker \
 --set global.helm_broker.image="${DOCKER_PUSH_REPOSITORY}${DOCKER_PUSH_DIRECTORY}/helm-broker" \
 --set global.helm_broker.version=${DOCKER_TAG} \
 --set global.helm_controller.image="${DOCKER_PUSH_REPOSITORY}${DOCKER_PUSH_DIRECTORY}/helm-controller" \
 --set global.helm_controller.version=${DOCKER_TAG}