diff --git a/docs/pages/admin-guides/access-controls/guides/locking.mdx b/docs/pages/admin-guides/access-controls/guides/locking.mdx index c71bd5f3e6313..69567f86022f3 100644 --- a/docs/pages/admin-guides/access-controls/guides/locking.mdx +++ b/docs/pages/admin-guides/access-controls/guides/locking.mdx @@ -194,51 +194,27 @@ the last known locks. This decision strategy is encoded as one of the two modes: The cluster-wide mode defaults to `best_effort`. You can set up the default locking mode via API or CLI using a `cluster_auth_preference` resource or static -configuration file: +configuration file. - - - - Create a YAML file called `cap.yaml` or get the existing file using - `tctl get cap`. - - ```yaml - kind: cluster_auth_preference - metadata: - name: cluster-auth-preference - spec: - locking_mode: best_effort - version: v2 - ``` - - Create a resource: - - ```code - $ tctl create -f cap.yaml - # cluster auth preference has been updated - ``` - - - Edit `/etc/teleport.yaml` on the Auth Server: +If your Auth Service configuration (`/etc/teleport.yaml` by default) contains +an `auth_service.authentication` section, edit the Teleport configuration +file to contain the following: - ```yaml - auth_service: - authentication: - locking_mode: best_effort - ``` +```yaml +auth_service: + authentication: + locking_mode: best_effort +``` - Restart the Auth Server for the change to take effect. - - +Restart or redeploy the Auth Service for the change to take effect. - - +If not, edit your cluster authentication preference resource: -The cluster-wide mode defaults to `best_effort`. You can set up the default -locking mode via API or CLI using a `cluster_auth_preference` resource: +```code +$ tctl edit cap +``` -Create a YAML file called `cap.yaml` or get the existing file using -`tctl get cap`. +Adjust the file in your editor to include the following: ```yaml kind: cluster_auth_preference @@ -249,15 +225,32 @@ spec: version: v2 ``` -Create a resource: +Save and close your editor to apply your changes. + + + + +The cluster-wide mode defaults to `best_effort`. You can set up the default +locking mode via API or CLI using a `cluster_auth_preference` resource: ```code -$ tctl create -f cap.yaml -# cluster auth preference has been updated +$ tctl edit cap ``` - +Adjust the file in your editor to include the following: + +```yaml +kind: cluster_auth_preference +metadata: + name: cluster-auth-preference +spec: + locking_mode: best_effort +version: v2 +``` + +Save and close your editor to apply your changes. + It is also possible to configure the locking mode for a particular role: diff --git a/docs/pages/admin-guides/deploy-a-cluster/helm-deployments/aws.mdx b/docs/pages/admin-guides/deploy-a-cluster/helm-deployments/aws.mdx index b3aadada628cd..de375be78b5df 100644 --- a/docs/pages/admin-guides/deploy-a-cluster/helm-deployments/aws.mdx +++ b/docs/pages/admin-guides/deploy-a-cluster/helm-deployments/aws.mdx @@ -290,11 +290,9 @@ Edit your `aws-values.yaml` file (created below) to refer to the name of your se ## Step 5/7. Set values to configure the cluster - - - -Before you can install Teleport in your Kubernetes cluster, you will need to -create a secret that contains your Teleport license information. +If you run Teleport Enterprise, you will need to create a secret that contains +your Teleport license information before you can install Teleport in your +Kubernetes cluster. (!docs/pages/includes//enterprise/obtainlicense.mdx!) @@ -305,105 +303,9 @@ this secret as long as your file is named `license.pem`. $ kubectl -n create secret generic license --from-file=license.pem ``` - - - - Next, configure the `teleport-cluster` Helm chart to use the `aws` mode. Create a file called `aws-values.yaml` and write the values you've chosen above to it: - - - - - -```yaml -chartMode: aws -clusterName: # Name of your cluster. Use the FQDN you intend to configure in DNS below. -proxyListenerMode: multiplex -aws: - region: # AWS region - backendTable: # DynamoDB table to use for the Teleport backend - auditLogTable: # DynamoDB table to use for the Teleport audit log (must be different to the backend table) - auditLogMirrorOnStdout: false # Whether to mirror audit log entries to stdout in JSON format (useful for external log collectors) - sessionRecordingBucket: # S3 bucket to use for Teleport session recordings - backups: true # Whether or not to turn on DynamoDB backups - dynamoAutoScaling: false # Whether Teleport should configure DynamoDB's autoscaling. -highAvailability: - replicaCount: 2 # Number of replicas to configure - certManager: - enabled: true # Enable cert-manager support to get TLS certificates - issuerName: letsencrypt-production # Name of the cert-manager Issuer to use (as configured above) -# If you are running Kubernetes 1.23 or above, disable PodSecurityPolicies -podSecurityPolicy: - enabled: false -``` - -If using an AWS PCA with cert-manager, you will need to -[ensure you set](../../../reference/helm-reference/teleport-cluster.mdx) -`highAvailability.certManager.addCommonName: true` in your values file. You will also need to get the certificate authority -certificate for the CA (`aws acm-pca get-certificate-authority-certificate --certificate-authority-arn `), -upload the full certificate chain to a secret, and -[reference the secret](../../../reference/helm-reference/teleport-cluster.mdx) -with `tls.existingCASecretName` in the values file. - - - -```yaml -chartMode: aws -clusterName: # Name of your cluster. Use the FQDN you intend to configure in DNS below. -proxyListenerMode: multiplex -service: - type: ClusterIP -aws: - region: # AWS region - backendTable: # DynamoDB table to use for the Teleport backend - auditLogTable: # DynamoDB table to use for the Teleport audit log (must be different to the backend table) - auditLogMirrorOnStdout: false # Whether to mirror audit log entries to stdout in JSON format (useful for external log collectors) - sessionRecordingBucket: # S3 bucket to use for Teleport session recordings - backups: true # Whether or not to turn on DynamoDB backups - dynamoAutoScaling: false # Whether Teleport should configure DynamoDB's autoscaling. -highAvailability: - replicaCount: 2 # Number of replicas to configure -ingress: - enabled: true - spec: - ingressClassName: alb -annotations: - ingress: - alb.ingress.kubernetes.io/target-type: ip - alb.ingress.kubernetes.io/backend-protocol: HTTPS - alb.ingress.kubernetes.io/scheme: internet-facing - alb.ingress.kubernetes.io/load-balancer-attributes: idle_timeout.timeout_seconds=350 - alb.ingress.kubernetes.io/healthcheck-protocol: HTTPS - alb.ingress.kubernetes.io/success-codes: 200,301,302 - # Replace with your AWS certificate ARN - alb.ingress.kubernetes.io/certificate-arn: "" -# If you are running Kubernetes 1.23 or above, disable PodSecurityPolicies -podSecurityPolicy: - enabled: false -``` - -To use an internal AWS application load balancer (as opposed to an internet-facing ALB), you should -edit the `alb.ingress.kubernetes.io/scheme` annotation: - - ```yaml - alb.ingress.kubernetes.io/scheme: internal - ``` - -To automatically redirect HTTP requests on port 80 to HTTPS requests on port 443, you -can also optionally provide these two values under `annotations.ingress`: - - ```yaml - alb.ingress.kubernetes.io/listen-ports: '[{"HTTP": 80}, {"HTTPS": 443}]' - alb.ingress.kubernetes.io/ssl-redirect: '443' - ``` - - - - - - ```yaml @@ -423,7 +325,9 @@ highAvailability: certManager: enabled: true # Enable cert-manager support to get TLS certificates issuerName: letsencrypt-production # Name of the cert-manager Issuer to use (as configured above) -enterprise: true # Indicate that this is a Teleport Enterprise deployment +# Indicate that this is a Teleport Enterprise deployment. Set to false for +# Teleport Community Edition. +enterprise: true # If you are running Kubernetes 1.23 or above, disable PodSecurityPolicies podSecurityPolicy: enabled: false @@ -455,7 +359,9 @@ aws: dynamoAutoScaling: false # Whether Teleport should configure DynamoDB's autoscaling. highAvailability: replicaCount: 2 # Number of replicas to configure -enterprise: true # Indicate that this is a Teleport Enterprise deployment +# Indicate that this is a Teleport Enterprise deployment. Set to false for +# Teleport Community Edition. +enterprise: true ingress: enabled: true spec: @@ -493,10 +399,6 @@ can also optionally provide these two values under `annotations.ingress`: - - - - Install the chart with the values from your `aws-values.yaml` file using this command: ```code diff --git a/docs/pages/admin-guides/management/admin/self-signed-certs.mdx b/docs/pages/admin-guides/management/admin/self-signed-certs.mdx index 2c7d4d89d52e2..0bdf021076e7d 100644 --- a/docs/pages/admin-guides/management/admin/self-signed-certs.mdx +++ b/docs/pages/admin-guides/management/admin/self-signed-certs.mdx @@ -110,37 +110,37 @@ running Teleport: via the `teleport` CLI, using a Helm chart, or via systemd: If you are using the `teleport-cluster` Helm chart, set [extraArgs](../../../reference/helm-reference/teleport-cluster.mdx) - to include the extra argument: `--insecure`: - - - ```yaml - extraArgs: - - "--insecure" - ``` - - - ```code - $ --set "extraArgs={--insecure}" + to include the extra argument: `--insecure`. + + Here is an example of the field within a values file: + + ```yaml + extraArgs: + - "--insecure" + ``` + + When using the `--set` flag, use the following syntax: + + + ```text + --set "extraArgs={--insecure}" ``` - - - If you are using the `teleport-kube-agent` chart, set the [insecureSkipProxyTLSVerify](../../../reference/helm-reference/teleport-kube-agent.mdx) - flag to `true`: - - - ```yaml - insecureSkipProxyTLSVerify: true - ``` - - - ```code - $ --set insecureSkipProxyTLSVerify=true - ``` - - + flag to `true`. + + In a values file, this would appear as follows: + + ```yaml + insecureSkipProxyTLSVerify: true + ``` + + When using the `--set` flag, use the following syntax: + + ```text + --set insecureSkipProxyTLSVerify=true + ``` diff --git a/docs/pages/connect-your-client/gui-clients.mdx b/docs/pages/connect-your-client/gui-clients.mdx index 50917aafcf0a6..30bc8ef8b727e 100644 --- a/docs/pages/connect-your-client/gui-clients.mdx +++ b/docs/pages/connect-your-client/gui-clients.mdx @@ -19,11 +19,32 @@ work with Teleport. ### Get connection information - - +Get information about the host and port where your database is available so you +can configure your GUI client to access the database. + +#### Using a local proxy server + +Use the `tsh proxy db` command to start a local TLS proxy your GUI database +client will be connecting to. This command requires that you use Teleport +Enterprise (Cloud) or, if self-hosting Teleport, have enabled [TLS +routing](../admin-guides/management/operations/tls-routing.mdx) mode. + +Run a command similar to the following:: + +```code +$ tsh proxy db +Started DB proxy on 127.0.0.1:61740 + +Use following credentials to connect to the proxy: + ca_file=/Users/r0mant/.tsh/keys/root.gravitational.io/certs.pem + cert_file=/Users/r0mant/.tsh/keys/root.gravitational.io/alice-db/root/-x509.pem + key_file=/Users/r0mant/.tsh/keys/root.gravitational.io/alice +``` + +Use the displayed local proxy host/port and credentials paths when configuring +your GUI client below. When entering the hostname, use `localhost` rather than +`127.0.0.1`. - - Starting the local database proxy with the `--tunnel` flag will create an authenticated tunnel that you can use to connect to your database instances. You won't need to configure any credentials when connecting to this tunnel. @@ -46,30 +67,11 @@ $ tsh proxy db --db-user=my-database-user --db-name=my-schema --tunnel - -If you're using Teleport in [TLS routing](../admin-guides/management/operations/tls-routing.mdx) -mode where each database protocol is multiplexed on the same web proxy port, use -the following command to start a local TLS proxy your GUI database client will -be connecting to: - -```code -$ tsh proxy db -Started DB proxy on 127.0.0.1:61740 - -Use following credentials to connect to the proxy: - ca_file=/Users/r0mant/.tsh/keys/root.gravitational.io/certs.pem - cert_file=/Users/r0mant/.tsh/keys/root.gravitational.io/alice-db/root/-x509.pem - key_file=/Users/r0mant/.tsh/keys/root.gravitational.io/alice -``` +#### Using a remote host and port -Use the displayed local proxy host/port and credentials paths when configuring -your GUI client below. When entering the hostname, use `localhost` rather than -`127.0.0.1`. - - -If you're not using TLS routing, run the following command to see the database -connection information: +If you are self-hosting Teleport and not using [TLS +routing](../admin-guides/management/operations/tls-routing.mdx), run the +following command to see the database connection information: ```code # View configuration for the database you're logged in to. @@ -94,32 +96,6 @@ Key: /Users/alice/.tsh/keys/teleport.example.com/alice The displayed `CA`, `Cert`, and `Key` files are used to connect through pgAdmin 4, MySQL Workbench, and other graphical database clients that support mutual TLS authentication. - - - - - - -Use the following command to start a local TLS proxy your GUI database client -will be connecting to: - -```code -$ tsh proxy db -Started DB proxy on 127.0.0.1:61740 - -Use following credentials to connect to the proxy: - ca_file=/Users/r0mant/.tsh/keys/root.gravitational.io/certs.pem - cert_file=/Users/r0mant/.tsh/keys/root.gravitational.io/alice-db/root/-x509.pem - key_file=/Users/r0mant/.tsh/keys/root.gravitational.io/alice -``` - -Use the displayed local proxy host/port and credentials paths when configuring -your GUI client below. When entering the hostname, use `localhost` rather than -`127.0.0.1`. - - - - ## MongoDB Compass diff --git a/docs/pages/connect-your-client/introduction.mdx b/docs/pages/connect-your-client/introduction.mdx index 233e5c2fe4e3e..2cb79ea46eb65 100644 --- a/docs/pages/connect-your-client/introduction.mdx +++ b/docs/pages/connect-your-client/introduction.mdx @@ -15,53 +15,12 @@ Teleport, and includes links to more detailed documentation at the end. [downloading](https://goteleport.com/download/) and installing `tsh`, sign in to your Teleport cluster: - - -```code -$ tsh login --proxy= --user= -Enter password for Teleport user alice: -Tap any security key -> Profile URL: https://teleport.example.com:443 - Logged in as: alice - Cluster: example.com - Roles: access - Logins: ubuntu, ec2-user - Kubernetes: enabled - Valid until: 2022-11-01 22:37:05 -0500 CDT [valid for 12h0m0s] - Extensions: permit-agent-forwarding, permit-port-forwarding, permit-pty, private-key-policy -``` - - - - -```code -$ tsh login --proxy= --auth=github -If browser window does not open automatically, open it by clicking on the link: - http://127.0.0.1:49927/1d80e257-ec61-4ed2-9403-784f8d35b2fe -> Profile URL: https://teleport.example.com:443 - Logged in as: user@example.com - Cluster: example.com - Roles: access - Logins: ubuntu, ec2-user - Kubernetes: enabled - Valid until: 2022-11-01 22:37:05 -0500 CDT [valid for 12h0m0s] - Extensions: permit-agent-forwarding, permit-port-forwarding, permit-pty, private-key-policy -``` - -Depending on how Teleport was configured for your network, you may not need -the additional flags `--auth`. Your administrator should provide the details -required for your particular use case. - - - - +Authenticate to Teleport as a local user with `tsh login` by +assigning to your Teleport username: - - - ```code $ tsh login --proxy= --user= Enter password for Teleport user alice: @@ -77,7 +36,11 @@ Tap any security key ``` - + + +Authenticate to Teleport as a single sign-on (SSO) user by running `tsh login` +and assinging the `auth` flag to the name of your authentication connector, if +implemented by your administrators: ```code $ tsh login --proxy= --auth= @@ -97,8 +60,6 @@ Depending on how Teleport was configured for your network, you may not need the additional flags `--auth`. Your administrator should provide the details required for your particular use case. - - diff --git a/docs/pages/enroll-resources/auto-discovery/kubernetes/aws.mdx b/docs/pages/enroll-resources/auto-discovery/kubernetes/aws.mdx index 92d2f6ac9c52c..1d16e399667ee 100644 --- a/docs/pages/enroll-resources/auto-discovery/kubernetes/aws.mdx +++ b/docs/pages/enroll-resources/auto-discovery/kubernetes/aws.mdx @@ -137,11 +137,26 @@ subjects: ### IAM mapping - - +If you cluster includes the `aws-auth` config map, edit the `configmap/aws-auth` +in the `kube-system` namespace and append the following to `mapRoles`. Replace +`{teleport_aws_iam_role}` with the appropriate IAM role that Teleport Kubernetes +Service will use. This step will link the Teleport IAM role into the Kubernetes +RBAC group `teleport`, allowing Teleport Kubernetes Service to forward requests +into the cluster: + +```yaml +apiVersion: v1 +data: + mapRoles: | + - groups: + - teleport + rolearn: {teleport_aws_iam_role} # e.g. arn:aws:iam::222222222222:role/teleport-role + username: teleport +``` -Create an EKS access entry to link the -to the Kubernetes Group `teleport` we created in the previous step. +Otherwise, create an EKS access entry to link the to the Kubernetes Group +`teleport` we created in the previous step: ```code $ aws eks create-access-entry \ @@ -155,28 +170,6 @@ $ aws eks create-access-entry \ } ``` - - - - -Finally, edit the `configmap/aws-auth` in the `kube-system` namespace and append -the following to `mapRoles`. Replace `{teleport_aws_iam_role}` with the -appropriate IAM role that Teleport Kubernetes Service will use. -This step will link the Teleport IAM role into the Kubernetes RBAC group `teleport`, -allowing Teleport Kubernetes Service to forward requests into the cluster. - -```yaml -apiVersion: v1 -data: - mapRoles: | - - groups: - - teleport - rolearn: {teleport_aws_iam_role} # e.g. arn:aws:iam::222222222222:role/teleport-role - username: teleport -``` - - - At this point, the Teleport IAM role already has the minimum permissions to forward requests to the cluster. @@ -215,13 +208,29 @@ service means granting administrator-level permissions on the Kubernetes cluster To follow least privilege principle we do not recommend using this method in production. +If your cluster contains an `aws-auth` config map, you can use this to associate +the Teleport IAM role with the `system:masters` RBAC group. Edit the +`configmap/aws-auth` in the `kube-system` namespace and append the following to +`mapRoles`: +```yaml +apiVersion: v1 +data: + mapRoles: | + ... + - groups: + - system:masters + rolearn: {teleport_aws_iam_role} # e.g. arn:aws:iam::222222222222:role/teleport-role + username: teleport +``` - - +Replace `{teleport_aws_iam_role}` with the appropriate IAM role that +Teleport Kubernetes Service is using. -Create an EKS access entry and Access Policy to link the -to the cluster wide policy `arn:aws:eks::aws:cluster-access-policy/AmazonEKSClusterAdminPolicy` (equivalent of `cluster-admin` `ClusterRole`). +Otherwise, create an EKS access entry and Access Policy to link the to the cluster wide +policy `arn:aws:eks::aws:cluster-access-policy/AmazonEKSClusterAdminPolicy` +(equivalent of `cluster-admin` `ClusterRole`): ```code $ aws eks create-access-entry \ @@ -246,31 +255,6 @@ $ aws eks associate-access-policy \ ``` - - - - -To associate the Teleport IAM role with the `system:masters` RBAC group, -edit the `configmap/aws-auth` in the `kube-system` namespace and append -the following to `mapRoles`. - -```yaml -apiVersion: v1 -data: - mapRoles: | - ... - - groups: - - system:masters - rolearn: {teleport_aws_iam_role} # e.g. arn:aws:iam::222222222222:role/teleport-role - username: teleport -``` - -Please replace `{teleport_aws_iam_role}` with the appropriate IAM role that -Teleport Kubernetes Service is using. - - - - At this point, the Teleport IAM role already has the minimum permissions to forward requests to the cluster. diff --git a/docs/pages/reference/architecture/architecture.mdx b/docs/pages/reference/architecture/architecture.mdx index bab8bbee62285..7400da6f4dfc4 100644 --- a/docs/pages/reference/architecture/architecture.mdx +++ b/docs/pages/reference/architecture/architecture.mdx @@ -93,7 +93,7 @@ about the architecture of Teleport Agent features: Teleport cluster ensures that Agents run the most up-to-date version of the `teleport` binary. - [Automatically discovering Kubernetes - applications](../../reference/architecture//kubernetes-applications-architecture.mdx): + applications](../../reference/architecture/kubernetes-applications-architecture.mdx): The Teleport Discovery Service queries your Kubernetes cluster and registers applications with the Teleport Auth Service. - [Session recordings](session-recording.mdx): Teleport Agents record user