Great Bear Application Package Guide

Great Bear Application Packages are an extended version of regular Helm charts commonly used for describing a Kubernetes-native application.

A Great Bear application uses a combination of metadata from the standard Helm Chart.yaml file and the Great Bear specific description file called appmetadata.yaml contained in the gbear directory.

The best practices of getting started with creating an application package are described in the Create an Application Package section, while this section focuses on the syntax, semantics, and options of the packaging format.

Package structure

A simple Great Bear Application Package consists of the following files:

myPath
├── Chart.yaml
├── gbear
│   └── appmetadata.yaml
├── templates
│   ├── _helpers.tpl
│   ├── deployment.yaml
│   ├── service.yaml
└── values.yaml

The most important files within an application package are the following:

Helm best practices to include a README.md and LICENSE file to the package’s root apply, but Great Bear ignores these files.

Chart.yaml

The Chart.yaml file is a mandatory part of Great Bear Application packages. The following fields are required:

For details, see the Helm Documentation.

gbear/appmetadata.yaml

The other mandatory part of a Great Bear Application Package is the appmetadata.yaml file within the gbear folder. This file describes the Great Bear specific properties of the application.

Required fields

• displayname: Display name of the application in the application store.
• description: Description of application offer in the application store.

For example:

displayname: Bear Echo
description: A simple HTTP echo service, based on Python Flask.

Optional fields

• tags: list of free-form tags used by the Great Bear Application Store to group available applications. For example: [machine learning, image processing].

• architectures: List of architectures supported like [amd64, arm64v8].

• icon: URL of icon to use in the Application Store. The URL should point to a publicly available 1:1 aspect ratio PNG file. For example:

  title: Bear Echo
  description: A simple HTTP echo service, based on Python Flask.
  icon: https://raw.githubusercontent.com/FortAwesome/Font-Awesome/5.15.4/svgs/solid/tools.svg 
  

• configuration: List of configuration fields that are supplied to the application when it’s deployed. Each field is defined with an object (dictionary). For details, see User-configurable parameters.

User-configurable parameters

You can request the user to provide parameters for your application when deploying the application from the Application Store. For example, that way you can request an authentication token for the application.

Use the configuration field of the gbear/appmetadata.yaml file to specify the parameters that the user can configure when deploying your application. For example:

...
configuration:
  - name: MY_CONFIGURATION_PARAMETER
    title: This label is displayed to the user
    type: String

Each entry in the configuration list can contain the following keys:

• name: The identifier of the field.
• key: A dot-separated name where the value of this field will be added to the Helm values. Like postgres.image.tag. Defaults to config.{name} if omitted.
• title: The label of the parameter to be displayed on the Great Bear dashboard when deploying the application.
• description: The description of the parameter to be displayed on the Great Bear dashboard when deploying the application.
• value: The default value of the parameter, the type depends on the correlating type field below. For example: a number for NodePort value: 31777, or a string for other types.
• type: The type of the parameter. The type determines how the parameter input looks on the Great Bear UI. For details, see Parameter types. Default value: string.
• choices: List of options when the field is rendered as a toggle or a dropdown. For details, see Parameter types.

The following example shows a NodePort input parameter with a default value:

...
configuration:
  - name: ACCESS_PORT
    title: Access HTTP port (30000-32767)
    type: NodePort
    value: 31777

Configuration parameter types

You can use the type and choices fields of a user-configurable parameter to determine how the input of the parameter will look on the Great Bear UI. The type and choices fields are mutually exclusive, so only one of them can be used for a parameter.

type has the following possible values:

• String: A simple string, rendered as a text box. This is the default value.

• Secret: A string, rendered as a password input, for example:

  

• NodePort: A port number in the 30000-32767 range.

• Runtime: A “hidden” field which is computed during deployment based on the Go Template specified in the value field. No form field is displayed and no user input is possible, however, the template can use other field’s values and a few contextual variables injected during deployment. For details, see Runtime fields.

To display a dropdown, use the choices field instead of type, and list the options to display. If you list only the “on” and “off” options, a toggle button is displayed (choices: ["on", "off"]), for example:

The possible options should be YAML 1.1 strings, which can be easily ensured if you enclose each value in double quotes.

The following example renders a dropdown with three options, and a toggle button.

...
configuration:
  - name: EXAMPLE_DROPDOWN
    title: Example dropdown
    choices:
    - "Option 1"
    - "Option 2"
    - "Option 3"
  - name: EXAMPLE_TOGGLE
    title: Example toggle
    choices:
    - "on"
    - "off"

Runtime configuration fields

The Runtime configuration field type is a powerful tool for preparing a Helm values structure in a way that’s required by the Helm charts used, especially if you work with an existing Helm chart.

The value within the field definition is parsed at the time of deployment as a Go Template, which is the templating language used by Helm charts. The templates have access to the other user-supplied values of the other input fields, as well as to several special variables, which contain deployment information. Just like in Helm, you can also use the Sprig template functions.

The following special variables are available:

• .GB_SITE_ID: Contains the Great Bear site ID the application is deployed to.
• .GB_SITE_NAME: Contains the descriptive name of the Great Bear site the application is deployed to (name substituted at the time of deployment).
• .GB_NODE_IDS: A string that contains a JSON-serialized object (also known as a dictionary), where the keys are the node names as seen by Kubernetes, and the values are the corresponding node IDs in Great Bear.
• .GB_NODE_NAMES: A string that contains a JSON-serialized object (also known as a dictionary), where the keys are the node names as seen by Kubernetes, and the values are the corresponding descriptive node names in Great Bear (at the time of deployment).

Example

The following example configuration shows how you can use the special variables and other fields in Runtime configuration field templates. Imagine that you create a Great Bear application from two existing Helm charts, namely service1 and service2. They need to access each other with a shared credential, but the charts expect those in two different formats: service 1 wants two separate fields, while service 2 needs a : separated string with the credential. We decided to use the Site ID as a user name and an arbitrary password from the user. The configuration section of our appmetadata.yaml file looks like the following:

configuration:
  - name: PASSWORD
    title: Password
    description: Shared secret for authentication between the two service.
    type: Secret
    key: service1.password

  - name: CHART1_USER
    type: Runtime
    key: service1.username
    value: "{{ .GB_SITE_ID }}"

  - name: CHART2_SECRET
    type: Runtime
    key: service2.secret
    value: "{{ .GB_SITE_ID }}:{{ .PASSWORD }}"

If the user inputs the following data at the time of deployment:

PASSWORD: "secure"

A values.yaml structure equivalent with the one below will be passed to the application deployment on site xxx-yyy:

service1:
  username: "xxx-yyy"
  password: "secure"
service2:
  secret: "xxx-yyy:secure"