docs: organizational optional limitations (#141)

<!--
Thank you for your contribution!

## Testing your PR

You can pinpoint the pr changes as terraform module source with
following format

```
source                    = "github.com/sysdiglabs/terraform-aws-secure-for-cloud//examples/organizational?ref=<BRANCH_NAME>"
```


## General recommendations
Check contribution guidelines at
https://github.com/sysdiglabs/terraform-aws-secure-for-cloud/blob/master/CONTRIBUTE.md#contribution-checklist

For a cleaner PR make sure you follow these recommendations:
- Review modified files and delete small changes that were not intended
and maybe slip the commit.
- Use Pull Request Drafts for visibility on Work-In-Progress branches
and use them on daily mob/pairing for team review
- Unless an external revision is desired, in order to validate or gather
some feedback, you are free to merge as long as **validation checks are
green-lighted**

## Checklist

- [ ] If `test/fixtures/*/main.tf` files are modified, update:
    - [ ] the snippets in the README.md file under root folder.
- [ ] the snippets in the README.md file for the corresponding example.
- [ ] If `examples` folder are modified, update:
    - [ ] README.md file with pertinent changes.
- [ ] `test/fixtures/*/main.tf` in case the snippet needs modifications.
- [ ] If any architectural change has been made, update the diagrams.

-->

Author: iru

examples/organizational/README.md

@@ -4,15 +4,16 @@ Assess the security of your organization.
 
 Deploy Sysdig Secure for Cloud using an [AWS Organizational Cloudtrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/creating-trail-organization.html) that will fetch events from all organization member accounts (and the managed one too).
 
+* In the **user-provided member account**
+    * All the Sysdig Secure for Cloud service-related resources/workload will be created
 * In the **management account**
     * An Organizational Cloutrail will be deployed  (with required S3,SNS)
     * An additional role `SysdigSecureForCloudRole` will be created
         * to be able to read cloudtrail-s3 bucket events (and query cloudtrail-sqs) from sysdig workload member account.
-        * scanning-only, to assumeRole over member-account role
+        * if `deploy_image_scanning_*`, to assumeRole over member-account role
           * to scan images pushed to ECR's that may be present in other member accounts.
           * to describe ECS task definitions and get images to be scanned, on clusters in other member accounts
-* In the **user-provided member account**
-    * All the Sysdig Secure for Cloud service-related resources/workload will be created
+
 
 ### Notice
 
@@ -196,7 +197,7 @@ $ terraform apply
 | <a name="input_ecs_vpc_id"></a> [ecs\_vpc\_id](#input\_ecs\_vpc\_id) | ID of the VPC where the workload is to be deployed. If defaulted a new VPC will be created. If specified all three parameters `ecs_cluster_name`, `ecs_vpc_id` and `ecs_vpc_subnets_private_ids` are required | `string` | `"create"` | no |
 | <a name="input_ecs_vpc_region_azs"></a> [ecs\_vpc\_region\_azs](#input\_ecs\_vpc\_region\_azs) | List of Availability Zones for ECS VPC creation. e.g.: ["apne1-az1", "apne1-az2"]. If defaulted, two of the default 'aws\_availability\_zones' datasource will be taken | `list(string)` | `[]` | no |
 | <a name="input_ecs_vpc_subnets_private_ids"></a> [ecs\_vpc\_subnets\_private\_ids](#input\_ecs\_vpc\_subnets\_private\_ids) | List of VPC subnets where workload is to be deployed. If defaulted new subnets will be created within the VPC. A minimum of two subnets is suggested. If specified all three parameters `ecs_cluster_name`, `ecs_vpc_id` and `ecs_vpc_subnets_private_ids` are required. | `list(string)` | `[]` | no |
-| <a name="input_existing_cloudtrail_config"></a> [existing\_cloudtrail\_config](#input\_existing\_cloudtrail\_config) | Optional block. If not set, a new cloudtrail, sns and sqs resources will be created<br/><br>If there's an existing cloudtrail, input one of the Optional 1/2/3 blocks.<br><ul><br>  <li>cloudtrail\_s3\_arn: Optional 1. ARN of a pre-existing cloudtrail\_sns s3 bucket. Used together with `cloudtrail_sns_arn`, `cloudtrail_s3_arn`. If it does not exist, it will be inferred from create cloudtrail"</li><br>  <li>cloudtrail\_sns\_arn: Optional 1. ARN of a pre-existing cloudtrail\_sns. Used together with `cloudtrail_sns_arn`, `cloudtrail_s3_arn`. If it does not exist, it will be inferred from created cloudtrail. Providing an ARN requires permission to SNS:Subscribe, check ./modules/infrastructure/cloudtrail/sns\_permissions.tf block</li><br>  <li>cloudtrail\_s3\_role\_arn: Optional 2. ARN of the role to be assumed for S3 access. This role must be in the same account of the S3 bucket. Currently this setup is not compatible with organizational scanning feature</li><br>  <li>cloudtrail\_s3\_sns\_sqs\_arn: Optional 3. ARN of the queue that will ingest events forwarded from an existing cloudtrail\_s3\_sns</li><br>  <li>cloudtrail\_s3\_sns\_sqs\_url: Optional 3. URL of the queue that will ingest events forwarded from an existing cloudtrail\_s3\_sns<</li><br></ul> | <pre>object({<br>    cloudtrail_s3_arn         = optional(string)<br>    cloudtrail_sns_arn        = optional(string)<br>    cloudtrail_s3_role_arn    = optional(string)<br>    cloudtrail_s3_sns_sqs_arn = optional(string)<br>    cloudtrail_s3_sns_sqs_url = optional(string)<br>  })</pre> | <pre>{<br>  "cloudtrail_s3_arn": "create",<br>  "cloudtrail_s3_role_arn": null,<br>  "cloudtrail_s3_sns_sqs_arn": null,<br>  "cloudtrail_s3_sns_sqs_url": null,<br>  "cloudtrail_sns_arn": "create"<br>}</pre> | no |
+| <a name="input_existing_cloudtrail_config"></a> [existing\_cloudtrail\_config](#input\_existing\_cloudtrail\_config) | Optional block. If not set, a new cloudtrail, sns and sqs resources will be created in the management account<br/><br>If provided, all resources (cloudtrail,s3,sqs) must exist in the management account.<br>Otherwise, check [use-cases](https://github.com/sysdiglabs/terraform-aws-secure-for-cloud/tree/master/use-cases) for proper permission setup.<br>If there's an existing cloudtrail, input one of the Optional 1/2/3 blocks.<br><ul><br>  <li>cloudtrail\_s3\_arn: Optional 1. ARN of a pre-existing cloudtrail\_sns s3 bucket. Used together with `cloudtrail_sns_arn`, `cloudtrail_s3_arn`. If it does not exist, it will be inferred from create cloudtrail"</li><br>  <li>cloudtrail\_sns\_arn: Optional 1. ARN of a pre-existing cloudtrail\_sns. Used together with `cloudtrail_sns_arn`, `cloudtrail_s3_arn`. If it does not exist, it will be inferred from created cloudtrail. Providing an ARN requires permission to SNS:Subscribe, check ./modules/infrastructure/cloudtrail/sns\_permissions.tf block</li><br>  <li>cloudtrail\_s3\_role\_arn: Optional 2. ARN of the role to be assumed for S3 access. This role must be in the same account of the S3 bucket. Currently this setup is not compatible with organizational scanning feature</li><br>  <li>cloudtrail\_s3\_sns\_sqs\_arn: Optional 3. ARN of the queue that will ingest events forwarded from an existing cloudtrail\_s3\_sns</li><br>  <li>cloudtrail\_s3\_sns\_sqs\_url: Optional 3. URL of the queue that will ingest events forwarded from an existing cloudtrail\_s3\_sns<</li><br></ul> | <pre>object({<br>    cloudtrail_s3_arn         = optional(string)<br>    cloudtrail_sns_arn        = optional(string)<br>    cloudtrail_s3_role_arn    = optional(string)<br>    cloudtrail_s3_sns_sqs_arn = optional(string)<br>    cloudtrail_s3_sns_sqs_url = optional(string)<br>  })</pre> | <pre>{<br>  "cloudtrail_s3_arn": "create",<br>  "cloudtrail_s3_role_arn": null,<br>  "cloudtrail_s3_sns_sqs_arn": null,<br>  "cloudtrail_s3_sns_sqs_url": null,<br>  "cloudtrail_sns_arn": "create"<br>}</pre> | no |
 | <a name="input_name"></a> [name](#input\_name) | Name to be assigned to all child resources. A suffix may be added internally when required. Use default value unless you need to install multiple instances | `string` | `"sfc"` | no |
 | <a name="input_organizational_member_default_admin_role"></a> [organizational\_member\_default\_admin\_role](#input\_organizational\_member\_default\_admin\_role) | Default role created by AWS for management-account users to be able to admin member accounts.<br/>https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_accounts_access.html | `string` | `"OrganizationAccountAccessRole"` | no |
 | <a name="input_tags"></a> [tags](#input\_tags) | sysdig secure-for-cloud tags. always include 'product' default tag for resource-group proper functioning | `map(string)` | <pre>{<br>  "product": "sysdig-secure-for-cloud"<br>}</pre> | no |

examples/organizational/variables.tf

@@ -65,7 +65,9 @@ variable "existing_cloudtrail_config" {
   }
 
   description = <<-EOT
-    Optional block. If not set, a new cloudtrail, sns and sqs resources will be created<br/>
+    Optional block. If not set, a new cloudtrail, sns and sqs resources will be created in the management account<br/>
+    If provided, all resources (cloudtrail,s3,sqs) must exist in the management account.<br/>
+    Otherwise, check [use-cases](https://github.com/sysdiglabs/terraform-aws-secure-for-cloud/tree/master/use-cases) for proper permission setup.<br/>
     If there's an existing cloudtrail, input one of the Optional 1/2/3 blocks.
     <ul>
       <li>cloudtrail_s3_arn: Optional 1. ARN of a pre-existing cloudtrail_sns s3 bucket. Used together with `cloudtrail_sns_arn`, `cloudtrail_s3_arn`. If it does not exist, it will be inferred from create cloudtrail"</li>

use-cases/README.md

@@ -6,7 +6,7 @@ Current examples were developed for simple use-case scenarios.
 
 New use-cases are appearing and once we consolidate a standard scenario, we will create new examples to accommodate new requirements.
 
-Check [current use-case list](https://github.com/sysdiglabs/terraform-aws-secure-for-cloud/tree/master/use-cases), or use the [questionnaire](./_questionnaire.md) to let us know your needs
+Check current use-case list or use the [questionnaire](./_questionnaire.md) to let us know your needs.
 
 Secure for cloud is served through Terraform for [AWS](https://github.com/sysdiglabs/terraform-aws-secure-for-cloud) 
 [GCP](https://github.com/sysdiglabs/terraform-google-secure-for-cloud) and [Azure](https://github.com/sysdiglabs/terraform-azurerm-secure-for-cloud) clouds, 
@@ -20,9 +20,14 @@ and for AWS in [Cloudformation](https://github.com/sysdiglabs/aws-templates-secu
 
 |                   | `/examples/single-*`                                               | `/examples/organizational-*` |
 | --| -- | -- |
-| Deployment Type   | all Sysdig resources will be deployed within the selected account | Most Sysdig resources will be deployed within the selected account (just one), but some features, require resources to be deployed on all of the member-accounts (for Compliance and Image Scanning) . <br />One role is needed on the management account for cloudtrail event access |
+| Deployment Type   | all Sysdig resources will be deployed within the selected account | Most Sysdig resources will 
+be deployed within the selected account (just one), but some features, require resources to be deployed on all of 
+the member-accounts (for Compliance and Image Scanning) . <br />One role is needed on the management account for 
+cloudtrail-s3 event access |
 | Target          | will only analyse current account                                 |  handles all accounts (managed and member)|
 | Drawbacks         | cannot re-use another account Cloudtrail data (unless its deployed on the same account where the sns/s3 bucket is) | for scanning, a per-member-account access role is required |
+| Optional usage limitations | - |  For organizational example, optional resources must exist in the management account. For other setups check
+other alternative use-cases | 
 | More Info | [single-ecs](https://github.com/sysdiglabs/terraform-aws-secure-for-cloud/tree/master/examples/single-account-ecs), [single-apprunner](https://github.com/sysdiglabs/terraform-aws-secure-for-cloud/tree/master/examples/single-account-apprunner), [single-k8s](https://github.com/sysdiglabs/terraform-aws-secure-for-cloud/tree/master/examples/single-account-k8s) | [organizational](https://github.com/sysdiglabs/terraform-aws-secure-for-cloud/tree/master/examples/organizational) |
 
 With both examples `single` and `org`, you can customize the desired features to de deployed with the `deploy_*` input vars to avoid deploying more than wanted.
@@ -47,7 +52,12 @@ Make use of optionals to allow the re-use of pre-existing resources, and avoid i
 
 |  Cloud |  Optionals | Related Input Vars | Other |
 | -- | --| -- | -- |
-| AWS  | Cloudtrail | single: [`cloudtrail_sns_arn`](https://github.com/sysdiglabs/terraform-aws-secure-for-cloud/tree/master/examples/single-account-ecs#input_cloudtrail_sns_arn)<br/>organizational: [`existing_cloudtrail_config`](https://github.com/sysdiglabs/terraform-aws-secure-for-cloud/tree/master/examples/organizational#input_existing_cloudtrail_config) | - |
+| AWS  | Cloudtrail | single: [`cloudtrail_sns_arn`](https://github.
+com/sysdiglabs/terraform-aws-secure-for-cloud/tree/master/examples/single-account-ecs#input_cloudtrail_sns_arn)
+<br/>organizational: [`existing_cloudtrail_config`](https://github.
+com/sysdiglabs/terraform-aws-secure-for-cloud/tree/master/examples/organizational#input_existing_cloudtrail_config) 
+|  For organizational example, optional resources must exist in the management account. For other setups check 
+other alternative use-cases |
 | | ECS, VPC, Subnet | `ecs_cluster_name`, `ecs_vpc_id`, `ecs_vpc_subnets_private_ids` | if used, the three are mandatory  |
 | GCP | - | - | - |
 | Azure | ResourceGroup | `resource_group_name` | - |