Merge pull request #420 from noqdev/iambic-template-examples-docs

Documentation for IAMbic template examples with IAMOps flow
noqdev · May 22, 2023 · 71d6b57 · 71d6b57
2 parents 38da745 + b7f435a
commit 71d6b57
Show file tree

Hide file tree

Showing 51 changed files with 495 additions and 162 deletions.
diff --git a/README.md b/README.md
@@ -25,7 +25,7 @@ Easily manage and streamline cloud Identity and Access Management (IAM) with IAM
 - **Extendable**: Integrate with various clouds and applications through a powerful plugin architecture.
 - **Auditable**: Track changes to IAM policies, permissions, and rules with Git history. For AWS, IAmbic annotates out-of-band commits with details from CloudTrail.
 
-The [iambic-templates-examples](https://github.com/noqdev/iambic-templates-examples) repository provides sample templates that are imported and maintained by IAMbic.
+Check out [IAMbic IAMOps Philosophy](/reference/iamops_philosophy) and an [example IAMbic templates repository](https://github.com/noqdev/iambic-templates-examples) to see a real-life example of IAMbic.
 
 ## 📣 Let's chat
 Do you want to connect with our contributors?

diff --git a/docs/generate_schema.py b/docs/generate_schema.py
@@ -115,7 +115,10 @@ def generate_docs():
 title: Template Schema
 ---
 
-These schema models are automatically generated.\n\n"""
+These schema models are automatically generated. Check out
+[IAMbic IAMOps Philosophy](/reference/iamops_philosophy) and the
+[example IAMbic templates repository](https://github.com/noqdev/iambic-templates-examples) to see a real-life
+examples of IAMbic templates and GitOps flows.\n\n"""
     schema_md_str += "# AWS Template Models\n"
     schema_md_str = create_model_schemas(
         parser, schema_dir, schema_md_str, aws_template_models

diff --git a/docs/web/docs/01-overview.mdx b/docs/web/docs/01-overview.mdx
@@ -6,10 +6,13 @@ title: Overview
 ## What is IAMbic?
 
 IAMbic tackles the complex task of managing distributed permissions across multiple cloud environments, such as AWS, Azure Active Directory,
-Okta, and Google Workspace. IAMbic creates a comprehensive copy of your human and cloud principals, and permissions in human readable
-"iambic templates" within Git. IAMbic ensures these templates stay in sync with your cloud environment, and supports bidirectional
+Okta, and Google Workspace. IAMbic creates a comprehensive copy of your human and cloud principals, and permissions, in the form of
+human readable "iambic templates" within Git. IAMbic ensures these templates stay in sync with your cloud environment, and supports bidirectional
 synchronization and round-trip functionality. This allows you to create or adjust templates and apply changes back to the cloud.
 
+Check out our [IAMOps Philosophy documentation](/reference/iamops_philosophy) to see examples of
+IAMbic templates, the structure of an iambic templates repository, and request workflows.
+
 <img src={"/img/generic/iambic_template_repository.png"} style={{width: '60%', display: 'block', marginLeft: 'auto', marginRight: 'auto'}} />
 
 IAMbic is built on top of a plugin-based architecture and can be extended to internal identity providers.

diff --git a/docs/web/docs/1-getting_started/2-install_and_configure.mdx b/docs/web/docs/1-getting_started/2-install_and_configure.mdx
@@ -31,7 +31,7 @@ cd iambic-templates
 git init
 cat <<EOF > .gitignore
 **/secrets.yaml
-proposed_changes.yaml
+proposed_changes*
 env/
 venv/
 EOF

diff --git a/docs/web/docs/1-getting_started/7-github.mdx b/docs/web/docs/1-getting_started/7-github.mdx
@@ -3,7 +3,17 @@ title: Deploy on GitHub
 ---
 
 ### Configuring GitHub to work with IAMbic
-These steps will ensure GitHub is configured properly to work with IAMbic.
+These steps will guide you through the process of setting up an IAMOps/GitOps workflow using
+GitHub Actions and an IAMbic Lambda function.
+
+:::note
+
+The instructions below leverage GitHub Action hosted runners. Github bills usage of action runners to the nearest full minute.
+You can find more details [here](https://docs.github.com/en/billing/managing-billing-for-github-actions/about-billing-for-github-actions).
+To avoid being charged, you might consider using self-hosted runners. Alternatively, you can reduce the frequency of your IAMbic
+action runs by changing their schedules after you have completed the setup process below.
+
+:::
 
 <!--
 
@@ -142,6 +152,7 @@ permissions from your cloud provider(s).
 	2. Add GitHub Apps
 4. Have an AWS admin configure federated login <!-- #TODO link to how to configure federated login --> for IAMbic GitHub actions.
 
+
 #### Configure your GitHub Repository to require approvals before merging
 
 1. Go to the GitHub repository you had created previously, `ExampleOrg/iambic-templates`

diff --git a/docs/web/docs/3-reference/00-example_iambic_templates_repository.mdx b/docs/web/docs/3-reference/00-example_iambic_templates_repository.mdx
@@ -0,0 +1,107 @@
+# Example IAMbic Templates Repository
+
+A sample IAMbic Templates repository is available at: [Example Repository](https://github.com/noqdev/iambic-templates-examples).
+This repository showcases the different features of IAMbic. Check out the [IAMOps Philosophy docs](/reference/iamops_philosophy) for specific examples of IAMOps in
+a GitHub workflow using this repository.
+
+## Initial Setup
+The `iambic setup` wizard was utilized to generate this file: [iambic_config.yaml](https://github.com/noqdev/iambic-templates-examples/blob/main/config/iambic_config.yaml).
+
+The configuration in `iambic_config.yaml` tells IAMbic to extract secrets from AWS Secrets Manager:
+
+```yaml
+extends:
+  - assume_role_arn: arn:aws:iam::580605962305:role/IambicSpokeRole
+    key: AWS_SECRETS_MANAGER
+    value: arn:aws:secretsmanager:us-east-1:580605962305:secret:iambic-config-secrets-c03d249e-a067-461c-a6a4-7d7d97f40bda-Bpuwi1
+```
+
+The secrets in AWS Secrets Manager are stored as YAML. Here's an example of how secrets look like in AWS Secrets Manager:
+
+```yaml
+secrets:
+  okta:
+    organizations:
+      - idp_name: development
+        org_url: https://dev-12345.okta.com/
+        api_token: API_TOKEN
+        iambic_managed: import_only
+  azure_ad:
+    organizations:
+      - idp_name: iambic
+        tenant_id: TENANT_ID
+        client_id: CLIENT_ID
+        client_secret: CLIENT_SECRET
+        iambic_managed: read_and_write
+  google_workspace:
+    workspaces:
+      - idp_name: "iambic.org"
+        subjects:
+          - domain: "iambic.org"
+            service_account: "SERVICE_ACCOUNT.iam.gserviceaccount.com"
+        type: "service_account"
+        project_id: "PROJECT_ID"
+        private_key_id: "PRIVATE_KEY_ID"
+        private_key: "-----BEGIN PRIVATE....-----...-----END PRIVATE...-----\n"
+        client_email: "PROJECT_ID@PROJECT_ID.iam.gserviceaccount.com"
+        client_id: "CLIENT_ID"
+        auth_uri: "https://accounts.google.com/o/oauth2/auth"
+        token_uri: "https://oauth2.googleapis.com/token"
+        auth_provider_x509_cert_url: "https://www.googleapis.com/oauth2/v1/certs"
+        client_x509_cert_url: "https://www.googleapis.com/robot/v1/metadata/x509/..."
+```
+
+## Resource Organization
+By default, IAMbic organizes your resources into folders based on the provider, resource type, and additional context, like AWS account names.
+However, you are free to move files outside of this structure. IAMbic will identify existing templates that exist for discovered resources, and will not attempt to
+move it. This flexibility allows you to organize your resources according to your needs, for instance, by environment (dev, stage, prod) or by team
+(engineering, finance, etc).
+
+```bash
+tree -d
+.
+├── config
+└── resources
+    ├── aws
+    │   ├── iam
+    │   │   ├── group
+    │   │   │   └── all_accounts
+    │   │   ├── managed_policy
+    │   │   │   ├── all_accounts
+    │   │   │   ├── iambic_test_org_account
+    │   │   │   ├── iambic_test_spoke_account_1
+    │   │   │   └── iambic_test_spoke_account_2
+    │   │   ├── role
+    │   │   │   ├── all_accounts
+    │   │   │   ├── iambic_test_org_account
+    │   │   │   ├── iambic_test_spoke_account_1
+    │   │   │   ├── iambic_test_spoke_account_2
+    │   │   │   ├── iambic_test_spoke_account_3
+    │   │   │   └── multi_account
+    │   │   └── user
+    │   │       ├── all_accounts
+    │   │       ├── iambic_test_org_account
+    │   │       └── iambic_test_spoke_account_1
+    │   └── identity_center
+    │       └── permission_set
+    ├── azure_ad
+    │   ├── group
+    │   │   └── iambic
+    │   └── user
+    │       └── iambic
+    ├── google_workspace
+    │   └── group
+    │       └── iambic.org
+    └── okta
+        ├── app
+        │   └── development
+        ├── group
+        │   └── development
+        └── user
+            └── development
+```
+
+## Example IAMOps Workflows in Git
+
+End-to-end IAMbic workflows in Git are available in the
+[IAMOps Philosophy docs](/reference/iamops_philosophy).
diff --git a/docs/web/docs/3-reference/3-schemas/aws_iam_group_template.json b/docs/web/docs/3-reference/3-schemas/aws_iam_group_template.json
@@ -62,7 +62,7 @@
     },
     "deleted": {
       "title": "Deleted",
-      "description": "Denotes whether the resource has been removed from AWS.Upon being set to true, the resource will be deleted the next time iambic is run.",
+      "description": "Denotes whether the resource has been removed from AWS.Upon being set to true, the resource will be deleted the next time iambic is ran.",
       "default": false,
       "type": "boolean"
     },
@@ -187,7 +187,7 @@
         },
         "deleted": {
           "title": "Deleted",
-          "description": "Denotes whether the resource has been removed from AWS.Upon being set to true, the resource will be deleted the next time iambic is run.",
+          "description": "Denotes whether the resource has been removed from AWS.Upon being set to true, the resource will be deleted the next time iambic is ran.",
           "default": false,
           "type": "boolean"
         },
@@ -333,7 +333,7 @@
         },
         "deleted": {
           "title": "Deleted",
-          "description": "Denotes whether the resource has been removed from AWS.Upon being set to true, the resource will be deleted the next time iambic is run.",
+          "description": "Denotes whether the resource has been removed from AWS.Upon being set to true, the resource will be deleted the next time iambic is ran.",
           "default": false,
           "type": "boolean"
         },
@@ -505,7 +505,7 @@
         },
         "deleted": {
           "title": "Deleted",
-          "description": "Denotes whether the resource has been removed from AWS.Upon being set to true, the resource will be deleted the next time iambic is run.",
+          "description": "Denotes whether the resource has been removed from AWS.Upon being set to true, the resource will be deleted the next time iambic is ran.",
           "default": false,
           "type": "boolean"
         },
@@ -561,10 +561,17 @@
         "statement": {
           "title": "Statement",
           "description": "List of policy statements",
-          "type": "array",
-          "items": {
-            "$ref": "#/definitions/PolicyStatement"
-          }
+          "anyOf": [
+            {
+              "type": "array",
+              "items": {
+                "$ref": "#/definitions/PolicyStatement"
+              }
+            },
+            {
+              "$ref": "#/definitions/PolicyStatement"
+            }
+          ]
         }
       },
       "required": [

diff --git a/docs/web/docs/3-reference/3-schemas/aws_iam_group_template.mdx b/docs/web/docs/3-reference/3-schemas/aws_iam_group_template.mdx
@@ -18,7 +18,7 @@ configurations for other models used in IAMbic.*
     - *string*
     - *string*
     - *string*
-- **`deleted`** *(boolean)*: Denotes whether the resource has been removed from AWS.Upon being set to true, the resource will be deleted the next time iambic is run. Default: `false`.
+- **`deleted`** *(boolean)*: Denotes whether the resource has been removed from AWS.Upon being set to true, the resource will be deleted the next time iambic is ran. Default: `false`.
 - **`template_type`** *(string)*: Default: `"NOQ::AWS::IAM::Group"`.
 - **`owner`** *(string)*: Owner of the group.
 - **`iambic_managed`**: Controls the directionality of Iambic changes. Default: `"undefined"`.
@@ -57,7 +57,7 @@ configurations for other models used in IAMbic. Cannot contain additional proper
       - *string*
       - *string*
       - *string*
-  - **`deleted`** *(boolean)*: Denotes whether the resource has been removed from AWS.Upon being set to true, the resource will be deleted the next time iambic is run. Default: `false`.
+  - **`deleted`** *(boolean)*: Denotes whether the resource has been removed from AWS.Upon being set to true, the resource will be deleted the next time iambic is ran. Default: `false`.
   - **`included_accounts`** *(array)*: A list of account ids and/or account names this statement applies to. Account ids/names can be represented as a regex and string. Default: `["*"]`.
     - **Items** *(string)*
   - **`excluded_accounts`** *(array)*: A list of account ids and/or account names this statement explicitly does not apply to. Account ids/names can be represented as a regex and string. Default: `[]`.
@@ -103,7 +103,7 @@ configurations for other models used in IAMbic. Cannot contain additional proper
       - *string*
       - *string*
       - *string*
-  - **`deleted`** *(boolean)*: Denotes whether the resource has been removed from AWS.Upon being set to true, the resource will be deleted the next time iambic is run. Default: `false`.
+  - **`deleted`** *(boolean)*: Denotes whether the resource has been removed from AWS.Upon being set to true, the resource will be deleted the next time iambic is ran. Default: `false`.
   - **`included_accounts`** *(array)*: A list of account ids and/or account names this statement applies to. Account ids/names can be represented as a regex and string. Default: `["*"]`.
     - **Items** *(string)*
   - **`excluded_accounts`** *(array)*: A list of account ids and/or account names this statement explicitly does not apply to. Account ids/names can be represented as a regex and string. Default: `[]`.
@@ -153,7 +153,7 @@ configurations for other models used in IAMbic. Cannot contain additional proper
       - *string*
       - *string*
       - *string*
-  - **`deleted`** *(boolean)*: Denotes whether the resource has been removed from AWS.Upon being set to true, the resource will be deleted the next time iambic is run. Default: `false`.
+  - **`deleted`** *(boolean)*: Denotes whether the resource has been removed from AWS.Upon being set to true, the resource will be deleted the next time iambic is ran. Default: `false`.
   - **`included_accounts`** *(array)*: A list of account ids and/or account names this statement applies to. Account ids/names can be represented as a regex and string. Default: `["*"]`.
     - **Items** *(string)*
   - **`excluded_accounts`** *(array)*: A list of account ids and/or account names this statement explicitly does not apply to. Account ids/names can be represented as a regex and string. Default: `[]`.
@@ -164,8 +164,11 @@ configurations for other models used in IAMbic. Cannot contain additional proper
     - **Items** *(string)*
   - **`policy_name`** *(string)*: The name of the policy.
   - **`version`** *(string)*
-  - **`statement`** *(array)*: List of policy statements.
-    - **Items**: Refer to *[#/definitions/PolicyStatement](#definitions/PolicyStatement)*.
+  - **`statement`**: List of policy statements.
+    - **Any of**
+      - *array*
+        - **Items**: Refer to *[#/definitions/PolicyStatement](#definitions/PolicyStatement)*.
+      - : Refer to *[#/definitions/PolicyStatement](#definitions/PolicyStatement)*.
 
 <a id="definitions/GroupProperties"></a>
 

diff --git a/docs/web/docs/3-reference/3-schemas/aws_iam_managed_policy_template.json b/docs/web/docs/3-reference/3-schemas/aws_iam_managed_policy_template.json
@@ -62,7 +62,7 @@
     },
     "deleted": {
       "title": "Deleted",
-      "description": "Denotes whether the resource has been removed from AWS.Upon being set to true, the resource will be deleted the next time iambic is run.",
+      "description": "Denotes whether the resource has been removed from AWS.Upon being set to true, the resource will be deleted the next time iambic is ran.",
       "default": false,
       "type": "boolean"
     },
@@ -301,7 +301,7 @@
         },
         "deleted": {
           "title": "Deleted",
-          "description": "Denotes whether the resource has been removed from AWS.Upon being set to true, the resource will be deleted the next time iambic is run.",
+          "description": "Denotes whether the resource has been removed from AWS.Upon being set to true, the resource will be deleted the next time iambic is ran.",
           "default": false,
           "type": "boolean"
         },
@@ -501,10 +501,17 @@
         "statement": {
           "title": "Statement",
           "description": "List of policy statements",
-          "type": "array",
-          "items": {
-            "$ref": "#/definitions/PolicyStatement"
-          }
+          "anyOf": [
+            {
+              "type": "array",
+              "items": {
+                "$ref": "#/definitions/PolicyStatement"
+              }
+            },
+            {
+              "$ref": "#/definitions/PolicyStatement"
+            }
+          ]
         }
       }
     },
@@ -572,7 +579,7 @@
         },
         "deleted": {
           "title": "Deleted",
-          "description": "Denotes whether the resource has been removed from AWS.Upon being set to true, the resource will be deleted the next time iambic is run.",
+          "description": "Denotes whether the resource has been removed from AWS.Upon being set to true, the resource will be deleted the next time iambic is ran.",
           "default": false,
           "type": "boolean"
         },

diff --git a/docs/web/docs/3-reference/3-schemas/aws_iam_managed_policy_template.mdx b/docs/web/docs/3-reference/3-schemas/aws_iam_managed_policy_template.mdx
@@ -18,7 +18,7 @@ configurations for other models used in IAMbic.*
     - *string*
     - *string*
     - *string*
-- **`deleted`** *(boolean)*: Denotes whether the resource has been removed from AWS.Upon being set to true, the resource will be deleted the next time iambic is run. Default: `false`.
+- **`deleted`** *(boolean)*: Denotes whether the resource has been removed from AWS.Upon being set to true, the resource will be deleted the next time iambic is ran. Default: `false`.
 - **`template_type`** *(string)*: Default: `"NOQ::AWS::IAM::ManagedPolicy"`.
 - **`owner`** *(string)*
 - **`iambic_managed`**: Controls the directionality of Iambic changes. Default: `"undefined"`.
@@ -96,7 +96,7 @@ configurations for other models used in IAMbic. Cannot contain additional proper
       - *string*
       - *string*
       - *string*
-  - **`deleted`** *(boolean)*: Denotes whether the resource has been removed from AWS.Upon being set to true, the resource will be deleted the next time iambic is run. Default: `false`.
+  - **`deleted`** *(boolean)*: Denotes whether the resource has been removed from AWS.Upon being set to true, the resource will be deleted the next time iambic is ran. Default: `false`.
   - **`included_accounts`** *(array)*: A list of account ids and/or account names this statement applies to. Account ids/names can be represented as a regex and string. Default: `["*"]`.
     - **Items** *(string)*
   - **`excluded_accounts`** *(array)*: A list of account ids and/or account names this statement explicitly does not apply to. Account ids/names can be represented as a regex and string. Default: `[]`.
@@ -150,8 +150,11 @@ configurations for other models used in IAMbic.
   - **`excluded_orgs`** *(array)*: A list of AWS organization ids this statement explicitly does not apply to. Org ids can be represented as a regex and string. Default: `[]`.
     - **Items** *(string)*
   - **`version`** *(string)*
-  - **`statement`** *(array)*: List of policy statements.
-    - **Items**: Refer to *[#/definitions/PolicyStatement](#definitions/PolicyStatement)*.
+  - **`statement`**: List of policy statements.
+    - **Any of**
+      - *array*
+        - **Items**: Refer to *[#/definitions/PolicyStatement](#definitions/PolicyStatement)*.
+      - : Refer to *[#/definitions/PolicyStatement](#definitions/PolicyStatement)*.
 
 <a id="definitions/Tag"></a>
 
@@ -170,7 +173,7 @@ configurations for other models used in IAMbic. Cannot contain additional proper
       - *string*
       - *string*
       - *string*
-  - **`deleted`** *(boolean)*: Denotes whether the resource has been removed from AWS.Upon being set to true, the resource will be deleted the next time iambic is run. Default: `false`.
+  - **`deleted`** *(boolean)*: Denotes whether the resource has been removed from AWS.Upon being set to true, the resource will be deleted the next time iambic is ran. Default: `false`.
   - **`key`** *(string)*
   - **`value`** *(string)*