Add resource class naming conventions to machine provisioner guide (#10504)

* Add resource class naming conventions to machine provisioner guide

- Document regex requirements for namespace (lowercase, numbers, underscore, dash)
- Document regex requirements for class portion (alphanumeric, colon, underscore, dash, plus)
- Include examples of valid resource class names
- Resolves DOC-34

Co-authored-by: Rosie Yohannan <rosieyohannan@users.noreply.github.com>

* Add resource class naming conventions to runner setup docs

- Document naming requirements in web app installation steps
- Document naming requirements in CLI installation steps
- Include practical examples in CLI steps
- Namespace: lowercase letters, numbers, underscores, dashes
- Resource class: alphanumeric, colons, underscores, dashes, plus signs

Resolves DOC-34

Co-authored-by: Rosie Yohannan <rosieyohannan@users.noreply.github.com>

* remove guidance misplaced in machine provisioner docs and add to runner provisioner docs

* style fixes

* remove confusing references to provisioner docs

* add in creating namespace and resource class as first step

* refine runner setup partials

* improve consistency

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Rosie Yohannan <rosieyohannan@users.noreply.github.com>

Author: rosieyohannan

docs/guides/modules/ROOT/partials/runner/install-with-cli-steps.adoc

@@ -5,32 +5,29 @@ ifdef::machine[]
 NOTE: If you are installing **self-hosted runners for server**, the CircleCI CLI needs to be configured using your server API key. Run `circleci setup` to configure the CLI and access the option to supply a new API token if required.
 endif::[]
 
-In order to install self-hosted runners, you will need to create a namespace and authentication token by performing the steps listed below.
+To install self-hosted runners, you need to create a CircleCI namespace and resource class. Once set up you will receive a resource class token. You must be an organization admin to complete this process. View your installed runners on the inventory page in the link:https://app.circleci.com/[web app] by selecting *Runners* from the sidebar.
 
-NOTE: To create resource classes and tokens you need to be an organization administrator in the VCS provider.
+TIP: If you already create orb in your organization you will already have a namespace configured. You must use this same namespace for runners. Each organization can only create a single namespace.
 
-You can view your installed runners on the inventory page in the link:https://app.circleci.com/[web app] or your CircleCI server app, by selecting *Runners* from the sidebar.
-
-. Create a namespace for your organization's self-hosted runners. *Each organization can only create a single namespace*. We suggest using a lowercase representation of your CircleCI organization's account name. If you already use orbs, this namespace should be the same namespace orbs use.
-+
-Use the following command to create a namespace:
+. Create a namespace for your organization's self-hosted runners if you do not already have one configured. We suggest using a lowercase representation of your CircleCI organization's account name.
 +
-```
-circleci namespace create <name> --org-id <your-organization-id>
-```
+Use the following command to create your CircleCI organization's namespace:
 +
-TIP: If your organization already has a namespace, you will receive an error if you run the above command to create a _different_ namespace. The error message returns the name of the existing namespace. In this case, move on to step 2 below, using your existing namespace.
+[source,console]
+$ circleci namespace create <name> --org-id <your-organization-id>
 
-. Create a resource class for your self-hosted runner's namespace using the following command:
+. Create a resource class for your runner using the following command. You will configure jobs to use this resource class when you want them to run on your slef-hosted runner:
++
+[source,console]
+$ circleci runner resource-class create <namespace>/<resource-class> <description> --generate-token
 +
-```
-circleci runner resource-class create <namespace>/<resource-class> <description> --generate-token
-```
+Make sure to replace `<namespace>` and `<resource-class>` with your org namespace and desired resource class name, respectively. You can add a description but this is optional.
 +
-Make sure to replace `<namespace>` and `<resource-class>` with your org namespace and desired resource class name, respectively. You may optionally add a description.
+Resource class names must follow specific naming conventions.
 +
-Example: `circleci runner resource-class create my-namespace/my-resource-class my-description --generate-token`.
+** The *namespace* can contain lowercase letters, numbers, underscores, and dashes.
+** The *resource class name* can contain uppercase and lowercase letters, numbers, colons, underscores, dashes, and plus signs.
 +
 The resource class token is returned after the runner resource class is successfully created.
 +
-CAUTION: The token cannot be retrieved again, so be sure to store it safely.
+CAUTION: The token is only displayed once, so be sure to store it safely.

docs/guides/modules/ROOT/partials/runner/install-with-web-app-steps.adoc

@@ -1,22 +1,32 @@
 //== CircleCI web app installation: pre-steps
-In order to install self-hosted runners, you will need to create a namespace and resource class token. To create resource classes and tokens, you need to be an organization admin in the VCS provider. You can read about namespaces and resource classes on the <<runner-concepts#namespaces-and-resource-classes,Concepts>> page.
+To install self-hosted runners, you need to create a CircleCI namespace and resource class. Once set up you will receive a resource class token. You must be an organization admin to complete this process. View your installed runners on the inventory page in the link:https://app.circleci.com/[web app] by selecting *Runners* from the sidebar.
 
-You can view your installed runners on the inventory page, by selecting *Runners* from the sidebar.
+TIP: If you already create orb in your organization you will already have a namespace configured. You must use this same namespace for runners. Each organization can only create a single namespace.
 
 . On the https://app.circleci.com/[CircleCI web app], navigate to *Runners* and select btn:[Create Resource Class].
 +
+.Runner set up, step one - Get started
 image::guides:ROOT:runner/runner-ui-step-one.png[Runner set up, step one - Get started]
 
-. Next, you will create a custom xref:guides:execution-managed:resource-class-overview.adoc[resource class] to use when configuring jobs to use your self-hosted runners. If this is your organization's first time using self-hosted runners, you will need to create or enter a namespace. If your organization already creates orbs, do not create a new namespace, but instead enter the namespace your organization uses for orbs here too. Enter a name for your self-hosted runner resource class.
+. Create a custom xref:guides:execution-managed:resource-class-overview.adoc[Resource Class]. You will configure jobs to use this resource class when you want them to run on your self-hosted runner.
 +
-TIP: *Each organization can only create a single namespace*. While not required, we suggest using a lowercase representation of your CircleCI account name. CircleCI will populate your org name as the suggested namespace by default in the UI.
+We suggest using a lowercase representation of your CircleCI account name for your namespace. CircleCI will populate your org name as the suggested namespace by default in the UI.
 +
+Namespace and resource classes must follow specific naming conventions:
++
+** The *namespace* can contain lowercase letters, numbers, underscores, and dashes.
+** The *resource class name* can contain uppercase and lowercase letters, numbers, colons, underscores, dashes, and plus signs.
++
+.Runner set up, step two - Create a namespace and resource class
 image::guides:ROOT:runner/runner-ui-step-two.png[Runner set up, step two - Create a namespace and resource class]
 
+. Enter a description for your resource class. This is an optional field.
+. Select btn:[Save and continue] to save and view your resource class token.
 . Copy and save the resource class token. Self-hosted runners use this token to claim work for the associated resource class.
 +
-CAUTION: The token cannot be retrieved again, be sure to store it safely.
+CAUTION: The token is only displayed once, be sure to store it safely.
 +
+.Runner set up, step three - Create a resource class token
 image::guides:ROOT:runner/runner-ui-step-three.png[Runner set up, step three - Create a resource class token]
 
 ifdef::container[]
@@ -32,3 +42,9 @@ ifdef::machine[]
 . Select the **Machine** tab and progress on to the platform-specific instructions in the next section of this installation guide.
 +
 endif::[]
+
+ifdef::provisioner[]
++
+. Select btn:[Continue] to complete the setup.
++
+endif::[]

docs/guides/modules/execution-runner/pages/runner-provisioner.adoc

@@ -38,11 +38,12 @@ Do not open a support ticket for issues with Runner Provisioner. Issues are rout
 * A Kubernetes cluster with KubeVirt installed. Refer to the link:https://github.com/kubevirt/kubevirt/blob/main/docs/compatibility.md[KubeVirt compatibility matrix] for the appropriate version for your cluster. Runner Provisioner has been tested with v1.8.
 * `kubectl` configured against your cluster.
 * `helm` v3+.
-* A CircleCI runner resource class and its associated resource class token. Create one in the CircleCI web app under **Self-Hosted Runners**. This token is used by the agent running on the VM to authenticate with CircleCI and claim and execute jobs for that resource class.
-* A CircleCI API token with permission to query runner tasks. This may be a personal API token or a project API token with read-only access.
+* A CircleCI API token with permission to query runner tasks. This may be a personal API token or a project API token with read-only access. See the xref:toolkit:managing-api-tokens.adoc[Managing API Tokens] page for more information.
 
 === Cluster requirements
 
+The following sections cover the cluster requirements for running Runner Provisioner on a Kubernetes cluster.
+
 ==== Nested virtualization
 
 KubeVirt runs VMs inside Kubernetes pods. Each node that will host runner VMs must expose `/dev/kvm` — the node itself must support hardware-accelerated virtualization (either bare metal, or a cloud VM with nested virtualization enabled).
@@ -256,8 +257,24 @@ $ kubectl label nodes -l agentpool=<nodepool-name> node-role.kubernetes.io/contr
 
 == Quickstart
 
+=== 1. Create CircleCI namespace and resource class
+
+[tabs]
+====
+Web app installation::
++
+--
+include::ROOT:partial$runner/install-with-web-app-steps.adoc[]
+--
+CLI installation::
++
+--
+include::ROOT:partial$runner/install-with-cli-steps.adoc[]
+--
+====
+
 [#create-namespace]
-=== 1. Create the namespace
+=== 3. Create the Kubernetes namespace
 
 [source,console]
 ----
@@ -310,7 +327,7 @@ provisioner:
 The image `quay.io/containerdisks/ubuntu:22.04` is an official container disk maintained by the KubeVirt project, providing a pre-built Ubuntu 22.04 OS image for running virtual machines on Kubernetes.
 
 [#install-helm-chart]
-=== 3. Install the Helm chart
+=== 4. Install the Helm chart
 
 [source,console]
 ----
@@ -322,7 +339,7 @@ $ helm install runner-provisioner circleci_runner-provisioner \
 ----
 
 [#verify-deployment]
-=== 4. Verify the deployment
+=== 5. Verify the deployment
 
 [source,console]
 ----
@@ -445,7 +462,7 @@ When enabled, the provisioner attaches a containerDisk that ships the `circleci-
 
 | `namespace`
 | `runner-provisioner`
-| Namespace where runner VMs are created
+| Namespace where runner VMs are created.
 
 | `circleToken`
 | `""`
@@ -470,7 +487,8 @@ When enabled, the provisioner attaches a containerDisk that ships the `circleci-
 
 | `name`
 | `""`
-| Resource class in `namespace/name` format (required)
+| Resource class in `namespace/name` format (required). The namespace can contain lowercase letters, numbers, underscores, and dashes. The resource class name can contain uppercase and lowercase letters, numbers, colons, underscores, dashes, and plus signs.
+Valid examples: `my-org/medium`, `acme_corp/large-gpu`, `dev-team/custom:arm64`.
 
 | `token`
 | `""`