From 0970e7223368cf23ca6e6833c0adcdfcf0611220 Mon Sep 17 00:00:00 2001 From: Paul Gottschling Date: Mon, 21 Mar 2022 18:34:34 -0400 Subject: [PATCH] Edit three guides for Cloud users Backports #11115 See #10633 Terraform Provider guide - Add tabbed prerequisites so users only see information relevant to their scopes. - Add the impersonation section as an H3 rather than an Admonition. If users are learning how to use our Terraform provider, they likely will not have enabled impersonation for the Terraform user, and would always need to read the Admonition, so this would work better as an H3. - Add a scoped Notice indicating which address to use for the cluster address in the sample Terraform config. Fluentd plugin guide - Add tabbed instructions for users of different scopes. - Move the impersonation Admonition to an H3 so readers can configure impersonation without running into an error. - Misc clarity/style edits. Certificate Authority Rotation - Add tabbed prerequisites so users of one scope don't see information intended for other scopes. --- docs/pages/includes/tctl.mdx | 3 +- docs/pages/setup/guides/fluentd.mdx | 238 +++++++++++++----- .../pages/setup/guides/terraform-provider.mdx | 229 ++++++++++++----- docs/pages/setup/operations/ca-rotation.mdx | 57 ++++- .../terraform/terraform-user-role-cloud.tf | 79 ++++++ ....tf => terraform-user-role-self-hosted.tf} | 4 +- 6 files changed, 478 insertions(+), 132 deletions(-) create mode 100644 examples/resources/terraform/terraform-user-role-cloud.tf rename examples/resources/terraform/{terraform-user-role.tf => terraform-user-role-self-hosted.tf} (93%) diff --git a/docs/pages/includes/tctl.mdx b/docs/pages/includes/tctl.mdx index b032754d16b40..ba0441b0d38ef 100644 --- a/docs/pages/includes/tctl.mdx +++ b/docs/pages/includes/tctl.mdx @@ -22,7 +22,8 @@ scopeOnly={true} opened={true} > -To connect to Teleport, log in to your cluster using `tsh`, then use `tctl` remotely: +To connect to Teleport, log in to your cluster using `tsh`, then use `tctl` +remotely: ```code $ tsh login --proxy=myinstance.teleport.sh --user=email@example.com diff --git a/docs/pages/setup/guides/fluentd.mdx b/docs/pages/setup/guides/fluentd.mdx index 28ce9f79370bf..a78eb48a2f0c9 100644 --- a/docs/pages/setup/guides/fluentd.mdx +++ b/docs/pages/setup/guides/fluentd.mdx @@ -4,37 +4,82 @@ description: Forwarding events with Fluentd and Teleport event handler videoBanner: HAqxs4rBv2c --- -This section will cover: +In this guide, we will explain how to: -- Setting up Teleport's event handler. -- Forwarding events with Fluentd for Cloud, Enterprise and Open Source editions. +- Set up Teleport's event handler. +- Forward events with Fluentd. ## Prerequisites -- Teleport v(=teleport.version=) Cloud, Open Source or Enterprise -- Teleport admin tool `tctl` configured to access the cluster. + + + +- A running Teleport cluster. For details on how to set this up, see [Getting + Started on a Linux Server](../../getting-started/linux-server.mdx). + +- The `tctl` admin tool version >= (=teleport.version=). + + ```code + $ tctl version + # Teleport v(=teleport.version=) go(=teleport.golang=) + ``` + + See [Installation](../../installation.mdx) for details. + + (!docs/pages/includes/tctl.mdx!) + + + + +- A running Teleport cluster. For details on setting this up, see our + [Enterprise getting started guide](../../enterprise/getting-started.mdx). + +- The `tctl` admin tool version >= (=teleport.version=), which you can download + by visiting the + [customer portal](https://dashboard.gravitational.com/web/login). + + ```code + $ tctl version + # Teleport v(=teleport.version=) go(=teleport.golang=) + ``` + + (!docs/pages/includes/tctl.mdx!) + + + + +- A Teleport Cloud account. If you do not have one, visit the + [sign up page](https://goteleport.com/signup/) to begin your free trial. + +- The Enterprise version of the `tctl` admin tool. To download this, visit +the [customer portal](https://dashboard.gravitational.com/web/login). + + ```code + $ tctl version + # Teleport v(=teleport.version=) go(=teleport.golang=) + ``` + + (!docs/pages/includes/tctl.mdx!) + + + + - Fluentd version v(=fluentd.version=). - Docker version v(=docker.version=). -```code -$ tctl version -# Teleport v(=teleport.version=) go(teleport.golang) -# -# Test connectivity and admin permissions -$ tctl get roles -``` - -Create a folder `fluentd` to hold configuration and plugin state: +Create a folder called `fluentd` to hold configuration and plugin state: ```code $ mkdir -p event-handler $ cd event-handler ``` -## Step 1/6. Install event handler plugin +## Step 1/6. Install the event handler plugin -Teleport event handler runs alongside fluentd forwarder, receives events from Teleport's events API -and forwards them to fluentd. +The Teleport event handler runs alongside the Fluentd forwarder, receives events +from Teleport's events API, and forwards them to Fluentd. @@ -54,13 +99,30 @@ and forwards them to fluentd. ## Step 2/6. Generate configuration -Run `configure` command to generate sample configuration. Replace `teleport.example.com:443` -with the DNS name and web proxy port of Teleport's proxy: + + + +Run the `configure` command to generate a sample configuration. Replace +`teleport.example.com:443` with the DNS name and HTTPS port of Teleport's Proxy +Service: ```code $ ./teleport-event-handler configure . teleport.example.com:443 ``` + + + +Run the `configure` command to generate a sample configuration. Replace +`mytenant.teleport.sh` with the DNS name of your Teleport Cloud tenant: + +```code +$ ./teleport-event-handler configure . mytenant.teleport.sh +``` + + + + You'll see the following output: ```txt @@ -76,7 +138,7 @@ Follow-along with our getting started guide: https://goteleport.com/setup/guides/fluentd ``` -Plugin has generated several setup files: +The plugin generates several setup files: ```code $ ls -l @@ -91,15 +153,19 @@ $ ls -l # -rw------- 1 bob bob 343 Jul 1 11:14 teleport-event-handler.toml ``` -- `ca.crt` and `ca.key` is a fluentd self-signed CA certificate and a private key. -- `server.crt` and `server.key` is a fluentd server certificate and key. -- `client.crt` and `client.key` is a fluentd client certificate and key, all signed by the generated CA. -- `teleport-event-handler-role.yaml` is a Teleport's event handler client user and role. -- `fluent.conf` is a fluentd plugin configuration. +|File(s)|Purpose| +|---|---| +| `ca.crt` and `ca.key`| Self-signed CA certificate and private key for Fluentd| +| `server.crt` and `server.key`| Fluentd server certificate and key| +| `client.crt` and `client.key`| Fluentd client certificate and key, all signed by the generated CA| +| `teleport-event-handler-role.yaml`| `user` and `role` resource definitions for Teleport's event handler |client. +| `fluent.conf`| Fluentd plugin configuration| -## Step 3/6. Create user and role for reading audit events +## Step 3/6. Create a user and role for reading audit events -`configure` command generated `teleport-event-handler-role.yaml` that defines a `teleport-event-handler` role and a user with read-only access to the `event` API: +The `configure` command generates a file called +`teleport-event-handler-role.yaml` that defines a `teleport-event-handler` role +and a user with read-only access to the `event` API: ```yaml kind: user @@ -130,24 +196,16 @@ $ tctl create -f teleport-event-handler-role.yaml ## Step 4/6. Create teleport-event-handler credentials -Teleport Plugin use the fluentd role and user to read the events. We export the identity files, using tctl auth sign. - -```code -$ tctl auth sign --out identity --user teleport-event-handler -# The credentials have been written to identity -``` - -This will generate `identity` which contains TLS certificates and will be used to connect plugin to your Teleport instance. - - -Clients, for example cloud interactive users, could be missing impersonation privileges when trying to use `tctl auth sign`, -will get the following error: +### Enable impersonation of the Fluentd plugin user -```txt -ERROR: access denied: impersonation is not allowed -``` +In order for the Fluentd plugin to forward events from your Teleport cluster, it +needs a signed identity file from the cluster's certificate authority. The +Fluentd user cannot request this itself, and requires another user to +**impersonate** this account in order to request a certificate. -Create the following file with role: `teleport-event-handler-impersonator.yaml`: +Create a role that enables your user to impersonate the Fluentd user. First, +paste the following YAML document into a file called +`teleport-event-handler-impersonator.yaml`: ```yaml kind: role @@ -169,28 +227,61 @@ spec: roles: ["teleport-event-handler"] ``` +Next, create the role: + ```code $ tctl create teleport-event-handler-impersonator.yaml ``` -Assign this role to the current user by running the below command, subsituing the user as appropriate: +Assign this role to the current user by running the following command, substituting +the user as appropriate: + ```code $ tctl get users/ > out.yaml ``` -Now edit `out.yaml` with your favourite editor, adding `teleport-event-handler-impersonator` to the list of existing roles and update via `tctl` again: +Now edit `out.yaml`, adding `teleport-event-handler-impersonator` to the list of +existing roles and update via `tctl` again: + ``` $ tctl create -f out.yaml ``` -Re-login to assume the new role and try to issue certificate for the teleport-event-handle user again. - +Log in to your Teleport cluster again to assume the new role. + +### Export an identity file for the Fluentd plugin user -## Step 5/6. Start fluentd forwarder +The Fluentd Teleport plugin uses the `teleport-event-handler` role and user to +read events. We export an identity file for the user with the `tctl auth sign` +command. -The plugin will send events to the fluentd instance using keys generated on the previous step. + + +```code +$ tctl auth sign --format=tls --user=teleport-event-handler --out=auth +``` -Generated sample `fluent.conf` file sets accepts events using `TLS` and prints them: +This command should result in three PEM-encoded files: `auth.crt`, `auth.key`, +and `auth.cas` (certificate, private key, and CA certs, respectively). + + + +```code +$ tctl auth sign --user=teleport-event-handler --out=identity +``` + +The above sequence should result in one PEM-encoded file: `terraform-identity`. + + + + +## Step 5/6. Start the Fluentd forwarder + +The Fluentd plugin will send events to your Fluentd instance using keys +generated on the previous step. + +The `fluent.conf` file generated earlier configures your Fluentd instance to +accept events using TLS and print them: ``` @@ -223,7 +314,7 @@ Generated sample `fluent.conf` file sets accepts events using `TLS` and prints t ``` -To try it out, start fluentd instance: +To try out this Fluentd configuration, start your fluentd instance: ```code $ docker run -u $(id -u ${USER}):$(id -g ${USER}) -p 8888:8888 -v $(pwd):/keys -v $(pwd)/fluent.conf:/fluentd/etc/fluent.conf fluent/fluentd:edge @@ -231,8 +322,11 @@ $ docker run -u $(id -u ${USER}):$(id -g ${USER}) -p 8888:8888 -v $(pwd):/keys - ## Step 6/6. Start the event handler plugin -`configure` command generated `teleport-event-handler.toml` configuration file -for the event handler: +Earlier, we generated a file called `teleport-event-handler.toml` to configure +the Fluentd event handler. This file includes setting similar to the following: + + + ```toml storage = "./storage" @@ -251,27 +345,53 @@ addr = "example.teleport.com:443" identity = "identity" ``` -Start an export from the current moment: + + + +```toml +storage = "./storage" +timeout = "10s" +batch = 20 +namespace = "default" + +[forward.fluentd] +ca = "/home/sasha/scripts/event-handler/ca.crt" +cert = "/home/sasha/scripts/event-handler/client.crt" +key = "/home/sasha/scripts/event-handler/client.key" +url = "https://localhost:8888/test.log" + +[teleport] +addr = "example.teleport.com:443" +client_key = "auth.key" +client_crt = "auth.crt" +root_cas = "auth.cas" +``` + + + + +To start the event handler, run the following command: ```code $ ./teleport-event-handler start --config teleport-event-handler.toml ``` -This example will start export from `May 5th 2021`: + +This example will start exporting from `May 5th 2021`: ```code $ ./teleport-event-handler start --config teleport-event-handler.toml --start-time "2021-05-05T00:00:00Z" ``` -Start time can be set only once, on the first run of the tool. +The start time can be set only once, on the first run of the tool. -If you want to change the time frame later, remove plugin state dir -which you had specified in `storage-dir` argument. +If you want to change the time frame later, remove the plugin state directory +that you specified in the `storage` field of the handler's configuration file. -Once handler starts, you will see notifications about scanned and forwarded events: +Once the handler starts, you will see notifications about scanned and forwarded events: ```txt INFO[0046] Event sent id=0b5f2a3e-faa5-4d77-ab6e-362bca0994fc ts="2021-06-08 11:00:56.034 +0000 UTC" type=user.login diff --git a/docs/pages/setup/guides/terraform-provider.mdx b/docs/pages/setup/guides/terraform-provider.mdx index 33a5dd4441784..35256435a8648 100644 --- a/docs/pages/setup/guides/terraform-provider.mdx +++ b/docs/pages/setup/guides/terraform-provider.mdx @@ -4,25 +4,89 @@ description: Configuration as a code with Terraform Provider videoBanner: YgNHD4SS8dg --- -This section will cover: +This guide will explain how to: -- Setting up Teleport's terraform provider on Linux and Mac. -- Configuring users and roles using terraform provider for Cloud, Enterprise and Open Source editions. +- Set up Teleport's Terraform provider on Linux and Mac. +- Configure Teleport users and roles using the Terraform provider. ## Prerequisites + + + +- A running Teleport cluster. For details on how to set this up, see [Getting + Started on a Linux Server](../../getting-started/linux-server.mdx). + +- The `tctl` admin tool version >= (=teleport.version=). + + ```code + $ tctl version + # Teleport v(=teleport.version=) go(=teleport.golang=) + ``` + + See [Installation](../../installation.mdx) for details. + + (!docs/pages/includes/tctl.mdx!) + - [Terraform >= (=terraform.version=)+](https://learn.hashicorp.com/tutorials/terraform/install-cli) -- Teleport (=teleport.version=) Cloud, Open Source or Enterprise -```code -$ terraform version -# Terraform v(=terraform.version=) -``` + ```code + $ terraform version + # Terraform v(=terraform.version=) + ``` + + + + +- A running Teleport cluster. For details on setting this up, see our + [Enterprise getting started guide](../../enterprise/getting-started.mdx). + +- The `tctl` admin tool version >= (=teleport.version=), which you can download + by visiting the + [customer portal](https://dashboard.gravitational.com/web/login). + + ```code + $ tctl version + # Teleport v(=teleport.version=) go(=teleport.golang=) + ``` + + (!docs/pages/includes/tctl.mdx!) + +- [Terraform >= (=terraform.version=)+](https://learn.hashicorp.com/tutorials/terraform/install-cli) + + ```code + $ terraform version + # Terraform v(=terraform.version=) + ``` + + + + +- A Teleport Cloud account. If you do not have one, visit the + [sign up page](https://goteleport.com/signup/) to begin your free trial. + +- The Enterprise version of the `tctl` admin tool. To download this, visit +the [customer portal](https://dashboard.gravitational.com/web/login). + + ```code + $ tctl version + # Teleport v(=teleport.version=) go(=teleport.golang=) + ``` + + (!docs/pages/includes/tctl.mdx!) + +- [Terraform >= (=terraform.version=)+](https://learn.hashicorp.com/tutorials/terraform/install-cli) + + ```code + $ terraform version + # Terraform v(=terraform.version=) + ``` + + + -```code -$ tctl version -# Teleport v(=teleport.version=) go(teleport.golang) -``` Create a folder `teleport-terraform` to hold some temporary files: @@ -31,7 +95,7 @@ $ mkdir -p teleport-terraform $ cd teleport-terraform ``` -## Step 1/4. Install terraform provider +## Step 1/4. Install the Terraform provider @@ -51,7 +115,54 @@ $ cd teleport-terraform -## Step 2/4. Create a terraform user +## Step 2/4. Create a Terraform user + +### Enable impersonation + +In order for Terraform to manage resources in your Teleport cluster, it needs a +signed identity file from the cluster's certificate authority. The Terraform user +cannot request this itself, and requires another user to **impersonate** this +account in order to request a certificate. + +Create a role that enables your user to impersonate the Terraform user. First, paste +the following YAML document into a file called `terraform-impersonator.yaml`: + +```yaml +kind: role +version: v5 +metadata: + name: terraform-impersonator +spec: + # SSH options used for user sessions + options: + # max_session_ttl defines the TTL (time to live) of SSH certificates + # issued to the users with this role. + max_session_ttl: 10h + + # The allow section declares a list of resource/verb combinations that are + # allowed for the users of this role. By default, nothing is allowed. + allow: + impersonate: + users: ['terraform'] + roles: ['terraform'] + + # The deny section uses the identical format as the 'allow' section. + # Deny rules always override allow rules. + deny: + node_labels: + '*': '*' +``` + +Next, create the role: + +```code +$ tctl create terraform-impersonator.yaml +``` + +Assign this role to the current user. Log in to your Teleport cluster to assume +the new role. + +### Create the Terraform user Put the following content into `terraform.yaml`: @@ -74,79 +185,75 @@ spec: version: v2 ``` -Run: +Create the `terraform` user and role. ```code $ tctl create terraform.yaml -$ tctl auth sign --format=file --user=terraform --out=terraform-identity --ttl=10h ``` - -Clients missing impersonation privileges when trying to use `tctl auth sign`, -will get the following error: +Next, request a signed certificate for the Terraform user: -```txt -ERROR: access denied: impersonation is not allowed + + +```code +$ tctl auth sign --format=tls --user=terraform --out=auth ``` -Create the following file with role: `terraform-impersonator.yaml`: - -```yaml -kind: role -version: v5 -metadata: - name: terraform-impersonator -spec: - # SSH options used for user sessions - options: - # max_session_ttl defines the TTL (time to live) of SSH certificates - # issued to the users with this role. - max_session_ttl: 10h - - # allow section declares a list of resource/verb combinations that are - # allowed for the users of this role. by default nothing is allowed. - allow: - impersonate: - users: ['terraform'] - roles: ['terraform'] - - # the deny section uses the identical format as the 'allow' section. - # the deny rules always override allow rules. - deny: - node_labels: - '*': '*' -``` +This command should result in three PEM-encoded files: `auth.crt`, `auth.key`, +and `auth.cas` (certificate, private key, and CA certs, respectively). + + ```code -tctl create terraform-impersonator.yaml +$ tctl auth sign --user=terraform --out=terraform-identity ``` -Assign this role to the current user. Re-login to assume the new role and try -to issue certificate for terraform user again. +The above sequence should result in one PEM-encoded file: `terraform-identity`. - + + -## Step 3/4. Create Terraform configuration +## Step 3/4. Create a Terraform configuration -Create a `main.tf` terraform file: +Paste the following into a file called `main.tf` to define an example user and +role using Terraform. + + ``` -(!examples/resources/terraform/terraform-user-role.tf!) +(!examples/resources/terraform/terraform-user-role-cloud.tf!) ``` - - -Update `teleport.example.com:443` with the address of your Teleport cluster. - + + +``` +(!examples/resources/terraform/terraform-user-role-self-hosted.tf!) +``` + + ## Step 4/4. Apply the configuration -Check the contents of `teleport-terraform` folder: +Check the contents of the `teleport-terraform` folder: + + + ```code $ ls # main.tf terraform-identity terraform-impersonator.yaml terraform.yaml ``` + + + +```code +$ ls +# main.tf auth.crt auth.key auth.cas terraform-impersonator.yaml terraform.yaml +``` + + + + Init terraform and apply the spec: ```code @@ -156,5 +263,5 @@ $ terraform apply ## Next Steps -- Find the full list of [supported terraform provider resources](../reference/terraform-provider.mdx). +- Find the full list of [supported Terraform provider resources](../reference/terraform-provider.mdx). - Read more about [impersonation](../../access-controls/guides/impersonation.mdx). diff --git a/docs/pages/setup/operations/ca-rotation.mdx b/docs/pages/setup/operations/ca-rotation.mdx index 934b20114de66..dfeabee9a2388 100644 --- a/docs/pages/setup/operations/ca-rotation.mdx +++ b/docs/pages/setup/operations/ca-rotation.mdx @@ -5,20 +5,57 @@ description: How to rotate Teleport's certificate authority ## Prerequisites -- Installed [Teleport](../../getting-started.mdx) or [Teleport Cloud](../../cloud/introduction.mdx) >= (=teleport.version=) -- [Tctl admin tool](https://goteleport.com/teleport/download) >= (=teleport.version=) + + -(!docs/pages/includes/tctl.mdx!) +- A running Teleport cluster. For details on how to set this up, see [Getting + Started on a Linux Server](../../getting-started/linux-server.mdx). + +- The `tctl` admin tool version >= (=teleport.version=). - - For Cloud, log in with a Teleport user with editor privileges: ```code - # tsh logs you in and receives short-lived certificates - $ tsh login --proxy=myinstance.teleport.sh --user=email@example.com - # try out the connection - $ tctl get nodes + $ tctl version + # Teleport v(=teleport.version=) go(=teleport.golang=) ``` - + + See [Installation](../../installation.mdx) for details. + + + + +- A running Teleport cluster. For details on setting this up, see our + [Enterprise getting started guide](../../enterprise/getting-started.mdx). + +- The `tctl` admin tool version >= (=teleport.version=), which you can download + by visiting the + [customer portal](https://dashboard.gravitational.com/web/login). + + ```code + $ tctl version + # Teleport v(=teleport.version=) go(=teleport.golang=) + ``` + + + + +- A Teleport Cloud account. If you do not have one, visit the + [sign up page](https://goteleport.com/signup/) to begin your free trial. + +- The Enterprise version of the `tctl` admin tool. To download this, visit +the [customer portal](https://dashboard.gravitational.com/web/login). + + ```code + $ tctl version + # Teleport v(=teleport.version=) go(=teleport.golang=) + ``` + + + + +(!docs/pages/includes/tctl.mdx!) + ## Certificate Authority rotation diff --git a/examples/resources/terraform/terraform-user-role-cloud.tf b/examples/resources/terraform/terraform-user-role-cloud.tf new file mode 100644 index 0000000000000..cec5b0e38ce74 --- /dev/null +++ b/examples/resources/terraform/terraform-user-role-cloud.tf @@ -0,0 +1,79 @@ +terraform { + required_providers { + teleport = { + version = ">= (=teleport.version=)" + source = "gravitational.com/teleport/teleport" + } + } +} + +provider "teleport" { + # Update addr to point to your Teleport Cloud tenant URL + addr = "mytenant.teleport.sh" + identity_file_path = "terraform-identity" +} + +resource "teleport_role" "terraform-test" { + metadata { + name = "terraform-test" + description = "Terraform test role" + labels = { + example = "yes" + } + } + + spec { + options { + forward_agent = false + max_session_ttl = "30m" + port_forwarding = false + client_idle_timeout = "1h" + disconnect_expired_cert = true + permit_x11_forwarding = false + request_access = "denied" + } + + allow { + logins = ["this-user-does-not-exist"] + + rules { + resources = ["user", "role"] + verbs = ["list"] + } + + request { + roles = ["example"] + claims_to_roles { + claim = "example" + value = "example" + roles = ["example"] + } + } + + node_labels { + key = "example" + value = ["yes"] + } + } + + deny { + logins = ["anonymous"] + } + } +} + +resource "teleport_user" "terraform-test" { + metadata { + name = "terraform-test" + description = "Test terraform user" + expires = "2022-10-12T07:20:50.52Z" + + labels = { + test = "true" + } + } + + spec { + roles = ["terraform-test"] + } +} diff --git a/examples/resources/terraform/terraform-user-role.tf b/examples/resources/terraform/terraform-user-role-self-hosted.tf similarity index 93% rename from examples/resources/terraform/terraform-user-role.tf rename to examples/resources/terraform/terraform-user-role-self-hosted.tf index ac8204e31e550..893f977ca352d 100644 --- a/examples/resources/terraform/terraform-user-role.tf +++ b/examples/resources/terraform/terraform-user-role-self-hosted.tf @@ -11,7 +11,9 @@ provider "teleport" { # Update addr to point to Teleport Auth/Proxy # addr = "auth.example.com:3025" addr = "proxy.example.com:443" - identity_file_path = "terraform-identity" + cert_path = "auth.crt" + key_path = "auth.key" + root_ca_path = "auth.cas" } resource "teleport_role" "terraform-test" {