Code to Cloud

Ballerina Code to Cloud is designed to allow developers to write code without thinking about the deployment platform.

This greatly simplifies the experience of developing and deploying Ballerina code in the cloud. It also enables using cloud native technologies easily without in-depth knowledge.

As of now, Ballerina code to cloud supports generating the deployment artifacts of the platforms below.

  1. Docker
  2. Kubernetes

Setting Up the Prerequisites

  1. You need to have Docker installed and configured in your machine.
  2. You need to have kubectl installed and configured in a Kubernetes cluster in order to deploy.

How Code to Cloud Works

Code to cloud builds the containers and required artifacts by deriving the required values from the code. This process happens when the package is being compiled. In order to override the default values given by the compiler, the Cloud.toml file needs to be created in the package directory.

Package Layout

Ballerina encourages to have one microservice per package. In order to adhere to that rule, code to cloud generates only one container per package. These artifacts can be found in the target directory of the package. A complete representation of the package layout is as follows.

├── Cloud.toml                               
├── Ballerina.lock
├── Ballerina.toml
├── entry.bal                          
└── target
    ├── bala
    │   └── module-0.0.1.bala
    ├── bin
    │   └── <module>.jar
    ├── docker
    │       └── Dockerfile                        
    └── kubernetes
            └── <module>-0.0.1.yaml 

Cloud.toml

The configuration file to be used to override the default values generated by code to cloud.

Note: The Cloud.toml file is completely optional and you only have to specify the values you need to override. If the value is not specified for a certain field, the compiler will take the default value. All the supported properties can be found below.

Ballerina.toml

Contains metadata about the Ballerina package. This file is used to fetch defaults for deployment artifacts generation.

Note: The Ballerina.toml file can be used to specify the build option.

[build-options]
cloud = "k8s"

entry.bal

Represents any .bal file that has an entry point. The compiler will be using this file to retrieve service-related information for the deployment artifacts.

target/docker/

Contains the Docker artifacts generated by code to cloud. These artifacts will be required to build the Docker image.

target/kubernetes/

Contains the Kubernetes artifacts generated by code to cloud. These artifacts will be required to deploy the Ballerina application in Kubernetes.

Properties of the ‘Cloud.toml’ File

[container.image]

Contains container image related properties.

Identifier Description Default Value
name Name of the container image $USER-$MODULE_NAME
repository Container repository to host the container ””
tag Tag of the container “latest”
base Base container of the container image “ballerina/jre11:v1”

[container.image.user]

Container image user account related properties.

Identifier Description Default Value
run_as Name of the container image “ballerina”

[[cloud.config.envs]]

Contains the environment variables required for the application.

Identifier Description Example Value
key_ref Key of the environment variable “FOO”
name(optional) Name of the env if its different from the key “foo”
config_name Name of the config map “module-foo”

[[cloud.config.secrets]]

Contains the secrets required for the application.

Identifier Description Example Value
key_ref Reference key of the secret “MYSQL_ROOT_PASSWORD”
name(optional) Name of the secret if its different from the key “ROOT_PASSWORD”
secret_name Name of the secret group “db-credential-secret”

[[cloud.config.files]]

Contains the external configuration files for the code.

Identifier Description Example Value
file Path of the external configuration file “resource/ballerina.conf”
mount_path Path of the configuration file in the container “/home/ballerina/foo/ballerina.conf”

[cloud.deployment]

Contains the properties related to the deployment.

Identifier Description Default Value
internal_domain_name Name of the internal domain $MODULE_NAME
external_accessible Status of exposing the container outside the cluster true
min_memory Minimum memory allocated to the container “100Mi”
max_memory Maximum memory allocated to the container “256Mi”
min_cpu Minimum CPU allocated to the container “1000m”
max_cpu Maximum CPU allocated to the container “1500m”

[cloud.deployment.autoscaling]

Contains the matrices to auto-scale the container.

Identifier Description Default Value
enable Status of autoscaling true
min_replicas Minimum number of replicas of the container alive at a given time 2
max_replicas Maximum number of replicas of the container alive at a given time 3
cpu CPU utilization threshold for spawning a new instance 50
memory Memory utilization threshold for spawning a new instance 80

[cloud.deployment.probes.readiness]

Probe to indicate whether the container is running. No liveness probe will be generated if this property is not specified.

Identifier Description Example Value
port Port of the readiness probe endpoint 9091
path Endpoint of the readiness probe “/readyz”

[cloud.deployment.probes.liveness]

Probe to indicate whether the container is running. No liveness probe will be generated if this property is not specified.

Identifier Description Example Value
port Port of the liveness probe endpoint 9091
path Endpoint of the liveness probe “/healthz”

[[cloud.deployment.storage.volumes]]

Contains the volume definitions of the application. No default volumes will be generated if this property is not specified.

Identifier Description Example Value
name Name of the volume “volume1”
local_path Path of the volume “files”
size Maximum size of the volume “2Gi”

Code to Cloud Samples

For sample use cases of code to cloud, see Code to Cloud Samples.