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:
- 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.
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
- The Helm Broker watches for ClusterAddonsConfiguration CRs in a given cluster.
- The user creates a ClusterAddonsConfiguration CR.
- The Helm Broker fetches and parses the data of all addon repositories defined in the ClusterAddonsConfiguration CR.
- The Helm Broker creates a ClusterServiceBroker. There is always only one ClusterServiceBroker, even if there are multiple ClusterAddonsConfiguration CRs.
NOTE: The Helm Broker is the sole component that manages the Cluster Service Broker. The user should not create or delete this resource.
- The Service Catalog fetches services that the ClusterServiceBroker exposes.
- The Service Catalog creates a ClusterServiceClass for each service received from the ClusterServiceBroker.
Namespace-scoped addons flow
- The Helm Broker watches for AddonsConfiguration CRs in all Namespaces.
- The user creates an AddonsConfiguration CR in a given Namespace.
- The Helm Broker fetches and parses the data of all addon repositories defined in the AddonsConfiguration CR.
- 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.
NOTE: The Helm Broker is the sole component that manages the Service Broker. The user should not create or delete this resource.
- The Service Catalog fetches the services that the Service Broker exposes.
- The Service Catalog creates a ServiceClass for each service received from the Service Broker.
Provisioning and binding
After you register your addons in the Service Catalog, you can provision and bind Service Classes that your addons provide.
- Select a given addon Service Class from the Service Catalog.
- Provision this Service Class by creating its ServiceInstance in a given Namespace.
- Bind your ServiceInstance to a service or a Function.
- The service or Function calls a given addon.
Architecture deep dive
This document describes the Helm Broker workflow in details, including the logic of its inner components, namely the Controller and Broker.
- The Controller watches for ClusterAddonsConfiguration (CAC) and AddonsConfiguration (AC) custom resources (CRs).
- The user creates, updates, or deletes CAC or AC custom resources.
- 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.
- The Controller saves the fetched addons to the storage.
- 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.
- The Broker component fetches addons from the storage and exposes them to the Service Catalog.
- 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:
- If a given CR is in the Ready state, the Controller removes it from the storage.
- 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.
- 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:
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.
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 Name | Required | Description |
---|---|---|
name | Yes | The name of the addon. |
version | Yes | The version of the addon. It is a broker service identifier. |
id | Yes | The broker service identifier. |
description | Yes | The short description of the service. |
displayName | Yes | The display name of the addon. |
tags | No | Keywords describing the provided service, separated by commas. |
bindable | No | The field that specifies whether you can bind a given addon. |
providerDisplayName | No | The name of the upstream entity providing the actual service. |
longDescription | No | The long description of the service. |
documentationURL | No | The link to the documentation page for the service. |
supportURL | No | The link to the support page for the service. |
imageURL | No | The URL to an image. You must provide the image in the SVG format. |
labels | No | Key-value pairs that help you to organize your project. Use labels to indicate different elements, such as Namespaces, services, or teams. |
bindingsRetrievable | No | The 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 . |
planUpdatable | No | The field that specifies whether instances of this service can be updated to a different plan. The default value is false |
requires | No | The list of permissions the user must grant to the instances of this service. |
provisionOnlyOnce | No | The 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 theprovisionOnlyOnce:true
label only if provisionOnlyOnce is set totrue
.
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 to0
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 Name | Required | Description |
---|---|---|
name | Yes | The name of the plan. |
id | Yes | The ID of the plan. |
description | Yes | The description of the plan. |
displayName | Yes | The display name of the plan. |
bindable | No | The field that specifies whether you can bind an instance of the plan or not. The default value is false . |
free | No | The 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 themeta.yaml
file that your plan is bindable, you must also create abind.yaml
file. For more information, read about binding addons.values.yaml
file - provides the default configuration values in a given plan for the chart definition located in thechart
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 the 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
file, which provides information on how documentation for the addon is uploaded.
Because you can install the Helm Broker as a ClusterServiceBroker or as a ServiceBroker, documentation for addons is provided using either ClusterAssetGroups or AssetGroups custom resources, respectively.
The meta.yaml
file contains the specification of the ClusterAssetGroup or AssetGroup. The example structure of the meta.yaml
file looks as follows:
Field Name | Required | Description |
---|---|---|
docs[] | Yes | Contains the definitions of documentation. |
docs[].template | Yes | Contains the specification of the ClusterAssetGroup or AssetGroup. |
docs[].template.displayName | Yes | Specifies the display name of the ClusterAssetGroup or AssetGroup. |
docs[].template.description | Yes | Provides the description of the ClusterAssetGroup or AssetGroup. |
docs[].template.sources[] | Yes | Contains the definitions of assets for an addon. |
docs[].template.sources[].type | Yes | Defines the type of the asset. |
docs[].template.sources[].name | Yes | Defines a unique identifier of a given asset. It must be unique for a given asset type. |
docs[].template.sources[].mode | Yes | Specifies if the asset consists of one file or a set of compressed files in the ZIP or TAR format. Use single for one file and package for a set of files. |
docs[].template.sources[].url | Yes | Specifies the location of a file. |
docs[].template.sources[].filter | Yes | Specifies the directory from which the documentation is fetched. The regex used in the filter must be RE2-compliant. |
NOTE: Currently you can provide only one entry in the
docs
array.
See the example of the docs
directory with documentation for the testing addon. Read also how to provide addons 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:
# bind.yamlcredential: - 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 Name | Description |
---|---|
credential | The list of credential variables returned during the binding action. |
credential.name | The name of a given credential variable. |
credential.value | The variable value. You can also use the Helm Chart templating directives. This field is interchangeable with credential.valueFrom. |
credential.valueFrom | The source of the given credential variable's value. This field is interchangeable with credential.value. |
credential.valueFrom.configMapKeyRef | The field which selects a ConfigMap key in the Helm chart release Namespace. |
credential.valueFrom.configMapKeyRef.name | The name of the ConfigMap. |
credential.valueFrom.configMapKeyRef.key | The name of the key from which the value is retrieved. |
credential.valueFrom.secretKeyRef | The field which selects a Secret key in the Helm Chart release Namespace. |
credential.valueFrom.secretKeyRef.name | The name of the Secret. |
credential.valueFrom.secretKeyRef.key | The name of the key from which the value is retrieved. |
credential.valueFrom.serviceRef | The field which selects a service resource in the Helm Chart release Namespace. |
credential.valueFrom.serviceRef.name | The name of the service. |
credential.valueFrom.serviceRef.jsonpath | The JSONPath expression used to select the specified field value. For more information, see the User Guide. |
credentialFrom | The 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.configMapRef | The ConfigMap to retrieve the values from. It must be available in the Helm chart release Namespace. |
credentialFrom.configMapRef.name | The name of the ConfigMap. |
credentialFrom.secretRef | The Secret to retrieve the values from. It must be available in the Helm chart release Namespace. |
credentialFrom.secretRef.name | The name of the Secret. |
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-namecredentialFrom: - 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. Theredis-svc
Service runs this expression. - A
REDIS_PASSWORD
key with a value selected by theredis-password
key from theredis-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.
Test addons
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.
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:
apiVersion: v1entries: {addon_name}: - name: {addon_name} description: {addon_description} version: {addon_version}
See the example:
apiVersion: v1entries: 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
- Mercurial
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/v1alpha1kind: ClusterAddonsConfigurationmetadata: name: addons-cfg-samplespec: repositories: - url: "https://{host}/{project}/addons/index.yaml" secretRef: name: data---apiVersion: v1kind: Secretmetadata: name: datatype: OpaquestringData: 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:
- HTTP/HTTPS
- Git SSH
- S3
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.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-brokerkubectl logs -n kyma-system $HELM_BROKER_POD_NAME helm-broker
Provide documentation for your addon
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 your own documentation
- Use external 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.
- Provide your own documentation
- Use external documentation
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:
Parameter | Description | Default value |
---|---|---|
ctrl.resources.limits.cpu | Defines limits for CPU resources. | 100m |
ctrl.resources.limits.memory | Defines 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.cpu | Defines requests for CPU resources. | 80m |
ctrl.resources.requests.memory | Defines requests for memory resources. | 32Mi |
ctrl.tmpDirSizeLimit | Specifies 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.cfgReposUrlName | Specifies the name of the default ConfigMap which provides the URLs of addons repositories. | helm-repos-urls |
global.isDevelopMode | Defines whether to accept URL prefixes from the global.urlRepoPrefixes.additionalDevelopMode list. If set to true , the Helm Broker accepts the prefixes from the list. | false |
global.urlRepoPrefixes.default | Defines a list of accepted prefixes for repository URLs. | 'https://', 'git::', 'github.com/', 'bitbucket.org/' |
global.urlRepoPrefixes.additionalDevelopMode | Defines a list of accepted prefixes for repository URLs when develop mode is enabled. | 'http://' |
additionalAddonsRepositories.myRepo | Provides a map of additional ClusterAddonsConfiguration repositories to create by default. The key is used as a name and the value is used as a URL for the repository. | github.com/myOrg/myRepo//addons/index.yaml |
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:
Parameter | Description | Default value |
---|---|---|
etcd.resources.limits.cpu | Defines limits for CPU resources. | 200m |
etcd.resources.limits.memory | Defines limits for memory resources. | 256Mi |
etcd.resources.requests.cpu | Defines requests for CPU resources. | 50m |
etcd.resources.requests.memory | Defines requests for memory resources. | 64Mi |
replicaCount | Defines 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:
kubectl get crd clusteraddonsconfiguration.addons.kyma-project.io -o yaml
NOTE: Only users with the kyma-admin role can modify the ClusterAddonsConfiguration CR. For more information, read about roles in Kyma.
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.
apiVersion: addons.kyma-project.io/v1alpha1kind: ClusterAddonsConfigurationmetadata: 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.urlstatus: 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:
Parameter | Required | Description |
---|---|---|
metadata.name | Yes | Specifies the name of the CR. |
metadata.finalizers | Yes | Specifies the finalizer which prevents the CR from deletion until the Controller completes the deletion logic. The default finalizer is addons.kyma-project.io . |
metadata.labels | No | Specifies a key-value pair that helps you to organize and filter your CRs. The label that indicates the default addon configuration is addons.kyma-project.io/managed: "true" . |
spec.reprocessRequest | No | Allows you to manually trigger the reprocessing action of this CR. It is a strictly increasing, non-negative integer counter. |
spec.repositories.url | Yes | Provides the full URL to the index file of addons repositories. |
spec.repositories.secretRef.name | No | Defines the name of a Secret which provides values for the URL template. |
spec.repositories.secretRef.namespace | No | Defines the Namespace which stores a Secret that provides values for the URL template. |
status.phase | Not applicable | Describes the status of processing the CR by the Helm Broker Controller. It can be Ready , Failed , or Pending . |
status.lastProcessedTime | Not applicable | Specifies the last time when the Helm Broker Controller processed the CR. |
status.observedGeneration | Not applicable | Specifies the most recent generation that the Helm Broker Controller observed. |
status.repositories.url | Not applicable | Provides the full URL to the index file with addons definitions. |
status.repositories.status | Not applicable | Describes the status of processing a given repository by the Helm Broker Controller. |
status.repositories.reason | Not applicable | Provides the reason why the repository processing failed. See the complete list of reasons for reference. |
status.repositories.message | Not applicable | Provides a human-readable message why the repository processing failed. See the complete list of messages for reference. |
status.repositories.addons.name | Not applicable | Defines the name of the addon. |
status.repositories.addons.version | Not applicable | Defines the version of the addon. |
status.repositories.addons.status | Not applicable | Describes the status of processing a given addon by the Helm Broker Controller. |
status.repositories.addons.reason | Not applicable | Provides the reason why the addon processing failed. See the complete list of reasons for reference. |
status.repositories.addons.message | Not applicable | Provides a human-readable message on processing progress, success, or failure. See the complete list of messages for reference. |
NOTE: The Helm Broker Controller automatically adds all parameters marked as Not applicable to the ClusterAddonsConfiguration CR.
Related resources and components
These components use this CR:
Component | Description |
---|---|
Helm Broker | Fetches 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:
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/v1alpha1kind: AddonsConfigurationmetadata: 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.urlstatus: 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:
Parameter | Required | Description |
---|---|---|
metadata.name | Yes | Specifies the name of the CR. |
metadata.namespace | Yes | Specifies the Namespace in which the CR is available. |
metadata.finalizers | Yes | Specifies the finalizer which prevents the CR from deletion until the Controller completes the deletion logic. The default finalizer is addons.kyma-project.io . |
metadata.labels | No | Specifies 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.reprocessRequest | No | Allows you to manually trigger the reprocessing action of this CR. It is a strictly increasing, non-negative integer counter. |
spec.repositories.url | Yes | Provides the full URL to the index file of addons repositories. |
spec.repositories.secretRef.name | No | Defines the name of a Secret which provides values for the URL template. |
spec.repositories.secretRef.namespace | No | Defines the Namespace which stores a Secret that provides values for the URL template. |
status.phase | Not applicable | Describes the status of processing the CR by the Helm Broker Controller. It can be Ready , Failed , or Pending . |
status.lastProcessedTime | Not applicable | Specifies the last time when the Helm Broker Controller processed the CR. |
status.observedGeneration | Not applicable | Specifies the most recent generation that the Helm Broker Controller observed. |
status.repositories.url | Not applicable | Provides the full URL to the index file with addons definitions. |
status.repositories.status | Not applicable | Describes the status of processing a given repository by the Helm Broker Controller. |
status.repositories.reason | Not applicable | Provides the reason why the repository processing failed. See the complete list of reasons for reference. |
status.repositories.message | Not applicable | Provides a human-readable message why the repository processing failed. See the complete list of messages for reference. |
status.repositories.addons.name | Not applicable | Defines the name of the addon. |
status.repositories.addons.version | Not applicable | Defines the version of the addon. |
status.repositories.addons.status | Not applicable | Describes the status of processing a given addon by the Helm Broker Controller. |
status.repositories.addons.reason | Not applicable | Provides the reason why the addon processing failed. See the complete list of reasons for reference. |
status.repositories.addons.message | Not applicable | Provides a human-readable message on processing progress, success, or failure. See the complete list of messages for reference. |
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:
Component | Description |
---|---|
Helm Broker | Fetches Namespace-scoped addons provided by this CR. |
Troubleshooting
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.