Merge branch 'main' into benny/pass-on-connvergence-pages

Author: rosieyohannan

docs/guides/modules/integration/pages/add-ssh-key.adoc

@@ -18,7 +18,7 @@ See the following VCS-specific docs for additional details on creating SSH keys:
 ****
 
 [#steps-to-add-additional-ssh-keys]
-== 1. Add an additional SSH key to your project
+== Add an additional SSH key to your project
 
 CircleCI cannot decrypt SSH keys, therefore every new key must have an empty passphrase. The below examples are for macOS.
 
@@ -35,7 +35,7 @@ If you have a GitLab integration, you will find that an additional SSH key alrea
 . Select *Add SSH Key*.
 
 [#add-ssh-keys-to-a-job]
-== 2. Add SSH keys to a job
+== Add SSH keys to a job
 
 Even though all CircleCI jobs use `ssh-agent` to automatically sign all added SSH keys, you *must* use the `add_ssh_keys` key to actually add keys to a container.
 
@@ -63,9 +63,49 @@ All fingerprints in the `fingerprints` list must correspond to keys that have be
 To checkout additional repositories from within your job, ensure that you run the `checkout` command *before* `add_ssh_keys`; otherwise, `CIRCLE_CI_REPOSITORY_URL` will be empty.  Also ensure that the private key is added to the CircleCI project and that the public key has been added to the additional repositories that you want to checkout from within your job.
 
 [#adding-multiple-keys-with-blank-hostnames]
-== Adding multiple keys with blank hostnames
+=== Adding multiple keys with blank hostnames
 
-If you need to add multiple SSH keys with blank hostnames to your project, you will need to make some changes to the default SSH configuration provided by CircleCI. In the scenario where you have multiple SSH keys that have access to the same hosts, but are for different purposes the default `IdentitiesOnly no` is set causing connections to use `ssh-agent`. This will always cause the first key to be used, even if that is the incorrect key. If you have added the SSH key to a container, you will need to either set `IdentitiesOnly no` in the appropriate block, or you can remove all keys from the `ssh-agent` for this job using `ssh-add -D`, and reading the key added with `ssh-add /path/to/key`.
+If you add multiple SSH keys with blank hostnames to your project, you will need to make some changes to the default SSH configuration provided by CircleCI.
+
+If you have multiple SSH keys for different purposes that have access to the same hosts, the default `IdentitiesOnly no` is set, which causes connections to use `ssh-agent`.
+
+In this scenario the first key is used regardless of whether it is the correct key. If you have added the SSH key to a container, you will need to either set `IdentitiesOnly yes` in the appropriate block, or you can remove all keys from the `ssh-agent` for the job using `ssh-add -D` and read the added key using `ssh-add /path/to/key`.
+
+[#using-specific-ssh-keys-for-a-job]
+=== Using specific SSH keys for a job
+
+[NOTE]
+====
+SSH keys are named using MD5 fingerprints with colons removed from the hash.
+
+To retrieve the MD5 fingerprint of an SSH key, run this command locally:
+
+`ssh-keygen -l -E md5 -f ~/.ssh/your_key_name`
+
+The filename follows this format:
+
+`id_rsa_[MD5_fingerprint_without_colons]`
+
+Example:
+
+- SSH key MD5 fingerprint: `a3:f9:82:c5:1d:47:9b:e6:88:32:a1:bc:f4:29:7e:15`.
+
+- SSH key filename: `id_rsa_a3f982c51d479be68832a1bcf4297e15`.
+====
+
+
+If you have added multiple SSH keys for the same hostname to your project and want to use a specific key in your SSH commands, follow these steps:
+
+. Add the SSH key to the job using the `add_ssh_keys` step.
+. Use the `-i` parameter to specify the exact SSH key file path in your SSH commands.
+. Add the `-o "IdentitiesOnly=yes"` option to prevent SSH from using other keys from the SSH agent.
+
+Example:
+
+[source,bash]
+----
+ssh -i ~/.ssh/id_rsa_a3f982c51d479be68832a1bcf4297e15 -o "IdentitiesOnly=yes" user@hostname
+----
 
 [#see-also]
 == See also

docs/guides/modules/toolkit/pages/how-to-use-the-circleci-local-cli.adoc

@@ -330,6 +330,134 @@ circleci build -e VAR1=FOO -e VAR2=BAR
 
 The CircleCI CLI is used for some advanced features during job runs, for example xref:optimize:use-the-circleci-cli-to-split-tests.adoc[test splitting] for build time optimization.
 
+[#runner-management]
+== Runner management
+
+You can operate on your self-hosted runners using the CLI.
+
+=== List runner instances
+
+Use the `runner instance list` sub-command to get a list of your runner instances.
+
+For your namespace:
+
+[,shell]
+----
+circleci runner instance list <namespace> [flags]
+----
+
+For a specific resource class:
+
+[,shell]
+----
+circleci runner instance list <namespace/resource-class> [flags]
+----
+
+- `<namespace>` is the namespace claimed for your organization. You can see your namespace on the self-hosted runners inventory page in the CircleCI web app, by selecting **Self-Hosted Runners** in the sidebar.
+
+- `<resource-class>` is the label for the resource class of the specific pool of self-hosted runners. You can find the resource class for all your pools in the link:https://app.circleci.com[CircleCI web app], by selecting **Self-Hosted Runners** in the sidebar.
+
+To find out more on namespace and resource class, see the xref:execution-runner:runner-concepts.adoc#namespaces-and-resource-classes[Self-hosted runner concepts] page.
+
+For full details on the `instance list` sub-command, refer to the link:https://circleci-public.github.io/circleci-cli/circleci_runner_instance_list.html[CLI docs].
+
+=== Create a resource class
+
+Use the `resource-class create` sub-command to add a new resource class.
+
+[,shell]
+----
+circleci runner instance create <namespace/resource-class> <description> [flags]
+----
+
+- `<namespace>` is the namespace claimed for your organization. You can see your namespace on the self-hosted runners inventory page in the CircleCI web app, by selecting **Self-Hosted Runners** in the sidebar.
+
+- `<resource-class>` is the label for the resource class of the specific pool of self-hosted runners. You can find the resource class for all your pools in the link:https://app.circleci.com[CircleCI web app], by selecting **Self-Hosted Runners** in the sidebar.
+
+- `<description>` is the argument that allows you to provide a description for the resource class. It must be enclosed in double-quotes.
+
+For full details on the `resource-class create` sub-command, refer to the link:https://circleci-public.github.io/circleci-cli/circleci_runner_resource-class_create.html[CLI docs].
+
+=== Delete a resource class
+
+Use the `resource-class delete` sub-command to delete an existing resource class.
+
+[,shell]
+----
+circleci runner resource-class delete <namespace/resource-class> [flags]
+----
+
+- `<namespace>` is the namespace claimed for your organization. You can see your namespace on the self-hosted runners inventory page in the CircleCI web app, by selecting **Self-Hosted Runners** in the sidebar.
+
+- `<resource-class>` is the label for the resource class of the specific pool of self-hosted runners. You can find the resource class for all your pools in the link:https://app.circleci.com[CircleCI web app], by selecting **Self-Hosted Runners** in the sidebar.
+
+For full details on the `resource-class delete` sub-command, refer to the link:https://circleci-public.github.io/circleci-cli/circleci_runner_resource-class_delete.html[CLI docs].
+
+=== List resource classes
+
+Use the `resource-class list` sub-command to list all resource classes for your namespace.
+
+[,shell]
+----
+circleci runner resource-class list <namespace> [flags]
+----
+
+Alternatively, you can use the shorthand `ls`, instead of `list`.
+
+
+- `<namespace>` is the namespace claimed for your organization. You can see your namespace on the self-hosted runners inventory page in the CircleCI web app, by selecting **Self-Hosted Runners** in the sidebar.
+
+For full details on the `resource-class list` sub-command, refer to the link:https://circleci-public.github.io/circleci-cli/circleci_runner_resource-class_list.html[CLI docs].
+
+=== Create a token for a resource class
+
+Use the `token create` sub-command to create a token for a resource class.
+
+[,shell]
+----
+circleci runner token create <namespace/resource-class> <nickname> [flags]
+----
+
+- `<namespace>` is the namespace claimed for your organization. You can see your namespace on the self-hosted runners inventory page in the CircleCI web app, by selecting **Self-Hosted Runners** in the sidebar.
+
+- `<resource-class>` is the name of the resource class for the specific pool of self-hosted runners. You can find the resource class for all your pools in the link:https://app.circleci.com[CircleCI web app], by selecting **Self-Hosted Runners** in the sidebar.
+
+- `<nickname>` refers to a human-readable name you assign to the token.
+
+For full details on the `resource-class token create` sub-command, refer to the link:https://circleci-public.github.io/circleci-cli/circleci_runner_token_create.html[CLI docs].
+  
+
+=== List tokens for a resource class
+
+Use the `token list` sub-command to list all tokens for a resource class.
+
+[,shell]
+----
+circleci runner token list <namespace/resource-class> [flags]
+----
+
+Alternatively, you can use the shorthand `ls`, instead of `list`.
+
+- `<namespace>` is the namespace claimed for your organization. You can see your namespace on the self-hosted runners inventory page in the CircleCI web app, by selecting **Self-Hosted Runners** in the sidebar.
+
+- `<resource-class>` is the name of the resource class for the specific pool of self-hosted runners. You can find the resource class for all your pools in the link:https://app.circleci.com[CircleCI web app], by selecting **Self-Hosted Runners** in the sidebar.
+
+For full details on the `token list` sub-command, refer to the link:https://circleci-public.github.io/circleci-cli/circleci_runner_token_list.html[CLI docs].
+
+=== Delete a token
+
+Use the `token delete` sub-command to delete a token for a resource class.
+
+[,shell]
+----
+circleci runner token delete <token-id> [flags]
+----
+
+- `<token-id>` is the ID of the token to delete. You can find the token ID by running the `token list` sub-command, described above.
+
+For full details on the `token delete` sub-command, refer to the link:https://circleci-public.github.io/circleci-cli/circleci_runner_token_delete.html[CLI docs].
+
+
 [#project-management]
 == Project management