From 4a658272d7d44b1d2eb25fed1538cbec8546e060 Mon Sep 17 00:00:00 2001 From: David Cheung Date: Fri, 6 Aug 2021 17:31:47 -0400 Subject: [PATCH 1/4] doc-site: core-concept and life-cycle explanation --- doc-site/docs/about/overview.md | 6 ++--- doc-site/docs/concepts/core-concepts.md | 12 ++++++++++ doc-site/docs/concepts/module-life-cycle.md | 5 ---- doc-site/docs/concepts/project-life-cycle.md | 24 ++++++++++++++++++++ doc-site/sidebars.js | 8 +++---- 5 files changed, 43 insertions(+), 12 deletions(-) delete mode 100644 doc-site/docs/concepts/module-life-cycle.md diff --git a/doc-site/docs/about/overview.md b/doc-site/docs/about/overview.md index 76f8b9d8..33a460a0 100644 --- a/doc-site/docs/about/overview.md +++ b/doc-site/docs/about/overview.md @@ -71,9 +71,9 @@ Security: Properly configured access-control to resources/security groups, using [technology-choices]: ./technology-choices [learning-resources]: ../reference/learning-resources [docs-infra]: /docs/modules/aws-eks-stack/ -[docs-backend-go]: /docs/modules/backend-go/ -[docs-backend-nodejs]: /docs/modules/backend-nodejs/ -[docs-frontend-react]: /docs/modules/frontend-react/ +[docs-backend-go]: https://getzero.dev/docs/modules/backend-go/ +[docs-backend-nodejs]: https://getzero.dev/docs/modules/backend-nodejs/ +[docs-frontend-react]: https://getzero.dev/docs/modules/frontend-react/ diff --git a/doc-site/docs/concepts/core-concepts.md b/doc-site/docs/concepts/core-concepts.md index 1cf25f00..6c3264aa 100644 --- a/doc-site/docs/concepts/core-concepts.md +++ b/doc-site/docs/concepts/core-concepts.md @@ -3,3 +3,15 @@ title: Core Concepts sidebar_label: Core Concepts sidebar_position: 1 --- + +## Project +A project defines a set of **modules** along with the module's parameters input by the user, and these information are stored in `zero-project.yml`. Which you can generated using `zero init`. + +The Project manifest(`zero-project.yml`) is the source of truth for the commands (`create` and `apply`). It determines where to fetch the modules, the execution order of modules, whether it will push your project to version control, and other project information. You can provision both staging and production environment using the same manifest to ensure the environments are reproducible and controlled. + +## Module +A module is useful bundle of code and/or resources that can be templated out with the Project Manifest, then executes a provision flow, this could be templating out terraform infrastructure as code then provisioning the resources, or creating a backend application and deploying it. + +A module is defined by it's **Module manifest**(`zero-module.yml`) in it's root folder, it contains all the parameters it requires, and declares it's requirements and execution. + +Modules can declare it's dependencies, for example a backend that will be deployed can declare its dependency on the infrastructure repository, so that it will execute the infrastructure module's flow before the backend itself. diff --git a/doc-site/docs/concepts/module-life-cycle.md b/doc-site/docs/concepts/module-life-cycle.md deleted file mode 100644 index ce0f6503..00000000 --- a/doc-site/docs/concepts/module-life-cycle.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: Module Life Cycle -sidebar_label: Module Life Cycle -sidebar_position: 3 ---- diff --git a/doc-site/docs/concepts/project-life-cycle.md b/doc-site/docs/concepts/project-life-cycle.md index c632cc36..ba320328 100644 --- a/doc-site/docs/concepts/project-life-cycle.md +++ b/doc-site/docs/concepts/project-life-cycle.md @@ -3,3 +3,27 @@ title: Project Life Cycle sidebar_label: Project Life Cycle sidebar_position: 2 --- + +## zero init +The goal of the `init` step is to create the project manifest (`zero-project.yml`). + +`zero init` will fetch each **module(s)** defined in the `zero-project.yml`, and prompt user through a series of questions to fill in parameters required by the module definition. At this phase module definition will be parsed and provide defaults and options to guide users to fill in their project details. + +:::note +It's recommended to review the `zero-project.yml` and make adjustments as needed before running `zero create` and `zero apply` +::: + +## zero create +`zero create` runs on the same folder as `zero-project.yml`, it will scaffold and template out each module `templates/` folder as the basis of your repository, then push them to your version control repository(github). + +During scaffolding Zero will also determine based on project's parameters to optionally scaffold conditioned files, for example it will not scaffold the authentication examples if you opted out from this step. + +## zero apply +`zero apply` setups up the final steps of your provisioning, it by default runs the `make` command and modules can specify to change this behavior. Zero expects a two step process of which it will run `check` then `make` to setup the module. + +### Check +`check` is ran for all the modules in your project before attempting to do the `run` step, so if one dependent's `check` fails it will not start the actual provisioning for any of the modules, this is useful to check for missing binaries or API token permissions. + +### Apply +The run step is by default `make` and can be overriden in the module definition. Run should be the one time setup procedures that allow the module to function. +For example in the infrastructure repository this would be **running terraform**, and for the backend repository this could be **setting up the webhooks for your circleCI to connect to your github**. diff --git a/doc-site/sidebars.js b/doc-site/sidebars.js index 74da488c..f495ac2e 100644 --- a/doc-site/sidebars.js +++ b/doc-site/sidebars.js @@ -12,14 +12,14 @@ module.exports = { type: 'autogenerated', dirName: 'getting-started', }], - "Reference": [{ - type: 'autogenerated', - dirName: 'reference', - }], "Concepts": [{ type: 'autogenerated', dirName: 'concepts', }], + "Reference": [{ + type: 'autogenerated', + dirName: 'reference', + }], }, sidebarsNavModules(config), ] From b71cd38fee66c944c1e19a670bc45ffbde25a8a8 Mon Sep 17 00:00:00 2001 From: David Cheung Date: Mon, 9 Aug 2021 11:18:10 -0400 Subject: [PATCH 2/4] Update doc-site/docs/concepts/project-life-cycle.md Co-authored-by: Bill Monkman --- doc-site/docs/concepts/project-life-cycle.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/doc-site/docs/concepts/project-life-cycle.md b/doc-site/docs/concepts/project-life-cycle.md index ba320328..f5d048e8 100644 --- a/doc-site/docs/concepts/project-life-cycle.md +++ b/doc-site/docs/concepts/project-life-cycle.md @@ -7,23 +7,23 @@ sidebar_position: 2 ## zero init The goal of the `init` step is to create the project manifest (`zero-project.yml`). -`zero init` will fetch each **module(s)** defined in the `zero-project.yml`, and prompt user through a series of questions to fill in parameters required by the module definition. At this phase module definition will be parsed and provide defaults and options to guide users to fill in their project details. +`zero init` will fetch each **module** defined in `zero-project.yml` from their remote repository, and prompt the user through a series of questions to fill in parameters required by each module. In this phase, the module definition will be parsed and provide defaults, options, and extra context to guide users through filling in their project details. :::note -It's recommended to review the `zero-project.yml` and make adjustments as needed before running `zero create` and `zero apply` +It's recommended to review the `zero-project.yml` and make adjustments as needed before running `zero create` and `zero apply`. ::: ## zero create -`zero create` runs on the same folder as `zero-project.yml`, it will scaffold and template out each module `templates/` folder as the basis of your repository, then push them to your version control repository(github). +`zero create` is run in the same folder as `zero-project.yml`. It will template out each module specified in the project manifest as the basis of your repositories, then push them to your version control repository (Github). -During scaffolding Zero will also determine based on project's parameters to optionally scaffold conditioned files, for example it will not scaffold the authentication examples if you opted out from this step. +During the `create` step, Zero will also conditionally include or exclude certain sets of files, as defined by each module. For example, it will not scaffold the authentication examples if you opted not to use this feature. ## zero apply -`zero apply` setups up the final steps of your provisioning, it by default runs the `make` command and modules can specify to change this behavior. Zero expects a two step process of which it will run `check` then `make` to setup the module. +`zero apply` is the provisioning step that starts to make real-world changes. By default, it runs a command defined by the module to check for any dependencies, and then runs a command to actually apply any changes. ### Check -`check` is ran for all the modules in your project before attempting to do the `run` step, so if one dependent's `check` fails it will not start the actual provisioning for any of the modules, this is useful to check for missing binaries or API token permissions. +`check` is run for all the modules in your project before attempting to do the `run` step, so if a dependent's `check` fails it will not start the actual provisioning for any of the modules. This is useful to check for missing binaries or API token permissions before starting to apply any changes. ### Apply -The run step is by default `make` and can be overriden in the module definition. Run should be the one time setup procedures that allow the module to function. -For example in the infrastructure repository this would be **running terraform**, and for the backend repository this could be **setting up the webhooks for your circleCI to connect to your github**. +By default, the run step is to execute `make` in the root of the module, but that can be overridden in the module definition. Run should be the one-time setup commands that allow the module to function. +For example, in the infrastructure repository, this would be to **run terraform**, and for the backend repository, this could be to **make API calls to CircleCI to set up your build pipeline**. From 7654a52e3ee7ba6cf564c2c9310c4d801f947811 Mon Sep 17 00:00:00 2001 From: David Cheung Date: Mon, 9 Aug 2021 11:18:16 -0400 Subject: [PATCH 3/4] Update doc-site/docs/concepts/core-concepts.md Co-authored-by: Bill Monkman --- doc-site/docs/concepts/core-concepts.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc-site/docs/concepts/core-concepts.md b/doc-site/docs/concepts/core-concepts.md index 6c3264aa..f324e7e7 100644 --- a/doc-site/docs/concepts/core-concepts.md +++ b/doc-site/docs/concepts/core-concepts.md @@ -5,13 +5,13 @@ sidebar_position: 1 --- ## Project -A project defines a set of **modules** along with the module's parameters input by the user, and these information are stored in `zero-project.yml`. Which you can generated using `zero init`. +A project defines a set of **modules** to use, along with a full set of config parameters for each module which were entered by the user during the `zero init` step. These config options are stored in `zero-project.yml`. -The Project manifest(`zero-project.yml`) is the source of truth for the commands (`create` and `apply`). It determines where to fetch the modules, the execution order of modules, whether it will push your project to version control, and other project information. You can provision both staging and production environment using the same manifest to ensure the environments are reproducible and controlled. +The project manifest (`zero-project.yml`) is the source of truth for the commands `create` and `apply`. It determines from where to fetch the modules, the execution order of modules, whether it will push your project to version control, module configuration, and other project information. Both staging and production environments are provisioned using the same manifest to ensure the environments are reproducible and controlled. ## Module -A module is useful bundle of code and/or resources that can be templated out with the Project Manifest, then executes a provision flow, this could be templating out terraform infrastructure as code then provisioning the resources, or creating a backend application and deploying it. +A module is a useful bundle of code and/or resources that can be templated out during the `create` step, then executes a provisioning flow. This could be templating out terraform infrastructure as code then provisioning the resources, or creating a backend application, making API calls to set up a build pipeline, and then deploying it. -A module is defined by it's **Module manifest**(`zero-module.yml`) in it's root folder, it contains all the parameters it requires, and declares it's requirements and execution. +A module is defined by the **module manifest** (`zero-module.yml`) in its root folder. It contains all the parameters required to render the templated files (during `zero create`) and execute any provisioning steps, and declares it's requirements and the commands to execute during provisioning (`zero apply`). -Modules can declare it's dependencies, for example a backend that will be deployed can declare its dependency on the infrastructure repository, so that it will execute the infrastructure module's flow before the backend itself. +Modules can declare their dependencies, for example a backend that will be deployed can declare its dependency on the infrastructure repository so that the infrastructure will already exist by the time we want to deploy to it. From fa96d71f2cf6456216fbc32968538c908d20e167 Mon Sep 17 00:00:00 2001 From: David Cheung Date: Mon, 9 Aug 2021 11:20:00 -0400 Subject: [PATCH 4/4] fixup! Update doc-site/docs/concepts/core-concepts.md --- doc-site/docs/about/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc-site/docs/about/overview.md b/doc-site/docs/about/overview.md index 33a460a0..a6b7e806 100644 --- a/doc-site/docs/about/overview.md +++ b/doc-site/docs/about/overview.md @@ -70,7 +70,7 @@ Security: Properly configured access-control to resources/security groups, using [real-world-usage]: ./real-world-usage [technology-choices]: ./technology-choices [learning-resources]: ../reference/learning-resources -[docs-infra]: /docs/modules/aws-eks-stack/ +[docs-infra]: https://getzero.dev/docs/modules/aws-eks-stack/ [docs-backend-go]: https://getzero.dev/docs/modules/backend-go/ [docs-backend-nodejs]: https://getzero.dev/docs/modules/backend-nodejs/ [docs-frontend-react]: https://getzero.dev/docs/modules/frontend-react/