README.md

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
• 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
• Debugging / Troubleshooting
  • Configuring Apps for N|Solid with kubernetes
    • Buiding 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 Enginer
• kubernetes on aws - Amazon Web Services
• kubernetes on GCE - Google Compute Engine
• kubernetes on Azure - Microsoft Azure (Weave-based)
• kubernetes on Azure - Microsoft Azure (Flannel-based)

## Quickstart

Make sure your kubectl is pointing to your active cluster.

./install

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

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

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

N|Solid is free for non-production use, but does require a license key. Request one from the Console welcome screen. For more information, see the N|Solid Quickstart.

### 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-registry
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
aws ec2 create-volume --availability-zone eu-west-1a --size 10 --volume-type gp2

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

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:v1.4.0.

FROM nodesource/nsolid:v1.4.0

##### Kubernetes

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

  env:
    - name: NSOLID_APPNAME
      value: sample-app
    - name: NSOLID_HUB
      value: "registry.nsolid:80"
    - name: NSOLID_SOCKET
      value: "8000"

NOTE: NSOLID_SOCKET needs to be set so it isn't automatically assigned. It also needs to be exposed via the ports pod options so the N|Solid hub can communicate.

Optional flags:

  env:
    - name: NSOLID_TAGS
      value: "nsolid-v1.4.0,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) 2016 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.