Merge pull request #130 from screwdriver-cd/configuration

feat: add more detailed configuration information
screwdriver-cd · Dec 20, 2017 · 5462ade · 5462ade
2 parents 44def7b + e734243
commit 5462ade
Show file tree

Hide file tree

Showing 7 changed files with 363 additions and 18 deletions.
diff --git a/docs/_data/menu.yml b/docs/_data/menu.yml
@@ -1,21 +1,5 @@
 - title: "Home"
   url: "/"
-- title: "Cluster Management"
-  subcategories:
-    - title: "Overall Architecture"
-      url: "/cluster-management/"
-    - title: "Configuring the API"
-      url: "/cluster-management/configure-api"
-    - title: "Configuring the UI"
-      url: "/cluster-management/configure-ui"
-    - title: "Configuring the Store"
-      url: "/cluster-management/configure-store"
-    - title: "Running Locally"
-      url: "/cluster-management/running-locally"
-    - title: "Examples"
-      subcategories:
-        - title: "Kubernetes"
-          url: "/cluster-management/kubernetes"
 - title: "User Guide"
   subcategories:
     - title: "Quickstart"
@@ -28,16 +12,42 @@
       subcategories:
         - title: "Overall"
           url: "/user-guide/configuration/"
-        - title: "Metadata"
-          url: "/user-guide/configuration/metadata"
+        - title: "Job Configuration"
+          url: "/user-guide/configuration/jobconfiguration"
+        - title: "Workflow"
+          url: "/user-guide/configuration/workflow"
+        - title: "Environment"
+          url: "/user-guide/configuration/environment"
+        - title: "Settings"
+          url: "/user-guide/configuration/settings"
+        - title: "Annotations"
+          url: "/user-guide/configuration/annotations"
         - title: "Secrets"
           url: "/user-guide/configuration/secrets"
+    - title: "Metadata"
+      url: "/user-guide/metadata"
     - title: "Environment Variables"
       url: "/user-guide/environment-variables"
     - title: "Templates"
       url: "/user-guide/templates"
     - title: "FAQ"
       url: "/user-guide/FAQ"
+- title: "Cluster Management"
+  subcategories:
+    - title: "Overall Architecture"
+      url: "/cluster-management/"
+    - title: "Configuring the API"
+      url: "/cluster-management/configure-api"
+    - title: "Configuring the UI"
+      url: "/cluster-management/configure-ui"
+    - title: "Configuring the Store"
+      url: "/cluster-management/configure-store"
+    - title: "Running Locally"
+      url: "/cluster-management/running-locally"
+    - title: "Examples"
+      subcategories:
+        - title: "Kubernetes"
+          url: "/cluster-management/kubernetes"
 - title: "About"
   subcategories:
     - title: "What is Screwdriver?"

diff --git a/docs/user-guide/configuration/annotations.md b/docs/user-guide/configuration/annotations.md
@@ -0,0 +1,33 @@
+---
+layout: main
+title: Annotations
+category: User Guide
+menu: menu
+toc:
+    - title: Annotations
+      url: "#annotations"
+---
+# Annotations
+Annotations is a freeform key/value store, often used to configure build execution settings. Annotations may be used as a sandbox for [YAML anchors and aliases](http://blog.daemonl.com/2016/02/yaml.html).
+
+### Example
+```
+shared:
+    template: example/mytemplate@stable
+    annotations:
+        foo: &bar               # Making an anchor for this configuration
+            image: node:8
+
+jobs:
+    main: *bar                  # Referencing the annotation anchor to use that config for main job
+                                # This will cause the main job to use a node:8 image
+```
+
+## Supported Annotations
+Some Annotations are used to modify the properties of the build environment. The following annotations are supported by plugins maintained by Screwdriver.cd. Ask your cluster admin which annotations are supported in your Screwdriver cluster.
+
+| Annotation | Values | Description |
+|------------|--------|-------------|
+| beta.screwdriver.cd/executor | Ask your cluster admin | This will determine what compute system is used to run the build. For example, set the build to run in a VM, a kubernetes pod, a docker container, or a Jenkins agent. |
+| beta.screwdriver.cd/cpu | `LOW` / `HIGH` | When using a `k8s-vm` executor, this will allow the user to choose between 2 CPU resources (`LOW`) and 6 CPU resources (`HIGH`). Default is `LOW`. | 
+| beta.screwdriver.cd/memory | `LOW` / `HIGH` | When using a `k8s-vm` executor, this will allow the user to choose between 2 GB RAM (`LOW`) and 12 GB RAM (`HIGH`). Default is `LOW`. |
diff --git a/docs/user-guide/configuration/environment.md b/docs/user-guide/configuration/environment.md
@@ -0,0 +1,25 @@
+---
+layout: main
+title: Environment
+category: User Guide
+menu: menu
+toc:
+    - title: Environment
+      url: "#environment"
+---
+# Environment
+A set of key/value pairs for environment variables that need to available in a build. If an environment variable is set in both shared and a specific job, the value from the job configuration will be used.
+
+### Example
+```
+shared:
+    template: example/mytemplate@stable
+    environment:
+        FOO: bar
+        MYVAR: hello        # This will set MYVAR=hello in all builds
+jobs:
+    main:
+        environment:
+            FOO: baz        # This will set FOO=baz in the build
+    main2: {}               # This will set FOO=bar in the build
+```
diff --git a/docs/user-guide/configuration/jobconfiguration.md b/docs/user-guide/configuration/jobconfiguration.md
@@ -0,0 +1,99 @@
+---
+layout: main
+title: Job Configuration
+category: User Guide
+menu: menu
+toc:
+    - title: Job Configuration
+      url: "#job-configuration"
+    - title: Image
+      url: "#image"
+    - title: Steps
+      url: "#steps"
+    - title: Shared Configuration
+      url: "#shared"
+---
+# Job configuration
+Jobs are how you define what happens in every build. Every job configuration must consist of an `image` and a list of `steps`, or a `template`.
+
+#### Example
+```
+jobs:
+    main:
+        image: node:6
+        steps:
+            - init: npm install
+            - test: npm test
+    main2: 
+        template: example/mytemplate@stable
+```
+
+## Image
+The `image` configuration refers to a docker image, e.g. an container from (hub.docker.com)[https://hub.docker.com]. You can specify an image from a custom registry by specifying the full url to that image.
+
+#### Example
+```
+jobs:
+    main:
+        image: my-custom-registry.example.com/myorg/myimage:label
+        steps:
+            - step1: echo hello
+```
+
+## Steps
+Steps are the list of instructions you want to execute in your build. These should be defined as:
+`step_name: step_command`. Steps will be executed in the order they are defined.
+
+#### Example
+```
+jobs:
+    main:
+        image: node:8
+        steps:
+            - step_name: step_command --arg1 --arg2 foo
+            - greet: echo Hello
+```
+
+
+# Shared
+The `shared` configuration is a special job configuration section that is applied to all jobs. Configuration that is specified in a job configuration will override the same configuration in `shared`.
+
+#### Example
+The following example defines a shared configuration for `image` and `steps`, which is used by the main and main2 jobs.
+```
+shared:
+    image: node:8
+    steps:
+        - init: npm install
+        - test: npm test
+
+jobs:
+    main:
+        image: node:6
+    main2:
+        steps:
+            - greet: echo hello
+```
+
+The above example would be equivalent to:
+```
+jobs:
+    main:
+        image: node:6
+        steps:
+            - init: npm install
+            - test: npm test
+    main2:
+        image: node:8
+        steps:
+            - greet: echo hello
+
+```
+
+### See also:
+* [Annotations](/user-guide/configuration/annotations) - Freeform key/value store, often used to configure build execution settings
+* [Environment](/user-guide/configuration/environment) - Define environment variables for jobs
+* [Secrets](/user-guide/configuration/secrets) - Securely pass secrets as environment variables into the build
+* [Settings](/user-guide/configuration/settings) - Define configuration of build plugins
+* [Templates](/user-guide/templates) - Common, community supported job configurations
+* [Workflow](/user-guide/configuration/workflow) - Define the path of the pipeline
diff --git a/docs/user-guide/configuration/settings.md b/docs/user-guide/configuration/settings.md
@@ -0,0 +1,32 @@
+---
+layout: main
+title: Settings
+category: User Guide
+menu: menu
+toc:
+    - title: Settings
+      url: "#settings"
+    - title: Email
+      url: "#email"
+---
+# Settings
+Configurable settings for any additional build plugins added to Screwdriver.cd.
+
+## Email
+To enable emails to be sent as a result of build events, use the email setting.
+You can configure a list of one or more email addresses to contact. You can also configure when to send an email, e.g. when the build status is `SUCCESS` and/or `FAILURE`.
+
+### Example
+```
+shared:
+    template: example/mytemplate@stable
+
+jobs:
+    main:
+        settings:
+            email:
+                addresses: [[email protected], [email protected]]
+                statuses: [SUCCESS, FAILURE]
+```
+
+The settings email configuration can be set in `shared`, to apply to all jobs, or in an individual job. A job `email` configuration will completely override the `shared` setting.