self-hosted/teleport
self-hosted/teleport
1
0
Fork 0
mirror of https://github.com/gravitational/teleport synced 2024-10-19 16:53:57 +00:00
Code Issues Packages Projects Releases Wiki Activity

Promote IAC docs for agents and dynamic resources (#27703)

Browse source 
* Promote IAC docs for agents and dynamic resources

Closes #27382
Closes #25418
Closes #25442

Two aspects of setting up a Teleport cluster are omnipresent in the docs
but never get dedicated treatment:

- Running agents
- Applying dynamic resources

As a result, it is difficult to include discussions about those topics
that are separate from a specific workflow or how-to guide. One glaring
absence has been prominent guidance on using infrastructure-as-code
tools to achieve these tasks.

This change improves the visibility of Teleport's support for
infrastructure-as-code tools by:

- Creating top-level docs sections for running agents and applying
  dynamic resources
- Making IAC instructions prominent within these sections

The intention is for readers to become familiar with different methods
of applying dynamic resources and running agents, including how to do
this with IAC, so they can apply this knowledge when reading other parts
of the docs.

As a result, in the docs sidebar, the "Dynamic Resources" section comes
before the section on RBAC, and the "Teleport Agents" section comes
before the sections related to individual Teleport services
("Application Access", "Server Access", etc.).

The new section on dynamic resources also gives us a place to put other
guides to using the Terraform provider and Kubernetes Operator, e.g., if
we add guides to using these tools with popular GitOps platforms.

Likewise, the section on agents gives us a place to put other agent-wide
information, e.g., how to enable an additional Teleport service on an
instance that is already running.

To allow for these changes, I have also made the following, more
tangentially related sidebar changes:

- **Renamed sidebar sections to be noun phrases instead of verb
  phrases:** Currently, one half of the sidebar is made of imperative
  phrases like "Manage Access" and "Manage your Cluster". This doesn't
  really work for the sections on agents and dynamic resources, so I
  have renamed these sections for consistency.

- **Moved the "Manage your Cluster" and "Deploy a Cluster" sections**: I
  have arranged the sidebar so more basic topics (i.e., those that new
  users and experienced users alike will need to be familiar with) are
  on the top and more advanced ones are on the bottom.

  The other sections that are currently in the first half of the sidebar
  are topics that all Teleport users will need to get familiar with,
  while day two operations and self-hosted production deployments are
  more advanced topics.

- **Edited the landing page:** I have edited the landing page of the
  docs to reflect the new sidebar organization. This also makes the page
  shorter, simpler, and more opinionated. It spells out a high-level
  sequence for setting up Teleport, then provides a list of advanced
  topics for further reading.

  Links correspond to sidebar sections--as before, I wanted to describe
  the topic of each sidebar section so users would know this information
  without having to navigate away from the landing page.

* Move the "Dynamic Configuration" section

Make this a subsection of "Manage your Cluster" since it's not
self-evidently clear as a top-level docs section. Users will probably
need an introduction via the "Manage your Cluster" section intro page.

This also reverts some of the more drastic sidebar changes introduced by
the previous commit.

Responds to xinding33 feedback.

* Make IAC learning tracks prominent/hard to avoid

Closes #27751

Responds to xinding33 feedback

The motivation is to be more opinionated about the course that users
take through the docs. We currently recommend two tracks for
self-service users, i.e., the users expected to make use of the landing
page:

- Setting up a toy self-hosted Teleport cluster
- Setting up a Teleport Team/Enterprise Cloud cluster that can
  eventually become production ready

By moving the "Get Started" guide to the landing page, we direct users
immediately on to the first track. This change then gives new users a
way to enter the second track from the docs landing page with a
prominent link to the Teleport Team docs.

This change also edits The landing page to direct users who have
completed the getting started experience to instructions for setting up
a pool of agents on Terraform, helping to make infrastructure-as-code a
first-class citizen of the docs.

This change also removes the menu of links that used to confront users
on the landing page. Since all sidebar sections include introduction
pages, users interested in the content of a sidebar section can visit
the section. By removing links, we make it clearer for users how to
proceed through the docs.

* Fix linter errors

* Incorporate Trivy recommendations

* Respond to alexfornuto feedback

* Restore list of dynamic resources to the reference

* Fix linter warnings

* Remove the ".sh" extension from userdata script

The Terraform module that reads this file does not need the extension,
which was causing trouble for our shellcheck linter.
This commit is contained in:
Paul Gottschling 2023-06-30 11:45:37 -04:00 committed by GitHub
parent c548bd73ca
commit faf6dadb53
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
50 changed files with 1295 additions and 987 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

597
docs/config.json
View file

File diff suppressed because it is too large Load diff

2
docs/cspell.json
View file

@ -711,6 +711,7 @@
"teleportyaml",
"tenantname",
"testuser",
"tfvars",
"thisisunsafe",
"thred",
"timechart",
@ -739,6 +740,7 @@
"updaterversionserver",
"uqcje",
"urandom",
"userdata",
"userdel",
"usermod",
"usernameclaim",

2
docs/pages/access-controls/compliance-frameworks/soc2.mdx
View file

@ -56,7 +56,7 @@ Each principle has many “Points of Focus” which will apply differently to di
| CC6.1 - Manages Points of Access | Points of access by outside entities and the types of data that flow through the points of access are identified, inventoried, and managed. The types of individuals and systems using each point of access are identified, documented, and managed. | [Label Nodes to inventory and create rules](../../management/admin/labels.mdx) <br/><br/> [Create Labels from AWS Tags](../../management/guides/ec2-tags.mdx) <br/><br/>Teleport maintains a live list of all nodes within a cluster. This node list can be queried by users (who see a subset they have access to) and administrators any time. |
| CC6.1 - Restricts Access to Information Assets | Combinations of data classification, separate data structures, port restrictions, access protocol restrictions, user identification, and digital certificates are used to establish access-control rules for information assets. | [Teleport uses Certificates to grant access and create access control rules](../../core-concepts.mdx) |
| CC6.1 - Manages Identification and Authentication | Identification and authentication requirements are established, documented, and managed for individuals and systems accessing entity information, infrastructure, and software. | Teleport makes setting policies for SSH requirements easy since it works in the cloud and on premise with the same authentication security standards. |
| CC6.1 - Manages Credentials for Infrastructure and Software | New internal and external infrastructure and software are registered, authorized, and documented prior to being granted access credentials and implemented on the network or access point. Credentials are removed and access is disabled when access is no longer required or the infrastructure and software are no longer in use. | [Invite nodes to your cluster with short lived tokens](../../management/join-services-to-your-cluster/join-token.mdx) |
| CC6.1 - Manages Credentials for Infrastructure and Software | New internal and external infrastructure and software are registered, authorized, and documented prior to being granted access credentials and implemented on the network or access point. Credentials are removed and access is disabled when access is no longer required or the infrastructure and software are no longer in use. | [Invite nodes to your cluster with short lived tokens](../../agents/join-services-to-your-cluster/join-token.mdx) |
| CC6.1 - Uses Encryption to Protect Data | The entity uses encryption to supplement other measures used to protect data at rest, when such protections are deemed appropriate based on assessed risk. | Teleport Audit logs can use DynamoDB encryption at rest. |
| CC6.1 - Protects Encryption Keys | Processes are in place to protect encryption keys during generation, storage, use, and destruction. | Teleport acts as a Certificate Authority to issue SSH and x509 user certificates that are signed by the CA and are (by default) short-lived. SSH host certificates are also signed by the CA and rotated automatically |
| CC6.2 - Controls Access Credentials to Protected Assets | Information asset access credentials are created based on an authorization from the system&#39;s asset owner or authorized custodian. | [Request Approval from the command line](../../reference/cli.mdx#tctl-request-approve) <br/><br/> [Build Approval Workflows with Access Requests](../../access-controls/access-requests.mdx) <br/><br/> [Use Plugins to send approvals to tools like Slack or Jira](../../access-controls/access-requests.mdx) |

4
docs/pages/access-controls/login-rules/kubernetes.mdx
View file

@ -44,7 +44,7 @@ This guide is applicable if you self-host Teleport in Kubernetes using the
</Admonition>
- Follow Step 1 of the
[Teleport operator guide](../../management/guides/teleport-operator.mdx#step-13-install-teleport-cluster-helm-chart-with-the-operator)
[Teleport operator guide](../../management/dynamic-resources/teleport-operator.mdx#step-13-install-teleport-cluster-helm-chart-with-the-operator)
to install the Teleport Operator in your Kubernetes cluster.
Make sure to follow the Enterprise instructions.
@ -250,7 +250,7 @@ logins:
## Next Steps
- Read the [Teleport Operator Guide](../../management/guides/teleport-operator.mdx) to
- Read the [Teleport Operator Guide](../../management/dynamic-resources/teleport-operator.mdx) to
learn more about the Teleport Operator.
- Read the [Login Rules reference](./reference.mdx) to learn mode about the
Login Rule expression syntax.

4
docs/pages/access-controls/login-rules/terraform.mdx
View file

@ -31,7 +31,7 @@ For simplicity, this guide will configure the Terraform provider to use your
current logged-in user's Teleport credentials obtained from `tsh login`.
<Admonition type="note">
The [Terraform provider guide](../../management/guides/terraform-provider.mdx)
The [Terraform provider guide](../../management/dynamic-resources/terraform-provider.mdx)
includes instructions for configuring a dedicated `terraform` user and role,
which is a better option when running Terraform in a non-interactive
environment.
@ -156,7 +156,7 @@ logins:
## Next Steps
- Read the [Terraform Guide](../../management/guides/terraform-provider.mdx) to
- Read the [Terraform Guide](../../management/dynamic-resources/terraform-provider.mdx) to
learn more about configuring the Terraform provider.
- Read the [Login Rules reference](./reference.mdx) to learn mode about the
Login Rule expression syntax.

308
docs/pages/agents/deploy-agents-terraform.mdx Normal file
View file

@ -0,0 +1,308 @@
---
title: "Deploy Teleport Agents with Terraform"
description: "In this guide, we will show you how to deploy a pool of Teleport agents so you can apply dynamic resources to enroll your infrastructure with Teleport."
---
An agent is a Teleport instance configured to run one or more Teleport services
in order to proxy infrastructure resources. For a brief architectural overview
of how agents run in a Teleport cluster, read the [Introduction to Teleport
Agents](introduction.mdx).
This guide shows you how to deploy a pool of Teleport agents by declaring it as
code using Terraform.
There are several methods you can use to join a Teleport agent to your cluster,
which we discuss in the [Joining Services to your
Cluster](join-services-to-your-cluster.mdx) guide. In this guide, we will use
the **join token** method, where the operator stores a secure token on the Auth
Service, and an agent presents the token in order to join a cluster.
No matter which join method you use, it will involve the following Terraform
resources:
- Compute instances to run Teleport services
- A join token for each compute instance in the agent pool
```mermaid
flowchart TB
subgraph agent1["Teleport agent"]
service1["Teleport service"]
service2["Teleport service"]
join1["Join token"]
end
subgraph agent2["Teleport agent"]
join2["Join token"]
service3["Teleport service"]
service4["Teleport service"]
end
subgraph auth["Auth Service"]
join3["Join token"]
join4["Join token"]
end
join1<-.Matches.->join3
join2<-.Matches.->join4
```
## Prerequisites
(!docs/pages/includes/edition-prereqs-tabs.mdx!)
<Admonition type="tip">
We recommend following this guide on a fresh Teleport demo cluster so you can
see how an agent pool works. After you are familiar with the setup, apply the
lessons from this guide to protect your infrastructure. You can get started with
a demo cluster using:
- A demo deployment on a [Linux server](../index.mdx)
- A [Teleport Team trial](https://goteleport.com/signup)
</Admonition>
- An AWS account with permissions to create EC2 instances.
- Terraform v(=terraform.version=).
- An identity file for the Teleport Terraform provider. Make sure you are
familiar with [how to set up the Teleport Terraform
provider](../management/dynamic-resources/terraform-provider.mdx) before following this
guide.
- (!docs/pages/includes/tctl.mdx!)
## Step 1/3. Fetch the example Terraform configuration
Fetch the Teleport code repository and copy the example Terraform configuration
for this project into your current working directory:
```code
$ git clone --depth=1 https://github.com/gravitational/teleport
$ cp -R teleport/examples/agent-pool-terraform .
$ rm -rf teleport
```
Move the identity file for the Teleport Terraform provider into your project
directory so the Terraform provider an access it. Name the file
`terraform-identity`.
<Notice type="warning">
If you don't have an identify file available, make sure you have followed the
[prerequisites for this guide](#prerequisites).
</Notice>
## Step 2/3. Prepare your Terraform configuration
After you have copied the example Terraform configuration, you will assign input
variables and apply your new resources. First, we will explain the Terraform
resource configuration you copied so you can understand how to deploy an agent
pool in your infrastructure.
### Instances and tokens
The file `agent-pool.tf` configures EC2 instances and Teleport join tokens:
```text
(!examples/agent-pool-terraform/agent-pool.tf!)
```
In this minimal example, we deploy one EC2 instance for each Teleport agent.
Each agent joins the cluster using a token. We create each token using the
`teleport_provision_token` Terraform resource, specifying the token's value with
a `random_string` resource.
When we apply the `teleport_provision_token` resources, the Teleport Terraform
provider creates them on the Teleport Auth Service backend. Each EC2 instance
presents the token in order to establish trust with the cluster.
The Auth Service associates the join token with one or more roles, identifying
the Teleport service that is allowed to use the token. The configuration above
generates tokens for the following Teleport services:
- Teleport SSH Service (`Node`)
- Teleport Application Service (`App`)
- Teleport Database Service (`Db`)
- Teleport Kubernetes Service (`Kube`)
### Startup script
Each EC2 instance runs a script on startup, which we configured above using the
`user_data` field within the `aws_instance.teleport_agent` resource
(`examples/agent-pool-terraform/userdata`):
```text
(!examples/agent-pool-terraform/userdata!)
```
This script installs Teleport Community Edition on the host, then writes a
configuration file to the default location, `/etc/teleport.yaml`. The
configuration file enables each Teleport service we associated with our token.
The configuration also adds the `role: agent-pool` label to the Teleport SSH
Service on each instance. This will make it easier to access hosts in the agent
pool later.
Finally, the script restarts Teleport on the host to apply the new
configuration.
### Input variables
The Terraform configuration we show in this guide relies on the following inputs
(`examples/agent-pool-terraform/inputs.tf`):
```text
(!examples/agent-pool-terraform/inputs.tf!)
```
In your `agent-pool-terraform` project directory, create a file called
`main.auto.tfvars` with the following content:
```text
agent_count=2
proxy_service_address="mytenant.teleport.sh"
aws_region=""
teleport_version=(=teleport.version=)
subnet_id=""
```
Assign `agent_count` to `2` for high availability. As you scale your Teleport
usage, you can increase this count to ease the load on each agent. You can
consider adding your agents to an Auto Scaling group as well.
Assign `proxy_service_address` to the host and HTTPS port of your Teleport Proxy
Service, e.g., `mytenant.teleport.sh:443`.
<Notice type="tip">
Make sure to include the port.
</Notice>
Assign `aws_region` to your AWS region, e.g., `us-east-1`.
For `subnet_id`, include the ID of the AWS subnet where you will deploy Teleport
agents.
Finally, make sure you are using the latest supported version of the Teleport
Terraform provider. The `required_providers` block for the Teleport provider
includes a placeholder value:
```text
(!examples/agent-pool-terraform/provider.tf!)
```
Replace the placeholder value with the latest version:
```code
$ sed -i "" "s/TELEPORT_VERSION/(=teleport.plugin.version=)/" provider.tf
```
## Step 3/3. Verify the deployment
Make sure your AWS credentials are available to Terraform using the standard
approach for your organization.
Apply the Terraform configuration:
```code
$ terraform apply
```
Once the `apply` command completes, run the following command to verify that the
two agents have deployed successfully:
```code
$ tsh ls role=agent-pool
Node Name Address Labels
-------------------------- ---------- ---------------
ip-10-1-1-187.ec2.internal ⟵ Tunnel role=agent-pool
ip-10-1-1-24.ec2.internal ⟵ Tunnel role=agent-pool
```
## Next step: Enroll infrastructure resources
There are two ways to configure your agent pool to protect infrastructure
resources with Teleport, which we describe below.
### Define dynamic resources in Terraform
You can declare Terraform resources that enroll your infrastructure with
Teleport. The Teleport Terraform provider currently supports the following:
|Infrastructure Resource|Terraform Resource|
|---|---|
|Application|`teleport_app`|
|Database|`teleport_database`|
To declare a dynamic resource with Terraform, add a configuration block similar
to the ones below to a `*.tf` file in your `agent-pool-terraform` project
directory.
The Teleport Terraform provider creates these on the Auth Service backend, and
the relevant Teleport services query them in order to proxy user traffic. For a
full list of supported resources and fields, see the [Terraform provider
reference](../reference/terraform-provider.mdx).
<Tabs>
<TabItem label="Application">
```text
resource "teleport_app" "example" {
metadata = {
name = "example"
description = "Test app"
labels = {
// Teleport adds this label by default, so add it here to
// ensure a consistent state.
"teleport.dev/origin" = "dynamic"
}
}
spec = {
uri = "localhost:3000"
}
}
```
</TabItem>
<TabItem label="Database">
```text
resource "teleport_database" "example" {
metadata = {
name = "example"
description = "Test database"
labels = {
// Teleport adds this label by default, so add it here to
// ensure a consistent state.
"teleport.dev/origin" = "dynamic"
}
}
spec = {
protocol = "postgres"
uri = "localhost"
}
}
```
</TabItem>
</Tabs>
### Configure Teleport services in the agent pool
Each Teleport service reads its local configuration file (`/etc/teleport.yaml`
by default) to determine which infrastructure resources to proxy. You can edit
this configuration file to enroll resources with Teleport.
In the setup we explored in this guide, you can edit the user data script for
each instance to add configuration settings to, for example, the
`database_service` or `kubernetes_service` sections.
To see how to configure each service, read its section of the documentation:
- [SSH Service](../server-access/introduction.mdx)
- [Database Service](../database-access/introduction.mdx)
- [Kubernetes Service](../kubernetes-access/introduction.mdx)
- [Windows Desktop Service](../desktop-access/introduction.mdx)
- [Application Service](../application-access/introduction.mdx)

101
docs/pages/agents/introduction.mdx Normal file
View file

@ -0,0 +1,101 @@
---
title: "Teleport Agents"
description: Deploy agents to enroll resources in your infrastructure with Teleport. You can run multiple Teleport services per agent."
---
Teleport agents are Teleport instances that are configured to proxy traffic to
resources in your infrastructure, such as servers, databases, and Kubernetes
clusters.
This section shows you how to use Teleport agents to enable secure access to
your infrastructure.
## Architecture overview
### Services
Each Teleport agent can run one or more services. A Teleport instance runs a
service if it is enabled within the instance's configuration file. See the
[Teleport Configuration
Reference](../reference/config.mdx#enabling-teleport-services) for which
services are enabled by default and how to enable a particular service.
### Agent pools
Agents typically run in the same private networks as the resources they proxy.
They should be the only clients that can access a resource without Teleport.
In this setup, agents dial the Teleport Proxy Service in order to establish
reverse SSH tunnels. While the Proxy Service remains open to the public internet
via its HTTPS port, agents require no open ports or public address.
The Teleport Proxy Service uses these reverse tunnels to forward traffic in
Teleport's supported protocols to an available agent. Agents apply RBAC
rules and forward the traffic to resources in your infrastructure.
```mermaid
%%{init: {"flowchart": {"curve": "linear"}}}%%
flowchart LR
proxy["Teleport Proxy Service"]
Clients--->proxy
subgraph private["Private network"]
db["Self-hosted database"]
app["Internal web application"]
subgraph agent2["Teleport agent"]
service3["Teleport Database Service"]
service4["Teleport Application Service"]
end
subgraph agent1["Teleport agent"]
service1["Teleport Kubernetes Service"]
service2["Teleport SSH Service"]
end
kubernetes["Kubernetes API server"]
ssh["SSH server"]
agent1 -.-> kubernetes & ssh
agent2 -.-> db
agent2 -.-> app
end
agent1 & agent2--Reverse tunnel---->proxy
agent2-.->cloud["Cloud provider API"]
```
Read our guide for how to use Terraform to [deploy a pool of
agents](deploy-agents-terraform.mdx).
## Joining agents
Teleport agents need to establish trust with the Teleport Auth Service in order
to authorize users to access your infrastructure. There are several ways to join
an agent to your Teleport cluster, making it possible to automate the join
process for your environment. Read about the available join methods in our [Join
Services to your Cluster](./join-services-to-your-cluster.mdx) guides.
## Enrolling infrastructure
There are two ways to enroll infrastructure resources with Teleport agents:
1. **Static**: Edit an agent's configuration file to configure a specific
infrastructure resource to proxy.
2. **Dynamic**: Apply a [configuration
resource](../management/dynamic-resources.mdx) that configures a resource to
proxy.
The dynamic method allows Teleport to discover resources automatically. The
Discovery Service polls your cloud provider APIs and modifies dynamic
infrastructure resources as required.
[Read our guide](deploy-agents-terraform.mdx) to deploying a pool of agents
via Terraform and enrolling infrastructure resources dynamically.
To learn how to enroll resources via static configuration files, plus all the
ways Teleport supports enrolling infrastructure, consult our guides to each of
Teleport's services:
- [SSH Service](../server-access/introduction.mdx)
- [Database Service](../database-access/introduction.mdx)
- [Kubernetes Service](../kubernetes-access/introduction.mdx)
- [Windows Desktop Service](../desktop-access/introduction.mdx)
- [Application Service](../application-access/introduction.mdx)

0
docs/pages/management/join-services-to-your-cluster.mdx → docs/pages/agents/join-services-to-your-cluster.mdx
View file

0
docs/pages/management/join-services-to-your-cluster/aws-ec2.mdx → docs/pages/agents/join-services-to-your-cluster/aws-ec2.mdx
View file

0
docs/pages/management/join-services-to-your-cluster/aws-iam.mdx → docs/pages/agents/join-services-to-your-cluster/aws-iam.mdx
View file

0
docs/pages/management/join-services-to-your-cluster/azure.mdx → docs/pages/agents/join-services-to-your-cluster/azure.mdx
View file

0
docs/pages/management/join-services-to-your-cluster/gcp.mdx → docs/pages/agents/join-services-to-your-cluster/gcp.mdx
View file

2
docs/pages/management/join-services-to-your-cluster/join-token.mdx → docs/pages/agents/join-services-to-your-cluster/join-token.mdx
View file

@ -335,4 +335,4 @@ $ tctl tokens rm <Var name="token-to-delete"/>
- If you have workloads split across different networks or clouds, we recommend
setting up Trusted Clusters. Read how to get started in our [Trusted Clusters
guide](../admin/trustedclusters.mdx).
guide](../../management/admin/trustedclusters.mdx).

0
docs/pages/management/join-services-to-your-cluster/kubernetes.mdx → docs/pages/agents/join-services-to-your-cluster/kubernetes.mdx
View file

2
docs/pages/ai-assist.mdx
View file

@ -35,7 +35,7 @@ Community Edition.
Before you get started with Teleport Assist, make sure you have the following:
- A running Teleport Community Edition cluster. For details on how to set this
up, see our [Getting Started](./get-started.mdx) guide.
up, see our [Getting Started](./index.mdx) guide.
- **OpenAI Account**: You will need an active OpenAI account with GPT-4 API
access as Teleport Assist relies on OpenAI services.

2
docs/pages/application-access/getting-started.mdx
View file

@ -42,7 +42,7 @@ Let's connect to Grafana using Teleport in three steps:
<Admonition type="tip" title="Not yet a Teleport user?">
{/*lint ignore messaging*/}
If you have not yet deployed the Auth Service and Proxy Service, you should
follow one of our [getting started guides](../get-started.mdx) or try our
follow one of our [getting started guides](../index.mdx) or try our
Teleport Application Access [interactive learning track](https://play.instruqt.com/teleport/invite/rgvuva4gzkon).
</Admonition>

2
docs/pages/architecture/authentication.mdx
View file

@ -143,7 +143,7 @@ services and rotates SSH and X.509 certificates.
Teleport internal services - Auth, Proxy and Nodes use certificates to identify themselves
within a cluster. To join proxies and nodes to the cluster and receive certificates, admins should use
[short-lived tokens or cloud identity services](../management/join-services-to-your-cluster/join-token.mdx).
[short-lived tokens or cloud identity services](../agents/join-services-to-your-cluster/join-token.mdx).
Unlike users and services, internal services receive long-lived certificates.

2
docs/pages/choose-an-edition/introduction.mdx
View file

@ -38,7 +38,7 @@ compliance.
We provide a free, open source distribution of Teleport that enables you to get
secure access to databases, Windows desktops, Kubernetes clusters, and more.
[Try out Teleport on a Linux server](../get-started.mdx). If you would like to
[Try out Teleport on a Linux server](../index.mdx). If you would like to
take a look at the source, visit the [Teleport GitHub
repository](https://github.com/gravitational/teleport).

7
docs/pages/choose-an-edition/teleport-cloud/faq.mdx
View file

@ -76,8 +76,9 @@ S3, are established using encryption provided by AWS, both at rest and in transi
### How do I add resources to Teleport Enterprise Cloud?
You can connect servers, Kubernetes clusters, databases, desktops and applications using
[reverse tunnels](../../management/join-services-to-your-cluster.mdx).
You can connect servers, Kubernetes clusters, databases, desktops, and
applications using [reverse
tunnels](../../agents/join-services-to-your-cluster.mdx).
There is no need to open any ports on your infrastructure for inbound traffic.
@ -88,7 +89,7 @@ If you plan on connecting more than 10,000 nodes or agents, please contact your
### Are dynamic node tokens available?
After [connecting](#how-can-i-access-the-tctl-admin-tool) `tctl` to Teleport Enterprise Cloud, users can generate
[dynamic tokens](../../management/join-services-to-your-cluster/join-token.mdx):
[dynamic tokens](../../agents/join-services-to-your-cluster/join-token.mdx):
```code
$ tctl nodes add --ttl=5m --roles=node,proxy --token=$(uuid)

23
docs/pages/choose-an-edition/teleport-team.mdx
View file

@ -217,24 +217,15 @@ infrastructure by registering a server with your Teleport Team cluster. From
here, you can explore more of the documentation to see how to set up secure
access for your infrastructure.
### Register resources
To enroll your infrastructure with Teleport, you deploy one or more Teleport
**agents**, which proxy traffic to resources like servers, databases, Kubernetes
clusters, cloud provider APIs, and Windows desktops.
Read about how you can register resources in your infrastructure, including:
You can use Terraform to declare a pool of Teleport agents and configure them to
proxy your infrastructure. Read [Deploy Teleport Agents with
Terraform](../agents/deploy-agents-terraform.mdx).
- [Additional SSH servers](../server-access/introduction.mdx)
- [Cloud provider tools and internal web applications](../application-access/introduction.mdx)
- [Databases](../database-access/introduction.mdx)
- [Kubernetes clusters](../kubernetes-access/introduction.mdx)
- [Service accounts](../machine-id/introduction.mdx)
- [Windows desktops](../desktop-access/introduction.mdx)
### Connect to your infrastructure
Aside from `tsh` and the Web UI, you can also connect to Teleport with our
desktop application, [Teleport
Connect](../connect-your-client/teleport-connect.mdx).
### Subscribe
## Subscribe
After you finish your free trial, Teleport Team will charge based on usage.
Check the [pricing page](https://goteleport.com/pricing/) for detailed

2
docs/pages/core-concepts.mdx
View file

@ -17,7 +17,7 @@ within your infrastructure, such as Kubernetes clusters and Windows desktops.
A minimal Teleport cluster consists of the **Teleport Auth Service** and
**Teleport Proxy Service**. In a demo environment, you can run these two
services from a single `teleport` process on a [Linux
host](./get-started.mdx).
host](./index.mdx).
### Teleport Auth Service

4
docs/pages/database-access/guides/aws-opensearch.mdx
View file

@ -177,8 +177,8 @@ Teleport:
- [Configure Teleport to Automatically Enroll EC2 instances (Preview)](../../server-access/guides/ec2-discovery.mdx)
- [Joining Nodes via AWS IAM
Role](../../management/join-services-to-your-cluster/aws-iam.mdx)
- [Joining Nodes via AWS EC2 Identity Document](../../management/join-services-to-your-cluster/aws-ec2.mdx)
Role](../../agents/join-services-to-your-cluster/aws-iam.mdx)
- [Joining Nodes via AWS EC2 Identity Document](../../agents/join-services-to-your-cluster/aws-ec2.mdx)
</Details>

6
docs/pages/deploy-a-cluster/deployments/aws-terraform.mdx
View file

@ -768,7 +768,7 @@ To add new nodes/EC2 servers that you can "SSH into" you'll need to:
- [Run Teleport - we recommend using systemd](../../management/admin/daemon.mdx)
- [Set the correct settings in /etc/teleport.yaml](../../reference/config.mdx)
- [Add Nodes to the Teleport
cluster](../../management/join-services-to-your-cluster.mdx)
cluster](../../agents/join-services-to-your-cluster.mdx)
### Getting the CA pin hash
@ -790,7 +790,7 @@ $ aws ssm get-parameter --region ${TF_VAR_region} --name "/teleport/${TF_VAR_clu
# 992a9725-0a64-428d-8e5e-308e6877743d
```
You can also generate a Node join token using `tctl tokens add --type=node` [as detailed here in our admin guide](../../management/join-services-to-your-cluster/join-token.mdx).
You can also generate a Node join token using `tctl tokens add --type=node` [as detailed here in our admin guide](../../agents/join-services-to-your-cluster/join-token.mdx).
### Joining Nodes via the Teleport Auth Service
@ -811,7 +811,7 @@ auth_server: example-cluster-auth-c5b0fc2764ee015b.elb.us-east-1.amazonaws.com:3
### Joining Nodes via Teleport IoT/Node tunneling
To join Teleport Nodes from outside the same VPC, you will either need to investigate VPC peering/gateways (out of scope
for this document) or join your nodes using [Teleport's node tunneling](../../management/join-services-to-your-cluster/join-token.mdx) functionality.
for this document) or join your nodes using [Teleport's node tunneling](../../agents/join-services-to-your-cluster/join-token.mdx) functionality.
With this method, you can join the nodes using the public facing proxy address - `teleport.example.com:443` for our
example.

2
docs/pages/desktop-access/active-directory-manual.mdx
View file

@ -193,7 +193,7 @@ certificate-based smart card authentication, and ensuring RDP is enabled.
The following step requires an existing cluster. If you don't already have a
Teleport cluster up and running, see our general [Getting
Started](../get-started.mdx) guide to set up a demo cluster.
Started](../index.mdx) guide to set up a demo cluster.
<Admonition type="note" title="User CA Rotation">
These steps will need to be repeated if Teleport's user certificate authority is rotated.

2
docs/pages/faq.mdx
View file

@ -54,7 +54,7 @@ Yes. When running a Teleport agent, use the `--auth-server` flag to point to the
Proxy Service address (this would be `public_addr` and `web_listen_addr` in your
file configuration). For more information, see
[Adding Nodes to the
Cluster](./management/join-services-to-your-cluster/join-token.mdx).
Cluster](./agents/join-services-to-your-cluster/join-token.mdx).
## Can Nodes use a single port for reverse tunnels?

221
docs/pages/get-started.mdx
View file

@ -1,221 +0,0 @@
---
title: Try out Teleport on a Linux Server
description: This tutorial will guide you through the steps needed to install and run Teleport on a Linux server
videoBanner: BJWbSqiDLeU
---
This tutorial will show you how to install and run a demo Teleport cluster
(=teleport.version=) on a Linux host using Teleport Community Edition. Once you
deploy the cluster, you can configure RBAC, register resources, and protect your
small-scale demo environments or home lab.
<Figure width="700">
![Architecture of the setup you will complete in this
guide](../img/linux-server-diagram.png)
</Figure>
We will run the following Teleport services:
- **Teleport Auth Service:** The certificate authority for your cluster. It
issues certificates and conducts authentication challenges. The Auth Service
is typically inaccessible outside your private network.
- **Teleport Proxy Service:** The cluster frontend, which handles user requests,
forwards user credentials to the Auth Service, and communicates with Teleport
instances that enable access to specific resources in your infrastructure.
- **Teleport SSH Service:** An SSH server implementation that takes advantage of
Teleport's short-lived certificates, sophisticated RBAC, session recording,
and other features.
(!docs/pages/includes/cloud/call-to-action.mdx!)
## Prerequisites
- A Linux host with only port `443` open to ingress traffic. You must be able
to install and run software on the host. Either configure access to the host
via SSH for the initial setup (and open an SSH port in addition port `443`)
or enter the commands in this guide into an Amazon EC2 [user data
script](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/user-data.html),
Google Compute Engine [startup
script](https://cloud.google.com/compute/docs/instances/startup-scripts),
or similar.
<Admonition type="tip" title="Quick demo environments">
For a quick demo environment you can use to follow this guide, consider
installing our DigitalOcean 1-Click droplet. View the installation page on
[DigitalOcean
Marketplace](https://marketplace.digitalocean.com/apps/teleport). Once your
droplet is ready, SSH into the droplet and follow the configuration wizard.
</Admonition>
- A two-factor authenticator app such as [Authy](https://authy.com/download/),
[Google Authenticator](https://www.google.com/landing/2step/), or [Microsoft
Authenticator](https://www.microsoft.com/en-us/account/authenticator)
You must also have one of the following:
- A registered domain name.
- An authoritative DNS nameserver managed by your organization, plus an existing
certificate authority. If using this approach, ensure that your browser is
configured to use your organization's nameserver.
This guide is not intended for local deployments. If your environment doesn't
meet the prerequisites above, you can get started with Teleport by signing up
for a [free trial of Teleport Enterprise Cloud](https://goteleport.com/signup/).
## Step 1/4. Configure DNS
Teleport uses TLS to provide secure access to its Proxy Service and Auth
Service, and this requires a domain name that clients can use to verify
Teleport's certificate. Set up two DNS `A` records, each pointing to the IP
address of your Linux host. Assuming `teleport.example.com` is your domain name,
set up records for:
|Domain|Reason|
|---|---|
|`teleport.example.com`|Traffic to the Proxy Service from users and services.|
|`*.teleport.example.com`|Traffic to web applications registered with Teleport. Teleport issues a subdomain of your cluster's domain name to each application.|
## Step 2/4. Set up Teleport on your Linux host
### Install Teleport
On your Linux host, run the following command to install the Teleport binary:
```code
$ curl https://goteleport.com/static/install.sh | bash -s (=teleport.version=)
```
### Configure Teleport
Generate a configuration file for Teleport using the `teleport configure` command.
This command requires information about a TLS certificate and private key.
(!docs/pages/includes/tls-certificate-setup.mdx!)
### Start Teleport
(!docs/pages/includes/start-teleport.mdx!)
Access Teleport's Web UI via HTTPS at the domain you created earlier (e.g.,
`https://teleport.example.com`). You should see a welcome screen similar to the
following:
![Teleport Welcome Screen](../img/quickstart/welcome.png)
## Step 3/4. Create a Teleport user and set up two-factor authentication
In this step, we'll create a new Teleport user, `teleport-admin`, which is
allowed to log into SSH hosts as any of the principals `root`, `ubuntu`, or
`ec2-user`.
On your Linux host, run the following command:
```code
# tctl is an administrative tool that is used to configure Teleport's auth service.
$ sudo tctl users add teleport-admin --roles=editor,access --logins=root,ubuntu,ec2-user
```
The command prints a message similar to the following:
```text
User "teleport-admin" has been created but requires a password. Share this URL with the user to complete user setup, link is valid for 1h:
https://teleport.example.com:443/web/invite/123abc456def789ghi123abc456def78
NOTE: Make sure teleport.example.com:443 points at a Teleport proxy which users can access.
```
Visit the provided URL in order to create your Teleport user.
<Admonition
type="tip"
title="OS User Mappings"
>
The users that you specify in the `logins` flag (e.g., `root`, `ubuntu` and
`ec2-user` in our examples) must exist on your Linux host. Otherwise, you
will get authentication errors later in this tutorial.
If a user does not already exist, you can create it with `adduser <login>` or
use [host user creation](./server-access/guides/host-user-creation.mdx).
If you do not have the permission to create new users on the Linux host, run
`tctl users add teleport $(whoami)` to explicitly allow Teleport to
authenticate as the user that you have currently logged in as.
</Admonition>
Teleport enforces the use of two-factor authentication by default. It supports
one-time passwords (OTP) and second-factor authenticators (WebAuthn). In this
guide, you will need to enroll an OTP authenticator application using the QR
code on the Teleport welcome screen.
<Details title="Logging in via the CLI">
In addition to Teleport's Web UI, you can access resources in your
infrastructure via the `tsh` client tool.
Install `tsh` on your local workstation:
(!docs/pages/includes/install-tsh.mdx!)
Log in to receive short-lived certificates from Teleport:
```code
# Replace teleport.example.com with your Teleport cluster's public address as configured above.
$ tsh login --proxy=<Var name="teleport.example.com" /> --user=teleport-admin
> Profile URL: https://teleport.example.com:443
Logged in as: teleport-admin
Cluster: teleport.example.com
Roles: access, editor
Logins: root, ubuntu, ec2-user
Kubernetes: enabled
Valid until: 2022-04-26 03:04:46 -0400 EDT [valid for 12h0m0s]
Extensions: permit-agent-forwarding, permit-port-forwarding, permit-pty
```
</Details>
## Step 4/4. Enroll your infrastructure
With Teleport, you can protect all of the resources in your infrastructure
behind a single identity-aware access proxy, including servers, databases,
applications, Kubernetes clusters, Windows desktops, and cloud provider APIs.
To enroll a resource with Teleport, visit the Web UI and click the name of a
resource on the sidebar, e.g., **Servers**, **Applications**, and
**Kubernetes**. The Web UI will show you the steps you can take to enroll that
resource.
![Adding resources](../img/add-resources.png)
In the **Servers** tab, you can see that you have already enrolled your Linux
server.
## Next steps
Now that you have launched your Teleport cluster and added your first resources,
see how to use Teleport to set up secure access to your infrastructure.
Read the [Manage Access](./access-controls/introduction.mdx) documentation to
get started setting up role-based access controls for all of the resources you
registered.
To learn about common Day Two operations when managing a Teleport cluster, read
the [Manage your Cluster](./management/introduction.mdx) guides.
You can also read more about how to protect your infrastructure with Teleport,
including:
- [Applications](./application-access/introduction.mdx)
- [Databases](./database-access/introduction.mdx)
- [Kubernetes clusters](./kubernetes-access/introduction.mdx)
- [Servers](./server-access/introduction.mdx)
- [Windows desktops](./desktop-access/introduction.mdx)
- [Service accounts](./machine-id/introduction.mdx) (via Machine ID)
## Further reading
- How Let's Encrypt uses the [ACME protocol](https://letsencrypt.org/how-it-works/) to issue certificates.
- Configuration for the `teleport` daemon relies on [systemd](https://www.freedesktop.org/wiki/Software/systemd/). For more information on how the
`teleport` service daemon is configured, see our guide on how to [Run Teleport as a Daemon](management/admin/daemon.mdx).

4
docs/pages/includes/database-access/alternative-methods-join.mdx
View file

@ -6,7 +6,7 @@ Teleport:
- [Configure Teleport to Automatically Enroll EC2 instances (Preview)](../../server-access/guides/ec2-discovery.mdx)
- [Joining Teleport Services via AWS IAM
Role](../../management/join-services-to-your-cluster/aws-iam.mdx)
- [Joining Teleport Services via AWS EC2 Identity Document](../../management/join-services-to-your-cluster/aws-ec2.mdx)
Role](../../agents/join-services-to-your-cluster/aws-iam.mdx)
- [Joining Teleport Services via AWS EC2 Identity Document](../../agents/join-services-to-your-cluster/aws-ec2.mdx)
</Details>

2
docs/pages/includes/edition-prereqs-tabs.mdx
View file

@ -2,7 +2,7 @@
<TabItem scope={["oss"]} label="Open Source">
- A running Teleport cluster. For details on how to set this up, see our
[Getting Started](../get-started.mdx) guide.
[Getting Started](../index.mdx) guide.
- The `tctl` admin tool and `tsh` client tool version >= (=teleport.version=).

13
docs/pages/includes/tls-certificate-setup.mdx
View file

@ -21,19 +21,6 @@ deployments, use your own private key and certificate.
$ teleport configure --acme --acme-email=<Var name="user@example.com" description="Your email address to register with Let's Encrypt for TLS certificates" /> --cluster-name=<Var name="tele.example.com" description="The domain name of your Teleport cluster" /> | sudo tee /etc/teleport.yaml > /dev/null
```
The `--acme`, `--acme-email`, and `--cluster-name` flags will add the following
settings to your Teleport configuration file:
```yaml
proxy_service:
enabled: "yes"
web_listen_addr: 0.0.0.0:443
public_addr: tele.example.com:443
acme:
enabled: "yes"
email: user@example.com
```
Port 443 on your Teleport Proxy Service host must allow traffic from all sources.
</TabItem>

327
docs/pages/index.mdx
View file

@ -1,175 +1,220 @@
---
title: Introduction to Teleport
description: Teleport is an identity-aware, multi-protocol access proxy with native support for SSH, RDP, Kubernetes, and more. Get started with the Teleport documentation.
layout: tocless-doc
videoBanner: ki-uVTSocGE
title: Get Started with Teleport
description: This tutorial will guide you through the steps needed to install and run Teleport on a Linux server
videoBanner: BJWbSqiDLeU
tocDepth: 3
---
Teleport is an identity-aware, multi-protocol access proxy. Teleport understands
the SSH, HTTPS, RDP, Kubernetes API, MySQL, MongoDB and PostgreSQL wire
protocols, plus many others.
protocols, plus many others. It can integrate with Single Sign-On providers and
enables you to apply access policies using infrastructure-as-code and GitOps
tools.
With Teleport you can:
See how Teleport works by completing the tutorial below. This shows you how to
spin up a single-instance Teleport cluster on a Linux server using Teleport
Community Edition. Once you deploy the cluster, you can configure RBAC, register
resources, and protect your small-scale demo environments or home lab.
- Replace a mix of vaults, passwords, API keys and tokens with short-lived SSH and X.509 certs.
- Have a single access point and Single-Sign-On provider for all of your
infrastructure, including SSH servers, Kubernetes clusters, databases,
desktops, web applications, and more.
- Write policies with Terraform or Kubernetes resources for all clouds,
environments and protocols and manage them with GitOps.
- Record SSH and `kubectl exec` sessions, DB queries, Windows desktop sessions,
web sessions and API requests.
- Use mutual TLS tunnels to protect your infrastructure endpoints.
You can also get started right away with a production-ready Teleport cluster by
signing up for a [free trial of Teleport
Team](./choose-an-edition/teleport-team.mdx).
<Notice type="info">
## Set up a demo cluster
If your organization is already using Teleport and you want to learn how to
access infrastructure, read our [Connect your
Client](./connect-your-client/introduction.mdx) guides for instructions.
<Figure width="700">
![Architecture of the setup you will complete in this
guide](../img/linux-server-diagram.png)
</Figure>
</Notice>
We will run the following Teleport services:
## Try out Teleport
- **Teleport Auth Service:** The certificate authority for your cluster. It
issues certificates and conducts authentication challenges. The Auth Service
is typically inaccessible outside your private network.
- **Teleport Proxy Service:** The cluster frontend, which handles user requests,
forwards user credentials to the Auth Service, and communicates with Teleport
instances that enable access to specific resources in your infrastructure.
- **Teleport SSH Service:** An SSH server implementation that takes advantage of
Teleport's short-lived certificates, sophisticated RBAC, session recording,
and other features.
If you are curious to see how Teleport works, you can get started by [spinning
up a demo cluster](./get-started.mdx) on a Linux server. After seeing how your
demo Teleport cluster lets you securely access a server and play back your SSH
sessions, you can configure RBAC, add resources, and protect your home lab with
Teleport.
You can also get started right away with a production-ready Teleport cluster.
[Sign up for a free trial](https://goteleport.com/signup/) of Teleport
Team.
Once you are ready to learn more about Teleport, read our [Core Concepts
guide](./core-concepts.mdx), which introduces the components of a Teleport
cluster. You can refer to this glossary as you continue through the
documentation.
## Choose an edition
After trying out Teleport, you are ready to deploy a cluster to your
infrastructure. Teleport has four editions:
- Teleport Team
- Teleport Enterprise Cloud
- Teleport Enterprise
- Teleport Community Edition
You can compare these in our [Choose an
Edition](./choose-an-edition/introduction.mdx) section.
### Prerequisites
<Notice type="tip">
You can view information specific to an edition of Teleport by using the "Open
Source", "Enterprise", and "Cloud" buttons at the top of the page.
You will need the following to deploy a demo Teleport cluster. If your
environment doesn't meet the prerequisites above, you can get started with
Teleport by signing up for a [free trial of Teleport
Team](https://goteleport.com/signup/).
</Notice>
## Deploy a cluster
- A Linux host with only port `443` open to ingress traffic. You must be able
to install and run software on the host. Either configure access to the host
via SSH for the initial setup (and open an SSH port in addition port `443`)
or enter the commands in this guide into an Amazon EC2 [user data
script](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/user-data.html),
Google Compute Engine [startup
script](https://cloud.google.com/compute/docs/instances/startup-scripts),
or similar.
Once you know which edition you would like to deploy, read our [Deploy a
Cluster](./deploy-a-cluster/introduction.mdx) documentation for how to launch a
fully fledged Teleport cluster in production. (If you are using Teleport
Enterprise Cloud, you can skip this step.) This section shows you the best
practices to follow for a high-availability Teleport cluster, and how to deploy
Teleport on your cloud provider of choice.
<Admonition type="tip" title="Quick demo environments">
## Manage access
For a quick demo environment you can use to follow this guide, consider
installing our DigitalOcean 1-Click droplet. View the installation page on
[DigitalOcean
Marketplace](https://marketplace.digitalocean.com/apps/teleport). Once your
droplet is ready, SSH into the droplet and follow the configuration wizard.
Now that you have a running Teleport cluster, set up role-based access controls
to enable secure access to your infrastructure. You can define roles with
granular permissions and use Teleport's integrations with Single Sign-On
providers to automatically map these roles to users. You can also set up Access
Requests to enable just-in-time access to your infrastructure. Read [Manage
Access](./access-controls/introduction.mdx) to get started.
</Admonition>
## Manage your cluster
- A two-factor authenticator app such as [Authy](https://authy.com/download/),
[Google Authenticator](https://www.google.com/landing/2step/), or
[1Password](https://support.1password.com/one-time-passwords/).
With your Teleport cluster configured, you can now begin Day Two operations
such as upgrades, adding agents to the cluster, and integrating Teleport with
third-party tools. Read [Manage your
Cluster](./management/introduction.mdx) for more information.
You must also have **one** of the following:
- A registered domain name.
- An authoritative DNS nameserver managed by your organization, plus an existing
certificate authority. If using this approach, ensure that your browser is
configured to use your organization's nameserver.
## Add your infrastructure
### Step 1/4. Configure DNS
Teleport is protocol aware and provides functionality that is unique to each
protocol it supports. To enable access to a protocol, deploy the appropriate
Teleport service and configure it to communicate with resources in your
infrastructure.
Teleport uses TLS to provide secure access to its Proxy Service and Auth
Service, and this requires a domain name that clients can use to verify
Teleport's certificate. Set up two DNS `A` records, each pointing to the IP
address of your Linux host. Assuming `teleport.example.com` is your domain name,
set up records for:
Read about how to enable access to:
|Domain|Reason|
|---|---|
|`teleport.example.com`|Traffic to the Proxy Service from users and services.|
|`*.teleport.example.com`|Traffic to web applications registered with Teleport. Teleport issues a subdomain of your cluster's domain name to each application.|
- [Servers](./server-access/getting-started.mdx), including OpenSSH servers that
[do not have Teleport installed](./server-access/guides/openssh.mdx)
- [Kubernetes clusters](./kubernetes-access/introduction.mdx)
- [Databases](./database-access/introduction.mdx)
- [Applications](./application-access/introduction.mdx)
- [Remote desktops](./desktop-access/introduction.mdx)
### Step 2/4. Set up Teleport on your Linux host
You can also set up [Machine ID](./machine-id/introduction.mdx) to enable
service accounts to access resources in your infrastructure with short-lived
credentials.
#### Install Teleport
## Extend Teleport for your organization
On your Linux host, run the following command to install the Teleport binary:
Teleport is highly customizable, exposing much of its functionality via a gRPC
API. For example, you can build API clients to register infrastructure
automatically or manage Access Requests using your organization's unique
workflows. Read how to build applications that interact with Teleport's API in
our [API guides](./api/introduction.mdx).
```code
$ curl https://goteleport.com/static/install.sh | bash -s (=teleport.version=)
```
## Learn more about Teleport
#### Configure Teleport
Get more information about Teleport by reading our library of architecture,
reference, and developer guides. See the
[Upcoming Releases](./upcoming-releases.mdx) section for a glimpse of features we
will release in the next Teleport version. Consult our
[Reference](./reference/introduction.mdx) guides for comprehensive lists of
configuration options, CLI flags, and more. For detailed explanations of how
Teleport works, see the [Architecture](./architecture/introduction.mdx) section.
Generate a configuration file for Teleport using the `teleport configure` command.
This command requires information about a TLS certificate and private key.
Finally, if you're interested in adding to Teleport's documentation, view
our [contribution guide](./contributing/documentation.mdx).
(!docs/pages/includes/tls-certificate-setup.mdx!)
<TileSet>
<TileList title="For developers" icon="stack">
<TileListItem href="./connect-your-client/tsh.mdx#sharing-sessions">
Collaborate through session sharing.
</TileListItem>
<TileListItem href="./management/admin/labels.mdx">
Discover servers and clusters with dynamic labels.
</TileListItem>
<TileListItem href="./management/admin/adding-nodes.mdx#adding-a-node-located-behind-nat">
Connect to computing resources located behind firewalls or without static IPs.
</TileListItem>
</TileList>
<TileList title="For security teams" icon="lock">
<TileListItem href="./server-access/guides/openssh.mdx">
Capture sessions and manage certificates for an existing OpenSSH fleet.
</TileListItem>
<TileListItem href="./architecture/authentication.mdx#issuing-user-certificates">
Replace static keys and passwords with short-lived certificates.
</TileListItem>
<TileListItem href="./access-controls/guides/webauthn.mdx">
Enforce two-factor authentication for all of your infrastructure.
</TileListItem>
</TileList>
<TileList title="Reach out" icon="question">
<TileListItem href="https://github.com/gravitational/teleport/discussions">
Ask a question in the discussion forum.
</TileListItem>
<TileListItem href="https://goteleport.com/slack">
Join our Slack channel to get help with your setup.
</TileListItem>
<TileListItem href="https://github.com/gravitational/teleport/">
Create an issue on GitHub.
</TileListItem>
<TileListItem href="https://goteleport.com/get-started/">
Reach out to sales for a demo of Teleport Enterprise.
</TileListItem>
<TileListItem href="https://goteleport.com/signup/">
Start a free trial of Teleport Cloud.
</TileListItem>
</TileList>
</TileSet>
#### Start Teleport
(!docs/pages/includes/start-teleport.mdx!)
Access Teleport's Web UI via HTTPS at the domain you created earlier (e.g.,
`https://teleport.example.com`). You should see a welcome screen similar to the
following:
![Teleport Welcome Screen](../img/quickstart/welcome.png)
### Step 3/4. Create a Teleport user and set up two-factor authentication
In this step, we'll create a new Teleport user, `teleport-admin`, which is
allowed to log into SSH hosts as any of the principals `root`, `ubuntu`, or
`ec2-user`.
On your Linux host, run the following command:
```code
# tctl is an administrative tool that is used to configure Teleport's auth service.
$ sudo tctl users add teleport-admin --roles=editor,access --logins=root,ubuntu,ec2-user
```
The command prints a message similar to the following:
```text
User "teleport-admin" has been created but requires a password. Share this URL with the user to complete user setup, link is valid for 1h:
https://teleport.example.com:443/web/invite/123abc456def789ghi123abc456def78
NOTE: Make sure teleport.example.com:443 points at a Teleport proxy which users can access.
```
Visit the provided URL in order to create your Teleport user.
<Admonition
type="tip"
title="OS User Mappings"
>
The users that you specify in the `logins` flag (e.g., `root`, `ubuntu` and
`ec2-user` in our examples) must exist on your Linux host. Otherwise, you
will get authentication errors later in this tutorial.
If a user does not already exist, you can create it with `adduser <login>` or
use [host user creation](./server-access/guides/host-user-creation.mdx).
If you do not have the permission to create new users on the Linux host, run
`tctl users add teleport $(whoami)` to explicitly allow Teleport to
authenticate as the user that you have currently logged in as.
</Admonition>
Teleport enforces the use of two-factor authentication by default. It supports
one-time passwords (OTP) and second-factor authenticators (WebAuthn). In this
guide, you will need to enroll an OTP authenticator application using the QR
code on the Teleport welcome screen.
<Details title="Logging in via the CLI">
In addition to Teleport's Web UI, you can access resources in your
infrastructure via the `tsh` client tool.
Install `tsh` on your local workstation:
(!docs/pages/includes/install-tsh.mdx!)
Log in to receive short-lived certificates from Teleport:
```code
# Replace teleport.example.com with your Teleport cluster's public address as configured above.
$ tsh login --proxy=<Var name="teleport.example.com" /> --user=teleport-admin
> Profile URL: https://teleport.example.com:443
Logged in as: teleport-admin
Cluster: teleport.example.com
Roles: access, editor
Logins: root, ubuntu, ec2-user
Kubernetes: enabled
Valid until: 2022-04-26 03:04:46 -0400 EDT [valid for 12h0m0s]
Extensions: permit-agent-forwarding, permit-port-forwarding, permit-pty
```
</Details>
### Step 4/4. Enroll your infrastructure
With Teleport, you can protect all of the resources in your infrastructure
behind a single identity-aware access proxy, including servers, databases,
applications, Kubernetes clusters, Windows desktops, and cloud provider APIs.
To enroll a resource with Teleport, visit the Web UI and click the name of a
resource on the sidebar, e.g., **Servers**, **Applications**, and
**Kubernetes**. The Web UI will show you the steps you can take to enroll that
resource.
![Adding resources](../img/add-resources.png)
In the **Servers** tab, you can see that you have already enrolled your Linux
server.
### Next step: deploy agents
Teleport **agents** proxy traffic to infrastructure resources like servers,
databases, Kubernetes clusters, cloud provider APIs, and Windows desktops.
Step 4 showed you how to install agents manually, and you can also launch agents
and enroll resources with them using infrastructure-as-code tools. For example,
you can use Terraform to declare a pool of Teleport agents and configure them to
proxy your infrastructure. Read [Deploy Teleport Agents with
Terraform](agents/deploy-agents-terraform.mdx) to get started.

4
docs/pages/installation.mdx
View file

@ -13,7 +13,7 @@ including:
- `tbot`
If you are new to Teleport, we recommend following our [getting started
guide](./get-started.mdx).
guide](./index.mdx).
For best results, Teleport clients (`tsh`, `tctl`, `tbot`) should be the same major
version as the cluster they are connecting to. Teleport servers are compatible
@ -253,7 +253,7 @@ Services on a local Docker container using Teleport Community Edition.
Since this container uses a self-signed certificate, we do not recommend using
this configuration to protect any infrastructure outside your workstation. You
can, however, join other local Docker containers to it using the [token
method](./management/join-services-to-your-cluster/join-token.mdx).
method](./agents/join-services-to-your-cluster/join-token.mdx).
First, create directories in your home directory to mount to the container. The
Teleport container will write its configuration and data to these directories:

2
docs/pages/machine-id/getting-started.mdx
View file

@ -71,7 +71,7 @@ auditor no-login-6566121f-b602-47f1-a118-c9c618ee5aec session:list,r
editor user:list,create,read,update,delete,...
```
Machine ID can join with a token or the [IAM Method](../management/join-services-to-your-cluster/aws-iam.mdx) on AWS.
Machine ID can join with a token or the [IAM Method](../agents/join-services-to-your-cluster/aws-iam.mdx) on AWS.
Assuming that you are using the default `access` role, ensure that you use the
`--logins` flag when adding your bot to specify the SSH logins that you wish to

2
docs/pages/machine-id/guides/host-certificate.mdx
View file

@ -402,6 +402,6 @@ to connect to OpenSSH with Teleport, see the following documentation:
- [Using Teleport With OpenSSH](../../server-access/guides/openssh.mdx)
- [Using SSH Host Certificates](https://goteleport.com/blog/how-to-ssh-properly/)
- [Machine ID Configuration Reference](../reference/configuration.mdx)
- [Joining Nodes using the IAM method](../../management/join-services-to-your-cluster/aws-ec2.mdx)
- [Joining Nodes using the IAM method](../../agents/join-services-to-your-cluster/aws-ec2.mdx)
[More information about `TELEPORT_ANONYMOUS_TELEMETRY`.](../reference/telemetry.mdx)

4
docs/pages/management/admin/self-signed-certs.mdx
View file

@ -34,7 +34,7 @@ to the Proxy Service.
<TabItem scope={["oss"]} label="Open Source">
- A running Teleport cluster. For details on how to set this up, see our
[Getting Started](../../get-started.mdx) guide (skip TLS certificate setup).
[Getting Started](../../index.mdx) guide (skip TLS certificate setup).
- A Teleport Proxy Service which does not have certificates or ACME automatic certificates configured.
For example, this Teleport Proxy Service configuration would use self-signed certs:
@ -205,7 +205,7 @@ flag](../../connect-your-client/teleport-connect.mdx#skipping-tls-certificate-ve
## Further reading
- [Configuring Teleport TLS Certs](../../get-started.mdx#configure-teleport)
- [Configuring Teleport TLS Certs](../../index.mdx#configure-teleport)
- [Run Teleport as a systemd Daemon](./daemon.mdx)
- [Teleport Proxy Service](../../architecture/proxy.mdx)
- [Teleport Authentication](../../architecture/authentication.mdx)

17
docs/pages/management/admin/trustedclusters.mdx
View file

@ -27,7 +27,7 @@ A leaf cluster always creates an outbound reverse SSH tunnel to the root cluster
<Notice type="tip">
Individual nodes and proxies can create reverse tunnels to proxy services without creating a new cluster.
You don't need to set up a trusted cluster just to connect a couple of servers, kubernetes clusters or
databases behind a firewall. For more information, see [Adding Nodes to the Cluster](../join-services-to-your-cluster/join-token.mdx).
databases behind a firewall. For more information, see how to [join a service to your cluster](../../agents/join-services-to-your-cluster.mdx).
</Notice>
When a user tries to connect to any resource inside the leaf cluster using the root's proxy
@ -45,16 +45,17 @@ This guide will explain how to:
<TabItem scope={["oss"]} label="Open Source">
- Two running Teleport clusters. For details on how to set up your clusters, see
our [Getting Started](../../get-started.mdx) guide.
our [Getting Started](../../index.mdx) guide.
- (!docs/pages/includes/tctl-tsh-prerequisite.mdx!)
See [Installation](../../installation.mdx) for details.
- A Teleport Node that is joined to one of your clusters. We will refer to this
- A Teleport agent that is joined to one of your clusters. We will refer to this
cluster as the **leaf cluster** throughout this guide.
See [Joining Services to your Cluster](../join-services-to-your-cluster.mdx) for how to launch a
See [Join Services to your
Cluster](../../agents/join-services-to-your-cluster.mdx) for how to launch a
Teleport agent in your cluster.
</TabItem>
@ -70,7 +71,7 @@ This guide will explain how to:
- A Teleport Node that is joined to one of your clusters. We will refer to this
cluster as the **leaf cluster** throughout this guide.
See [Adding Nodes](../join-services-to-your-cluster.mdx) for how to launch a Teleport Node in
See [Join Services to your Cluster](../../agents/join-services-to-your-cluster.mdx) for how to launch a Teleport agent in
your cluster.
</TabItem>
@ -82,7 +83,7 @@ This guide will explain how to:
- A second Teleport cluster, which will act as the leaf cluster. For details on
how to set up this cluster, see our
[Getting Started](../../get-started.mdx) guide.
[Getting Started](../../index.mdx) guide.
As an alternative, you can set up a second Teleport Cloud account.
@ -91,8 +92,8 @@ how to set up this cluster, see our
- A Teleport Node that is joined to one of your clusters. We will refer to this
cluster as the **leaf cluster** throughout this guide.
See [Adding Nodes](../join-services-to-your-cluster.mdx) for how to launch a
Teleport Node in your cluster.
See [Join Services to your Cluster](../../agents/join-services-to-your-cluster.mdx) for how to launch a
Teleport agent in your cluster.
</TabItem>
</Tabs>

276
docs/pages/management/dynamic-resources.mdx Normal file
View file

@ -0,0 +1,276 @@
---
title: Using Dynamic Resources
description: An introduction to Teleport's dynamic resources, which make it possible to apply settings to remote clusters using infrastructure as code.
tocDepth: 3
---
This section explains how to manage Teleport's **dynamic resources**, which make
it possible to adjust the behavior of your Teleport cluster as your
infrastructure changes.
## What is a dynamic resource?
There are two ways to configure a Teleport cluster:
- **Static configuration file:** At startup, a Teleport process reads a
configuration file from the local filesystem (the default path is
`/etc/teleport.yaml`). Static configuration settings control aspects of a
cluster that are not expected to change frequently, like the ports that
services listen on.
- **Dynamic resources:** Dynamic resources control aspects of your cluster that
are likely to change over time, such as roles, local users, and registered
infrastructure resources.
This approach makes it possible to incrementally adjust your Teleport
configuration without restarting Teleport instances.
```mermaid
flowchart LR
subgraph backend["Cluster state backend"]
direction LR
resources["Dynamic resources"]
end
subgraph cluster[Teleport cluster]
subgraph auth[Auth Service]
conf1["Static config"]
end
subgraph proxy[Proxy Service]
conf2["Static config"]
end
end
auth-->backend
subgraph clients["API clients"]
terraform["Terraform Provider"]
operator["Kubernetes Operator"]
tctl
end
terraform & operator & tctl-->proxy
proxy-.->auth
```
A cluster is composed of different objects (i.e., resources) and there are three
common operations that can be performed on them: `get` , `create` , and `remove`
.
Every resource in Teleport has three required fields:
- `kind`: The type of resource
- `name`: A required field in the `metadata` to uniquely identify the resource
- `version`: The version of the resource format
All other fields are specific to a resource.
While Teleport Enterprise Cloud and Teleport Team do not expose the static
configuration file to operators, they do use a static configuration file for
certain settings. Read how Teleport [reconciles static and dynamic
resources](#reconciling-the-configuration-file-with-dynamic-resources) to
understand how to see the values of static configuration settings that also
appear in dynamic resources.
When examining a dynamic resource, note that some of the fields you will see are
used only internally and are not meant to be changed. Others are reserved for
future use.
## Managing dynamic resources
Teleport provides three methods for applying dynamic resources: the `tctl`
client tool, Teleport Terraform provider, and Kubernetes Operator.
All three methods connect to the Teleport Auth Service's gRPC endpoint in order
to manipulate cluster resources stored on the Auth Service backend. The design
of Teleport's configuration interface makes it well suited for
infrastructure-as-code and GitOps approaches.
### YAML documents with `tctl`
You can define resources as YAML documents and apply them using the `tctl`
client tool. Here is an example of a `role` resource that allows access to
servers with the label `env:test`:
```yaml
kind: role
version: v6
metadata:
name: developer
spec:
allow:
logins: ['ubuntu', 'debian', '{{internal.logins}}']
node_labels:
'env': 'test'
```
Since `tctl` works from the local filesystem, you can write commands that apply
all configuration documents in a directory tree. See the [CLI
reference](../reference/cli.mdx#tctl) for more information on `tctl`.
### Teleport Terraform provider
Teleport's Terraform provider lets you manage your Teleport resources within the
same infrastructure-as-code source as the rest of your infrastructure. There is
a Terraform resource for each Teleport configuration resource. For example:
```text
resource "teleport_role" "developer" {
metadata = {
name = "developer"
}
spec = {
allow = {
logins = ["ubuntu", "debian", "{{internal.logins}}"]
node_labels = {
key = ["env"]
value = ["test"]
}
}
}
}
```
[Get started with the Terraform provider](./dynamic-resources/terraform-provider.mdx).
### Teleport Kubernetes Operator
The Teleport Kubernetes Operator lets you apply Teleport resources as Kubernetes
resources so you can manage your Teleport settings alongside the rest of your
Kubernetes infrastructure. Here is an example of a `TeleportRole` resource,
which is equivalent to the two roles shown above:
```yaml
apiVersion: resources.teleport.dev/v5
kind: TeleportRole
metadata:
name: developer
spec:
allow:
logins: ['ubuntu', 'debian', '{{internal.logins}}']
node_labels:
'env': 'test'
```
[Get started with the Kubernetes Operator](dynamic-resources/teleport-operator.mdx).
## Reconciling the configuration file with dynamic resources
Some dynamic resources assign the same settings as fields within
Teleport's static configuration file. For these fields, the Teleport Auth
Service reconciles static and dynamic configurations on startup and when you
create or remove a Teleport resource.
### Configuration resources that apply to static configuration fields
There are four dynamic resources that share fields with the
static configuration file:
- `session_recording_config`
- `cluster_auth_preference`
- `cluster_networking_config`
- `ui_config`
#### `session_recording_config`
|Dynamic resource field|Static configuration field|
|---|---|
|`spec.mode`|`auth_service.session_recording`|
|`spec.proxy_checks_host_keys`|`auth_service.proxy_checks_host_keys`|
#### `cluster_auth_preference`
|Dynamic resource field|Static configuration field|
|---|---|
|`spec.type`|`auth_service.authentication.type`|
|`spec.second_factor`|`auth_service.authentication.second_factor`|
|`spec.connector_name`|`auth_service.authentication.connector_name`
|`spec.u2f`|`auth_service.authentication.u2f`|
|`spec.disconnect_expired_cert`|`auth_service.disconnect_expired_cert`|
|`spec.allow_local_auth`|`auth_service.authentication.local_auth`|
|`spec.message_of_the_day`|`auth_service.message_of_the_day`|
|`spec.locking_mode`|`auth_service.authentication.locking_mode`|
|`spec.webauthn`|`auth_service.authentication.webauthn`|
|`spec.require_session_mfa`|`auth_service.authentication.require_session_mfa`|
|`spec.allow_passwordless`|`auth_service.authentication.passwordless`|
|`spec.device_trust`|`auth_service.authentication.device_trust`|
|`spec.idp`|`proxy_service.idp`|
|`spec.allow_headless`|`auth_service.authentication.headless`|
#### `cluster_networking_config`
|Dynamic resource field|Static configuration field|
|---|---|
|`spec.client_idle_timeout`|`auth_service.client_idle_timeout`|
|`spec.keep_alive_interval`|`auth_service.keep_alive_interval`|
|`spec.keep_alive_count_max`|`auth_service.keep_alive_count_max`|
|`spec.session_control_timeout`|`auth_service.session_control_timeout`|
|`spec.idle_timeout_message`|`auth_service.client_idle_timeout_message`|
|`spec.web_idle_timeout`|`auth_service.web_idle_timeout`|
|`spec.proxy_listener_mode`|`auth_service.proxy_listener_mode`|
|`spec.routing_strategy`|`auth_service.routing_strategy`|
|`spec.tunnel_strategy`|`auth_service.tunnel_strategy`|
|`spec.proxy_ping_interval`|`auth_service.proxy_ping_interval`|
#### `ui_config`
|Dynamic resource field|Static configuration field|
|---|---|
|`spec.scrollback_lines`|`proxy_service.ui.scrollback_lines`|
### Origin labels
The Teleport Auth Service applies the `teleport.dev/origin` label to
configuration resources to indicate whether they originated from the static
configuration file, a dynamic configuration resource, or the default value.
Here are possible values of the `teleport.dev/origin` label:
- `defaults`
- `config-file`
- `dynamic`
When the Auth Service starts up, it looks up the values of static configuration
fields that correspond to fields in dynamic configuration resources. If any of
these have values, it creates the corresponding dynamic configuration resources
and stores them in its backend.
For any static configuration fields without a value, the Auth Service checks
whether the backend contains the corresponding dynamic configuration resource.
If not, it creates one with default values and the
`teleport.dev/origin=defaults` label.
If you attempt to create a dynamic configuration resource after the Auth Service
has already loaded the configuration from a static configuration file, the Auth
Service will return an error.
If you remove a dynamic configuration resource, the Auth Service will restore
its configuration fields to the default values and add the
`teleport.dev/origin=defaults` label.
<Notice type="tip">
Cloud-hosted Teleport deployments use configuration files, but these are not
available for operators to modify. Users of Teleport Enterprise Cloud and
Teleport Team may see configuration resources with the
`teleport.dev/origin=config-file` label.
</Notice>
## Further reading
### Configuration references
- For a comprehensive reference of Teleport's static configuration options, read
the [Configuration Reference](../reference/config.mdx).
- To see the dynamic configuration resources available to apply, read the
[Configuration Resource Reference](../reference/resources.mdx). There are also
dedicated configuration resource references for
[applications](../application-access/reference.mdx#application-resource) and
[databases](../database-access/reference/configuration.mdx#database-resource).
### Other ways to use the Teleport API
The Teleport Kubernetes Operator, Terraform provider, and `tctl` are all clients
of the Teleport Auth Service's gRPC API. To build your own API client to extend
Teleport for your organization's needs, read our [API
guides](../api/introduction.mdx).

0
docs/pages/management/guides/teleport-operator.mdx → docs/pages/management/dynamic-resources/teleport-operator.mdx
View file

0
docs/pages/management/guides/terraform-provider.mdx → docs/pages/management/dynamic-resources/terraform-provider.mdx
View file

17
docs/pages/management/guides.mdx
View file

@ -1,10 +1,15 @@
---
title: Setup Guides
description: Teleport Installation and Configuration Guides.
title: Integrations
description: Miscellaneous guides for integrating Teleport with third-party tools.
layout: tocless-doc
---
- [Kubernetes Operator (Preview)](./guides/teleport-operator.mdx). How to add the Teleport Kubernetes Operator to your Kubernetes cluster.
- [Terraform Provider](./guides/terraform-provider.mdx). How to configure Teleport Cloud, Open Source, and Enterprise with the Terraform Provider for Teleport.
- [EC2 tags as Teleport Nodes](./guides/ec2-tags.mdx). How to set up Teleport Node labels based on EC2 tags.
- [Using Teleport's Certificate Authority with GitHub](./guides/ssh-key-extensions.mdx). Use Teleport's short-lived certificates with GitHub's Certificate Authority.
You can integrate Teleport with third-party tools in order to complete various
tasks in your cluster. These guides describe Teleport integrations that are not
documented elsewhere:
- [EC2 tags as Teleport Node labels](./guides/ec2-tags.mdx). How to set up
Teleport Node labels based on EC2 tags.
- [Using Teleport's Certificate Authority with
GitHub](./guides/ssh-key-extensions.mdx). Use Teleport's short-lived
certificates with GitHub's Certificate Authority.

4
docs/pages/management/guides/ec2-tags.mdx
View file

@ -27,8 +27,8 @@ fakehost.example.com 127.0.0.1:3022 env=example,hostname=ip-172-31-53-70,aws/Nam
## Prerequisites
(!docs/pages/includes/edition-prereqs-tabs.mdx!)
- One Teleport Node running on an Amazon EC2 instance. See
[Adding Nodes](../join-services-to-your-cluster.mdx) for how to set up a Teleport Node.
- One Teleport agent running on an Amazon EC2 instance. See
[our guides](../../agents/join-services-to-your-cluster.mdx) for how to set up Teleport agents.
## Enable tags in instance metadata

20
docs/pages/management/introduction.mdx
View file

@ -7,14 +7,20 @@ layout: tocless-doc
In this section, you can find guides on managing a Teleport cluster after
deploying it.
## Join Teleport services to your cluster
## Use dynamic resources
Protect resources in your infrastructure with Teleport by joining Teleport
services to proxy those resources. To do this, start a Teleport process that
runs one or more services. The Teleport process establishes a trust relationship
with your Teleport cluster through a variety of methods. Read [Joining Teleport
Services to a Cluster](./join-services-to-your-cluster.mdx) for a detailed
explanation of each method.
In Teleport, **dynamic resources** let you adjust the behavior of your Teleport
cluster as your infrastructure changes. Teleport provides three methods for
applying dynamic resources: the `tctl` client tool, Teleport Terraform provider,
and Kubernetes Operator. Read [Using Dynamic Resources](./dynamic-resources.mdx)
for more information.
## Configure your cluster
Get to know the [tools you can use](./dynamic-resources.mdx) to apply
settings to your cluster, all of which work well with infrastructure-as-code
solutions, including the `tctl` client, Terraform provider, and Kubernetes
Operator.
## Admin guides

2
docs/pages/management/operations/ca-rotation.mdx
View file

@ -14,7 +14,7 @@ description: How to rotate Teleport's certificate authority
This section will show you how to rotate Teleport's certificate authority.
If you are joining Teleport processes to a cluster via the Teleport Auth Service
using a [join token](../join-services-to-your-cluster/join-token.mdx), each
using a [join token](../../agents/join-services-to-your-cluster/join-token.mdx), each
Teleport process will need a CA pin to trust the Auth Service. The CA pin will
change after each CA rotation. Make sure you use the *new* CA pin when adding
Teleport services after rotation.

6
docs/pages/reference/helm-reference/teleport-kube-agent.mdx
View file

@ -301,9 +301,9 @@ These sub-values must be configured for the agent to connect to a cluster.
Possible values are `token`, `iam` and `ec2`.
- For `iam`, see [Joining Nodes Via AWS IAM
Role](../../management/join-services-to-your-cluster/aws-iam.mdx).
Role](../../agents/join-services-to-your-cluster/aws-iam.mdx).
- For `ec2`, see [Joining Nodes Via AWS IAM
Role](../../management/join-services-to-your-cluster/aws-ec2.mdx).
Role](../../agents/join-services-to-your-cluster/aws-ec2.mdx).
- For `token` (default value), the token must be provided through `joinParams.tokenName` or
[through an existing Kubernetes Secret](#joinTokenSecret).
@ -692,7 +692,7 @@ If you want to run Teleport version `X.Y.Z`, you should use
When `caPin` is set, the Teleport pod will use its values to check the
Auth Service's identity when first joining a cluster. This enables a more secure
way of adding new Teleport instances to a cluster. See
["Adding Nodes to the Cluster"](../../management/join-services-to-your-cluster/join-token.mdx).
["Adding Nodes to the Cluster"](../../agents/join-services-to-your-cluster/join-token.mdx).
Each list element can be the pin itself (recommended, works out of the box),
or a path to a file containing the pin. For the latter it is your

159
docs/pages/reference/resources.mdx
View file

@ -1,130 +1,13 @@
---
title: Teleport Resources Reference
description: The detailed reference documentation for Teleport Configuration Resources
h1: Teleport Configuration Resources Reference
title: Teleport Resource Reference
description: Reference documentation for Teleport resources
---
## Introduction
This reference guide lists dynamic resources you can manage with Teleport. For
more information on dynamic resources, see our guide to [Using Dynamic
Resources](../management/dynamic-resources.mdx).
<Tabs>
<TabItem scope={["oss", "enterprise"]} label="Self-Hosted">
A Teleport administrator has two tools to configure a Teleport cluster:
- The [configuration file](./config.mdx) is used for static configuration
settings such as the cluster name.
- The [`tctl`](./cli.mdx#tctl) admin tool is used for configuring the Teleport
Auth Service, and can be used to manage dynamic records like Teleport users.
</TabItem>
<TabItem scope={["cloud"]} label="Teleport Cloud">
A Teleport administrator can configure a Teleport cluster by using the
[`tctl`](./cli.mdx#tctl) admin tool to manage dynamic records like Teleport
users.
</TabItem>
</Tabs>
- (!docs/pages/includes/tctl.mdx!)
### `tctl` concepts
[`tctl`](./cli.mdx#tctl) has convenient sub-commands for dynamic
configuration, such as `tctl users` or `tctl nodes`.
For more advanced management tasks, like connecting clusters together or
troubleshooting trust, [`tctl`](./cli.mdx#tctl) offers the more powerful,
lower-level CLI interface called `resources`.
The concept is borrowed from the REST programming pattern. A cluster is composed
of different objects (i.e., resources) and there are three common operations
that can be performed on them: `get` , `create` , and `remove` .
A resource is defined as a [YAML](https://en.wikipedia.org/wiki/YAML) file.
Every resource in Teleport has three required fields:
- `kind`: The type of resource
- `name`: A required field in the `metadata` to uniquely identify the resource
- `version`: The version of the resource format
Everything else is resource specific and any component of a Teleport cluster can
be manipulated with just three CLI commands:
| Command | Description | Examples |
| - | - | - |
| [`tctl get`](./cli.mdx#tctl-get) | Get one or multiple resources. | `tctl get users` or `tctl get user/joe` |
| [`tctl rm`](./cli.mdx#tctl-rm) | Delete a resource by type/name. | `tctl rm user/joe` |
| [`tctl create`](./cli.mdx#tctl-create) | Create a new resource from a YAML file. Use the `-f` flag to update existing resources. | `tctl create -f joe.yaml` |
<Admonition
type="warning"
title="YAML Format"
>
By default, Teleport uses [YAML format](https://en.wikipedia.org/wiki/YAML) to
describe resources. YAML is a human-readable alternative to JSON or XML, but
it's sensitive to white space. Pay attention to spaces versus tabs.
</Admonition>
### `tctl` example
Here's an example of a YAML resource definition for a user named `joe`. It can
be retrieved by executing `tctl get user/joe`.
```yaml
kind: user
version: v2
metadata:
name: joe
spec:
roles: admin
status:
# Users can be temporarily locked in a Teleport system, but this
# functionality is reserved for internal use for now.
is_locked: false
lock_expires: 0001-01-01T00:00:00Z
locked_time: 0001-01-01T00:00:00Z
traits:
# These are "allowed logins" which are usually specified as the
# last argument to `tctl users add`.
logins:
- joe
- root
# Any resource in Teleport can automatically expire.
expires: 0001-01-01T00:00:00Z
# For internal use only
created_by:
time: 0001-01-01T00:00:00Z
user:
name: builtin-Admin
```
<Admonition
type="tip"
title="Note"
>
Some of the fields you will see when printing resources are used only internally and are not meant to be changed. Others are reserved for future use.
</Admonition>
## Dynamic resources
Here's the list of resources currently exposed via [`tctl`](./cli.mdx#tctl):
| Resource Kind | Description |
| - | - |
| [user](#user) | A user record in the internal Teleport user DB. |
| [role](#role) | A role assumed by interactive and non-interactive users. |
| connector | Authentication connectors for [Single Sign-On](../access-controls/sso.mdx) (SSO) for SAML, OIDC and GitHub. |
| node | A registered SSH node. The same record is displayed via `tctl nodes ls` |
| cluster | A trusted cluster. See [here](../management/admin/trustedclusters.mdx) for more details on connecting clusters together. |
| login_rule | A Login Rule, see the [Login Rules guide](../access-controls/login-rules.mdx) for more info. |
| device | A Teleport Trusted Device, see the [Device Trust guide](../access-controls/device-trust/guide.mdx) for more info. |
| [ui_config](#ui-config) | Configuration for the Web UI served by the Proxy Service |
| cluster_auth_preference | Configuration for the cluster's auth preferences. |
**Examples:**
Examples of applying dynamic resources with `tctl`:
```code
# List all connectors:
@ -159,7 +42,23 @@ $ tctl get cluster_auth_preference
Although `tctl get connectors` will show you every connector, when working with an individual connector you must use the correct `kind`, such as `saml` or `oidc`. You can see each connector's `kind` at the top of its YAML output from `tctl get connectors`.
</Admonition>
### User
## List of dynamic resources
Here's the list of resources currently exposed via [`tctl`](./cli.mdx#tctl):
| Resource Kind | Description |
| - | - |
| [user](#user) | A user record in the internal Teleport user DB. |
| [role](#role) | A role assumed by interactive and non-interactive users. |
| connector | Authentication connectors for [Single Sign-On](../access-controls/sso.mdx) (SSO) for SAML, OIDC and GitHub. |
| node | A registered SSH node. The same record is displayed via `tctl nodes ls` |
| cluster | A trusted cluster. See [here](../management/admin/trustedclusters.mdx) for more details on connecting clusters together. |
| login_rule | A Login Rule, see the [Login Rules guide](../access-controls/login-rules.mdx) for more info. |
| device | A Teleport Trusted Device, see the [Device Trust guide](../access-controls/device-trust/guide.mdx) for more info. |
| [ui_config](#ui-config) | Configuration for the Web UI served by the Proxy Service |
| cluster_auth_preference | Configuration for the cluster's auth preferences. |
## User
Teleport supports interactive local users, non-interactive local users (bots)
and single-sign on users that are represented as a resource.
@ -195,7 +94,7 @@ spec:
name: builtin-Admin
```
### Role
## Role
Interactive and non-interactive users (bots) assume one or many roles.
@ -203,31 +102,31 @@ Roles govern access to databases, SSH servers, Kubernetes clusters, web services
(!docs/pages/includes/role-spec.mdx!)
### Login Rules
## Login Rules
Login rules contain logic to transform SSO user traits during login.
(!docs/pages/includes/login-rule-spec.mdx!)
### Device
## Device
Device contains information identifying a trusted device.
(!docs/pages/includes/device-spec.mdx!)
### UI config
## UI config
Global configuration options for the Web UI served by the Proxy Service. This resource is not set by default, which means a `tctl get ui` will result in an error if used before this resource has been set.
(!docs/pages/includes/ui-config-spec.mdx!)
### Cluster Maintenance Config
## Cluster maintenance config
Global configuration options for the agents enrolled into automatic updates.
(!docs/pages/includes/cluster-maintenance-config-spec.mdx!)
### Cluster Auth Preferences
## Cluster auth preferences
Global cluster configuration options for authentication.

2
docs/pages/server-access/guides/azure-discovery.mdx
View file

@ -265,7 +265,7 @@ for more information.
## Next steps
- Read [Joining Nodes via Azure Managed Identity](../../management/join-services-to-your-cluster/azure.mdx)
- Read [Joining Nodes via Azure Managed Identity](../../agents/join-services-to-your-cluster/azure.mdx)
for more information on Azure tokens.
- Full documentation on Azure discovery configuration can be found through the [
config file reference documentation](../../reference/config.mdx).

2
docs/pages/server-access/guides/ec2-discovery.mdx
View file

@ -338,7 +338,7 @@ See SSM RunCommand error codes and troubleshooting information in AWS documentat
## Next steps
- Read [Joining Nodes via AWS IAM
Role](../../management/join-services-to-your-cluster/aws-iam.mdx)
Role](../../agents/join-services-to-your-cluster/aws-iam.mdx)
for more information on IAM Invite Tokens.
- Information on IAM best practices on EC2 instances managed by Systems
Manager can be found for in the [AWS Cloud Operations & Migrations Blog

40
examples/agent-pool-terraform/agent-pool.tf Normal file
View file

@ -0,0 +1,40 @@
resource "random_string" "token" {
count = var.agent_count
length = 32
}
resource "teleport_provision_token" "agent" {
count = var.agent_count
spec = {
roles = [
"Node",
"App",
"Db",
"Kube",
]
name = random_string.token[count.index].result
}
}
resource "aws_instance" "teleport_agent" {
count = var.agent_count
# Amazon Linux 2023 64-bit x86
ami = "ami-04a0ae173da5807d3"
instance_type = "t3.small"
subnet_id = var.subnet_id
user_data = templatefile("./userdata", {
token = teleport_provision_token.agent[count.index].id
proxy_service_address = var.proxy_service_address
teleport_version = var.teleport_version
})
// The following two blocks adhere to security best practices.
metadata_options {
http_tokens = "required"
}
root_block_device {
encrypted = true
}
}

24
examples/agent-pool-terraform/inputs.tf Normal file
View file

@ -0,0 +1,24 @@
variable "agent_count" {
type = number
description = "Number of agents to deploy"
}
variable "proxy_service_address" {
type = string
description = "Host and HTTPS port of the Teleport Proxy Service"
}
variable "aws_region" {
type = string
description = "Region in which to deploy AWS resources"
}
variable "teleport_version" {
type = string
description = "Version of Teleport to install on each agent"
}
variable "subnet_id" {
type = string
description = "ID of the AWS subnet for deploying Teleport agents"
}

23
examples/agent-pool-terraform/provider.tf Normal file
View file

@ -0,0 +1,23 @@
terraform {
required_providers {
teleport = {
source = "terraform.releases.teleport.dev/gravitational/teleport"
version = "TELEPORT_VERSION"
}
aws = {
source = "hashicorp/aws"
version = "~> 4.0"
}
}
}
provider "aws" {
region = var.aws_region
}
provider "teleport" {
# Update addr to point to your Teleport Cloud tenant URL's host:port
addr = var.proxy_service_address
identity_file_path = "terraform-identity"
}

37
examples/agent-pool-terraform/userdata Normal file
View file

@ -0,0 +1,37 @@
#!/bin/bash
curl https://goteleport.com/static/install.sh | bash -s ${teleport_version}
echo ${token} > /var/lib/teleport/token
cat<<EOF >/etc/teleport.yaml
version: v3
teleport:
auth_token: /var/lib/teleport/token
proxy_server: ${proxy_service_address}
app_service:
enabled: true
resources:
- labels:
"*": "*"
auth_service:
enabled: false
db_service:
enabled: true
resources:
- labels:
"*": "*"
discovery_service:
enabled: true
kubernetes_service:
enabled: true
resources:
- labels:
"*": "*"
proxy_service:
enabled: false
ssh_service:
labels:
role: agent-pool
EOF
systemctl restart teleport;