From 2a577938f3e647108c91acf78a3c88d66d84d47c Mon Sep 17 00:00:00 2001 From: Pavel Nosovets <56305887+palson-cf@users.noreply.github.com> Date: Tue, 9 Jun 2020 08:50:26 +0300 Subject: [PATCH] Add Documentation (#3) * Added docs * Add original_yaml_string and runtime_environment to pipeline * Minor fix in docs * Add pipeline revision * Fix docs --- docs/index.md | 69 ++++++++++++++++++ docs/resources/pipeline.md | 140 +++++++++++++++++++++++++++++++++++++ docs/resources/project.md | 37 ++++++++++ examples/README.md | 115 +++++++++++++++--------------- 4 files changed, 306 insertions(+), 55 deletions(-) create mode 100644 docs/index.md create mode 100644 docs/resources/pipeline.md create mode 100644 docs/resources/project.md diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..e2aa6c2 --- /dev/null +++ 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. \ No newline at end of file diff --git a/docs/resources/pipeline.md b/docs/resources/pipeline.md new file mode 100644 index 0000000..aef9b09 --- /dev/null +++ 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 new file mode 100644 index 0000000..781bcb7 --- /dev/null +++ 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 index 46bedac..db6a17a 100644 --- 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 = "" - name = "staging" - namespace = "staging" - cluster = "abcinc-staging" -} -``` + spec { + concurrency = 1 + priority = 5 -## User -```yaml -resource "codefresh_user" "john_doe" { - email = "jdoe@abcinc.com" + 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" + } + } } ```