This the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

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.

Terraform State Managment

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.

Export Terraform State Store, Terraform Varable and Certs

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.

$ make state-export

Import Terraform State Store, Terraform Varable and Certs

Importing a zip file called import.zip in the root on the project.

$ make state-import

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

  1. Go to the Azure portal to create a DNS zone. Search for and select DNS zones.
  2. Select Create DNS zone.
  3. 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.

  1. With the DNS zone created, in the Azure portal Favorites pane, select All resources. On the All resources page, select your DNS zone.
  2. 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.

  1. In the registrar’s DNS management page, edit the NS records and replace the NS records with the Azure DNS name servers.
  2. 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.
  3. 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

dig contoso.com

Applying DNS values to terraform.tfvars

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.