![Fork me on GitHub](/docs/_next/image/?url=%2Fdocs%2F_next%2Fstatic%2Fmedia%2Fforkme.b9234619.webp&w=256&q=75)
Teleport
Machine ID with tctl
- Version 17.x
- Version 16.x
- Version 15.x
- Version 14.x
- Older Versions
tctl
is the Teleport cluster management CLI tool. Whilst it usually uses the
credentials from the locally logged in user, it is also possible to use
Machine ID credentials. This allows tctl
to be leveraged as part of a custom
automation workflow deployed in a non-interactive environment (e.g CI/CD).
In this guide, you will configure tbot
to produce credentials for tctl
, and
then use tctl
to deploy Teleport roles defined in files.
Prerequisites
-
A running Teleport cluster version 16.2.1 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 andtsh
client tool.Visit Installation for instructions on downloading
tctl
andtsh
.
- 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. 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 16.2.1
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. tbot
must already be installed and configured on the machine that will usetctl
. For more information, see the deployment guides.
Step 1/3. Configure RBAC
First, Teleport must be configured to allow the credentials produced by tbot
to modify the Teleport configuration. This is done by creating a role that
grants the necessary permissions and then assigning this role to a Bot.
It's important to grant as few privileges as possible in order to limit the blast radius of an attack, so in this example we grant only the ability to create and update roles.
Create a file called role.yaml
with the following content:
kind: role
version: v6
metadata:
name: example-role
spec:
allow:
rules:
- resources:
# Specify the names of resources you wish to manage with tctl.
# For this guide, we will only manage roles.
- role
verbs:
- create
- read
- update
- delete
- list
Replace example-role
with a descriptive name related to your use case.
Use tctl create -f ./role.yaml
to create the role.
Now, use tctl bots update
to add the role to the Bot. Replace example
with the name of the Bot you created in the deployment guide and example-role
with the name of the role you just created:
$ tctl bots update example --add-roles example-role
Step 2/3. Configure tbot
output
Now, tbot
needs to be configured with an output that will produce the
credentials needed by tctl
. As tctl
will be accessing the Teleport API, the
correct output type to use is identity
.
For this guide, the directory
destination will be used. This will write these
credentials to a specified directory on disk. Ensure that this directory can
be written to by the Linux user that tbot
runs as, and that it can be read by
the Linux user that tctl
will run as.
Modify your tbot
configuration to add an identity
output:
outputs:
- type: identity
destination:
type: directory
# For this guide, /opt/machine-id is used as the destination directory.
# You may wish to customize this. Multiple outputs cannot share the same
# destination.
path: /opt/machine-id
If operating tbot
as a background service, restart it. If running tbot
in
one-shot mode, it must be executed before you attempt to execute the Terraform
plan later.
You should now see an identity
file under /opt/machine-id
. This contains
the private key and signed certificates needed by tctl
to
authenticate with the Teleport Auth Server.
Step 3/3. Use tctl
with the identity output
As an example, tctl
will be used to apply a directory of YAML files that
define Teleport roles. If these were stored in version control (e.g., git
) and
this were executed on change, this would form the basis for managing Teleport
roles in a GitOps style.
The example role will not be useful within the context of your Teleport cluster and should be modified once you have completed this guide.
Create a directory called roles/
and within it create example.yaml
:
kind: role
version: v6
metadata:
name: tctl-test
spec:
# This role does nothing as it is an example role.
allow: {}
To configure tctl
to use the identity file, the -i
flag is used. As the
identity file does not specify the address of Teleport, --auth-server
must
also be specified with the address of your Teleport Proxy or Teleport Auth
Server.
Run tctl
, replacing example.teleport.sh:443
with the address of your
Teleport Proxy or Auth Server and /opt/machine-id/identity
with the path to
the generated identity file if you have modified this:
tctl --auth-server example.teleport.sh:443 -i /opt/machine-id/identity create -f roles/*.yaml
Check your Teleport cluster, ensuring the role has been created.
tctl get role/tctl-test
Next steps
- Explore the
tctl
reference to discover alltctl
can do. - Read the configuration reference to explore
all the available
tbot
configuration options.