Nodeshift

What is it

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

Prerequisites

• Node.js - version 18.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.

login - will login to the cluster

logout - will logout of the cluster

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

Using Login and Logout

By default, the Nodeshift CLI will look for a kube config in ~/.kube/config. This is usually created when a user does an oc login, but that requires the oc to be installed and the extra step of running the oc login command. The Nodeshift CLI allows you to pass a username/password or a valid auth token along with the clusters API server address to authenticate requests without the need to run oc login first.

While these parameters can be specified for each command, the nodeshift login command helps to simplify that. You can now run nodeshift login with the parameters mentioned to first login, then run the usual nodeshift deploy without neededing to add the flags.

CLI Usage - Login:

$ nodeshift login --username=developer --password=password --server=https://api.server

or

$ nodeshift login --token=12345 --server=https://api.server

CLI Usage - Logout

$ nodeshift logout

API usage using async/await would look something like this:

const nodeshift = require('nodeshift');

const options = {
  username: 'kubeadmin',
  password: '...',
  server: '...',
  insecure: true
};

(async () => {
  await nodeshift.login(options);
  await nodeshift.deploy();
  await nodeshift.logout();
})();

.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 Deployment 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.

For kubernetes based deployments, a Service and Deployment will be created by default, if none are provided. The Service is of a LoadBalancer type, so no Ingress is needed to expose the application.

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 Deployment 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

<!-- For more on writing openshift templates, [see here](https://docs.openshift.org/latest/dev_guide/templates.html#writing-templates) -->

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, 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

Using with Kubernetes

Nodeshift can deploy Node.js applications to a Kubernetes Cluster using the --kube flag.

There are 2 options that can be passed. minikube or docker-desktop . Passing just the --kube flag will default to minikube

Nodeshift expects that your code has a Dockerfile in its root directory. Then deploying to kubernetes is as easy as running:

npx nodeshift --kube=minikube

Note on Minikube: This connects to Minikubes docker server, create a new container and then deploy and expose that container with a Deployment and Service

To learn more about minikube.

To learn more about docker-desktop.

Openshift Rest Client Configuration

Nodeshift uses the Openshift Rest Client under the hood to make all REST calls to the cluster. By default, the rest client will look at your ~/.kube/config file to authenticate you. This file will be created when you do an oc login.

If you don't want to use oc to login first, you can pass in a username, password, and the server of the cluster to authenticate against. If you are using a cluster with a self-signed certificate(like code ready containers), then you will need to add the insecure flag.

Also note, that when accessing the cluster this way, the namespace will default to default. If you need to target another namespace, use the namespace.name flag. Just make sure the user you use has the appropriate permissions.

An example of this might look something like this:

npx nodeshift --username developer --password developer --server https://apiserver_for_cluster --insecure --namespace.name nodejs-examples

You can also pass in a valid auth token using the token flag. If both a token and username/password is specified, the token will take the preference.

npx nodeshift --token 123456789 --server https://apiserver_for_cluster --insecure --namespace.name nodejs-examples

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

token

Auth token to pass into the openshift rest client for logging in with the API Server. Overrides the username/password

username

username to pass into the openshift rest client for log