Expand Test Kitchen driver docs and improve SEO (CHEF-37533)

config/_default/menu.toml

@@ -1299,6 +1299,12 @@ weight = 70
   parent = "workstation_25/tools"
   weight = 20
 
+    [[workstation_25]]
+    title = "Drivers"
+    identifier = "workstation_25/tools/test_kitchen/drivers"
+    parent = "workstation_25/tools/test_kitchen"
+    weight = 50
+
 ####
 # End Chef Workstation 25 Menu
 ####
@@ -1343,6 +1349,12 @@ weight = 80
   parent = "workstation_26_0/tools"
   weight = 200
 
+    [[workstation_26_0]]
+    title = "Drivers"
+    identifier = "workstation_26_0/tools/test_kitchen/drivers"
+    parent = "workstation_26_0/tools/test_kitchen"
+    weight = 50
+
 ####
 # End Chef Workstation 26.0 Menu
 ####
@@ -1387,6 +1399,12 @@ weight = 80
   parent = "workstation_26_1/tools"
   weight = 200
 
+    [[workstation_26_1]]
+    title = "Drivers"
+    identifier = "workstation_26_1/tools/test_kitchen/drivers"
+    parent = "workstation_26_1/tools/test_kitchen"
+    weight = 50
+
 ####
 # End Chef Workstation 26.1 Menu
 ####

content/workstation/25/reusable/md/test_kitchen_drivers.md

@@ -1,30 +1,52 @@
-Test Kitchen uses a driver plugin architecture to enable Test Kitchen to
-test instances on cloud providers such as Amazon EC2, Google Compute
-Engine, and Microsoft Azure. You can also test on multiple local
-hypervisors, such as VMware, Hyper-V, or VirtualBox.
+A Test Kitchen _driver_ configures the compute instance that Test Kitchen uses for isolated cookbook testing.
+A driver targets a local hypervisor, a hypervisor abstraction layer such as Vagrant, or a cloud service such as Amazon EC2.
 
 {{< note >}}
 
 Chef Workstation includes many common Test Kitchen drivers.
 
 {{< /note >}}
 
-Most drivers have driver-specific configuration settings that must be
-added to the `kitchen.yml` file before Test Kitchen will be able to use
-that platform during cookbook testing. For information about these
-driver-specific settings, please refer to the driver-specific
-documentation.
-
-Some popular drivers:
-
-- **[kitchen-azurerm](https://github.com/test-kitchen/kitchen-azurerm)**: A driver for Microsoft Azure.
-- **[kitchen-cloudstack](https://github.com/test-kitchen/kitchen-cloudstack)**: A driver for CloudStack.
-- **[kitchen-digitalocean](https://github.com/test-kitchen/kitchen-digitalocean)**: A driver for DigitalOcean. This driver ships in Chef Workstation.
-- **[kitchen-dokken](https://github.com/test-kitchen/kitchen-dokken)**: A driver for Docker. This driver ships in Chef Workstation.
-- **[kitchen-dsc](https://github.com/test-kitchen/kitchen-dsc)**: A driver for Windows PowerShell Desired State Configuration (DSC).
-- **[kitchen-ec2](https://github.com/test-kitchen/kitchen-ec2)**: A driver for Amazon EC2. This driver ships in Chef Workstation.
-- **[kitchen-google](https://github.com/test-kitchen/kitchen-google)**: A driver for Google Compute Engine. This driver ships in Chef Workstation
-- **[kitchen-hyperv](https://github.com/test-kitchen/kitchen-hyperv)**: A driver for Microsoft Hyper-V Server. This driver ships in Chef Workstation.
-- **[kitchen-openstack](https://github.com/test-kitchen/kitchen-openstack)**: A driver for OpenStack. This driver ships in Chef Workstation.
-- **[kitchen-rackspace](https://github.com/test-kitchen/kitchen-rackspace)**: A driver for Rackspace.
-- **[kitchen-vagrant](https://github.com/test-kitchen/kitchen-vagrant)**: A driver for HashiCorp Vagrant. This driver ships in Chef Workstation.
+Most drivers have driver-specific settings that you add to the `kitchen.yml` file before Test Kitchen can use that platform.
+Driver availability depends on the Ruby environment that runs `kitchen`.
+To confirm that a driver is available, list its gem before you rely on it:
+
+```shell
+# System Ruby
+gem list kitchen-vagrant
+
+# Chef Workstation
+chef gem list kitchen-vagrant
+```
+
+If a driver isn't installed, add its gem to that same environment.
+
+## Supported drivers
+
+The following drivers have dedicated configuration pages:
+
+- **[kitchen-azurerm](/workstation/25/tools/kitchen/drivers/azurerm/)**: Provisions virtual machines on Microsoft Azure.
+- **[kitchen-digitalocean](/workstation/25/tools/kitchen/drivers/digitalocean/)**: Provisions droplets on DigitalOcean. This driver ships with Chef Workstation.
+- **[kitchen-dokken](/workstation/25/tools/kitchen/drivers/dokken/)**: Runs fast cookbook tests using Docker. This driver ships with Chef Workstation.
+- **[kitchen-ec2](/workstation/25/tools/kitchen/drivers/ec2/)**: Provisions instances on Amazon EC2. This driver ships with Chef Workstation.
+- **[kitchen-google](/workstation/25/tools/kitchen/drivers/google/)**: Provisions instances on Google Compute Engine. This driver ships with Chef Workstation.
+- **[kitchen-hyperv](/workstation/25/tools/kitchen/drivers/hyperv/)**: Provisions virtual machines on Microsoft Hyper-V. This driver ships with Chef Workstation.
+- **[kitchen-openstack](/workstation/25/tools/kitchen/drivers/openstack/)**: Provisions instances on OpenStack. This driver ships with Chef Workstation.
+- **[kitchen-vagrant](/workstation/25/tools/kitchen/drivers/vagrant/)**: Provisions local virtual machines with HashiCorp Vagrant. This driver ships with Chef Workstation.
+- **[kitchen-vcenter](/workstation/25/tools/kitchen/drivers/vcenter/)**: Provisions virtual machines on VMware vCenter.
+- **[kitchen-vra](/workstation/25/tools/kitchen/drivers/vra/)**: Provisions machines through VMware vRealize Automation.
+
+## Additional drivers
+
+The following drivers are also available. For configuration details, see each driver's repository:
+
+- **[kitchen-cloudstack](https://github.com/test-kitchen/kitchen-cloudstack)**: Apache CloudStack.
+- **[kitchen-docker](https://github.com/test-kitchen/kitchen-docker)**: Docker containers.
+- **[kitchen-dsc](https://github.com/test-kitchen/kitchen-dsc)**: Windows PowerShell Desired State Configuration (DSC).
+- **[kitchen-habitat](https://github.com/test-kitchen/kitchen-habitat)**: Chef Habitat packages.
+- **[kitchen-opennebula](https://github.com/test-kitchen/kitchen-opennebula)**: OpenNebula.
+- **[kitchen-rackspace](https://github.com/test-kitchen/kitchen-rackspace)**: Rackspace Cloud.
+- **[kitchen-vcair](https://github.com/test-kitchen/kitchen-vcair)**: VMware vCloud Air.
+- **[kitchen-vro](https://github.com/test-kitchen/kitchen-vro)**: VMware vRealize Orchestrator.
+
+For the full list of maintained drivers, see the [Test Kitchen drivers reference](https://kitchen.ci/docs/drivers/).

content/workstation/25/tools/kitchen/_index.md

@@ -1,5 +1,7 @@
 +++
 title = "Test Kitchen"
+description = "Test Kitchen tests Chef Infra cookbooks across platforms, cloud providers, and virtualization drivers using a driver plugin architecture."
+summary = "Test Chef Infra cookbooks across platforms and cloud providers with Test Kitchen and its supported drivers."
 draft = false
 
 
@@ -51,7 +53,8 @@ For more information, see the [Chef licensing documentation](/licensing/).
 
 ## Drivers
 
-{{< readfile file="content/workstation/25/reusable/md/test_kitchen_drivers.md" >}}
+Test Kitchen uses a driver plugin architecture to test instances on cloud providers and local hypervisors.
+For the list of supported drivers and their configuration, see the [Test Kitchen drivers](/workstation/25/tools/kitchen/drivers/) documentation.
 
 ## Validation with Chef InSpec
 

content/workstation/25/tools/kitchen/config_yml_kitchen.md

@@ -1,5 +1,7 @@
 +++
 title = "kitchen.yml"
+description = "Configure the kitchen.yml file to set Test Kitchen drivers, provisioners, platforms, and suites for testing Chef Infra cookbooks."
+summary = "Reference for kitchen.yml configuration, including Test Kitchen driver and provisioner settings."
 draft = false
 
 
@@ -355,15 +357,8 @@ Specific `optional_settings: values` may be specified.
 
 ### Drivers
 
-{{< readfile file="content/workstation/25/reusable/md/test_kitchen_drivers.md" >}}
-
-### kitchen-vagrant
-
-{{< readfile file="content/workstation/25/reusable/md/test_kitchen_driver_vagrant.md" >}}
-
-{{< readfile file="content/workstation/25/reusable/md/test_kitchen_driver_vagrant_settings.md" >}}
-
-{{< readfile file="content/workstation/25/reusable/md/test_kitchen_driver_vagrant_config.md" >}}
+Test Kitchen uses a driver plugin architecture to test instances on cloud providers and local hypervisors.
+For the list of supported drivers and their configuration, see the [Test Kitchen drivers](/workstation/25/tools/kitchen/drivers/) documentation.
 
 ## Examples
 

content/workstation/25/tools/kitchen/ctl_kitchen.md

@@ -1,5 +1,7 @@
 +++
 title = "kitchen executable"
+description = "Reference for the kitchen command-line executable used to create, converge, verify, and destroy Test Kitchen instances."
+summary = "kitchen command-line executable reference for Test Kitchen."
 draft = false
 
 

content/workstation/25/tools/kitchen/drivers/_index.md

@@ -0,0 +1,14 @@
++++
+title = "Test Kitchen drivers"
+description = "Test Kitchen drivers provision the compute instances used to test Chef Infra cookbooks on cloud providers and local hypervisors."
+summary = "Overview of supported Test Kitchen drivers and where to configure each one."
+
+[menu]
+  [menu.workstation_25]
+    title = "About drivers"
+    identifier = "workstation_25/tools/test_kitchen/drivers/_index"
+    parent = "workstation_25/tools/test_kitchen/drivers"
+    weight = 10
++++
+
+{{< readfile file="content/workstation/25/reusable/md/test_kitchen_drivers.md" >}}

content/workstation/25/tools/kitchen/drivers/azurerm.md

@@ -0,0 +1,42 @@
++++
+title = "kitchen-azurerm"
+description = "Configure the kitchen-azurerm Test Kitchen driver (Microsoft Azure) to test Chef Infra cookbooks."
+
+[menu]
+  [menu.workstation_25]
+    title = "kitchen-azurerm"
+    identifier = "workstation_25/tools/test_kitchen/drivers/azurerm"
+    parent = "workstation_25/tools/test_kitchen/drivers"
+    weight = 20
++++
+
+The `kitchen-azurerm` driver provisions virtual machines on Microsoft Azure using the Azure Resource Manager API. Authenticate with the Azure CLI or a service principal, then set your subscription and location in the driver configuration.
+
+## Example kitchen.yml
+
+The following example sets `azurerm` as the driver in a `kitchen.yml` file:
+
+```yaml
+driver:
+  name: azurerm
+  subscription_id: <azure-subscription-id>
+  location: eastus
+  machine_size: Standard_D2s_v3
+
+platforms:
+  - name: ubuntu-2204
+    driver:
+      image_urn: Canonical:0001-com-ubuntu-server-jammy:22_04-lts-gen2:latest
+```
+
+## Configuration
+
+The `kitchen-azurerm` driver provides configuration options that you set in the `driver` section of your `kitchen.yml` file, either globally or for an individual platform.
+For the complete and current list of settings, see the [`kitchen-azurerm` repository](https://github.com/test-kitchen/kitchen-azurerm).
+
+{{< note >}}
+
+The upstream driver documentation can lag behind the driver code.
+Verify the configuration options against the version of `kitchen-azurerm` installed in your Test Kitchen environment.
+
+{{< /note >}}

content/workstation/25/tools/kitchen/drivers/digitalocean.md

@@ -0,0 +1,38 @@
++++
+title = "kitchen-digitalocean"
+description = "Configure the kitchen-digitalocean Test Kitchen driver (DigitalOcean) to test Chef Infra cookbooks."
+
+[menu]
+  [menu.workstation_25]
+    title = "kitchen-digitalocean"
+    identifier = "workstation_25/tools/test_kitchen/drivers/digitalocean"
+    parent = "workstation_25/tools/test_kitchen/drivers"
+    weight = 30
++++
+
+The `kitchen-digitalocean` driver provisions droplets on DigitalOcean. This driver ships with Chef Workstation. Set the `DIGITALOCEAN_ACCESS_TOKEN` and `DIGITALOCEAN_SSH_KEY_IDS` environment variables to authenticate.
+
+## Example kitchen.yml
+
+The following example sets `digitalocean` as the driver in a `kitchen.yml` file:
+
+```yaml
+driver:
+  name: digitalocean
+
+platforms:
+  - name: ubuntu-22-04
+  - name: rockylinux-9
+```
+
+## Configuration
+
+The `kitchen-digitalocean` driver provides configuration options that you set in the `driver` section of your `kitchen.yml` file, either globally or for an individual platform.
+For the complete and current list of settings, see the [`kitchen-digitalocean` repository](https://github.com/test-kitchen/kitchen-digitalocean).
+
+{{< note >}}
+
+The upstream driver documentation can lag behind the driver code.
+Verify the configuration options against the version of `kitchen-digitalocean` installed in your Test Kitchen environment.
+
+{{< /note >}}

content/workstation/25/tools/kitchen/drivers/dokken.md

@@ -0,0 +1,46 @@
++++
+title = "kitchen-dokken"
+description = "Configure the kitchen-dokken Test Kitchen driver (Docker (Dokken)) to test Chef Infra cookbooks."
+
+[menu]
+  [menu.workstation_25]
+    title = "kitchen-dokken"
+    identifier = "workstation_25/tools/test_kitchen/drivers/dokken"
+    parent = "workstation_25/tools/test_kitchen/drivers"
+    weight = 40
++++
+
+The `kitchen-dokken` driver uses Docker with prebuilt Linux and Chef Infra Client images to run fast cookbook tests. This driver ships with Chef Workstation. It combines the driver, transport, and provisioner into a single plugin, so set `dokken` in all three sections of your `kitchen.yml` file.
+
+## Example kitchen.yml
+
+The following example sets `dokken` as the driver in a `kitchen.yml` file:
+
+```yaml
+driver:
+  name: dokken
+  privileged: true
+
+provisioner:
+  name: dokken
+
+transport:
+  name: dokken
+
+platforms:
+  - name: ubuntu-22.04
+    driver:
+      image: dokken/ubuntu-22.04
+```
+
+## Configuration
+
+The `kitchen-dokken` driver provides configuration options that you set in the `driver` section of your `kitchen.yml` file, either globally or for an individual platform.
+For the complete and current list of settings, see the [`kitchen-dokken` repository](https://github.com/test-kitchen/kitchen-dokken).
+
+{{< note >}}
+
+The upstream driver documentation can lag behind the driver code.
+Verify the configuration options against the version of `kitchen-dokken` installed in your Test Kitchen environment.
+
+{{< /note >}}

content/workstation/25/tools/kitchen/drivers/ec2.md

@@ -0,0 +1,39 @@
++++
+title = "kitchen-ec2"
+description = "Configure the kitchen-ec2 Test Kitchen driver (Amazon EC2) to test Chef Infra cookbooks."
+
+[menu]
+  [menu.workstation_25]
+    title = "kitchen-ec2"
+    identifier = "workstation_25/tools/test_kitchen/drivers/ec2"
+    parent = "workstation_25/tools/test_kitchen/drivers"
+    weight = 50
++++
+
+The `kitchen-ec2` driver provisions instances on Amazon Elastic Compute Cloud (EC2). This driver ships with Chef Workstation. Provide AWS credentials through the standard AWS SDK credential chain---environment variables, shared credential files, or an IAM instance profile---rather than storing them in the `kitchen.yml` file.
+
+## Example kitchen.yml
+
+The following example sets `ec2` as the driver in a `kitchen.yml` file:
+
+```yaml
+driver:
+  name: ec2
+  region: us-east-1
+  instance_type: t3.medium
+
+platforms:
+  - name: ubuntu-22.04
+```
+
+## Configuration
+
+The `kitchen-ec2` driver provides configuration options that you set in the `driver` section of your `kitchen.yml` file, either globally or for an individual platform.
+For the complete and current list of settings, see the [`kitchen-ec2` repository](https://github.com/test-kitchen/kitchen-ec2).
+
+{{< note >}}
+
+The upstream driver documentation can lag behind the driver code.
+Verify the configuration options against the version of `kitchen-ec2` installed in your Test Kitchen environment.
+
+{{< /note >}}

content/workstation/25/tools/kitchen/drivers/google.md

@@ -0,0 +1,42 @@
++++
+title = "kitchen-google"
+description = "Configure the kitchen-google Test Kitchen driver (Google Compute Engine) to test Chef Infra cookbooks."
+
+[menu]
+  [menu.workstation_25]
+    title = "kitchen-google"
+    identifier = "workstation_25/tools/test_kitchen/drivers/google"
+    parent = "workstation_25/tools/test_kitchen/drivers"
+    weight = 60
++++
+
+The `kitchen-google` driver provisions instances on Google Compute Engine (GCE). This driver ships with Chef Workstation. Authenticate with the Google Cloud SDK application default credentials, then set the project and zone in the driver configuration. The driver name in `kitchen.yml` is `gce`.
+
+## Example kitchen.yml
+
+The following example sets `gce` as the driver in a `kitchen.yml` file:
+
+```yaml
+driver:
+  name: gce
+  project: <gcp-project-id>
+  zone: us-central1-a
+
+platforms:
+  - name: ubuntu-2204
+    driver:
+      image_project: ubuntu-os-cloud
+      image_family: ubuntu-2204-lts
+```
+
+## Configuration
+
+The `kitchen-google` driver provides configuration options that you set in the `driver` section of your `kitchen.yml` file, either globally or for an individual platform.
+For the complete and current list of settings, see the [`kitchen-google` repository](https://github.com/test-kitchen/kitchen-google).
+
+{{< note >}}
+
+The upstream driver documentation can lag behind the driver code.
+Verify the configuration options against the version of `kitchen-google` installed in your Test Kitchen environment.
+
+{{< /note >}}