Prerequisites
There are several options available to deploy this reference architecture listed below, please ensure you complete the Common prerequisites and one of either VS Code DevContainer, GitHub Codespaces or Manual prerequisites.
The VS Code DevContainer or GitHub Codespaces deployment methods are highly recommended over the Manual method.
1 - Common
Common prerequisites necessary for all deployment methods
Azure Prerequisites
- An active Azure account
- A subscription available for deployment into, where you have
Owner
privileges
DNS Domain Name / Zone resource in Azure
The reference architecture takes advantage of Azure DNS for create and allocate DNS host names to service APIs and web endpoints programmatically through code.
Please see the following guide for setting up a domainin in Azure DNS.
Required Azure Preview features
Please ensure that the following Azure Preview features listed in the table below are registered on the Azure subscription.
Name |
Documentation |
Name Space |
Feature Flag |
Description |
Azure PowerShell Command |
Azure CLI Command |
Host-based encryption on Azure Kubernetes Service (AKS) |
docs.microsoft.com |
“Microsoft.Compute” |
“EncryptionAtHost” |
The data stored on the VM host of your AKS agent nodes' VMs is encrypted at rest and flows encrypted to the Storage service. This means the temp disks are encrypted at rest with platform-managed keys |
Register-AzProviderFeature -FeatureName "EncryptionAtHost" -ProviderNamespace "Microsoft.Compute" |
az feature register --namespace "Microsoft.Compute" --name "EncryptionAtHost" |
After applying all the feature registrations, please check that the registration state have fully registered, as it may take a few minutes, before deploying this reference architecture.
PowerShell
Get-AzProviderFeature -FeatureName "<Feature_Flag>" -ProviderNamespace "<NAME_SPACE>"
AZ CLI
az feature show --namespace "<NAME_SPACE>" --name "<Feature_Flag>"
Read about setting up Azure DNS in the next section.
This reference architecture uses Terraform’s state store to manage the infrastructure and configuration lifecycle.
This state is used by Terraform to map real world resources to your configuration, keep track of metadata, and to improve performance for large infrastructures.
Ideally the state store should be stored and accessed remotely, but for simplicity for this blueprint Terraform’s state store locally in files named terraform.tfstate
.
Runing this command will generate a export.zip
in the root on the project, while you can right click on and download if on Github Codespaces.
Importing a zip file called import.zip
in the root on the project.
Calls to Action
Read about the Azure DNS in the next section.
2 - Azure DNS - Setting Up a Custom DNS within Azure DNS
This guide shows the following steps to create a Custom DNS in Azure DNS aswell as adding the correct Varables for the Configuration to be utilized by The Reference Architecture.
Prerequisites
You must have a domain name available to test with that you can host in Azure DNS.
You must have full control of this domain. Full control includes the ability to set the name server (NS) records for the domain.
Create a DNS zone
- Go to the Azure portal to create a DNS zone. Search for and select DNS zones.
- Select Create DNS zone.
- On the Create DNS zone page, enter the following values, and then select Create. For example:
Setting |
Example Value |
Details |
Resource group |
edgc-dns-rg |
Create a resource group. The resource group name must be unique within the subscription that you selected. The location of the resource group has no impact on the DNS zone. Note to reference this resource group as parent_dns_zone_rg_name in terraform.tfvars config file. |
Zone child |
leave unchecked |
Since this zone is not a child zone you should leave this unchecked |
Name |
contoso.com |
Field for your parent zone name. Note to DNS as parent_dns_zone_name in terraform.tfvars config file. |
Location |
North Europe |
This field is based on the location selected as part of Resource group creation |
Retrieve name servers
Before you can delegate your DNS zone to Azure DNS, you need to know the name servers for your zone.
- With the DNS zone created, in the Azure portal Favorites pane, select All resources. On the All resources page, select your DNS zone.
- Retrieve the name servers from the DNS zone page. the assigned ns will look similar to:
ns1-01.azure-dns.com
, ns2-01.azure-dns.net
, ns3-01.azure-dns.org
, and ns4-01.azure-dns.info
.
Delegate the domain
Once the DNS zone gets created and you have the name servers,
you’ll need to update the parent domain with the Azure DNS name servers.
Each registrar has its own DNS management tools to change the name server records for a domain.
- In the registrar’s DNS management page, edit the NS records and replace the NS records with the Azure DNS name servers.
- When you delegate a domain to Azure DNS, you must use the name servers that Azure DNS provides. Use all four name servers, regardless of the name of your domain. Domain delegation doesn’t require a name server to use the same top-level domain as your domain.
- Once All Azure NS have been set and podagated, you can verify the DNS by testing with the follwoing command to verify the NS records.
For Windows verify DNS in command pronmpt
nslookup -type=SOA contoso.com
For linux/Mac verify DNS in command pronmpt
Here are the relavent DNS varables required for terraform.tfvars
file.
..
parent_dns_zone_name = "contoso.com"
parent_dns_zone_rg_name = "edgc-dns-rg"
..
Calls to Action
Learn more about Azure DNS and get the most up-to-date information at the Microsoft Docs.
Read about the Visual Studio Code Dev Container in the next section.
3 - VS Code DevContainer
Prerequisites necessary for deployment using a VS Code DevContainer
This repository includes configuration for a DevContainer, allowing for repeatable and reliable usage in VS Code or using GitHub Codespaces.
This document describes it’s use within a VS Code. For other options, see here.
Download and install Docker
Docker is required for running the DevContainer, please follow the Docker installation guidance for your platform.
Download and install VS Code
Visual Studio Code is Microsoft’s free IDE, it can be downloaded here: Visual Studio code.
Install required VS Code extensions
The “Remote - Containers” extension is required to use a DevContainer, it is not installed by default. Please follow the installation instructions for installing this extension.
Clone the respository and open in a DevContainer
Once the repository has been cloned, VS code will prompt to open the repository in a container, if this would not happen, it can be triggered by the command palete (CMD+Shift+p) and selecting the command ‘Reopen in container’. The first time, vs code automatically will build and run the container locally, attaching the IDE UI to it.
Once container has been opened, please go to the deployment page of the docs.
Open a Terminal within DevContainer
To open a Terminal within the DevContainer, press Ctrl+Shift+P
(Cmd+Shift+P
on OSX), and begin to type “Terminal”. Choose the “Terminal: Create New Terminal” option and press return.
Calls to Action
Learn more about VS Code DevContainers and get the most up-to-date information at the Visuals Studio Code Docs.
Read about using Github codespaces in the next section.
4 - GitHub Codespaces
Prerequisites necessary for deployment using GitHub Codespaces
This repository includes configuration for a DevContainer, allowing for repeatable and reliable usage in GitHub Codespaces or using VS Code DevContainer.
This document describes it’s use within a GitHub Codespaces. For other options, see here.
Prepare GutHub Orginsation
To use Codespaces, you must enable codespaces for your organization. Please follow the GitHub documentation, if Codespaces has not already been enabled.
Fork the respository and open in Codespaces
Navigate to the Reference Architecture GitHub Repository, and choose the “Fork” button from the upper right hand side of the page & choose the approperiate organisation.
Once the fork has been created - Choose the green “Code” button at the upper left of the page, select the CodeSpaces tab, select “New Codespace” and finally, select the machine type. We recommend the smallest machine type, that is the 2 core & 4GB RAM option.
GitHub will take several minutes to build the Codespace, once complete, proceed to the section below.
Open a Terminal within Codespaces
To open a Terminal within the Codespace, press Ctrl+Shift+P
(Cmd+Shift+P
on OSX), and begin to type “Terminal”. Choose the “Terminal: Create New Terminal” option and press return.
Calls to Action
Learn more about Github Codespaces and get the most up-to-date information at the GitHub Docs.
Read about manual deployment in the next section.
5 - Manual
Prerequisites necessary for manual deployment
This document describes manual deployment prerequisites. This deployment method is not recommended. For other options, see here.
If you would like to run the deployment on your PC without a container, this is a list of the tools required to complete the deployment. The exact versions of the tools used, where the version is important, can be found in the Dockerfile.
The following are needed for a deployment:
Once the tooling is installed and the code has been checked out, please proceed to the deployment page of this docs.