Skip to content

setup.md

Latest commit

 

History

History
228 lines (148 loc) · 8.85 KB

setup.md

File metadata and controls

228 lines (148 loc) · 8.85 KB

Setup

The following instructions will setup up a development environment for building and running the samples, as well as creating and testing your own Azure IoT Operations edge applications.

Contents:

Setup the environment

The following development environment setup options utilize k3d to simplify Kubernetes cluster creation. Codespaces provides the most streamlined experience and can get the development environment up and running in a couple of minutes.

Follow the steps in one of the sections below to get your development environment up and running:

Option 1 - Codespaces

Caution

We are currently experiencing container corruption with Azure IoT Operations deployed in a codespace, so we don't recommend this path until we have resolved the issue with the GitHub team.

  1. Create a codespace from the Azure IoT Operations SDKs repository by clicking the following button:

    Open in GitHub Codespaces

  2. Once the codespace is created, you will have a container with the developer tools and a local k3s cluster pre-installed.

Option 2 - Linux

  1. Install Ubuntu

  2. Install Docker Engine

  3. Clone the Azure IoT Operations SDKs repository:

    git clone https://github.com/Azure/iot-operations-sdks

Option 3 - Linux devcontainer on Windows

Warning

The latest WSL release doesn't support Azure IoT Operations. You will need to install WSL v2.3.14 as outlined in the steps below.

  1. Install WSL v2.3.14 (contains kernel v6.6)

  2. Install Docker Desktop for Windows with WSL 2 backend, and confirm it's running the v6.6 kernel:

    wsl -d docker-desktop -e uname -a

    output:

    Linux docker-desktop 6.6.36.3-microsoft-standard-WSL2 ...

  3. Install VS Code and the Dev Containers extension

  4. Launch VS Code, and clone the repository in a container:

    F1 > Dev Containers: Clone Repository in Container Volume...

  5. When prompted, enter the Azure IoT Operations SDKs URL and select the main branch:

    https://github.com/azure/iot-operations-sdks

Tip

To reconnect to the container in VSCode, choose F1 > Dev Containers: Attach to Running Container... and then select the container name created previously.

Option 4 - Windows Subsystem for Linux

Warning

The latest WSL release doesn't support Azure IoT Operations. You will need to install WSL v2.3.14 as outlined in the steps below.

  1. Install WSL v2.3.14 (contains kernel v6.6)

  2. Install Docker Desktop for Windows with WSL 2 backend, and confirm it's running the v6.6 kernel:

    wsl -d docker-desktop -e uname -a

    output:

    Linux docker-desktop 6.6.36.3-microsoft-standard-WSL2 ...

  3. Clone the Azure IoT Operations SDKs repository:

    git clone https://github.com/Azure/iot-operations-sdks

Install Azure IoT Operations

Azure IoT Operations will be installed to the development cluster, and then the configuration will be altered to provide additional off-cluster access methods to streamline development:

  1. Launch a shell, and change to the root directory of the Azure IoT Operations SDKs repository.

  2. If required, run the following to install required dependencies and initialize the cluster:

    sudo ./tools/deployment/initialize-cluster.sh

  3. Follow the Azure IoT Operations documentation to connect Azure Arc and deploy Azure IoT Operations.

  4. Check that Azure IoT Operations is successfully installed and Resolve any errors before continuing:

    az iot ops check

    Expected output:

    ╭─────── Check Summary ───────╮
│ 13 check(s) succeeded.      │
│ 0 check(s) raised warnings. │
│ 0 check(s) raised errors.   │
│ 4 check(s) were skipped.    │
╰─────────────────────────────╯

  5. Run the configure-aio script to configure Azure IoT Operations for development:

    ./tools/deployment/configure-aio.sh

Shell configuration

The samples within this repository read configuration from environment variables. We have provided a .env file in the repository root that exports the variables used by the samples to connect to the MQTT Broker.

source <REPOSITORY ROOT>/.env

Testing the installation

To test the setup is working correctly, use mosquitto_pub to connect to the MQTT broker to validate the x509 certs, SAT and trust bundle.

  1. Export the .session directory:

    export SESSION=$(git rev-parse --show-toplevel)/.session

  2. Test no TLS, no auth:

    mosquitto_pub -L mqtt://localhost:1883/hello -m world --debug

  3. Test TLS with x509 auth:

    mosquitto_pub -L mqtts://localhost:8883/hello -m world --cafile $SESSION/broker-ca.crt --cert $SESSION/client.crt --key $SESSION/client.key --debug

  4. Test TLS with SAT auth:

    mosquitto_pub -L mqtts://localhost:8884/hello -m world --cafile $SESSION/broker-ca.crt -D CONNECT authentication-method K8S-SAT -D CONNECT authentication-data $(cat $SESSION/token.txt) --debug

Configuration summary

MQTT broker configuration

With the installation complete, the cluster will contain the following MQTT broker definitions:

Component Type Name Description
Broker default The MQTT broker
BrokerListener default Provides cluster access to the MQTT Broker
BrokerListener default-external Provides off-cluster access to the MQTT Broker
BrokerAuthentication default SAT authentication definition
BrokerAuthentication default-x509 An x509 authentication definition

MQTT broker access

The MQTT broker can be accessed both on-cluster and off-cluster using the connection information below. Refer to Connection Settings for information on which environment variables to use when configuration your application.

Note

The hostname when accessing the MQTT broker off-cluster may differ from localhost depending on your setup.

Hostname Authentication TLS On cluster port Off cluster port
aio-broker SAT ✅ 18883 -
localhost None ❌ 1883 1883
localhost x509 ✅ 8883 8883
localhost SAT ✅ 8884 8884

Development artifacts

As part of the deployment script, the following files are created in the local environment, to facilitate connection and authentication to the MQTT broker. These files are located in the .session directory, found at the repository root.

File Description
broker-ca.crt The MQTT broker trust bundle required to validate the MQTT broker on ports 8883 and 8884
token.txt A Service authentication token (SAT) for authenticating with the MQTT broker on 8884
client.crt A x509 client certificate for authenticating with the MQTT broker on port 8883
client.key A x509 client private key for authenticating with the MQTT broker on port 8883

Next Steps

The development environment is now setup! Refer to the language documentation for further instructions on setting up the SDK: