HashiConf Our community conference is taking place in San Francisco and online October 10-12. Register now
Consul
HCS on Azure

Discover HashiCorp Consul Service on Azure Configuration

  • 13min

  • Consul

In the Deploy HashiCorp Consul Service on Azure tutorial, you deployed an HashiCorp Consul Service (HCS) instance on Azure servers. The next step before deploying clients and services is to discover nformation about your servers. In this tutorial, you will retrieve the HCS on Azure data including server connection information, Consul agent configuration, and Consul certificates.

Note

For "Beta Testing" you can also access the Consul ACL system to create tokens for the Consul client agents. This process will be updated when HCS on Azure is generally available.

This tutorial provides steps to retrieve configuration to manually configure a physical node or VM to act as Consul client for HCS. In case you want to configure an AKS cluster to run your client load, you can skip this tutorial and follow Connect an Azure Kubernetes Service (AKS) cluster to HashiCorp Consul Service on Azure instead.

Prerequisites

To successfully complete this tutorial, you need previous experience with Azure. You will also need the following:

Configure AZ tool to communicate with HCS

In this tutorial collection you will use the Azure CLI tool to retrieve information about your managed HCS on Azure.

HashiCorp provides an Azure CLI extension to interact with your HCS cluster.

Install the HashiCorp extension

You can install the extension directly from your shell using the az command:

$ az extension add \
  --source https://releases.hashicorp.com/hcs/0.4.9/hcs-0.4.9-py2.py3-none-any.whl

Are you sure you want to install this extension? (y/n): y
The installed extension 'hcs' is in preview.

Login to your Azure account

First, login into Azure using the CLI tool.

$ az login

To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code A2J3NELBP to authenticate.

The command redirects you to a web page where you can authorize your login. Use the same credentials for this login as you used to access the Azure console and create your HCS on Azure servers.

Retrieve Consul client configuration and certificates

Now that you have installed the hcs extension to your Azure CLI tool, you can retrieve Consul client configuration and certificates. We used learn-hcs-lab as Azure resource group and learnlab as managed application name in the previous tutorial. Change the arguments with the names you used during the initial configuration for your HCS instance.

$ az hcs get-config \
  --resource-group learn-hcs-lab \
  --name learnlab

Command group 'hcs' is in preview. It may be changed/removed in a future release.
Wrote Consul client configuration to consul.json
Wrote Consul CA file to ca.pem

Tip

You can abbreviate --resource-group with -g

The command will create two files:

  • consul.json - containing the Consul agent configuration for the clients.
  • ca.pem - containing certificates for the Consul HCS CA to be used with auto-encrypt enabled

Note

You are going to need these files to complete the following tutorials. Don't remove them before you complete the full tutorial collection or unless you want to clean up your test node.

Check agent configuration

If you want to check the configuration HCS created for your clients you can inspect the file consul.json.

consul.json
{
  "acl": {
    "enabled": true,
    "down_policy": "async-cache",
    "default_policy": "deny",
    "tokens": {
      "agent": ""
    }
  },
  "ca_file": "./ca.pem",
  "verify_outgoing": true,
  "datacenter": "dc1",
  "encrypt": "Lb64vf/kICB4wiW+gmnHhw==",
  "server": false,
  "log_level": "INFO",
  "ui": true,
  "retry_join": [
    "11eabd2f-dd1b-d45d-ac97-0242ac11000b.private.consul.az.hashicorp.cloud"
  ],
  "auto_encrypt": {
    "tls": true
  }
}

Fields of note from the automatic client configuration are:

  • acl - The ACL system is enabled with "default_policy": "deny". In the following section you'll learn how to bootstrap the ACL system and retrieve the administrative token.

  • encrypt - It is configured for gossip encryption and includes the key which is going to be used by the datacenter to secure gossip communication.

  • auto_encrypt - It is configured for TLS encryption and to use the auto encryption method that automatically distributes certificates to the clients.

  • retry_join - It is configured to join the servers at startup.

Note

The configuration is made to have agents joining the datacenter using an HCS private endpoint. In order for your clients to communicate with the Consul servers deployed by HCS on Azure, you must configure bi-directional peering between your VNet and the VNet created for HCS on Azure. You will do it in the next tutorial.

Bootstrap the ACL system

To start the configuration of the ACL system, retrieve the administrative token from HCS.

$ az hcs create-token \
  --resource-group learn-hcs-lab \
  --name learnlab

{
  "masterToken": {
    "accessorId": "5bc32be0-57e4-9840-4cad-209a3c0b9b82",
    "secretId": "05c75a1d-6f2a-864c-9aaa-bf49693802a4"
  }
}

Compatibility notice

The tutorial refers to the token as masterToken. The term is temporary and will likely change in the near future. We will update the tutorials and the documentation when the change happens.

Using the administrative token, identified by the value of SecretID, you can create policies and tokens to define ACLs for your client nodes.

Next steps

In this tutorial you used the Azure CLI tool to discover information about HCS on Azure and to bootstrap the ACL system in your Consul datacenter. With the Consul server agent configuration, the TLS certificate, and the ACL token you created, you can now add Consul clients to your Consul service. Continue to the Connect VM-based Applications to HashiCorp Consul Service on Azure tutorial to connect an Azure VM and install a Consul client or Connect an Azure Kubernetes Service (AKS) cluster to HashiCorp Consul Service on Azure tutorial to connect Consul clients deployed into a Kubernetes cluster.

To learn more about the Consul ACL system and how to create ACL tokens, complete the Secure Consul with ACLs tutorial.

To learn more about TLS encryption and configuration settings, read the Secure Agent Communication with TLS Encryption tutorial.

If you have any feedback for the HashiCorp Engineering or SRE team, including leaving comments and filing bugs, please contact hcs@hashicorp.com.

Previous
Next