
Teleport
Automatically Discover Azure Virtual Machines
- Version 15.x
- Version 14.x
- Version 13.x
- Version 12.x
- Older Versions
- Available for:
- OpenSource
- Team
- Cloud
- Enterprise
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 the Getting Started guide.
-
The
tctl
admin tool andtsh
client tool version >= 14.2.0.See Installation for details.
To check version information, run the tctl version
and tsh version
commands.
For example:
tctl versionTeleport v14.2.0 git:api/14.0.0-gd1e081e go1.21
tsh versionTeleport v14.2.0 go1.21
Proxy version: 14.2.0Proxy: teleport.example.com
-
A Teleport Team account. If you don't have an account, sign up to begin your free trial.
-
The Enterprise
tctl
admin tool andtsh
client tool, version >= 14.1.3.You can download these tools from the Cloud Downloads page.
To check version information, run the tctl version
and tsh version
commands.
For example:
tctl versionTeleport Enterprise v14.1.3 git:api/14.0.0-gd1e081e go1.21
tsh versionTeleport v14.1.3 go1.21
Proxy version: 14.1.3Proxy: teleport.example.com
-
A running Teleport Enterprise cluster. For details on how to set this up, see the Enterprise Getting Started guide.
-
The Enterprise
tctl
admin tool andtsh
client tool version >= 14.2.0.You can download these tools by visiting your Teleport account workspace.
To check version information, run the tctl version
and tsh version
commands.
For example:
tctl versionTeleport Enterprise v14.2.0 git:api/14.0.0-gd1e081e go1.21
tsh versionTeleport v14.2.0 go1.21
Proxy version: 14.2.0Proxy: teleport.example.com
-
A Teleport Enterprise Cloud account. If you don't have an account, sign up to begin a free trial of Teleport Team and upgrade to Teleport Enterprise Cloud.
-
The Enterprise
tctl
admin tool andtsh
client tool version >= 14.1.3.You can download these tools from the Cloud Downloads page.
To check version information, run the tctl version
and tsh version
commands.
For example:
tctl versionTeleport Enterprise v14.1.3 git:api/14.0.0-gd1e081e go1.21
tsh versionTeleport v14.1.3 go1.21
Proxy version: 14.1.3Proxy: teleport.example.com
- 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 runtctl
commands using your current credentials.tctl
is supported on macOS and Linux machines. For example:If you can connect to the cluster and run thetsh login --proxy=teleport.example.com --user=[email protected]tctl statusCluster teleport.example.com
Version 14.2.0
CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
tctl status
command, you can use your current credentials to run subsequenttctl
commands from your workstation. If you host your own Teleport cluster, you can also runtctl
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:

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 the following permissions to discover and enroll Azure VMs:
Microsoft.Compute/virtualMachines/read
Microsoft.Compute/virtualMachines/runCommands/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/runCommands/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:

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/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
.
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.
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
.
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.
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.
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 Application Service.
On the right side panel, click the Identity tab, then within the
Identity view, click the User assigned tab. Click +Add, then select
the teleport-azure
identity. Click Add.
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:
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.
Create a file named teleport-create-identity.json
and copy the following into
it:
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"metadata": {
"_generator": {
"name": "bicep",
"version": "0.5.6.12127",
"templateHash": "2227781763411200690"
}
},
"parameters": {
"roleName": {
"type": "string",
"defaultValue": "teleport-read-vm",
"metadata": {
"description": "Friendly name of the role definition"
}
},
"identityName": {
"type": "string",
"defaultValue": "teleport-azure",
"metadata": {
"description": "Name of the managed identity"
}
}
},
"variables": {
"roleDefName": "[guid(resourceGroup().id, string('Microsoft.Compute/virtualMachines/read'))]"
},
"resources": [
{
"type": "Microsoft.Authorization/roleDefinitions",
"apiVersion": "2022-04-01",
"name": "[variables('roleDefName')]",
"properties": {
"roleName": "[parameters('roleName')]",
"description": "A role to allow reading information about Virtual Machines, to be used for Teleport.",
"type": "customRole",
"permissions": [
{
"actions": [
"Microsoft.Compute/virtualMachines/read"
],
"notActions": []
}
],
"assignableScopes": [
"[resourceGroup().id]"
]
}
},
{
"type": "Microsoft.ManagedIdentity/userAssignedIdentities",
"name": "[parameters('identityName')]",
"apiVersion": "2018-11-30",
"location": "[resourceGroup().location]"
}
],
"outputs": {
"principalID": {
"type": "string",
"value": "[reference(resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', parameters('identityName'))).principalId]"
},
"clientID": {
"type": "string",
"value": "[reference(resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', parameters('identityName'))).clientId]"
},
"roleName": {
"type": "string",
"value": "[variables('roleDefName')]"
}
}
}
Then run the following commands to create the custom role and managed identity:
DEPLOY_OUTPUT=$(az deployment group create \--resource-group <your-resource-group> \--template-file teleport-create-identity.json)PRINCIPAL_ID=$(echo $DEPLOY_OUTPUT | jq -r '.properties.outputs.principalID.value')CLIENT_ID=$(echo $DEPLOY_OUTPUT | jq -r '.properties.outputs.principalID.value')ROLE_NAME=$(echo $DEPLOY_OUTPUT | jq -r '.properties.outputs.roleName.value')
This command requires jq
to be installed on your workstation, which you can do
via the jq
download page.
Next, create another file named teleport-assign-identity.json
and copy the
following into it:
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"metadata": {
"_generator": {
"name": "bicep",
"version": "0.5.6.12127",
"templateHash": "2227781763411200690"
}
},
"parameters": {
"identityName": {
"type": "string",
"defaultValue": "teleport-azure"
},
"principalId": {
"type": "string"
},
"roleName": {
"type": "string"
},
"vmNames": {
"type": "array"
}
},
"resources": [
{
"type": "Microsoft.Authorization/roleAssignments",
"apiVersion": "2022-04-01",
"name": "[guid(resourceGroup().id)]",
"properties": {
"roleDefinitionId": "[concat('/subscriptions/', subscription().subscriptionId, '/providers/Microsoft.Authorization/roleDefinitions/', parameters('roleName'))]",
"principalId": "[parameters('principalId')]"
}
},
{
"apiVersion": "2018-06-01",
"type": "Microsoft.Compute/virtualMachines",
"name": "[parameters('vmNames')[copyIndex('vmcopy')]]",
"location": "[resourceGroup().location]",
"identity": {
"type": "userAssigned",
"userAssignedIdentities": {
"[resourceID('Microsoft.ManagedIdentity/userAssignedIdentities/',parameters('identityName'))]": {}
}
},
"copy": {
"name": "vmcopy",
"count": "[length(parameters('vmNames'))]"
}
}
]
}
Run the following command to assign your custom role to your managed identity and assign the identity to your virtual machines:
az deployment group create \--resource-group <your-resource-group> \--template-file teleport-assign-identity.json \-- parameters principalId="$PRINCIPAL_ID" roleName="$ROLE_NAME" \vmNames='<list-of-vm-names>'
Use the value of CLIENT_ID
in Step 3.
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
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:
Select an edition, then follow the instructions for that edition to install Teleport.
Teleport Edition
- Teleport Community Edition
- Teleport Team
- Teleport Enterprise
- Teleport Enterprise Cloud
curl https://goteleport.com/static/install.sh | bash -s 14.2.0
Add the Teleport repository to your repository list:
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 cloud.
echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/cloud" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/nullsudo apt-get updatesudo apt-get install teleport-ent-updater
Source variables about OS version
source /etc/os-releaseAdd the Teleport YUM repository for cloud.
First, get the OS major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")sudo yum install -y yum-utilssudo yum-config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-yum.repo")"sudo yum install teleport-ent-updaterTip: 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 cloud.
First, get the OS major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")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/cloud/teleport-yum.repo")"Install teleport
sudo dnf install teleport-ent-updaterTip: 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 Zypper repository for cloud.
First, get the OS major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")Use Zypper to add the teleport RPM repo
sudo zypper addrepo --refresh --repo $(rpm --eval "https://zypper.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-zypper.repo")Install teleport
sudo zypper install teleport-ent-updater
OS repository channels
The following channels are available for APT, YUM, and Zypper repos. They may be used in place of
stable/v14
anywhere in the Teleport documentation.
Channel name | Description |
---|---|
stable/<major> | Receives releases for the specified major release line, i.e. v14 |
stable/cloud | Rolling channel that receives releases compatible with current Cloud version |
stable/rolling | Rolling channel that receives all published Teleport releases |
Before installing a teleport
binary with a version besides
v14, read our compatibility rules to ensure that the
binary is compatible with Teleport Cloud.
When running multiple teleport
binaries within a cluster, the following rules
apply:
- Patch and minor versions are always compatible, for example, any 8.0.1 component will work with any 8.0.3 component and any 8.1.0 component will work with any 8.3.0 component.
- Servers support clients that are 1 major version behind, but do not support
clients that are on a newer major version. For example, an 8.x.x Proxy Service
is compatible with 7.x.x resource services and 7.x.x
tsh
, but we don't guarantee that a 9.x.x resource service will work with an 8.x.x Proxy Service. This also means you must not attempt to upgrade from 6.x.x straight to 8.x.x. You must upgrade to 7.x.x first. - Proxy Services and resource services do not support Auth Services that are on
an older major version, and will fail to connect to older Auth Services by
default. This behavior can be overridden by passing
--skip-version-check
when starting Proxy Services and resource services.
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 v14. 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/v14" \| 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 v14. You'll need to update this
file for each major release of Teleport.
First, get the major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")sudo yum install -y yum-utilssudo yum-config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v14/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 Zypper repository for v14. You'll need to update this
file for each major release of Teleport.
First, get the OS major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")Use zypper to add the teleport RPM repo
sudo zypper addrepo --refresh --repo $(rpm --eval "https://zypper.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-zypper.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 v14. You'll need to update this
file for each major release of Teleport.
First, get the major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")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/v14/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
Source variables about OS version
source /etc/os-releaseAdd the Teleport Zypper repository.
First, get the OS major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")Use Zypper to add the teleport RPM repo
sudo zypper addrepo --refresh --repo $(rpm --eval "https://zypper.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v14/teleport-zypper.repo")Install teleport
sudo zypper install teleport-ent
For FedRAMP/FIPS-compliant installations, install the teleport-ent-fips
package instead:
sudo zypper 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-v14.2.0-linux-$SYSTEM_ARCH-bin.tar.gz.sha256<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-ent-v14.2.0-linux-$SYSTEM_ARCH-bin.tar.gzshasum -a 256 teleport-ent-v14.2.0-linux-$SYSTEM_ARCH-bin.tar.gzVerify that the checksums match
tar -xvf teleport-ent-v14.2.0-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-v14.2.0-linux-$SYSTEM_ARCH-fips-bin.tar.gz.sha256<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-ent-v14.2.0-linux-$SYSTEM_ARCH-fips-bin.tar.gzshasum -a 256 teleport-ent-v14.2.0-linux-$SYSTEM_ARCH-fips-bin.tar.gzVerify that the checksums match
tar -xvf teleport-ent-v14.2.0-linux-$SYSTEM_ARCH-fips-bin.tar.gzcd teleport-entsudo ./install
OS repository channels
The following channels are available for APT, YUM, and Zypper repos. They may be used in place of
stable/v14
anywhere in the Teleport documentation.
Channel name | Description |
---|---|
stable/<major> | Receives releases for the specified major release line, i.e. v14 |
stable/cloud | Rolling channel that receives releases compatible with current Cloud version |
stable/rolling | Rolling channel that receives all published Teleport releases |
Add the Teleport repository to your repository list:
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 cloud.
echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/cloud" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/nullsudo apt-get updatesudo apt-get install teleport-ent-updater
Source variables about OS version
source /etc/os-releaseAdd the Teleport YUM repository for cloud.
First, get the OS major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")sudo yum install -y yum-utilssudo yum-config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-yum.repo")"sudo yum install teleport-ent-updaterTip: 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 cloud.
First, get the OS major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")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/cloud/teleport-yum.repo")"Install teleport
sudo dnf install teleport-ent-updaterTip: 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 Zypper repository for cloud.
First, get the OS major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")Use Zypper to add the teleport RPM repo
sudo zypper addrepo --refresh --repo $(rpm --eval "https://zypper.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-zypper.repo")Install teleport
sudo zypper install teleport-ent-updater
OS repository channels
The following channels are available for APT, YUM, and Zypper repos. They may be used in place of
stable/v14
anywhere in the Teleport documentation.
Channel name | Description |
---|---|
stable/<major> | Receives releases for the specified major release line, i.e. v14 |
stable/cloud | Rolling channel that receives releases compatible with current Cloud version |
stable/rolling | Rolling channel that receives all published Teleport releases |
Before installing a teleport
binary with a version besides v14,
read our compatibility rules to ensure that the binary is compatible with
Teleport Enterprise Cloud.
When running multiple teleport
binaries within a cluster, the following rules
apply:
- Patch and minor versions are always compatible, for example, any 8.0.1 component will work with any 8.0.3 component and any 8.1.0 component will work with any 8.3.0 component.
- Servers support clients that are 1 major version behind, but do not support
clients that are on a newer major version. For example, an 8.x.x Proxy Service
is compatible with 7.x.x resource services and 7.x.x
tsh
, but we don't guarantee that a 9.x.x resource service will work with an 8.x.x Proxy Service. This also means you must not attempt to upgrade from 6.x.x straight to 8.x.x. You must upgrade to 7.x.x first. - Proxy Services and resource services do not support Auth Services that are on
an older major version, and will fail to connect to older Auth Services by
default. This behavior can be overridden by passing
--skip-version-check
when starting Proxy Services and resource services.
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:
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: ["<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 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 be edited to
change what gets executed when enrolling discovered 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/v14. See installation for more details.{{ .AutomaticUpgrades }}
: indicates whether Automatic Upgrades are enabled or disabled. Its value is eithertrue
orfalse
. See self-hosted automatic agent updates for more information.{{ .TeleportPackage }}
: the Teleport package to use. Its value is eitherteleport-ent
orteleport
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-14.2.0
echo Repository Channel: stable/v14.2.0
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.
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
- 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 .