Skip to content

Latest commit

 

History

History
223 lines (153 loc) · 8.41 KB

SETUP.md

File metadata and controls

223 lines (153 loc) · 8.41 KB
Raw

Setup

Prerequisities

Tools needed

Other helpful tools (not needed for setup)

Infrastucture preparation for Kuksa Cloud

In order to deploy SMAD specific Kuksa Cloud, Terraform is first used create necessary infrastucture resources into Microsoft Azure.

Authenticate to Azure

Be sure to authenticate to Azure using Azure CLI before running these Terraform scripts.

If you are running these scripts in Azure Cloud Shell you are already authenticated.

Otherwise, you can login using, for example, Azure CLI interactively:

$ az login

For other login options see Azure documentation provided by Microsoft: https://docs.microsoft.com/en-us/cli/azure/authenticate-azure-cli

Select a subscription

After you authenticate with Azure CLI, check that the selected subscription is the one you want to use:

$ az account show --output table

You can list all subscriptions you can use:

$ az account list --output table

To change your selected subscription

$ az account set -s <$SUBSCRIPTION_ID_OR_NAME>

Cloud deployment

Cloud deployment has four phases. These phases are represented as modules: 00_tfstate_storage 01_storage_rg 02_deployHono 03_container_registry Currently not in use

Initialising modules

Modules that are in use need to be initialised before use with

$ terraform init

You need to be in the same directory as the module or use

$ terraform -chdir=[MODULE NAME] init

ie.

$ terraform -chdir=00_tfstate_storage init

Important

Note that when running "$ terraform -chdir=[MODULE NAME]" default workspace is used. Do not use default workspace for modules other than 00_tfstate_storage.

Use same workspace name when deploying 01_storage_rg and 02_deployHono. See more about workspaces below.

0. Create a storage account to store shared state for Terraform

Shared state should always be preferred when working with Terraform.

In order to create one run after initializing 00_tfstate_storage module

$ terraform apply './00_tfstate_storage'

This creates:

  • Azure Resource Group (default name 'smaddis-tfstate-rg')
  • Azure Storage Account (default name 'smaddistfstatesa')
  • Azure Storage Container (default name 'tfstate')

You can customize naming in './00_tfstate_storage/variables.tf'. Check file content for naming restrictions and details.

Terraform Workspaces

It is recommended that you familiarize yourself with Terraform Workspaces concept and utilize them when using these scripts.

By using a non-default workspace you

  • Enable creation of multiple AKS clusters with the same configuration
  • Prevent accidental deletion of other clusters within the same subscription

Workspaces can be created by running

$ terraform workspace new <workspace_name>

and selected by running

$ terraform workspace select <workspace_name>

All commands can be shown with

$ terraform workspace

Workspace-specific configurations

Default workspace:

Resources are not prefixed, so only one instance of the deployment can be set up at a time. The cluster is assigned 3 nodes in the default workspace configuration.

Non-default workspace:

Resources are prefixed, so multiple instances of the deployment can be set up at a time. The cluster is assigned 2 nodes in the non-default workspace configuration.

Example:

Terraform Workspace name: testdeploy
Project name: smaddis
Name for resources: testdeploy-smaddis

Setting variables before deploying resources

via command line arguments

Run

$ terraform apply -var=use_separate_storage_rg=true

to set a variable named 'use_separate_storage_rg' to have value 'true' via command line. With this variable set as 'true', you effectively switch the K8S cluster to use a separate resource group for storage.

Terraform plan

Run $ terraform plan to see an overview of the resources that will be deployed.

Deploy the SMAD stack

Ensure that you have created proper Terraform state resources to Azure with 00_tfstate_storage, before continuing to this part.

1. Create separate resource group

Create separate resource group for storing data. Be sure to use the same workspace as when deploying the main service stack

$ terraform apply ./01_storage_rg

2. Deploy the main service stack with default parameters (see variables.tf)

$ terraform apply ./02_deployHono

If you want to use a separate resource group for storage: Deploy the main service stack with use_separate_storage_rg=true

$ terraform apply -var=use_separate_storage_rg=true ./02_deployHono

Configuration

Modifying resources created by Terraform

Resources created by Terraform should be modified via Terraform. If you modify resources created by Terraform using e.g. Kubectl, you may end up in a situation where terraform state is out of sync.

Modifying the resources is simply accomplished by editing the script and then running terraform apply.

If you change the configuration by e.g. changing the code and run terraform apply, Terraform will try to modify the resources in-place whenever possible. If in-place modification is not possible, Terraform will first destroy and then apply the modified resources. Run terraform plan to see the changes.

Using the -target flag

The -target flag can be used to apply or destroy only specific resources:

terraform apply -target=module.container_deployment.helm_release.mongodb

Note that resources that depend on the targeted resource will also be destroyed if you run terraform destroy -target.

Similarly, when running terraform apply -target, if resources that are needed by the targeted resource do not exist, Terraform cannot apply the targeted resources.

Testing that Hono works

tests/honoscript folder has a shell script that can be used to quickly verify that Hono is running properly. Refer to tests/honoscript/README.md for more detailed instructions.