1. Introduction

• Purpose of the Guide: This guide is designed to assist users in comprehending the necessary prerequisites and the steps involved to successfully execute the project.
• Definitions:
  • Environment: The project utilized terraform workspace for switch between environments.
• Project's folder structure:
  • docs: Project's documentation
  • env: Folder contains environment specific backend and modules configuration
  • modules: Project's modules
  • plans: Folder for storing generated plans
  • scripts: terraform init, terraform plan and terraform apply, with workspace (environment) configuration applied, implemented in both bash and powershell scripts.
• Backend: azurerm backend is configured by <ENV>.backend.tfvars file.
• Customization:
  • Modules can be customized by editing their respective <ENV>.tfvars files, where ENV is selected workspace.
  • Additional resources and configurations can be added as per project requirements.

2. Getting Started

Please note that this project is designed to provision new Azure resources, including the setup of a new Azure Kubernetes Service (AKS) cluster, among other components. It has not been tested with existing AKS clusters or pre-configured Azure resources. Users planning to deploy this project should be aware that it assumes a fresh environment for optimal compatibility and performance. Existing Azure resource configurations may require adjustments or could lead to unpredictable outcomes if used in conjunction with this project.

• Prerequisites:

  • Azure account with Contributor permission for the Azure subscription.
  • Terraform installed on your local machine.
  • Azure Storage Account for storing Terraform State.
  • You will need a domain under your control with the ability to manage its DNS settings for Kiali and Grafana dashboards. After deployment, Kiali and Grafana dashboards will be up and running.
  • Some knowledge of Terraform, Kubernetes, Helm and Istio.
  • You must be logged in with Azure CLI az login and required subscription should be selected az account set

• Initial Setup:

  • Rename default.backend.tfvars to dev.backend.tfvars and define a proper backend configuration.

  • Run terraform init to initialize the backend:

    .\scripts\init.ps1 -ENV "dev" 
    

  • Create a new workspace dev:

    terraform workspace new dev
    

    Empty dev workspace will be created and selected

  • Rename default.tfvars to dev.tfvars and configure project's modules.

  • Adjust parameters as per your infrastructure needs

  • Make sure that optional modules are disabled on this stage:

    project_modules         = {
        kiali           = false
        prometheus      = false
        grafana         = false
        letsencrypt     = false
    }
    

  • Create an empty azure.yaml file in root folder

3. Deployment with Terraform

The deployment can be divided in 3 phases:

• Deploy azure resources
• Create an A records for your domains
• Deploy services

There is couple of reasons for such dividing:

1. kubernetes_manifest terraform statements will try to connect cluster first to check if resource is already created on a plan stage, and will fail because cluster is not created yet.
2. Let's encrypt will perform ACME challenge for your domains as a part of certification issuing process, which requires your domain to point to AKS IP address. DNS record update is async and might take 5-60 minutes depending on provider.

• Phase I - Build azure resources (~5 minute): Considering everything is set in Initial setup, you can start building the Azure infrastructure

  • Plan terraform changes:

    .\scripts\plan.ps1 
    

  • Review the output

  • Apply the changes:

    .\scripts\apply.ps1 
    

• Phase II - Create A records for domains (~ 5-60 minutes):

  • Obtain clusters public IP address via Portal/AKS/Services ann ingresses blade or by running:

    kubectl get svc/istio-ingress -n istio-system
    

    EXTERNAL-IP will be the cluster's IP address

  • Create A record for kiali

  • Create A record for grafana

  • Wait couple of minutes and check that domain is resolved to cluster's IP

• Phase III - Build the services (~5-10 minutes): Assuming that above is implemented

  • Turn optional modules on:

    project_modules         = {
        kiali           = true
        prometheus      = true
        grafana         = true
        letsencrypt     = true
    }
    

  • Plan terraform changes:

    .\scripts\plan.ps1 
    

  • Review the output

  • Apply the changes:

    .\scripts\apply.ps1 
    

  Enjoy!

4. Usage

• Connecting to AKS: With newly generated kubeconfig file:

  $env:KUBECONFIG = "azure.yaml"
  

  You can also connect cluster as described in the portal.