NAV Navbar

Kedge File Reference

yaml
  • Introduction
  • Kedge Keys
  • Objects
  • Variables
  • 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>
    

    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
    
    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
    
    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>
    

    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>
    
    Type Required Description
    string yes The name of the app or microservice 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
    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
    
    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:

    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
    
    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
    
    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

    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>
    
    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>
    

    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
    
    Field Type Required Description
    containers array of containerObject yes containerObject

    routeObject

    routes:
    - <route>
    

    Example

    name: webroute
    to:
      kind: Service
      name: httpd
    
    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"
    
    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"
    
    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.