opensource/teleport
3
0
Fork 0
mirror of https://github.com/gravitational/teleport.git synced 2026-11-02 14:59:53 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
acb255cd883d3d94de949f54e322edacab736112
teleport/docs/pages/reference/terraform-provider.mdx
T
Tiago SilvaandPaul Gottschling 2ffbd01944 Adds kubernetes_resources references (#22125) 
* Adds `kubernetes_resources` references

This PR adds references to Role `v6` in `Role Versions` and updates the
Terraform docs to include the new Role's field `kubernetes_resources`.

It also fixes a typo in Helm chart guide.

Fixes #21889
Fixes #22117

* Update docs/pages/reference/terraform-provider.mdx

Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>

* Update docs/pages/reference/terraform-provider.mdx

Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>

---------

Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
2023-02-24 09:31:32 +00:00

551 lines
32 KiB
Plaintext
Raw Blame History

---
title: Terraform provider resources
description: Terraform provider resources reference
---
Supported resources:
- [teleport_user](#teleport_user)
- [teleport_role](#teleport_role)
- [teleport_provision_token](#teleport_provision_token)
- [teleport_github_connector](#teleport_github_connector)
- [teleport_oidc_connector](#teleport_oidc_connector)
- [teleport_saml_connector](#teleport_saml_connector)
- [teleport_trusted_cluster](#teleport_trusted_cluster)
- [teleport_auth_preference](#teleport_auth_preference)
## Provider configuration
Add the following configuration section to your `terraform` configuration block:
```
terraform {
required_providers {
teleport = {
version = ">= (=teleport.version=)"
source = "terraform.releases.teleport.dev/gravitational/teleport"
}
}
}
```
The provider supports the following options:
| Name | Type | Description | Environment Variable |
| ---------------------- | ------ | ------------------------------------------------------------------------------ | ---------------------------------- |
| `addr` | string | Teleport auth or proxy address in "host:port" format. | `TF_TELEPORT_ADDR` |
| `cert_path` | string | Path to Teleport certificate file. | `TF_TELEPORT_CERT` |
| `cert_base64` | string | Teleport certificate as base64. | `TF_TELEPORT_CERT_BASE64` |
| `identity_file_path` | string | Path to Teleport identity file. | `TF_TELEPORT_IDENTITY_FILE_PATH` |
| `identity_file_base64` | string | Teleport identity file as base64. | `TF_TELEPORT_IDENTITY_FILE_BASE64` |
| `key_path` | string | Path to Teleport key file. | `TF_TELEPORT_KEY` |
| `key_base64` | string | Teleport key as base64. | `TF_TELEPORT_KEY_BASE64` |
| `profile_dir` | string | Teleport profile path. | `TF_TELEPORT_PROFILE_PATH` |
| `profile_name` | string | Teleport profile name. | `TF_TELEPORT_PROFILE_NAME` |
| `root_ca_path` | string | Path to Teleport CA file. | `TF_TELEPORT_ROOT_CA` |
| `root_ca_base64` | string | Teleport CA as base64. | `TF_TELEPORT_ROOT_CA_BASE64` |
| `retry_base_duration` | string | Base duration between retries. [Format](https://pkg.go.dev/time#ParseDuration) | `TF_TELEPORT_RETRY_BASE_DURATION` |
| `retry_cap_duration` | string | Max duration between retries. [Format](https://pkg.go.dev/time#ParseDuration) | `TF_TELEPORT_RETRY_CAP_DURATION` |
| `retry_max_tries` | string | Max number of retries. | `TF_TELEPORT_RETRY_MAX_TRIES` |
You need to specify at least one of:
- `cert_path`, `key_path`,`root_ca_path` and `addr` to connect using key files.
- `cert_base64`, `key_base64`,`root_ca_base64` and `addr` to connect using a base64-encoded key.
- `identity_file_path` or `identity_file_base64` and `addr` to connect using an identity file.
- `profile_name` and `profile_dir` (both can be empty) and Teleport will try to connect using current profile from `~/.tsh`
The `retry_*` values are used to retry the API calls to Teleport when the cache is stale.
If more than one are provided, they will be tried in the order above until one succeeds.
Example:
```
provider "teleport" {
addr = "localhost:3025"
cert_path = "tf.crt"
key_path = "tf.key"
root_ca_path = "tf.ca"
}
```
## teleport_user
The user resource allows to manage local non-interactive Teleport users: CI/CD bots and plugins.
**metadata**
Metadata specifies the resource name, description, labels and optional expiry date and time.
| Name | Type | Required | Description |
|-------------------------|------------|----------|-------------------------------------------|
| `name`| string | * | User name |
| `description`| string | | User description |
| `labels`| string map | | Resource labels |
| `namespace`| string | | Resource namespace ("default" by default) |
| `expires`| string | | Expiry time in RFC8829 format |
Example:
```
resource "teleport_user" "example" {
metadata = {
name = "example"
description = "Example Teleport User"
expires = "2022-10-12T07:20:50.3Z"
labels = {
example = "yes"
}
}
}
```
**spec**
Spec contains parameters of a resource.
| Name | Type | Description |
|-------------------------|-------------|-----------------------------------------------------------------|
| `roles`| string list | User role names |
| `traits`| set | User traits |
| `traits.key`| string | Trait name |
| `traits.value`| string list | Trait values |
| `github_identities`| object list | List of associated GitHub OAuth2 identities |
| `github_identities.connector_id` | string | An id of registered GitHub connector, e.g. 'github.com' |
| `github_identities.username` | string | GitHub username |
| `oidc_identities`| object list | List of OpenID Connect identities |
| `oidc_identities.connector_id` | string | An id of registered OIDC connector, e.g. 'google-example.com' |
| `oidc_identities.username` | string | OIDC username |
| `saml_identities`| object list | List of SAML identities |
| `saml_identities.connector_id` | string | An id of registered SAML connector, e.g. 'google-example.com' |
| `saml_identities.username` | string | SAML username |
Example:
```
resource "teleport_user" "example" {
metadata = {
name = "example"
}
spec = {
roles = ["example"]
oidc_identities = [
{
connector_id = "oidc1.example.com"
username = "example"
},
{
connector_id = "oidc2.example.com"
username = "example"
}
]
traits = {
key = ["trait1"]
value = ["example", "test"]
}
traits = {
key = ["trait2"]
value = ["foo", "bar"]
}
github_identities = [
{
connector_id = "github.com"
username = "example"
}
]
saml_identities = [
{
connector_id = "saml.example.com"
username = "example"
}
]
}
}
```
## teleport_role
The role resource specifies a set of permissions assigned to local and SSO users.
**metadata**
Metadata specifies a resource name, description, labels and optional expiry date and time.
| Name | Type | Required | Description |
|-------------------------|------------|----------|-------------------------------------------|
| `name`| string | * | Role name |
| `description`| string | | Role description |
| `labels`| string map | | Resource labels |
| `namespace`| string | | Resource namespace ("default" by default) |
| `expires`| string | | Expiry time in RFC8829 format |
**version**
`version` is an optional string that specifies the role version (default `v6`).
**spec**
Role specification consists of two sections: `allow` and `deny`. They are identical and contain the following fields:
`spec.allow` and `spec.deny`
| Name | Type | Description |
|---------------------------|-------------|-----------------------------------------------------------------|
| `db_names`| string list | List of database names this role is allowed to connect to |
| `db_users`| string list | List of database users this role is allowed to connect as |
| `kubernetes_groups`| string list | List of Kubernetes groups |
| `kubernetes_users`| string list | List of Kubernetes users to impersonate |
| `kubernetes_resources`| set | List of Kubernetes Resources the Role applies to |
| `logins`| string list | Logins is a list of *nix system logins |
| `app_labels`| map | Application labels |
| `app_labels.key`| string | Application name |
| `app_labels.values`| string list | List of labels |
| `cluster_labels`| map | Cluster labels |
| `cluster_labels.key`| string | Cluster name |
| `cluster_labels.values`| string list | List of labels |
| `db_labels`| map | Database labels |
| `db_labels.key`| string | Database name |
| `db_labels.values`| string list | List of labels |
| `kubernetes_labels`| map | Kubernetes labels |
| `kubernetes_labels.key`| string | Kubernetes cluster name |
| `kubernetes_labels.values`| string list | List of labels |
| `node_labels`| map | Node labels |
| `node_labels.key`| string | Node name |
| `node_labels.values`| string list | List of labels |
| `impersonate`| object | Specifies whether users are allowed to issue certificates for other users or groups |
| `impersonate.roles`| string list | list of roles this role is allowed to impersonate |
| `impersonate.users`| string list | List of users this role is allowed to impersonate |
| `impersonate.where`| string | Optional advanced matcher |
| `rules`| set | List of rules and their access levels. Rules are a high level construct used for access control |
| `rules.actions`| string list | Actions specifies optional actions taken when this rule matches |
| `rules.resources`| string list | List of resources |
| `rules.verbs`| string list | List of verbs |
| `rules.where`| string | Additional advanced matcher |
**spec.allow.kubernetes_resources** and **spec.deny.kubernetes_resources**
Kubernetes resources represents the resources the role allows/denies access to. The following fields are supported:
| `kind`| string | Resource kind. Supported values: `pod` |
| `name`| string | Resource name in the Kubernetes cluster. Supports regular expressions and wildcards (`*`) |
| `namespace`| string | Resource namespace in the Kubernetes cluster. Supports regular expressions and wildcards (`*`) |
**spec.allow.request and spec.deny.request**
Request matcher represents matcher for allow/deny restrictions on access-requests.
| Name | Type | Description |
|---------------------------|-------------|-----------------------------------------------------------------|
| `roles`| string list | Name of roles which will match the request rule |
| `suggested_reviewers`| string list | List of reviewer suggestions. These can be teleport usernames, but that is not a requirement. |
| `annotations`| set | Annotations |
| `annotations.key`| string | Annotation name |
| `annotations.value`| string list | Annotation values |
| `claims_to_roles`| set | Specifies a mapping from claims (traits) to teleport roles |
| `claims_to_roles.claim`| string | Claim name |
| `claims_to_roles.roles`| string list | List of static Teleport roles to match |
| `claims_to_roles.value`| string | Claim value to match |
| `thresholds`| set | List of thresholds, one of which must be met in order for reviews to trigger a state-transition. If no thresholds are provided, a default threshold of 1 for approval and denial is used. |
| `thresholds.name`| string | Threshold name |
| `thresholds.approve`| number | Number of matching approvals needed for state-transition |
| `thresholds.deny`| number | Number of denials needed for state-transition |
| `thresholds.filter`| string | Optional predicate used to determine which reviews count toward this threshold. |
**spec.allow.review_requests and spec.deny.review_requests**
Allow or deny access reviews matching the criteria.
| Name | Type | Description |
|---------------------------|-------------|-----------------------------------------------------------------|
| `roles`| string list | Name of roles which may be reviewed |
| `where`| string | Optional predicate which further limits which requests are reviewable |
| `claims_to_roles.claim`| string | Claim name |
| `claims_to_roles.roles`| string list | List of static Teleport roles to match |
| `claims_to_roles.value`| string | Claim value to match |
**spec.options**
Options specify session, connection and auditing permissions of the role.
| Name | Type | Description |
|---------------------------|-------------|-----------------------------------------------------------------|
| `cert_format` | string | The format of the user certificate to allow compatibility with older versions of OpenSSH |
| `client_idle_timeout` | duration | Sets disconnect clients on idle timeout behavior, if set to 0 means do not disconnect, otherwise is set to the idle duration |
| `disconnect_expired_cert` | bool | Sets disconnect clients on expired certificates |
| `enhanced_recording` | string list | Events to record for the BPF-based session recorder |
| `forward_agent` | bool | SSH agent forwarding |
| `max_connections` | number | The maximum number of concurrent connections a user may hold |
| `max_session_ttl` | number | How long a SSH session can last for |
| `max_sessions` | number | Maximum number of concurrent sessions per connection |
| `permit_x11_forwarding` | bool | Authorizes use of X11 forwarding |
| `port_forwarding` | bool | Port forwarding |
| `request_access` | string | Access request strategy (optional\|note\|always) |
| `request_prompt` | string | An optional message which tells users what they aught to |
| `require_session_mfa` | bool/string | Enforce per-session MFA or PIV-hardware key restrictions on user login sessions |
Example:
```
resource "teleport_role" "example" {
metadata = {
name = "example"
}
spec = {
options = {
forward_agent = false
max_session_ttl = "7m"
port_forwarding = false
client_idle_timeout = "1h"
disconnect_expired_cert = true
permit_x11_forwarding = false
request_access = "denied"
}
allow = {
logins = ["example"]
rules = [{
resources = ["user", "role"]
verbs = ["list"]
}]
request = {
roles = ["example"]
claims_to_roles = [{
claim = "example"
value = "example"
roles = ["example"]
}]
}
node_labels = {
env = ["prod"]
example = ["a", "b"]
}
kubernetes_resources = [
{
kind = "pod"
name = "*"
namespace = "myns"
}
]
}
deny = {
logins = ["anonymous"]
}
}
}
```
## teleport_provision_token
Provision tokens authenticate Teleport resource services and Proxy Service
instances when they first join the cluster.
**metadata**
Metadata specifies a resource name, description, labels and optional expiry date and time.
| Name | Type | Required | Description |
|-------------------------|------------|----------|-------------------------------------------|
| `name`| string | * | Token name |
| `description`| string | | Token description |
| `labels`| string map | | Resource labels |
| `namespace`| string | | Resource namespace ("default" by default) |
| `expires`| string | * | Expiry time in RFC8829 format |
**spec**
Spec contains parameters of a resource. It has a single field: `roles`, a list of roles associated with a token.
It will be converted to metadata in the SSH and X509 certificates issued to the user of the token.
## teleport_github_connector
**metadata**
Metadata specifies a resource name, description, labels and optional expiry date and time.
| Name | Type | Required | Description |
|-------------------------|------------|----------|-------------------------------------------|
| `name`| string | * | Connector name |
| `description`| string | | Connector description |
| `labels`| string map | | Resource labels |
| `namespace`| string | | Resource namespace ("default" by default) |
| `expires`| string | | Expiry time in RFC8829 format |
**spec**
Spec contains parameters of a resource.
| Name | Type | Description |
|-------------------------------------|-------------|-----------------------------------------------------------------|
| `client_id` | string | GitHub OAuth app client ID |
| `client_secret` | string | GitHub OAuth app client secret |
| `display` | string | Connector display name |
| `redirect_url` | string | Authorization callback URL |
| `teams_to_roles` | set | Maps GitHub team memberships onto allowed roles |
| `teams_to_roles.roles` | string list | List of allowed roles for this org/team |
| `teams_to_roles.organization` | string | GitHub organization a user belongs to |
| `teams_to_roles.team` | string | Team within the organization a user belongs to |
## teleport_oidc_connector
An OIDC connector resource specifies OpenID Connect identity provider for Teleport.
**metadata**
Metadata specifies a resource name, description, labels and optional expiry date and time.
| Name | Type | Required | Description |
|-------------------------|------------|----------|-------------------------------------------|
| `name`| string | * | Connector name |
| `description`| string | | Connector description |
| `labels`| string map | | Resource labels |
| `namespace`| string | | Resource namespace ("default" by default) |
| `expires`| string | | Expiry time in RFC8829 format |
**spec**
Spec contains parameters of a resource.
| Name | Type | Description |
|---------------------------|-------------|-----------------------------------------------------------------|
| `acr_values` | string | Authentication Context Class Reference value. The meaning of the ACR value is context-specific and varies for identity providers |
| `client_id` | string | The id of the authentication client (Teleport Auth server) |
| `client_secret` | string | Used to authenticate the client |
| `display` | string | Connector display name |
| `google_admin_email` | string | The email of a google admin to impersonate |
| `google_service_account` | string | String containing google service account credentials |
| `google_service_account_uri` | string | Path to a google service account uri |
| `issuer_url` | string | The endpoint of the provider, e.g. https://accounts.google.com |
| `prompt` | string | An optional OIDC prompt. An empty string omits prompt. If not specified, it defaults to select_account for backwards compatibility |
| `provider` | string | The external identity provider |
| `redirect_url` | string | An URL that will redirect the client's browser back to the identity provider after successful authentication. This should match the URL on the Provider's side |
| `scope` | string list | Specifies additional scopes set by provider |
| `claims_to_roles` | set | Specifies a mapping from claims (traits) to teleport roles |
| `claims_to_roles.claim` | string | Claim name |
| `claims_to_roles.roles` | string list | List of static Teleport roles to match |
| `claims_to_roles.value` | string | Claim value to match |
## teleport_saml_connector
An OIDC connector resource specifies SAML identity provider for Teleport.
**metadata**
Metadata specifies a resource name, description, labels and optional expiry date and time.
| Name | Type | Required | Description |
|-------------------------|------------|----------|-------------------------------------------|
| `name`| string | * | Connector name |
| `description`| string | | Connector description |
| `labels`| string map | | Resource labels |
| `namespace`| string | | Resource namespace ("default" by default) |
| `expires`| string | | Expiry time in RFC8829 format |
**spec**
Spec contains parameters of a resource.
| Name | Type | Description |
|------------------------------|-------------|-------------------------------------------------------------------------------|
| `acs` | string | URL for assertion consumer service on the service provider (Teleport's side) |
| `audience` | string | Audience uniquely identifies our service provider |
| `cert` | string | Cert is the identity provider certificate PEM. IDP signs `Response` responses using this certificate |
| `display` | string | Connector display name |
| `entity_descriptor` | string | XML with descriptor. It can be used to supply configuration parameters in one XML file rather than supplying them in the individual elements. |
| `entity_descriptor_url` | string | URL that supplies a configuration XML |
| `issuer` | string | Identity provider issuer |
| `provider` | string | External identity provider |
| `service_provider_issuer` | string | The issuer of the service provider (Teleport) |
| `sso` | string | SSO is the URL of the identity provider's SSO service |
| `attributes_to_roles` | set | List of mappings of attribute statements to roles |
| `attributes_to_roles.name` | string | Attribute statement name |
| `attributes_to_roles.roles` | string list | List of static Teleport roles to map to |
| `attributes_to_roles.value` | string | Attribute statement value to match |
| `assertion_key_pair` | object | Public and private key used for encryption |
| `assertion_key_pair.cert` | string | PEM-encoded x509 certificate |
| `assertion_key_pair.private_key` | string | PEM-encoded x509 private key |
| `signing_key_pair` | object | Public and private key used for signing |
| `signing_key_pair.cert` | string | PEM-encoded x509 certificate |
| `signing_key_pair.private_key` | string | PEM-encoded x509 private key |
## teleport_trusted_cluster
A trusted cluster resource connects dials and connects this cluster to another, root cluster.
**metadata**
Metadata specifies a resource name, description, labels and optional expiry date and time.
| Name | Type | Required | Description |
|-------------------------|------------|----------|-------------------------------------------|
| `name`| string | * | Connector name |
| `description`| string | | Connector description |
| `labels`| string map | | Resource labels |
| `namespace`| string | | Resource namespace ("default" by default) |
| `expires`| string | | Expiry time in RFC8829 format |
**spec**
Spec contains parameters of a resource.
| Name | Type | Description |
|------------------------------|-------------|-------------------------------------------------------------------------------|
| `enabled` | bool | Indicates if the trusted cluster is enabled or disabled. Setting Enabled to false has a side effect of deleting the user and host certificate authority (CA). |
| `web_proxy_addr | string | The address of the web proxy server of the cluster to join. If not set, it is derived from `metadata.name:default web proxy server port`. |
| `tunnel_address` | string | The address of the SSH proxy server of the cluster to join. If not set, it is derived from `metadata.name:default reverse tunnel port`. |
| `roles` | string list | List of roles that users will be assuming when connecting to this cluster |
| `token` | string | The authorization token provided by another cluster needed by this cluster to join |
| `role_map` | set | Role mappings to remote roles |
| `role_map.local` | string list | Local roles to map to |
| `role_map.remote` | string | Remote role name to map from |
## teleport_auth_preference
The auth preference resource defines cluster auth preference for the Teleport cluster. This resource is a singleton. It gots reset on deletion.
**metadata**
Metadata specifies a resource description, labels and optional expiry date and time.
| Name | Type | Required | Description |
|-------------------------|------------|----------|-------------------------------------------|
| `description`| string | | Connector description |
| `labels`| string map | | Resource labels |
| `namespace`| string | | Resource namespace ("default" by default) |
| `expires`| string | | Expiry time in RFC8829 format |
**spec**
Spec contains parameters of a resource.
{/* TODO(codingllama): Add and document Terraform support for WebAuthn. */}
| Name | Type | Description |
|------------------------------|-------------|-------------------------------------------------------------------------------|
| `type` | string | Type is the type of authentication |
| `second_factor` | string | SecondFactor is the type of second factor |
| `connector_name` | string | ConnectorName is the name of the OIDC or SAML connector. If this value is not set the first connector in the backend will be used |
| `u2f` | set | U2F defines settings for U2F device |
| `u2f.app_id` | string | The application ID for universal second factor |
| `u2f.facets` | string list | The facets for universal second factor |
| `u2f.device_attestation_cas` | string list | Trusted attestation CAs for U2F devices |
| `require_session_mfa` | bool/string | Enforce per-session MFA or PIV-hardware key restrictions on all user login sessions |
| `disconnect_expired_cert` | bool | If true, connections with expired client certificates will get disconnected |
| `allow_local_auth` | bool | If true, local authentication is enabled |
Reference in New Issue View Git Blame Copy Permalink