Ballerina Kubernetes Extension

Annotation based kubernetes extension implementation for ballerina.

Features:

• Kubernetes deployment support.
• Kubernetes service support.
• Kubernetes liveness probe support
• Kubernetes readiness probe support
• Kubernetes ingress support.
• Kubernetes horizontal pod autoscaler support.
• Docker image generation.
• Docker push support with remote docker registry.
• Kubernetes secret support.
• Kubernetes config map support.
• Kubernetes persistent volume claim support.
• Kubernetes resource quotas.
• Istio gateways support.
• Istio virtual services support.
• OpenShift build config and image stream support.
• OpenShift route support.

Refer samples for more info.

Supported Annotations:

@kubernetes:Deployment{}

• Supported with ballerina services, listeners and functions.

@kubernetes:Service{}

• Supported with ballerina services and listeners.

@kubernetes:Ingress{}

• Supported with ballerina services and listeners.

@kubernetes:HPA{}

• Supported with ballerina services and functions.

@kubernetes:Secret{}

• Supported with ballerina service and functions.

@kubernetes:ConfigMap{}

• Supported with ballerina services and functions.

@kubernetes:PersistentVolumeClaim{}

• Supported with ballerina services and functions.

@kubernetes:ResourceQuota{}

• Support with ballerina services and functions.

@kubernetes:Job{}

• Supported with ballerina main function.

@istio:Gateway{}

• Support with ballerina services and listeners.

@istio:VirtualService{}

• Support with ballerina services and listeners.

@openshift:Route{}

• Support with ballerina services and listeners.

How to build

1. Download and install JDK 8 or later
2. Install Docker
3. Get a clone or download the source from this repository (https://github.com/ballerinax/kubernetes)
4. Run the Maven command mvn clean install from within the kubernetes directory.

Enabling debug logs

• Use the "BAL_DOCKER_DEBUG=true" environment variable to enable docker related debug logs when building the ballerina source(s).
• Use the "BAL_KUBERNETES_DEBUG=true" environment variable to enable kubernetes related debug logs when building the ballerina source(s).

Deploy ballerina service directly using kubectl command.

This repository also provides a kubectl plugin which allows to build ballerina programs and deploy their kubernetes artifacts directly to a kuberetes cluster. The plugin is located at kubernetes-extension/src/main/resources/kubectl-extension/kubectl-ballerina-deploy. Follow the steps mentioned in "Extend kubectl with plugins" . Check if the plugin is available using the command kubectl plugin list.

Replacing values with environment variables.

You can replace values in an annotation using environment variables. The replacement is done with a string placeholder like "$env{ENV_VAR}". As an example lets say that you want to set the namespace field in the @kubernetes:Deployment{} annotation with a environment variable and the name of the environment variable is K8S_NAMESPACE. Following is how the annotation would look like:

@kubernetes:Deployment {
    namespace: "$env{K8S_NAMESPACE}"
}

Note: You cannot use the ballerina/config module to replace values in the annotation. This is because the kubernetes artifacts are generated during compile time. The ballerina/config module works in the runtime.

How to execute:

$> kubectl ballerina deploy hello_world_k8s.bal
> building ballerina source...
Compiling source
    hello_world_k8s.bal
Generating executable
    hello_world_k8s.balx

    @kubernetes:Service              - complete 1/1
    @kubernetes:Deployment           - complete 1/1
    @kubernetes:Docker           - complete 3/3
    @kubernetes:Helm             - complete 1/1

    Run the following command to deploy the Kubernetes artifacts:
    kubectl apply -f ./kubernetes

    Run the following command to install the application using Helm:
    helm install --name hello-world-k8s-deployment ./kubernetes/hello-world-k8s-deployment

> deploying artifacts...
executing 'kubectl apply -f ./kubernetes'
service/helloworld-svc unchanged
deployment.apps/hello-world-k8s-deployment configured

> deployment complete!

Annotation Usage Sample:

import ballerina/http;
import ballerina/log;
import ballerina/kubernetes;

@kubernetes:Ingress{
    hostname: "abc.com"
}
@kubernetes:Service {
    name:"hello"
}
listener http:Listener helloEP = new(9090);

@kubernetes:Deployment {
    livenessProbe: true
}
@http:ServiceConfig {
    basePath: "/helloWorld"
}
service helloWorld on helloEP {
    resource function sayHello(http:Caller caller, http:Request request) {
        http:Response response = new;
        response.setTextPayload("Hello, World from service helloWorld ! ");
        var responseResult = caller->respond(response);
        if (responseResult is error) {
            log:printError("error responding back to client.", err = responseResult);
        }
    }
}

The kubernetes artifacts will be created in following structure.

$> tree kubernetes

kubernetes/
├── docker
│   └── Dockerfile
├── hello-world-deployment
│   ├── Chart.yaml
│   └── templates
│       └── hello-world.yaml
└── hello-world.yaml