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.

The Helm Broker fetches addons which contain a set of specific files. You must place your addons in a repository of an appropriate format. The Helm Broker fetches default cluster-wide addons defined by the helm-repos-urls custom resource (CR). This CR contains URLs that point to the release of addons repository compatible with a given Kyma release. You can also configure the Helm Broker to fetch addons definitions from other addons repositories.

In Kyma, you can use addons to install the following Service Brokers:

• Azure Service Broker
• AWS Service Broker
• GCP Service Broker

To see all addons that the Helm Broker provides, go to the addons repository.

The Helm Broker implements the Open Service Broker API (OSB API). To be compliant with the Service Catalog version used in Kyma, the Helm Broker supports only the following OSB API versions:

• v2.13
• v2.12
• v2.11

NOTE: The Helm Broker does not implement the OSB API update operation.

This document describes the Helm Broker workflow in details, including the logic of its inner components, namely the Controller and Broker.

1. The Controller watches for ClusterAddonsConfiguration (CAC) and AddonsConfiguration (AC) custom resources (CRs).
2. The user creates, updates, or deletes CAC or AC custom resources.
3. The Controller fetches and parses the data of all addon repositories defined under the spec.repositories field in a given CR. During this step the Controller:
   • Analyzes fetched addons against errors.
   • Checks for ID duplications under the repositories field.
   • Checks for ID conflicts with already registered addons.
4. The Controller saves the fetched addons to the storage.
5. When the first CR appears, the Controller creates a ClusterServiceBroker or a ServiceBroker, depending on the type of the CR. The ClusterServiceBroker or the ServiceBroker provides information about the Broker's endpoint which returns the list of all available services to the Service Catalog. There is always only one ClusterServiceBroker per cluster and one ServiceBroker per Namespace, no matter the number of existing CRs. Whenever the list of offered services changes, the Controller triggers the Service Catalog to fetch a new list of services from the ClusterServiceBroker or the ServiceBroker.
6. The Broker component fetches addons from the storage and exposes them to the Service Catalog.
7. The Service Catalog calls the catalog endpoint of the ClusterServiceBroker or the ServiceBroker and creates Service Classes based on the list of registered services.

Update CRs

There are two cases in which you might want to update your CR:

• Re-fetching addons from a remote server
• Changing repositories URLs

Re-fetching addons

If you provided changes to your addon on a remote server but the URL did not change, you must re-fetch your changes manually. In such a case, increment the reprocessRequest field to explicitly request the reprocessing of already registered and processed CR.

Changing repositories URLs

If you made any change in your addon's URLs, the update process is triggered automatically and the Controller performs its logic.

Delete CRs

This is the logic the Controller executes after you delete a given CR:

1. If a given CR is in the Ready state, the Controller removes it from the storage.
2. After addons are removed from the storage, the Controller increments the reprocessRequest field of all failed CRs that had conflicts with the deleted CR in order to reprocess them.
3. The Controller deletes a finalizer from the given CR.

If you defined in the meta.yaml file that your plan is bindable, you must also create a bind.yaml file. The bind.yaml file supports the Service Catalog binding concept. It is mandatory for all bindable plans as it contains information needed during the binding process. Currently, Kyma supports only the credentials-type binding.

NOTE: Resolving the values from the bind.yaml file is a post-provision action. If this operation ends with an error, the provisioning also fails.

In the bind.yaml file, you can use the Helm chart templates directives. See the example:

# bind.yaml
credential:
  - name: HOST
    value: {{ template "redis.fullname" . }}.{{ .Release.Namespace }}.svc.cluster.local
{{- if .Values.usePassword }}
  - name: REDIS_PASSWORD
    valueFrom:
      secretKeyRef:
        name: {{ template "redis.fullname" . }}
        key: redis-password
{{- end }}

In this example, the system renders the bind.yaml file. The system resolves all the directives enclosed in the double curly braces in the same way as in the files located in the templates directory in your Helm chart.

File specification

Define the following fields to create a valid bind.yaml file:

See the fully extended example of the bind.yaml file:

credential:
  - name: HOST
    value: redis.svc.cluster.local
  - name: PORT
    valueFrom:
      serviceRef:
        name: redis-svc
        jsonpath: '{ .spec.ports[?(@.name=="redis")].port }'
  - name: REDIS_PASSWORD
    valueFrom:
      secretKeyRef:
        name: redis-secrets
        key: redis-password
  - name: REDIS_DB_NAME
    valueFrom:
      configMapKeyRef:
        name: redis-cm
        key: redis-db-name
credentialFrom:
  - configMapRef:
    name: redis-config
  - secretRef:
    name: redis-v2-secrets

In this example, the Helm Broker returns the following values:

• A HOST key with the defined inlined value.
• A PORT key with the value from the field specified by the JSONPath expressions. The redis-svc Service runs this expression.
• A REDIS_PASSWORD key with a value selected by the redis-password key from the redis-secrets Secret.
• All the key-value pairs fetched from the redis-config ConfigMap.
• All the key-value pairs fetched from the redis-v2-secrets Secrets.

Credential name conflicts policy

The following rules apply in case of credential name conflicts:

• If the credential and credentialFrom fields have duplicate values, the system uses the values from the credential field.
• If you duplicate a key in the credential field, an error appears and informs you about the name of the key that the conflict refers to.
• If a key exists in the multiple sources defined by the credentialFrom section, the value associated with the last source takes precedence.

If you want to test whether your addons are correct, you can use the dry run mode to check the generated manifests of the chart without installing it.

The --debug option prints the generated manifests. As a prerequisite, you must install Helm on your machine to run this command:

 helm install --dry-run {path-to-chart} --debug

You can also use this option for the basic debugging purposes, when your addons are installed but you fail to provision ServiceInstances from them. For more details, read the Helm official documentation.

The repository in which you create your own addons must contain at least one index.yaml file and have a specific structure, depending on the type of server that exposes your addons.

The index yaml file

Your remote addons repository can contain many addons defined in index files. Depending on your needs and preferences, you can create one or more index files to categorize your addons. In the index file, provide an entry for every single addon from your addons repository. The index file must have the following structure:

apiVersion: v1
entries:
  {addon_name}:
    - name: {addon_name}
      description: {addon_description}
      version: {addon_version}

See the example:

apiVersion: v1
entries:
  redis:
    - name: redis
      description: Redis service
      version: 0.0.1

NOTE: You must place your addons in the same directory where the index.yaml file is stored.

Supported protocols

Expose your addons repository so that you can provide URLs in the AddonsConfiguration (AC) and ClusterAddonsConfiguration (CAC) custom resources. The Helm Broker supports exposing addons using the following protocols:

Supported protocols with authentication

You can provide authentication as part of the URL in your AddonsConfiguration and ClusterAddonsConfiguration custom resources. Instead of using sensitive information directly in the URL, put it in the Secret resource and take advantage of templating. In your repository URL, use placeholders which refer to keys in the Secret. See the following example:

apiVersion: addons.kyma-project.io/v1alpha1
kind: ClusterAddonsConfiguration
metadata:
  name: addons-cfg-sample
spec:
  repositories:
    - url: "https://{host}/{project}/addons/index.yaml"
      secretRef:
        name: data
---
apiVersion: v1
kind: Secret
metadata:
  name: data
type: Opaque
stringData:
  host: "github.com"
  project: "kyma-project/addons"       

The URL renders as follows:

https://github.com/kyma-project/addons/addons/index.yaml

The Helm Broker supports authentication with these protocols:

This document presents the rules you must follow when you configure the Helm Broker. It also describes the Helm Broker's behavior in case of conflicts.

Using HTTP URLs

On your non-local clusters, you can use only servers with TLS enabled. All incorrect or unsecured URLs will be omitted. Find the information about the rejected URLs in the Helm Broker logs. You can use unsecured URLs only on your local cluster. To use URLs without TLS enabled, set the global.isDevelopMode environment variable in the values.yaml file to true.

Registering the same ID multiple times

NOTE: This section does not cover global problems with conflicting IDs between ClusterServiceClasses or ServiceClasses. There can still be a situation where few different brokers register ClusterServiceClasses or ServiceClasses with the same ID. In such a case, those classes are visible in the Service Catalog but provisioning action is blocked with the Found more that one class message.

• When both AddonsConfiguration and ClusterAddonsConfiguration register addons with the same ID, then both are visible in the Service Catalog and they do not have a conflict with each other.
• When there is more than one addon with the same ID specified under the repositories parameter in one ClusterAddonsConfiguration, the whole CR is marked as failed. The status field of the CR contains information about the conflicted addons. The same rule applies to AddonsConfiguration CRs.
• When many ClusterAddonsConfigurations register addons with the same IDs, only the first CR is registered and all others are marked as failed. In the status entry, you can find information about the conflicted addons. The same rule applies to AddonsConfiguration CRs.

Checker is a tool that validates addons in the addons repository on every pull request. It checks whether all required fields are set in your addons.

The Checker also triggers the helm lint command using Helm CLI 2.16.1, which checks your addons' charts. Run the Checker locally to test if your addons are valid:

go run components/helm-broker/cmd/checker/main.go {PATH_TO_YOUR_ADDONS}

If any addon does not meet the requirements, the Helm Broker does not expose it as a Service Class. This situation is displayed in logs. To check logs from the Helm Broker, run these commands:

export HELM_BROKER_POD_NAME=kubectl get pod -n kyma-system -l app=helm-broker
kubectl logs -n kyma-system $HELM_BROKER_POD_NAME helm-broker

Using the Helm Broker, you can provide documentation for your addon and display it in the Console UI. There are two cases in which you may want to use this feature:

• Providing documentation for your addon
• Providing documentation for objects that appear after provisioning your addon

NOTE: Deliver documentation for your addons in Markdown files with specified metadata. For more information, read about metadata and content of the Markdown files, and see the supported types of assets.

Provide documentation for your addon

To provide documentation for your addon, create the docs folder inside your addon's directory. Your docs folder must contain a meta.yaml file with metadata information about how documentation for the addon is uploaded. You can either provide your own documents or point to the external URL with the source documentation:

Provide documentation for objects

To provide documentation for objects that appear after provisioning your addon, create the docs.yaml file inside the addon's chart. This file contains ClusterAssetGroup or AssetGroup custom resources. Each ClusterAssetGroup or AssetGroup corresponds to a single object with the same ID as the name of the specified object. Your docs.yaml file can contain many ClusterAssetGroups or AssetGroups.

To configure the Etcd-stateful sub-chart, override the default values of its values.yaml file. This document describes parameters that you can configure.

TIP: To learn more about how to use overrides in Kyma, see the following documents:

• Helm overrides for Kyma installation
• Sub-charts overrides

Configurable parameters

This table lists the configurable parameters, their descriptions, and default values:

The addonsconfiguration.addons.kyma-project.io CustomResourceDefinition (CRD) is a detailed description of the kind of data and the format used to define define Namespace-scoped addons fetched by the Helm Broker. To get the up-to-date CRD and show the output in the yaml format, run this command:

kubectl get crd addonsconfiguration.addons.kyma-project.io -o yaml

NOTE: Only users with the kyma-admin role can modify the AddonsConfiguration CR. For more information, read about roles in Kyma.

Sample custom resource

This is a sample AddonsConfiguration which provides Namespace-scoped addons. If any of the status fields of the CR is marked as Failed, none of the addons registered with the CR is available in the Service Catalog.

NOTE: All CRs must have the addons.kyma-project.io finalizer which prevents the CR from deletion until the Controller completes the deletion logic successfully. If you don't set a finalizer, the Controller sets it automatically.

apiVersion: addons.kyma-project.io/v1alpha1
kind: AddonsConfiguration
metadata:
  name: addons-cfg-sample
  namespace: default
  finalizers:
  - addons.kyma-project.io
  label:
spec:
  reprocessRequest: 0
  repositories:
    - url: https://github.com/kyma-project/addons/releases/download/0.6.0/index.yaml
    - url: https://github.com/kyma-project/addons/releases/download/0.6.0/index-testing.yaml
    - url: https://broker.url
status:
  phase: Failed
  lastProcessedTime: "2018-01-03T07:38:24Z"
  observedGeneration: 1
  repositories:
    - url: https://github.com/kyma-project/addons/releases/download/0.6.0/index.yaml
      status: Ready
      addons:
        - name: gcp-service-broker
          version: 0.0.2
          status: Failed
          reason: ConflictInSpecifiedRepositories
          message: "Specified repositories have addons with the same ID: [url: https://github.com/kyma-project/addons/releases/download/0.6.0/index-testing.yaml, addons: testing:0.0.1]"
        - name: aws-service-broker
          version: 0.0.2
          status: Failed
          reason: ConflictWithAlreadyRegisteredAddons
          message: "An addon with the same ID is already registered: [ConfigurationName: addons-cfg, url: https://github.com/kyma-project/addons/releases/download/0.4.0/index.yaml, addons: aws-service-broker:0.0.1]"
        - name: azure-service-broker
          version: 0.0.1
          status: Ready
    - url: https://github.com/kyma-project/addons/releases/download/0.6.0/index-testing.yaml
      status: Ready
      addons:
        - name: testing
          version: 0.0.1
          status: Failed
          reason: ConflictInSpecifiedRepositories
          message: "Specified repositories have addons with the same ID: [url: https://github.com/kyma-project/addons/releases/download/0.6.0/index.yaml, addons: gcp-service-broker:0.0.2]"
        - name: redis
          version: 0.0.3
          status: Failed
          reason: ValidationError
          message: "Addon validation failed due to error: schema /plans/default/update-instance-schema.json is larger than 64 kB"
    - url: https://broker.url
      status: Failed
      reason: FetchingIndexError
      message: "Fetching repository failed due to error: the index file was not found"

NOTE: The Controller fetches and processes all addons, even if any of them fails. Thanks to that, at the end of the process you can see the status of all processed addons. You can read information about all detected problems in the status entry of a given CR.

Custom resource parameters

This table lists all possible parameters of a given resource together with their descriptions:

NOTE: The Helm Broker Controller automatically adds all parameters marked as Not applicable to the AddonsConfiguration CR.

Related resources and components

These components use this CR:

Possible FAILED status for created ServiceInstances

If your ServiceInstance creation was successful and yet the release is marked as FAILED on the releases list when running the helm list command, it means that there is an error on the Helm's side that was not passed on to the Helm Broker. To get the error details, check the Helm release status.