Helm Broker

Overview

The Helm Broker is an implementation of a service broker which runs in the Kyma cluster and deploys Kubernetes native resources using Helm and Kyma bundles. A bundle is an abstraction layer over a Helm chart which allows you to represent it as a ClusterServiceClass in the Service Catalog. For example, a bundle can provide plan definitions or binding details. The Helm Broker fetches bundle definitions from an HTTP server. By default, the Helm Broker fetches bundles from the newest release with the Semantic Versioning pattern available at the bundles repository.

Using bundles, you can also install these brokers:

  • Google Cloud Platform (GCP) Broker
  • Azure Service Broker

To get the bundles that the Helm Broker provides, go to the bundles repository. For more information about Service Brokers, see this document.

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 versions of the OSB API:

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

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

Architecture

The Helm Broker workflow starts with the registration process, during which the Helm Broker fetches bundles from the Kyma bundles directory, or from a remote HTTP server.

Registration process

The registration process in case of the Helm Broker consists of the following steps: 1. The Helm Broker fetches bundles from the remote HTTP server. 2. The Helm Broker registers bundles as ServiceClasses in the Service Catalog.

Helm Broker registration

Bundles provisioning and binding

After the registration, the process of bundle provisioning and binding takes place. It consists of the following steps:

  1. Select a given bundle ServiceClass from the Service Catalog.
  2. Provision this ServiceClass by creating its ServiceInstance in the given Namespace.
  3. Bind your ServiceInstance to the service or lambda. During the binding process, ServiceBinding and ServiceBindingUsage resources are created.
  4. The service or lambda calls a bundle.

Helm Broker architecture

Configuration

Configure Helm Broker

The Helm Broker fetches bundle definitions from HTTP servers defined in the helm-repos-urls ConfigMap.

Add a new bundle repository

Follow these steps to change the configuration and make the Helm Broker fetch bundles from a custom HTTP servers:

  1. Create a remote repository with the definition of your bundles. Your remote bundle repository must include the following resources:

    • A yaml file which defines available bundles, for example index.yaml. This file must have the following structure:
      Click to copy
      apiVersion: v1
      entries:
      {bundle_name}:
      - name: {bundle_name}
      description: {bundle_description}
      version: {bundle_version}
      This is an example of a yaml file for the Redis bundle:
      Click to copy
      apiVersion: v1
      entries:
      redis:
      - name: redis
      description: Redis service
      version: 0.0.1
    • A {bundle_name}-{bundle_version}.tgz file for each bundle version defined in the yaml file. The .tgz file is an archive of your bundle's directory.
  2. Install Kyma on Minikube. See this document to learn how.

  3. Create a ConfigMap which contains an URL to the repository:

    Click to copy
    kubectl create configmap my-helm-repos-urls -n kyma-system --from-literal=URLs=https://github.com/kyma-project/bundles/releases/download/latest/index-testing.yaml

    NOTE: If you want to fetch bundles from many HTTP servers, use \n to separate the URLs.

  4. Label the newly created ConfigMap:

    Click to copy
    kubectl label configmap my-helm-repos-urls -n kyma-system helm-broker-repo=true

Helm Broker triggers the Service Catalog synchronization automatically. New ClusterServiceClasses appear after a few seconds.

Use the following example to create a valid ConfigMap with many URLs from the yaml file:

Click to copy
apiVersion: v1
kind: ConfigMap
metadata:
name: helm-repos-configs
labels:
helm-broker-repo: "true"
data:
URLs: |-
https://github.com/kyma-project/bundles/releases/download/0.3.0/index-testing.yaml
https://github.com/kyma-project/bundles/releases/download/0.3.0/

Create a bundle

To create your own bundle, you must create a directory with the following structure:

Click to copy
sample-bundle/
├── meta.yaml # A file which contains the metadata information about this bundle
├── chart/ # A directory which contains a Helm chart that installs your Kubernetes resources
│ └── <chart-name>/ # A Helm chart directory
│ └── .... # Helm chart files
└── plans/ # A directory which contains the possible plans for an installed chart
├── example-enterprise # A directory of files for a specific plan
│ ├── meta.yaml # A file which contains the metadata information about this plan
│ ├── bind.yaml # A file which contains information about the values that the Helm Broker returns when it receives the bind request
│ ├── create-instance-schema.json # The JSON Schema definitions for creating a ServiceInstance
│ ├── bind-instance-schema.json # The JSON Schema definitions for binding a ServiceInstance
│ ├── update-instance-schema.json # The JSON Schema definitions for updating a ServiceInstance
│ └── values.yaml # The default configuration values in this plan for a chart defined in the `chart` directory
└── ....

NOTE: All the file names in the bundle directory are case-sensitive.

The bundle meta.yaml file

The meta.yaml file is mandatory as it contains information about the bundle. Set the following fields to create service objects which comply with the Open Service Broker API.

Field NameRequiredDescription
nametrueThe bundle name. It has the same restrictions as defined in the Open Service Broker API.
versiontrueThe bundle version. It is a broker service identifier. It has the same restrictions as defined in the Open Service Broker API.
idtrueA broker service identifier. It has the same restrictions as defined in the Open Service Broker API.
descriptiontrueA short description of the service. It has the same restrictions as defined in the Open Service Broker API.
tagsfalseThe keywords describing the provided service, separated by commas.
bindablefalseThe bindable field described in the Open Service Broker API.
displayNametrueThe displayName field described in the Open Service Broker API.
providerDisplayNamefalseThe providerDisplayName field described in the Open Service Broker API.
longDescriptionfalseThe longDescription field described in the Open Service Broker API.
documentationURLfalseThe documentationURL field described in the Open Service Broker API.
supportURLfalseThe supportURL field described in the Open Service Broker API.
imageURLfalseThe imageURL field described in the Open Service Broker API. You must provide the image as an SVG.
labelsfalseTo organize your project, add arbitrary labels as key/value pairs. Use labels to indicate different elements, such as Namespaces, services, or teams.
bindingsRetrievablefalseThe bindingRetrievable field specifies whether fetching a ServiceBinding using a GET call on the resource's endpoint is supported for all plans. The default value is false.
planUpdatablefalseThe planUpdatable field specifies whether instances of this service can be updated to a different plan. The default value is false
requiresfalseThe requires field defines a list of permissions the user must grant to the instances of this service.
provisionOnlyOncefalseDefines that the bundle can be provisioned only once in a given Namespace. The default value is false

NOTE: The provisionOnlyOnce and local keys are reserved and cannot be added to the labels entry, since the Helm Broker overrides them at runtime. The Helm Broker always adds the local:true label and it adds the provisionOnlyOnce:true label only if provisionOnlyOnce is set to true.

The chart directory

In the mandatory chart directory, create a folder with the same name as your chart. Put all the files related to your chart in this folder. The system supports chart version 2.6.

If you are not familiar with the chart definitions, see the Charts specification.

NOTE: Helm Broker uses the helm wait option to ensure that all the resources that a chart creates are available. If you set your Deployment replicas to 1, you must set maxUnavailable to 0 as a part of the rolling update strategy.

The plans directory

The mandatory plans directory must contain at least one plan. A directory for a specific plan must contain the meta.yaml file. Other files, such as create-instance-schema.json, bind.yaml and values.yaml are not mandatory.

The meta.yaml file

The meta.yaml file contains information about a bundle plan. Set the following fields to create the plan objects, which comply with the Open Service Broker API.

Field NameRequiredDescription
nametrueThe plan name. It has the same restrictions as defined in the Open Service Broker API.
idtrueThe plan ID. It has the same restrictions as defined in the Open Service Broker API.
descriptiontrueThe plan description. It has the same restrictions as defined in the Open Service Broker API.
displayNametrueThe plan display name. It has the same restrictions as defined in the Open Service Broker API.
bindablefalseThe plan bindable attribute. It has the same restrictions as defined in the Open Service Broker API.
freefalseThe attribute which specifies whether the instance is free or not. The default value is false.

The bind.yaml file

The bind.yaml file contains the information required for the binding action in a specific plan. If you defined in the meta.yaml file that your plan is bindable, you must also create a bind.yaml file. For more information about the content of the bind.yaml file, see the Binding bundles document.

The values.yaml file

The values.yaml file provides the default configuration values in a concrete plan for the chart definition located in the chart directory. This file is not required. For more information about the content of the values.yaml file, see the Values Files specification.

The create-instance-schema.json file

The create-instance-schema.json file contains a schema used to define the parameters for a provision operation of the ServiceInstance. Each input parameter is expressed as a property within a JSON object. This file is not required. For more information about the content of the create-instance-schema.json file, see the Schemas specification.

The update-instance-schema.json file

The update-instance-schema.json file contains a schema used to define the parameters for an update operation of the ServiceInstance. Each input parameter is expressed as a property within a JSON object. This file is not required. For more information about the content of the update-instance-schema.json file, see the Schemas specification.

The bind-instance-schema.json file

The bind-instance-schema.json file contains a schema used to define the parameters for a bind operation. Each input parameter is expressed as a property within a JSON object. This file is not required. For more information about the content of the bind-instance-schema.json file, see the Schemas specification.

Troubleshooting

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:

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

For more details, read the Helm official documentation.

Binding bundles

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. The bind.yaml file contains information the system uses in the binding process. The bind.yaml file is mandatory for all bindable plans. 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.

Details

This section provides an example of the bind.yaml file. It further describes the templating, the policy concerning credential name conflicts, and the detailed bind.yaml file specification.

Example usage

Click to copy
# bind.yaml
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
credentialFrom:
- configMapRef:
name: redis-config
- secretRef:
name: redis-v2-secrets

In this example of the binding action, 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.

Templating

In the bind.yaml file, you can use the Helm Chart templates directives.

Click to copy
# 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.

Credential name conflicts policy

The following rules apply in cases of credential name conflicts:

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

File specification

Field NameDescription
credentialThe list of the credential variables to return during the binding action.
credentialFromThe list of the sources to populate the credential variables on the binding action. When the key exists in multiple sources, the value associated with the last source takes precedence. The variables from the credential section override the values if duplicate keys exist.

Credential

Field NameDescription
nameThe name of the credential variable.
valueA variable value. You can also use the Helm Chart templating directives.
valueFromThe source of the credential variable's value. You cannot use it if the value is not empty.
ValueFrom
Field NameDescription
configMapKeyRefSelects a ConfigMap key in the Helm chart release Namespace.
secretKeyRefSelects a Secret key in the Helm Chart release Namespace.
serviceRefSelects a Service resource in the Helm Chart release Namespace.
ConfigMapKeyRef
Field NameDescription
nameThe name of the ConfigMap.
keyThe name of the key from which the value is retrieved.
SecretKeyRef
Field NameDescription
nameThe name of the Secret.
keyThe name of the key from which the value is retrieved.
ServiceRef
Field NameDescription
nameThe name of the Service.
jsonpathThe JSONPath expression used to select the specified field value. For more information, see the User Guide.

CredentialFrom

Field NameDescription
configMapRefThe ConfigMap to retrieve the values from. It must be available in the Helm Chart release Namespace.
secretRefThe Secret to retrieve the values from. It must be available in the Helm Chart release Namespace.
ConfigMapRef
Field NameDescription
nameThe name of the ConfigMap.
SecretRef
Field NameDescription
nameThe name of the Secret.