Deploy a Go MSSQL API Endpoint in the Kyma Runtime
- How to configure and build a Go Docker image
- How to create a development Namespace in the Kyma runtime
- How to deploy the Go Docker image to the Kyma runtime
Prerequisites
This tutorial expects that the tutorial Deploying MSSQL in the Kyma Runtime has been completed and relies on the database running either locally or within the Kyma runtime. If you run the database in the Kyma runtime, make sure to use the port-forward
feature presented in the tutorial to expose the database to your local environment.
Deploying the image includes:
- A Kubernetes Secret to store the database user/password
- A Kubernetes
ConfigMap
to store the database configuration in - A Kubernetes Service used to expose the Go application to other Kubernetes resources
- A Kyma
APIRule
to expose the API to the Internet
- Step 1
- Copy the repository URL.
In your browser, go to kyma-runtime-extension-samples. This repository contains a collection of Kyma sample applications which will be used during the tutorial.
Choose the Code button and choose one of the options to download the code locally or simply run the following command within your CLI at your desired folder location:
Shell/BashCopygit clone https://github.com/SAP-samples/kyma-runtime-extension-samples
- Step 2
Open the
api-mssql-go
directory in your desired editor.Explore the content of the sample.
Within the
cmd/api
directory, you can findmain.go
which is the main entry point of the Go application.The
docker
directory contains the Dockerfile used to generate the Docker image. The image is built in two stages to create an image with a small file size.In the first stage, a Go image is used. It copies the related content of the project into the image and builds the application. The built application is then copied into the Docker
scratch
image and exposed on port 8000. Thescratch
image is an empty image containing no other tools within it so obtaining a shell/bash session is not possible. If desired, the following lines could be commented out to build an image with more included tools, but this results in a larger image.Shell/BashCopyFROM scratch WORKDIR /app COPY --from=builder /app/api-mssql-go /app/
The
internal
directory contains the rest of the Go application, which is broken down into three packages:api
,config
anddb
. Explore these contents to understand the structure and functionality.Within the
k8s
directory you can find the Kubernetes/Kyma resources you will apply to your Kyma runtime.Within the root you can find
go.mod
andgo.sum
files that are used to manage the dependencies the application uses.
- Step 3
Run the following commands from the
api-mssql-go
directory using your CLI.- The application expects that the following environment variables are set as they are required for the database connection. Make sure to adjust them for your environment. Review the the tutorial Deploying MSSQL in the Kyma Runtime for the different configurations to run the database.
-
To run the application, use the following command:
Shell/BashCopygo run ./cmd/api/main.go
-
The application is available at http://localhost:8000/orders. You can use a tool such as curl to test the different HTTP methods, for example:
To GET data:
Shell/BashCopycurl -i -H "Accept: application/json" -H "Content-Type: application/json" -X GET http://localhost:8000/orders
To POST data:
Shell/BashCopycurl --data "{\"order_id\":\"10000003\",\"description\":\"test from curl\"}" http://localhost:8000/orders
- Step 4
Run the following commands from the
api-mssql-go
directory within your CLI.Make sure to replace the value of
<your-docker-id>
with your Docker account ID.To build the Docker image, run this command:
Shell/BashCopydocker build -t <your-docker-id>/api-mssql-go -f docker/Dockerfile .
To push the Docker image to your Docker repository, run this command:
Shell/BashCopydocker push <your-docker-id>/api-mssql-go
- Step 5
Run the following commands from the
api-mssql-go
directory within your CLI.Make sure to replace the value of
<your-docker-id>
with your Docker account ID.- Start the image locally by running the following command:
The command is expecting that the database is available at
localhost:1433
on the host machine. This is denoted by thehost.docker.internal
value. Review the tutorial Deploying MSSQL in the Kyma Runtime for the different configurations to run/stop the database.-
The application is available at http://localhost:8000/orders. You can use a tool such as curl to test the different HTTP methods, for example:
To GET data:
Shell/BashCopycurl -i -H "Accept: application/json" -H "Content-Type: application/json" -X GET http://localhost:8000/orders
To POST data - make sure to use a unique value for the order_id:
Shell/BashCopycurl --data "{\"order_id\":\"10000004\",\"description\":\"test from curl\"}" http://localhost:8000/orders
-
Stop the Docker container by running:
Shell/BashCopydocker stop api-mssql-go
-
Here are some additional commands that you can use:
To restart the Docker container, run:
Shell/BashCopydocker start api-mssql-go
To remove the Docker container, run:
Shell/BashCopydocker rm api-mssql-go
- Step 6
You can find the resource definitions in the
k8s
folder. If you performed any changes in the configuration, these files may also need to be updated. The folder contains the following files that are relevant to this tutorial:apirule.yaml
: defines the API endpoint which exposes the application to the Internet. This endpoint does not define any authentication access strategy and should be disabled when not in use.configmap.yaml
: defines the name of the database, host, and port. The host value assumes that the service for the database is namedmssql
and is defined in thedev
Namespace. Make sure to adjust this if you made any changes.deployment.yaml
: defines the deployment definition for the Go API, as well as a service used for communication. This definition references both thesecret.yaml
, which was defined in the previous tutorial and also included in this directory, and theconfigmap.yaml
by name.
Start by creating the
dev
Namespace and enablingIstio
:Shell/BashCopykubectl create namespace dev kubectl label namespaces dev istio-injection=enabled
Namespaces separate objects inside a Kubernetes cluster. Choosing a different namespace will require adjustments to the provided samples.
Adding the label
istio-injection=enabled
to the namespace enablesIstio
.Istio
is the service mesh implementation used by the Kyma runtime.Within the
deployment.yaml
, adjust the value ofspec.template.spec.containers.image
, commented with #change it to your image, to use your Docker image. Apply the Deployment which will cause an error which we will further explore:Shell/BashCopykubectl -n dev apply -f ./k8s/deployment.yaml
Check the status of the Pod by running:
Shell/BashCopykubectl -n dev get po
This command results in a table similar to the one below, showing a Pod with the name
api-mssql-go-
ending with a random hash. Make sure to adjust this value in the subsequent commands. Notice that STATUS is reportingCreateContainerConfigError
.Shell/BashCopyNAME READY STATUS RESTARTS AGE api-mssql-go-c694bc847-tkthc 1/2 CreateContainerConfigError 0 23s
You can also see the logs that report the same STATUS
CreateContainerConfigError
:Shell/BashCopykubectl logs api-mssql-go-c694bc847-tkthc -c api-mssql-go -n dev
To find the reason for the STATUS
CreateContainerConfigError
, review the Pod definition:Shell/BashCopykubectl describe pod api-mssql-go-c694bc847-tkthc -n dev
Within the Events of the pods you should find a message
Error: configmap "api-mssql-go" not found
.Apply the
ConfigMap
:Shell/BashCopykubectl -n dev apply -f ./k8s/configmap.yaml
Verify the status of the Pod by running:
Shell/BashCopykubectl -n dev get po
The Pod should now be running.
Shell/BashCopyNAME READY STATUS RESTARTS AGE api-mssql-go-c694bc847-tkthc 2/2 Running 0 23m
Apply the
APIRule
:Shell/BashCopykubectl -n dev apply -f ./k8s/apirule.yaml
What port is the api-mssql-go pod exposed on?
- Step 7
To access the API we can use the
APIRule
we created in the previous step.Open the Kyma runtime console
From the menu, choose Namespaces
Choose the
dev
Namespace.From the menu, choose Discovery and Network >
API Rules
.Choose the Host entry for the api-mssql-go
APIRule
to open the application in the browser which will produce a 404 error. Append/orders
to the end of the URL and refresh the page to successfully access the API. The URL should be similar to:https://api-mssql-go.<cluster>.kyma.ondemand.com/orders
A tool such as
curl
can be used to test the various HTTP methods of the API.
Why was the STATUS of the pod reporting CreateContainerConfigError?