staroid.yaml

Staroid reads a staroid.yaml file from the repository. It finds the files in the following order.

  1. /staroid.yaml

  2. /.staroid.yaml

  3. /.staroid/staroid.yaml

The file is an entry point to release the project to Staroid cloud platform.

apiVersion: beta/v1
starRank:
  rate: 1.0                           # Community rate >= 1.0. Defaults to '1.0'. See https://staroid.com/site/starrank.
  upstream:                           # Optional upstream projects to fund.
  - project:                          # Github project owner/name. e.g. staroids/hello-world.
    weight:                           # weight for this project.
build:                                # Currently, 'skaffold' is a supported value.
  skaffold:                           # Run skaffold to deploy the project.
    file: skaffold.yaml               # locates the skaffold.yaml relative to workspace. Defaults to 'skaffold.yaml'.
    profile:                          # Name of a profile to use.
ingress:                              # Ingress configures https endpoints.
- serviceName:                        # Name of a Service to connect. Defaults to 'service'.
  port:                               # Port number of the service. Defaults to '8080'.
  hideOpenButton:                     # Hide 'Open' button on management console. For example, in case of ingress is serving API endpoint instead of web page. Defaults to 'false'.
deploy:                               # Deploy configures various parameters required when launch.
  implements:                         # Name of the project that this project is compatible with. e.g. 'org1/project1'.
  dependencies:                       # List of dependencies. Defaults to empty list.
  - project:                          # (Required) Project name. e.g. 'org1/project1'.
    level:                            # (Required) 'REQUIRED' or 'OPTIONAL'
  paramGroups:                        # List of parameter groups to be shown on the Launch dialog.
  - name:                             # (Required) Name of parameter group.
    collapsed: false                  # Parameter group will be displayed in collapsed state when 'true'. Defaults to 'false'.
    params:                           # (Required) List of parameter values.
    - name:                           # (Required) Name of parameter.
      description:                    # Description of this parameter.
      type:                           # (Required) 'NUMBER', 'STRING', 'CPU', 'MEMORY'. 'NUMBER' for integer or floating point numbers, 'STRING' for string value. 'CPU' and 'MEMORY' for substitute resource requests and limits.
      optional: false                 # 'true' when the parameter is optional. Defaults to 'false'. 'defaultValue' field must be defined when this value is 'true'.
      defaultValue:                   # (Required when 'optional' is 'true'). Default value of this field.
      options:                        # When defined, Launch dialog shows options on dropdown instead of input field.
      - name:                         # Name of the option item.
        value:                        # Value of the option item. When not defined, name becomes the value.
      range:                          # Define valid range of value when type is 'NUMBER'. Define valid range of length when type is 'STRING'. When the type is 'CPU', unit of range is number of CPU (core). When the type is 'MEMORY', unit is 1,000,000 byte. "[,]" inclusive range, "(,)" for exclusive range. e.g. "[1,10]", "[3,7)"".
      pattern:                        # Regex pattern to validate value.
      paths: []                       # List of target path of the kubernetes resource to substitute value. Path format is '<Kind>:<Name>:<Json path>'. e.g. 'Pod:my-pod:spec.containers[0].envs[0].value'

You can use an online Validator to validate staroid.yaml file.

starRank

starRank.rate

This field decide the Community rate. The Community rate is a multiplier to the Computing rate, valid >= 1.0.

This field takes effect from the default (usually master) branch of the repository. This field is ignored on staroid.yaml file in other branches.

The value need to be same or greater than its source repository. For example, if project F is fork of project S, and rate of project S is 1.5, rate of Project F should be 1.5 or greater.

See also

See StarRank to know how Community rate works

starRank.upstream

List of projects to fund. When defined, funds will be distributed to the listed projects based on weights. If upstream is not defined, funds will go to the current projects (and its original project in case of the fork).

upstream:
- project:
  weight:
project

A string value in <org>/<project> format. For example myorg/myproj.

weight

Positive number

build

Currently ‘skaffold’ is a supported value.

ingress

Ingress creates https endpoint and connect your Kubernetes Service. Currently, only the first item on the list is valid.

The Service configured here will be the main entry point to the application when the user launches an instance.

See Service to get ingress urls of multiple services in the instance.

deploy

deploy.implements

If this project implements the same functionality to the original project (e.g fork), this field can be set to name of the original project in <org>/<project> format. For example myorg/myproj.

Then, any other projects that have the original project in its dependencies list can those this project as well, on the Launch dialog as a dependency.

deploy.dependencies

List of dependency. When defined, the Launch dialog will ask to choose running instnace of dependencies from the same cluster.

dependencies:
- project:
  level:
project

A string value in <org>/<project> format. For example myorg/myproj.

level

‘REQUIRED’ or ‘OPTIONAL’. When ‘REQUIRED’, the Launch dialog will not allow launch this project unless an instance of the dependency project is selected.

deploy.paramGroups

List of parameter group. The Launch dialog will display parameters, get value from user and substitute Kubernetes resource manifest fields defined in paths before apply.

paramGroups
- name:
  collapsed: false
  params: []

Tip

Use Validator to live test how the Launch dialog will display your parameters and how it will substitute Kubernetes resource manifest vlaues.

name

A name of this parameter group.

collapsed

When ‘true’, this parameter group will be displayed in collapsed state by default in the Launch dialog. This is useful when all parameters in this group are optional.

params

List of parameters to substitute Kubernetes resource manifests before apply. The Launch dialog will display input field for each parameter defined in the list.

params:
- name:
  description:
  type:
  optional: false
  defaultValue:
  range:
  pattern:
  paths: []
name

A name of this paramter.

description

Put description of this paramter to be displayed in the Launch dialog.

type

‘NUMBER’, ‘STRING’, ‘CPU’, ‘MEMORY’.

In case of ‘NUMBER’, integer (e.g. 123, -123) and floating point number (e.g. 1.23, -1.23) are valid.

‘CPU’ and ‘MEMORY’ are for resource requests and limits. For example, 2, 0.5, 500m are valid ‘CPU’ value. 100Mi, 200M, 1G, 2Gi are valid ‘MEMORY’ value.

optional

When ‘true’, defaultValue is required. Default to ‘false’.

defaultValue

The Launch dialog will set a defaultValue for the input field. This field is optional when optional is ‘false’.

options

The Launch dialog will show dropdown list instead of the input field when defined.

For example

options:
- name: Small
  value: 1G
- name: Large
  value: 10G

When value is not defined, name becomes the value. For example

options:
- name: yes
- name: no
range

When type is ‘NUMBER’, this field validates range of the number value. When type is ‘STRING’, this field validates range of the length of string value. When type is ‘MEMORY’, this unit of range is 1,000,000. For example [100,200] is validating memory amount between 100M and 200M

"[,]" for inclusive range, "(,)" for exclusive range. You can also mix them. For examples "[1,3]", "(2,10)", "[-10,10)", "(-1.5,3.0]", … are valid.

This field is optional. When not defined, no validation is performed.

Attention

Make sure double quote(") your range value.

pattern

Regex expression to validate the value. For example "[a-z]+" for lowercase alphabet as a valid input for this parameter.

This field is optional. When not defined, no validation is performed.

This field is ignored when type is ‘CPU’ or ‘MEMORY’.

Attention

Make sure double quote(") your regex value.

paths

List of path to the Kubernetes resource manifest field to substitute.

<Kind>:<Name>:<JsonPath>

For example,

paths:
  - "Pod:my-pod:spec.containers[0].envs[1].value"
  - "ConfigMap:my-conf:data.key1"

staroid.yaml examples

Minimal configuration

apiVersion: beta/v1
build:
  skaffold: {}

Community rate and Ingress

apiVersion: beta/v1
starRank:
  rate: 1.5
build:
  skaffold: {}
ingress:
- service: my-service
  port: 8080

Launch parameters

apiVersion: beta/v1
build:
  skaffold: {}
deploy:
  paramGroups:
  - name: Basic configuration
    params:
    - name: Color
      description: Select your color. Red or Yellow
      type: STRING
      optional: false
      pattern: "Red|Yellow"
      defaultValue: Red
      paths:
      - Deployment:server:spec.template.spec.container[0].env[0].value
  - name: Advanced configuration
    collapsed: true
    params:
    - name: Sensitivity
      description: Sensitivity between -1.5 and 1.5
      type: NUMBER
      optional: true
      defaultValue: 0.5
      range: "[-1.5,1.5]"
      paths:
      - ConfigMap:app-conf:data.sensitivity

Project Dependencies

apiVersion: beta/v1
build:
  skaffold: {}
deploy:
  dependencies:
  - project: org1/projectA
    level: REQUIRED
  - project: org2/projectB
    level: OPTIONAL
apiVersion: beta/v1
build:
  skaffold: {}
deploy:
  implements: org1/projectA