nodesource / nsolid-kubernetes

Overview

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

Table of Contents

• Installing Kubernetes
• Upgrading
• Quickstart
  • Access N|Solid Dashboard
  • Uninstall N|Solid
• Deploy Sample App with N|Solid
• Production Install
  • N|Solid namespace
  • nginx SSL certificates
  • Basic Auth file
  • Secret object for certs
  • Configmap object for settings
  • Define Services
  • GCE persistent disks
  • AWS persistent disks
  • Azure persistent disks
  • Bluemix persistent disks
• Debugging / Troubleshooting
  • Configuring Apps for N|Solid with Kubernetes
    • Building an N|Solid app
      • Docker
      • Kubernetes
    • Accessing your App
  • Accessing N|Solid Kubernetes objects
    • Setting nsolid as the default namespace
  • Running nsolid-cli
  • minikube
    • Setting ENV for cluster
    • Service Discovery
  • Common Gotchas
• License & Copyright

Installing kubernetes

• local with minikube - for local development / testing.
• kubernetes on GKE - Google Container Engine
• kubernetes on aws - Amazon Web Services
• kubernetes on GCE - Google Compute Engine
• kubernetes on ACS - Microsoft Azure Container Service
• kubernetes on Bluemix - IBM Cloud Container Service

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, Azure, GCP, Bluemix) please make sure to make the necessary adjustments to conf/nsolid.cloud.yml

kubectl apply -f conf/nsolid.cloud.yml

Quickstart

./install

Notes:

1. Make sure your kubectl is pointing to your active cluster.
2. If your cluster is a Bluemix Lite cluster, make this adjustment to conf/nsolid.services.yml before running ./install.

This command will install the N|Solid Console 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 and nginx-secure-proxy) have a status of 'Running', you may continue to access the N|Solid Console.

Access N|Solid Dashboard

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. If using Bluemix Lite cluster, get EXTERNAL-IP this way.

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

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: the container image in sample-app.deployment.yml must be set to match your docker image name. E.g. if you are using minikube and ran eval $(minikube docker-env), set the image to:

    spec:
      containers:
        - name: sample-app
          image: sample-app:v1

If you are working in a cloud environment, you will need to push the sample-app to a public Docker registry like Docker Hub, Quay.io, the Azure Container Registry, or the IBM Bluemix Container Registry, 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

Note: If your cluster is a Bluemix Lite cluster, make this adjustment to conf/nsolid.services.yml before running kubectl create.

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

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

There's no need to explicitly create a persistent disk, since the Azure Container Service provides a default StorageClass, which will dynamically create them as needed (e.g. when a Pod includes a PersistentVolumeClaim).

On Bluemix

There's no need to explicitly create a persistent disk, since the Bluemix Container Service provides a default StorageClass, which will dynamically create them as needed (e.g. when a Pod includes a PersistentVolumeClaim).

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 they will be dynamically provisioned by the default StorageClass.

Bluemix

There's no need to explicitly create a PersistentVolume object, since they will be dynamically provisioned by the default StorageClass.

Deploy N|Solid components

kubectl create -f conf/nsolid.cloud.yml

Debugging / Troubleshooting

Configuring Apps for N|Solid with Kubernetes

Building an N|Solid app

Docker

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

FROM nodesource/nsolid:carbon-latest

Kubernetes

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

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

Optional flags:

  env:
    - name: NSOLID_TAGS
      value: "nsolid-carbon,staging"

A comma separate 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.
Open EXTERNAL-IP. If using Bluemix Lite cluster, get EXTERNAL-IP this way.

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 --remote=http://console.nsolid:6753 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) 2018 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.