feat: initial content for Terraform samples

.gitignore

@@ -36,4 +36,13 @@ override.tf.json
 .terraformrc
 terraform.rc
 
+# Ignore typical plan output files
+*.tfplan
+*.out
+*.plan
+
+.DS_Store
+
 *.env
+
+playground/**

.wordlist.txt

@@ -1,23 +1,32 @@
-APIs
+API
+api
 autocompletion
 APIs
 backend
 Backend
 breakpoint
 BTP
 btp
+carte
 CLA
 CLI
 CLIs
+cloudfoundry
+Cloudfoundry
 CodeQL
 config
 Copilot
+costcenter
+Costcenter
 customizations
 DCO
 dependabot
+Dev
+dev
 devcontainer
 devcontainers
 dir
+EMEA
 faq
 Github
 github
@@ -32,8 +41,11 @@ JSON
 js
 JS
 jq
+Kyma
 macOS
 md
+namings
+Namings
 NextSteps
 OAuth
 OpenSSF
@@ -70,6 +82,12 @@ TOML
 toolchain
 UIs
 UI
+Unmanaged
+unmanaged
+URL
+url
+uuid
+UUID
 VS
 workspace
 workspaces

sample-setups/README.md

@@ -0,0 +1,30 @@
+# Terraform Samples for SAP BTP Administrator's Guide
+
+## Paradigms
+
+We follow the paradigms of a simple and clear Terraform configuration as laid out in the [Simple, Clear, Maintainable](https://rosesecurity.dev/blog/2024/11/24/terraform-proverbs) blog post of the [Development Log](https://rosesecurity.dev/) especially:
+
+- Clear is better than clever.
+- Modules should be reusable, not rigid.
+- Outputs are for sharing.
+- Labels are free; use them liberally.
+- Descriptions are for users.
+- Use positive variable names to avoid double negatives.
+- Name with underscores, not dashes.
+- Using locals makes code descriptive and maintainable.
+
+## Naming Conventions and Tagging
+
+Ensuring naming conventions is one import aspect when provisioning and managing your SAP BTP account. We will align our samples in accordance to the [Naming Conventions for SAP BTP Accounts](https://help.sap.com/docs/btp/btp-admin-guide/naming-conventions-for-sap-btp-accounts).
+
+To ensure consistent naming of your resources, we encapsulate the guidelines in dedicated module. Besides the naming we will also include the labels that can be attached to some resources on SAP BTP.
+
+We have created one module for the level of the [directory](./modules/sap-btp-naming-conventions-directory/README.md) and one for the level of the [subaccount](./modules/sap-btp-naming-conventions-subaccount/README.md).
+
+## Setup of Directories
+
+The setup of directories as a structuring element for the subaccounts is configured in the folder `basic-setup/directory-setup`. The Details about the setup are described in the [README.md](./basic-setup/directory-setup/README.md) file.
+
+## Setup of Subaccounts
+
+The setup of subaccounts is configured in the folder `basic-setup/subaccount-setup`. The Details about the setup are described in the [README.md](./basic-setup/subaccount-setup/README.md) file.

sample-setups/basic-setup/directory-setup/README.md

@@ -0,0 +1,31 @@
+# Sample Setup for a Basic Directory Structure
+
+## Assumptions
+
+- We assume that we use the directories as structuring element for the subaccounts i.e., in an unmanaged fashion.
+- We assume that we do the directory setup in one run for all involved departments.
+
+## Design Decisions
+
+We decouple the directory creation i.e., the setup of the basic structure from the creation of the operational units namely the subaccounts inside of the directories. The changes on directory level are probably a rare scenario compared to changes in the subaccounts additionally depending on their stage. We want to avoid side effects as well as lengthy state refreshes and keep the state of the directories separate.
+
+## Directory Setup
+
+The creation of the directories is steered by a map of objects that define the business data relevant for a directory namely:
+
+- business_unit (`string`): The business unit that owns the directory e.g., HR, IT, Finance
+- costcenter (`string`): Cost center of the business unit
+- directory_contacts (`list(string)`): List of email addresses representing the directory contacts
+- region (`string`): The geographical region of the directory e.g., EMEA
+
+This is input data is reflected by the variables defined in the [variables.tf](./variables.tf) file
+
+The directories are provisioned via the [main.tf](./main.tf) file which delegates to the module [base-directory-setup](../../modules/base-directory-setup/README.md). This module combines the corresponding module containing the naming and labeling conventions for a directory and calls the Terraform resource [btp_directory](https://registry.terraform.io/providers/SAP/btp/latest/docs/resources/directory).
+
+After provisioning the output summarizes the executed setup as given by the [outputs.tf](./outputs.tf) file. Here is an example how the output could look like:
+
+![Sample Output for a directory](../../../assets/base-directory-output.png)
+
+## SAP BTP Administrator's Guide - References
+
+- [Naming and Directory Templates](https://help.sap.com/docs/btp/btp-admin-guide/naming-directory-templates)

sample-setups/basic-setup/directory-setup/main.tf

@@ -0,0 +1,10 @@
+module "directory" {
+  source = "../../modules/base-directory-setup"
+
+  for_each = var.directory_inputs
+
+  business_unit      = each.value.business_unit
+  costcenter         = each.value.costcenter
+  directory_contacts = each.value.directory_contacts
+  region             = each.value.region
+}

sample-setups/basic-setup/directory-setup/outputs.tf

@@ -0,0 +1,11 @@
+output "directories" {
+  value = {
+    for k, v in module.directory : k => {
+      id            = v.directory_id
+      name          = v.directory_name
+      business_unit = v.business_unit
+      costcenter    = v.costcenter
+      region        = v.region
+    }
+  }
+}

sample-setups/basic-setup/directory-setup/provider.tf

@@ -0,0 +1,13 @@
+terraform {
+  required_providers {
+    btp = {
+      source  = "SAP/btp"
+      version = "~>1.11.0"
+    }
+  }
+}
+
+# Configure the BTP Provider
+provider "btp" {
+  globalaccount = var.globalaccount
+}

sample-setups/basic-setup/directory-setup/variables.tf

@@ -0,0 +1,22 @@
+variable "globalaccount" {
+  type        = string
+  description = "The subdomain of the global account on SAP BTP"
+}
+
+variable "directory_inputs" {
+  type = map(object({
+    business_unit      = string
+    costcenter         = string
+    directory_contacts = list(string)
+    region             = string
+  }))
+  description = <<-EOT
+    The inputs for the directory module.
+    - `business_unit`: Business unit of the project e.g., HR, IT or Sales
+    - `costcenter`: Cost center to be used for subaccounts
+    - `directory_contacts`: Contact persons to be used for directories, added as label
+    - `region`: The geographical region for a directory. The parameter is optional
+      If you set it the possible values are: `EMEA`, `APAC`, `AMER`.
+      Default value: `null`.
+  EOT
+}

sample-setups/basic-setup/subaccount-setup/README.md

@@ -0,0 +1,60 @@
+# Setup of a Subaccount
+
+## Assumptions
+
+- We assume a basic setup of a subaccount is executed by the platform team/ SAP BTP administrator team
+- We assume that the responsibility of the platform team is restricted to a basic setup of a subaccount leaving out app subscriptions and service instance creation.
+
+## Design Decisions
+
+To keep the Terraform state files clearly separated the setup is done per subaccount i.e. per stage.
+
+## Subaccount Setup
+
+The setup of the subaccount comprises:
+
+- The setup of a subaccount in accordance to the naming conventions and labeling strategy of the company
+- The trust configuration to a custom IdP is configured by default.
+- Default entitlements are added depending on the stage. In addition the requesting team can add additional project specific entitlements ("à la carte entitlements")
+- Optionally a Cloud Foundry Environment is created
+
+### Naming Conventions and Labels
+
+The naming conventions and labels are centralized in the module [sap-btp-naming-conventions-subaccount](../../modules/sap-btp-naming-conventions-subaccount/README.md). The names and labels are derived based on input variables defined in the [variables.tf](./variables.tf) file.
+
+### Validations for Geographies and BTP Regions
+
+According to the SAP BTP Administrators Guide one part of the naming is the geographical region. To ensure that this region fits to the subaccount region, a validation is implemented in the [variables.tf](./variables.tf) file. The validation checks if the region of the subaccount is part of the geographical region. The geographical regions are defined in a local variables defined in the [main.tf](main.tf) file.
+
+### Setup of Entitlements
+
+The setup of entitlements is split into two parts:
+
+- The default entitlements that are defined per stage and sourced from the module [](../../modules/sap-btp-subaccount-default-entitlements/README.md)
+- Optional additional entitlements that might be needed due to project specific requirements. These entitlements are defined in the [variables.tf](./variables.tf) file
+
+The configuration merges the two files and adds the entitlements to the subaccount.
+
+To ease the provisioning of entitlements we use the Terraform community module [SAP BTP Entitlements Management with Terraform Module: sap-btp-entitlements](https://registry.terraform.io/modules/aydin-ozcan/sap-btp-entitlements/btp/latest).
+
+### Setup of Cloud Foundry Environment
+
+The setup of a Cloud Foundry environment is optional. The caller can decide if a Cloud Foundry environment is required or not e.g. when setting up a shared subaccount. The boolean variable is `provision_cf_environment` in the [variables.tf](./variables.tf) file.
+
+
+### Output
+
+The output defined in the [outputs.tf](./outputs.tf) file returns the main information relevant for the development team namely:
+
+- a link to the subaccount
+- The ID of the Cloud Foundry org
+- The API endpoint of the Cloud Foundry environment
+
+
+
+## SAP BTP Administrator's Guide - References
+
+- [Setting Up Your Account Model](https://help.sap.com/docs/btp/btp-admin-guide/setting-up-your-account-model)
+- [Naming and Directory Templates](https://help.sap.com/docs/btp/btp-admin-guide/naming-directory-templates)
+- [Setting Up Authentication](https://help.sap.com/docs/btp/btp-admin-guide/setting-up-authentication)
+- [Cloud Foundry, Kyma, or Both?](https://help.sap.com/docs/btp/btp-admin-guide/cloudfoundry-kyma-or-both)