Skip to main content
Version: v0.12

service

Schemasโ€‹

Schema Serviceโ€‹

Service is a kind of workload profile that describes how to run your application code. This
is typically used for long-running web applications that should "never" go down, and handle
short-lived latency-sensitive web requests, or events.

Attributesโ€‹

nametypedescriptiondefault value
annotations{str:str}Annotations are key/value pairs that attach arbitrary non-identifying metadata to the workload.
containers required{str:}Containers defines the templates of containers to be ran.
More info: https://kubernetes.io/docs/concepts/containers
labels{str:str}Labels are key/value pairs that are attached to the workload.
replicasintNumber of container replicas based on this configuration that should be ran.
secrets{str:Secret}Secrets can be used to store small amount of sensitive data e.g. password, token.

Examplesโ€‹

# Instantiate a long-running service and its image is "nginx:v1"

import kam.workload as wl
import kam.workload.container as c

nginxSvc : wl.Service {
containers: {
"nginx": c.Container {
image: "nginx:v1"
}
}
}

Base Schemaโ€‹

WorkloadBase

Schema Containerโ€‹

Container describes how the Application's tasks are expected to be run. Depending on
the replicas parameter 1 or more containers can be created from each template.

Attributesโ€‹

nametypedescriptiondefault value
args[str]Arguments to the entrypoint.
Args will overwrite the CMD value set in the Dockfile, otherwise the Docker
image's CMD is used if this is not provided.
command[str]Entrypoint array. Not executed within a shell.
Command will overwrite the ENTRYPOINT value set in the Dockfile, otherwise the Docker
image's ENTRYPOINT is used if this is not provided.
dirs{str:str}Collection of volumes mount into the container's filesystem.
The dirs parameter is a dict with the key being the folder name in the container and the value
being the referenced volume.
env{str:str}List of environment variables to set in the container.
The value of the environment variable may be static text or a value from a secret.
files{str:FileSpec}List of files to create in the container.
The files parameter is a dict with the key being the file name in the container and the value
being the target file specification.
image requiredstrImage refers to the Docker image name to run for this container.
More info: https://kubernetes.io/docs/concepts/containers/images
lifecyclelc.LifecycleLifecycle refers to actions that the management system should take in response to container lifecycle events.
livenessProbep.ProbeLivenessProbe indicates if a running process is healthy.
Container will be restarted if the probe fails.
readinessProbep.ProbeReadinessProbe indicates whether an application is available to handle requests.
resources{str:str}Map of resource requirements the container should run with.
The resources parameter is a dict with the key being the resource name and the value being
the resource value.
startupProbep.ProbeStartupProbe indicates that the container has started for the first time.
Container will be restarted if the probe fails.
workingDirstrThe working directory of the running process defined in entrypoint.
Default container runtime will be used if this is not specified.

Examplesโ€‹

import kam.workload.container as c

web = c.Container {
image: "nginx:latest"
command: ["/bin/sh", "-c", "echo hi"]
env: {
"name": "value"
}
resources: {
"cpu": "2"
"memory": "4Gi"
}
}

Schema FileSpecโ€‹

FileSpec defines the target file in a Container.

Attributesโ€‹

nametypedescriptiondefault value
contentstrFile content in plain text.
contentFromstrSource for the file content, reference to a secret of configmap value.
mode requiredstrMode bits used to set permissions on this file, must be an octal value
between 0000 and 0777 or a decimal value between 0 and 511
"0644"

Examplesโ€‹

import kam.workload.container as c

tmpFile = c.FileSpec {
content: "some file contents"
mode: "0777"
}

Schema Lifecycleโ€‹

Lifecycle describes actions that the management system should take in response to container lifecycle events.

Attributesโ€‹

nametypedescriptiondefault value
postStartThe action to be taken after a container is created.
More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks
preStopThe action to be taken before a container is terminated due to an API request or
management event such as liveness/startup probe failure, preemption, resource contention, etc.
More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks

Examplesโ€‹

import kam.workload.container.probe as p
import kam.workload.container.lifecycle as lc

lifecycleHook = lc.Lifecycle {
preStop: p.Exec {
command: ["preStop.sh"]
}
postStart: p.Http {
url: "http://localhost:80"
}
}

Schema Execโ€‹

Exec describes a "run in container" action.

Attributesโ€‹

nametypedescriptiondefault value
command required[str]The command line to execute inside the container.

Examplesโ€‹

import kam.workload.container.probe as p

execProbe = p.Exec {
command: ["probe.sh"]
}

Schema Httpโ€‹

Http describes an action based on HTTP Get requests.

Attributesโ€‹

nametypedescriptiondefault value
headers{str:str}Collection of custom headers to set in the request
url requiredstrThe full qualified url to send HTTP requests.

Examplesโ€‹

import kam.workload.container.probe as p

httpProbe = p.Http {
url: "http://localhost:80"
headers: {
"X-HEADER": "VALUE"
}
}

Schema Probeโ€‹

Probe describes a health check to be performed against a container to determine whether it is alive or ready to receive traffic. There are three probe types: readiness, liveness, and startup.

Attributesโ€‹

nametypedescriptiondefault value
failureThresholdintMinimum consecutive failures for the probe to be considered failed after having succeeded.
initialDelaySecondsintThe number of seconds before health checking is activated.
More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes
periodSecondsintHow often (in seconds) to perform the probe.
probeHandler requiredExecHttpTcp
successThresholdintMinimum consecutive successes for the probe to be considered successful after having failed.
terminationGracePeriodintDuration in seconds before terminate gracefully upon probe failure.
timeoutSecondsintThe number of seconds after which the probe times out.
More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes

Examplesโ€‹

import kam.workload.container.probe as p

probe = p.Probe {
probeHandler: p.Http {
path: "/healthz"
}
initialDelaySeconds: 10
}

Schema Tcpโ€‹

Tcp describes an action based on opening a socket.

Attributesโ€‹

nametypedescriptiondefault value
url requiredstrThe full qualified url to open a socket.

Examplesโ€‹

import kam.workload.container.probe as p

tcpProbe = p.Tcp {
url: "tcp://localhost:1234"
}

Schema Secretโ€‹

Secret can be used to store sensitive data.

Attributesโ€‹

nametypedescriptiondefault value
data{str:str}Data contains the non-binary secret data in string form.
immutableboolImmutable, if set to true, ensures that data stored in the Secret cannot be updated.
params{str:str}Collection of parameters used to facilitate programmatic handling of secret data.
type required"basic""token""opaque"

Examplesโ€‹

import kam.workload.secret as sec

basicAuth = sec.Secret {
type: "basic"
data: {
"username": ""
"password": ""
}
}