README

Nodeshift CircleCI

Build Status Coverage Status

What is it

Nodeshift is an opinionated command line application and programmable API that you can use to deploy Node.js projects to OpenShift.

Prerequisites

  • Node.js - version 10.x or greater

Install

To install globally: npm install -g nodeshift

Use with npx: npx nodeshift

or to use in an npm script

npm install --save-dev nodeshift

// inside package.json
scripts: {
  nodeshift: nodeshift
}

$ npm run nodeshift

Core Concepts

Commands & Goals

By default, if you run just nodeshift, it will run the deploy goal, which is a shortcut for running resource, build and apply-resource.

resource - will parse and create the application resources files on disk

apply-resource - does the resource goal and then deploys the resources to your running cluster

build - archives the code, creates a build config and imagestream and pushes the binary to the cluster

deploy - a shortcut for running resource, build and apply-resource

undeploy - removes resources that were deployed with the apply-resource command

.nodeshift Directory

The .nodeshift directory contains your resource fragments. These are .yml files that describe your services, deployments, routes, etc. By default, nodeshift will create a Service and DeploymentConfig in memory, if none are provided. A Route resource fragment should be provided or use the expose flag if you want to expose your application to the outside world.

Resource Fragments

OpenShift resource fragments are user provided YAML files which describe and enhance your deployed resources. They are enriched with metadata, labels and more by nodeshift.

Each resource gets its own file, which contains some skeleton of a resource description. Nodeshift will enrich it and then combine all the resources into a single openshift.yml and openshift.json(located in ./tmp/nodeshift/resource/).

The resource object's Kind, if not given, will be extracted from the filename.

Enrichers

Enrichers will add things to the resource fragments, like missing metadata and labels. If your project uses git, then annotations with the git branch and commit hash will be added to the metadata.

Default Enrichers will also create a default Service and DeploymentConfig when none are provided.

The default port value is 8080, but that can be overridden with the --deploy.port flag.

You can also override this value by providing a .nodeshift/deployment.yaml resource file

Resource Fragment Parameters

Some Resource Fragments might need to have a value set at "run time". For example, in the fragment below, we have the ${SSO_AUTH_SERVER_URL} parameter:

    apiVersion: v1
    kind: Deployment
    metadata:
        name: nodejs-rest-http-secured
    spec:
      template:
        spec:
          containers:
            - env:
              - name: SSO_AUTH_SERVER_URL
                value: "${SSO_AUTH_SERVER_URL}"
              - name: REALM
                value: master

To set that using nodeshift, use the -d option with a KEY=VALUE, like this:

nodeshift -d SSO_AUTH_SERVER_URL=https://sercure-url

Project Archive

A user can specify exactly what files would like nodeshift to include to the archive it will generate by using the files property in package.json.

If a user does not use the files property in the package.json to filter what files they would like to include, then nodeshift by default will include everything except the node_modules, .git and tmp directories.

Nodeshift will also look for additional exclusion rules at a .gitignore file if there is one. Same thing with a .dockerignore file.

If both ignore files are present, nodeshift will union them together and use that.

API

Along with the command line, there is also a public API. The API mirrors the commands.

API Docs - https://nodeshift.github.io/nodeshift/

  • resource

  • applyResource

  • build

  • deploy

  • undeploy

Options that you can specify on the command line, can also be passed as an options object to the API

All methods are Promise based and will return a JSON object with information about each goal that is run.

For example, if the deploy method was run, it would return something similar:

{
    build: {
        ... // build information
    },
    resources: [
        ... // resources created
    ],
    appliedResources: [
        ... // resources that were applied to the running cluster
    ]
}

Example Usage

const nodeshift = require('nodeshift');

// Deploy an Application
nodeshift.deploy().then((response) => {
    console.log(response);
    console.log('Application Deployed')
}).catch((err) => {
    console.log(err);
})

please note: Currently, once a route, service, deployment config, build config, and imagestream config are created, those are re-used. The only thing that changes from deployment to deployment is the source code. For application resources, you can update them by undeploying and then deploying again. BuildConfigs and Imagestreams can be re-created using the --build.recreate flag

Advanced Options

While nodeshift is very opinionated about deployment parameters, both the CLI and the API accept options that allow you to customize nodeshift's behavior.

version

Outputs the current version of nodeshift

projectLocation

Changes the default location of where to look for your project. Defaults to your current working directory(CWD)

configLocation

This option is passed through to the Openshift Rest Client. Defaults to the ~/.kube/config

imageTag

Specify the tag of the docker image to use for the deployed application. defaults to latest. These version tags correspond to the RHSCL tags of the ubi8/nodejs s2i images

dockerImage

Specify the s2i builder image of Node.js to use for the deployed applications. Defaults to ubi8/nodejs s2i images

web-app

Flag to automatically set the appropriate docker image for web app deployment. Defaults to false

resourceProfile

Define a subdirectory below .nodeshift/ that indicates where Openshift resources are stored

outputImageStream

The name of the ImageStream to output to. Defaults to project name from package.json

outputImageStreamTag

The tag of the ImageStream to output to. Defaults to latest

quiet

suppress INFO and TRACE lines from output logs.

expose

options to create a default route, if non is provided. Defaults to false

removeAll

option to remove builds, buildConfigs and Imagestreams. Defaults to false - Only for the undeploy Command

deploy.port

Flag to update the default ports on the resource files. Defaults to 8080

deploy.env

Flag to pass deployment config environment variables as NAME=Value. Can be used multiple times. ex: nodeshift --deploy.env NODE_ENV=development --deploy.env YARN_ENABLED=true

build.recreate

Flag to recreate a BuildConfig or Imagestream. Defaults to false. Choices are "buildConfig", "imageStream", false, true. If true, both are re-created

build.forcePull

Flag to make your BuildConfig always pull a new image from dockerhub. Defaults to false

build.incremental

Flag to perform incremental builds(if applicable), which means it reuses artifacts from previously-built images. Defaults to false

build.env

Flag to pass build config environment variables as NAME=Value. Can be used multiple times. ex: nodeshift --build.env NODE_ENV=development --build.env YARN_ENABLED=true

build.strategy

Flag to change the build strategy used. Values can be Docker or Source. Defaults to Source

useDeployment

Flag to deploy the application using a Deployment instead of a DeploymentConfig. Defaults to false

knative

EXPERIMENTAL. Flag to deploy an application as a Knative Serving Service. Defaults to false Since this feature is experimental, it is subject to change without a Major version release until it is fully stable.

help

Shows the below help

    Usage: nodeshift [--options]

    Commands:
        nodeshift deploy          default command - deploy                   [default]
        nodeshift build           build command
        nodeshift resource        resource command
        nodeshift apply-resource  apply resource command
        nodeshift undeploy        undeploy resources

    Options:
        --version                Show version number                         [boolean]
        --projectLocation        change the default location of the project   [string]
        --configLocation         change the default location of the config    [string]
        --imageTag           The tag of the docker image to use for the deployed
                            application.                 [string] [default: "latest"]
        --web-app                flag to automatically set the appropriate docker image
                                 for web app deployment
                                                         [boolean] [default: false]
        --resourceProfile        Define a subdirectory below .nodeshift/ that indicates
                                 where Openshift resources are stored         [string]
        --outputImageStream      The name of the ImageStream to output to.  Defaults
                       to project name from package.json            [string]
        --outputImageStreamTag   The tag of the ImageStream to output to.    [string]
        --quiet                  suppress INFO and TRACE lines from output logs
                                                                            [boolean]
        --expose            flag to create a default Route and expose the default
                   service [boolean] [choices: true, false] [default: false]
        --namespace.displayName  flag to specify the project namespace display name to
                       build/deploy into.  Overwrites any namespace settings
                       in your OpenShift or Kubernetes configuration files
                                                                    [string]
        --namespace.create       flag to create the namespace if it does not exist.
                       Only applicable for the build and deploy command.
                       Must be used with namespace.name            [boolean]
        --namespace.remove       flag to remove the user created namespace.  Only
                       applicable for the undeploy command.  Must be used
                       with namespace.name                         [boolean]
        --namespace.name         flag to specify the project namespace name to
                       build/deploy into.  Overwrites any namespace settings
                       in your OpenShift or Kubernetes configuration files
                                                                    [string]
        --deploy.port        flag to update the default ports on the resource files.
                   Defaults to 8080                          [default: 8080]
        --build.recreate         flag to recreate a buildConfig or Imagestream
                [choices: "buildConfig", "imageStream", false, true] [default: false]
        --build.forcePull        flag to make your BuildConfig always pull a new image
                                from dockerhub or not
                                    [boolean] [choices: true, false] [default: false]
        --build.incremental  flag to perform incremental builds, which means it reuses
                                artifacts from previously-built images
                                    [boolean] [choices: true, false] [default: false]
        --build.strategy         flag to change the build strategy.  Defaults to Source
                                  [choices: "Source", "Docker"]
        --metadata.out           determines what should be done with the response
                                metadata from OpenShift
                [string] [choices: "stdout", "ignore", "<filename>"] [default: "ignore"]
        --useDeployment          flag to deploy the application using a Deployment
                       instead of a DeploymentConfig
                           [boolean] [choices: true, false] [default: false]
        --knative                EXPERIMENTAL. flag to deploy an application
                       as a Knative Serving Service
                           [boolean] [choices: true, false] [default: false]
        --help                   Show help                                   [boolean]
        --cmd                                                      [default: "deploy"]

Contributing

Please read the contributing guide

deploy

The deploy function will do the combination of resource, build and apply-resource

deploy(options: object?): Promise<object>
Parameters
options (object? = {}) Options object for the deploy function
Name Description
options.projectLocation string? the location(directory) of your projects package.json. Defaults to process.cwd
options.expose boolean? Set to true to create a default Route and expose the default service. defaults to false
options.namespace object? -
options.namespace.displayName string? flag to specify the project namespace display name to build/deploy into. Overwrites any namespace settings in your OpenShift or Kubernetes configuration files
options.namespace.create boolean? flag to create the namespace if it does not exist. Only applicable for the build and deploy command. Must be used with namespace.name
options.namespace.name string? flag to specify the project namespace name to build/deploy into. Overwrites any namespace settings in your OpenShift or Kubernetes configuration files
options.resourceProfile string? Define a subdirectory below .nodeshift/ that indicates where Openshift resources are stored
options.imageTag string? set the version to use for the ubi8/nodejs-10. Versions are ubi8/nodejs-10 tags: https://access.redhat.com/containers/?tab=tags#/registry.access.redhat.com/ubi8/nodejs-10
options.outputImageStream string? the name of the ImageStream to output to. Defaults to project name from package.json
options.outputImageTag string? The tag of the ImageStream to output to. Defaults to latest
options.quiet boolean? suppress INFO and TRACE lines from output logs
options.deploy object? -
options.deploy.port number? flag to update the default ports on the resource files. Defaults to 8080
options.deploy.env Array? an array of objects to pass deployment config environment variables. [{name: NAME_PROP, value: VALUE}]
options.build object? -
options.build.strategy string? flag to change the build strategy used. Values can be Docker or Source. Defaults to Source
options.build.recreate string/boolean? flag to recreate a buildConfig or Imagestream. values are "buildConfig", "imageStream", true, false. Defaults to false
options.build.forcePull boolean? flag to make your BuildConfig always pull a new image from dockerhub or not. Defaults to false
options.build.env Array? an array of objects to pass build config environment variables. [{name: NAME_PROP, value: VALUE}]
options.definedProperties array? Array of objects with the format { key: value }. Used for template substitution
options.useDeployment boolean? Flag to deploy the application using a Deployment instead of a DeploymentConfig. Defaults to false
options.knative boolean? EXPERIMENTAL. flag to deploy an application as a Knative Serving Service. Defaults to false
Returns
Promise<object>: Returns a JSON Object

resource

The resource function will find and enrich all the resource fragments from the .nodeshift directory and create missing service and deployment configs. An openshift.yaml and openshift.json will also be created in the ./tmp/nodeshift/resource directory

resource(options: object?): Promise<object>
Parameters
options (object? = {}) Options object for the resource function
Name Description
options.projectLocation string? the location(directory) of your projects package.json. Defaults to process.cwd
options.expose boolean? Set to true to create a default Route and expose the default service. defaults to false
options.namespace object? -
options.namespace.displayName string? flag to specify the project namespace display name to build/deploy into. Overwrites any namespace settings in your OpenShift or Kubernetes configuration files
options.namespace.name string? flag to specify the project namespace name to build/deploy into. Overwrites any namespace settings in your OpenShift or Kubernetes configuration files
options.resourceProfile string? Define a subdirectory below .nodeshift/ that indicates where Openshift resources are stored
options.imageTag string? set the version to use for the ubi8/nodejs-10. Versions are ubi8/nodejs-10 tags: https://access.redhat.com/containers/?tab=tags#/registry.access.redhat.com/ubi8/nodejs-10
options.outputImageStream string? the name of the ImageStream to output to. Defaults to project name from package.json
options.outputImageTag string? The tag of the ImageStream to output to. Defaults to latest
options.quiet boolean? suppress INFO and TRACE lines from output logs
options.build object? -
options.build.recreate string/boolean? flag to recreate a buildConfig or Imagestream. values are "buildConfig", "imageStream", true, false. Defaults to false
options.build.forcePull boolean? flag to make your BuildConfig always pull a new image from dockerhub or not. Defaults to false
options.definedProperties array? Array of objects with the format { key: value }. Used for template substitution
options.useDeployment boolean? Flag to deploy the application using a Deployment instead of a DeploymentConfig. Defaults to false
options.knative boolean? EXPERIMENTAL. flag to deploy an application as a Knative Serving Service. Defaults to false
Returns
Promise<object>: Returns a JSON Object

applyResource

The apply-resource function does what resource does, but also pushes those resource fragments to your cluster

applyResource(options: object?): Promise<object>
Parameters
options (object? = {}) Options object for the apply-resource function
Name Description
options.projectLocation string? the location(directory) of your projects package.json. Defaults to process.cwd
options.expose boolean? Set to true to create a default Route and expose the default service. defaults to false
options.namespace object? -
options.namespace.displayName string? flag to specify the project namespace display name to build/deploy into. Overwrites any namespace settings in your OpenShift or Kubernetes configuration files
options.namespace.create boolean? flag to create the namespace if it does not exist. Only applicable for the build and deploy command. Must be used with namespace.name
options.namespace.name string? flag to specify the project namespace name to build/deploy into. Overwrites any namespace settings in your OpenShift or Kubernetes configuration files
options.resourceProfile string? Define a subdirectory below .nodeshift/ that indicates where Openshift resources are stored
options.imageTag string? set the version to use for the ubi8/nodejs-10. Versions are ubi8/nodejs-10 tags: https://access.redhat.com/containers/?tab=tags#/registry.access.redhat.com/ubi8/nodejs-10
options.outputImageStream string? the name of the ImageStream to output to. Defaults to project name from package.json
options.outputImageTag string? The tag of the ImageStream to output to. Defaults to latest
options.quiet boolean? suppress INFO and TRACE lines from output logs
options.deploy object? -
options.deploy.port number? flag to update the default ports on the resource files. Defaults to 8080
options.deploy.env Array? an array of objects to pass deployment config environment variables. [{name: NAME_PROP, value: VALUE}]
options.build object? -
options.build.recreate string/boolean? flag to recreate a buildConfig or Imagestream. values are "buildConfig", "imageStream", true, false. Defaults to false
options.build.forcePull boolean? flag to make your BuildConfig always pull a new image from dockerhub or not. Defaults to false
options.definedProperties array? Array of objects with the format { key: value }. Used for template substitution
options.useDeployment boolean? Flag to deploy the application using a Deployment instead of a DeploymentConfig. Defaults to false
options.knative boolean? EXPERIMENTAL. flag to deploy an application as a Knative Serving Service. Defaults to false
Returns
Promise<object>: Returns a JSON Object

undeploy

The undeploy function will use the openshift.yaml/openshift.json from the resource function and remove those values from your cluster.

undeploy(options: object?): Promise<object>
Parameters
options (object? = {}) Options object for the undeploy function
Name Description
options.projectLocation string? the location(directory) of your projects package.json. Defaults to process.cwd
options.namespace object? -
options.namespace.displayName string? flag to specify the project namespace display name to build/deploy into. Overwrites any namespace settings in your OpenShift or Kubernetes configuration files
options.namespace.remove boolean? flag to remove the user created namespace. Only applicable for the undeploy command. Must be used with namespace.name
options.namespace.name string? flag to specify the project namespace name to build/deploy into. Overwrites any namespace settings in your OpenShift or Kubernetes configuration files
options.resourceProfile string? Define a subdirectory below .nodeshift/ that indicates where Openshift resources are stored
options.imageTag string? set the version to use for the ubi8/nodejs-10. Versions are ubi8/nodejs-10 tags: https://access.redhat.com/containers/?tab=tags#/registry.access.redhat.com/ubi8/nodejs-10
options.outputImageStream string? the name of the ImageStream to output to. Defaults to project name from package.json
options.outputImageTag string? The tag of the ImageStream to output to. Defaults to latest
options.quiet boolean? suppress INFO and TRACE lines from output logs
options.removeAll boolean? option to remove builds, buildConfigs and Imagestreams. Defaults to false
options.deploy object? -
options.deploy.port number? flag to update the default ports on the resource files. Defaults to 8080
options.deploy.env Array? an array of objects to pass deployment config environment variables. [{name: NAME_PROP, value: VALUE}]
options.build object? -
options.build.recreate string/boolean? flag to recreate a buildConfig or Imagestream. values are "buildConfig", "imageStream", true, false. Defaults to false
options.build.forcePull boolean? flag to make your BuildConfig always pull a new image from dockerhub or not. Defaults to false
options.definedProperties array? Array of objects with the format { key: value }. Used for template substitution
options.useDeployment boolean? Flag to deploy the application using a Deployment instead of a DeploymentConfig. Defaults to false
options.knative boolean? EXPERIMENTAL. flag to deploy an application as a Knative Serving Service. Defaults to false
Returns
Promise<object>: Returns a JSON Object

build

The build function will archive your code, create a BuildConfig and Imagestream and then upload the archived code to your cluster

build(options: object?): Promise<object>
Parameters
options (object? = {}) Options object for the build function
Name Description
options.projectLocation string? the location(directory) of your projects package.json. Defaults to process.cwd
options.namespace object? -
options.namespace.displayName string? flag to specify the project namespace display name to build/deploy into. Overwrites any namespace settings in your OpenShift or Kubernetes configuration files
options.namespace.create boolean? flag to create the namespace if it does not exist. Only applicable for the build and deploy command. Must be used with namespace.name
options.namespace.name string? flag to specify the project namespace name to build/deploy into. Overwrites any namespace settings in your OpenShift or Kubernetes configuration files
options.imageTag string? set the version to use for the ubi8/nodejs-10. Versions are ubi8/nodejs-10 tags: https://access.redhat.com/containers/?tab=tags#/registry.access.redhat.com/ubi8/nodejs-10
options.outputImageStream string? the name of the ImageStream to output to. Defaults to project name from package.json
options.outputImageTag string? The tag of the ImageStream to output to. Defaults to latest
options.quiet boolean? suppress INFO and TRACE lines from output logs
options.build object? -
options.build.strategy string? flag to change the build strategy used. Values can be Docker or Source. Defaults to Source
options.build.recreate string/boolean? flag to recreate a buildConfig or Imagestream. values are "buildConfig", "imageStream", true, false. Defaults to false
options.build.forcePull boolean? flag to make your BuildConfig always pull a new image from dockerhub or not. Defaults to false
options.build.env Array? an array of objects to pass build config environment variables. [{name: NAME_PROP, value: VALUE}]
options.definedProperties array? Array of objects with the format { key: value }. Used for template substitution
Returns
Promise<object>: Returns a JSON Object