
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. For details on how to set this up, see one of our Getting Started guides.
-
The
tctl
admin tool andtsh
client tool version >= 13.0.3.tctl versionTeleport v13.0.3 go1.20
tsh versionTeleport v13.0.3 go1.20
See Installation for details.
-
A running Teleport Enterprise cluster. For details on how to set this up, see our Enterprise Getting Started guide.
-
The Enterprise
tctl
admin tool andtsh
client tool version >= 13.0.3, which you can download by visiting your Teleport account.tctl versionTeleport Enterprise v13.0.3 go1.20
tsh versionTeleport v13.0.3 go1.20
Please use the latest version of Teleport Enterprise documentation.
- 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.)
- Make sure you can connect to Teleport. Log in to your cluster using
tsh
, then usetctl
remotely:tsh login --proxy=teleport.example.com [email protected]tctl statusCluster teleport.example.com
Version 13.0.3
CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
You can run subsequent
tctl
commands in this guide on your local machine.For full privileges, you can also run
tctl
commands on your Auth Service host.
Step 1/5. 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/5. 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:

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

Take note of the created identity's Client ID:

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

Attach this identity to all Azure VMs that will be running the Discovery Service.
Registering the Discovery Service as Azure AD application is suitable for test and development scenarios, or if your Discovery Service does not run on an Azure VM. For production scenarios prefer to use the managed identity approach.
Go the the App registrations page of your Azure Active Directory and click on New registration:

Pick a name (e.g. DiscoveryService) and register a new application. Once the app has been created, take note of its Application (client) ID and click on Add a certificate or secret:

Create a new client secret that the Discovery Service agent will use to authenticate with the Azure API:

The Teleport Discovery Service uses Azure SDK's default credential provider chain to look for credentials. Refer to Azure SDK Authorization to pick a method suitable for your use-case. For example, to use environment-based authentication with a client secret, the Discovery Service should have the following environment variables set:
export AZURE_TENANT_ID=
export AZURE_CLIENT_ID=
export AZURE_CLIENT_SECRET=
Create a custom role
Teleport requires Microsoft.Compute/virtualMachines/read
permissions for discovery and
Microsoft.Compute/virtualMachines/runCommand/action
permissions for installation.
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"
],
"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:

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 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.

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/5. Install the Teleport Discovery Service
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:
Use the appropriate commands for your environment to install your package.
Teleport Edition
Download Teleport's PGP public key
sudo curl https://apt.releases.teleport.dev/gpg \-o /usr/share/keyrings/teleport-archive-keyring.ascSource variables about OS version
source /etc/os-releaseAdd the Teleport APT repository for v13. You'll need to update this
file for each major release of Teleport.
echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/v13" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/nullsudo apt-get updatesudo apt-get install teleport
Source variables about OS version
source /etc/os-releaseAdd the Teleport YUM repository for v13. You'll need to update this
file for each major release of Teleport.
sudo yum-config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v13/teleport.repo")"sudo yum install teleportTip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)
echo "Defaults secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path
Source variables about OS version
source /etc/os-releaseAdd the Teleport YUM repository for v13. You'll need to update this
file for each major release of Teleport.
Use the dnf config manager plugin to add the teleport RPM repo
sudo dnf config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v13/teleport.repo")"Install teleport
sudo dnf install teleportTip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)
echo "Defaults secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path
In the example commands below, update $SYSTEM_ARCH
with the appropriate
value (amd64
, arm64
, or arm
). All example commands using this variable
will update after one is filled out.
curl https://get.gravitational.com/teleport-v13.0.3-linux-$SYSTEM_ARCH-bin.tar.gz.sha256<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-v13.0.3-linux-$SYSTEM_ARCH-bin.tar.gzshasum -a 256 teleport-v13.0.3-linux-$SYSTEM_ARCH-bin.tar.gzVerify that the checksums match
tar -xvf teleport-v13.0.3-linux-$SYSTEM_ARCH-bin.tar.gzcd teleportsudo ./install
Download Teleport's PGP public key
sudo curl https://apt.releases.teleport.dev/gpg \-o /usr/share/keyrings/teleport-archive-keyring.ascSource variables about OS version
source /etc/os-releaseAdd the Teleport APT repository for v13. You'll need to update this
file for each major release of Teleport.
echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/v13" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/nullsudo apt-get updatesudo apt-get install teleport-ent
For FedRAMP/FIPS-compliant installations, install the teleport-ent-fips
package instead:
sudo apt-get install teleport-ent-fips
Source variables about OS version
source /etc/os-releaseAdd the Teleport YUM repository for v13. You'll need to update this
file for each major release of Teleport.
sudo yum-config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v13/teleport.repo")"sudo yum install teleport-entTip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)
echo "Defaults secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path
For FedRAMP/FIPS-compliant installations, install the teleport-ent-fips
package instead:
sudo yum install teleport-ent-fips
Source variables about OS version
source /etc/os-releaseAdd the Teleport YUM repository for v13. You'll need to update this
file for each major release of Teleport.
Use the dnf config manager plugin to add the teleport RPM repo
sudo dnf config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v13/teleport.repo")"Install teleport
sudo dnf install teleport-entTip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)
echo "Defaults secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path
For FedRAMP/FIPS-compliant installations, install the teleport-ent-fips
package instead:
sudo dnf install teleport-ent-fips
In the example commands below, update $SYSTEM_ARCH
with the appropriate
value (amd64
, arm64
, or arm
). All example commands using this variable
will update after one is filled out.
curl https://get.gravitational.com/teleport-ent-v13.0.3-linux-$SYSTEM_ARCH-bin.tar.gz.sha256<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-ent-v13.0.3-linux-$SYSTEM_ARCH-bin.tar.gzshasum -a 256 teleport-ent-v13.0.3-linux-$SYSTEM_ARCH-bin.tar.gzVerify that the checksums match
tar -xvf teleport-ent-v13.0.3-linux-$SYSTEM_ARCH-bin.tar.gzcd teleport-entsudo ./install
For FedRAMP/FIPS-compliant installations of Teleport Enterprise, package URLs will be slightly different:
curl https://get.gravitational.com/teleport-ent-v13.0.3-linux-$SYSTEM_ARCH-fips-bin.tar.gz.sha256<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-ent-v13.0.3-linux-$SYSTEM_ARCH-fips-bin.tar.gzshasum -a 256 teleport-ent-v13.0.3-linux-$SYSTEM_ARCH-fips-bin.tar.gzVerify that the checksums match
tar -xvf teleport-ent-v13.0.3-linux-$SYSTEM_ARCH-fips-bin.tar.gzcd teleport-entsudo ./install
Please use the latest version of Teleport Enterprise documentation.
Step 4/5. 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:
version: v2
teleport:
join_params:
token_name: "/tmp/token"
method: token
auth_servers:
- "teleport.example.com:3080"
auth_service:
enabled: off
proxy_service:
enabled: off
ssh_service:
enabled: off
discovery_service:
enabled: "yes"
azure:
- types: ["vm"]
subscriptions: []
resource_groups: []
regions: []
tags:
"env": "prod" # Match virtual machines where tag:env=prod
- 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 5/5. [Optional] Customize the default installer script
To customize the default installer script, execute the following command on your workstation:
tctl get installer/default-installer > teleport-default-installer.yaml
The resulting teleport-default-installer.yaml
can the be edited to
change what gets executed when enrolling discovered Azure instances.
After making the desired changes to the default installer, the resource can be updated by executing:
tctl create -f teleport-default-installer.yaml
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/v13. See installation for more details.
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 by the Systems Manager document will evaluate to a script with the following contents:
echo teleport.example.com
echo Teleport-13.0.3
echo Repository Channel: stable/v13.0.3
The default installer will take the following actions:
- Add an official Teleport repository to supported Linux distributions.
- Install Teleport via
apt
oryum
. - Generate the Teleport config file and write it to
/etc/teleport.yaml
. - Enable and start the Teleport service.
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.
Next steps
- Read Joining Nodes via Azure Managed Identity for more information on Azure tokens.
- Full documentation on Azure discovery configuration can be found through the config file reference documentation.
- The complete default installer can be found with the Teleport source .