gravitational/teleport
1
0
Fork 0
mirror of https://github.com/gravitational/teleport.git synced 2026-10-12 02:15:01 +00:00
Code Issues Packages Projects Releases Wiki Activity

MWI Docs: Rename final reference to "Machine ID" (#61320)

Browse Source 
* Remove "Machine ID" terminology from Access and Deployment guides

* Fix up last references to "Machien ID" terminology

* Fix mispelling
This commit is contained in:
Noah Stride
2025-11-13 14:25:08 +00:00
committed by GitHub
parent d20ce29867
commit 6089b082cf
33 changed files with 230 additions and 207 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/pages/machine-workload-identity/access-guides/ansible-awx.mdx
+14 -14
View File
@@ -11,9 +11,9 @@ tags:
Ansible AWX, formerly known as Ansible Tower, is an interface on top of Ansible
that can be used to run and coordinate Ansible workflows. These workflows
connect to remote hosts via SSH which requires a form of authentication. Machine
ID can provide short-lived certificates to Ansible jobs run via AWX that allow
the job to connect to SSH nodes enrolled in Teleport in a secure and auditable
manner.
& Workload Identity can provide short-lived certificates to Ansible jobs run via
AWX that allow the job to connect to SSH nodes enrolled in Teleport in a secure
and auditable manner.
This guide applies both to open-source Ansible AWX as well as Red Hat's
commercial Ansible Automation Platform automation controller, which is
@@ -21,11 +21,11 @@ built on top of the open-source Ansible AWX engine.
## How it works
In this guide, you will configure a container group in Ansible AWX to run
Machine ID's `tbot` client as a sidecar, which will provide credentials
and a high-performance multiplexing proxy to your Ansible AWX jobs. You'll then
configure Ansible to use these credentials to connect to SSH nodes through the
Teleport Proxy Service.
In this guide, you will configure a container group in Ansible AWX to run the
Machine & Workload Identity agent, `tbot`, as a sidecar, which will provide
credentials and a high-performance multiplexing proxy to your Ansible AWX jobs.
You'll then configure Ansible to use these credentials to connect to SSH nodes
through the Teleport Proxy Service.
## Prerequisites
@@ -40,7 +40,7 @@ Teleport Proxy Service.
- While not required, you may wish to read our guides on [Deploying tbot
in Kubernetes](../deployment/kubernetes.mdx) or [Deploying tbot in
Kubernetes with OIDC](../deployment/kubernetes-oidc.mdx) to learn more about
how to deploy Machine ID in Kubernetes, which is the foundation of the steps
how to deploy `tbot` on Kubernetes, which is the foundation of the steps
we'll be taking in this guide.
- (!docs/pages/includes/tctl.mdx!)
@@ -149,7 +149,7 @@ $ tctl create -f awx-bot-resources.yaml
Next, we'll prepare a `ConfigMap` resource in the Kubernetes cluster in which
your AWX jobs will run. This `ConfigMap` will contain the configuration for
Machine ID's `tbot` client, in particular:
Machine & Workload Identity's agent, `tbot`, in particular:
- The address of your Teleport cluster
- How to join your Teleport cluster, using the join token you created in the
previous step
@@ -159,7 +159,7 @@ Machine ID's `tbot` client, in particular:
`ssh-multiplexer` to provide efficient access to SSH nodes
The only Kubernetes resource we'll need to configure
manually is a `ConfigMap` for Machine ID's `tbot` client.
manually is a `ConfigMap` for `tbot`.
Write the following to `configmap-tbot-awx-config.yaml`:
```yaml
@@ -267,8 +267,8 @@ guide, and what alternatives you might consider when implementing this yourself:
Next, we'll need to create a new container instance group that spawns jobs in
Kubernetes (or OpenShift). We'll additionally customize the pod specification to
run Machine ID's `tbot` client as a sidecar alongside the `awx-ee` worker
container to provide SSH credentials to your jobs.
run `tbot` as a sidecar alongside the `awx-ee` worker container to provide SSH
credentials to your jobs.
In the AWX web UI, navigate to Administration, Instance Groups, select the "Add"
button, and select "Add container group". Enter any name you like, and set the
@@ -501,7 +501,7 @@ We've configured the `tbot` client to provide its own multiplexer (via the
## Next Steps
- Learn more about [deploying Machine ID in Kubernetes](../deployment/kubernetes.mdx)
- Learn more about [deploying `tbot` on Kubernetes](../deployment/kubernetes.mdx)
- Read the [configuration reference](../../reference/machine-workload-identity/configuration.mdx) to explore
all the available configuration options.
docs/pages/machine-workload-identity/access-guides/ansible.mdx
+7 -7
View File
@@ -11,13 +11,13 @@ tags:
{/* lint disable page-structure remark-lint */}
Ansible is a common tool for managing fleets of Linux hosts via SSH. In order to
connect to the hosts, it requires a form of authentication. Machine ID can be
used to provide short-lived certificates to Ansible that allow it to connect
to SSH nodes enrolled in Teleport in a secure and auditable manner.
connect to the hosts, it requires a form of authentication. Machine & Workload
Identity can be used to provide short-lived certificates to Ansible that allow
it to connect to SSH nodes enrolled in Teleport in a secure and auditable manner.
In this guide, you will configure the Machine ID agent, `tbot`, to produce
credentials and an OpenSSH configuration, and then configure Ansible to use
these to connect to your SSH nodes through the Teleport Proxy Service.
In this guide, you will configure the Machine & Workload Identity agent, `tbot`,
to produce credentials and an OpenSSH configuration, and then configure Ansible
to use these to connect to your SSH nodes through the Teleport Proxy Service.
## Prerequisites
@@ -148,7 +148,7 @@ $ cd ansible
Create a file called `ansible.cfg`. We will configure Ansible
to run the OpenSSH client with the configuration file generated
by Machine ID, `/opt/machine-id/ssh_config`. Note, `example.com` here is the
by `tbot`, `/opt/machine-id/ssh_config`. Note, `example.com` here is the
name of your Teleport cluster.
```code
docs/pages/machine-workload-identity/access-guides/applications.mdx
+7 -5
View File
@@ -10,11 +10,13 @@ tags:
{/* lint disable page-structure remark-lint */}
Teleport protects and controls access to HTTP and TCP applications. Machine ID
can be used to grant machines secure, short-lived access to these applications.
Teleport protects and controls access to HTTP and TCP applications. Machine &
Workload Identity can be used to grant machines secure, short-lived access to
these applications.
In this guide, you will configure `tbot` to produce credentials that can be
used to access an application enrolled in your Teleport cluster.
In this guide, you will configure Machine & Workload Identity's agent, `tbot`,
to produce credentials that can be used to access an application enrolled in
your Teleport cluster.
## Prerequisites
@@ -145,7 +147,7 @@ one-shot mode, it must be executed before you attempt to use the credentials.
</TabItem>
</Tabs>
## Step 3/3. Connect to your web application with the Machine ID identity
## Step 3/3. Connect to your web application
<Tabs>
<TabItem label="application-tunnel service">
docs/pages/machine-workload-identity/access-guides/argocd.mdx
+5 -4
View File
@@ -14,9 +14,9 @@ Argo CD is a declarative, GitOps continuous delivery tool for Kubernetes. It
runs in Kubernetes and can deploy applications to the same cluster or to other
"external" clusters.
In this guide, you will configure the Machine ID agent, `tbot`, to manage Argo
CD's cluster credentials, enabling it to securely deploy applications using
Teleport.
In this guide, you will configure the Machine & Workload Identity agent, `tbot`,
to manage Argo CD's cluster credentials, enabling it to securely deploy
applications using Teleport.
## How it works
@@ -51,7 +51,8 @@ can then use to access Teleport-protected Kubernetes clusters.
## Step 1/4. Configure Teleport and Kubernetes RBAC
First, we need to configure the RBAC for both Teleport and Kubernetes in order
to grant the Machine ID agent the correct level of access.
to grant the Machine & Workload Identity agent, `tbot`, the correct level of
access.
When forwarding requests to the Kubernetes API on behalf of a bot, the Teleport
Proxy attaches the groups configured (using `kubernetes_groups`) in the bot's
docs/pages/machine-workload-identity/access-guides/databases.mdx
+2 -2
View File
@@ -10,13 +10,13 @@ tags:
{/* lint disable page-structure remark-lint */}
Teleport protects and controls access to databases. Machine ID
Teleport protects and controls access to databases. Machine & Workload Identity
can be used to grant machines secure, short-lived access to these databases.
In this guide, you will configure `tbot` to produce credentials that can be
used to access a database configured in Teleport.
![Accessing Teleport-protected databases with Machine ID](../../../img/machine-id/machine-id-database-access.svg)
![Accessing Teleport-protected databases with Machine & Workload Identity](../../../img/machine-id/machine-id-database-access.svg)
## Prerequisites
docs/pages/machine-workload-identity/access-guides/kubernetes.mdx
+3 -3
View File
@@ -11,8 +11,8 @@ tags:
{/* lint disable page-structure remark-lint */}
Teleport protects and controls access to Kubernetes
clusters. Machine ID can be used to grant machines secure, short-lived
access to these clusters.
clusters. Machine & Workload Identity can be used to grant machines secure,
short-lived access to these clusters.
In this guide, you will configure `tbot` to produce credentials that can be
used to access a Kubernetes cluster enrolled with your Teleport cluster.
@@ -165,7 +165,7 @@ as registered in Teleport and adjust `/opt/machine-id` if you wish.
If operating `tbot` as a background service, restart it. If running `tbot` in
one-shot mode, it must be executed before you attempt to use the credentials.
## Step 3/3. Connect to your Kubernetes cluster with the Machine ID identity
## Step 3/3. Connect to your Kubernetes cluster
Once `tbot` has been run with the new service configured, a file called
`kubeconfig.yaml` should have been generated in the destination directory
docs/pages/machine-workload-identity/access-guides/ssh.mdx
+6 -4
View File
@@ -10,8 +10,9 @@ tags:
{/* lint disable page-structure remark-lint */}
Teleport protects and controls SSH access to servers. Machine ID
can be used to grant machines secure, short-lived access to these servers.
Teleport protects and controls SSH access to servers. Machine & Workload
Identity can be used to grant machines secure, short-lived access to these
servers.
In this guide, you will configure `tbot` to produce credentials that can be
used to access a Linux server enrolled in Teleport. The guide
@@ -168,8 +169,9 @@ If you wish to integrate with Ansible, check out the
[Ansible-specific guide](./ansible.mdx).
If your tool is not compatible with `ssh_config`, it may still be possible to
configure it to use the credentials produced by Machine ID. It must support
SSH client certificates and either ProxyCommand or ProxyJump functionality.
configure it to use the credentials produced by Machine & Workload Identity. It
must support SSH client certificates and either ProxyCommand or ProxyJump
functionality.
## Next steps
docs/pages/machine-workload-identity/access-guides/tctl.mdx
+3 -2
View File
@@ -12,8 +12,9 @@ tags:
`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).
credentials issued by Machine & Workload Identity. 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.
docs/pages/machine-workload-identity/deployment/aws.mdx
+12 -10
View File
@@ -1,6 +1,6 @@
---
title: Deploying tbot on AWS
description: How to install and configure Machine ID on an AWS EC2 instance
description: How to install and configure the Machine & Workload Identity agent, `tbot`, on an AWS EC2 instance
sidebar_label: AWS EC2
tags:
- how-to
@@ -9,16 +9,18 @@ tags:
- aws
---
This guide shows you how to deploy `tbot` on Amazon Web Services and connect it to your Teleport cluster.
This guide shows you how to deploy Machine & Workload Identity's agent, `tbot`,
on an AWS EC2 instance and connect it to your Teleport cluster.
## How it works
On AWS, virtual machines can be assigned an IAM role, which they can assume in
order to request a signed document that includes information about the machine.
The Teleport `iam` join method instructs the Machine ID bot to request this
signed document from AWS using the assigned identity and send it to the Teleport
Auth Service for verification. This allows the bot to join the cluster without
the exchange of a long-lived secret.
The Teleport `iam` join method instructs the Machine & Workload Identity bot to
request this signed document from AWS using the assigned identity and send it to
the Teleport Auth Service for verification. This allows the bot to join the
cluster without the exchange of a long-lived secret.
While this guide focuses on deploying `tbot` on an EC2 instance, it is also
possible to use the `iam` join method with workloads running on an EKS
@@ -26,7 +28,7 @@ Kubernetes cluster. To do so, you must configure [IAM Roles for Service Accounts
(IRSA)](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html)
for the cluster and the Kubernetes service account that will be used by the
`tbot` pod. See the [Kubernetes platform guide](kubernetes.mdx) for further
guidance on deploying Machine ID as a workload on Kubernetes.
guidance on deploying `tbot` as a workload on Kubernetes.
## Prerequisites
@@ -36,15 +38,15 @@ guidance on deploying Machine ID as a workload on Kubernetes.
- An AWS IAM role that you wish to grant access to your Teleport cluster. This
role must be granted `sts:GetCallerIdentity`. In this guide, this role will
be named `teleport-bot-role`.
- An AWS EC2 virtual machine that you wish to install Machine ID onto configured
- An AWS EC2 virtual machine that you wish to install `tbot` onto configured
with the IAM role attached.
## Step 1/5. Install `tbot`
**This step is completed on the AWS EC2 instance.**
First, `tbot` needs to be installed on the VM that you wish to use Machine ID
on.
First, `tbot` needs to be installed on the VM that you wish to use Machine &
Workload Identity on.
Download and install the appropriate Teleport package for your platform:
docs/pages/machine-workload-identity/deployment/azure-devops.mdx
+9 -8
View File
@@ -1,6 +1,6 @@
---
title: Deploying tbot on Azure DevOps
description: How to install and configure Machine ID on Azure DevOps.
description: How to install and configure the Machine & Workload Identity agent, `tbot`, on Azure DevOps.
sidebar_label: Azure DevOps
tags:
- how-to
@@ -9,16 +9,17 @@ tags:
- azure
---
In this guide, you will configure Machine ID's agent, `tbot`, to run within a
Azure DevOps pipeline run. The bot will be configured to use the `azure_devops`
delegated joining method to eliminate the need for long-lived secrets.
In this guide, you will configure Machine & Workload Identity's agent, `tbot`,
to run within a Azure DevOps pipeline run. The bot will be configured to use
the `azure_devops` delegated joining method to eliminate the need for long-lived
secrets.
## How it works
The `azure_devops` join method is a secure way for Machine ID bots to
authenticate with the Teleport Auth Service without using any shared secrets.
Instead, it makes use of an OpenID Connect token that Azure DevOps provides via
an API to the pipeline job.
The `azure_devops` join method is a secure way for Machine & Workload Identity
bots to authenticate with the Teleport Auth Service without using any shared
secrets. Instead, it makes use of an OpenID Connect token that Azure DevOps
provides via an API to the pipeline job.
This token is sent to the Teleport Auth Service, and assuming it has been
configured to trust Azure DevOps's identity provider and all identity assertions
docs/pages/machine-workload-identity/deployment/azure.mdx
+9 -9
View File
@@ -1,6 +1,6 @@
---
title: Deploying tbot on Azure
description: How to install and configure Machine ID on an Azure VM
description: How to install and configure the Machine & Workload Identity agent, `tbot`, on an Azure VM
sidebar_label: Azure VM
tags:
- how-to
@@ -9,10 +9,10 @@ tags:
- azure
---
In this guide, you will install Machine ID's agent, `tbot` on an Azure VM. The
bot will be configured to use the `azure` delegated joining method to
authenticate to your Teleport cluster. This eliminates the need for long-lived
secrets.
In this guide, you will install Machine & Workload Identity's agent, `tbot`, on
an Azure VM. The bot will be configured to use the `azure` delegated joining
method to authenticate to your Teleport cluster. This eliminates the need for
long-lived secrets.
## How it works
@@ -34,15 +34,15 @@ occur without the use of a long-lived secret.
- An Azure managed identity with a role granting the
`Microsoft.Compute/virtualMachines/read` permission. You will need to know
the UID of this identity.
- An Azure VM you wish to install Machine ID onto with the managed identity
configured as a user-assigned managed identity.
- An Azure VM you wish to install Machine & Workload Identity onto with the
managed identity configured as a user-assigned managed identity.
## Step 1/5. Install `tbot`
**This step is completed on the Azure VM.**
First, `tbot` needs to be installed on the VM that you wish to use Machine ID
on.
First, `tbot` needs to be installed on the VM that you wish to use Machine &
Workload Identity on.
Download and install the appropriate Teleport package for your platform:
docs/pages/machine-workload-identity/deployment/bitbucket.mdx
+12 -10
View File
@@ -1,6 +1,6 @@
---
title: Deploying tbot on Bitbucket Pipelines
description: How to install and configure Machine ID on Bitbucket Pipelines
description: How to install and configure the Machine & Workload Identity agent, `tbot`, on Bitbucket Pipelines
sidebar_label: Bitbucket Pipelines
tags:
- how-to
@@ -8,16 +8,17 @@ tags:
- infrastructure-identity
---
In this guide, you will configure Machine ID's agent, `tbot`, to run within a
Bitbucket Pipelines workflow. The bot will be configured to use the `bitbucket`
delegated joining method to eliminate the need for long-lived secrets.
In this guide, you will configure Machine & Workload Identity's agent, `tbot`,
to run within a Bitbucket Pipelines workflow. The bot will be configured to use
the `bitbucket` delegated joining method to eliminate the need for long-lived
secrets.
## How it works
The `bitbucket` join method is a secure way for Machine ID bots to authenticate
with the Teleport Auth Service without using any shared secrets. Instead, it
makes use of an OpenID Connect token that Bitbucket Pipelines injects into the
job environment.
The `bitbucket` join method is a secure way for Machine & Workload Identity bots
to authenticate with the Teleport Auth Service without using any shared secrets.
Instead, it makes use of an OpenID Connect token that Bitbucket Pipelines
injects into the job environment.
This token is sent to the Teleport Auth Service, and assuming it has been
configured to trust Bitbucket's identity provider and all identity assertions
@@ -43,7 +44,7 @@ From this page, note the following values:
- Workspace UUID, including the braces (<Var name="workspace-uuid" />)
- Repository UUID, including the braces (<Var name="repository-uuid" />)
## Step 2/4. Create the Machine ID bot
## Step 2/4. Create a Bot
(!docs/pages/includes/machine-id/create-a-bot.mdx!)
@@ -84,7 +85,8 @@ Let's go over the token resource's fields in more detail:
access to. Note that this value will need to be used in other parts of the
configuration later.
- `spec.roles` defines which roles that this token will grant access to. The
value of `[Bot]` states that this token grants access to a Machine ID bot.
value of `[Bot]` states that this token grants access to a Machine & Workload
Identity bot.
- `spec.join_method` defines the join method the token is applicable for. Since
this guide only focuses on Bitbucket Pipelines, you will set this to to
`bitbucket`.
docs/pages/machine-workload-identity/deployment/circleci.mdx
+8 -7
View File
@@ -1,6 +1,6 @@
---
title: Deploying tbot on CircleCI
description: How to install and configure Machine ID on CircleCI
description: How to install and configure the Machine & Workload Identity agent, `tbot`, on CircleCI
sidebar_label: CircleCI
tags:
- ci-cd
@@ -11,9 +11,9 @@ tags:
{/* lint disable page-structure remark-lint */}
In this guide, you will configure Machine ID's agent, `tbot`, to run within a
CircleCI workflow. The bot will be configured to use the `circleci` delegated
joining method to eliminate the need for long-lived secrets.
In this guide, you will configure Machine & Workload Identity's agent, `tbot`,
to run within a CircleCI workflow. The bot will be configured to use the
`circleci` delegated joining method to eliminate the need for long-lived secrets.
## Prerequisites
@@ -71,7 +71,7 @@ Note this value down and substitute <Var name="context-id" /> in configuration e
with it.
## Step 2/5. Create the Machine ID bot
## Step 2/5. Create a Bot
(!docs/pages/includes/machine-id/create-a-bot.mdx!)
@@ -111,7 +111,8 @@ example is set to the year `2100`.
access to. Note that this value will need to be used in other parts of the
configuration later.
- `spec.roles` defines which roles that this token will grant access to. The
value of `[Bot]` states that this token grants access to a Machine ID bot.
value of `[Bot]` states that this token grants access to a Machine & Workload
Identity bot.
- `spec.join_method` defines the join method the token is applicable for. Since
this guide only focuses on CircleCI, you will set this to to `circleci`.
- `spec.circleci.allow` is used to set rules for what CircleCI runs will be able
@@ -176,7 +177,7 @@ jobs:
command: |
curl "https://<Var name="example.teleport.sh"/>:443/scripts/install.sh" | sudo bash
- run:
name: "Run Machine ID"
name: "Run Machine & Workload Identity"
command: |
export TELEPORT_ANONYMOUS_TELEMETRY=1
tbot start -c tbot.yaml
docs/pages/machine-workload-identity/deployment/deployment.mdx
+16 -16
View File
@@ -7,26 +7,25 @@ tags:
- infrastructure-identity
---
The first step to set up Machine ID is to deploy the `tbot` binary and join a
Machine ID bot to your Teleport cluster. You can run the `tbot` binary on a
number of platforms, from AWS and GitHub Actions to a generic Linux server or
Kubernetes cluster. This guide shows you how to deploy Machine ID on your
infrastructure.
The first step to set up Machine & Workload Identity is to deploy the `tbot`
agent and join it as a Bot to your Teleport cluster. You can run the `tbot`
binary on a number of platforms, from AWS and GitHub Actions to a generic Linux
server or Kubernetes cluster.
## Choosing a deployment method
There are two considerations to make when determining how to deploy Machine ID on
your infrastructure.
There are two considerations to make when determining how to deploy the `tbot`
agent on your infrastructure.
### Your infrastructure
The `tbot` binary runs as a container or on a Linux virtual machine. If you run
The `tbot` agent runs as a container or on a Linux virtual machine. If you run
`tbot` on GitHub Actions, you can use one of the ready-made [Teleport GitHub
Actions workflows](https://github.com/teleport-actions).
### Join method
Machine ID joins your Teleport cluster by using one of the following
The `tbot` agent joins your Teleport cluster by using one of the following
authentication methods:
- **Platform-signed document:** The platform that hosts `tbot`, such as a
@@ -34,19 +33,19 @@ authentication methods:
that Teleport can verify using the platform's certificate authority. This is
the recommended approach because it avoids the use of shared secrets.
- **Static join token:** Your Teleport client tool generates a string and stores
it on the Teleport Auth Service. Machine ID provides this string when it first
it on the Teleport Auth Service. `tbot` provides this string when it first
connects to your Teleport cluster, demonstrating to the Auth Service that it
belongs in the cluster. From then on, Machine ID authenticates to your
Teleport cluster with a renewable certificate.
belongs in the cluster. From then on, `tbot` authenticates to your Teleport
cluster with a renewable certificate.
## Deployment guides
The guides in this section show you how to deploy Machine ID and join it to your cluster.
Choose a guide based on the platform where you intend to run Machine ID.
The guides in this section show you how to deploy the Machine & Workload
Identity agent, `tbot`, and join it to your cluster.
If a specific guide does not exist for your platform, the [Linux
guide](linux.mdx) is compatible with most platforms. For
custom approaches, you can also read the [Machine ID Reference](../../reference/machine-workload-identity/machine-workload-identity.mdx)
custom approaches, you can also read the [Machine & Workload Identity Reference](../../reference/machine-workload-identity/machine-workload-identity.mdx)
and [Architecture](../../reference/architecture/machine-id-architecture.mdx) to plan your deployment.
<TileGrid
@@ -121,7 +120,8 @@ and [Architecture](../../reference/architecture/machine-id-architecture.mdx) to
### CI/CD
Read the following guides for how to deploy Machine ID on a continuous integration and continuous deployment platform.
Read the following guides for how to deploy `tbot` on a continuous integration
and continuous deployment platform.
<TileGrid
tiles={[
docs/pages/machine-workload-identity/deployment/gcp.mdx
+14 -14
View File
@@ -1,6 +1,6 @@
---
title: Deploying tbot on GCP
description: How to install and configure Machine ID on a GCP VM
description: How to install and configure the Machine & Workload Identity agent, `tbot`, on a GCP VM
sidebar_label: GCP VM
tags:
- how-to
@@ -9,26 +9,26 @@ tags:
- google-cloud
---
This guide explains how to deploy Machine ID on Google Cloud Platform (GCP) by
running the `tbot` binary and joining it to your Teleport cluster.
This guide explains how to deploy the Machine & Workload Identity agent, `tbot`,
on a Google Cloud Platform GCE instance and connect it to your Teleport cluster.
## How it works
On GCP, virtual machines can be assigned a service account. These machines can
then request a signed JSON web token from GCP, which allows third parties to
verify information about them, including their service accounts, using the GCP
public key. The Teleport `gcp` join method instructs a Machine ID bot to use
this service account JWT to prove its identity to the Teleport Auth Service and
join your Teleport cluster without using long-lived secrets.
public key. The Teleport `gcp` join method instructs `tbot` to use this service
account JWT to prove its identity to the Teleport Auth Service and join your
Teleport cluster without using long-lived secrets.
Whilst the guide on this page focuses explicitly on deploying Machine ID on a
GCP Virtual Machine, it is also possible to use the `gcp` join method with
workloads running on Google Kubernetes Engine. To do so, you must configure
Whilst the guide on this page focuses explicitly on deploying `tbot` on a GCP
Virtual Machine, it is also possible to use the `gcp` join method with workloads
running on Google Kubernetes Engine. To do so, you must configure
[GCP Workload
Identity](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity)
for the cluster and the Kubernetes service account that will be used by the
`tbot` pod. See the [Kubernetes platform guide](kubernetes.mdx) for further
guidance on deploying Machine ID as a workload on Kubernetes.
guidance on deploying `tbot` as a workload on Kubernetes.
## Prerequisites
@@ -37,15 +37,15 @@ guidance on deploying Machine ID as a workload on Kubernetes.
- (!docs/pages/includes/tctl.mdx!)
- A GCP service account you wish to grant access to your Teleport cluster that
is not the GCP compute default service account.
- A GCP Compute Engine VM that you wish to install Machine ID onto that has
been configured with the GCP service account.
- A GCP Compute Engine VM that you wish to install `tbot` onto that has been
configured with the GCP service account.
## Step 1/5. Install `tbot`
**This step is completed on the GCP VM.**
First, `tbot` needs to be installed on the VM that you wish to use Machine ID
on.
First, `tbot` needs to be installed on the VM that you wish to use Machine &
Workload Identity on.
Download and install the appropriate Teleport package for your platform:
docs/pages/machine-workload-identity/deployment/github-actions.mdx
+12 -11
View File
@@ -1,6 +1,6 @@
---
title: Deploying tbot on GitHub Actions
description: How to install and configure Machine ID on GitHub Actions
description: How to install and configure the Machine & Workload Identity agent, `tbot`, on GitHub Actions
sidebar_label: GitHub Actions
tags:
- ci-cd
@@ -12,8 +12,9 @@ tags:
{/* lint disable page-structure remark-lint */}
GitHub Actions is a popular CI/CD platform that works as a part of the larger
GitHub ecosystem. Teleport Machine ID allows GitHub Actions to securely interact
with Teleport protected resources without the need for long-lived credentials.
GitHub ecosystem. Teleport Machine & Workload Identity allows GitHub Actions to
securely interact with Teleport protected resources without the need for
long-lived credentials.
Teleport supports secure joining on both GitHub-hosted and self-hosted GitHub
Actions runners as well as GitHub Enterprise Server.
@@ -186,8 +187,8 @@ on:
jobs:
demo:
permissions:
# The "id-token: write" permission is required or Machine ID will not be
# able to authenticate with the cluster.
# The "id-token: write" permission is required or tbot will not be able to
# authenticate with the cluster.
id-token: write
contents: read
# The name of the workflow, and the Linux distro to be used to perform the
@@ -203,7 +204,7 @@ jobs:
version: auto
# Replace with the address of your Teleport Proxy Service.
proxy: example.teleport.sh:443
- name: Fetch credentials using Machine ID
- name: Fetch credentials using Machine & Workload Identity
id: auth
uses: teleport-actions/auth@v2
with:
@@ -254,7 +255,7 @@ to complete, and will resemble the following once successful.
Expand the **List nodes** step of the action, and the output will
list all nodes in the cluster, from the perspective of the
Machine ID bot using the command `tsh ls`.
Machine & Workload Identity bot using the command `tsh ls`.
### Example: `teleport-actions/auth-k8s`
@@ -306,8 +307,8 @@ on:
jobs:
demo:
permissions:
# The "id-token: write" permission is required or Machine ID will not be
# able to authenticate with the cluster.
# The "id-token: write" permission is required or tbot will not be able to
# authenticate with the cluster.
id-token: write
contents: read
name: example
@@ -402,8 +403,8 @@ on:
jobs:
demo:
permissions:
# The "id-token: write" permission is required or Machine ID will not be
# able to authenticate with the cluster.
# The "id-token: write" permission is required or tbot will not be able to
# authenticate with the cluster.
id-token: write
contents: read
# The name of the workflow, and the Linux distro to be used to perform the
docs/pages/machine-workload-identity/deployment/gitlab.mdx
+7 -6
View File
@@ -1,6 +1,6 @@
---
title: Deploying tbot on GitLab CI
description: How to install and configure Machine ID on GitLab CI
description: How to install and configure the Machine & Workload Identity agent, `tbot`, on GitLab CI
sidebar_label: GitLab CI
tags:
- ci-cd
@@ -11,12 +11,13 @@ tags:
{/* lint disable page-structure remark-lint */}
In this guide, you will use Teleport Machine ID to allow a GitLab pipeline to
securely connect to a Teleport SSH node without the need for long-lived secrets.
In this guide, you will use Teleport Machine & Workload Identity to allow a
GitLab pipeline to securely connect to a Teleport SSH node without the need for
long-lived secrets.
Machine ID for GitLab works with GitLab's cloud-hosted option and with
self-hosted GitLab installations. **The minimum supported GitLab version is
15.7**.
Machine & Workload Identity for GitLab works with GitLab's cloud-hosted option
and with self-hosted GitLab installations. **The minimum supported GitLab
version is 15.7**.
This mitigates the risk of long-lived secrets such as passwords or SSH private
keys being exfiltrated from your GitLab organization and provides many of
docs/pages/machine-workload-identity/deployment/jenkins.mdx
+25 -21
View File
@@ -1,6 +1,6 @@
---
title: Deploying tbot on Jenkins
description: How to install and configure Machine ID on Jenkins
description: How to install and configure the Machine & Workload Identity agent, `tbot`, on Jenkins
sidebar_label: Jenkins
tags:
- ci-cd
@@ -15,7 +15,8 @@ Jenkins is an open source automation server that is frequently used to build
Continuous Integration and Continuous Delivery (CI/CD) pipelines.
In this guide, we will demonstrate how to migrate existing Jenkins pipelines to
utilize Machine ID with minimal changes.
utilize Machine & Workload Identity to connect to infrastructure protected by
Teleport.
## Prerequisites
@@ -30,9 +31,10 @@ You will need the following tools to use Teleport with Jenkins.
## Architecture
Before we begin, it should be noted that Jenkins is a tool that is notoriously
difficult to secure. Machine ID is one part of securing your infrastructure,
but it alone is not sufficient. Below we will provide some basic guidance which
can help improve the security posture of your Jenkins installation.
difficult to secure. Machine & Workload Identity is one part of securing your
infrastructure, but it alone is not sufficient. Below we will provide some basic
guidance which can help improve the security posture of your Jenkins
installation.
### Single-host deployments
@@ -53,19 +55,20 @@ to a subset of your CI/CD infrastructure instead of all of your infrastructure.
### Best practices
We strongly encourage the use of the second deployment model whenever possible,
with ephemeral hosts and IAM joining when possible. When using Machine ID with
this model, create and run Machine ID bots per-host and pin particular
pipelines to a worker. This will allow you to give each pipeline the minimal
scope for server access, reduce the blast radius if one pipeline is
with ephemeral hosts and IAM joining when possible. When using Machine &
Workload Identity with this model, create and run separate bots per-host and pin
particular pipelines to a worker. This will allow you to give each pipeline the
minimal scope for server access, reduce the blast radius if one pipeline is
compromised, and allow you to remotely audit and lock pipelines if you detect
malicious behavior.
![Jenkins Deployments](../../../img/machine-id/jenkins.png)
## Step 1/2 Configure and start Machine ID
## Step 1/2 Configure and start `tbot`
First, determine if you would like to create a new role for Machine ID or use
an existing role. You can run `tctl get roles` to examine your existing roles.
First, determine if you would like to create a new role or use an existing role
for your Jenkins workflow. You can run `tctl get roles` to examine your existing
roles.
In the example below, create a file called `api-workers.yaml` with the content below
to create a new role called `api-workers` that will allow you to log in to Nodes
@@ -104,12 +107,13 @@ $ tctl bots add jenkins --roles=api-workers
</Tabs>
Machine ID allows you to use Linux Access Control Lists (ACLs) to control
access to certificates on disk. You will use this to limit the access Jenkins
has to the short-lived certificates Machine ID issues.
The Machine & Workload Identity agent, `tbot`, allows you to use Linux Access
Control Lists (ACLs) to control access to certificates on disk. You will use
this to limit the access Jenkins has to the short-lived certificates `tbot`
issues.
In the example that follows, you will create a Linux user called `teleport` to
run Machine ID but short-lived certificates will be written to disk as the
run `tbot` but short-lived certificates will be written to disk as the
Linux user `jenkins`.
```code
@@ -134,9 +138,9 @@ $ sudo tbot init \
(!docs/pages/includes/machine-id/machine-id-init-bot-data.mdx!)
Next, you need to start Machine ID in the background of each Jenkins worker.
Next, you need to start `tbot` in the background of each Jenkins worker.
First create a configuration file for Machine ID at `/etc/tbot.yaml`.
First create a configuration file for `tbot` at `/etc/tbot.yaml`.
```yaml
version: v2
@@ -164,9 +168,9 @@ services:
## Step 2/2. Update and run Jenkins pipelines
Using Machine ID within a Jenkins pipeline is now a one-line change. For
example, if you want to run the `hostname` command on a remote host, add the
following to your Jenkins pipeline.
Using the credentials produced by `tbot` within a Jenkins pipeline is now a
one-line change. For example, if you want to run the `hostname` command on a
remote host, add the following to your Jenkins pipeline.
```
steps {
docs/pages/machine-workload-identity/deployment/kubernetes-oidc.mdx
+6 -5
View File
@@ -1,6 +1,6 @@
---
title: Deploying tbot on Kubernetes with OIDC
description: How to install and configure Machine ID on Kubernetes with OIDC
description: How to install and configure the Machine & Workload Identity agent, `tbot`, on Kubernetes with OIDC
sidebar_label: Kubernetes (OIDC)
tags:
- how-to
@@ -8,10 +8,11 @@ tags:
- infrastructure-identity
---
This guide shows you how to deploy the Machine ID daemon `tbot` on a Kubernetes
cluster that supports OIDC. The Kubernetes OIDC join method is a good fit for
use inside Kubernetes clusters on a cloud platform that can be configured to
provide a public OpenID Connect (OIDC) endpoint, including EKS, AKS, and GKE.
This guide shows you how to deploy the Machine & Workload Identity agent,
`tbot`, on a Kubernetes cluster that supports OIDC. The Kubernetes OIDC join
method is a good fit for use inside Kubernetes clusters on a cloud platform that
can be configured to provide a public OpenID Connect (OIDC) endpoint, including
EKS, AKS, and GKE.
## How it works
docs/pages/machine-workload-identity/deployment/kubernetes.mdx
+4 -3
View File
@@ -1,6 +1,6 @@
---
title: Deploying tbot on Kubernetes
description: How to install and configure Machine ID on Kubernetes with Static JWKS Keys
description: How to install and configure the Machine & Workload Identity agent, `tbot`, on Kubernetes with Static JWKS Keys
sidebar_label: Kubernetes (Static JWKS)
tags:
- how-to
@@ -8,8 +8,9 @@ tags:
- infrastructure-identity
---
This guide shows you how to deploy the Machine ID daemon `tbot`, on a Kubernetes
cluster using a static set of JWKS keys.
This guide shows you how to deploy the Machine & Workload Identity agent,
`tbot`, on a Kubernetes cluster and use a static reference to the cluster's
Service Account issuer keys for authentication.
## How it works
docs/pages/machine-workload-identity/deployment/linux-tpm.mdx
+11 -11
View File
@@ -1,6 +1,6 @@
---
title: Deploying tbot on Linux (TPM)
description: How to install and configure Machine ID on a Linux host and use a TPM 2.0 for authentication
description: How to install and configure the Machine & Workload Identity agent, `tbot`, on a Linux host and use a TPM 2.0 for authentication
sidebar_label: Linux (TPM)
tags:
- how-to
@@ -8,9 +8,9 @@ tags:
- infrastructure-identity
---
This page explains how to deploy Machine ID on a Linux host, and use the
secure identify of the onboard TPM 2.0 chip for authenticating with the
Teleport cluster.
This page explains how to deploy Machine & Workload Identity's agent, `tbot`, on
a Linux host, and use the secure identity of the onboard TPM 2.0 chip for
authenticating with the Teleport cluster.
The `tpm` join method requires a valid Teleport Enterprise license to be
installed on the cluster's Auth Service.
@@ -24,17 +24,17 @@ installed on the cluster's Auth Service.
(!docs/pages/includes/edition-prereqs-tabs.mdx!)
- (!docs/pages/includes/tctl.mdx!)
- A Linux host that you wish to install Machine ID onto, with a TPM2.0
- A Linux host that you wish to install `tbot` onto with a TPM2.0
installed.
- A Linux user on that host that you wish Machine ID to run as. In the guide,
- A Linux user on that host that you wish `tbot` to run as. In the guide,
we will use `teleport` for this.
## Step 1/5. Install `tbot`
**This step is completed on the Linux host.**
First, `tbot` needs to be installed on the VM that you wish to use Machine ID
on.
First, `tbot` needs to be installed on the VM that you wish to use Machine
& Workload Identity on.
Download the appropriate Teleport package for your platform:
@@ -63,7 +63,7 @@ With the Bot created, we now need to create a token. The token will be used by
### Determining the EKPub Hash or EKCert Serial for your TPM
First, you need to determine the characteristics of the TPM on the host that
you wish to use Machine ID on. These characteristics will then be used within
you wish to install `tbot` on. These characteristics will then be used within
the allow rules of the join token to grant access to this specific host.
On the machine, run `tbot tpm identify`:
@@ -103,8 +103,8 @@ metadata:
# name identifies the token. Try to ensure that this is descriptive.
name: my-bot-token
spec:
# For Machine ID and TPM joining, roles will always be "Bot" and
# join_method will always be "tpm".
# For MWI joining via TPM, roles will always be "Bot" and join_method will
# always be "tpm".
roles: [Bot]
join_method: tpm
docs/pages/machine-workload-identity/deployment/linux.mdx
+8 -7
View File
@@ -1,6 +1,6 @@
---
title: Deploying tbot on Linux
description: How to install and configure Machine ID on a Linux host
description: How to install and configure the Machine & Workload Identity agent, `tbot`, on a Linux host
sidebar_label: Linux
tags:
- how-to
@@ -8,7 +8,8 @@ tags:
- infrastructure-identity
---
This page explains how to deploy Machine ID on a Linux host.
This page explains how to deploy the Machine & Workload Identity agent, `tbot`,
on a Linux host.
## How it works
@@ -27,16 +28,16 @@ is not possible to use the same token multiple times.
(!docs/pages/includes/edition-prereqs-tabs.mdx!)
- (!docs/pages/includes/tctl.mdx!)
- A Linux host that you wish to install Machine ID onto.
- A Linux user on that host that you wish Machine ID to run as. In the guide,
we will use `teleport` for this.
- A Linux host that you wish to install `tbot` onto.
- A Linux user on that host that you wish `tbot` to run as. In the guide, we
will use `teleport` for this.
## Step 1/4. Install `tbot`
**This step is completed on the Linux host.**
First, `tbot` needs to be installed on the VM that you wish to use Machine ID
on.
First, `tbot` needs to be installed on the VM that you wish to use Machine &
Workload Identity on.
Install Teleport as appropriate for your platform:
docs/pages/machine-workload-identity/introduction.mdx
+6 -7
View File
@@ -91,7 +91,7 @@ Read this section to understand the high-level architecture of a Machine &
Workload Identity setup. For a more in-depth overview, check out the [architecture
page](../reference/architecture/machine-id-architecture.mdx).
![Machine ID architecture](../../img/machine-id/architecture-diagram.png)
![Machine & Workload Identity architecture](../../img/machine-id/architecture-diagram.png)
### Bots
@@ -157,10 +157,10 @@ For a quickstart non-production introduction to Machine & Workload Identity, rea
Production-ready guidance on deploying Machine & Workload Identity is broken out into two parts:
- [Deploying Machine ID](./deployment/deployment.mdx): How to install and configure
Machine ID for a specific platform.
- [Access your Infrastructure with Machine ID](./access-guides/access-guides.mdx): How to use Machine & Workload Identity to access
Teleport and Teleport resources.
- [Deploying `tbot`](./deployment/deployment.mdx): How to install and configure
`tbot` on specific platforms.
- [Access your Infrastructure using `tbot`](./access-guides/access-guides.mdx):
How to use `tbot` to access Infrastructure through Teleport.
Reference information:
@@ -174,5 +174,4 @@ them.
Workload Identity works.
- [Reference](../reference/machine-workload-identity/machine-workload-identity.mdx): Complete documentation of available
configuration options.
- [Manifesto](./manifesto.mdx): Our vision for Machine Identity and the
direction Machine ID and Workload ID are heading in.
- [Manifesto](./manifesto.mdx): Our vision for Machine & Workload Identity.
docs/pages/machine-workload-identity/manifesto.mdx
+2 -2
View File
@@ -1,6 +1,6 @@
---
title: Machine & Workload Identity Manifesto
description: A manifesto for Machine Identity
description: A manifesto for Machine & Workload Identity
sidebar_label: Manifesto
tags:
- conceptual
@@ -53,5 +53,5 @@ Together, these three pillars create a strong foundation for AI, automations and
other workloads running together in a predictable way that is secure and
possible to reason about and maintain.
Teleport Workload & Machine Identity is on a mission to make this vision a
Teleport Machine & Workload Identity is on a mission to make this vision a
reality.
docs/pages/machine-workload-identity/use-cases/mwi-ci-cd.mdx
+2 -2
View File
@@ -86,7 +86,7 @@ API endpoints and full audit visibility.
### Further reading
- [Architecture](../../reference/architecture/machine-id-architecture.mdx): A technical deep-dive into how Machine ID
works.
- [Architecture](../../reference/architecture/machine-id-architecture.mdx): A technical deep-dive into how Machine &
Workload Identity works.
- [Reference](../../reference/machine-workload-identity/machine-workload-identity.mdx): Complete documentation of available
configuration options.
docs/pages/machine-workload-identity/workload-identity/aws-roles-anywhere.mdx
+4 -3
View File
@@ -29,11 +29,12 @@ AWS APIs in a few ways:
- Workload Identity works with any AWS client, including the command-line tool
but also
their SDKs.
- Using the Teleport Application Service to access AWS does not work with Machine ID
and therefore cannot be used when a machine needs to authenticate with AWS.
- Using the Teleport Application Service to access AWS does not work with
Machine & Workload Identity and therefore cannot be used when a machine needs
to authenticate with AWS.
Whilst this guide is primarily aimed at allowing a machine to access AWS,
the `tsh svid issue` command can be used in place of Machine ID to allow a human
the `tsh svid issue` command can be used in place of `tbot` to allow a human
user to authenticate with using AWS Roles Anywhere.
## OIDC Federation vs Roles Anywhere
docs/pages/machine-workload-identity/workload-identity/azure-federated-credentials.mdx
+2 -2
View File
@@ -33,8 +33,8 @@ protect Azure APIs in a few ways:
- Workload Identity works with any Azure client, including the command-line tool
but also their SDKs.
- Using the Teleport Application Service to access Azure does not work with
Machine ID and therefore cannot be used when a machine needs to authenticate
with Azure.
Machine & Workload Identity and therefore cannot be used when a machine needs
to authenticate with Azure.
## Prerequisites
docs/pages/machine-workload-identity/workload-identity/best-practices.mdx
+2 -1
View File
@@ -146,7 +146,8 @@ can then configure Postgres to map this common name to `myuser`.
There are certain circumstances where you may wish to use Teleport Workload ID
to authenticate a workload's access to a database.
This differs from using Machine ID with the Database Service in a few ways:
This differs from using Machine & Workload Identity with the Database Service in
a few ways:
- The connection is made directly from the workload to the database, rather
than through Teleport's Proxy Service and Database Service.
docs/pages/machine-workload-identity/workload-identity/gcp-workload-identity-federation-jwt.mdx
+3 -2
View File
@@ -32,8 +32,9 @@ GCP APIs in a few ways:
recorded in Teleport's audit log.
- Workload Identity works with any GCP client, including the command-line tool
but also their SDKs.
- Using the Teleport Application Service to access GCP does not work with Machine ID
and therefore cannot be used when a machine needs to authenticate with AWS.
- Using the Teleport Application Service to access GCP does not work with
Machine & Workload Identity and therefore cannot be used when a machine needs
to authenticate with AWS.
## Prerequisites
docs/pages/machine-workload-identity/workload-identity/getting-started.mdx
+1 -1
View File
@@ -1,7 +1,7 @@
---
title: Getting Started with Workload Identity
sidebar_label: Getting Started
description: Getting started with Teleport Workload Identity for SPIFFE and Machine ID
description: Getting started with Teleport Workload Identity for SPIFFE
tags:
- get-started
- mwi
docs/pages/machine-workload-identity/workload-identity/introduction.mdx
+5 -5
View File
@@ -83,12 +83,12 @@ Once the workload has its identity, it can be used for a range of purposes. The
X.509 certificates can be used to establish Mutual TLS, and the JWTs can be used
to authenticate with a range of third-party APIs.
## Teleport Workload Identity vs Machine ID
## Teleport Zero Trust Access vs Workload Identity
Teleport Machine ID issues short-lived credentials to workloads to enable them
to access resources secured by the Teleport cluster. The credentials issued are
only compatible with Teleport itself, and access to resources must be through
the Teleport Proxy.
Teleport Machine & Workload Identity for Zero Trust Access primarily issues
short-lived credentials to workloads to enable them to access resources secured
by the Teleport cluster. The credentials issued are only compatible with
Teleport itself, and access to resources must be through the Teleport Proxy.
Teleport Workload Identity issues cryptographic identities that are compatible
with the popular SPIFFE standard for interoperable workload identity. These
docs/pages/machine-workload-identity/workload-identity/tsh.mdx
+2 -2
View File
@@ -10,8 +10,8 @@ tags:
{/* lint disable page-structure remark-lint */}
In some scenarios, you may wish to issue a SPIFFE SVID manually, without using
Machine ID. This can be useful in scenarios where you need to impersonate a
service for the purposes of debugging or could provide a mechanism for providing
`tbot`. This can be useful in scenarios where you need to impersonate a service
for the purposes of debugging or could provide a mechanism for providing
human access to services which use SPIFFE SVIDs for authentication.
In this guide, you will use the `tsh` tool to issue a SPIFFE SVID.
docs/pages/machine-workload-identity/workload-identity/workload-identity.mdx
+1 -1
View File
@@ -12,7 +12,7 @@ issues flexible short-lived identities to workloads in your infrastructure.
## Getting started
- [Introduction to Workload Identity](./introduction.mdx): Describes Teleport Workload Identity, which securely issues flexible, short-lived cryptographic identities to workloads and non-human identities.
- [Introduction to SPIFFE](./spiffe.mdx): Learn about Secure Production Identity Framework For Everyone (SPIFFE) and how it is implemented by Teleport Workload Identity
- [Getting Started with Workload Identity](./getting-started.mdx): Getting started with Teleport Workload Identity for SPIFFE and Machine ID
- [Getting Started with Workload Identity](./getting-started.mdx): Getting started with Teleport Workload Identity for SPIFFE
## Configuration Guides