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:
File name | Description |
---|---|
Chart.yaml |
The basic application metadata in the standard Helm format. |
gbear/appmetadata.yaml |
Great Bear specific metadata. |
templates/ |
Directory of standard Helm templates for the Kubernetes resources that define your application. |
charts/ |
Directory of Helm charts that are used as embedded dependencies. |
values.yaml |
The default configuration values (as in standard Helm format). |
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:
Field name | Description | Example |
---|---|---|
apiVersion |
Always v2 |
v2 |
name |
The name of the Great Bear Application Package (the middle section from the application identifier constructed like <tenant-name>/<application-name>/<version> . |
my-chart |
version |
The version number of the Application Package. Versions must follow the SemVer 2 specification. | 0.0.1 |
description |
Short description of the application. This is shown in the Application Store if no description is provided in the appmetadata.yaml . |
Demo application. |
dependencies |
List of other charts to install as part of this package. | [] |
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. Likepostgres.image.tag
. Defaults toconfig.{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 correlatingtype
field below. For example: a number for NodePortvalue: 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 thevalue
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"