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.

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:

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.

Architecture

Basic architecture

The Helm Broker is installed alongside other Kyma components and it automatically registers itself in the Service Catalog as a ClusterServiceBroker. The installation provides the default helm-repos-urls ClusterAddonsConfiguration (CAC) custom resource (CR). It contains URLs from which Helm Broker fetches addons. You can also add your own addons with URLs that point to your addons repository.

If you want the Helm Broker to act as a Namespace-scoped ServiceBroker, create the AddonsConfiguration (AC) CR. In such a case, the Helm Broker creates a service and registers itself in the Service Catalog as a ServiceBroker inside the Namespace in which the CR is created.

The Helm Broker workflow starts with the registration process, during which the Helm Broker fetches addons from URLs provided in the ClusterAddonsConfiguration or AddonsConfiguration CRs and registers them as Service Classes in the Service Catalog.

Cluster-wide addons flow

  1. The Helm Broker watches for ClusterAddonsConfiguration CRs in a given cluster.
  2. The user creates a ClusterAddonsConfiguration CR.
  3. The Helm Broker fetches and parses the data of all addon repositories defined in the ClusterAddonsConfiguration CR.
  4. The Helm Broker creates a ClusterServiceBroker. There is always only one ClusterServiceBroker, even if there are multiple ClusterAddonsConfiguration CRs.
  5. The Service Catalog fetches services that the ClusterServiceBroker exposes.
  6. The Service Catalog creates a ClusterServiceClass for each service received from the ClusterServiceBroker.

Helm Broker cluster

Namespace-scoped addons flow

  1. The Helm Broker watches for AddonsConfiguration CRs in all Namespaces.
  2. The user creates an AddonsConfiguration CR in a given Namespace.
  3. The Helm Broker fetches and parses the data of all addon repositories defined in the AddonsConfiguration CR.
  4. The Helm Broker creates a Service Broker (SB) inside the Namespace in which the AddonsConfiguration CR is created. There is always a single ServiceBroker per Namespace, even if there are more AddonsConfigurations CRs.
  5. The Service Catalog fetches the services that the Service Broker exposes.
  6. The Service Catalog creates a ServiceClass for each service received from the Service Broker.

Helm Broker cluster

Provisioning and binding

After you register your addons in the Service Catalog, you can provision and bind Service Classes that your addons provide.

  1. Select a given addon Service Class from the Service Catalog.
  2. Provision this Service Class by creating its ServiceInstance in a given Namespace.
  3. Bind your ServiceInstance to a service or a lambda function.
  4. The service or lambda calls a given addon.

Helm Broker architecture

Architecture deep dive

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

Architecture deep dive

  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.

Details

Create addons

Addons which the Helm Broker uses must have a specific structure. These are all possible files that you can include in your addons:

Click to copy
sample-addon/
├── meta.yaml # [REQUIRED] A file which contains metadata information about this addon
├── chart/ # [REQUIRED] A directory which contains a Helm chart that installs your Kubernetes resources
│ └── {chart-name}/ # [REQUIRED] A Helm chart directory
│ └── .... # [REQUIRED] Helm chart files
├── plans/ # [REQUIRED] A directory which contains the possible plans for an installed chart
│ ├── example-enterprise # [REQUIRED] A directory which contains files for a specific plan
│ │ ├── meta.yaml # [REQUIRED] A file which contains metadata information about this plan
│ │ ├── bind.yaml # A file which contains information required to bind this plan
│ │ ├── create-instance-schema.json # JSON schema definitions for creating a ServiceInstance
│ │ ├── bind-instance-schema.json # JSON schema definitions for binding a ServiceInstance
│ │ ├── update-instance-schema.json # JSON schema definitions for updating a ServiceInstance
│ │ └── values.yaml # Default configuration values in this plan for a chart defined in the `chart` directory
│ └── ....
└── docs/ # A directory which contains documentation for this addon
├── meta.yaml # [REQUIRED] A file which contains metadata information about documentation for this addon
├── {assets} # Files with documentation and assets
└── ....

NOTE: All file names in an addon repository are case-sensitive.

NOTE: The maximum size of an addon is determined by the amount of memory and storage size. These limits are set in the Helm Broker chart.

For details about particular files, read the following sections.

meta.yaml file

The meta.yaml file contains information about the addon. Define the following fields to create a service object which complies with the Open Service Broker API.

Field NameRequiredDescription
nameYESThe name of the addon.
versionYESThe version of the addon. It is a broker service identifier.
idYESThe broker service identifier.
descriptionYESThe short description of the service.
displayNameYESThe display name of the addon.
tagsNOKeywords describing the provided service, separated by commas.
bindableNOThe field that specifies whether you can bind a given addon.
providerDisplayNameNOThe name of the upstream entity providing the actual service.
longDescriptionNOThe long description of the service.
documentationURLNOThe link to the documentation page for the service.
supportURLNOThe link to the support page for the service.
imageURLNOThe URL to an image. You must provide the image in the SVG format.
labelsNOKey-value pairs that help you to organize your project. Use labels to indicate different elements, such as Namespaces, services, or teams.
bindingsRetrievableNOThe field that specifies whether fetching a ServiceBinding using a GET request on the resource's endpoint is supported for all plans. The default value is false.
planUpdatableNOThe field that specifies whether instances of this service can be updated to a different plan. The default value is false
requiresNOThe list of permissions the user must grant to the instances of this service.
provisionOnlyOnceNOThe field that specifies whether the addon 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.

chart directory

In the 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 Helm version 2.6.

NOTE: The 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.

plans directory

The plans directory must contain at least one plan. Each plan must contain the meta.yaml file. Other files are not mandatory.

  • meta.yaml file - contains information about a given plan. Define the following fields to create a plan object which complies with the Open Service Broker API.
Field NameRequiredDescription
nameYESThe name of the plan.
idYESThe ID of the plan.
descriptionYESThe description of the plan.
displayNameYESThe display name of the plan.
bindableNOThe field that specifies whether you can bind an instance of the plan or not. The default value is false.
freeNOThe attribute which specifies whether an instance of the plan is free or not. The default value is false.
  • bind.yaml file - contains information about binding in a specific plan. If you define in the meta.yaml file that your plan is bindable, you must also create a bind.yaml file. For more information about this file, see this document.

  • values.yaml file - provides the default configuration values in a given plan for the chart definition located in the chart directory. For more information, see the values files specification.

  • create-instance-schema.json file - contains a schema that defines parameters for a provision operation of a ServiceInstance. Each input parameter is expressed as a property within a JSON object.

  • update-instance-schema.json file - contains a schema that defines parameters for an update operation of a ServiceInstance. Each input parameter is expressed as a property within a JSON object.

  • bind-instance-schema.json file - contains a schema that defines parameters for a bind operation. Each input parameter is expressed as a property within a JSON object.

NOTE: For more information about schemas, see this specification.

docs directory

In the docs directory, provide documentation for your addon. The documentation can include Markdown documents, AsyncAPI, OData, and OpenAPI specification files. Create the assets directory inside the docs directory to store assets, such as images. The docs directory must contain a meta.yaml which provides information on how documentation for the addon is uploaded. As the Helm Broker is installed as a ClusterServiceBroker, documentation for addons is provided using ClusterDocsTopics.

The meta.yaml file contains the specification of the ClusterDocsTopic. The example structure of the meta.yaml file looks as follows:

Field NameRequiredDescription
docs[]YESContains the definitions of documentation.
docs[].templateYESContains the specification of the ClusterDocsTopic.
docs[].template.displayNameYESSpecifies the display name of the ClusterDocsTopic.
docs[].template.descriptionYESProvides the description of the ClusterDocsTopic.
docs[].template.sources[]YESContains the definitions of assets for an addon.
docs[].template.sources[].typeYESDefines the type of the asset.
docs[].template.sources[].nameYESDefines the name of the asset.
docs[].template.sources[].modeYESDefines the type of the asset file.
docs[].template.sources[].urlYESDefines the URL under which the asset is stored.
docs[].template.sources[].filterYESDefines the path from which to upload assets.

NOTE: Currently you can provide only one entry in the docs array.

See this example of the docs directory with documentation for the testing addon.

Using the Helm Broker, you can provision a broker which provides its own Service Classes. To learn how to upload documentation for those classes, read this document.

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.

Bind addons

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:

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.

File specification

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

Field NameDescription
credentialThe list of credential variables returned during the binding action.
credential.nameThe name of a given credential variable.
credential.valueThe variable value. You can also use the Helm Chart templating directives. This field is interchangeable with credential.valueFrom.
credential.valueFromThe source of the given credential variable's value. This field is interchangeable with credential.value.
credential.valueFrom.configMapKeyRefThe field which selects a ConfigMap key in the Helm chart release Namespace.
credential.valueFrom.configMapKeyRef.nameThe name of the ConfigMap.
credential.valueFrom.configMapKeyRef.keyThe name of the key from which the value is retrieved.
credential.valueFrom.secretKeyRefThe field which selects a Secret key in the Helm Chart release Namespace.
credential.valueFrom.secretKeyRef.nameThe name of the Secret.
credential.valueFrom.secretKeyRef.keyThe name of the key from which the value is retrieved.
credential.valueFrom.serviceRefThe field which selects a service resource in the Helm Chart release Namespace.
credential.valueFrom.serviceRef.nameThe name of the service.
credential.valueFrom.serviceRef.jsonpathThe JSONPath expression used to select the specified field value. For more information, see the User Guide.
credentialFromThe list of sources to populate credential variables on the binding action. When the key exists in multiple sources, the value associated with the last source takes precedence. Variables from the credential section override the values if duplicated keys exist.
credentialFrom.configMapRefThe ConfigMap to retrieve the values from. It must be available in the Helm chart release Namespace.
credentialFrom.configMapRef.nameThe name of the ConfigMap.
credentialFrom.secretRefThe Secret to retrieve the values from. It must be available in the Helm chart release Namespace.
credentialFrom.secretRef.nameThe name of the Secret.

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

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

Create addons repository

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:

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

See the example:

Click to copy
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:

  • HTTP/HTTPS
  • Git

NOTE: The HTTP protocol is supported only in DevelopMode. To learn more, read this document.

If you want to use an HTTP or HTTPS server, you must compress your addons to .tgz files. The repository structure looks as follows:

Click to copy
sample-addon-repository
├── {addon_x_name}-{addon_x_version}.tgz # An addon compressed to a .tgz file
├── {addon_y_name}-{addon_y_version}.tgz
├── ...
├── index.yaml # A file which defines available addons
├── index-2.yaml
└── ...

See the example of the Kyma addons repository here.

TIP: If you contribute to the Kyma addons repository, you do not have to compress your addons as the system does it automatically.

These are the allowed addon repository URLs provided in CAC or AC custom resources for HTTP or HTTPS servers:

Click to copy
apiVersion: addons.kyma-project.io/v1alpha1
kind: ClusterAddonsConfiguration
metadata:
name: addons-cfg-sample
spec:
repositories:
# HTTPS protocol
- url: "https://github.com/kyma-project/addons/releases/download/latest/index.yaml"
# HTTP protocol
- url: "http://github.com/kyma-project/addons/releases/download/latest/index.yaml"

Registration rules

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.

Addons validation

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.8.2, which checks your addons' charts. Run the Checker locally to test if your addons are valid:

Click to copy
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:

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

Provide Service Classes documentation

Using the Helm Broker, you can provision an addon which defines a Service Broker and provides its own Service Classes. If you want to provide documentation for those Service Classes, create the docs.yaml file inside the addon's chart to comply with the naming convention. The structure of this file looks as follows:

Click to copy
apiVersion: cms.kyma-project.io/v1alpha1
kind: DocsTopic
metadata:
labels:
cms.kyma-project.io/view-context: service-catalog
name: {ServiceClass ID}
spec:
displayName: {displayName}
description: {description}
sources:
- type: {type}
name: {name}
mode: {mode}
url: {{ .Values.addonsRepositoryURL }}
filter: docs/{class_name}/
___
apiVersion: cms.kyma-project.io/v1alpha1
kind: DocsTopic
metadata ...

If your addon defines a ServiceBroker, use the DocsTopic type. If your addon defines a ClusterServiceBroker, use the ClusterDocsTopic type. For more details, see the ClusterDocsTopic and DocsTopic custom resources documentation. For more information about currently supported types of the assets, read this document.

One ClusterDocsTopic or DocsTopic object corresponds to a single Service Class with the same ID as the name of the specified object. Store documentation for each Service Class in the docs/{class_name} directory which corresponds to the value of the filter parameter in the ClusterDocsTopic or DocsTopic definition.

During the provisioning process, the Helm Broker pushes the addonRepositoryURL variable into the chart. The addonsRepositoryURL points to your addon compressed to a .tgz file.

Documentation structure

Deliver documentation for your addons in Markdown files with specified metadata. To learn more about the metadata and content of the Markdown files, read this document.

Configuration

Helm Broker chart

To configure the Helm Broker 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:

Configurable parameters

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

ParameterDescriptionDefault value
ctrl.resources.limits.cpuDefines limits for CPU resources.100m
ctrl.resources.limits.memoryDefines limits for memory resources. During the clone action, the Git binary loads the whole repository into memory. You may need to adjust this value if you want to clone a bigger repository.76Mi
ctrl.resources.requests.cpuDefines requests for CPU resources.80m
ctrl.resources.requests.memoryDefines requests for memory resources.32Mi
ctrl.tmpDirSizeLimitSpecifies a size limit on the tmp directory in the Helm Pod. This directory is used to store processed addons. Eviction manager monitors the disk space used by the Pod and evicts it when the usage exceeds the limit. Then, the Pod is marked as Evicted. The limit is enforced with a time delay, usually about 10s.1Gi
global.cfgReposUrlNameSpecifies the name of the default ConfigMap which provides the URLs of addons repositories.helm-repos-urls
global.isDevelopModeDefines that each repository URL must be an HTTPS server. If set to true, HTTP servers are also acceptable.false

Etcd-stateful sub-chart

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:

Configurable parameters

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

ParameterDescriptionDefault value
etcd.resources.limits.cpuDefines limits for CPU resources.200m
etcd.resources.limits.memoryDefines limits for memory resources.256Mi
etcd.resources.requests.cpuDefines requests for CPU resources.50m
etcd.resources.requests.memoryDefines requests for memory resources.64Mi
replicaCountDefines the size of the etcd cluster.1

Custom Resource

ClusterAddonsConfiguration

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

Click to copy
kubectl get crd clusteraddonsconfiguration.addons.kyma-project.io -o yaml

Sample custom resource

This is a sample ClusterAddonsConfiguration which provides cluster-wide 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.

Click to copy
apiVersion: addons.kyma-project.io/v1alpha1
kind: ClusterAddonsConfiguration
metadata:
name: addons-cfg-sample
finalizers:
- addons.kyma-project.io
labels:
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:

ParameterMandatoryDescription
metadata.nameYESSpecifies the name of the CR.
metadata.finalizersYESSpecifies the finalizer which prevents the CR from deletion until the Controller completes the deletion logic. The default finalizer is addons.kyma-project.io.
metadata.labelsNOSpecifies a key-value pair that helps you to organize and filter your CRs. The label indicating the default addon configuration is addons.kyma-project.io/managed: "true".
spec.reprocessRequestNOAllows you to manually trigger the reprocessing action of this CR. It is a strictly increasing, non-negative integer counter.
spec.repositories.urlYESProvides the full URL to the index file of addons repositories.
status.phaseNot applicableDescribes the status of processing the CR by the Helm Broker Controller. It can be Ready, Failed, or Pending.
status.lastProcessedTimeNot applicableSpecifies the last time when the Helm Broker Controller processed the CR.
status.observedGenerationNot applicableSpecifies the most recent generation that the Helm Broker Controller observed.
status.repositories.urlNot applicableProvides the full URL to the index file with addons definitions.
status.repositories.statusNot applicableDescribes the status of processing a given repository by the Helm Broker Controller.
status.repositories.reasonNot applicableProvides the reason why the repository processing failed. Here you can find a complete list of reasons.
status.repositories.messageNot applicableProvides a human-readable message why the repository processing failed. Here you can find a complete list of messages.
status.repositories.addons.nameNot applicableDefines the name of the addon.
status.repositories.addons.versionNot applicableDefines the version of the addon.
status.repositories.addons.statusNot applicableDescribes the status of processing a given addon by the Helm Broker Controller.
status.repositories.addons.reasonNot applicableProvides the reason why the addon processing failed. Here you can find a complete list of reasons.
status.repositories.addons.messageNot applicableProvides a human-readable message on processing progress, success, or failure. Here you can find a complete list of messages.

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

These components use this CR:

ComponentDescription
Helm BrokerFetches cluster-wide addons provided by this CR.

AddonsConfiguration

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:

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

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.

Click to copy
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:

ParameterMandatoryDescription
metadata.nameYESSpecifies the name of the CR.
metadata.namespaceYESSpecifies the Namespace in which the CR is available.
metadata.finalizersYESSpecifies the finalizer which prevents the CR from deletion until the Controller completes the deletion logic. The default finalizer is addons.kyma-project.io.
metadata.labelsNOSpecifies a key-value pair that helps you to organize and filter your CRs. The label indicating the default addon configuration is addons.kyma-project.io/managed: "true".
spec.reprocessRequestNOAllows you to manually trigger the reprocessing action of this CR. It is a strictly increasing, non-negative integer counter.
spec.repositories.urlYESProvides the full URL to the index file of addons repositories.
status.phaseNot applicableDescribes the status of processing the CR by the Helm Broker Controller. It can be Ready, Failed, or Pending.
status.lastProcessedTimeNot applicableSpecifies the last time when the Helm Broker Controller processed the CR.
status.observedGenerationNot applicableSpecifies the most recent generation that the Helm Broker Controller observed.
status.repositories.urlNot applicableProvides the full URL to the index file with addons definitions.
status.repositories.statusNot applicableDescribes the status of processing a given repository by the Helm Broker Controller.
status.repositories.reasonNot applicableProvides the reason why the repository processing failed. Here you can find a complete list of reasons.
status.repositories.messageNot applicableProvides a human-readable message why the repository processing failed. Here you can find a complete list of messages.
status.repositories.addons.nameNot applicableDefines the name of the addon.
status.repositories.addons.versionNot applicableDefines the version of the addon.
status.repositories.addons.statusNot applicableDescribes the status of processing a given addon by the Helm Broker Controller.
status.repositories.addons.reasonNot applicableProvides the reason why the addon processing failed. Here you can find a complete list of reasons.
status.repositories.addons.messageNot applicableProvides a human-readable message on processing progress, success, or failure. Here you can find a complete list of messages.

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

These components use this CR:

ComponentDescription
Helm BrokerFetches Namespace-scoped addons provided by this CR.