Skip to main content
Version: 17.x (unreleased)

Automatically Discover Azure Virtual Machines

The Teleport Discovery Service can connect to Azure and automatically discover and enroll virtual machines matching configured labels. It will then execute a script on these discovered instances that will install Teleport, start it and join the cluster.

Prerequisites​

  • A running Teleport cluster version 17.0.0-dev or above. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.

  • The tctl admin tool and tsh client tool.

    Visit Installation for instructions on downloading tctl and tsh.

  • Azure subscription with virtual machines and permissions to create and attach managed identities.
  • Azure virtual machines to join the Teleport cluster, running Ubuntu/Debian/RHEL if making use of the default Teleport install script. (For other Linux distributions, you can install Teleport manually.)
  • To check that you can connect to your Teleport cluster, sign in with tsh login, then verify that you can run tctl commands using your current credentials. For example: 
    $ tsh login --proxy=teleport.example.com [email protected]
    $ tctl status
    # Cluster  teleport.example.com
    # Version  17.0.0-dev
    # CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
    If you can connect to the cluster and run the tctl status command, you can use your current credentials to run subsequent tctl commands from your workstation. If you host your own Teleport cluster, you can also run tctl commands on the computer that hosts the Teleport Auth Service for full permissions.

Step 1/6. Create an Azure invite token​

When discovering Azure virtual machines, Teleport makes use of Azure invite tokens for authenticating joining SSH Service instances.

Create a file called token.yaml:

# token.yaml
kind: token
version: v2
metadata:
  # the token name is not a secret because instances must prove that they are
  # running in your Azure subscription to use this token
  name: azure-discovery-token
  # set a long expiry time, as the default for tokens is only 30 minutes
  expires: "3000-01-01T00:00:00Z"
spec:
  # use the minimal set of roles required
  roles: [Node]

  # set the join method allowed for this token
  join_method: azure

  azure:
    allow:
    # specify the Azure subscription which Nodes may join from
    - subscription: "123456789"

Assign the subscription field to your Azure subscription ID. Add the token to the Teleport cluster with:

$ tctl create -f token.yaml

Step 2/6. Configure IAM permissions for Teleport​

The Teleport Discovery Service needs Azure IAM permissions to discover and register Azure virtual machines.

Configure an Azure service principal​

There are a couple of ways for the Teleport Discovery Service to access Azure resources:

  • The Discovery Service can run on an Azure VM with attached managed identity. This is the recommended way of deploying the Discovery Service in production since it eliminates the need to manage Azure credentials.
  • The Discovery Service can be registered as an Azure AD application (via AD's "App registrations") and configured with its credentials. This is only recommended for development and testing purposes since it requires Azure credentials to be present in the Discovery Service's environment.

Go to the Managed Identities page in your Azure portal and click Create to create a new user-assigned managed identity:

Managed identities

Pick a name and resource group for the new identity and create it:

New identity

Take note of the created identity's Client ID:

Created identity

Next, navigate to the Azure VM that will run your Discovery Service instance and add the identity you've just created to it:

VM identity

Attach this identity to all Azure VMs that will be running the Discovery Service.

Create a custom role​

Teleport requires the following permissions to discover and enroll Azure VMs:

  • Microsoft.Compute/virtualMachines/read
  • Microsoft.Compute/virtualMachines/runCommand/action
  • Microsoft.Compute/virtualMachines/runCommands/write
  • Microsoft.Compute/virtualMachines/runCommands/read
  • Microsoft.Compute/virtualMachines/runCommands/delete

Here is a sample role definition allowing Teleport to read and run commands on Azure virtual machines:

{
    "properties": {
        "roleName": "TeleportDiscovery",
        "description": "Allows Teleport to discover Azure virtual machines",
        "assignableScopes": [
            "/subscriptions/11111111-2222-3333-4444-555555555555"
        ],
        "permissions": [
            {
                "actions": [
                    "Microsoft.Compute/virtualMachines/read",
                    "Microsoft.Compute/virtualMachines/runCommand/action",
                    "Microsoft.Compute/virtualMachines/runCommands/write",
                    "Microsoft.Compute/virtualMachines/runCommands/read",
                    "Microsoft.Compute/virtualMachines/runCommands/delete"
                ],
                "notActions": [],
                "dataActions": [],
                "notDataActions": []
            }
        ]
    }
}

The assignableScopes field above includes a subscription /subscriptions/<subscription>, allowing the role to be assigned at any resource scope within that subscription or the subscription scope itself. If you want to further limit the assignableScopes, you can use a resource group /subscriptions/<subscription>/resourceGroups/<group> or a management group /providers/Microsoft.Management/managementGroups/<group> instead.

Now go to the Subscriptions page and select a subscription.

Click on Access control (IAM) in the subscription and select Add > Add custom role:

IAM custom role

In the custom role creation page, click the JSON tab and click Edit, then paste the JSON example and replace the subscription in assignableScopes with your own subscription id:

Create JSON role

Create a role assignment for the Teleport Discovery Service principal​

To grant Teleport permissions, the custom role you created must be assigned to the Teleport service principal - either the managed identity or the app registration you created earlier.

Navigate to the resource scope where you want to make the role assignment. Click Access control (IAM) and select Add > Add role assignment. Choose the custom role you created as the role and the Teleport service principal as a member.

Assign role

Azure Role Assignments

The role assignment should be at a high enough scope to allow the Teleport Discovery Service to discover all matching virtual machines. See Identify the needed scope for more information about Azure scopes and creating role assignments.

Step 3/6. Set up managed identities for discovered nodes​

Every Azure VM to be discovered must have a managed identity assigned to it with at least the Microsoft.Compute/virtualMachines/read permission.

Create a custom role​

Enter the name of your Azure resource group in the Azure Portal search box and visit the page for that resource group. On the left navigation sidebar, click the Access control (IAM) tab. In the row of buttons at the top of the Access control (IAM) panel, click Add > Add custom role.

In the Custom role name field, enter teleport-read-vm.

Create custom role

Click the Permissions tab, then within the Permissions view, click +Add permissions.

Enter Microsoft.Compute/virtualMachines/read in the search box. Click the Microsoft Compute box, then enable Read: Get Virtual Machine. Click Add.

Add virtual machine read permission

Click Review + create, then Create.

Create an Azure managed identity​

Visit the Managed Identities view in Azure Portal.

Click Create.

Under Subscription, Resource group, and Region, choose the ones that your VM belongs to.

In the Name field, enter teleport-azure.

Creating an Azure managed identity

Click Review + create, then Create.

Once creation finishes, click Go to resource. On the page for the new identity, copy the value for the Client ID so you can use it later in this guide.

Assign the teleport-read-vm role to the teleport-azure identity​

Enter the name of your Azure resource group in the Azure Portal search box and visit the page for that resource group. On the left navigation sidebar, click the Access control (IAM) tab. In the row of buttons at the top of the Access control (IAM) panel, click Add > Add role assignment.

Within the Add role assignment screen, click teleport-read-vm.

Add a role assignment

Scroll to the bottom of the screen and click Next.

Within the Members tab, in the Assign access to field, choose Managed identity. Click Select members.

On the right sidebar, find the Managed identity dropdown menu and select User-assigned managed identity. Choose the teleport-azure identity you created earlier.

Select managed identities

Click Select, then Review + assign.

Verify that your Role is teleport-read-vm, the Scope matches your chosen resource group, and the Members field includes the teleport-azure managed identity you created earlier.

Click Review + assign again.

Attach an identity to your Azure VM​

In the Virtual machines view of Azure Portal, click on the name of the VM you are using to host the Teleport Service.

On the right side panel, click the Security/Identity tab, then within the Identity view, click the User assigned tab. Click +Add, then select the teleport-azure identity. Click Add.

Add an identity to a VM

Navigate back to Identity tab in the page for your Azure VM. You should see the new identity listed in the User assigned sub-tab:

Verifying that you added the identity

IMPORTANT

As part of authentication, Teleport will be able to do anything allowed by the identity. If you use a managed identity other than the one created in this guide, we strongly recommend limiting its permissions and scope.

If the VMs to be discovered have more than one managed identity assigned to them, save the client ID of the identity you just created for step 5.

Step 4/6. Install the Teleport Discovery Service​

tip

If you plan on running the Discovery Service on a host that is already running another Teleport service (Auth or Proxy, for example), you can skip this step.

Install Teleport on the virtual machine that will run the Discovery Service:

Install Teleport on your Linux server:

  1. Assign edition to one of the following, depending on your Teleport edition:

    EditionValue
    Teleport Enterprise Cloudcloud
    Teleport Enterprise (Self-Hosted)enterprise
    Teleport Community Editionoss

  2. Get the version of Teleport to install. If you have automatic agent updates enabled in your cluster, query the latest Teleport version that is compatible with the updater:

    $ TELEPORT_DOMAIN=example.teleport.com
    $ TELEPORT_VERSION="$(curl https://$TELEPORT_DOMAIN/v1/webapi/automaticupgrades/channel/default/version | sed 's/v//')"

    Otherwise, get the version of your Teleport cluster:

    $ TELEPORT_DOMAIN=example.teleport.com
    $ TELEPORT_VERSION="$(curl https://$TELEPORT_DOMAIN/v1/webapi/ping | jq -r '.server_version')"

  3. Install Teleport on your Linux server:

    $ curl https://cdn.teleport.dev/install-v15.4.11.sh | bash -s ${TELEPORT_VERSION} edition

    The installation script detects the package manager on your Linux server and uses it to install Teleport binaries. To customize your installation, learn about the Teleport package repositories in the installation guide.

Step 5/6. Configure Teleport to discover Azure instances​

If you are running the Discovery Service on its own host, the service requires a valid invite token to connect to the cluster. Generate one by running the following command against your Teleport Auth Service:

$ tctl tokens add --type=discovery

Save the generated token in /tmp/token on the virtual machine that will run the Discovery Service.

In order to enable Azure instance discovery the discovery_service.azure section of teleport.yaml must include at least one entry:

warning

Discovery Service exposes a configuration parameter - discovery_service.discovery_group - that allows you to group discovered resources into different sets. This parameter is used to prevent Discovery Agents watching different sets of cloud resources from colliding against each other and deleting resources created by another services.

When running multiple Discovery Services, you must ensure that each service is configured with the same discovery_group value if they are watching the same cloud resources or a different value if they are watching different cloud resources.

It is possible to run a mix of configurations in the same Teleport cluster meaning that some Discovery Services can be configured to watch the same cloud resources while others watch different resources. As an example, a 4-agent high availability configuration analyzing data from two different cloud accounts would run with the following configuration.

  • 2 Discovery Services configured with discovery_group: "prod" polling data from Production account.
  • 2 Discovery Services configured with discovery_group: "staging" polling data from Staging account.
version: v3
teleport:
  join_params:
    token_name: "/tmp/token"
    method: token
  proxy_server: "teleport.example.com:443"
auth_service:
  enabled: off
proxy_service:
  enabled: off
ssh_service:
  enabled: off
discovery_service:
  enabled: "yes"
  discovery_group: "azure-prod"
  azure:
    - types: ["vm"]
      subscriptions: ["<subscription>"]
      resource_groups: ["<resource-group>"]
      regions: ["<region>"]
      tags:
        "env": "prod" # Match virtual machines where tag:env=prod
      install:
        azure:
          # Optional: If the VMs to discover have more than one managed
          # identity assigned to them, set the client ID here to the client
          # ID of the identity created in step 3.
          client_id: "<client-id>"
  • Edit the teleport.auth_servers key to match your Auth Service or Proxy Service's URI and port.
  • Adjust the keys under discovery_service.azure to match your Azure environment, specifically the regions and tags you want to associate with the Discovery Service.

Step 6/6. [Optional] Customize the default installer script​

To customize an installer, your user must have a role that allows list, create, read and update verbs on the installer resource.

Create a file called installer-manager.yaml with the following content:

kind: role
version: v5
metadata:
  name: installer-manager
spec:
  allow:
    rules:
      - resources: [installer]
        verbs: [list, create, read, update]

Create the role:

$ tctl create -f installer-manager.yaml
# role 'installer-manager' has been created

The preset editor role has the required permissions by default.

To customize the default installer script, execute the following command on your workstation:

$ tctl edit installer/default-installer

After making the desired changes to the default installer, save and close the file in your text editor.

Multiple installer resources can exist and be specified in the azure.install.script_name section of a discovery_service.azure list item in teleport.yaml:

discovery_service:
  # ...
  azure:
    - types: ["vm"]
      tags:
       - "env": "prod"
      install: # optional section when default-installer is used.
        script_name: "default-installer"
    - types: ["vm"]
      tags:
       - "env": "devel"
      install:
        script_name: "devel-installer"

The installer resource has the following templating options:

  • {{ .MajorVersion }}: the major version of Teleport to use when installing from the repository.
  • {{ .PublicProxyAddr }}: the public address of the Teleport Proxy Service to connect to.
  • {{ .RepoChannel }}: Optional package repository (apt/yum) channel name. Has format <channel>/<version> e.g. stable/v17. See installation for more details.
  • {{ .AutomaticUpgrades }}: indicates whether Automatic Updates are enabled or disabled. Its value is either true or false. See Automatic Agent Updates for more information.
  • {{ .TeleportPackage }}: the Teleport package to use. Its value is either teleport-ent or teleport depending on whether the cluster is enterprise or not.

These can be used as follows:

kind: installer
metadata:
  name: default-installer
spec:
  script: |
    echo {{ .PublicProxyAddr }}
    echo Teleport-{{ .MajorVersion }}
    echo Repository Channel: {{ .RepoChannel }}
version: v1

Which, when retrieved for installation, will evaluate to a script with the following contents:

echo teleport.example.com
echo Teleport-17.0.0-dev
echo Repository Channel: stable/v17.0.0-dev

The default installer will take the following actions:

  • Add an official Teleport repository to supported Linux distributions.
  • Install Teleport via apt or yum.
  • Generate the Teleport config file and write it to /etc/teleport.yaml.
  • Enable and start the Teleport service.

If client_id is set in the Discovery Service config, custom installers will also have the {{ .AzureClientID }} templating option.

Troubleshooting​

No credential providers error​

If you see the error DefaultAzureCredential: failed to acquire a token. in Discovery Service logs then Teleport is not detecting the required credentials to connect to the Azure SDK. Check whether the credentials have been applied in the machine running the Teleport Discovery Service and restart the Teleport Discovery Service. Refer to Azure SDK Authorization for more information.

Teleport reports no error but VM does not join​

Check your Discovery Service config and make sure that the VM you want to discover matches. In debug mode, Teleport will log the Subscription IDs and names of VMs it discovers.

The Azure run command API does not report the output of commands, so Teleport has no way of knowing if a command succeeded or failed. Run command logs can be found on the targeted VM at /var/log/azure/run-command-handler/handler.log.

Next steps​