Skip to content

Latest commit

 

History

History
570 lines (441 loc) · 25.6 KB

resources.mdx

File metadata and controls

570 lines (441 loc) · 25.6 KB
title h1 description
Teleport Resources
Teleport Resource Reference
Reference documentation for Teleport resources

This reference guide lists dynamic resources you can manage with Teleport. For more information on dynamic resources, see our guide to Using Dynamic Resources.

Examples of applying dynamic resources with tctl:

# List all connectors:
$ tctl get connectors

# Dump a SAML connector called "okta":
$ tctl get saml/okta

# Delete a SAML connector called "okta":
$ tctl rm saml/okta

# Delete an OIDC connector called "gworkspace":
$ tctl rm oidc/gworkspace

# Delete a github connector called "myteam":
$ tctl rm github/myteam

# Delete a local user called "admin":
$ tctl rm users/admin

# Show all devices:
$ tctl get devices

# Fetch a specific device:
$ tctl get devices/<asset-tag>

# Fetch the cluster auth preferences
$ 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`.

List of dynamic resources

Here's the list of resources currently exposed via tctl:

Resource Kind Description
user A user record in the internal Teleport user DB.
role A role assumed by interactive and non-interactive users.
connector Authentication connectors for Single Sign-On (SSO) for SAML, OIDC and GitHub.
node A registered SSH node. The same record is displayed via tctl nodes ls.
windows_desktop A registered Windows desktop.
cluster A trusted cluster. See here for more details on connecting clusters together.
login_rule A Login Rule, see the Login Rules guide for more info.
device A Teleport Trusted Device, see the Device Trust guide for more info.
ui_config Configuration for the Web UI served by the Proxy Service.
vnet_config Configuration for the cluster's VNet options.
cluster_auth_preference Configuration for the cluster's auth preferences.
database_object_import_rule Database object import rules.
autoupdate_config Client tools auto-update configuration
autoupdate_version Client tools auto-update target version configuration

User

Teleport supports interactive local users, non-interactive local users (bots) and single-sign on users that are represented as a resource.

kind: user
version: v2
metadata:
  name: joe
spec:
  # roles is a list of roles assigned to this user
  roles:
  - admin
  # status sets user temporarily locked in a Teleport system, for example
  # when users exceed predefined amount of failed login attempts
  status:
    is_locked: false
    lock_expires: 0001-01-01T00:00:00Z
    locked_time: 0001-01-01T00:00:00Z
  # traits are key, list of values pairs assigned to a user resource.
  # Traits can be used in role templates as variables.
  traits:
    logins:
    - joe
    - root
  # expires, if not empty, sets automatic expiry of the resource
  expires: 0001-01-01T00:00:00Z
  # created_by is a system property that tracks
  # identity of the author of this user resource.
  created_by:
    time: 0001-01-01T00:00:00Z
    user:
      name: builtin-Admin

Role

Interactive and non-interactive users (bots) assume one or many roles.

Roles govern access to databases, SSH servers, Kubernetes clusters, web services and applications and Windows Desktops.

(!docs/pages/includes/role-spec.mdx!)

Role versions

Versions 5, 6 and 7 of the Teleport role resource have different behaviors when accessing Kubernetes resources. {/lint ignore messaging/} Roles not granting Kubernetes access are equivalent in the three versions.

Roles v5 and v6 can only restrict actions on pods (e.g. executing in them). Role v7 supports restricting all common resource kinds ( see the kubernetes_resource documentation for a complete list).

When no kubernetes_resource is set:

  • Roles v5 and v7 grant all access by default
  • Roles v6 blocks pod execution by default, this was reverted by roles v7 to improve the user experience.

{/* This table is cursed. Our current docs engine doesn't support HTML tables (due to SSR and the rehydration process). We have dto do everything inlined in markdown. Some HTML character codes are used to render specific chars like {} or to avoid line breaks in the middle fo the YAML. Spaces before br tags are required.*/}

Allow rule Role v5 Role v6 Role v7 
kubernetes_groups: 
  - "system:masters" 
kubernetes_labels: {} 
kubernetes_resources: []
 ❌ no access ❌ no access ❌ no access 
kubernetes_groups: 
  - "system:masters" 
kubernetes_labels: 
  env: ["dev"] 
kubernetes_resources: []
 ✅ full access to dev clusters ❌ cannot exec in pods
✅ can access other
resources like secrets		 ✅ full access to dev clusters 
kubernetes_groups: 
  - "system:masters" 
kubernetes_labels: 
  env: ["dev"] 
kubernetes_resources: 
  - name: "*" 
    kind: pod 
    namespace: "foo"
 ✅ can exec in pods in foo
✅ can access secrets in all namespaces.
❌ cannot exec in other namespaces		 ✅ can exec in pods in foo
✅ can access secrets in all namespaces.
❌ cannot exec in other namespaces		 ✅ can exec in pods in foo
❌ cannot access secrets in all namespaces
❌ cannot exec in other namespaces		 
kubernetes_groups: 
  - "system:masters" 
kubernetes_labels: 
  env: ["dev"] 
kubernetes_resources: 
  - name: "*" 
    kind: pod 
    namespace: "foo" 
  - name: "*" 
    kind: secret 
    namespace: "foo"
 ⚠️ not supported ⚠️ not supported ✅ can exec in pods in foo
✅ can access secrets in foo
❌ cannot exec in other namespaces
❌ cannot access secrets in other namespaces
❌ cannot access configmaps in foo		 
kubernetes_groups: 
  - "system:masters" 
kubernetes_labels: 
  env: ["dev"] 
kubernetes_resources: 
  - kind: "namespace" 
    name: "foo"
 ⚠️ not supported ⚠️ not supported ✅ full access in namespace foo
❌ cannot access other namespaces

Windows desktops

In most cases, Teleport will register windows_desktop resources automatically based on static hosts in your configuration file or via LDAP-based discovery.

You can also use dynamic registration using dynamic_windows_desktop resources. This can be useful for managing inventories of hosts that are not joined to an Active Directory domain.

There are a few important considerations to keep in mind when registering desktops this way:

  1. The desktop's addr can be a hostname or IP address, and should include the RDP port (typically 3389).
  2. If you intend to log in to the desktop with local Windows users you must set non_ad: true. If you intend to log in with Active Directory users, leave non_ad unset (or false), and specify the Active Directory domain in the domain field.

Login Rules

Login rules contain logic to transform SSO user traits during login.

(!docs/pages/includes/login-rule-spec.mdx!)

Database object import rule

Database object import rule define the labels to be applied to database objects imported into Teleport.

See Database Access Controls for more details.

(!docs/pages/includes/database-access/auto-user-provisioning/database-object-import-rule-spec.mdx!)

Device

Device contains information identifying a trusted device.

(!docs/pages/includes/device-spec.mdx!)

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!)

VNet config

Cluster-specific options VNet should use when setting up connections to resources from this cluster.

See VNet for more details.

kind: vnet_config
version: v1
metadata:
  name: vnet-config
spec:
  # The range to use when assigning IP addresses to resources.
  # It can be changed in case of conflicts with other software
  # deployed on end user devices. Defaults to "100.64.0.0/10".
  ipv4_cidr_range: "100.64.0.0/10"
  # Extra DNS zones that VNet should capture DNS queries for.
  # Set them if your TCP apps use custom public_addr.
  # Requires DNS TXT record to be set on the domains,
  # see the guide linked above. Empty by default.
  custom_dns_zones:
  - suffix: company.test

Cluster maintenance config

Global configuration options for the agents enrolled into automatic updates (v1).

`cluster_maintenance_config` configures Managed Updates v1, which are currently supported but will be superseded by Managed Updates v2. The `autoupdate_config` and `autoupdate_version` resources further down configure Managed Updates v2.

(!docs/pages/includes/cluster-maintenance-config-spec.mdx!)

Cluster auth preferences

Global cluster configuration options for authentication.

metadata:
  name: cluster-auth-preference
spec:
  # Sets the list of allowed second factors for the cluster.
  # Possible values: "otp", "webauthn", and "sso".
  # Defaults to ["otp"].
  second_factors: ["webauthn", "otp"]

  # second_factors is the list of allowed second factors for the cluster.
  # Possible values: "on", "otp" and "webauthn"
  # If "on" is set, all MFA protocols are supported.
  #
  # Prefer setting second_factors instead.
  #second_factor: "webauthn"

  # The name of the OIDC or SAML connector. if this is not set, the first connector in the backend is used.
  connector_name: ""

  # webauthn is the settings for server-side Web authentication support.
  webauthn:
    # rp_id is the ID of the Relying Party.
    # It should be set to the domain name of the Teleport installation.
    #
    # IMPORTANT: rp_id must never change in the lifetime of the cluster, because
    # it's recorded in the registration data on the WebAuthn device. If the
    # ri_id changes, all existing WebAuthn key registrations will become invalid
    # and all users who use WebAuthn as the second factor will need to
    # re-register.
    rp_id: teleport.example.com
    # Allow list of device attestation CAs in PEM format.
    # If present, only devices whose attestation certificates match the
    # certificates specified here may be registered (existing registrations are
    # unchanged).
    # If supplied in conjunction with `attestation_denied_cas`, then both
    # conditions need to be true for registration to be allowed (the device
    # MUST match an allowed CA and MUST NOT match a denied CA).
    # By default all devices are allowed.
    attestation_allowed_cas: []
    # Deny list of device attestation CAs in PEM format.
    # If present, only devices whose attestation certificates don't match the
    # certificates specified here may be registered (existing registrations are
    # unchanged).
    attestation_denied_cas: []

  # Enforce per-session MFA or PIV-hardware key restrictions on user login sessions.
  # Possible values: true, false, "hardware_key", "hardware_key_touch".
  # Defaults to false.
  require_session_mfa: false

  # Sets whether connections with expired client certificates will be disconnected.
  disconnect_expired_cert: false

  # Sets whether headless authentication is allowed.
  # Headless authentication requires WebAuthn.
  # Defaults to true if webauthn is configured.
  allow_headless: false

  # Sets whether local auth is enabled alongside any other authentication
  # type.
  allow_local_auth: true

  # Sets whether passwordless authentication is allowed.
  # Requires Webauthn to work.
  allow_passwordless: false

  # Sets the message of the day for the cluster.
  message_of_the_day: ""

  # idp is a set of options related to accessing IdPs within Teleport. Requires Teleport Enterprise
  idp:
    # options related to the Teleport SAML IdP.
    saml:
      # enables access to the Teleport SAML IdP.
      enabled: true

  # locking_mode is the cluster-wide locking mode default.
  # Possible values: "strict" or "best_effort"
  locking_mode: best_effort

  # default_session_ttl defines the default TTL (time to live) of certificates
  # issued to the users on this cluster.
  default_session_ttl: "12h"

  # The type of authentication to use for this cluster.
  # Possible values: "local", "oidc", "saml" and "github"
  type: local

  stable_unix_user_config:
    # If set to true, SSH instances will use the same UID for each given
    # username when automatically creating users.
    enabled: false

    # The range of UIDs (including both ends) used for automatic UID assignment.
    first_uid: 90000
    last_uid: 95000

version: v2

Bot

Bot resources define a Machine ID Bot identity and its access.

Find out more on the Machine ID configuration reference.

(!docs/pages/includes/machine-id/bot-spec.mdx!)

Auto-update config

Configuration options for Teleport Agent and client tools Managed Updates (v2).

The `autoupdate_config` and `autoupdate_version` resources configure Managed Updates v2 and Managed Updates v1.

cluster_maintenance_config above configures only Managed Updates v1 which are currently supported but will be deprecated in a future version. 

kind: autoupdate_config
metadata:
  name: autoupdate-config
spec:
  agents:
    # mode allows users to enable, disable, or suspend agent updates at the
    # cluster level. Disable agent automatic updates only if self-managed
    # updates are in place. This value may also be set in autoupdate_version.
    # If set in both places, disabled overrides suspended, which overrides enabled.
    # Possible values: "enabled", "disabled", "suspended"
    # Default: "disabled" (unless specified in autoupdate_version)
    mode: enabled

    # strategy used to roll out updates to agents.
    # The halt-on-error strategy ensures that groups earlier in the schedule are
    # given the opportunity to update to the target_version before groups that are
    # later in the schedule. (Currently, the schedule must be stopped manually by
    # setting the mode to "suspended" or "disabled". In the future, errors will be
    # detected automatically).
    # The time-based strategy ensure that each group updates within a defined
    # time window, with no dependence between groups.
    # Possible values: "halt-on-error" or "time-based"
    # Default: "halt-on-error"
    strategy: halt-on-error

    # maintenance_window_duration configures the duration after the start_hour
    # when updates may occur. Only valid for the time-based strategy.
    # maintenance_window_duration: 1h

    # schedules define groups of agents with different update times.
    # Currently, only the regular schedule is configurable.
    schedules:
      regular:

        # name of each group, configured locally via "teleport-update enable --group"
        - name: staging

          # start_hour of the update, in UTC
          start_hour: 4

          # days that the update may occur on
          # Days are not configurable for most Enterprise cloud-hosted users.
          # Possible values: "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun", and "*"
          # Default: [ "Mon", "Tue", "Wed", "Thu" ]
          days: [ "Mon", "Tue", "Wed", "Thu" ]

        - name: production
          start_hour: 5

          # wait_hours ensures that the group executes at least a specific number of hours
          # after the previous group. Only valid for the halt-on-error schedule.
          # Default: 0
          wait_hours: 24

  tools:
    # mode allows users to enable or disable client tool updates at the
    # cluster level. Disable client tool automatic updates only if self-managed
    # updates are in place.
    # Possible values: "enabled" or "disabled"
    # Default: "disabled"
    mode: enabled

See Teleport Client Tool Managed Updates and Teleport Agent Managed Updates for more details.

Auto-update version

Allows cluster administrators to manage versions used for agent and client tools Managed Updates.

The `autoupdate_config` and `autoupdate_version` resources configure Managed Updates v2 and Managed Updates v1.

cluster_maintenance_config above configures only Managed Updates v1 which are currently supported but will be deprecated in a future version.

This resource is not editable for cloud-managed Teleport Enterprise to ensure that all of your clients receive security patches and remain compatible with your cluster.

kind: autoupdate_version
metadata:
  name: autoupdate-version
spec:
  agents:
    # start_version is the version used to install new agents before their
    # group's scheduled update time. Agents never update to the start_version
    # automatically, but may be required to via "teleport-update update --now".
    start_version: v17.2.0

    # target_version is the version that agents update to during their group's
    # scheduled update time. New agents also use this version after their group's
    # scheduled update time.
    target_version: v17.2.1

    # schedule used to roll out updates.
    # The regular schedule is defined in the autoupdate_config resource.
    # The immediate schedule updates all agents to target_version immediately.
    # Possible values: "regular" or "immediate"
    # Default: "regular"
    schedule: regular

    # mode allows users to enable, disable, or suspend agent updates at the
    # cluster level. Disable agent automatic updates only if self-managed
    # updates are in place. This value may also be set in autoupdate_config.
    # If set in both places, disabled overrides suspended, which overrides enabled.
    # Possible values: "enabled", "disabled", "suspended"
    # Default: "disabled" (unless specified in autoupdate_config)
    mode: enabled

  tools:
    # target_version is the semver version of client tools the cluster will advertise.
    # Client tools such as tsh and tctl will update to this version at login if the
    # mode set in autoupdate_config is set to enabled.
    # Default: cluster version
    target_version: v17.2.1

See Teleport Client Tool Managed Updates and Teleport Agent Managed Updates for more details.

Auto-update agent rollout

Allows cluster administrators to view the current agent rollout for Teleport Agent Managed Updates (v2).

This resource should not be edited by humans.

kind: autoupdate_agent_rollout
metadata:
  name: autoupdate-agent-rollout
spec:
  # start_version is the version used to install new agents before their
  # group's scheduled update time. Agents never update to the start_version
  # automatically, but may be required to via "teleport-update update --now".
  start_version: v17.2.0

  # target_version is the version that agents update to during their group's
  # scheduled update time. New agents also use this version after their group's
  # scheduled update time.
  target_version: v17.2.1

  # schedule used to roll out updates.
  # The regular schedule is defined in the autoupdate_config resource.
  # The immediate schedule updates all agents to target_version immediately.
  # Possible values: "regular" or "immediate"
  schedule: regular

  # autoupdate_mode allows users to enable, disable, or suspend agent updates at the
  # cluster level. Disable agent automatic updates only if self-managed
  # updates are in place. This value may also be set in autoupdate_config.
  # If set in both places, disabled overrides suspended, which overrides enabled.
  # Possible values: "enabled", "disabled", "suspended"
  autoupdate_mode: enabled

  # strategy used to roll out updates to agents.
  # The halt-on-error strategy ensures that groups earlier in the schedule are
  # given the opportunity to update to the target_version before groups that are
  # later in the schedule. (Currently, the schedule must be stopped manually by
  # setting the mode to "suspended" or "disabled". In the future, errors will be
  # detected automatically).
  # The time-based strategy ensure that each group updates within a defined
  # time window, with no dependence between groups.
  # Possible values: "halt-on-error" or "time-based"
  # Default: "halt-on-error"
  strategy: halt-on-error

  # maintenance_window_duration configures the duration after the start_hour
  # when updates may occur. Only valid for the time-based strategy.
  # maintenance_window_duration: 1h

status:

  # groups contains the status for each group in the currently executing schedule.
  groups:

    # name of each group, configured locally via "teleport-update enable --group"
    - name: staging

      # start_time of the group
      start_time: 0001-01-01T00:00:00Z

      # state of the group
      # Possible values: unstarted, active, done, rolledback
      state: active

      # last_update_time of this group's status
      last_update_time: 0001-01-01T00:00:00Z

      # last_update_reason of this group's status
      last_update_reason: "new version"

      # days that the update may occur on, from autoupdate_config
      # Possible values: "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun", and "*"
      config_days: [ "Mon", "Tue", "Wed", "Thu" ]

      # start_hour of the update, in UTC, from autoupdate_config
      config_start_hour: 4

    - name: production

      # ...

      # config_wait_hours is specific number of hours after the previous group that this
      # group may execute after, from autoupdate_config.
      config_wait_hours: 24

  # start_time of the rollout
  start_time: 0001-01-01T00:00:00Z

  # state of the entire rollout
  # Possible values: unstarted, active, done, rolledback
  state: active

See Teleport Agent Managed Updates for more details.