Add Documentation (#3)

* Added docs * Add original_yaml_string and runtime_environment to pipeline * Minor fix in docs * Add pipeline revision * Fix docs
codefresh-io · Jun 9, 2020 · 2a57793 · 2a57793
1 parent b924e06
commit 2a57793
Show file tree

Hide file tree

Showing 4 changed files with 306 additions and 55 deletions.
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,69 @@
+---
+layout: "codefresh"
+page_title: "Provider: Codefresh"
+sidebar_current: "docs-codefresh-index"
+description: |-
+  The Codefresh provider is used to manage Codefresh resources.
+---
+
+# Codefresh Provider
+
+The Codefresh Provider can be used to configure [Codefresh](https://codefresh.io/) resources - pipelines, projects, accounts, etc using the [Codefresh API](https://codefresh.io/docs/docs/integrations/codefresh-api/).
+
+## Authenticating to Codefresh
+
+The Codefresh API requires the [authentication key](https://codefresh.io/docs/docs/integrations/codefresh-api/#authentication-instructions) to authenticate.
+The key can be passed either as provider's attribute or as environment variable - `CODEFRESH_API_KEY`.
+
+## Example Usage
+
+```hcl
+provider "codefresh" {
+    token = "xxxxxxxxx.xxxxxxxxxx"
+}
+
+resource "codefresh_project" "project" {
+    name = "myproject"
+
+    tags = [
+      "production",
+      "docker",
+    ]
+
+    variables = {
+      myProjectVar = "value"
+   }
+}
+
+resource "codefresh_pipeline" "pipeline" {
+    lifecycle {
+        ignore_changes = [
+            revision
+        ]
+    }
+
+    name  = "${codefresh_project.project.name}/mypipeline"
+
+    spec {
+
+        spec_template {
+            repo        = "my-github-account/my-repository"
+            path        = "./codefresh.yml"
+            revision    = "master"
+            context     = "github"
+        }
+
+        variables = {
+            goVersion = "1.13"
+            release = "true"
+        }
+    }
+}
+```
+
+## Argument Reference
+
+The following arguments are supported:
+
+- `token` - (Optional) The client API token. This can also be sourced from the `CODEFRESH_API_KEY` environment variable.
+- `api_url` -(Optional) Default value - https://g.codefresh.io/api.
diff --git a/docs/resources/pipeline.md b/docs/resources/pipeline.md
@@ -0,0 +1,140 @@
+# Pipeline Resource
+
+The central component of the Codefresh Platform. Pipelines are workflows that contain individual steps. Each step is responsible for a specific action in the process.
+See the [documentation](https://codefresh.io/docs/docs/configure-ci-cd-pipeline/introduction-to-codefresh-pipelines/) for the details.
+
+## Example Usage
+
+```hcl
+resource "codefresh_project" "test" {
+  name = "myproject"
+}
+
+resource "codefresh_pipeline" "test" {
+
+  lifecycle {
+    ignore_changes = [
+      revision
+    ]
+  }
+
+  name    = "${codefresh_project.test.name}/react-sample-app"
+
+  tags = [
+    "production",
+    "docker",
+  ]
+
+  spec {
+    concurrency = 1
+    priority    = 5
+
+    spec_template {
+      repo        = "codefresh-contrib/react-sample-app"
+      path        = "./codefresh.yml"
+      revision    = "master"
+      context     = "git"
+    }
+
+    trigger {
+      branch_regex  = "/.*/gi"
+      context       = "git"
+      description   = "Trigger for commits"
+      disabled      = false
+      events        = [
+        "push.heads"
+      ]
+      modified_files_glob = ""
+      name                = "commits"
+      provider            = "github"
+      repo                = "codefresh-contrib/react-sample-app"
+      type                = "git"
+    }
+
+    trigger {
+      branch_regex  = "/.*/gi"
+      context       = "git"
+      description   = "Trigger for tags"
+      disabled      = false
+      events        = [
+        "push.tags"
+      ]
+      modified_files_glob = ""
+      name                = "tags"
+      provider            = "github"
+      repo                = "codefresh-contrib/react-sample-app"
+      type                = "git"
+    }
+
+    variables = {
+      MY_PIP_VAR      = "value"
+      ANOTHER_PIP_VAR = "another_value"
+    }
+  }
+}
+```
+
+## Argument Reference
+
+- `name` - (Required) The display name for the pipeline.
+- `revision` - (Optional) The pipeline's revision. Should be added to the **lifecycle/ignore_changes** or incremented mannually each update.
+- `tags` - (Optional) A list of tags to mark a project for easy management and access control.
+- `spec` - (Required) A collection of `spec` blocks as documented below.
+- `original_yaml_string` - (Optional) A string with original yaml pipeline.
+  - `original_yaml_string = "version: \"1.0\"\nsteps:\n  test:\n    image: alpine:latest\n    commands:\n      - echo \"ACC tests\""`
+  - or `original_yaml_string = file("/path/to/my/codefresh.yml")`
+
+---
+
+`spec` supports the following:
+
+- `concurrency` - (Optional) The maximum amount of concurrent builds.
+- `priority` - (optional) Helps to organize the order of builds execution in case of reaching the concurrency limit.
+- `variables` - (Optional) Pipeline variables.
+- `trigger` - (Optional) A collection of `trigger` blocks as documented below. Triggers [documentation](https://codefresh.io/docs/docs/configure-ci-cd-pipeline/triggers/git-triggers/).
+- `spec_template` - (Optional) A collection of `spec_template` blocks as documented below.
+- `runtime_environment` - (Optional) A collection of `runtime_environment` blocks as documented below.
+
+---
+
+`spec_template` supports the following:
+
+- `location` - (Optional) Default value - **git**.
+- `repo` - (Required) The GitHub `account/repo_name`.
+- `path` - (Required) The relative path to the Codefresh pipeline file.
+- `revison` - (Required) The git revision.
+- `context` - (Optional) The Codefresh Git [context](https://codefresh.io/docs/docs/integrations/git-providers/).
+
+---
+
+`trigger` supports the following:
+
+- `name` - (Optional) The display name for the pipeline.
+- `description` - (Optional) The trigger description.
+- `type` - (Optional) The trigger type. Default value - **git**.
+- `repo` - (Optional) The GitHub `account/repo_name`.
+- `branch_regex` - (Optional) A regular expression and will only trigger for branches that match this naming pattern.
+- `modified_files_glob` - (Optional) Allows to constrain the build and trigger it only if the modified files from the commit match this glob expression.
+- `events` - (Optional) A list of GitHub events for which a Pipeline is triggered. Default value - **push.heads**.
+- `provider` - (Optional) Default value - **github**.
+- `context` - (Optional) Codefresh Git context.
+- `variables` - (Optional) Trigger variables.
+
+---
+
+`runtime_environment` supports the following:
+
+- `name` - (Required) A name of runtime.
+- `cpu` - (Optional) A required amount of CPU.
+- `memory` - (Optional) A required amount of memory.
+- `dind_storage` - (Optional) A pipeline shared storage.
+
+## Attributes Reference
+
+- `id` - The Pipeline ID.
+
+## Import
+
+```sh
+terraform import codefresh_pipeline.test xxxxxxxxxxxxxxxxxxx
+```
diff --git a/docs/resources/project.md b/docs/resources/project.md
@@ -0,0 +1,37 @@
+# Project Resource
+
+The top-level concept in Codefresh. You can create projects to group pipelines that are related. In most cases a single project will be a single application (that itself contains many micro-services). You are free to use projects as you see fit. For example, you could create a project for a specific Kubernetes cluster or a specific team/department.
+More about pipeline concepts see in the [official documentation](https://codefresh.io/docs/docs/configure-ci-cd-pipeline/pipelines/#pipeline-concepts).
+
+## Example Usage
+
+```hcl
+resource "codefresh_project" "test" {
+    name = "myproject"
+
+    tags = [
+      "production",
+      "docker",
+    ]
+
+    variables = {
+      go_version = "1.13"
+   }
+}
+```
+
+## Argument Reference
+
+- `name` (Required) The display name for the project.
+- `tags` (Optional) A list of tags to mark a project for easy management and access control.
+- `variables` (Optional) project variables.
+
+## Attributes Reference
+
+- `id` - The Project ID
+
+## Import
+
+```sh
+terraform import codefresh_project.test xxxxxxxxxxxxxxxxxxx
+```
diff --git a/examples/README.md b/examples/README.md
@@ -1,76 +1,81 @@
 # Example
 
-```yaml
-resource "codefresh_project" "test" {
-    name = "test"
-}
-```
+In the example the Codefresh Provider is configured to authenticate with Codefresh API, and new project and pipeline are created.
+Pipeline includes link to the original __codefresh.yml__ spec and two git triggres.
 
 Run `terraform plan` or `terraform apply` as usual. Note this will modify the actual Codefresh configuration.
 
-# Syntax Examples
-
-## Project
-
-```yaml
-resource "codefresh_project" "docker" {
-  name = "docker"
+```hcl
+provider "codefresh" {
+  api_url = "https://my.onpremcodefresh.com/api"
+  token = "xxxxxxxxxxxxxxx.xxxxxxxxxxxxxx"
 }
-```
-
-## Pipeline
 
-```yaml
-resource "codefresh_pipeline" "docker_monorepo" {
-  name    = "docker/docker-monorepo"
-  project = "docker"
-
-  spec = {
-    repo        = "abcinc/monorepo"
-    path        = "./codefresh/docker/docker-monorepo.yaml"
-    revision    = "master"
-    concurrency = 1
-    priority    = 5
-  }
+resource "codefresh_project" "test" {
+  name = "myproject"
 
   tags = [
     "docker",
   ]
 
   variables {
-    TAG = "master"
+    go_version = "1.13"
   }
 }
-```
-
-## Cron Trigger
-
-```yaml
-resource "codefresh_cron_event" "docker_monorepo_cron" {
-  expression = "40 0 * * *"
-  message    = "build monorepo docker"
-}
 
-resource "codefresh_cron_trigger" "docker_monorepo_cron" {
-  pipeline = "${codefresh_pipeline.docker_monorepo.id}"
-  event    = "${codefresh_cron_event.docker_monorepo_cron.id}"
-}
-```
+resource "codefresh_pipeline" "test" {
+  name    = "${codefresh_project.test.name}/react-sample-app"
 
-## Environment
+  tags = [
+    "production",
+    "docker",
+  ]
 
-```yaml
-resource "codefresh_environment" "staging" {
-  account_id = "<redacted>"
-  name       = "staging"
-  namespace  = "staging"
-  cluster    = "abcinc-staging"
-}
-```
+  spec {
+    concurrency = 1
+    priority    = 5
 
-## User
-```yaml
-resource "codefresh_user" "john_doe" {
-  email = "[email protected]"
+    spec_template {
+      repo        = "codefresh-contrib/react-sample-app"
+      path        = "./codefresh.yml"
+      revision    = "master"
+      context     = "git"
+    }
+
+    trigger {
+      branch_regex  = "/.*/gi"
+      context       = "git"
+      description   = "Trigger for commits"
+      disabled      = false
+      events        = [
+        "push.heads"
+      ]
+      modified_files_glob = ""
+      name                = "commits"
+      provider            = "github"
+      repo                = "codefresh-contrib/react-sample-app"
+      type                = "git"
+    }
+
+    trigger {
+      branch_regex  = "/.*/gi"
+      context       = "git"
+      description   = "Trigger for tags"
+      disabled      = false
+      events        = [
+        "push.tags"
+      ]
+      modified_files_glob = ""
+      name                = "tags"
+      provider            = "github"
+      repo                = "codefresh-contrib/react-sample-app"
+      type                = "git"
+    }
+
+    variables = {
+      MY_PIP_VAR      = "value"
+      ANOTHER_PIP_VAR = "another_value"
+    }
+  }
 }
 ```