Using N|Solid, the Enterprise Node Platform from NodeSource with Kubernetes
Nginx JavaScript Shell
Latest commit 2d8ea7e Feb 14, 2017 @nw nw committed on GitHub Merge pull request #34 from nodesource/readme-update
Removes reference to hub and registry in README.md
Permalink
Failed to load latest commit information.
conf image fix for cloud deployment Feb 6, 2017
docs
sample-app
.gitignore ignore sesitive files from being checked in Jul 17, 2016
LICENSE.md added license and copywrite Jul 25, 2016
README.md Removes reference to hub and registry in README.md Feb 13, 2017
install

README.md

NSolid, Docker, and Kubernetes

Overview

This repository is for deploying N|Solid with Kubernetes. It assumes that Kubernetes is already setup for your environment.

NSolid, Docker, and Kubernetes

Table of Contents

Installing kubernetes

Upgrading

local

Existing nsolid-kubernetes installs can be upgraded running the following command:

kubectl apply -f conf/nsolid.quickstart.yml

Cloud

If deployed to a cloud (AWS or GCP) please make sure to make the necessary adjustments to conf/nsolid.cloud.yml

kubectl apply -f conf/nsolid.cloud.yml

Quickstart

Make sure your kubectl is pointing to your active cluster.

./install

This command will install the N|Solid Console, N|Solid Storage, and a secure HTTPS proxy to the nsolid namespace.

It can take a little while for Kubernetes to download the N|Solid Docker images. You can verify that they are active by running:

kubectl --namespace=nsolid get pods

When all three pods (console, storage, and nginx-secure-proxy) have a status of 'Running', you may continue to access the N|Solid Console.

Access N|Solid Console

Secure credentials

  • Default username: nsolid
  • Default password: demo

With minikube

printf "\nhttps://$(minikube ip):$(kubectl get svc nginx-secure-proxy --namespace=nsolid --output='jsonpath={.spec.ports[1].nodePort}')\n"

or

Cloud Deployment:

kubectl get svc nginx-secure-proxy --namespace=nsolid

Open EXTERNAL-IP

NOTE: You will need to ignore the security warning on the self signed certificate to proceed.

Welcome Screen

Uninstall N|Solid from kubernetes cluster

kubectl delete ns nsolid --cascade

Deploy Sample App with N|Solid

Quick Start

cd sample-app
docker build -t sample-app:v1 .
kubectl create -f sample-app.service.yml
kubectl create -f sample-app.deployment.yml

NOTE: container image in sample-app.deployment.yml assumes sample-app:v1 docker image. This will work if your using minikube and ran eval $(minikube docker-env).

If you are working in a cloud environment, you will need to push the sample-app to a public Docker registry like Dockerhub or Quay.io, and update the sample-app Deployment file.

Production Install

NOTE: Assumes kubectl is configured and pointed at your kubernetes cluster properly.

Create the namespace nsolid to help isolate and manage the N|Solid components.

kubectl create -f conf/nsolid.namespace.yml

Create nginx SSL certificates

openssl req -x509 -nodes -newkey rsa:2048 -keyout conf/certs/nsolid-nginx.key -out conf/certs/nsolid-nginx.crt

Create Basic Auth file

rm ./conf/nginx/htpasswd
htpasswd -cb ./conf/nginx/htpasswd {username} {password}

Create a secret for certs to mount in nginx

kubectl create secret generic nginx-tls --from-file=conf/certs --namespace=nsolid

Create configmap for nginx settings

kubectl create configmap nginx-config --from-file=conf/nginx --namespace=nsolid

Define the services

kubectl create -f conf/nsolid.services.yml

Create persistent disks

N|Solid components require persistent storage. Kubernetes does not (yet!) automatically handle provisioning of disks consistently across all cloud providers. As such, you will need to manually create the persistent volumes.

On Google Cloud

Make sure the zone matches the zone you brought up your cluster in!

gcloud compute disks create --size 10GB nsolid-storage

On AWS

We need to create our disks and then update the volumeIds in conf/nsolid.persistent.aws.yml.

Make sure the zone matches the zone you brought up your cluster in!

aws ec2 create-volume --availability-zone eu-west-1a --size 10 --volume-type gp2

On Azure

We need to deploy a default StorageClass object that will automatically provision new PersistentVolume instances (backed by an Azure data disk) for all PersistentVolumeClaim objects that are bound to pods (e.g. the nsolid.storage pod).

kubectl create -f https://raw.githubusercontent.com/Azure/acs-engine/master/parts/kubernetesmasteraddons-default-storage-class.yaml 

Once the Azure Container Service is updated to run Kubernetes v1.5.3 by default, the above command won't even be neccessary.

Configure Kubernetes to utilize the newly created persistent volumes

GCE
kubectl create -f conf/nsolid.persistent.gce.yml
AWS
kubectl create -f conf/nsolid.persistent.aws.yml
Azure

There's no need to explicitly create a PersistentVolume object, since the StorageClass that was previously created will automatically provision them as needed.

Deploy N|Solid components

kubectl create -f conf/nsolid.cloud.yml

Debugging / Troubleshooting

Configuring Apps for N|Solid with kubernetes

Buiding an N|Solid app

Docker

Make sure your docker image is build on top of nodesource/nsolid:boron-2.1.2.

FROM nodesource/nsolid:boron-2.1.2

Kubernetes

When defining your application make sure the following ENV are set.

  env:
    - name: NSOLID_APPNAME
      value: sample-app
    - name: NSOLID_COMMAND
      value: "storage.nsolid:9001"
    - name: NSOLID_DATA
      value: "storage.nsolid:9002"
    - name: NSOLID_BULK
      value: "storage.nsolid:9003"

Optional flags:

  env:
    - name: NSOLID_TAGS
      value: "nsolid-boron-v2.1.2,staging"

A comma seperate list of tags that can be used to filter processes in the N|Solid console.

Accessing your App

kubectl get svc {service-name}

The EXTERNAL-IP will access the application.

Accessing N|Solid kubernetes objects

Make sure you use the --namespace=nsolid flag on all kubectl commands.

Setting nsolid as the default namespace

kubectl config current-context // outputs current context
kubectl config set-context {$context} --namespace=nsolid // make 'nsolid' the default namespace
kubectl config set-context {$context} --namespace=default // revert to default

Running nsolid-cli

Verify CLI:

kubectl exec {pod-name} -- nsolid-cli --hub=hub:80 ping

See N|Solid cli docs for more info.

minikube

Minikube is a bit different then a normal kubernetes install. The DNS service isn't running so discovering is a bit more involved. IP addresses are not dynamically assigned, instead we must use the host ports the service is mapped to.

Setting ENV for cluster

If your doing a lot of work with docker and minikube it is recommended that you run the following:

eval $(minikube docker-env)

Service discovery

Get the kubernetes cluster ip address:

minikube ip

To get the service port:

kubectl get svc {$service-name} --output='jsonpath={.spec.ports[0].nodePort}'

Note: If your service exposes multiple ports you may want to examine with --output='json' instead.

Common Gotchas

If you get the following message when trying to run docker build or communicating with the kubernetes api.

Error response from daemon: client is newer than server (client API version: 1.24, server API version: 1.23)

Export the DOCKER_API_VERSION to match the server API version.

export DOCKER_API_VERSION=1.23

License & Copyright

nsolid-kubernetes is Copyright (c) 2017 NodeSource and licensed under the MIT license. All rights not explicitly granted in the MIT license are reserved. See the included LICENSE.md file for more details.