Permalink
Fetching contributors…
Cannot retrieve contributors at this time
1180 lines (874 sloc) 39.5 KB

Introduction

Using an example httpd.yaml file.

name: httpd

deployments:
- containers:
  - image: centos/httpd

services:
- name: httpd
  type: LoadBalancer
  portMappings: 
    - 8080:80

Now run the apply command to deploy to Kubernetes

$ kedge apply -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

Extending Kedge as well as using a shortcut

name: web

deployments:
- name: web
  containers:
  - image: nginx
    # Extending the Kedge file using:
    # https://v1-6.docs.kubernetes.io/docs/api-reference/v1.6/#container-v1-core
    livenessProbe:
      httpGet:
        path: /
        port: 80
      initialDelaySeconds: 20
      timeoutSeconds: 5

services:
- name: nginx
  type: NodePort
  # Using a Kedge-specific 'shortcut'
  portMappings:
  - 8080: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>
appversion: <string>
controller: <string>
labels: <object>
deployments:
- <deploymentObject>
jobs:
- <jobObject>
deploymentConfigs:
- <deploymentConfigObject>
volumeClaims:
- <persistentVolumeObject>
configMaps:
- <configMapObject>
services:
- <serviceObject>
ingresses:
- <ingressObject>
routes:
- <routeObject>
secrets:
- <secretObject>
imageStreams:
- <imageStreamObject>
buildConfigs:
- <buildConfigObject>
includeResources:
- <includeResources>
Depending on the controller key selected. Each controller (deployments, jobs, deploymentConfigs) is an extension of Kubernetes (or OpenShift with deploymentConfigs). Anything defineable within Kubernetes may also be defined within Kedge. See objects for more information.

Kedge Root Keys

Root keys are definable in the innermost section of a YAML file.

Field Type Required Description
name string yes The name of the app or microservice this particular file defines.
appversion string no The version of the app or microservice this particular file defines.
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.
deployments array of deploymentObject no deploymentObject
jobs array of jobObject no jobObject
volumeClaims array of persistentVolumeObject no persistentVolumeObject
configMap array of configMapObject no configMapObject
services array of serviceObject no serviceObject
ingresses array of ingressObject no ingressObject
secrets array of secretObject no secretObject
deploymentConfigs array of deploymentconfigobject no deploymentconfigobject
routes array of routeObject no routeObject
imageStreams array of imageStreamObject no imageStreamObject
buildConfigs array of buildConfigObject no buildConfigObject
includeResources array of includeResourceObject no includeResourceObject

name

name: mariadb
Type Required Description
string yes The name of the app or microservice this particular file defines.

appversion

appversion: 5.0.0-alpha
Type Required Description
string no The version of the app or microservice this particular file defines.

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 kubernetes.io/docs/user-guide/labels

deployments

deployments:
- <deploymentObject>
Type Required Description
array of deploymentObject no deploymentObject

jobs

jobs:
- <jobObject>
Type Required Description
array of jobObject no jobObject

deploymentConfigs

deploymentConfigs:
- <deploymentConfigObject>
Type Required Description
array of deploymentConfigObject no deploymentConfigObject

volumeClaims

volumeClaims:
- <volume>
Type Required Description
array of persistentVolumeObject no persistentVolumeObject

configMaps

configMaps:
- <configMapObject>
Type Required Description
array of configMapObject no configMapObject

services

services:
- <service>
Type Required Description
array of serviceObject no serviceObject

ingresses

ingresses:
- <ingressObject>
Type Required Description
array of ingressObject no ingressObject

routes

routes:
- <routeObject>
Type Required Description
array of routeObject no routeObject

secrets

secrets:
- <secret>
Type Required Description
array of secretObject no secretObject

buildConfigs

buildConfigs:
- <buildConfigObject>
Type Required Description
array of buildConfig Object no buildConfig Object object

imageStreams

imageStreams:
- <imageStreamObject>
Type Required Description
array of imageStream Object no imageStream Object 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 includeResourceObject no includeResourceObject

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

Some objects are extension(s) of their Kubernetes / OpenShift counterparts. Below is a chart that lists each extension:

Key Field Extension of
deployments deploymentObject Kubernetes Deployment
jobs jobObject Kubernetes Job
containers containerObject Kubernetes Container
volumeClaims persistentVolumeObject Kubernetes PersistentVolumeClaim
services serviceObject Kubernetes Service
ingresses ingressObject Kubernetes Ingress
secrets secretObject Kubernetes EnvVarSource
deploymentConfigs deploymentConfigObject OpenShift DeploymentConfig
routes routeObject OpenShift Route
buildConfigs buildConfigObject OpenShift BuildConfig
imageStreams imageStreamObject OpenShift ImageStream
includeResourcs includeResourceObject N/A

deploymentObject

Example using the Kubernetes Deployment controller

name: httpd

deployments:
- containers:
  - image: centos/httpd

services:
- name: httpd
  type: LoadBalancer
  portMappings: 
    - 8080:80
Each "deployments" is a Kubernetes Deployment Spec with additional Kedge-specific keys.
Field Type Required Description
containers array of containerObject yes containerObject

jobObject

Example using the Kubernetes Jobs controller

name: pival

jobs:
- containers:
  - image: perl
    command: ["perl",  "-Mbignum=bpi", "-wle", "print bpi(2000)"]
  # Job-related definitions
  restartPolicy: Never
  parallelism: 3
Each "jobs" is a Kubernetes Job Spec with additional Kedge-specific keys.
Field Type Required Description
containers array of containerObject yes containerObject

containerObject

Using the deployments controller

deployments:
- containers:
  - <containerObject>

Using the deploymentConfigs controller with name.

deploymentConfigs:
- name: foo
  containers:
    - <containerObject>
Each "container" is a Kubernetes Container Spec with additional Kedge-specific keys.

The containers key is used with every type of controller (deployments, jobs, deploymentConfigs).

List of containers

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

health

containers:
- image: foobar
  health: <probe>

Using health with a Guestbook example

deployments:
- containers:
  - name: guestbook
    image: gcr.io/google_containers/guestbook:v3
    health:
      httpGet:
        path: /
        port: 3000
      initialDelaySeconds: 20
      timeoutSeconds: 5
Type Required Description
string yes A probe as defined by Kubernetes Probe v1 core

health copies a Kubernetes Probe spec to both livenessProbe and readinessProbe. Thus only having to define it once.

Kubernetes extension

Example extending containers with Kubernetes Container Spec

name: web
deployments:
- containers:
  - name: nginx
    image: nginx
    # https://v1-6.docs.kubernetes.io/docs/api-reference/v1.6/#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.

persistentVolumeObject

volumeClaims:
- <persistentVolumeObject>

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 "persistentVolumeObject" 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://v1-6.docs.kubernetes.io/docs/api-reference/v1.6/#persistentvolumeclaim-v1-core
  persistentVolumeReclaimPolicy: Recycle
  storageClassName: slow
  mountOptions:
    - hard
    - nfsvers=4.1

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

configMapObject

configMaps:
- <configMapObject>

Example

configMaps:
- name: database
  data:
    MYSQL_DATABASE: wordpress
    app_data: /etc/app/data
Each "configMapObject" is a Kubernetes ConfigMap Spec with additional Kedge-specific keys.
Field Type Required Description
name string yes The name of the configMapObject. This is optional field if only one configMapObject 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 configMapObject. This is optional field if only one configMapObject 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 configMapObject is created out of this configuration.

Kubernetes extension

Example extending configMapObjects 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://v1-6.docs.kubernetes.io/docs/api-reference/v1.6/#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.

serviceObject

services:
- <serviceObject>

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: v1-6.docs.kubernetes.io/docs/api-reference/v1.6/#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://v1-6.docs.kubernetes.io/docs/api-reference/v1.6/#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 yes The name of the Ingress

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://v1-6.docs.kubernetes.io/docs/api-reference/v1.6/#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.

secretObject

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://v1-6.docs.kubernetes.io/docs/api-reference/v1.6/#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.

deploymentConfigObject

Example using the OpenShift DeploymentConfig controller

name: httpd

deploymentConfigs:
- containers:
  - image: bitnami/nginx
  # DeploymentConfig related definitions
  replicas: 2

services:
- name: httpd
  type: NodePort
  ports:
  - port: 8080
    targetPort: 8080
Each "deploymentConfigs" is an OpenShift Deployment Config Spec with additional Kedge-specific keys.
Field Type Required Description
containers array of containerObject yes containerObject

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 yes The name of the Route

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.

buildConfigObject

buildConfigs:
- <buildConfigObject>

Example

name: rubybc
triggers:
- type: "ImageChange"
source:
  type: "Git"
  git:
    uri: "https://github.com/openshift/ruby-hello-world"
strategy:
  type: "Source"
  sourceStrategy:
    from:
      kind: "ImageStreamTag"
      name: "ruby-22-centos7:latest"
output:
  to:
    kind: "ImageStreamTag"
    name: "origin-ruby-sample:latest"
Each "buildConfigObject" is an OpenShift BuildConfig Spec with additional Kedge-specific keys.
Type Required Description
name yes The name of the BuildConfig

name

name: wordpress
Type Required Description
string yes The name of the BuildConfig

OpenShift extension

Example extending buildConfigs with OpenShift BuildConfig Spec

name: ruby
buildConfigs:
- triggers:
  - type: "ImageChange"
  source:
    type: "Git"
    git:
      uri: "https://github.com/openshift/ruby-hello-world"
  strategy:
    type: "Source"
    sourceStrategy:
      from:
        kind: "ImageStreamTag"
        name: "ruby-22-centos7:latest"
  output:
    to:
      kind: "ImageStreamTag"
      name: "origin-ruby-sample:latest"

imageStreamObject

imageStreams:
- <imageStreamObject>

Example

name: rubyapp
imageStreams:
- name: rubystream
  dockerImageRepository: "docker.io/openshift/ruby-20-centos7"
Each "imageStreamObject" is an OpenShift ImageStream Spec with additional Kedge-specific keys.
Type Required Description
name yes The name of the ImageStream

name

name: wordpress
Type Required Description
string yes The name of the ImageStream

OpenShift extension

Example extending imageStreams with OpenShift ImageStream Spec

name: webapp
imageStreams:
- tags:
  - from:
      kind: DockerImage
      name: centos/httpd-24-centos7:latest
    name: "2.4"

includeResourceObject

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

Example using local environment variables

name: nginx

deployments:
- containers:
  - image: nginx:[[ NGINX_VERSION ]]

services:
- name: nginx
  ports:
  - port: 8080
    targetPort: 80

Using the variables on the command line

NGINX_VERSION=1.13 kedge apply -f nginx.yaml

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.

Specify default value of variable,

name: foo
image: foo/bar:[[ TAG:latest ]]

You can specify a default value of a variable if it is not set. For example: [[ TAG:latest ]] If TAG variable is not set, latest will be used.