|
1 | 1 | --- |
2 | 2 | title: Infrastructure as Code |
3 | 3 | 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. |
5 | 5 | tocDepth: 3 |
6 | 6 | tags: |
7 | 7 | - conceptual |
8 | 8 | - zero-trust |
9 | 9 | --- |
10 | 10 |
|
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. |
16 | 13 |
|
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 |
18 | 25 |
|
19 | 26 | There are two ways to configure a Teleport cluster: |
20 | 27 |
|
21 | 28 | - **Static configuration file:** At startup, a Teleport process reads a |
22 | 29 | configuration file from the local filesystem (the default path is |
23 | 30 | `/etc/teleport.yaml`). Static configuration settings control aspects of a |
24 | 31 | 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.) |
26 | 35 | - **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. |
32 | 38 |
|
33 | 39 |  |
34 | 40 |
|
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. |
40 | 45 |
|
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 |
151 | 47 |
|
152 | 48 | Some dynamic resources assign the same settings as fields within |
153 | 49 | Teleport's static configuration file. For these fields, the Teleport Auth |
154 | 50 | Service reconciles static and dynamic configurations on startup and when you |
155 | 51 | create or remove a Teleport resource. |
156 | 52 |
|
| 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 | + |
157 | 56 | ### Configuration resources that apply to static configuration fields |
158 | 57 |
|
159 | 58 | There are four dynamic resources that share fields with the |
@@ -214,7 +113,7 @@ static configuration file: |
214 | 113 | | `spec.scrollback_lines` | `proxy_service.ui.scrollback_lines` | |
215 | 114 | | `spec.show_resources` | `proxy_service.ui.show_resources` | |
216 | 115 |
|
217 | | -### Origin labels |
| 116 | +## Origin labels |
218 | 117 |
|
219 | 118 | The Teleport Auth Service applies the `teleport.dev/origin` label to |
220 | 119 | configuration resources to indicate whether they originated from the static |
@@ -254,19 +153,33 @@ configuration resources with the `teleport.dev/origin=config-file` label. |
254 | 153 |
|
255 | 154 | </Admonition> |
256 | 155 |
|
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). |
258 | 175 |
|
259 | | -### Configuration references |
| 176 | +### Kubernetes operator resources |
260 | 177 |
|
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). |
268 | 181 |
|
269 | | -### Other ways to use the Teleport API |
| 182 | +## Other ways to use the dynamic resource API |
270 | 183 |
|
271 | 184 | The Teleport Kubernetes Operator, Terraform provider, and `tctl` are all clients |
272 | 185 | of the Teleport Auth Service's gRPC API. To build your own API client to extend |
|
0 commit comments