Introduction

Using an example httpd.yaml file.

name: httpd
containers:
- image: centos/httpd
services:
- name: httpd
  type: NodePort
  ports:
  - port: 8080
    targetPort: 80

Now run the create command to deploy to Kubernetes

$ kedge create -f httpd.yaml
deployment "httpd" created
service "httpd" created

View the deployed service

$ minikube service httpd
Opening kubernetes service default/httpd in default browser...

$ kubectl describe svc httpd
Name:                   httpd
...
Endpoints:              172.17.0.4:80
...

Note: This markdown file is best viewed at kedgeproject.org/file-reference/.

Kedge is a simple, easy and declarative way to define and deploy applications to Kubernetes by writing very concise application definitions.

It's an extension of Kubernetes constructs and extends many concepts of Kubernetes you're familiar with, such as PodSpec.

Installation and Quick Start

Installing Kedge can be found at kedgeproject.org or alternatively, the GitHub release page.

If you haven't used Kedge yet, we recommend using the Quick Start guide, or follow the instructions within the side-bar.

Extending Kubernetes

Using the health key within containers

name: web
containers:
- image: nginx
  health:
    httpGet:
      path: /
      port: 80
    initialDelaySeconds: 20
    timeoutSeconds: 5
services:
- name: nginx
  type: NodePort
  ports:
  - port: 8080
    targetPort: 80

Alternatively, using readinessProbe instead of health

name: web
containers:
- image: nginx
  # https://kubernetes.io/docs/api-reference/v1.8/#container-v1-core
  livenessProbe:
    httpGet:
      path: /
      port: 80
    initialDelaySeconds: 20
    timeoutSeconds: 5
services:
- name: nginx
  type: NodePort
  ports:
  - port: 8080
    targetPort: 80

Kedge introduces a simplification of Kubernetes constructs in order to make application development simple and easy to modify/deploy.

However, in many parts of Kedge, you're able to use the standard Kubernetes constructs you may already know.

For example, Kedge simplifies deployment by introducing the health key. However, you can still use constructs such as readinessProbe or livenessProbe.

Kedge Keys

All defineable Kedge keys

name: <string>
controller: <string>
labels: <object>
containers:
  - <containerSpec>
volumeClaims:
  - <persistentVolume>
configMaps:
  - <configMap>
services:
  - <service>
ingresses:
  - <ingressObject>
routes:
  - <routeObject>
secrets:
  - <secret>
includeResources:
  - <includeResources>

Each "app" (Kedge file) is a Kubernetes Pod Spec with additional Kedge-specific keys.

Kedge specific

Field	Type	Required	Description
name	string	yes	The name of the app or micro-service this particular file defines.
controller	string	no	The Kubernetes controller of the app or micro-service this particular file (default: "deployment")
labels	object	no	Map of string keys and values that can be used to organize and categorize (scope and select) objects. May match selectors of replication controllers and services.
containers	array of containerSpec	yes	containerSpec object
volumeClaims	array of persistentVolume	no	persistentVolume object
configMaps	array of configMap	no	configMap object
services	array of service	no	service object
ingresses	array of ingress object	no	ingress object object
routes	array of route object	no	route object object
secrets	array of secret	no	secret object
includeResources	array of includeResources	no

name

name: mariadb

Type	Required	Description
string	yes	The name of the app or micro-service this particular file defines.

controller

controller: deployment

Type	Required	Description
string	no	The Kubernetes controller of the app or micro-service this particular file (default: "deployment")

defines.

Supported controllers:

Deployment
Job
DeploymentConfig

Default controller is Deployment

Note: activeDeadlineSeconds is a conflicting field which exists in both, v1.PodSpec and batch/v1.JobSpec, and both of these fields exist at the top level of the Kedge spec. So, whenever activeDeadlineSeconds field is set, only JobSpec is populated, which means that activeDeadlineSeconds is set only for the job and not for the pod. To populate a pod's activeDeadlineSeconds, the user will have to pass this field the long way by defining the pod exclusively under job.spec.template.spec.activeDeadlineSeconds.

labels

labels:
  env: dev
  department: middle-tier

Type	Required	Description
object	no	Map of string keys and values that can be used to organize and categorize (scope and select) objects. May match selectors of replication controllers and services.

All the configuration created will have this label applied. More info: http://kubernetes.io/docs/user-guide/labels

containers

containers:
- <containerSpec>

Type	Required	Description
array of containerSpec	yes	containerSpec object

volumeClaims

volumeClaims:
- <volume>

Type	Required	Description
array of persistentVolume	no	persistentVolume object

configMaps

configMaps:
- <configMap>

Type	Required	Description
array of configMap	no	configMap object

services

services:
- <service>

Type	Required	Description
array of service	no	service object

ingresses

ingresses:
- <ingressObject>

Type	Required	Description
array of ingress object	no	ingress object object

routes

routes:
- <routeObject>

Type	Required	Description
array of route object	no	route object object

secrets

secrets:
- <secret>

Type	Required	Description
array of secret	no	secret object

includeResources

includeResources:
- <string>

Example

includeResources:
- ./kubernetes/cron-job.yaml
- secrets.yaml

This is list of files that are Kubernetes specific that can be passed to Kubernetes directly. Of these files, Kedge will not do any processing, but simply pass it to the container orchestrator.

Type	Required	Description
array of includeResources	no	includeResources object

The file path are relative to the kedge application file.

This is one of the mechanisms to extend kedge beyond its capabilites to support anything in the Kubernetes land.

Objects

containerSpec

containers:
  - <containerSpec>

Each "container" is a Kubernetes Container Spec with additional Kedge-specific keys.

List of containers

Field	Type	Required	Description
health	string	yes	The name of the app or micro-service this particular file defines.

health

containers:
  - image: foobar
    health: <probe>

Type	Required	Description
string	yes	The name of the app or micro-service this particular file defines.

This is probe spec. Rather than defining livenessProbe and readinessProbe, define only health. And then it gets copied in both in the resultant spec. But if health and livenessProbe or readinessProbe are defined simultaneously then the tool will error out.

Kubernetes extension

Example extending containers with Kubernetes Container Spec

name: web
containers:
- image: nginx
  # https://kubernetes.io/docs/api-reference/v1.8/#container-v1-core
  env:
  - name: WORDPRESS_DB_PASSWORD
    value: wordpress
  - name: WORDPRESS_DB_USER
    value: wordpress
  envFrom:
  - configMapRef:
      name: web
services:
- name: nginx
  type: NodePort
  ports:
  - port: 8080
    targetPort: 80

Anything Container Spec from Kubernetes can be included within the Kedge file.

For example, keys such as env and envFrom are commonly used.

persistentVolume

volumeClaims:
  - <persistentVolume>

An example of deploying a volume

volumeClaims:
  - name: database
    size: 500Mi

Or further specifically defining it

volumeClaims:
  - name: database
    accessModes:
    - ReadWriteOnce
    resources:
      requests:
        storage: 500Mi

Each "persistentVolume" is a Kubernetes PersistentVolumeClaim with additional Kedge-specific keys.

Field	Type	Required	Description
name	string	yes	The name of the volume. This should match with the `volumeMount` defined in the `container`.
size	string	yes	Size of persistent volume claim to be created. Conflicts with resources field so define either of those.
resources	ResourceRequirements	yes	Resources represents the minimum resources the volume should have. Conflicts with size field so define either of those.
accessModes	array of string	no	AccessModes contains the desired access modes the volume should have. Defaults to `ReadWriteOnce`.

A user needs to define this list of volumes and then use it in the volumeMounts field in containers. In the resultant output the volumes in podSpec will be populated automatically by the tool.

name

name: database

Type	Required	Description
string	yes	The name of the volume. This should match with the `volumeMount` defined in the `container`.

size

size: 700Mi

Type	Required	Description
string	yes	Size of persistent volume claim to be created. Conflicts with resources field so define either of those.

resources

resources:
  requests:
    storage: 500Mi

Type	Required	Description
ResourceRequirements	yes	Resources represents the minimum resources the volume should have. Conflicts with size field so define either of those.

More info: http://kubernetes.io/docs/user-guide/persistent-volumes#resources

accessModes

accessModes:
- ReadWriteOnce

Type	Required	Description
array of string	no	AccessModes contains the desired access modes the volume should have. Defaults to `ReadWriteOnce`.

The access modes are:

ReadWriteOnce – the volume can be mounted as read-write by a single node
ReadOnlyMany – the volume can be mounted read-only by many nodes
ReadWriteMany – the volume can be mounted as read-write by many nodes

More info: http://kubernetes.io/docs/user-guide/persistent-volumes#access-modes-1

Kubernetes extension

Example extending volumesClaims with Kubernetes PersistentVolumeClaim Spec

name: database
containers:
- image: mariadb:10
  env:
  - name: MYSQL_ROOT_PASSWORD
    value: rootpasswd
  - name: MYSQL_DATABASE
    value: wordpress
  - name: MYSQL_USER
    value: wordpress
  - name: MYSQL_PASSWORD
    value: wordpress
  volumeMounts:
  - name: database
    mountPath: /var/lib/mysql
services:
- name: database
  ports:
  - port: 3306
volumeClaims:
- name: database
  size: 500Mi
  # https://kubernetes.io/docs/api-reference/v1.8/#persistentvolumeclaim-v1-core
  persistentVolumeReclaimPolicy: Recycle
  storageClassName: slow
  mountOptions:
    - hard
    - nfsvers=4.1

Anything PersistentVolumeClaim Spec from Kubernetes can be included within the Kedge file.

configMap

configMaps:
  - <configMap>

Example

configMaps:
- name: database
  data:
    MYSQL_DATABASE: wordpress
    app_data: /etc/app/data

Each "configMap" is a Kubernetes ConfigMap Spec with additional Kedge-specific keys.

Field	Type	Required	Description
name	string	yes	The name of the configMap. This is optional field if only one configMap is defined, the default name will be the app name.
data	object	yes	Data contains the configuration data. Each key must be a valid DNS_SUBDOMAIN with an optional leading dot.

Name

name: database

Type	Required	Description
string	yes	The name of the configMap. This is optional field if only one configMap is defined, the default name will be the app name.

Data

data:
  key: value

Type	Required	Description
object	yes	Data contains the configuration data. Each key must be a valid DNS_SUBDOMAIN with an optional leading dot.

A configMap is created out of this configuration.

Kubernetes extension

Example extending configMaps with Kubernetes ConfigMap Spec

name: database
containers:
- image: mariadb:10
  env:
  - name: MYSQL_ROOT_PASSWORD
    value: rootpasswd
  - name: MYSQL_DATABASE
    valueFrom:
      configMapKeyRef:
        key: MYSQL_DATABASE
        name: database
  - name: MYSQL_USER
    value: wordpress
  - name: MYSQL_PASSWORD
    value: wordpress
services:
- name: database
  ports:
  - port: 3306
configMaps:
- data:
  # https://kubernetes.io/docs/api-reference/v1.8/#configmap-v1-core
    MYSQL_DATABASE: wordpress

Anything ConfigMap Spec from Kubernetes can be included. Note: Since Kedge already implents "data" in ConfigMaps no other keys are available to be added.

service

services:
  - <service>

Example

services:
- name: wordpress
  ports:
  - port: 8080
    targetPort: 80
  portMappings:
  - 90:9090/tcp

Each "service" is a Kubernetes Service Spec with additional Kedge-specific keys.

Field	Type	Required	Description
name	string	yes	The name of the service.
endpoint	string	no	The endpoint of the service.
portMappings	array of "port"	no	Array of ports. Ex. `80:8080/tcp`

More info: https://kubernetes.io/docs/api-reference/v1.8/#servicespec-v1-core

Each service gets converted into a Kubernetes service and ingress respectively.

name

name: wordpress

Type	Required	Description
string	yes	The name of the service.

endpoint

endpoint: www.mycoolapp.com/admin

Type	Required	Description
string	yes	The endpoint of the service.

This is an added field in the Service port, which if specified an ingress resource is created. The ingress resource name will be the same as the name of service.

endpoint the way it is defined is can actually can be divided into two parts the URL and Path, it is delimited by a forward slash.

portMappings

portMappings:
- 8081:81/UDP

Type	Required	Description
array of "port"	yes	Array of ports. Ex. `80:8080/tcp`

portMappings is an added field to ServiceSpec. This lets us set the port, targetPort and the protocol for a service in a single line. This is parsed and converted to a Kubernetes ServicePort object.

portMappings is an array of port:targetPort/protocol definitions, so the syntax looks like -

portMappings:
- <port:targetPort/protocol>
- <port:targetPort/protocol>

The only mandatory part to specify in a portMapping is "port". There are 4 possible cases here

When only port is specified - targetPort is set to port and protocol is set to TCP
When port:targetPort is specified - protocol is set to TCP
When port/protocol is specified - targetPort is set to port
When port:targetPort/protocol is specified - no auto population is done since all values are provided

Find a working example using portMappings field here

Kubernetes extension

Example extending service with Kubernetes Service Spec

name: httpd
containers:
- image: centos/httpd
services:
- name: httpd
  # https://kubernetes.io/docs/api-reference/v1.8/#servicespec-v1-core
  ports:
  - port: 8080
    targetPort: 80
  type: NodePort

Anything Service Spec from Kubernetes can be included within the Kedge file.

For example, keys such as image and ports are commonly used.

ingressObject

ingresses:
- <ingress>

Each "ingress" is a Kubernetes Ingress Spec with additional Kedge-specific keys.

Type	Required	Description
name	string	yes

If there is only one port and user wants to expose the service then user should define one ingress with host atleast then the rest of the ingress spec (things like http, etc.) will be populated for the user.

name

name: wordpress

Type	Required	Description
string	yes	The name of the Ingress.

Kubernetes extension

Example extending ingresses with Kubernetes Ingress Spec

ingresses:
- name: wordpress
  # https://kubernetes.io/docs/api-reference/v1.8/#ingressspec-v1beta1-extensions
  rules:
  - host: minikube.local
    http:
      paths:
      - backend:
          serviceName: wordpress
          servicePort: 8080
        path: /

Anything Ingress Spec from Kubernetes can be included within the Kedge file.

routeObject

routes:
- <route>

Example

name: webroute
to:
  kind: Service
  name: httpd

Each "route" is an OpenShift Route Spec with additional Kedge-specific keys.

Type	Required	Description
name	string	yes

name

name: wordpress

Type	Required	Description
string	yes	The name of the Route

OpenShift extension

Example extending routes with OpenShift Route Spec

routes:
- name: httpd
  # https://docs.openshift.org/latest/rest_api/apis-route.openshift.io/v1.Route.html#object-schema
  to:
    kind: Service
    name: httpd

Anything Route Spec from OpenShift can be included within the Kedge file.

secret

secrets:
  - <secret>

Each "secret" is a Kubernetes EnvVarSource Spec with additional Kedge-specific keys.

Name

name: wordpress

Type	Required	Description
string	no	The name of the secret

Kubernetes extension

Example extending service with Kubernetes Service Spec

secrets:
- name: wordpress
  data:
    # https://kubernetes.io/docs/api-reference/v1.8/#envvarsource-v1-core
    # Encoded in base64
    MYSQL_ROOT_PASSWORD: YWRtaW4=
    MYSQL_PASSWORD: cGFzc3dvcmQ=

Anything EnvVarSource Spec from Kubernetes can be included within the Kedge file.

includeResources

includeResources:
- <string>

Example

includeResources:
- ./kubernetes/cron-job.yaml
- secrets.yaml

Including external resources.

Type	Required	Description
string	no	File location of the Kubernetes resource

Variables

You can use variables anywhere in the Kedge file. Variable names are enclosed in double square brackets ([[ variable_name ]]). For example [[ IMAGE_NAME ]] will be replaced with value of environment variable $IMAGE_NAME

Example

# nginx.yaml

name: nginx
containers:
- image: nginx:[[ NGINX_VERSION ]]
services:
- name: nginx
  ports:
  - port: 8080
    targetPort: 80

Now you can call Kedge and define NGINX_VERSION variable.

NGINX_VERSION=1.13 kedge apply -f nginx.yaml

The string [[ NGINX_VERSION ]] will be replaced with 1.13. Effecting Kedge file will look as following:

name: nginx
containers:
- image: nginx:1.13
services:
- name: nginx
  type: ClusterIP
  ports:
  - port: 8080
    targetPort: 80

Examples

Example file

An example of using all possible Kedge-specific keys.

name: database
controller: deployment
containers:
- image: mariadb:10
  envFrom:
  - configMapRef:
      name: database
  - secretRef:
      name: wordpress
  volumeMounts:
  - name: database
    mountPath: /var/lib/mysql
  health:
    httpGet:
      path: /
      port: 3306
services:
- name: wordpress
  ports:
  - port: 8080
    targetPort: 80
    endpoint: minikube.external/foo
volumeClaims:
- name: database
  size: 500Mi
configMaps:
- data:
    MYSQL_DATABASE: wordpress
secrets:
- name: wordpress
  data:
    MYSQL_ROOT_PASSWORD: YWRtaW4=

Deployment

name: database
containers:
- image: mariadb:10
  envFrom:
  - configMapRef:
      name: database
  - secretRef:
      name: wordpress
  volumeMounts:
  - name: database
    mountPath: /var/lib/mysql
  livenessProbe:
    httpGet:
      path: /
      port: 3306
  readinessProbe:
    exec:
      command:
      - mysqladmin
      - ping
    initialDelaySeconds: 5
    timeoutSeconds: 1
services:
- name: wordpress
  expose: true
  ports:
  - port: 8080
    targetPort: 80
    endpoint: minikube.external/foo
ingresses:
- name: pseudo-wordpress
  rules:
  - host: minikube.local
    http:
      paths:
      - backend:
          serviceName: wordpress
          servicePort: 8080
        path: /
volumeClaims:
- name: database
  size: 500Mi
  accessModes:
  - ReadWriteOnce
configMaps:
- data:
    MYSQL_DATABASE: wordpress
secrets:
- name: wordpress
  data:
    MYSQL_ROOT_PASSWORD: YWRtaW4=

Job

controller: job
name: pival
containers:
- image: perl
  command: ["perl",  "-Mbignum=bpi", "-wle", "print bpi(2000)"]
restartPolicy: Never
parallelism: 3

Deployment Config

controller: deploymentconfig
name: httpd
replicas: 2
containers:
- image: centos/httpd
services:
- name: httpd
  type: NodePort
  ports:
  - port: 8080
    targetPort: 80

Files

file-reference.md

Latest commit

History

file-reference.md

File metadata and controls

Introduction

Extending Kubernetes

Kedge Keys

Kedge specific

name

controller

labels

containers

volumeClaims

configMaps

services

ingresses

routes

secrets

includeResources

Objects

containerSpec

health

Kubernetes extension

persistentVolume

name

size

resources

accessModes

Kubernetes extension

configMap

Name

Data

Kubernetes extension

service

name

endpoint

portMappings

Kubernetes extension

ingressObject

name

Kubernetes extension

routeObject

name

OpenShift extension

secret

Name

Kubernetes extension

includeResources

Variables

Example

Examples

Example file

Deployment

Job

Deployment Config