better terraform page

Author: toto04

docs/infrastructure/02-getting-started/basic-knowledge/_category_.yml

@@ -6,11 +6,30 @@ description: "Detailed overview of our Azure-based infrastructure managed via th
 ## What is Terraform?
 
 Terraform is an open-source Infrastructure as Code (IaC) tool developed by
-HashiCorp. It allows you to define, provision, and manage your infrastructure
+HashiCorp. It allows you to define, provision, and manage the infrastructure
 using a declarative configuration language. This means you describe the desired
-state of your infrastructure, and Terraform takes care of creating and updating
+state of the infrastructure, and Terraform takes care of creating and updating
 the resources to match that state.
 
+:::important
+This documentation assumes you already have the Terraform CLI installed on your
+local machine. If you need help setting up Terraform, please refer to the
+[official documentation](https://learn.hashicorp.com/tutorials/terraform/install-cli).
+
+You'll also need to be logged in with the Azure CLI and have the necessary
+permissions to manage the resources in our Azure subscription (more on this
+[here](../setup#azure-cli--kubectl)).
+
+Once you have logged in to the Azure CLI, you need to set the necessary
+environment variables by running this command at the root of the repository:
+
+```sh
+source ./access_key.sh
+```
+
+More about this in the [repository README](https://github.com/PoliNetworkOrg/terraform/?tab=readme-ov-file#notes).
+:::
+
 ### Why We Use Terraform
 
 Our organization leverages Terraform to manage our Azure cloud infrastructure for several important reasons:
@@ -22,28 +41,44 @@ Our organization leverages Terraform to manage our Azure cloud infrastructure fo
 
 ### How Terraform Works
 
+:::warning
+To run terraform commands you need to have the right permissions and credentials.
+If you are not sure about your permissions, please contact the IT department (but
+if you have to ask you probably shouldn't run `apply` yourself anyway).
+
+If you haven't yet set up the Azure CLI please refer to the [setup guide](../setup#azure-cli--kubectl).
+:::
+
 Terraform operates through a simple yet powerful workflow:
 
-1. **Write:** You define your infrastructure in configuration files (typically with a `.tf` extension).
+1. **Write:** You define the infrastructure in configuration files (typically with a `.tf` extension).
 2. **Plan:** Running `terraform plan` generates an execution plan, showing you the changes Terraform will make to achieve the desired state.
-3. **Apply:** Executing `terraform apply` implements the changes, creating or updating your infrastructure accordingly.
+3. **Apply:** Executing `terraform apply` implements the changes, creating or updating the infrastructure accordingly.
+
+:::danger
+Running Terraform commands can modify the cloud infrastructure.
+
+**THIS CAN INCUR COSTS OR CAUSE DOWNTIME AND PERMANENT DATA LOSS IF NOT DONE PROPERLY.**
+
+Always review the execution plan (`terraform plan`) before applying changes.
+:::
 
 ### Terraform Code vs. Terraform State vs. Azure State
 
 - **Terraform Code:**  
   This consists of the configuration files that describe your desired
-  infrastructure. These files are the blueprint for what you want your infrastructure to look like.
+  infrastructure. These files are the blueprint for what you want the infrastructure to look like.
 
 - **Terraform State:**  
-  The state file (commonly named `terraform.tfstate`) records the current state
+  The state file (which we named `state.tfstate`) records the current state
   of the infrastructure as managed by Terraform. This file is critical because
   it maps your configuration to the real-world resources, tracks dependencies,
   and allows Terraform to detect what needs to change during updates. Our state
   file is stored remotely (in an Azure Storage Account) and is locked using
   Azure's integrated leasing mechanism to prevent concurrent modifications.
 
 - **Azure State:**  
-  This is the actual state of resources deployed in your Azure environment.
+  This is the actual state of resources deployed in the Azure environment.
   While Terraform keeps track of these resources via its state file, the real
   configuration and runtime details exist within Azure. The Terraform state acts
   as an intermediary, ensuring that the desired state (from the Terraform code)
@@ -67,37 +102,48 @@ and our setup is tailored to our current needs.
 
 The **polinetworkorg/terraform** repository is our centralized solution for
 provisioning and managing cloud infrastructure on Azure. It follows a modular
-design that breaks down the overall architecture into focused components. Some
-of the primary modules include:
+design that breaks down the overall architecture into focused components. To give
+you a rough idea of what is in there, here are some of the primary modules:
 
 - **aks:** Defines all resources related to our Azure Kubernetes Service (AKS) instance.
 - **mariadb:** Manages the main MariaDB database.
 - **monitoring:** Sets up our monitoring stack using Grafana and Prometheus.
 - **argocd:** Configures our ArgoCD installation for GitOps-driven deployments.
+- **storage:** Handles the Azure Storage Account where the Terraform state is stored.
 
 There are also additional modules in the repository that handle specific
 applications or services, but these are not detailed in this general overview.
 
+:::info
+While the choices made in this implementation reflect our specific requirements
+and constraints, it's worth noting that other approaches exist for managing
+cloud infrastructure with Terraform.
+
+Our modular design, state management strategy,
+and access controls are tailored to our current operational needs and funding
+situation—but they are not set in stone. Please feel free to reach out to the
+IT department if you have any questions or suggestions.
+:::
+
 ### Infrastructure Structure
 
 Our repository is organized to clearly separate concerns and promote reusability.
 While the exact folder structure may vary, a typical layout looks like this:
 
 ```bash
-polinetworkorg/terraform/
-├── modules/
-│   ├── aks/             # Module for Azure Kubernetes Service resources
-│   ├── mariadb/         # Module for the main MariaDB database
-│   ├── monitoring/      # Module for monitoring (Grafana + Prometheus)
-│   ├── argocd/          # Module for ArgoCD installation
-│   └── [other modules]  # Additional modules for specific services
-├── storage/             # Module for Azure Storage Account for state management
-│   └── state.tfstate    # Terraform state file container (in a 'terraform-state' container)
-├── environments/        # Environment-specific configurations (e.g., dev, prod)
-├── main.tf              # Main Terraform configuration file
-├── variables.tf         # Variables definition file
-├── outputs.tf           # Outputs definition file
-└── README.md            # General repository documentation
+📁 polinetworkorg/terraform/
+ ├─ 📁 modules/             # All modules are kept in a dedicated directory
+ │   ├─ 📁 aks/             # Module for Azure Kubernetes Service resources
+ │   ├─ 📁 mariadb/         # Module for the main MariaDB database
+ │   ├─ 📁 monitoring/      # Module for monitoring (Grafana + Prometheus)
+ │   ├─ 📁 argocd/          # Module for ArgoCD installation
+ │   ├─ 📁 storage/         # Module for Azure Storage Account where the state.tfstate is kept
+ │   └─ [other modules]     # Additional modules for specific services
+ ├── main.tf                # Main Terraform configuration file
+ ├── variables.tf           # Variables definition file
+ ├── outputs.tf             # Outputs definition file
+ ├── README.md              # General repository documentation
+ └── [other files]          
 ```
 
 ### State Management
@@ -124,14 +170,15 @@ which provides us with a budget of **€2000 per year**. This support helps offs
 our cloud costs and underpins our commitment to maintaining a robust and scalable
 infrastructure.
 
-### Acknowledgements and Alternative Approaches
+:::info
+This is one of the core reasons we are structured as a nonprofit organization, and why
+we use Azure as our cloud provider.
 
-While the choices made in this implementation reflect our specific requirements
-and constraints, it's worth noting that other approaches exist for managing
-cloud infrastructure with Terraform. Our modular design, state management strategy,
-and access controls are tailored to our current operational needs and funding
-situation—but they are not set in stone. We continuously review and update our
-practices as our needs evolve.
+You can find more about our benefits [here](https://www.microsoft.com/en-us/nonprofits/azure).
+
+If you have access to the adminorg account, you can check the current status of
+our Azure grant [here](https://www.microsoftazuresponsorships.com/).
+:::
 
 ## Making Changes to the Infrastructure
 
@@ -155,6 +202,10 @@ consistency and control.
    automatically. This workflow calculates the estimated cost impact of your
    changes and posts a report in the pull request comments, so you can review
    any potential cost implications before merging.
+   :::tip
+   If you want to run Infracost locally, you can install it by following the
+   [official documentation](https://www.infracost.io/docs/).
+   :::
 
 4. **Apply the Changes:**  
    After your changes have been reviewed and approved, merge the pull request
@@ -171,16 +222,34 @@ consistency and control.
 
 - **`terraform init`**  
   Initializes the working directory containing the Terraform configuration files.
+  :::tip
+  This has to be run as soon as you clone the repository or when you pull changes
+  that include new modules or providers.
+  :::
 
 - **`terraform plan`**  
-  Generates an execution plan showing what changes will be applied to your infrastructure.
+  Generates an execution plan showing what changes will be applied to the infrastructure.
 
 - **`terraform apply`**  
-  Applies the changes defined in your Terraform configuration to your cloud environment.
+  Applies the changes defined in your Terraform configuration to the cloud environment.
 
 - **`terraform destroy`**  
   Destroys the resources managed by Terraform, useful for tearing down test environments or decommissioning infrastructure.
 
+  :::danger
+  If you ever happen to be as much as tempted of using `terraform destroy`, you
+  better be **SURE AS SHIT** about what you are doing. Make sure to review the
+  implications thoroughly before proceeding.
+  > *One does not simply destroy PoliNetwork with one command.*
+  :::
+
 By following these steps and leveraging our automated workflows, you ensure that
 infrastructure changes are managed in a consistent, cost-aware, and controlled
 manner.
+
+## References
+
+- [Terraform Documentation](https://www.terraform.io/docs/index.html)
+- [Microsoft Azure Documentation](https://docs.microsoft.com/en-us/azure/)
+- [Infracost Documentation](https://www.infracost.io/docs/)
+- [Terraform Repository](https://github.com/polinetworkorg/terraform)

…ing-started/basic-knowledge/Terraform.md …tarted/cloud-infrastructure/Terraform.mddocs/infrastructure/02-getting-started/basic-knowledge/Terraform.md renamed to docs/infrastructure/02-getting-started/cloud-infrastructure/Terraform.md docs/infrastructure/02-getting-started/basic-knowledge/Terraform.md renamed to docs/infrastructure/02-getting-started/cloud-infrastructure/Terraform.md

@@ -0,0 +1,2 @@
+label: Cloud Infrastructure
+position: 2

docs/infrastructure/02-getting-started/cloud-infrastructure/_category_.yml

@@ -1,5 +1,5 @@
 ---
-title: Basic Knowledge
+title: Cloud Infrastructure
 ---
 import DocCardList from '@theme/DocCardList';
 
@@ -64,6 +64,9 @@ While Terraform is responsible for infrastructure, **PoliNetwork-CD** focuses on
 
 In summary, **Terraform builds the foundation on which applications run**, while **PoliNetwork-CD manages the deployment and continuous updating of applications**. Both repositories work together to ensure a scalable and efficient cloud infrastructure.
 
+<!-- markdownlint-disable-next-line -->
+<DocCardList />
+
 ## References
 
 ### **Links to Repositories**
@@ -76,6 +79,3 @@ In summary, **Terraform builds the foundation on which applications run**, while
 - [Kubernetes Documentation](https://kubernetes.io/docs/)
 - [Terraform Documentation](https://www.terraform.io/docs/)
 - [ArgoCD Documentation](https://argo-cd.readthedocs.io/en/stable/)
-
-<!-- markdownlint-disable-next-line -->
-<DocCardList />