Home

Awesome

NDS Labs Service Catalog

This repository contains specifications for services supported in the National Data Service NDS Labs platform. Service specifications include the following information:

Specifications for a given service stack are organized into subdirectories.

Example specification

{
    "id": "uniqueid",
    "key": "shortname",
    "label": "My Service Display Name",
    "maintainer": "Maintainer name and email",
    "info": "URL",
    "logo": "URL",
    "image": {
        "registry" : "docker.io",
        "name" : "ndslabs/myimage",
        "tags" : [ "latest", "v1", "v2", "v3" ]
    },
    "display": "stack",
    "access": "external",
    "description": "Description of my service",
    "depends": [
        {
            "key": "dependencykey",
            "required": true,
            "shareConfig": false
        }
    ],
    "config":  [
        {
            "name": "ENV_VAR",
            "value": "value",
            "label": "Label",
            "canOverride": true,
            "isPassword": true
        }
    ],
    "command": [ "somecommand" ],
    "args" : [
        "-someargument"
    ],
    "ports": [
        {
            "port": 80,
            "protocol": "http"
        },
        {
            "port": 8000,
            "protocol": "http"
        }
    ],
    "repositories":  [
        {
            "url": "https://github.com/golang/example",
            "type": "git"
        }
    ],
    "developerEnvironment" : "devenvId",
    "volumeMounts":[
       { 
            "name": "data",
            "mountPath": "/data"
       },
       {
            "name": "other",
            "mountPath": "/other"
       }   
    ],
    "readinessProbe" : {
        "type" : "http",
        "path" : "/favicon.ico",
        "port" : 80,
        "initialDelay": 10,
        "timeout" : 600
    },
    "resourceLimits": {
        "cpuMax": 1000,
        "cpuDefault": 100,
        "memMax": 1024,
        "memDefault": 512
    },
    "tags": [
        "tagId1",
        "tagId2"
    ]
}

Documentation

Service

FieldTypeDescription
keystringUnique identifier for the service (alpha-numeric only, lowercase)
labelstringLabel used for display
descriptionstringDescription used for display
maintainerstringmaintainer name and email
infostringOptional URL to help page for this service
logostringOptional URL to logo for service
imageServiceImageDocker image information (see below)
displaystring"stack" => show this service as a top-level stack; "standalone" => show this service as a standalone (hidden behind the checkbox in the UI) otherwise, do not display this service; only allow it to be added to other stacks
accessstring"internal" => allow this service to receive requests only from within the cluster; "external" => allow this service to receive requests from outside of the cluster (usually a browser); otherwise, do not allow any communication to be received by this service
dependsServiceDepencency[]List of dependencies (see below)
configConfig[]List of configuration options (see below)
commandstring[]Optional commands to be passed to the container.
argsstring[]Optional arguments to be passed to the container
portsPort[]List of ports exposed by this service (see below)
repositoriesRepository[]List of source code repositoriues associated with service
volumeMountsVolumeMount[]Defines volume requirements for the service. Currently only one mount is supported per service.
readinessProbeReadyProbeProbe used to determine when a service is ready to receive traffic
resourceLimitsResourceLimit[]Required CPU and memory requirements for application.
developerEnvironmentstringUnique key of associated developer environment
tagsstring[]List of tags

ServiceImage

FieldTypeDescription
registrystringRegistry URL (for now, only docker)
namestringDocker image name
tagsstring[]List of tags

ServiceDependency

FieldTypeDescription
keystringUnique ID of dependency
requiredboolWhether dependency is required (default: false)
shareConfigboolWhether config is shared with other services (default:false)

Config

FieldTypeDescription
namestringEnvironment variable name
valuestringEnvironment variable value
labelstringLabel to display in UI
canOverrideboolWhether user can override value
isPasswordboolWhether value is a password

Port

FieldTypeDescription
portintPort number
protocolstringProcotol (http or tcp)

VolumeMount

FieldTypeDescription
namestringUnique name for volume
mountPathstringMount path in container

ReadyProbe

FieldTypeDescription
typestringProbe type: must be one of "http" or "tcp"
pathstringProbe path for HTTP probes
portintProbe port
initialDelayintHow long to wait before starting probe
timeoutintHow long to wait before timing out

Repository

FieldTypeDescription
urlstringRespository URL
typestringRepository type (git, svn or hg)

ResourceLimit

Individual NDS Labs projects are configured with specific memory and CPU limits. Because of this, all services must declare memory and CPU requirements to enable scheduling and resource constraint enforcement. These values relate directly to Kubernetes limit ranges and resource requests.

FieldTypeDescription
cpuMaxStringMaximum expected CPU utilization in millicores
cpuDefaultStringInitial CPU utilization in millicores
memMaxStringMaximum memory in Mb
memDefaultStringInitial memory in Mb

Adding a New Spec

To add a new service to NDS Labs, you only need:

For some tutorials on how to add a new spec to a running instance of NDS Labs, see developer-tutorial.

Contributing a Spec

Have you created and tested a spec of your own? Want to see it end up in NDS Labs for others to use?

That's great!

Share Your Spec

Share the JSON spec you have created with other users of NDS Labs!

This will enable them to add the JSON spec using the CLI:

ndslabsctl add service -f path/to/spec/file.json

They will then be able to run your custom service using your pushed Docker image.

Make a Pull Request

To contribute your service back to our code base:

We will review and give feedback on your pull request before merging it in.

For more information on our Developer Workflows, see Developer Workflows.

See Also