Files documentation update. (#5)

source/pages/pipelines/building_failure_handlers.rst

@@ -81,3 +81,31 @@ Below is an example of running a :attr:`failure handlers<FailureHandler>` from b
 .. note::
   Notice that ``failure-handler-1`` will run twice because it's declared in both the global section and in the step. Currently IceCI does not implement any deduplication mechanism for failure handlers.
 
+
+Environment variables and files
+_______________________________
+
+Here's an example of defining environment variables and files on :attr:`failure handler<FailureHandler>` level.
+
+.. code-block:: yaml
+
+  steps:
+  - name: step-that-fails
+    dockerRun:
+      image: busybox
+      script: "noSuchCommand"
+    onFailure:
+    - handlerName: failure-handler-1
+
+  failureHandlers:
+  - name: failure-handler-1
+    image: busybox
+    script: |
+      echo $ICE_FH
+      cat /mnt/file
+    environment:
+    - name: ICE_FH
+      value: failure-handler-env
+    files:
+    - path: /mnt/file
+      fromSecret: failure-secret

source/pages/pipelines/building_globals.rst

@@ -17,7 +17,10 @@ Some of the settings that can be specified for :attr:`steps<Step>` can also be s
 Examples
 ++++++++
 
-Below is an example of setting up a :attr:`global<globals>` environment variables, and overriding them on :attr:`step<Step>` level.
+Environment variables
+_____________________
+
+Below is an example of setting up a :attr:`global<globals>` environment variables and overriding them on :attr:`step<Step>` level.
 
 .. code-block:: yaml
 
@@ -40,3 +43,28 @@ Below is an example of setting up a :attr:`global<globals>` environment variable
       - name: GLOBAL_ENV
         value: local-value
 
+Files
+_____
+
+Here's an example of setting up a :attr:`global<globals>` file and overriding it on :attr:`step<Step>` level.
+
+.. code-block:: yaml
+
+  globals:
+    files:
+    - path: /mnt/file
+      fromSecret: global-secret
+
+  steps:
+  - name: step1
+    dockerRun:
+      image: busybox
+      script: "cat /mnt/file"
+
+  - name: step2
+    dockerRun:
+      image: busybox
+      script: "cat /mnt/file"
+      files:
+      - path: /mnt/file
+        fromSecret: local-secret

source/pages/pipelines/building_steps.rst

@@ -84,6 +84,28 @@ Here's an example of passing environment variables to a container.
 
   As you can see, the environment variable value is hardcoded into the pipeline. This is fine if your build configuration doesn't contain passwords or other sensitive data. For more information on how to manage sensitive data in ``IceCI`` see :ref:`secrets section<secrets-desc>`.
 
+Files
+_____
+
+Here's an example of mounting files from a secret in a container.
+
+.. code-block:: yaml
+
+  steps:
+  - name: file-test
+    dockerRun:
+      image: busybox
+      script: "cat /mnt/file"
+      files:
+      - path: /mnt/file
+        fromSecret: file-secret
+
+.. note::
+
+  The content of a file can't be defined inline. Every file has to have a reference to a secret, from which the content is pulled.
+
+
+
 Further reading
 +++++++++++++++
 

source/pages/pipelines/structure.rst

@@ -67,7 +67,15 @@ The root of pipeline yaml file consists of the following fields.
     Those environment variables will be passed to every :attr:`Docker run step<DockerRun>` in the pipeline.
 
     .. important::
-      ``Failure handlers`` have access to all the environment variables of a given ``step`` injected into their spec, so they're available in the failure handler as well. For more information about passing environment variables to failure handlers see TODO
+      ``Failure handlers`` have access to all the environment variables of a given ``step`` injected into their spec, so they're available in the failure handler as well.
+
+  .. py:attribute:: files
+    :type: list(File)
+
+    List of files that will be mounted in every :attr:`Docker run step<DockerRun>` in the pipeline.
+
+    .. important::
+      Like environment variables, files from a given ``step`` are also mounted into ``Failure handlers``.
 
 
 
@@ -143,6 +151,11 @@ Definitions of all objects and types used in the pipeline definition.
 
     List of environment variables passed to the container.
 
+  .. py:data:: files
+    :type: list(File)
+
+    List of files that will be mounted in the container.
+
 
 
 .. _docker-build-reference:
@@ -261,6 +274,11 @@ Definitions of all objects and types used in the pipeline definition.
 
     List of environment variables passed to the container.
 
+  .. py:data:: files
+    :type: list(File)
+
+    List of files that will be mounted in the container.
+
 
 .. _failure-handler-reference-reference:
 
@@ -296,3 +314,20 @@ Definitions of all objects and types used in the pipeline definition.
 
   .. note::
     Currently ``IceCI`` supports creating environment variables by explicitly entering their values in the pipeline yaml or by providing a secret name from which the value should be taken. Those options are exclusive for a given variable - you can't have both :attr:`value` and :attr:`fromSecret` set at the same time - the pipeline validation will fail.
+
+
+
+.. _file-reference:
+
+.. py:attribute:: File
+  :type: Object
+
+  The file object represents a file that'll be mounted in a container from a secret. Unlike environment variables, file values cannot be provided inline - they have to reference a secret.
+
+  .. py:attribute:: path
+
+    The absolute path that the file will be mounted in.
+
+  .. py:attribute:: fromSecret
+
+    Name of a secret from which the value should be retrieved to mount into the container as a file.