permalink |
---|
/guides/collection-nodejs/ |
Developing cloud native microservice applications with the Kabanero Node.js Collection and Appsody CLI.
In this guide, you’ll learn how to create and run a simple cloud native microservice. Then, you’ll update the microservice that you created and deploy it to Kubernetes or Knative. This process will be done by using the Kabanero Node.js Collection with the Appsody CLI. Deployment to Knative is optional depending on whether you want to Scale to Zero.
Kabanero’s Node.js Collection provides an application stack that enables the development and optimization of microservices. With application stacks, developers don’t need to manage full software development stacks or be experts on underlying container technologies or Kubernetes. Application stacks are customized for specific enterprises to incorporate their company standards and technology choices.
Applications in this guide are built and run with Node.js, and deployed to Kubernetes through a modern DevOps toolchain that is triggered in Git.
-
Docker must be installed.
-
Appsody must be installed.
-
Optional: If you have a repository that contains a set of custom collections, you need the URL for the
index.yaml
file. Use this URL to make your custom collections available with the Appsody CLI. -
Optional: If you are testing multiple microservices together, you must have access to a local Kubernetes cluster for local development. If you are using Docker Desktop, you can enable Kubernetes from the menu by selecting Preferences → Kubernetes → Enable Kubernetes. Other options include Minishift or Minikube.
Note: The use of the public Kabanero Collection Hub is only for the purposes of this guide. It is recommended that you make a private copy of the Kabanero Collection Hub and use it in the same way. However, this demonstration does not require that you make your own copy.
-
Take a look at the repositories Appsody can already access, run the following command:
appsody repo list
You see output similar to the following example:
NAME URL *incubator https://github.com/appsody/stacks/releases/latest/download/incubator-index.yaml
-
Add your Kabanero index to the Appsody CLI. The following example uses the public index for Kabanero Version 0.5.0. Run the following command to add the Kabanero index:
appsody repo add kabanero https://github.com/kabanero-io/collections/releases/download/0.5.0/kabanero-index.yaml
-
Check the repositories again by running
appsody repo list
to see that the Kabanero repository was added:NAME URL *incubator https://github.com/appsody/stacks/releases/latest/download/incubator-index.yaml kabanero https://github.com/kabanero-io/collections/releases/download/0.5.0/kabanero-index.yaml
-
In this example, the asterisk (*) shows that
incubator
is the default repository. Run the following command to set the Kabanero index as the default repository:appsody repo set-default kabanero
-
Check the available repositories again by running
appsody repo list
to see that the default is updated:NAME URL incubator https://github.com/appsody/stacks/releases/latest/download/incubator-index.yaml *kabanero https://github.com/kabanero-io/collections/releases/download/0.5.0/kabanero-index.yaml
-
Recommendation: In enterprise settings, when a solution architect creates application stacks with technology choices that are in a private Collection Hub, it’s best to remove
incubator
from the list. These Appsody stacks are not supported by the Kabanero application cluster. Run the following command to remove theincubator
repository:appsody repo remove incubator
Check the available repositories again by running
appsody repo list
to see thatincubator
is removed:NAME URL *kabanero https://github.com/kabanero-io/collections/releases/download/0.5.0/kabanero-index.yaml
Your Appsody CLI is now configured to use the Kabanero Collections. Next, you need to initialize your project.
-
First, create a directory that will contain the project:
mkdir -p ~/projects/simple-nodejs cd ~/projects/simple-nodejs
-
Run the following command to initialize your Node.js project with the Appsody CLI:
appsody init nodejs
The output from the command is similar to the following example:
Running appsody init... Downloading nodejs template project from https://github.com/kabanero-io/collections/releases/download/0.5.0/incubator.nodejs.v0.2.6.templates.simple.tar.gz Download complete. Extracting files from /Users/user1/appsody/simple-nodejs/nodejs.tar.gz Setting up the development environment Your Appsody project name has been set to simple-nodejs Pulling docker image kabanero/nodejs:0.5 Running command: docker pull kabanero/nodejs:0.5 0.5: Pulling from kabanero/nodejs Digest: sha256:99c6429bf96ee3aa91f355794d33d412060c036687f4b601fd35b75d59f87773 Status: Downloaded newer image for kabanero/nodejs:0.5 docker.io/kabanero/nodejs:0.5 [Warning] The stack image does not contain APPSODY_PROJECT_DIR. Using /project Running command: docker run --rm --entrypoint /bin/bash kabanero/nodejs:0.5 -c find /project -type f -name .appsody-init.sh Successfully initialized Appsody project
Your new project is created, built, and started inside a container.
-
Run the following command to start the Appsody development environment:
appsody run
The Appsody CLI launches a local Docker image that contains the Node.js runtime environment that hosts the microservice. After some time, you see a message similar to the following example:
[Container] Running command: npm start --node-options --require=appmetrics-dash/attach [Container] [Container] > nodejs-simple@0.1.0 start /project/user-app [Container] > node app.js [Container] [Container] [Tue Dec 3 09:40:54 2019] com.ibm.diagnostics.healthcenter.loader INFO: Node Application Metrics 5.1.1.201912022045 (Agent Core 4.0.5) [Container] Hello from Node.js 10!
This message indicates that the project is started. The container exposes port 3000, which allows you to bring your own web application and use it with this stack.
You are now ready to begin developing your application.
You are now going to create a new simple web server that listens on http://localhost:3000/
.
-
Edit the
app.js
file in your project folder and update the contents to match the following code:const http = require('http'); const hostname = '0.0.0.0'; const port = 3000; const hander = (req, res) => { res.statusCode = 200; res.setHeader('Content-Type', 'text/plain'); res.end('New web server available!\n'); } const server = http.createServer((handler) server.listen(port, hostname, () => { console.log(`Server running at http://${hostname}:${port}/`); });
-
Save the changes.
-
Appsody watches for file changes and automatically updates your application. Point your browser to
http://localhost:3000/
to see your new server, which displays New web server available!.
If you are building an application that is composed of microservices, you need to test within the context of the overall system. First, test your application and perform unit testing in isolation. To test the application as part of the system, deploy the system and then the new application.
You can choose how you want to deploy the system and application. If you have adequate CPU and memory to run MiniShift, the application, and the associated services, then you can deploy the application on a local Kubernetes that is running on your computer. Alternatively, you can enable Docker Desktop for Kubernetes, which is described in the Prerequisites section of the guide.
You can also deploy the system, application, and the associated services in a private namespace on a development cluster. From this private namespace, you can commit the microservices in Git repositories and deploy them through a DevOps pipeline, not directly to Kubernetes.
After you finish writing your application code, the Appsody CLI makes it easy to deploy directly to a Kubernetes cluster for further local testing. The ability to deploy directly to a Kubernetes cluster is valuable when you want to test multiple microservices together or test with services that the application requires.
-
Ensure that your
kubectl
command is configured with cluster details and run the following command to deploy the application:appsody deploy
This command builds a new Docker image that is optimized for production deployment and deploys the image to your local Kubernetes cluster. After some time you see a message similar to the following example:
Deployed project running at http://localhost:32569
-
Run the following command to check the status of the application pods:
kubectl get pods
In the following example output, you can see that a
simple-nodejs
pod is running:NAME READY STATUS RESTARTS AGE appsody-operator-6bbddbd455-nfhnm 1/1 Running 0 26d simple-nodejs-775b655768-lqn6q 1/1 Running 0 3m10s
-
After the
simple-nodejs
pod starts, go to the URL that was returned when you ran theappsody deploy
command, and you see the Appsody microservice splash screen. To see the response from your application, point your browser to the<URL_STRING>/example
URL, where<URL_STRING>
is the URL that was returned. For example,http://localhost:32569
was returned in the previous example. Go to thehttp://localhost:32569/`
URL to see the deployed application response. -
Use the following command to stop the deployed application:
appsody deploy delete
After you run this command and the deployment is deleted, you see the following message:
Deployment deleted
You can choose to test an application that is deployed with Knative Serving to take advantage of Scale to Zero. Not all applications can be written to effectively take advantage of Scale to Zero. The Kabanero operator-based installation configures Knative on the Kubernetes cluster, specifically OKD 3.11. Because of the resources that are required to run Knative and its dependencies, testing locally can be difficult. Publish to Kubernetes by using pipelines that are described later in the guide. Your operations team can configure the pipelines so that Knative Serving is enabled for deployment.
After you develop and test your application in your local environment, it’s time to publish it to your enterprise’s pipeline. From your enterprise’s pipeline, you can deploy the application to the appropriate Kubernetes cluster for staging or production. Complete this process in Git.
When Kabanero is installed, deploying applications to a Kubernetes cluster always occurs through the DevOps pipeline that is triggered in Git. Using DevOps pipelines to deploy applications ensures that developers can focus on application code, not on containers or Kubernetes infrastructure. From an enterprise perspective, this deployment process ensures that both the container image build and the deployment to Kubernetes or Knative happen in a secure and consistent way that meets company standards.
To deliver your application to the pipeline, push the project to the pre-configured Git repository that has a configured webhook. This configured webhook triggers the enterprise build and deploy pipeline.