feat: docs finally (#52)

.editorconfig

@@ -0,0 +1,9 @@
+root = true
+
+[*]
+indent_size = 2
+indent_style = space
+end_of_line = lf
+
+[{GNUMakefile, Makefile}]
+indent_style = tab

.gitignore

@@ -1,3 +1,6 @@
 # temporary dir
 .temp
 .alzlib
+
+# Custom VSCode launch settings
+.vscode/launch.json

.vscode/extensions.json

@@ -0,0 +1,7 @@
+{
+  "recommendations": [
+    "EditorConfig.EditorConfig",
+    "redhat.vscode-yaml",
+    "remcohaszing.schemastore"
+  ]
+}

CONTRIBUTING.md

@@ -0,0 +1,14 @@
+# Contributing
+
+This project welcomes contributions and suggestions. Most contributions require you to
+agree to a Contributor License Agreement (CLA) declaring that you have the right to,
+and actually do, grant us the rights to use your contribution. For details, visit
+https://cla.microsoft.com.
+
+When you submit a pull request, a CLA-bot will automatically determine whether you need
+to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the
+instructions provided by the bot. You will only need to do this once across all repositories using our CLA.
+
+This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
+For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/)
+or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.

Makefile

@@ -0,0 +1,4 @@
+.PHONY: server
+server:
+	@echo "Starting Hugo docs server..."
+	cd docs && hugo server && cd ..

docs/content/_index.md

@@ -5,8 +5,31 @@ geekdocNav: true
 geekdocAnchor: true
 ---
 
-{{< hint type=info icon=gdoc_date title="Work in progress" >}}
+Welcome to the Azure Landing Zones Library. This library is a collection of resources to help you build and manage governance on Azure. The library is comprised of Azure Policy assets, together with a series of constructs that result in a deployable architecture.
 
-This site is under construction 🏗️
+For an example, please see the alz library member in the `platform/alz` directory of the [repository](https://github.com/Azure/Azure-Landing-Zones-Library/tree/main/platform/alz).
 
-{{< /hint >}}
+For more information on why we built this, see the [Why](/Azure-Landing-Zones-Library/why) section.
+
+## What types of things can you find in the library?
+
+See the [Library Assets](/Azure-Landing-Zones-Library/assets) section for more information.
+
+## How can you consume the library?
+
+See the [Library Clients](/Azure-Landing-Zones-Library/clients) section for more information.
+
+## Library structure
+
+Each library member has its own directory in the `platform` directory of the repo.
+The files are processed according to their file names, the directory they are in is not considered, however you may wish to organize your files in to directories for clarity.
+We recommend that you use the following directory naming convention for consistency:
+
+- `archetype_definitions`
+- `architecture_definitions`
+- `policy_assignments`
+- `policy_definitions`
+- `policy_set_definitions`
+- `role_definitions`
+
+You should place the metadata and policy default values files in the root of the library member directory.

docs/content/assets/_index.md

@@ -0,0 +1,41 @@
+---
+title: Library Assets
+geekdocNav: true
+# geekdocAlign: center
+geekdocAnchor: true
+---
+
+Assets are identified by filename patterns and are read from the library member directories. The assets are processed according to their names, the directory they are in is not considered, however you may wish to organize your files in to directories for clarity.
+
+{{< hint type=important >}}
+The name (JSON property `.name`) of the asset must be unique for any given asset type. For example, you cannot have two policy definitions with the same name. This is especially important when considering extensibility.
+{{< /hint >}}
+
+Assets are keyed by name, during the process of creating a deployable architecture, the assets are modified to update references such as resource ids.
+Clients should lookup references resources by name and correctly update values before deploying the resource.
+
+The following assets are supported:
+
+- [**Policy Definitions**](/Azure-Landing-Zones-Library/assets/policy-definitions): These are the custom Azure policy definitions that you can assign to your environment.
+
+- [**Policy Set Definitions**](/Azure-Landing-Zones-Library/assets/policy-set-definitions): These are the custom Azure policy set definitions that you can assign to your environment.
+
+- [**Policy Assignments**](/Azure-Landing-Zones-Library/assets/policy-assignments): These are the Azure policy assignments that you can assign to your environment.
+They may reference built-in or custom policy (set) definitions.
+
+- [**Role Definitions**](/Azure-Landing-Zones-Library/assets/role-definitions): These are the custom Azure role definitions that you can assign to your environment.
+
+The above assets are organized in to a hierarchy of constructs. The constructs are:
+
+- [**Archetypes**](/Azure-Landing-Zones-Library/assets/archetypes): These constructs that represent a set of policies and roles.
+One or more archetypes may be assigned to a management group using an architecture.
+
+- [**Architectures**](/Azure-Landing-Zones-Library/assets/architectures): These are the constructs that represent a deployable management group hierarchy, together with associated archetypes.
+
+There are also some additional items in each library member:
+
+- [**Metadata**](/Azure-Landing-Zones-Library/assets/metadata): This is the metadata for the library member. It includes the name, description, and dependency information.
+A library memebr may extend another, if this is the case then the dependency information is useful for clients to understand the relationship between the members.
+
+- [**Policy Default Values**](/Azure-Landing-Zones-Library/assets/policy-default-values): It is common to want to pass the same value into multiple policy assignments.
+For example, a default Log Analytics workspace id. This construct allows you to define a default value that can be referenced by many policy assignments, for specific parameters.

docs/content/assets/archetype-overrides.md

@@ -0,0 +1,44 @@
+---
+title: Archetype Overrides
+geekdocNav: true
+geekdocAlign: left
+geekdocAnchor: true
+---
+
+Filename patterns:
+
+- `*.alz_archetype_override.json`
+- `*.alz_archetype_override.yaml`
+- `*.alz_archetype_override.yml`
+
+An archetype override is a delta of an existing archetype.
+it is used by callers to modify the behavior of an archetype without changing the archetype itself.
+
+{{< hint type=important >}}
+Archetype overrides are designed to be used in local libraries as the last step in customization by the caller.
+They should not be stored in a central library.
+{{< /hint >}}
+
+We publish the schema of an archetype override [here](https://raw.githubusercontent.com/Azure/Azure-Landing-Zones-Library/main/schemas/archetype_override.json) and we have registered the file extensions with [schemastore.org](https://www.schemastore.org/json/) to enable  automatic validation in editors.
+
+An archetype override has a name, which must be unique amonst all archetypes and override archetypes.
+It also has and a set of policy definitions, policy set definitions, policy assignments, and role definitions to add and remove from the referenced base archetype.
+All of these associated assets are referenced by their name (JSON `.name`) property.
+
+## Example
+
+Here is an example archetype definition file:
+
+```yaml
+name: "landing_zones_override"
+base_archetype: "landing_zones"
+policy_assignments_to_add: []
+policy_assignments_to_remove:
+  - "Deny-IP-forwarding"
+policy_definitions_to_add: []
+policy_definitions_to_remove: []
+policy_set_definitions_to_add: []
+policy_set_definitions_to_remove: []
+role_definitions_to_add: []
+role_definitions_to_remove: []
+```

docs/content/assets/archetypes.md

@@ -0,0 +1,57 @@
+---
+title: Archetypes
+geekdocNav: true
+geekdocAlign: left
+geekdocAnchor: true
+---
+
+Filename patterns:
+
+- `*.alz_archetype_definition.json`
+- `*.alz_archetype_definition.yaml`
+- `*.alz_archetype_definition.yml`
+
+An archetype is a collection of assets that can be deployed to a management group.
+In order to promote extensibility, multiple archetypes can be deployed to the same management group.
+
+We publish the schema of an archetype definition [here](https://raw.githubusercontent.com/Azure/Azure-Landing-Zones-Library/main/schemas/archetype_definition.json) and we have registered the file extensions with [schemastore.org](https://www.schemastore.org/json/) to enable  automatic validation in editors.
+
+An archetype has a name, which must be unique, and a set of associated policy definitions, policy set definitions, policy assignments, and role definitions.
+All of these associated assets are referenced by their name (JSON `.name`) property.
+
+## Example
+
+Here is an example archetype definition file:
+
+```yaml
+name: "landing_zones"
+policy_assignments:
+  - "Audit-AppGW-WAF"
+  - "Deny-IP-forwarding"
+  - "Deny-MgmtPorts-Internet"
+  - "Deny-Priv-Esc-AKS"
+  - "Deny-Privileged-AKS"
+  - "Deny-Storage-http"
+  - "Deny-Subnet-Without-Nsg"
+  - "Deploy-AKS-Policy"
+  - "Deploy-AzSqlDb-Auditing"
+  - "Deploy-MDFC-DefSQL-AMA"
+  - "Deploy-SQL-TDE"
+  - "Deploy-SQL-Threat"
+  - "Deploy-VM-Backup"
+  - "Deploy-VM-ChangeTrack"
+  - "Deploy-VM-Monitoring"
+  - "Deploy-vmArc-ChangeTrack"
+  - "Deploy-vmHybr-Monitoring"
+  - "Deploy-VMSS-ChangeTrack"
+  - "Deploy-VMSS-Monitoring"
+  - "Enable-AUM-CheckUpdates"
+  - "Enable-DDoS-VNET"
+  - "Enforce-AKS-HTTPS"
+  - "Enforce-ASR"
+  - "Enforce-GR-KeyVault"
+  - "Enforce-TLS-SSL-H224"
+policy_definitions: []
+policy_set_definitions: []
+role_definitions: []
+```

docs/content/assets/architectures.md

@@ -0,0 +1,30 @@
+---
+title: Architectures
+geekdocNav: true
+geekdocAlign: left
+geekdocAnchor: true
+---
+
+Filename patterns:
+
+- `*.alz_architecture_definition.json`
+- `*.alz_architecture_definition.yaml`
+- `*.alz_architecture_definition.yml`
+
+Architectures define a management group hierarchy, together with the policies and policy assignments that are applied to the management groups.
+
+We publish the schema of an architecture definition [here](https://raw.githubusercontent.com/Azure/Azure-Landing-Zones-Library/main/schemas/architecture_definition.json) and we have registered the file extensions with [schemastore.org](https://www.schemastore.org/json/) to enable  automatic validation in editors.
+
+An architecture has a name, which must be unique, and a set of management groups with associated archetypes.
+Each management group has the following properties:
+
+- **id**: The name of the management group
+- **display_name**: The display name of the management group
+- **archetypes**: A list of archetype names to apply to the management group
+- **parent_id**: The id of the parent management group, set to `null` to indicate the root management group
+- **exists**: A boolean value indicating whether the management group already exists and should not be created
+
+If `parent_id` is set to `null`, the management group is created as a child of the management group defined by the client.
+Typically, this is the tenant root management group.
+
+All of these associated assets are referenced by their name (JSON `.name`) property.

docs/content/assets/metadata.md

@@ -0,0 +1,64 @@
+---
+title: Metadata
+geekdocNav: true
+geekdocAlign: left
+geekdocAnchor: true
+---
+
+Filename patterns:
+
+- `alz_library_metadata.json`
+
+The metadata file is a JSON file that contains metadata about the library.
+Note only the JSON format is supported for this file, there can only be one metadata file and it must be in the root of the library member directory.
+It is used to provide information about the library, such as the name, display name, description and any dependencies.
+
+We publish the schema of the library metadata [here](https://raw.githubusercontent.com/Azure/Azure-Landing-Zones-Library/main/schemas/library_metadata.json) and we have registered the file name with [schemastore.org](https://www.schemastore.org/json/) to enable  automatic validation in editors.
+
+## Dependencies
+
+It is a key value proposition that one library member can depend on another library member.
+This is done by specifying library references in the `.dependencies` section of the metadata file.
+
+Clients can read this metadata to understand the dependencies of the library and ensure that they download all the required libraries in order to create a successful deployment.
+
+Dependencies come in two flavors:
+
+1. ALZ Library dependencies
+2. External dependencies
+
+### ALZ Library dependencies
+
+These are defined by the library path and reference (version):
+
+```json
+{
+  "dependencies": [
+    {
+      "path": "platform/alz",
+      "ref": "2024.07.0"
+    }
+  ]
+}
+```
+
+### External dependencies
+
+These are defined by the library path and reference (version):
+
+```json
+{
+  "dependencies": [
+    {
+      "custom_url": "git::https://github.com/myorg/myrepo.git//mypath@mytag",
+    }
+  ]
+}
+```
+
+The `custom_url` should be valid [go-getter](https://pkg.go.dev/github.com/hashicorp/go-getter#section-readme) URL format.
+
+{{< hint type=note >}}
+Do not put security sensitive information into the `custom_url`.
+Instead configure any authentication/authorization externally to the client.
+{{< /hint >}}

docs/content/assets/policy-assignments.md

@@ -0,0 +1,28 @@
+---
+title: Policy Assignments
+geekdocNav: true
+geekdocAlign: left
+geekdocAnchor: true
+---
+
+Filename patterns:
+
+- `*.alz_policy_assignment.json`
+- `*.alz_policy_assignment.yaml`
+- `*.alz_policy_assignment.yml`
+
+These files represent Azure Policy assignments.
+They are files that represent the resource definition as per the schema.
+Although the Azure Resource Manager APIs use JSON, the library supports both JSON and YAML formats.
+Any keys that are not part of the schema should be ignored.
+
+Within the resource definition, there are several values that specific to the scope of the deployed resource and must be modified when the assignment is deployed in an architecture.
+
+These are:
+
+- The resource id
+- The scope
+- The location
+- The referenced policy (set) definition resource id
+
+[Clients](/Azure-Landing-Zones-Library/clients) should be aware of these values and ensure that they are correctly set when deploying the resource.