Connect a Cloud Databases deployment to an IBM Cloud Kubernetes Service application
The Cloud Databases "Hello World" Kubernetes examples repository holds sample IBM Cloud® applications, which are written in various programming languages, that detail how to connect a Cloud Databases deployment to an IBM Cloud Kubernetes Service application.
Each Git branch of the examples repository corresponds to samples in a particular programming language, either JavaScript that uses Node.js, or python. The files in each folder correspond either to a database or a message queue.
Trying out the sample applications
Clone the respective repo you want to use. For instance, you can clone the Node repository by selecting the Node branch. Then, click Clone or download to get the URL you need to clone by using SSH or HTTPS. This command looks like:
git clone -b node git@github.com:IBM-Cloud/clouddatabases-helloworld-kubernetes-examples.git
Or, clone by using HTTPS:
git clone -b node https://github.com/IBM-Cloud/clouddatabases-helloworld-kubernetes-examples.git
After the branch is cloned, select the appropriate directory for the database you want to try. Each database has its own copy of these instructions on how to provision and deploy a database or message queue and an application on IBM Cloud Kubernetes Service.
Running on IBM Cloud
-
If you do not already have an IBM Cloud account, sign up here.
-
Download and install IBM Cloud CLI. The IBM Cloud CLI tool enables you to communicate with IBM Cloud from your console or CLI.
-
Install the Kubernetes Service CLI plug-in and the Container Registry CLI plug-in
ibmcloud plugin install container-service ibmcloud plugin install container-registry
To verify their installation, run
ibmcloud plugin list
You receive a response like this:
Listing installed plug-ins... Plugin Name Version Status container-registry 0.1.382 container-service/kubernetes-service 0.3.34
-
Download and install the Kubernetes CLI.
Follow the instructions for downloading and installing the Kubernetes CLI for the platform that you're using.
-
Connect to IBM Cloud in the CLI tool and follow the prompts to log in.
ibmcloud login
If you have a federated user ID, use the
ibmcloud login --sso
command to log in with your single sign-on ID.
Creating your database
This process creates a standard database instance in the service that you specify that might incur extra charges in your selected plan.
-
You must target a resource group, by using the following command:
ibmcloud target -g RESOURCE_GROUP
For more information, see Working with resources and resource groups (ibmcloud resource).
-
The database can be created from the CLI by using the
ibmcloud resource service-instance-create
command. The command takes a service instance name, a service name, plan name, and location. -
The service name is one of the Cloud Databases services,
databases-for-elasticsearch
,databases-for-enterprisedb
,databases-for-etcd
,databases-for-mongodb
,databases-for-postgresql
,databases-for-redis
,messages-for-rabbitmq
, ordatabases-for-mysql
.ibmcloud resource service-instance-create <your_deployment_name> <service_name> standard <region>
Remember the database deployment name. Find your region identifier here.
Configuring the Kubernetes App
-
Create a Kubernetes Service. Choose the location and resource group in which you'd like to set up your cluster. Select the cluster type that you want to use. This example requires only the lite plan, which comes with one worker node. After a cluster is provisioned, you are given a list of steps to access your cluster and set the environment variables under the Access tab. You are also able to verify that your deployment is provisioned and running normally.
-
Make sure that you are targeting the correct IBM Cloud resource group of your Kubernetes Service.
If your resource group is named anything other than
default
, use the following command to target your cluster resource group:ibmcloud target -g <resource_group_name>
This example uses the
default
resource group. -
Create your own private image repository in Container Registry to store your application's Docker image. Since we want the images to be private, we need to create a namespace, which creates a unique URL to your image repository.
ibmcloud cr namespace-add <your_namespace>
-
Add the Cloud Databases deployment to your cluster.
ibmcloud ks cluster service bind --cluster <your_cluster_name> --namespace default --service <your_database_deployment>
The "default" namespace refers to the Kubernetes instance and not the user-created image store namespace. Likewise, if your database uses both public and private endpoints, your public endpoint is used by default. Therefore, if you want to select the private endpoint, first you need to create a service key for your database so Kubernetes can use it when binding to the database. You set up a service key by using the command:
ibmcloud resource service-key-create <your-private-key> --instance-name <your_database_deployment> --service-endpoint private
The private service endpoint is selected with
--service-endpoint private
. After that, you bind the database to the Kubernetes cluster through the private endpoint by using the commandibmcloud ks cluster service bind <your_cluster_name> default <your_database_deployment> --key example-private-key
-
Verify that the Kubernetes secret was created in your cluster namespace. Kubernetes uses secrets to store confidential information like the IBM Cloud Identity and Access Management (IAM) API key and the URL that the container uses to gain access. To set the cluster as the context for this session and then get the API key for accessing the instance of your deployment, run the following commands
ibmcloud ks cluster config --cluster <cluster_name_or_ID>
Then
kubectl get secrets --namespace=default
Save the name of the secret that was generated when you bound
your_database_name
to your Kubernetes service. -
If you haven't already, clone the app in one of the available languages to your local environment from your console by using the following command
git clone -b <language> git@github.com:IBM-Cloud/clouddatabases-helloworld-kubernetes-examples.git
-
cd
into this newly created directory, andcd
into the database folder. The code for connecting to the service, and reading from and updating the database can be found inserver.js
. See Code Structure and the code comments for information on the app's functions. Apublic
directory contains the html, stylesheets, and JavaScript for the web app. However, to get the application to work, we first need to push the Docker image of this application to our Container Registry. -
Build and push the application's Docker image to your Container Registry. Specify the appropriate region and give the container a name.
ibmcloud cr build -t <region>.icr.io/<namespace>/<container_name> .
You can view the image in container registry by using
ibmcloud cr images
You get something like the following response
REPOSITORY TAG DIGEST NAMESPACE CREATED SIZE SECURITY STATUS <region>.icr.io/mynamespace/container_name latest 81c3959ea657 mynamespace 4 hours ago 28 MB No Issues
-
Update the Kubernetes deployment configuration file
clouddb-deployment.yaml
.Change the
image
name to the repository name that you got from the previous step:image: "<region>.icr.io/mynamespace/<container_name>" # Edit me
Now, under
secretKeyRef
, change the name of<db-secret-name>
to match the name of the secret that was created when you bound your database deployment to your Kubernetes cluster.secretKeyRef: name: <db-secret-name> # Edit me
As for the
service
configuration at the end of the file,nodePort
indicates the port that the application can be accessed from. You have ports in the range 30000 - 32767 that you can use, but we chose 30081. The TCP port is set to 8080, which is the port the Node.js application runs on in the container.
Deploying your Kubernetes App
-
Deploy the application to Kubernetes Service. When you deploy the application, it is automatically bound to your Kubernetes cluster.
kubectl apply -f clouddb-deployment.yaml
-
Get the IP for the application.
ibmcloud ks workers -c <cluster_name>
The result is something like:
ID Public IP PrivateIP Machine Type State Status Zone Version kube-hou02-pa1a59e9fd92f44af9b4147a27a31db5c4-w1 199.199.99.999 10.76202.188 free normal Ready hou02 1.10.11_1536
Now you can access the application from the Public IP from port 30082.
The clouddatabases-helloworld app displays the contents of an examples database. To demonstrate that the app is connected to your service, add some words to the database. The words are displayed as you add them, with the most recently added words displayed first.
Code Structure
File | Description |
---|---|
server.js | Establishes a connection to the database by using credentials from BINDING (the name that we created in the Kubernetes deployment file to display the credentials) and handles create and read operations on the database. |
main.js | Handles user input for a PUT command and parses the results of a GET command to output the contents of the database. |
The app uses a PUT and a GET operation:
-
PUT
- Takes user input from main.js.
- Adds the user input to the database.
-
GET
- Retrieves the contents of the database.
- Returns the response of the database command to main.js.