Update documentation

documentation/README.md

@@ -8,28 +8,28 @@ In this series of articles, we describe the development, code architecture, the
 
 [Introduction to service composition inside landing zones](./code_architecture/service_composition.md)
 
-[Create your first landing zone in 10 easy steps](./code_architecture/how_to_code_a_landingzone.md)
+[Create your first landing zone in 10 easy steps - part 1](./code_architecture/how_to_code_a_landingzone.md)
 
 [Unit and integration testing modules](./test/unit_test.md)
 
-Soon - [CAF landing zones hierarchy model]()
+[CAF landing zones hierarchy model](./code_architecture/hierarchy.md)
+
+[CAF module development conventions](./code_architecture/module_conventions.md)
+
+Soon - [Create your first landing zone in 10 easy steps - part 2]()
 
 Soon - [Developing landing zones, modules, blueprints]()
 
 ## Delivery of landing zones
 
-Soon - [Introduction to delivery of landing zones]()
+[Introduction to delivery of landing zones](./delivery/delivery_landingzones.md)
 
 Soon - [Deployment guide for Azure CAF landing zones]()
 
-Soon - [DevOps for landing zones]()
-
 ## Operating an environment with landing zones
 
 Soon - [Deep-dive on launchpad]()
 
-Soon - [IaC vs regular code, the similarities and the differences]()
-
 Soon - [Introduction to GitOps for landing zones]()
 
 Soon - [The people, procedures and policies]()

documentation/code_architecture/hierarchy.md

@@ -0,0 +1,53 @@
+# Understanding landing zones hierarchy
+
+Isolation of different Terraform state files is an important factor of reliability in an enterprise deployment.
+
+## Layered approach
+
+Separating the Terraform states enables:
+
+- **Control blast radius**: if one configuration is deficient, its only impact the landing zone in scope and does not compromise the whole environment.
+- **Enforce standard configuration**: by using different Terraform state, you can compose a complex environment very fast.
+- **Enable autonomy**: different landing zones can enable innovation and features at different pace from each other.
+- **Least privilege**: Each level is protected by its own identity to prevent unwanted modifications.
+
+Cloud Adoption Framework for Azure proposes a hierarchy of landing zones based on 5 levels as described below:
+
+![Hierarchy](../../_pictures/code_architecture/hierarchy.png)
+
+### Level 0: Transition from manual to automation
+
+Create the subscriptions (for levels 0 to level 4), creates the Terraform state repository for the different environments (sandpit, production, dev), created the privileged access workstation, and service principals.
+Level 0 also enables the connection to the Azure DevOps environment as well as the creation of the DevOps private agents and the needed Azure AD groups for collaboration between the developers of the environment.
+
+### Level 1: Core security, Governance and Accounting
+
+Level 1 is responsible for RBAC enforcement on the subscriptions, subscription behavior configuration using Azure Management groups and Azure Policies ensures deployment of preventive and reactive controls.
+This level is also in charge of deploying the fundamental configuration for Azure Monitor and Log analytics, shared security services, including Azure Event Hub namespace for integration with third parties SIEM solutions.
+
+### Level 2: Shared services
+
+Shared services include each environments the core networking components (using hub and spoke or any other network topology). Level 2 also includes services like Azure Site Recovery Vault for Backup and Disaster Recovery, Azure monitor settings for the monitoring of the environment alongside with Azure Automation for patch management of the resources.
+Other resources could be image management for virtual machines in the environment.  
+
+### Level 3: Application infrastructure
+
+This layer is responsible for enforcing the application environment overall configuration for instance the Azure AppService environment, the Azure Kubernetes Services Cluster, the API Management services and all its dependency to deliver a service: deploying the Azure Application Gateway, Web Application Firewall.
+
+### Level 4: Application layer
+
+This level contains the application configuration and links to the source repository and frameworks. It describes which framework is used (for instance Springboot microservices, dotnet core, etc.) and described the configuration of the application (how many instances, how to link to the database, etc.).
+
+## Operate with landing zones hierarchy
+
+A deployment will typically contain little "level 0" landing zones, a few "level 1" and "2", couple of "level 3" and as many "level 4" as applications will exist in an environment.
+
+It is important to keep in mind that each landing zone will be enforced by a pipeline as showing below:
+
+![Hierarchy3](../../_pictures/code_architecture/hierarchy3.png)
+
+For a given "level" in the environment, each Agent VM will be assigned a managed identity that will be used to authenticate and authorize operations on:
+- The target Azure Subscription
+- The Terraform state file: will be Read and Write permissions for the current level, will be Read only permissions for a "lower" level type of landing zone, avoiding alterations on more privileged environments.
+
+In the example above, each pipeline will have its lifecycle management (typically, level 0 and 1 will be initiated at every new subscription creation, while level 4 could be initiated as many times a day you deploy code in your application environment).

documentation/code_architecture/how_to_code_a_landingzone.md

@@ -2,6 +2,12 @@
 
 Coding a landing zone can be a bit intimidating, the white page syndrome can kick-in and you might feel there are too much things to do, so here is my process in creating a landing zone.
 
+**Warning:** This document is about the process of creating the landing zone and is not about Terraform objects and syntax. If you need to get started with Terraform, please refer to the following great documents:
+
+1. Azure Citadel: https://azurecitadel.com/automation/terraform-new/ 
+2. Hashicorp Learning: https://learn.hashicorp.com/terraform?track=azure#azure 
+3. Terraform on Azure documenation: https://docs.microsoft.com/en-us/azure/terraform/ 
+
 ## Step 1. Start with the diagram
 
 First thing to know: what are you trying to achieve?

documentation/code_architecture/module_conventions.md

@@ -0,0 +1,62 @@
+# Conventions for module creation
+
+All modules shall be stored inside a different repository, and must use the convention as described [here](https://www.terraform.io/docs/registry/modules/publish.html).Module must use semantic versioning.
+
+## Structure for the module directory
+
+| Filename| Content  |
+|--|--|
+| main.tf  |  Contains the entry point data, data sources, etc.|
+| module.tf | Contains the main coding for the module logic. |
+| variables.tf | Contains the input variables.|
+| diagnostics.tf | Contains the call to the diagnostics and operations logs features for the resources created in the module. This will be called via the external diagnostics module using the arguments passed in tfvars.   |
+| versions.tf | Terraform modules versions constraints if any. Avoid as possible to put version constraints in module and try to manage that in the blueprints. |
+| output.tf | Output variables to export. |
+| README.MD | Short description of the features the module is achieving, the input and output variables. |
+| CHANGELOG.MD | Version history, new features, improvements and bugs with version number aligned with GitHub releases. |
+
+## Examples
+
+Each module must have at least an example that must be easy to trigger, you shall use the following structure for examples:
+| Filename| Content  |
+|--|--|
+| README.MD | Short description of the example, the input and output variables. |
+| locals.tf | Contains the local variable that are necessary to make the module example working. |
+| outputs.tf | Output variables to export.|
+| test.tf | Contains the logic of the test that will call the module locally and will include dependencies to make the example working |  
+
+In examples, please use *caf_random* or *random* naming convention in order to avoid naming collisions.
+
+## Unit and Integration testing
+
+Each module must implement integration and unit testing using GitHub Actions following the example here:https://github.com/aztfmod/terraform-azurerm-caf-resource-group
+
+Please refer to the unit and integration testing reference article:  https://github.com/Azure/caf-terraform-landingzones/blob/master/documentation/test/unit_test.md
+
+## Module Diagnostics
+
+In order to allow flexibility, the diagnostics settings for each module will be passed as variable with the following object:
+
+```hcl
+diag_object = {
+    log = [
+           ["Category name",  "Diagnostics Enabled(true/false)", "Retention Enabled(true/false)", Retention_period] 
+                ["AzureBackupReport", true, true, 20],
+        ]
+    metric = [
+               #["AllMetrics", 60, True],
+    ]
+}
+```
+
+## Module Output conventions
+
+As a convention we will use the following minimal module outputs:
+
+| Output variable name | Content  |
+|--|--|
+| id  |  returns the object identifiers|
+| name | returns the object name |
+| object | returns the full resource object |
+
+Any other resource specific outputs.

documentation/delivery/delivery_landingzones.md

@@ -1,21 +1,62 @@
-# Delivery mechanisms for landing zones
+# Delivery model for landing zones
 
-Like in any DevOps approach, you need to have:
+Cloud Adoption Framework for Azure landing zones for Terraform are to be delivered mainly by DevOps, this includes providing guidances and toolset for deploying and operating an environment.
 
-- A short feedback loop: on your laptop, you can author new landing zones and test them very fast.
-- A set of CI/test pipelines: You commit your test code and validate syntax/features.
-- A set of production pipelines: enforcing configuration for the production environment.  
+## DevOps components
 
-The toolset is vital here, the more discrepancies you will have between your laptop and the CI/CD pipelines, the more time you will waste troubleshooting business-irrelevant problems (wrong versioning, wrong configuration, etc.)
+For DevOps and innovation to happen, we will have the following components to enforce configuration and applications inside Microsoft Azure:
 
-For that reason, the "rover"  which is part of the fundamental toolset of the Azure Cloud Adoption Framework landing zones, enables that integration. More details on the rover here ()
+- **A inner feedback loop**:
+Meant to provide very quick feedback to developers and DevOps engineers, offers the possibility to develop code, test it fast and iterate at fast pace.
+- **DevOps pipelines enforcing the landing zones**:
+A whole execution environment composed of pipelines executed in a customer environment.
 
-## more on rover
+![PipelinesOverview](../../_pictures/delivery/overview_pipelines.png)
 
-## more on launchpad
+- **Rover** is the DevOps toolchain that enables deployments as described [here](../code_architecture/intro_architecture.md).
 
-## How many landing zones for a production environment
+- **Terraform scripts repositories**:  will be used to store and describe logic of Terraform deployments (the script and core code that will be executed)
 
-In a customer environment, there will be a variation in the number of landing zones.
+- **Terraform configuration repositories**: will be used to store and describe the configuration of the environment and of the applications.
+Different environments like PROD, DEV, UAT, etc. will be implemented using different configuration files inside the configuration repository.
 
-- The
+The Azure pipelines will be using Azure DevOps hosted agents will be authenticated by Azure Active Directory using Managed Identities. In order to control privileges and reduce attack surface, we propose a hierarchy of pipelines that is described [here](../code_architecture/hierarchy.md).
+
+## Repositories topology
+
+During the lifecycle of the landing zones deployment you will find that it is easier to work with mono-repository environment (mixing Terraform and code variable). This is absolutely fine and will mature  over time, as you add more modules, more complex environments and you want to move towards a full cycle of release.
+
+Multiple approaches are valid depending on the size of your organization:
+
+- By environment types:
+
+```bash
+tfvars
+├── uat
+|   uat_landingzone_caf_foundations.tfvars
+|   uat_landingzone_networking.tfvars
+├── prod
+├── sandpit
+├── ...
+```
+
+- By "classic" team structures
+``` bash
+tfvars
+├── networking
+|   uat_landingzone_networking.tfvars
+|   test_landingzone_networking.tfvars
+|   prod_landingzone_networking.tfvars
+├── audit
+├── governance
+├── etc.
+```
+
+## GitOps for Azure landing zones
+
+Changes in the different environments introduced and promoted following GitOps concepts, principles and mechanisms:
+
+- Configuration changes are described in a declarative language (here using Terraform).
+- Operations are promoted from one environment to another via Git operations (Git commit, push, pull request).
+- Changes are promoted only once they have reached quality gates (provided by automation, CI mechanisms and test suites executions) to promote higher quality changes.
+- Changes are promoted only once they also have been validated by service owners in the environment (that can be declared in the DevOps configuration of the platform).