Before You Begin

This 15-minute tutorial shows you how to deploy a Node.js microservice Docker image available on Oracle Cloud Infrastructure Registry (OCIR) to OCI Container Engine for Kubernetes (OKE) using Oracle Visual Builder Studio (VB Studio).

Background

Oracle Cloud Infrastructure Container Engine for Kubernetes (or OKE) is a fully-managed, scalable, and highly available service that you can use to deploy your containerized applications to the cloud. OKE uses Kubernetes - the open-source system for automating deployment, scaling, and management of containerized applications across clusters of hosts. To find more about OKE, see Overview of Container Engine for Kubernetes.

In this tutorial, you'll complete these steps to deploy the Docker image of a Node.js microservice available on OCIR to OKE:

• Create a YAML file in the VB Studio Git repository that defines the Deployment and Service objects
• Configure a job to:
  • Connect to Oracle Cloud Infrastructure (OCI) using OCIcli
  • Get the Node.js Microservice Docker Image from OCIR
  • Run the kubectl command to create the service and deployment objects in OKE
  • Get the deployed Node.js app's IP address and port
• Run the deployed app
• Configure another job to delete the service and deployment objects from OKE

What Do You Need?

This section lists the input values you need to complete this tutorial and explains how to get them. When you have them, replace the default values in this section's input fields with your actual values. The values you substitute automatically replace the default values used in the commands and snippets further down in the tutorial, allowing them to be used as-is with no further editing. In the commands and snippets, these input values are highlighted in bold. To copy the snippet or the command, click its Copy icon.

For example, one of the input values you need is the OCI region key, which in this tutorial is set to iad, by default. To provide your region key, in the OCI Region Key's input box below, replace iad with your region key. After changing the region key, verify it in the Configure a Build Job section's Step 15.

This substitution functionality is provided by JavaScript. To ensure you see the values and use them, you might have to enable JavaScript within your browser.

Note that the values you enter in this tutorial are not saved or uploaded. When you refresh the page, all input values revert to their default values. If you don't want to enter your values in this section's input fields, then don't copy or use the bold text values in the commands and snippets. Instead, replace them with your own values before using the commands and snippets. If you're not sure what the bold text value is, hover mouse over it.

You'll need these items to complete this tutorial:

• A web browser
• Your Oracle Cloud account credentials
• Docker image of the Node.js microservice pushed to OCIR

  If you haven't pushed the Docker image, see the previous tutorial and push the Docker image to OCIR before you continue with this tutorial.

  In this tutorial, use the same OCI region, tenancy, and user's details that you used to push the Docker image.

• OCI region key and its identifier. Your home region is displayed on the tenancy's details page. See Viewing the Tenancy Details Page to find out how to open the page and then see About Regions and Availability Domains to know your region's key and identifier.

  OCI Home Region Identifier

  OCI Region Key .ocir.io

  Here's an example of the Tenancy Details page:

  

• OCI tenancy's name and its OCID. To find out how to get the values, see Viewing the Tenancy Details Page.

  Tenancy Name

  Tenancy OCID

  Here's an example of the Tenancy Details page:

  

• OCI user's details who belongs to either the tenancy's Administrators group, or a group to which a policy grants the appropriate Container Engine for Kubernetes permissions. For more details, see Preparing for Container Engine for Kubernetes.

  Get the user's name, OCID, fingerprint, authentication token, email address, and the private key used to create the fingerprint. To find out how to get them, see Required Keys and OCIDs.

  You must've saved the private key and the auth token when you generated them. If you don't have the auth token, see Getting an Auth Token to learn how to generate one.

  User Name

  User OCID

  User's Fingerprint

  User's Auth Token

  User's Email Address

  User's Passphrase
  Leave it empty if you didn't use a passphrase while generating the private key.

  User's Private key

  Here's an example of an OCI user details page:

  

• A Kubernetes cluster set up on OCI

  See Creating a Kubernetes Cluster or this tutorial to learn how to set up a Kubernetes cluster on OCI. After creating the cluster, get its OCID.

  Cluster OCID

  Here's an example of a Cluster's details page:

  

• OCIR secret name

  To pull images from OCIR, you'll need a unique Docker registry secret name. You'll use the secret name when you configure a build job. The secret name could be any name of your choice.

  OCIR Secret Name

• Name of the Docker image that was pushed to OCIR

  OCIR Docker Image and Tag .ocir.io///

  Here's an example of the Registry page:

  

• The Docker and Node.js VM template configured in the previous tutorial. In this tutorial, you'll update the template to include Kubernetes and OCIcli software.

  

Update the Build VM Template

1. Open VB Studio.
2. In the navigation menu, click Organization.
3. On the Organization page, click the Virtual Machines Templates tab.

   

4. From the left list, select the Node.js and Docker template.

   

5. Click Edit.
6. In the Edit VM dialog box, enter these details and click Save.
   • Name: Node.js, Docker, and Kubernetes
   • Description: Build VM template with Node.js, Docker, and Kubernetes

   

7. Click Configure Software.
8. In the search box, enter Kubernetes and press Enter.

   

   The software versions you see in this tutorial's images might be different what you see in your VB Studio organization.

9. In the Kubectl tile, select the check box.

   The Kubernetes software is added to the Selected Software list.

10. In the search box, enter OCIcli.

    

11. In the OCIcli tile, select the check box.

    The OCIcli software is added to the Selected Software list.

12. In the Selected Software list, click Add to add Python3. OCIcli requires Python to run.
13. Click Done.

    After you've added the required software, your template should look like this:

    

14. Click the Virtual Machines tab.
15. Search for the Node.js, Docker, and Kubernetes VM.

    

16. If the VM is in the Stopped state, from Actions , select Start.
    The VM's status changes to Starting.

Add the Kubernetes File to the Git Repository

1. Open the VB Studio project.
2. In the left navigation menu, click Git.
3. From the Repositories list, select my-nodejs-app.
4. Click + File.

   

5. In File Name, enter nodejs_micro.yml
6. In the content area, copy and paste this script.
   Click to copy the script.

   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: nodejsmicroappocir-k8s-deployment
   spec:
     selector:
       matchLabels:
         app: nodejsmicro
     replicas: 1 # deployment runs 1 pods matching the template
     template: # create pods using pod definition in this template
       metadata:
         labels:
           app: nodejsmicro
       spec:
         containers:
         - name: nodejsmicro
           image: .ocir.io///
           ports:
           - containerPort: 80 #Endpoint is at port 80 in the container
         imagePullSecrets:
           - name: 
   ---
   apiVersion: v1
   kind: Service
   metadata:
     name: nodejsmicroappocir-k8s-service
   spec:
     type: NodePort #Exposes the service as a node port
     ports:
     - port: 80
       protocol: TCP
       targetPort: 80
     selector:
       app: nodejsmicro

   The above script performs these actions:

   • Sets nodejsmicroappocir-k8s-deployment as the deployment's name
   • Creates one replicated Pod, defined by replicas
   • Sets the deployment object's label to app: nodejsmicro
   • Using selector, defines how the Deployment object finds the Pod object using the label app: nodejsmicro
   • Using template, defines Pod with the app: nodejsmicro label, container's name, Docker image's name on OCIR, and the open port number as 80
   • Using imagePullSecrets, specifies the Docker secret name required to access the Oracle Cloud Infrastructure Registry
   • Sets nodejsmicroappocir-k8s-service as the service's name
   • Defines Pod's TCP target port as 80 with the app: nodejsmicro label

   In the code editor, if you see an (1, 1) Expecting 'job' or 'pipeline'; found 'apiVersion' error, ignore it.

7. Click Commit.

   

8. In the Commit Changes dialog box, click Commit.

Configure a Build Job

1. In the left navigation menu, click Builds.
2. In the Jobs tab, click + Create Job.
3. In the New Job dialog box, enter these values and click Create.
   • Job Name: deploy-nodejs-kubernetes
   • Description: Job to deploy the Node.js microservice app's Docker image to OKE
   • Template: Node.js, Docker, and Kubernetes

   

4. In the Configure tab, click the Git tab.
5. From Add Git, select Git.
6. In Repository, select my-nodejs-app.git.

   

7. Click the Steps tab. From Add Step, select OCIcli.

   

8. In User OCID, enter this value:

9. In Fingerprint, enter this value:

10. In Tenancy, enter this value:

11. In Private Key, enter this value:

    Note that the private key appears as ****** after you save the build job.

12. In Region, select as your OCI home region.

    Here's an example of the OCIcli build step:

    

13. In Passphrase, enter this value:

    If you didn't use a passphrase, no value is shown above. Leave the Passphrase field empty.

14. In the Steps tab, from Add Step, select Common Build Tools, and then select Unix Shell.
15. Copy this shell script and paste it in Script.

    mkdir -p $HOME/.kube
    oci ce cluster create-kubeconfig --cluster-id  --file $HOME/.kube/config --region 
    export KUBECONFIG=$HOME/.kube/config
    kubectl create secret docker-registry  --docker-server=.ocir.io --docker-username='/' --docker-password='' --docker-email=''
    kubectl create -f nodejs_micro.yml
    sleep 30
    kubectl get services nodejsmicroappocir-k8s-service
    kubectl describe pods

    The above shell script runs these commands:

    • Creates the .kube directory in the build executor's workspace
    • Using the oci ce command, downloads the Kubernetes cluster config file
    • Sets the KUBECONFIG environment variable
    • Using kubectl create secret docker-registry, creates the OCIR secret key
      If you've already created the secret key, remove this command.
    • Using the kubectl create -f command, deploys the Docker container on the Kubernetes cluster
    • Using the kubectl get services nodejsmicroappocir-k8s-service command, retrieves the deployed container's port
    • Using the kubectl describe pods command, show the state of the containers in the pod and their IP addresses

    In the script, remember that the nodejsmicroappocir-k8s-service name was configured in the nodejs_micro.yml file.

    Here's an example of the Unix Shell build step:

    

16. Scroll up and click Save.
17. On the job's details page, click Build Now.
18. Wait for the build to complete. If it's the VM's first build or the VM is in the Stopped state, the build will take some time.
19. Click Build Log to see a similar build log.

    Examine the build log to retrieve the deployed Node.js app's IP address and the port on the Kubernetes cluster. You'll find the port number after the kubectl get services nodejsmicroappocir-k8s-service command and the IP address after the kubectl describe pods command.

    In this log, the IP address and the port numbers are highlighted in Bold. You might need to scroll right to see the port number.

    [2020-01-01 08:06:47] Build scheduled. Build started by user alex.cloud
    [2020-01-01 08:06:47] Build task id: 123d4567-e6d3-4474-9655-6fcd8c5dc84f
    .
    .
    .
    [2020-01-01 08:07:10] + kubectl create -f nodejs_micro.yml
    [2020-01-01 08:07:17] deployment "nodejsmicroappocir-k8s-deployment" created
    [2020-01-01 08:07:17] service "nodejsmicroappocir-k8s-service" created
    [2020-01-01 08:07:17] + sleep 30
    [2020-01-01 08:09:17] + kubectl get services nodejsmicroappocir-k8s-service
    [2020-01-01 08:09:18] NAME                             TYPE       CLUSTER-IP     EXTERNAL-IP   PORT(S)        AGE
    [2020-01-01 08:09:18] nodejsmicroappocir-k8s-service   NodePort   10.11.123.45   <none>        80:32123/TCP   2m
    [2020-01-01 08:09:18] + kubectl describe pods
    [2020-01-01 08:09:19] Name:           nodejsmicroappocir-k8s-deployment-5b558c54f6-hkkwf
    [2020-01-01 08:09:19] Namespace:      default
    [2020-01-01 08:09:19] Node:           129.111.222.123/10.0.0.2
    [2020-01-01 08:09:19] Start Time:     Wed, 01 Jan 2020 08:07:17 +0000
    .
    .
    .
    [2020-01-01 08:09:19] END shell script execution
    [2020-01-01 08:09:19] /bin/sh -c rm -rf ~/.oci
    Executor log size 19.4 KB (19,418)
    [2020-01-01 08:09:20]
    [2020-01-01 08:09:20] Build completed.
    [2020-01-01 08:09:20] Status: DONE Result: SUCCESSFUL Duration: 2 min 18 sec
    

Run the Node.js App

1. Create a URL using the IP address and the port that you retrieved from the build's log.

   Here's an example:

   http://129.111.222.123:32123

2. On your computer, open a web browser.
3. Enter the URL to open the application.

   

4. To test the /add function of main.js, use cURL.

   For example, open the curl command-line or the Git Bash command-line and run this command to get the sum of two numbers: 11 and 22. Before you run the command, remember to replace the default URL with your deployed app's URL.

   $ curl -s -d "num1=11&num2=22" -X POST http://129.111.222.123:32123/add
   

   You should see a similar output:

   {"error":false,"message":"success","data":33}

Delete the Kubernetes Objects from OKE

Before you rebuild the deploy-nodejs-kubernetes job, you must delete the secret key, the Deployment object, and the Service object from OKE. To do that, create another job and run it.

Here, instead of creating a job from scratch, you'll create a copy of the deploy job and change its configuration.

1. In the left navigation menu, click Builds.
2. In the Jobs tab, click + Create Job.
3. In the New Job dialog box, enter these values and click Create.
   • Job Name: undeploy-nodejs-kubernetes
   • Description: Job to delete the Kubernetes objects from OKE
   • Copy From Existing: Select the check box
   • Copy From: Select deploy-nodejs-kubernetes

   

4. Click the Steps tab.
5. In Unix Shell, replace the existing commands with these commands:

   kubectl delete service nodejsmicroappocir-k8s-service
   kubectl delete deployment nodejsmicroappocir-k8s-deployment
   kubectl delete secret 

   Don't remove the OCIcli step or change its fields.

6. Click Save.
7. Click Build Now.
8. Wait for the build to complete. If it's the VM's first build or the VM is in the Stopped state, the build will take some time.
9. Click Build Log to see a similar build log.

   [2020-01-01 09:55:26] + kubectl delete service nodejsmicroappocir-k8s-service
   [2020-01-01 09:55:28] service "nodejsmicroappocir-k8s-service" deleted
   [2020-01-01 09:55:28] + kubectl delete deployment nodejsmicroappocir-k8s-deployment
   [2020-01-01 09:55:31] deployment.extensions "nodejsmicroappocir-k8s-deployment" deleted
   [2020-01-01 09:55:31] + kubectl delete secret ocirsecret
   [2020-01-01 09:55:33] secret "ocirsecret" deleted
   [2020-01-01 09:55:34] END shell script execution

After deleting the objects, you can run the deploy job again.