YAML_Specification.txt

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.
    name:$APP_NAME|default:wordpress|app name$ - the name will be set to "wordpress" but it could be changed.

++++++++++++++++++++++++
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: false
      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 to user. If 
publicIP value is "false", then public IP will not be assigned.
    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.

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

++++++++++++++++++++++++
volumeMounts:
        - mountPath: /var/lib/mysql
          name: wordpress-persistent
          kdCopyFromImage: true
++++++++++++++++++++++++

  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).
    kdCopyFromImage - If set to true contents of the mountPath folder will be 
    coppied from the docker image the container is created from on PODs creation. False by default.
++++++++++++++++++++++++
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.