Skip to content

Commit

Permalink
Remove outdated tctl get examples (#46533)
Browse files Browse the repository at this point in the history
Closes #42389

Replace examples of using `tctl get` with `tctl edit` to show how to
modify a dynamic resource.
  • Loading branch information
ptgott authored Sep 12, 2024
1 parent 8ada959 commit 5fa5f15
Show file tree
Hide file tree
Showing 16 changed files with 88 additions and 187 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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
Expand Down
11 changes: 4 additions & 7 deletions docs/pages/admin-guides/access-controls/device-trust/guide.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -94,13 +94,14 @@ For this guide, we will use the preset `require-trusted-device` role to update c
</Details>
</Admonition>
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:
Expand All @@ -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.
Expand Down
26 changes: 9 additions & 17 deletions docs/pages/admin-guides/access-controls/guides/per-session-mfa.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -77,13 +77,13 @@ auth_service:
</TabItem>
<TabItem label="Dynamic resources">

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
Expand All @@ -94,25 +94,21 @@ spec:
version: v2
```

Create the resource:

```code
$ tctl create -f cap.yaml
```
Apply your changes by saving and closing the file in your editor.

</TabItem>
</Tabs>

</TabItem>
<TabItem scope="cloud" label="Teleport Enterprise">

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
Expand All @@ -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.

</TabItem>

Expand Down Expand Up @@ -267,4 +259,4 @@ Current limitations for this feature are:

## Next steps

- [Require MFA for administrative actions](./mfa-for-admin-actions.mdx)
- [Require MFA for administrative actions](./mfa-for-admin-actions.mdx)
34 changes: 4 additions & 30 deletions docs/pages/admin-guides/access-controls/guides/webauthn.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -179,39 +179,16 @@ when starting new:
to improve security.
</Notice>

### 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
Expand All @@ -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

Expand Down
10 changes: 3 additions & 7 deletions docs/pages/admin-guides/access-controls/sso/azuread.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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

Expand Down
25 changes: 9 additions & 16 deletions docs/pages/admin-guides/management/admin/trustedclusters.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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/<Var name="myuser" /> > user.yaml
$ tctl edit user/<Var name="myuser" />
```

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:
Expand All @@ -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

Expand Down Expand Up @@ -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/<Var name="rootcluster.example.com" /> > trusted_cluster.yaml
$ tctl edit trusted_cluster/<Var name="rootcluster.example.com" />
```

1. Set the `spec.enabled` field to `false`:
Expand All @@ -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.

Expand Down
11 changes: 4 additions & 7 deletions docs/pages/admin-guides/management/admin/users.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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`:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -36,13 +36,13 @@ auth_service:
</TabItem>
<TabItem label="Cloud-Hosted" scope={["cloud","team"]}>
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
Expand All @@ -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.

</TabItem>
</Tabs>
Expand Down
18 changes: 9 additions & 9 deletions docs/pages/enroll-resources/database-access/troubleshooting.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -116,12 +116,15 @@ We can update a user's roles from the command-line by using either `tctl users u
```
</TabItem>
<TabItem label="tctl create">
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:
Expand All @@ -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.

</TabItem>
</Tabs>

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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:

Expand Down
Loading

0 comments on commit 5fa5f15

Please sign in to comment.