Blueprints

Introduction

An application blueprint is a packaged tarball file (*.tar.gz) that contains the application manifest YAML file (jovianx.yaml) and Helm Charts. The application manifest defines the components used by the application. The components can be Helm Charts, or other cloud managed services. JovianX uses the Application Blueprint to create resources and set up services when a new account signs up.

Blueprint Structure

The application blueprint contains the following:

  1. Application Manifest - The application manifest is a YAML file named jovianx.yaml. The manifest defines all the resources needed for creation of a new SaaS account. For example Kubernetes Helm Charts, DynamoDB, CloudDNS or other cloud managed services.

  2. Helm Charts - The blueprint can also include the Helm Charts that are used for creation of application services.

Application Manifest(jovianx.yaml)

The application manifest is a YAML file that describes the application. JovianX uses the manifest to create the needed resources and services when a new account signs-up.

A basic template of an application manifest looks as following:

jovianx.yaml
# v1 - JovainX API Compatability
jovianx_api_version: v1
# string - Name of this SaaS application
application_name: '<APP-NAME>'
# semantic versioning - version of this JovianX blueprint
version: <SEM-VERSION>
# string - Name of a component to be used a main application entry point
main_endpoint_component: '<COMPONENT-NAME>'
# Components section defines all application components and their helm chart implementations
components:
- name: '<COMPONENT-NAME>'
version: <COMPONENT-SEMVER>
provider: helm_chart
helm_chart_name: <PATH/TO/HELM/CHART>
helm_set:
# List of key-value pairs to pass to helm on account creation
- key: '<SET-KEY>'
value: '<SET-VALUE>'
endpoints:
- name: '<ENTRYPOPINT-NAME>'
type: entry_point
service_name: '<KUBERNETS-SERVICE-NAME>'
port: <KUBERNETES-SERVICE-PORT>
path: '<KUBERNETES-SERVICE-PATH>'
# Settings Descripts define user inputs and
settings_descriptors:
# list of descriptos
- name: <DESCRIPTOR-NAME>
display: '<A QUESTION TO ASK THE USER ON SIGN-UP>'
input_type: string
default: '<DEFAULT ANSWER>'
components:
- name: '<COMPONENT-NAME>' # Provide value to this componet
helm_set:
- key: '<SET-KEY>'

Creating Application Blueprint

To create an application blueprint archive the application manifest and helm charts into a blueprint tar.gz

$ tar -cf <BLUEPRINT-NAME> jovianx.yaml <HELM-CHART> ...

Note: The Helm Charts should be open, untar direcotry.

Example: the following directory has an application manifest jovianx.yaml and a Chart my-helm-chart

├── my-helm-chart
│   ├── charts
│   ├── templates
│   ├── Chart.yaml
│   └── values.yaml
└── jovianx.yaml

To create an application blueprint for the directory use the following command:

$ tar -cf blueprint-1.0.0.tar.gz jovianx.yaml my-helm-chart

Upload Application Blueprint

Upload Blueprint via Web UI

To upload your application blueprint to JovianX via the web console:

  1. Navigate to Blueprints page

  2. Click on Upload a new Blueprint bar

  3. Click on Choose blueprint tar.gz file

  4. Click on Upload to upload your blueprint

Once the blueprint is upload you will be able to find it in the blueprints list, and view the application manifest.

Upload Blueprint via CURL(CI)

To upload your application blueprint to JovianX via an automated CI process or from command line, you will need to find your API Access Key and API Secret. You can find both in Upload a new Blueprint bar under Blueprints navigation bar.

curl -u '<ACCOUNT-API-ACCESS-KEY>:<API-SECRET>' -F 'file=@<PATH/TO/BLUEPRINT/FILE.TAR.GZ>' 'https://<ACCOUNT-API-PATH>/api/v1/upload_blueprint?make_default=true'

Application Manifest (jovianx.yaml) Reference

Application Manifest Root

Key

Description

jovianx_api_version

Description: Version of the JovianX Manifest API.

Parent: Root Type: v1

Required

application_name

Description: Name of the SaaS Application.

Parent: Root Type: string

Required

version

Description: Version of the JovianX blueprint.

Parent: Root Type: semantic version

Required

main_endpoint_component

Description: Main application end-point.

Parent: Root Type: string

Required

components

Description: components section is a list of all components(Helm Charts or Cloud Managed Services) used as part of the application, and their settings.

Parent: Root Type: list Required

application_launch_timeout

Description: Application timeout configuration

Parent: Root Type: collection

Optional

status_check: failure_threshold:

Description: How many status error detection are accepted before changing the app status to error.

Parent: Root Type: collection

Default: 1

Optional

agents

Description: The list of agents

Parent: Root Type: list

Optional

settings_descriptors

Description: A list of settings descriptors

Parent: Root Type: list

Optional

hooks

Description: List of hooks

Parent: Root Type: list

Optional

Components

Components section is a list of all components used as part of the application, and their settings. Components are Helm Charts or Cloud Managed Services.

Key

Description

name

Description: Name of the component

Parent: components Type: string

Example: name: 'my-component'

Required

version

Description: Version of the component

Parent: components Type: semantic_version

Example: version: 14.5.2

Required

provider

Description: Provider that implements the component

Parent: components Type: Select Options:

  • helm_chart

  • [Additional providers available in private alpha]

Example: provider: helm_chart

Required

helm_chart_name

Description: Path to unarchived helm chart within the blueprint

Parent: components Type: string

Example: helm_chart_name: /my-helm-chart/

Required for helm_chart provider

helm_values_file

Description: Path to values.yaml file for the component

Parent: components Type: string

Example: helm_values_file: /my-helm-chart/my-values.yaml

Optional for helm_chart provider

helm_set

Description: List of helm set key and value pairs

Parent: components Type: list

Example:

helm_set:

- key: image

value: registry.hub.docker.com/my-company/image

Optional for helm_chart provider

Settings Descriptors

Key

Description

name

Type: string

display

Type: string

input_type

value: string | number | radio | select

default

Type: string

description_title

Type: string

select_options

Type: list

Hooks

Key

Description

pre_install

Description: List hooks that are executed before app install

Parent: hooks Type: list

Optional

post_install

Description: List of hooks that are executed after app install

Parent: hooks Type: list

Optional

Hook

Key

Description

name

on_failure

timeout

provider

image

command

args

env

Variables

Account

{{ account://vendor_company }}
{{ account://end_company }}
{{ account://account_api_key }}
{{ account://admin_email }}
{{ account://admin_password }}
{{ account://api_host }}
example
components:
- name: node-component
version: 1.0.0
provider: helm_chart # helm_chart | docker
helm_chart_name: node-chart
helm_values_file: values-jovianx.yaml
helm_set:
- key: repository
value: https://gitlab.com/jovianx-saas-platform/hello-world-app.git
- key: replicas
value: 1
- key: vendor_company
value: '{{ account://vendor_company }}'
- key: end_company
value: '{{ account://end_company }}'
- key: account_api_key
value: '{{ account://account_api_key }}'
- key: admin_email
value: '{{ account://admin_email }}'
- key: admin_password
value: '{{ account://admin_password }}'
- key: api_host
value: '{{ account://api_host }}'

Application