Describe inputs and outputs

README.md

@@ -10,18 +10,33 @@ Terraform module that creates kyma runtime in SAP BTP platform.
 
 ![image](./assets/sequence.png)
 
-### Input Variables
-
-### Outputs
-
+### Input Variables (TF vars)
+
+| NAME                       | MANDATORY | DEFAULT VALUE             | DESCRIPTION                                                                                                                                        |
+|----------------------------|-----------|---------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------|
+| BTP_GLOBAL_ACCOUNT         | true      |                           | UUID of SAP BTP Global Account                                                                                                                     |
+| BTP_BOT_USER               | true      |                           | Email of the technical user (shared mailbox)                                                                                                       |
+| BTP_BOT_PASSWORD           | true      |                           | Password of the techniacal user (created when inviting shared mailbox into custom SAP IAS tenant)                                                  |
+| BTP_USE_SUBACCOUNT_ID      | false     |                           | Provide an UUID of existing SAP BTP Subaccount to be used. Should not be combined with `BTP_NEW_SUBACCOUNT_*` inputs.                              |
+| BTP_NEW_SUBACCOUNT_NAME    | false     |                           | Provide a name for a new SAP BTP Subaccount to be created. Should not be combined with  `BTP_USE_SUBACCOUNT_ID` input.                             |
+| BTP_NEW_SUBACCOUNT_REGION  | false     |                           | Provide a region for a new SAP BTP Subaccount to be created. Should not be combined with  `BTP_USE_SUBACCOUNT_ID` input.                           |
+| BTP_CUSTOM_IAS_TENANT      | true      |                           | Provide the name of the custom SAP IAS tenant that is an authentication provider for the technical user.                                           |
+| BTP_CUSTOM_IAS_DOMAIN      | false     | accounts.ondemand.com     | Domain of the identity provider (on canary and staging environments this has to be set to `accounts400.ondemand.com`)                              |
+| BTP_BACKEND_URL            | false     | https://cli.btp.cloud.sap | URL of the BTP backend API (on canary environment this has to be set to  `https://cpcli.cf.sap.hana.ondemand.com`).                                |
+| BTP_KYMA_PLAN              | false     | azure                     | Use one of a valid kyma plans that you are entitled to use (One of: `azure`, `gcp`, `aws`,`sap-converged-cloud`)                                   |
+| BTP_KYMA_REGION            | false     | westeurope                | Use a valid kyma region that matches your selected kyma plan                                                                                       |
+| BTP_PROVIDER_SUBACCOUNT_ID | false     |                           | Use a UUID of a SAP BTP Subaccount where you already have a sharable service instances which you would like to reference in the new kyma runtime   |
+
+### Outputs 
+
+| Name                               | Condition for output presence                                     | Description                                                                                                                                                             |
+|------------------------------------|-------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| custom_service_manager_credentials | Present only if `BTP _PROVIDER_SUBACCOUNT_ID` was given as input  | Contains json-decoded parts of the provider subaccount's service manager secret data. Allows to reference a shared service instances from another (provider) subaccount |
+| kubeconfig                         | Always                                                            | yaml-encoded parts of the output kubeconfig. It can be used to initialise terraform kubernetes provider in the root module                                              |
+| subaccount_id                      | Always                                                            | subaccount ID of the created subaccount. It can be used to forcefully cleanup the subaccount i.e via BTP CLI                                                            |
 
 ## Running `terraform-sap-kyma-on-btp` module
 
 
 The module should be included as a child module, and provided with a configured `sap/btp` terraform provider. The root module must define the values for the input variables. Go to the included [examples](./examples/).
 
-## Useful Links (Optional)
-> Provide links to the most relevant module documentation (tutorials, technical references, resources, etc.).
-
-## Feedback (Optional)
-> Describe how users can provide feedback.

examples/kyma-on-btp-new-sa/README.md

@@ -1,5 +1,6 @@
-# Run 
+## Prerequisites
 
+### Ensure CLI tools
 Ensure you have opentofu (or terraform CLI installed).
 The sample scripts relly on `tofu` command, but its 100% compatible with `terraform` CLI.
 
@@ -8,8 +9,28 @@ Ensure the tofu CLI is installed by calling:
 brew install opentofu
 ```
 
+### Ensure Input parameters 
+
 Save a new version of the template file `examples/kyma-on-btp-new-sa/local-template.tfvars` as `examples/kyma-on-btp-new-sa/local.tfvars`. Provide values for input variables.
 
+```
+BTP_NEW_SUBACCOUNT_NAME = "new-test-sa"
+BTP_NEW_SUBACCOUNT_REGION = "..."
+BTP_BOT_USER = "{my-technical-user}@sap.com"
+BTP_BOT_PASSWORD = "..."
+BTP_GLOBAL_ACCOUNT = "..."
+BTP_CUSTOM_IAS_TENANT = "..."
+```
+
+### Ensure technical user access
+
+In this example a new subaccount is created automatically. Please ensure the following
+ - make sure that your custom SAP IAS tenant is trusted on global account level,
+ - make sure that technical user (bot user) is added to the global account and is assigned a global account administrator role collection,
+ - make sure the technical user is added to your custom SAP IAS tenant. 
+ - if you decide to use provider subaccount in order to create disposable references to existing, shared instances of stateful services  (via `BTP_PROVIDER_SUBACCOUNT_ID` environment variable ) the bot user would need to have `Subaccount Viewer` role collection assigned in the provider subaccount.
+
+## Run 
 Run the example:
 
 ```sh
@@ -26,5 +47,5 @@ kubectl get nodes --kubeconfig kubeconfig.yaml
 Last but not least, deprovision all resources via:
 
 ```sh
-tofu destroy -var="BTP_NEW_SUBACCOUNT_NAME=foo" -var-file="local.tfvars" -auto-approve
+tofu destroy -var-file="local.tfvars" -auto-approve
 ```

examples/kyma-on-btp-new-sa/local-template.tfvars

@@ -1,4 +1,4 @@
-# BTP_USE_SUBACCOUNT_ID = ""
+# Copy this file as `local.tfvars` and provide values 
 
 BTP_NEW_SUBACCOUNT_NAME = ""
 

examples/kyma-on-btp-reuse-sa/README.md

@@ -1,10 +1,6 @@
-# Prerequisites
-
-## Ensure CLI tools
-
-#TODO : Explain the requirements that existing subaccount needs to fulfill to be reused.
-- the bot user should have "Administrator" role
+## Prerequisites
 
+### Ensure CLI tools
 Ensure you have opentofu (or terraform CLI installed).
 The sample scripts relly on `tofu` command, but its 100% compatible with `terraform` CLI.
 
@@ -13,22 +9,28 @@ Ensure the tofu CLI is installed by calling:
 brew install opentofu
 ```
 
-## Ensure bot user access
-
-In order to make automatic management of btp resources possible you need to ensure the following:
- - establish trust between BTP global account and your custom IAS tenant
- - add the bot user to the custom IAS tenant
- - assign global account administrator role collection to the bot user (this example needs it to create subaccount. It is not required if subaccount is reused)
- - if you decide to use provider subaccount in order to create disposable references to existing, shared instances of stateful services  (via `BTP_PROVIDER_SUBACCOUNT_ID` environment variable ) the bot user would need to have `Subaccount Viewer` role collection assigned in the provider subaccount.
-
-## Ensure Input Variables
+### Ensure Input parameters 
 
-Save a new version of the template file `examples/kyma-on-btp-new-sa/local-template.tfvars` as `examples/kyma-on-btp-new-sa/local.tfvars`. Provide values for input variables
+Save a new version of the template file `examples/kyma-on-btp-reuse-sa/local-template.tfvars` as `examples/kyma-on-btp-reuse-sa/local.tfvars`. Provide values for input variables.
 
+```
+BTP_USE_SUBACCOUNT_ID = "...."
+BTP_BOT_USER = "{my-technical-user}@sap.com"
+BTP_BOT_PASSWORD = "..."
+BTP_GLOBAL_ACCOUNT = "..."
+BTP_CUSTOM_IAS_TENANT = "..."
+```
 
-# Run 
+### Ensure technical user access
 
+In this example a new subaccount is not created automaticallu but an existing subaccount is reused instead. Please ensure the following:
+ - make sure the subaccount to reuse belongs to the global account,
+ - make sure that your custom SAP IAS tenant is trusted on subbaccount level,
+ - make sure that technical user (bot user) is added to the subaccount and is assigned a subaccount administrator role collection,
+ - make sure the technical user is added to your custom SAP IAS tenant. 
+ - if you decide to use provider subaccount in order to create disposable references to existing, shared instances of stateful services  (via `BTP_PROVIDER_SUBACCOUNT_ID` environment variable ) the bot user would need to have `Subaccount Viewer` role collection assigned in the provider subaccount.
 
+## Run 
 Run the example:
 
 ```sh

examples/kyma-on-btp-reuse-sa/local-template.tfvars

@@ -1,7 +1,7 @@
 
-# Mandatory ID of the subaccount to be used
-BTP_USE_SUBACCOUNT_ID = ""
+# Copy this file as `local.tfvars` and provide values 
 
+BTP_USE_SUBACCOUNT_ID = ""
 BTP_BOT_USER = ""
 BTP_BOT_PASSWORD = ""
 BTP_GLOBAL_ACCOUNT = ""