From 10857657a49cfb9d339d5461680c5e2b5c2bbd8d Mon Sep 17 00:00:00 2001 From: Paul Gottschling Date: Thu, 12 Sep 2024 08:51:36 -0400 Subject: [PATCH] Remove outdated `tctl get` examples (#46500) Closes #42389 Replace examples of using `tctl get` with `tctl edit` to show how to modify a dynamic resource. --- .../ssh-approval-pagerduty.mdx | 12 +++---- .../access-controls/device-trust/guide.mdx | 11 +++--- .../guides/per-session-mfa.mdx | 26 +++++--------- .../access-controls/guides/webauthn.mdx | 34 +++---------------- .../access-controls/sso/azuread.mdx | 10 ++---- .../management/admin/trustedclusters.mdx | 25 +++++--------- .../admin-guides/management/admin/users.mdx | 11 +++--- .../security/reduce-blast-radius.mdx | 12 +++---- .../database-access/troubleshooting.mdx | 18 +++++----- .../dynamic-registration.mdx | 14 +++----- .../machine-id/troubleshooting.mdx | 13 ++++--- docs/pages/includes/add-role-to-user.mdx | 16 +++------ docs/pages/includes/plugins/rbac-update.mdx | 12 ++----- .../server-access/custom-installer.mdx | 13 ++----- .../access-controls/authentication.mdx | 34 +++++++------------ .../database-access-reference/cli.mdx | 14 +++----- 16 files changed, 88 insertions(+), 187 deletions(-) diff --git a/docs/pages/admin-guides/access-controls/access-request-plugins/ssh-approval-pagerduty.mdx b/docs/pages/admin-guides/access-controls/access-request-plugins/ssh-approval-pagerduty.mdx index b3e3376e51e11..7d0b3538c3915 100644 --- a/docs/pages/admin-guides/access-controls/access-request-plugins/ssh-approval-pagerduty.mdx +++ b/docs/pages/admin-guides/access-controls/access-request-plugins/ssh-approval-pagerduty.mdx @@ -322,14 +322,14 @@ To grant these permissions to your user, give your user the `editor-reviewer`, `access-plugin-impersonator`, and `demo-role-requester` roles we defined earlier. -Retrieve your user definition: +Open your user definition in an editor: ```code $ TELEPORT_USER=$(tsh status --format=json | jq -r .active.username) -$ tctl get users/${TELEPORT_USER?} > myuser.yaml +$ tctl edit users/${TELEPORT_USER?} ``` -Edit `myuser.yaml` to include the roles you just created: +Edit the user to include the roles you just created: ```diff roles: @@ -341,11 +341,7 @@ Edit `myuser.yaml` to include the roles you just created: + - demo-role-requester ``` -Apply your changes: - -```code -$ tctl create -f myuser.yaml -``` +Apply your changes by saving and closing the file in your editor. Log out of your Teleport cluster and log in again. You will now be able to review requests for the `editor` role, request the `demo-role` role, and diff --git a/docs/pages/admin-guides/access-controls/device-trust/guide.mdx b/docs/pages/admin-guides/access-controls/device-trust/guide.mdx index bae6a30b3ffbf..a7d23b69fd429 100644 --- a/docs/pages/admin-guides/access-controls/device-trust/guide.mdx +++ b/docs/pages/admin-guides/access-controls/device-trust/guide.mdx @@ -94,13 +94,14 @@ For this guide, we will use the preset `require-trusted-device` role to update c -First, let's fetch the user profile locally so we can update it with the preset `require-trusted-device` role. +Open the user resource in your editor so we can update it with the preset `require-trusted-device` role. ```code -$ tctl get users/(=clusterDefaults.username=) > (=clusterDefaults.username=).yaml +$ tctl edit users/(=clusterDefaults.username=) ``` Edit the profile: + ```diff kind: user metadata: @@ -120,11 +121,7 @@ spec: ... ``` -Save and update user: - -```code -$ tctl create -f (=clusterDefaults.username=).yaml -``` +Update the user by saving and closing the file in your editor. Now that the user profile is updated to enforce Device Trust, try to access the test server again. diff --git a/docs/pages/admin-guides/access-controls/guides/per-session-mfa.mdx b/docs/pages/admin-guides/access-controls/guides/per-session-mfa.mdx index 96052a65ce119..e09365dd95da0 100644 --- a/docs/pages/admin-guides/access-controls/guides/per-session-mfa.mdx +++ b/docs/pages/admin-guides/access-controls/guides/per-session-mfa.mdx @@ -77,13 +77,13 @@ auth_service: -Obtain your existing `cluster_auth_preference` resource: +Edit your `cluster_auth_preference` resource: ```code -$ tctl get cap > cap.yaml +$ tctl edit cap ``` -Ensure that `cap.yaml` contains the following content: +Ensure that the resource contains the following content: ```yaml kind: cluster_auth_preference @@ -94,11 +94,7 @@ spec: version: v2 ``` -Create the resource: - -```code -$ tctl create -f cap.yaml -``` +Apply your changes by saving and closing the file in your editor. @@ -106,13 +102,13 @@ $ tctl create -f cap.yaml -Obtain your existing `cluster_auth_preference` resource: +Edit your `cluster_auth_preference` resource: ```code -$ tctl get cap > cap.yaml +$ tctl edit cap ``` -Ensure that `cap.yaml` contains the following content: +Ensure that the resource contains the following content: ```yaml kind: cluster_auth_preference @@ -123,11 +119,7 @@ spec: version: v2 ``` -Create the resource: - -```code -$ tctl create -f cap.yaml -``` +Apply your changes by saving and closing the file in your editor. @@ -267,4 +259,4 @@ Current limitations for this feature are: ## Next steps -- [Require MFA for administrative actions](./mfa-for-admin-actions.mdx) \ No newline at end of file +- [Require MFA for administrative actions](./mfa-for-admin-actions.mdx) diff --git a/docs/pages/admin-guides/access-controls/guides/webauthn.mdx b/docs/pages/admin-guides/access-controls/guides/webauthn.mdx index d957c1e4da9ba..98614b8c36dca 100644 --- a/docs/pages/admin-guides/access-controls/guides/webauthn.mdx +++ b/docs/pages/admin-guides/access-controls/guides/webauthn.mdx @@ -179,39 +179,16 @@ when starting new: to improve security. -### Step 1/2. Enforce MFA checks - To enforce MFA checks for all roles, edit your cluster authentication configuration: -Obtain your existing `cluster_auth_preference` resource: - -```code -$ tctl get cap > cap.yaml -``` - -Ensure that `cap.yaml` contains the following content: - -```yaml -kind: cluster_auth_preference -metadata: - name: cluster-auth-preference -spec: - require_session_mfa: true -version: v2 -``` - -```code -$ tctl create -f cap.yaml -``` - -Obtain your existing `cluster_auth_preference` resource: +Edit your `cluster_auth_preference` resource: ```code -$ tctl get cap > cap.yaml +$ tctl edit cap ``` -Ensure that `cap.yaml` contains the following content: +Ensure that the resource contains the following content: ```yaml kind: cluster_auth_preference @@ -222,11 +199,8 @@ spec: version: v2 ``` -### Step 2/2. Create the resource +Save and close the file in your editor to apply your changes. -```code -$ tctl create -f cap.yaml -``` ### Per role diff --git a/docs/pages/admin-guides/access-controls/sso/azuread.mdx b/docs/pages/admin-guides/access-controls/sso/azuread.mdx index 3d488c583bcd9..29a77ca537daa 100644 --- a/docs/pages/admin-guides/access-controls/sso/azuread.mdx +++ b/docs/pages/admin-guides/access-controls/sso/azuread.mdx @@ -220,10 +220,10 @@ the public certificate with Azure AD and the private key with Teleport. $ openssl req -nodes -new -x509 -keyout server.key -out server.cer ``` -If you are modifying the existing connector, write the YAML to a file first: +If you are modifying the existing connector, open it in your editor: ```code -$ tctl get saml --with-secrets > azure-out.yaml +$ tctl edit saml ``` You will notice that Teleport has generated a `signing_key_pair`. This key pair @@ -349,11 +349,7 @@ spec: version: v2 ``` -Update the connector: - -```code -$ tctl create -f azure-connector.yaml -``` +Update the connector by saving and closing the file in your editor. ### Activate token encryption diff --git a/docs/pages/admin-guides/management/admin/trustedclusters.mdx b/docs/pages/admin-guides/management/admin/trustedclusters.mdx index 09dd84f2360bd..8145f4cda66c2 100644 --- a/docs/pages/admin-guides/management/admin/trustedclusters.mdx +++ b/docs/pages/admin-guides/management/admin/trustedclusters.mdx @@ -263,16 +263,16 @@ your Teleport username: Replace `rootcluster.example.com` with the Teleport root cluster domain and `myuser` with your Teleport username. -1. Create a file called `user.yaml` with your current user configuration by running -a command similar to the following: +1. Open your user resource in your editor by running a command similar to the + following: ```code - $ tctl get user/ > user.yaml + $ tctl edit user/ ``` Replace `myuser` with your Teleport username. -1. Open the `user.yaml` file in a text editor and add the `visitor` login: +1. Add the `visitor` login: ```diff traits: @@ -282,11 +282,7 @@ a command similar to the following: - root ``` -1. Apply your changes by running the following command: - - ```code - $ tctl create -f user.yaml - ``` +1. Apply your changes by saving and closing the file in your editor. ## Step 3/6. Establish trust between clusters @@ -750,10 +746,10 @@ your Teleport username: Replace `leafcluster.example.com` with the Teleport leaf cluster domain and `myuser` with your Teleport username. -1. Retrieve the resource configuration by running the following command: +1. Edit the resource configuration by running the following command: ```code - $ tctl get trusted_cluster/ > trusted_cluster.yaml + $ tctl edit trusted_cluster/ ``` 1. Set the `spec.enabled` field to `false`: @@ -767,12 +763,9 @@ your Teleport username: - visitor ``` -1. Update the trusted cluster configuration by running the following command: +1. Update the trusted cluster configuration by saving and closing the file in + your editor. - ```code - $ tctl create --force trusted_cluster.yaml - ``` - This command closes the reverse tunnel between your leaf cluster and your root cluster. It also deactivates the root cluster's certificate authority on the leaf cluster. diff --git a/docs/pages/admin-guides/management/admin/users.mdx b/docs/pages/admin-guides/management/admin/users.mdx index 9182c65719387..5f71a26ba8875 100644 --- a/docs/pages/admin-guides/management/admin/users.mdx +++ b/docs/pages/admin-guides/management/admin/users.mdx @@ -91,17 +91,14 @@ For example, to see the full list of user records, an administrator can execute: $ tctl get users ``` -To edit the user `joe`: +To edit the user `joe`, run the following command: ```code -# Dump the user definition into a file: -$ tctl get user/joe > joe.yaml -# ... edit the contents of joe.yaml - -# Update the user record: -$ tctl create -f joe.yaml +$ tctl edit user/joe ``` +Make your changes, then save and close the file in your editor to apply them. + ## Deleting users Admins can delete a local user via `tctl`: diff --git a/docs/pages/admin-guides/management/security/reduce-blast-radius.mdx b/docs/pages/admin-guides/management/security/reduce-blast-radius.mdx index 7397a25ec2bc9..951dc49c91c5e 100644 --- a/docs/pages/admin-guides/management/security/reduce-blast-radius.mdx +++ b/docs/pages/admin-guides/management/security/reduce-blast-radius.mdx @@ -36,13 +36,13 @@ auth_service: -Obtain your existing `cluster_auth_preference` resource: +Edit your `cluster_auth_preference` resource: ```code -$ tctl get cap > cap.yaml +$ tctl edit cap ``` -In `cap.yaml`, ensure that the value of `spec.second_factor` is `otp`, +In the resource, ensure that the value of `spec.second_factor` is `otp`, `webauthn`, or `on`: ```yaml @@ -54,11 +54,7 @@ spec: second_factor: "otp" ``` -Apply your change: - -```code -$ tctl create -f cap.yaml -``` +Apply your change by saving and closing the file in your editor. diff --git a/docs/pages/enroll-resources/database-access/troubleshooting.mdx b/docs/pages/enroll-resources/database-access/troubleshooting.mdx index 50bf783fcda83..82c2cd1fd45a3 100644 --- a/docs/pages/enroll-resources/database-access/troubleshooting.mdx +++ b/docs/pages/enroll-resources/database-access/troubleshooting.mdx @@ -116,12 +116,15 @@ We can update a user's roles from the command-line by using either `tctl users u ``` - First save Alice's user resource to a local file: - ```sh - $ tctl get users/alice@example.com > alice.yaml + + Open Alice's user resource in your text editor: + + ```code + $ tctl edit users/alice@example.com ``` - Then modify `alice.yaml` to assign the `access` role: + Then modify the resource to assign the `access` role: + ```yaml kind: user metadata: @@ -133,11 +136,8 @@ We can update a user's roles from the command-line by using either `tctl users u db_names: ["*"] ``` - Finally, use `tctl create --force` to update the user - (`--force` is required to overwrite an already existing resource). - ```sh - $ tctl create --force alice.yaml - ``` + Save and close the file to apply your changes. + diff --git a/docs/pages/enroll-resources/kubernetes-access/register-clusters/dynamic-registration.mdx b/docs/pages/enroll-resources/kubernetes-access/register-clusters/dynamic-registration.mdx index f987c4de96e33..20389f079716c 100644 --- a/docs/pages/enroll-resources/kubernetes-access/register-clusters/dynamic-registration.mdx +++ b/docs/pages/enroll-resources/kubernetes-access/register-clusters/dynamic-registration.mdx @@ -390,13 +390,14 @@ $ tctl get kube_clusters ### Update a Kubernetes cluster resource To update the `kube_cluster` resource you created earlier, execute the following -command to retrieve the resource as it exists on the Auth Service's backend: +command to open the resource as it exists on the Auth Service's backend in your +text editor: ```code -$ tctl get kube_clusters/mycluster > kube_cluster.yaml +$ tctl edit kube_clusters/mycluster ``` -Edit the `kube_cluster.yaml` file to add a label to your `kube_cluster`: +Edit the resource to add a label to your `kube_cluster`: ```diff kind: kube_cluster @@ -413,12 +414,7 @@ Edit the `kube_cluster.yaml` file to add a label to your `kube_cluster`: version: v3 ``` -Update the resource: - -```code -$ tctl create -f kube_cluster.yaml -kubernetes cluster "mycluster" has been updated -``` +Save and close the file in your editor to apply your changes. You should now see the updated labels: diff --git a/docs/pages/enroll-resources/machine-id/troubleshooting.mdx b/docs/pages/enroll-resources/machine-id/troubleshooting.mdx index b8c479ea2a3de..c51225c3cb4b7 100644 --- a/docs/pages/enroll-resources/machine-id/troubleshooting.mdx +++ b/docs/pages/enroll-resources/machine-id/troubleshooting.mdx @@ -262,16 +262,15 @@ granted: $ tctl get role/machine-id-db ``` -If the role is missing database permissions, it can be modified: +If the role is missing database permissions, it can be modified in your text +editor: + ```code -## save the role to a local file -$ tctl get role/machine-id-db > db-role.yaml -## edit the role as necessary -$ nano db-role.yaml -## replace the existing role with the modified copy -$ tctl create -f db-role.yaml +$ tctl edit role/machine-id-db ``` +Edit the role, then save and close the file to apply your changes. + By default, outputs (like `/opt/machine-id`) are granted all roles provided to the bot via `tctl bots add --roles=...`, but it's possible to grant only a diff --git a/docs/pages/includes/add-role-to-user.mdx b/docs/pages/includes/add-role-to-user.mdx index cf74d273cef33..d25f83473952d 100644 --- a/docs/pages/includes/add-role-to-user.mdx +++ b/docs/pages/includes/add-role-to-user.mdx @@ -23,17 +23,13 @@ commands for your authentication provider: -1. Retrieve your `github` authentication connector: +1. Open your `github` authentication connector in a text editor: ```code - $ tctl get github/github --with-secrets > github.yaml + $ tctl edit github/github ``` - Note that the `--with-secrets` flag adds the value of `spec.signing_key_pair.private_key` - to the `github.yaml` file. Because this key contains a sensitive value, you should remove the - github.yaml file immediately after updating the resource. - -1. Edit `github.yaml`, adding `{{ role }}` to the `teams_to_roles` section. +1. Edit the `github` connector, adding `{{ role }}` to the `teams_to_roles` section. The team you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the team must include your user account and @@ -50,12 +46,8 @@ commands for your authentication provider: + - {{ role }} ``` -1. Apply your changes: +1. Apply your changes by saving closing the file in your editor. - ```code - $ tctl create -f github.yaml - ``` - 1. Sign out of the Teleport cluster and sign in again to assume the new role. diff --git a/docs/pages/includes/plugins/rbac-update.mdx b/docs/pages/includes/plugins/rbac-update.mdx index 39e1ece12a52c..4cfac0379ee92 100644 --- a/docs/pages/includes/plugins/rbac-update.mdx +++ b/docs/pages/includes/plugins/rbac-update.mdx @@ -66,14 +66,14 @@ Create the `access-plugin-impersonator` role: $ tctl create -f access-plugin-impersonator.yaml ``` -Retrieve your user definition: +Edit your user definition: ```code $ TELEPORT_USER=$(tsh status --format=json | jq -r .active.username) -$ tctl get users/${TELEPORT_USER?} > myuser.yaml +$ tctl edit users/${TELEPORT_USER?} ``` -Edit `myuser.yaml` to include the role you just created: +Edit your user to include the role you just created: ```diff roles: @@ -83,11 +83,5 @@ Edit `myuser.yaml` to include the role you just created: + - access-plugin-impersonator ``` -Apply your changes: - -```code -$ tctl create -f myuser.yaml -``` - Log out of your Teleport cluster and log in again. You will now be able to generate signed certificates for the `access-plugin` role and user. diff --git a/docs/pages/includes/server-access/custom-installer.mdx b/docs/pages/includes/server-access/custom-installer.mdx index bfd999c573448..c3f1bdc309133 100644 --- a/docs/pages/includes/server-access/custom-installer.mdx +++ b/docs/pages/includes/server-access/custom-installer.mdx @@ -27,18 +27,11 @@ To customize the default installer script, execute the following command on your workstation: ```code -$ tctl get installer/default-installer > teleport-default-installer.yaml +$ tctl edit installer/default-installer ``` -The resulting `teleport-default-installer.yaml` can be edited to -change what gets executed when enrolling discovered instances. - -After making the desired changes to the default installer, the -resource can be updated by executing: - -```code -$ tctl create -f teleport-default-installer.yaml -``` +After making the desired changes to the default installer, save and close the +file in your text editor. Multiple `installer` resources can exist and be specified in the `{{ matcher }}.install.script_name` section of a `discovery_service.{{ matcher }}` list item in diff --git a/docs/pages/reference/access-controls/authentication.mdx b/docs/pages/reference/access-controls/authentication.mdx index 752a258ab0b2a..1f6feafcd791c 100644 --- a/docs/pages/reference/access-controls/authentication.mdx +++ b/docs/pages/reference/access-controls/authentication.mdx @@ -54,13 +54,13 @@ Add the following to your Teleport configuration file, which is stored in ### Dynamic resource -Obtain your existing `cluster_auth_preference` resource: +Edit your `cluster_auth_preference` resource: ```code -$ tctl get cap > cap.yaml +$ tctl edit cap ``` -Ensure that `cap.yaml` includes the following content: +Ensure that the resource includes the following content: ```yaml kind: cluster_auth_preference @@ -74,11 +74,8 @@ spec: version: v2 ``` -Create the `cluster_auth_preference` resource via `tctl`: +Save and close the file in your editor to apply changes. -```code -$ tctl create -f cap.yaml -``` @@ -91,10 +88,10 @@ $ tsh login --proxy=myinstance.teleport.sh $ tctl status ``` -Obtain your existing `cluster_auth_preference` resource: +Edit your `cluster_auth_preference` resource: ```code -$ tctl get cap > cap.yaml +$ tctl edit cap ``` Ensure that `cap.yaml` includes the following content: @@ -111,11 +108,8 @@ spec: version: v2 ``` -Create the `cluster_auth_preference` resource via `tctl`: +Save and close the file in your editor to apply changes. -```code -$ tctl create -f cap.yaml -``` @@ -131,13 +125,13 @@ Overriding a block is available to users with rights to maintain `user` resource available in the built-in `editor` role. To turn off a block, update the user entry, following these steps. -Retrieve the user entry so you can edit the status: +Open the user resource in your editor: ```code -$ tctl get users/ > user.yaml +$ tctl edit users/ ``` -The file `user.yaml` should resemble the following: +The resource should resemble the following: ```yaml kind: user @@ -153,12 +147,8 @@ spec: version: v2 ``` -Update the `is_locked` field under `status` to `false` and save the file. Now -update the user entry with the command below: - -```code -$ tctl create -f user.yaml -``` +Update the `is_locked` field under `status` to `false`, save the file, and close +your editor. The user will now be unblocked from login attempts and can attempt to authenticate again. diff --git a/docs/pages/reference/agent-services/database-access-reference/cli.mdx b/docs/pages/reference/agent-services/database-access-reference/cli.mdx index a03f9ed81bdf8..9a3b50c81fd06 100644 --- a/docs/pages/reference/agent-services/database-access-reference/cli.mdx +++ b/docs/pages/reference/agent-services/database-access-reference/cli.mdx @@ -228,15 +228,15 @@ Create the role: $ tctl create -f db-impersonator.yaml ``` -Retrieve your Teleport user's dynamic configuration resource so you can add the -`db-impersonator` role: +Open your Teleport user's dynamic configuration resource in your editor so you +can add the `db-impersonator` role: ```code $ TELEPORT_USER= -$ tctl get user/${TELEPORT_USER?} > myuser.yaml +$ tctl edit user/${TELEPORT_USER?} ``` -Edit `myuser.yaml` to add the `db-impersonator` role: +Add the `db-impersonator` role: ```diff spec: @@ -248,11 +248,7 @@ spec: is_locked: false ``` -Update your user: - -```code -$ tctl create -f myuser.yaml -``` +Update your user by saving and closing the file in your editor. Log out of your Teleport cluster and log in again. You will now be able to run `tctl auth sign` for database-specific certificate formats.