diff --git a/README.md b/README.md index 6b0aaef6897..dbc94016c2f 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,18 @@ Microsoft patterns & practices http://aka.ms/architecture +## Understanding the local build process + +Some of the markdown files are generated from data stored in json files. +This is primarily to avoid human error for pages that still require some HTML. +The process that converts the json to markdown uses a utility script located in the `build` folder. +To run the build script, navigate to the root folder of this repository. + +```bash +npm install +node .\build\build.js +``` + ## Legal Notices Microsoft and any contributors grant you a license to the Microsoft documentation and other content in this repository under the [Creative Commons Attribution 4.0 International Public License](https://creativecommons.org/licenses/by/4.0/legalcode), diff --git a/build/build.js b/build/build.js index 5c3c51e7af5..cb4b5b01750 100644 --- a/build/build.js +++ b/build/build.js @@ -1,2 +1,8 @@ -const formatIndex = require('./reference-architectures/index'); -formatIndex(); \ No newline at end of file +const formatIndexFor = require('./reference-architectures/index'); +formatIndexFor('.'); +formatIndexFor('app-service-web-app'); +formatIndexFor('dmz'); +formatIndexFor('hybrid-networking'); +formatIndexFor('identity'); +formatIndexFor('virtual-machines-linux'); +formatIndexFor('virtual-machines-windows'); \ No newline at end of file diff --git a/build/reference-architectures/index.js b/build/reference-architectures/index.js index 46559ff5df0..08903093fbf 100644 --- a/build/reference-architectures/index.js +++ b/build/reference-architectures/index.js @@ -8,9 +8,9 @@ const engine = Liquid({ extname: '.liquid' }); -module.exports = function () { +module.exports = function (indexFolder) { - const basePath = path.resolve(__dirname, `../../docs/reference-architectures/`); + const basePath = path.resolve(__dirname, `../../docs/reference-architectures/`, indexFolder); const outputhPath = path.resolve(basePath, 'index.md'); const jsonPath = path.resolve(basePath, `index.json`); diff --git a/build/reference-architectures/templates/index.liquid b/build/reference-architectures/templates/index.liquid index b4b62dba0d5..29940265ab5 100644 --- a/build/reference-architectures/templates/index.liquid +++ b/build/reference-architectures/templates/index.liquid @@ -1,13 +1,15 @@ --- -title: Azure Reference Architectures -description: Reference architectures, blueprints, and prescriptive implementation guidance for common workloads on Azure. +title: {{ title }} +description: {{ description }} layout: LandingPage -NOTE: edit the template in ./build/reference-architectures !!! --- + + + -# Azure Reference Architectures +# {{ title }} -Our reference architectures are arranged by scenario, with related architectures grouped together. Each architecture includes recommended practices, along with considerations for scalability, availability, manageability, and security. Most also include a deployable solution. +{{ summary }}
+ \ No newline at end of file diff --git a/docs/reference-architectures/dmz/index.json b/docs/reference-architectures/dmz/index.json new file mode 100644 index 00000000000..8016ade1f18 --- /dev/null +++ b/docs/reference-architectures/dmz/index.json @@ -0,0 +1,19 @@ +{ + "title": "Network DMZ", + "description": "Explains and compares the different methods available for protecting applications and components running in Azure as part of a hybrid system from unauthorized intrusion.", + "summary": "These reference architectures show proven practices for creating a network DMZ that protects the boundary between an Azure virtual network and an on-premises network or the Internet.", + "series": [ + { + "title": "DMZ between Azure and on-premises", + "url": "./secure-vnet-hybrid.md", + "image": "./images/secure-vnet-hybrid.svg", + "summary": "Implements a secure hybrid network that extends an on-premises network to Azure." + }, + { + "title": "DMZ between Azure and the Internet", + "url": "./secure-vnet-dmz.md", + "image": "./images/secure-vnet-dmz.svg", + "summary": "Implements a secure network that accepts Internet traffic to Azure." + } + ] +} \ No newline at end of file diff --git a/docs/reference-architectures/dmz/index.md b/docs/reference-architectures/dmz/index.md index 709789c5d17..e0ee58413ba 100644 --- a/docs/reference-architectures/dmz/index.md +++ b/docs/reference-architectures/dmz/index.md @@ -3,48 +3,58 @@ title: Network DMZ description: Explains and compares the different methods available for protecting applications and components running in Azure as part of a hybrid system from unauthorized intrusion. layout: LandingPage --- + + + + # Network DMZ These reference architectures show proven practices for creating a network DMZ that protects the boundary between an Azure virtual network and an on-premises network or the Internet. - + + \ No newline at end of file diff --git a/docs/reference-architectures/hybrid-networking/index.json b/docs/reference-architectures/hybrid-networking/index.json new file mode 100644 index 00000000000..d6226bf1010 --- /dev/null +++ b/docs/reference-architectures/hybrid-networking/index.json @@ -0,0 +1,32 @@ +{ + "title": "Connect an on-premises network to Azure", + "description": "Recommended architectures for secure, robust network connections between on-premises networks and Azure.", + "summary": "These reference architectures show proven practices for creating a robust network connection between an on-premises network and Azure. [Which should I choose?](./considerations.md)", + "series": [ + { + "title": "VPN", + "url": "./vpn.md", + "image": "./images/vpn.svg", + "summary": "Extend an on-premises network to Azure using a site-to-site virtual private network (VPN)." + }, + { + "title": "ExpressRoute", + "url": "./expressroute.md", + "image": "./images/expressroute.svg", + "summary": "Extend an on-premises network to Azure using Azure ExpressRoute." + }, + { + "title": "ExpressRoute with VPN failover", + "url": "./expressroute-vpn-failover.md", + "image": "./images/expressroute-vpn-failover.svg", + "summary": "Extend an on-premises network to Azure using Azure ExpressRoute, with a VPN as a failover connection." + }, + { + "title": "Hub-spoke topology", + "url": "./hub-spoke.md", + "image": "./images/hub-spoke.svg", + "summary": "The hub is a central point of connectivity to your on-premises network. The spokes are VNets that peer with the hub, and can be used to isolate workloads." + } + ] +} + diff --git a/docs/reference-architectures/hybrid-networking/index.md b/docs/reference-architectures/hybrid-networking/index.md index 8e13d2980f4..85c0393bd82 100644 --- a/docs/reference-architectures/hybrid-networking/index.md +++ b/docs/reference-architectures/hybrid-networking/index.md @@ -3,87 +3,98 @@ title: Connect an on-premises network to Azure description: Recommended architectures for secure, robust network connections between on-premises networks and Azure. layout: LandingPage --- + + + # Connect an on-premises network to Azure -These reference architectures show proven practices for creating a robust network connection between an on-premises network and Azure. [Which should I choose?](./considerations.md) +These reference architectures show proven practices for creating a robust network connection between an on-premises network and Azure.
[Which should I choose?](./considerations.md) - + + \ No newline at end of file diff --git a/docs/reference-architectures/identity/index.json b/docs/reference-architectures/identity/index.json new file mode 100644 index 00000000000..c95ad7af761 --- /dev/null +++ b/docs/reference-architectures/identity/index.json @@ -0,0 +1,31 @@ +{ + "title": "Identity management", + "description": "Explains and compares the different methods available for managing identity in hybrid systems that span the on-premises/cloud boundary with Azure.", + "summary": "These reference architectures show options for integrating your on-premises Active Directory (AD) environment with an Azure network. [Which should I choose?](./considerations.md)", + "series": [ + { + "title": "Integrate with Azure Active Directory", + "url": "./azure-ad.md", + "image": "./images/azure-ad.svg", + "summary": "Integrate on-premises Active Directory domains and forests with Azure AD." + }, + { + "title": "Extend AD DS to Azure", + "url": "./adds-extend-domain.md", + "image": "./images/adds-extend-domain.svg", + "summary": "Extend your Active Directory environment to Azure using Active Directory Domain Services." + }, + { + "title": "Create an AD DS forest in Azure", + "url": "./adds-forest.md", + "image": "./images/adds-forest.svg", + "summary": "Create a separate AD domain in Azure that is trusted by domains in your on-premises forest." + }, + { + "title": "Extend AD FS to Azure", + "url": "./adfs.md", + "image": "./images/adfs.svg", + "summary": "Use Active Directory Federation Services for federated authentication and authorization in Azure." + } + ] +} \ No newline at end of file diff --git a/docs/reference-architectures/identity/index.md b/docs/reference-architectures/identity/index.md index 3a438543273..f9edbaa4fff 100644 --- a/docs/reference-architectures/identity/index.md +++ b/docs/reference-architectures/identity/index.md @@ -1,89 +1,100 @@ --- -title: Identity management +title: Identity management description: Explains and compares the different methods available for managing identity in hybrid systems that span the on-premises/cloud boundary with Azure. layout: LandingPage --- + + + # Identity management -These reference architectures show options for integrating your on-premises Active Directory (AD) environment with an Azure network. [Which should I choose?](./considerations.md) +These reference architectures show options for integrating your on-premises Active Directory (AD) environment with an Azure network.
[Which should I choose?](./considerations.md) - + + \ No newline at end of file diff --git a/docs/reference-architectures/index.json b/docs/reference-architectures/index.json index 5f2a009926c..8a2fc4f11e3 100644 --- a/docs/reference-architectures/index.json +++ b/docs/reference-architectures/index.json @@ -1,4 +1,7 @@ { + "title": "Azure Reference Architectures", + "description": "Reference architectures, blueprints, and prescriptive implementation guidance for common workloads on Azure.", + "summary": "Our reference architectures are arranged by scenario, with related architectures grouped together. Each architecture includes recommended practices, along with considerations for scalability, availability, manageability, and security. Most also include a deployable solution.", "series": [ { "title": "Windows VM workloads", diff --git a/docs/reference-architectures/index.md b/docs/reference-architectures/index.md index 048a5e804ae..efe79cf7a0d 100644 --- a/docs/reference-architectures/index.md +++ b/docs/reference-architectures/index.md @@ -2,8 +2,10 @@ title: Azure Reference Architectures description: Reference architectures, blueprints, and prescriptive implementation guidance for common workloads on Azure. layout: LandingPage -NOTE: edit the template in ./build/reference-architectures !!! --- + + + # Azure Reference Architectures diff --git a/docs/reference-architectures/virtual-machines-linux/index.json b/docs/reference-architectures/virtual-machines-linux/index.json new file mode 100644 index 00000000000..317049c2519 --- /dev/null +++ b/docs/reference-architectures/virtual-machines-linux/index.json @@ -0,0 +1,32 @@ +{ + "title": "Linux VM workloads", + "description": "Explains some common architectures for deploying VMs that host enterprise-scale applications in Azure.", + "summary": "These reference architectures show proven practices for running Linux VMs in Azure.", + "series": [ + { + "title": "Single VM", + "url": "./single-vm.md", + "image": "./images/single-vm.svg", + "summary": "Baseline recommendations for running any Linux VM in Azure." + }, + { + "title": "Load balanced VMs", + "url": "./multi-vm.md", + "image": "./images/multi-vm.svg", + "summary": "Multiple VMs placed behind a load balancer for scalability and availability." + }, + { + "title": "N-tier application", + "url": "./n-tier.md", + "image": "./images/n-tier.svg", + "summary": "VMs configured for an N-tier application with Apache Cassandra." + }, + { + "title": "Multi-region application", + "url": "./multi-region-application.md", + "image": "./images/multi-region-application.svg", + "summary": "N-tier application deployed to two regions for high availability." + } + ] +} + diff --git a/docs/reference-architectures/virtual-machines-linux/index.md b/docs/reference-architectures/virtual-machines-linux/index.md index ec4e6208267..99429647ac6 100644 --- a/docs/reference-architectures/virtual-machines-linux/index.md +++ b/docs/reference-architectures/virtual-machines-linux/index.md @@ -1,89 +1,100 @@ --- -title: Linux VM workloads +title: Linux VM workloads description: Explains some common architectures for deploying VMs that host enterprise-scale applications in Azure. layout: LandingPage --- + + + -# Running Linux VM workloads +# Linux VM workloads -These reference architectures show proven practices for running Linux VMs in Azure. +These reference architectures show proven practices for running Linux VMs in Azure. - + + \ No newline at end of file diff --git a/docs/reference-architectures/virtual-machines-windows/index.json b/docs/reference-architectures/virtual-machines-windows/index.json new file mode 100644 index 00000000000..7e7af9ad29a --- /dev/null +++ b/docs/reference-architectures/virtual-machines-windows/index.json @@ -0,0 +1,32 @@ +{ + "title": "Windows VM workloads", + "description": "Explains some common architectures for deploying VMs that host enterprise-scale applications in Azure.", + "summary": "These reference architectures show proven practices for running Windows VMs in Azure.", + "series": [ + { + "title": "Single VM", + "url": "./single-vm.md", + "image": "./images/single-vm.svg", + "summary": "Baseline recommendations for running any Windows VM in Azure." + }, + { + "title": "Load balanced VMs", + "url": "./multi-vm.md", + "image": "./images/multi-vm.svg", + "summary": "Multiple VMs placed behind a load balancer for scalability and availability." + }, + { + "title": "N-tier application", + "url": "./n-tier.md", + "image": "./images/n-tier.svg", + "summary": "VMs configured for an N-tier application with SQL Server." + }, + { + "title": "Multi-region application", + "url": "./multi-region-application.md", + "image": "./images/multi-region-application.svg", + "summary": "N-tier application deployed to two regions for high availability." + } + ] +} + diff --git a/docs/reference-architectures/virtual-machines-windows/index.md b/docs/reference-architectures/virtual-machines-windows/index.md index f26ee418e39..00fced3863d 100644 --- a/docs/reference-architectures/virtual-machines-windows/index.md +++ b/docs/reference-architectures/virtual-machines-windows/index.md @@ -1,89 +1,100 @@ --- -title: Windows VM workloads +title: Windows VM workloads description: Explains some common architectures for deploying VMs that host enterprise-scale applications in Azure. layout: LandingPage --- + + + -# Running Windows VM workloads +# Windows VM workloads -These reference architectures show proven practices for running Windows VMs in Azure. +These reference architectures show proven practices for running Windows VMs in Azure. - + + \ No newline at end of file