YAML Specification

Navigation:  »No topics above this level«

YAML Specification

Previous pageReturn to chapter overviewNext page

The following specification is made using an example of YAML file, through which you can create a Pod with official WordPress and MySQL container images configured for the WordPress web-site comprehensive work. You can find YAML file in our github repository (https://github.com/cloudlinux/kuberdock_predefined_apps).

 

Note that you can use variables to set proper values for YAML file fields, transfer values from one field to another, generate value automatically and to show variables values in pre- and postDescription. For example:

 

To define field values use format:

 

$VAR_NAME|default:default_value|some text to show”

 

where:

 

 $VAR_NAME - variable name that can be used in other parts of YAML file;

 default - this variable default value. If enter "autogen", then this value will be autogenerated (8 characters, lower case, letters and numbers). For cPanel use “user_domain_list”, to enter the domans and subdomains list for user to choose;

          some text to show - title for a field specified by a user;

 

For pre-, postDescription and cPanel sections use %VAR_NAME% (between percent symbols). This will show $VAR_NAME value in pre- or postDescription.

 

To use a variable in some other part of YAML file use syntax $VAR_NAME$. This will return value of variable $VAR_NAME.

 

Note that you can use global variables in YAML. Their values can not be set. Use percent symbol (e.g. %PUBLIC_ADDRESS%) to show global variables values. Available global variables:

 

PUBLIC_ADDRESS - returns Public IP allocated to the pod;

USER_DOMAIN - returns main user domain in cPanel.

 

YAML File Description:

 

apiVersion: v1

kind: ReplicationController

 

metadata:

name:$APP_NAME|default:wordpress|app name$

 

metadata -  application name in cPanel and Pod name in KuberDock at the same time.

$APP_NAME|default:autogen|app name$ -

 

kuberdock:

icon: url_to_icon

packageID: 0

preDescription: |

    You are installing the application [b]WordPress[/b].

    The WordPress rich content management system can utilize plugins, widgets, and themes.

    All the components needed for this application correct work will also be installed: [b]MySQL[/b] server.

    Choose the amount of resources or use recommended parameters.

    When you click "Order now", you will get to order processing page.

  postDescription: |

    You have installed [b]WordPress![/b]

    To access [b]WordPress[/b] use this link: [url]http://%PUBLIC_ADDRESS%[/url]

    name: Wordpress

 

kuberdock section defines Pod parameters for KuberDock:

icon - link to application icon in .png;

packageID - optional, package ID in KuberDock database.  If this parameter is not specified in YAML, then package_id value will equal 0 when started from KuberDock, or equal to value from Application defaults when started from cPanel.

preDescription - text to show user before application start, will be displayed on the page with plans;

postDescription - text to show user after application start. BBCode can be used to format text. Note that if you use YAML in cPanel then write [url]http://%APP_DOMAIN%[url] instead of [url]http://%PUBLIC_ADDRESS%[/url]. APP_DOMAIN must be equal to domain parameter in proxy section.

name - defines application name for user in cPanel web-interface.

 

appPackages:

    - name: S

      goodFor: up to 100 users

      publicIP: true

      # or “baseDomain: example.com”

      packagePostDescription: |

      Special description in a specific package for the application

      pods:

        -

          name: $APP_NAME$

          kubeType: 1

          containers:

            - name: mysql

              kubes: 1

            - name: wordpress

              kubes: 1

          persistentDisks:

            - name: mysql-persistent-storage

              pdSize: 1

            - name: wordpress-persistent-storage

              pdSize: 1

   - name: M

      recommended: yes

      goodFor: up to 100K visitors

      publicIP: true

      pods:

        -

          name: $APP_NAME$

 

appPackages - starts describing packages available for user to start predefined application; a bunch of resources allocated to a Pod and to containers in it. In one YAML can be 4 or less appPackages.

name - appPackage name. We recommend to use 3 or less words in the field (e.g. -S, -M, -XL, -XXL) because it is good for existing theme.

recommended - only one plan can be recommended, it will be highlighted in web-interface.

goodFor - short text to show to user.

publicIP - defines if Public IP is available for this appPackage.  If container parameter for isPublic port in specification is "true", then publicIP should be "true" as well, to assign public IP. If publicIP value is "false", then public IP will not be assigned.

baseDomain - defines if pod will get service address based ob domain instead of public IP if any container port has parameter isPublic with value “true”. In case when domain user does not see the price for domain in the application package details. Note, that it is strongly recommended not to use publicIP and baseDomain in one appPackage.

packagePostDescription - use this description if you need to explain the difference between application usage in each package. For example, if you have not provide public IP in one of the packages, then postDescription for a whole YAML cannot be used.

pods - resources allocated to each pod.

name - name of the pod for which resources are allocated.

kubeType - Kube type ID in KuberDock database.

containers - describes Kubes number to be assigned to each container in YAML.

name - container name in container specification below.

kubes - number of Kubes for this container.

persistentDisks - persistent discs capacity.

name - persistent disk name.

pdSize - persistent disk size in GB. Note that in case of CEPH as a backend for persistent storage it is impossible to resize storage thus when customer will switch application package than persistent storage size will be the same for all packages which is equal to the current application package. In other case, it is possible to resize persistent storage if application package will have the same Kube Type as current application package.

 

proxy: 

     wordpress:

       container: wordpress

       domain: $APP_DOMAIN|default:user_domain_list|Select your domain$

 

proxy - sub-section is required for cPanel to do proxy to user domain. Not used in our original YAML for Wordpress application. This is just an example. You can set as many path as you need:

wordpress - path after domain, for example: http://domain.com/wordpress;

container - container image name used in YAML for which path will be used;

domain - show user domain list during predefined application setup to use with that path.

You can set paths for each container image in YAML.

 

spec:

  template:

    metadata:

      labels:

        name: $APP_NAME$

 

spec section starts describing each YAML container specification.

In template subsection we need to have metadata, where name field must be the same variable as in name field of metadata section above. This is required for KuberDock system pod name.

 

spec:

      volumes:

       - name: mysql-persistent-storage

         persistentDisk:

           pdName: wordpress_mysql_$PD_RAND|default:autogen|PD rand$

       - name: wordpress-persistent-storage

         persistentDisk:

           pdName: wordpress_www_$PD_RAND$

 

spec subsection starts describing pod specification. We begin to describe persistent volumes that will be used in the pod:

name - this is a name of volume to be used in container.

persistentDisk - if this volume uses some of persistent storages (ceph for example).

pdName - name of persistent disk within persistent storage. We use $PD_RAND$ variable to autogenerate random part of name. That will give possibility to create different volumes names for each user.

 

 restartPolicy: "Always"

 

restartPolicy field describe which restart policy will be used for this pod.

 

resolve: ["mysql", "wordpress"]

 

resolve field allows to resolve dns-name within a pod. This part is not used in YAML file for Wordpress application from our github repository. But, for example, Redmine needs to resolve dns-name mysql.

You can add more dns-names, separated by space.

 

containers:

        name: wordpress

        image: wordpress:4.4

 

containers field shows containers list within the pod.

name - name of a container within the pod.

image - container image name in DockerHub and a tag of image after “:”. You can find a tag in DockerHub registry in Tag tab on container image page. It is strongly recommended not to use tag latest, otherwise proper restore function of the application (pod) is not guaranteed, because latest means latest image at the current time,but latest image days or month ago can be different.

 

 env:

            - name: WORDPRESS_DB_USER

               value: "wordpress"

            - name: WORDPRESS_DB_NAME

               value: "wordpress"

            - name: WORDPRESS_DB_PASSWORD

               value: $MYSQL_USER_PASSWORD$

            - name: WORDPRESS_DB_HOST

               value: "127.0.0.1"

 

env - begins a list of environment variables of this container image “mysql:5”

name - environment variable name.

value - environment variable value.

Note that it is recommended to specify value in quotes. If value consists of digits only, then quotation marks are required (for example, “1234”). If you use variable in value parameter, then quotes are not required.

Note that to connect containers within the same pod you need to use IP 127.0.0.1 instead localhost.

 

ports:

        - containerPort: 80

          protocol: TCP

          podPort: 8080

          isPublic: true

 

ports field begins a list of ports to expose for this container image.

containerPort - ports number to be exposed.

protocol - protocol type for this port.

podPort - defines Pod port for this containerPort. Learn more about Pod port here. If podPort value is missing, it equals to containerPort by default.

isPublic - expose port to PublicIP. If you want to make this port available from the web, then this value must be "true".

If at least one PublicIP parameter in the whole YAML is "true", then Public IP will be assigned.

 

readinessProbe:

        tcpSocket:

            port: 80

        initialDelaySeconds: 5

        timeoutSeconds: 10

        periodSeconds: 15

        successThreshold: 1

        failureThreshold: 2

 

readinessProbe or livenessProbe  (read more in official Kubernetes documentation) allows to add tests to check if application (pod) successfully launched with all its containers. It is available to add the following tests:

 

exec: executes a specified command inside the container expecting on success that the command exits with status code 0. Example:

 

exec:

        command:

        - cat

        - /tmp/health

 

Where “- cat” is the command and “- /tmp/health” is the parameter.

 

tcpSocket: performs a TCP check against the container’s IP address on a specified port expecting on success that the port is open.

 

tcpSocket:

                  port: 80

 

Where “port” is a number of port to be tested.

 

httpGet: performs an HTTP Get against the container’s IP address on a specified port and path expecting on success that the response has a status code greater than or equal to 200 and less than 400.

 

httpGet

        path: /health

        port: 8080

        httpHeaders:

          - name: X-Custom-Header

            value: Awesome

 

Where “path” is the path for http request, “port” is the number of the port to be used, “httpHeader” name and value for request header.

 

Each probe will have one of three results:

 

Success: indicates that the container passed the diagnostic and status of pod becomes Running.

 

Failure: indicates that the container failed the diagnostic and status of the pod becomes Pending.

 

It is also possible to add conditions to the test:

 

initialDelaySeconds - number of seconds after the container has started before liveness probes are initiated.

 

timeoutSeconds - number of seconds after which the probe times out. Defaults to 1 second. Minimum value is 1.

 

periodSeconds - how often (in seconds) to perform the probe. Defaults to 10 seconds. Minimum value is 1.

 

successThreshold - minimum consecutive successes for the probe to be considered successful after having failed. Defaults to 1. Minimum value is 1.

 

failureThreshold - minimum consecutive failures for the probe to be considered failed after having succeeded. Defaults to 3. Minimum value is 1.

 

 

 volumeMounts:

        - mountPath: /var/lib/mysql

          name: wordpress-persistent

 

volumeMounts begins a list of container directories which will be mounted to persistent storage or persistent local storage. It depends on type of volumes above.

mountPath - mount path within the container.

name - name of persistent storage to be used (name parameter from volumes section).

 

name: mysql

     image: mysql:5

     env:

      - name: MYSQL_DATABASE

        value: "wordpress"

      - name: MYSQL_USER

        value: "wordpress"

      - name: MYSQL_PASSWORD

        value: $MYSQL_USER_PASSWORD|default:autogen|mysql password$

      - name: MYSQL_ROOT_PASSWORD

        value: $MYSQL_ROOT_PASSWORD|default:autogen|mysql password$

     ports:

       - containerPort: 3306

     volumeMounts:

       - mountPath: /var/lib/mysql

         name: mysql-persistent-storage

 

Here we describe the next MySQL container image in the pod.