Skip to content

Commit 07de286

Browse files
committed
Improve IaC docs index page link visibility
The index page of the Infrastructure as Code section of the docs was originally intended to explain dynamic resources, so links to the guides contained within the section are neither up to date nor particularly visible. This change improves the visibility of links to the sections within the IaC section, and focuses the IaC index page more on its current purpose. Edit the IaC index page to: - Explain dynamic resources in terms of IaC tools. - Remove information that is already included elsewhere, and not relevant to using IaC tools to manage Teleport. - Update reference links. Add links to Operator and Terraform provider resource references. - Move key guide links to the introductory section of this page. - Remove the example manifests, since these aren't necessary once a user chooses to get started with a particular IaC tool. The examples are too minimal to be useful, but long enough to take up substantial space within the guide. This helps shorten the guide and focus on key information.
1 parent dc5482d commit 07de286

File tree

1 file changed

+52
-139
lines changed

1 file changed

+52
-139
lines changed

docs/pages/zero-trust-access/infrastructure-as-code/infrastructure-as-code.mdx

Lines changed: 52 additions & 139 deletions
Original file line numberDiff line numberDiff line change
@@ -1,159 +1,58 @@
11
---
22
title: Infrastructure as Code
33
h1: Manage Teleport Resources with Infrastructure as Code
4-
description: An introduction to Teleport's dynamic resources, which make it possible to apply settings to remote clusters using infrastructure as code.
4+
description: An introduction to managing Teleport with Infrastructure as Code tools, including Terraform and Kubernetes resources.
55
tocDepth: 3
66
tags:
77
- conceptual
88
- zero-trust
99
---
1010

11-
This section explains how to manage Teleport's **dynamic resources**, which make
12-
it possible to adjust the behavior of your Teleport cluster as your
13-
infrastructure changes. The design of dynamic resources enables you to manage
14-
them using infrastructure as code tools, including Terraform, Helm, and the
15-
Teleport `tctl` client tool.
11+
This section explains how to manage Teleport using infrastructure as code (IaC)
12+
tools.
1613

17-
## What is a dynamic resource?
14+
Teleport provides three methods for managing Teleport with infrastructure as
15+
code tools:
16+
- [Teleport Terraform provider](terraform-provider/terraform-provider.mdx)
17+
- [Teleport Kubernetes operator](teleport-operator/teleport-operator.mdx)
18+
- [`tctl` client tool](../../reference/cli/tctl.mdx)
19+
20+
For instructions on managing users, roles, trusted clusters, and other resources
21+
with IaC tools, see [Managing Resources with Infrastructure as
22+
Code](managing-resources/managing-resources.mdx).
23+
24+
## How IaC works with Teleport
1825

1926
There are two ways to configure a Teleport cluster:
2027

2128
- **Static configuration file:** At startup, a Teleport process reads a
2229
configuration file from the local filesystem (the default path is
2330
`/etc/teleport.yaml`). Static configuration settings control aspects of a
2431
cluster that are not expected to change frequently, like the ports that
25-
services listen on.
32+
services listen on. (See the [Configuration
33+
Reference](../../reference/deployment/config.mdx) for all static configuration
34+
options.)
2635
- **Dynamic resources:** Dynamic resources control aspects of your cluster that
27-
are likely to change over time, such as roles, local users, and registered
28-
infrastructure resources.
29-
30-
This approach makes it possible to incrementally adjust your Teleport
31-
configuration without restarting Teleport instances.
36+
are likely to change over time, such as roles, local users, and
37+
Teleport-protected infrastructure resources.
3238

3339
![Architecture of dynamic resources](../../../img/dynamic-resources.png)
3440

35-
A cluster is composed of different objects (i.e., resources) and there are three
36-
common operations that can be performed on them: `get` , `create` , and `remove`
37-
.
38-
39-
Every resource in Teleport has three required fields:
41+
The Teleport Auth Service stores dynamic resources on its cluster state backend,
42+
and clients can authenticate to the Auth Service to read or write dynamic
43+
resources, depending on their permissions. Infrastructure as code tools can
44+
authenticate to a Teleport cluster to manage dynamic resources.
4045

41-
- `kind`: The type of resource
42-
- `name`: A required field in the `metadata` to uniquely identify the resource
43-
- `version`: The version of the resource format
44-
45-
All other fields are specific to a resource.
46-
47-
While Teleport Enterprise Cloud does not expose the static configuration file to
48-
operators, they do use a static configuration file for certain settings. Read
49-
how Teleport [reconciles static and dynamic
50-
resources](#reconciling-the-configuration-file-with-dynamic-resources) to
51-
understand how to see the values of static configuration settings that also
52-
appear in dynamic resources.
53-
54-
When examining a dynamic resource, note that some of the fields you will see are
55-
used only internally and are not meant to be changed. Others are reserved for
56-
future use.
57-
58-
## Managing dynamic resources
59-
60-
Teleport provides three methods for applying dynamic resources: the `tctl`
61-
client tool, Teleport Terraform provider, and Kubernetes Operator.
62-
63-
All three methods connect to the Teleport Auth Service's gRPC endpoint in order
64-
to manipulate cluster resources stored on the Auth Service backend. The design
65-
of Teleport's configuration interface makes it well suited for
66-
infrastructure-as-code and GitOps approaches.
67-
68-
You can get started with `tctl`, the Terraform Provider, and the Kubernetes
69-
Operator by following:
70-
- the ["Managing Users and Roles with IaC" guide](managing-resources/user-and-role.mdx)
71-
- the ["Creating Access Lists with IaC" guide](managing-resources/access-list.mdx)
72-
- the ["Registering Agentless OpenSSH Servers with IaC" guide](managing-resources/agentless-ssh-servers.mdx)
73-
74-
For more information on Teleport roles, including the `internal.logins`
75-
trait we use in these example roles, see the [Access
76-
Controls Reference](../../reference/access-controls/roles.mdx).
77-
78-
### YAML documents with `tctl`
79-
80-
You can define resources as YAML documents and apply them using the `tctl`
81-
client tool. Here is an example of a `role` resource that allows access to
82-
servers with the label `env:test`:
83-
84-
```yaml
85-
kind: role
86-
version: v7
87-
metadata:
88-
name: developer
89-
spec:
90-
allow:
91-
logins: ['ubuntu', 'debian', '{{internal.logins}}']
92-
node_labels:
93-
'env': 'test'
94-
```
95-
96-
Since `tctl` works from the local filesystem, you can write commands that apply
97-
all configuration documents in a directory tree. See the [CLI
98-
reference](../../reference/cli/tctl.mdx) for more information on `tctl`.
99-
100-
### Teleport Terraform provider
101-
102-
Teleport's Terraform provider lets you manage your Teleport resources within the
103-
same infrastructure-as-code source as the rest of your infrastructure. There is
104-
a Terraform resource for each Teleport configuration resource. For example:
105-
106-
```hcl
107-
resource "teleport_role" "developer" {
108-
version = "v7"
109-
metadata = {
110-
name = "developer"
111-
}
112-
113-
spec = {
114-
allow = {
115-
logins = ["ubuntu", "debian", "{{internal.logins}}"]
116-
117-
node_labels = {
118-
key = ["env"]
119-
value = ["test"]
120-
}
121-
}
122-
}
123-
}
124-
```
125-
126-
[Get started with the Terraform
127-
provider](terraform-provider/terraform-provider.mdx).
128-
129-
### Teleport Kubernetes Operator
130-
131-
The Teleport Kubernetes Operator lets you apply Teleport resources as Kubernetes
132-
resources so you can manage your Teleport settings alongside the rest of your
133-
Kubernetes infrastructure. Here is an example of a `TeleportRoleV7` resource,
134-
which is equivalent to the two roles shown above:
135-
136-
```yaml
137-
apiVersion: resources.teleport.dev/v1
138-
kind: TeleportRoleV7
139-
metadata:
140-
name: developer
141-
spec:
142-
allow:
143-
logins: ['ubuntu', 'debian', '{{internal.logins}}']
144-
node_labels:
145-
'env': 'test'
146-
```
147-
148-
[Get started with the Kubernetes Operator](teleport-operator/teleport-operator.mdx).
149-
150-
## Reconciling the configuration file with dynamic resources
46+
## Reconciling static and dynamic configurations
15147

15248
Some dynamic resources assign the same settings as fields within
15349
Teleport's static configuration file. For these fields, the Teleport Auth
15450
Service reconciles static and dynamic configurations on startup and when you
15551
create or remove a Teleport resource.
15652

53+
While Teleport Enterprise Cloud does not expose the static configuration file to
54+
operators, they do use a static configuration file for certain settings.
55+
15756
### Configuration resources that apply to static configuration fields
15857

15958
There are four dynamic resources that share fields with the
@@ -214,7 +113,7 @@ static configuration file:
214113
| `spec.scrollback_lines` | `proxy_service.ui.scrollback_lines` |
215114
| `spec.show_resources` | `proxy_service.ui.show_resources` |
216115

217-
### Origin labels
116+
## Origin labels
218117

219118
The Teleport Auth Service applies the `teleport.dev/origin` label to
220119
configuration resources to indicate whether they originated from the static
@@ -254,19 +153,33 @@ configuration resources with the `teleport.dev/origin=config-file` label.
254153

255154
</Admonition>
256155

257-
## Further reading
156+
## Dynamic resource references
157+
158+
Read the following reference guides for comprehensive lists of supported fields
159+
in Teleport dynamic resources:
160+
161+
### tctl resources
162+
163+
For reference guides to dynamic configuration resources available to apply using
164+
`tctl`, read the [Configuration Resource
165+
Reference](../../reference/infrastructure-as-code/resources.mdx). There are also
166+
dedicated configuration resource references for
167+
[applications](../../reference/agent-services/application-access.mdx) and
168+
[databases](../../reference/agent-services/database-access-reference/configuration.mdx).
169+
170+
### Terraform resources and data sources
171+
172+
For comprehensive reference guides for resources and data sources you can manage
173+
with the Teleport Terraform provider, see [Teleport Terraform Provider
174+
References](../../reference/infrastructure-as-code/terraform-provider/terraform-provider.mdx).
258175

259-
### Configuration references
176+
### Kubernetes operator resources
260177

261-
- For a comprehensive reference of Teleport's static configuration options, read
262-
the [Configuration Reference](../../reference/deployment/config.mdx).
263-
- To see the dynamic configuration resources available to apply, read the
264-
[Configuration Resource Reference](../../reference/infrastructure-as-code/resources.mdx). There are also
265-
dedicated configuration resource references for
266-
[applications](../../reference/agent-services/application-access.mdx) and
267-
[databases](../../reference/agent-services/database-access-reference/configuration.mdx).
178+
For comprehensive reference guides for resources you can manage with the
179+
Teleport Terraform provider, see [Teleport Terraform Provider
180+
References](../../reference/infrastructure-as-code/operator-resources/operator-resources.mdx).
268181

269-
### Other ways to use the Teleport API
182+
## Other ways to use the dynamic resource API
270183

271184
The Teleport Kubernetes Operator, Terraform provider, and `tctl` are all clients
272185
of the Teleport Auth Service's gRPC API. To build your own API client to extend

0 commit comments

Comments
 (0)