kitchen-openstack 7.0.1 → 8.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1f6ada19a9cfed5b59243e8ce7692c0154af0c58d8f644f7767a5ae0c7250854
-  data.tar.gz: 4acb3ae040435e3cc9701e34f524bb4840760ff934d777632414a07709e52368
+  metadata.gz: 7e257b104097e32c3a10839a0b02a216db638aa1f6e122f587ec3b8a7329affc
+  data.tar.gz: d5f629ce9b2605d901e935423149717e40d16a5fdc24c26871f3b28ace3328e9
 SHA512:
-  metadata.gz: a87b14b12ce6f527b972b64aaf8c5a12b0e6fa4f6383fc9613462114bf44ce58623dfbb389d3a2f2b5858f957d6fe086de2750d8eeb502e94ec0252edf315a5a
-  data.tar.gz: 28abcfff62bfba75b479db29553a25e1ea4eaa3b53d7d247ac83741eb9a084191b1e369d713f86837479f07d7c024b4bca5da6e2deca4c512097709f86867c9b
+  metadata.gz: 849cc31b25a28c30d74b68a9955a1f0670a2fc93dac9920d95367ad91dc623a44cc0664afcae21ad9e377485964be9d510cc5aa95f9bfe19256dca2792f8fbb7
+  data.tar.gz: 96faf8a295e4deccfb72d203ccbe8ad8a2905f10f52b8cde76ab6969133c0d7e4d4ea6ee5ca3ee13f940d3177d1e248b9655d4bcb7a51c15441efe03cbc96588

data/README.md

@@ -1,121 +1,214 @@
-# Kitchen::OpenStack
+# kitchen-openstack
 
 ![Gem Version](https://img.shields.io/gem/v/kitchen-openstack.svg)
 ![CI](https://github.com/test-kitchen/kitchen-openstack/actions/workflows/lint.yml/badge.svg)
 
-A Test Kitchen Driver for OpenStack.
+A [Test Kitchen](https://kitchen.ci/) driver for OpenStack.
 
-This driver uses the fog gem to provision and destroy nova instances. Use an OpenStack cloud for your infrastructure testing!
+Test Kitchen builds a throwaway machine, converges your configuration code on
+it, runs your tests, and destroys it. This driver makes that throwaway machine
+a Nova instance in an OpenStack cloud, so you can test against the same
+platform you deploy to.
 
-Shamelessly copied from [Fletcher Nichol](https://github.com/fnichol)'s awesome work on an [EC2 driver](https://github.com/test-kitchen/kitchen-ec2), and [Adam Leff](https://github.com/adamleff)'s amazing work on an [VRO driver](https://github.com/chef-partners/kitchen-vro).
+Maintained by the [OSU Open Source Lab](https://osuosl.org/).
 
-## Status
+> This documentation uses [Cinc Workstation](https://cinc.sh/) and the `cinc`
+> commands throughout. Everything here works identically with Chef Workstation —
+> see [Using with Chef](#using-with-chef).
 
-This software project is actively maintained by the [OSU Open Source Lab](https://osuosl.org/).
+---
 
-## Requirements
+## Contents
+
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Authentication](#authentication)
+- [Configuration reference](#configuration-reference)
+- [Common setups](#common-setups)
+- [Troubleshooting](#troubleshooting)
+- [Using with Chef](#using-with-chef)
+- [Contributing](#contributing)
 
-There are **no** external system requirements for this driver. However you will need access to an OpenStack cloud.
+---
 
-## Installation and Setup
+## Requirements
 
-This plugin ships out of the box with Chef Workstation, which is the easiest way to make sure you always have the latest testing dependencies in a single package.
+- Ruby 3.1 or newer
+- Access to an OpenStack cloud, and credentials for it
+- An SSH keypair uploaded to that cloud (Nova calls this a "keypair"; you
+  reference it by name as `key_name`)
 
-[Download Chef Workstation](https://downloads.chef.io/tools/workstation) to get started
+There are no other system requirements. The driver talks to OpenStack over
+HTTPS using the [fog-openstack](https://github.com/fog/fog-openstack) library.
 
-### Manual Installation
+## Installation
 
-Add this line to your application's Gemfile:
+This driver ships with [Cinc
+Workstation](https://cinc.sh/start/workstation/), which is the simplest way to
+get Test Kitchen and its plugins in one package. It also ships with
+[Chef Workstation](https://www.chef.io/downloads/tools/workstation).
+
+To install it yourself, add it to your `Gemfile`:
 
 ```ruby
-gem 'kitchen-openstack'
+gem "kitchen-openstack"
 ```
 
-And then execute:
+then `bundle install`. Or install the gem directly:
 
 ```bash
-bundle
+gem install kitchen-openstack
 ```
 
-Or install it yourself as:
+Confirm Test Kitchen can see it:
 
 ```bash
-gem install kitchen-openstack
+cinc kitchen driver discover | grep openstack
 ```
 
-## Usage
+## Quick start
 
-See <https://kitchen.ci/docs/drivers/openstack/> for documentation.
+This walks from nothing to a running instance. It assumes you already have a
+project with a `kitchen.yml`.
 
-### Using `clouds.yaml`
+### 1. Get your credentials into your shell
 
-This driver supports OpenStack's standard
-[`clouds.yaml`](https://docs.openstack.org/python-openstackclient/latest/configuration/index.html)
-client configuration file. This allows you to use the same credentials and
-endpoint configuration that other OpenStack tools (like the `openstack` CLI)
-already use, instead of duplicating them in `kitchen.yml`.
+If you use the `openstack` CLI, you already have what you need. Most clouds
+give you an `openrc` file to source, or a `clouds.yaml` in
+`~/.config/openstack/`. Either works — this driver reads both, the same way
+the CLI does:
 
-The driver searches for `clouds.yaml` in the standard locations:
+```bash
+source openrc.sh          # sets OS_AUTH_URL, OS_USERNAME, OS_PASSWORD, ...
+# or
+export OS_CLOUD=mycloud   # selects an entry from your existing clouds.yaml
+```
 
-1. `OS_CLIENT_CONFIG_FILE` environment variable (if set)
-2. `clouds_yaml_path` driver config option (if set)
-3. Current directory (`./clouds.yaml`)
-4. `~/.config/openstack/clouds.yaml`
-5. `/etc/openstack/clouds.yaml`
+Check that it works before involving Test Kitchen:
 
-The first file found is used. A `secure.yaml` file in the same search
-locations is also loaded and merged, so you can split secrets out of
-`clouds.yaml` following the
-[standard convention](https://docs.openstack.org/openstacksdk/latest/user/config/configuration.html#splitting-secrets).
+```bash
+openstack server list
+```
 
-#### Selecting a cloud
+If that fails, fix it first. Test Kitchen will fail the same way, with less
+helpful output.
 
-Specify which cloud entry to use in one of two ways:
+### 2. Find an image and a flavor
 
-- Set `openstack_cloud` in `kitchen.yml` (takes precedence)
-- Set the `OS_CLOUD` environment variable
+You need to tell the driver what to boot and how big:
+
+```bash
+openstack image list
+openstack flavor list
+openstack keypair list
+```
 
-#### Example `kitchen.yml`
+### 3. Write your `kitchen.yml`
 
 ```yaml
+---
 driver:
   name: openstack
-  openstack_cloud: mycloud
-  image_ref: ubuntu-22.04
+  image_ref: ubuntu-24.04       # name, ID, or /regex/
   flavor_ref: m1.small
-  key_name: my-keypair
+  key_name: my-keypair          # a keypair already uploaded to OpenStack
+
+transport:
+  username: ubuntu              # the image's default login user
+  ssh_key: ~/.ssh/my-keypair    # the *private* half of key_name
+
+provisioner:
+  name: cinc_infra
+
+verifier:
+  name: inspec
+
+platforms:
+  - name: ubuntu-24.04
+
+suites:
+  - name: default
 ```
 
-Or, relying entirely on `OS_CLOUD`:
+Two things new users most often get wrong here:
+
+- **`username` and `ssh_key` go under `transport:`, not `driver:`.** The driver
+  creates the machine; the transport logs into it. They are separate.
+- **`key_name` is the name OpenStack knows; `ssh_key` is the private key file
+  on your disk.** They must be two halves of the same pair.
+
+### 4. Run it
 
 ```bash
-export OS_CLOUD=mycloud
+cinc kitchen create      # boot the instance
+cinc kitchen converge    # apply your configuration code
+cinc kitchen verify      # run your tests
+cinc kitchen destroy     # tear it down
+
+cinc kitchen test        # all four, from scratch
 ```
 
+`cinc kitchen list` shows the state of each suite. If something goes wrong, jump to
+[Troubleshooting](#troubleshooting).
+
+## Authentication
+
+You can supply credentials three ways. You do not need to pick one globally —
+they layer, and the precedence is fixed:
+
+1. **`kitchen.yml`** — anything set explicitly here always wins
+2. **`OS_*` environment variables** — override `clouds.yaml`
+3. **`clouds.yaml`** (merged with `secure.yaml`) — the base
+
+This is the order the upstream OpenStack SDK uses, so it should match what the
+`openstack` CLI does.
+
+### Using `clouds.yaml` (recommended)
+
+OpenStack's standard
+[`clouds.yaml`](https://docs.openstack.org/python-openstackclient/latest/configuration/index.html)
+keeps credentials in one place shared by every OpenStack tool. If you have one,
+use it — there is nothing to copy into `kitchen.yml`.
+
+The driver searches these locations and uses the first file it finds:
+
+1. `$OS_CLIENT_CONFIG_FILE`
+2. the `clouds_yaml_path` driver option
+3. `./clouds.yaml`
+4. `~/.config/openstack/clouds.yaml`
+5. `/etc/openstack/clouds.yaml`
+
+A `secure.yaml` is searched for in the same locations — with
+`$OS_CLIENT_SECURE_FILE` in place of `$OS_CLIENT_CONFIG_FILE` — and merged on
+top, so you can keep secrets in a separate file following the [standard
+convention](https://docs.openstack.org/openstacksdk/latest/user/config/configuration.html#splitting-secrets).
+
+Select which cloud entry to use with either `OS_CLOUD` or the
+`openstack_cloud` driver option:
+
 ```yaml
 driver:
   name: openstack
-  image_ref: ubuntu-22.04
+  openstack_cloud: mycloud
+  image_ref: ubuntu-24.04
   flavor_ref: m1.small
   key_name: my-keypair
 ```
 
-Settings specified in `kitchen.yml` always take precedence over values from
-`clouds.yaml`. For example, you can override just the region:
+Because `kitchen.yml` wins, you can adopt a cloud entry and override one piece
+of it:
 
 ```yaml
 driver:
   name: openstack
   openstack_cloud: mycloud
-  openstack_region: RegionTwo
+  openstack_region: RegionTwo   # everything else still comes from clouds.yaml
 ```
 
-#### Using `OS_*` environment variables
+### Using `OS_*` environment variables
 
-The driver recognizes the standard OpenStack `OS_*` environment variables
-(e.g. from an `openrc` file). This means you can source your OpenStack
-credentials and use them directly without any extra configuration in
-`kitchen.yml`:
+Sourcing an `openrc` file is enough on its own:
 
 ```bash
 source openrc.sh
@@ -124,15 +217,16 @@ source openrc.sh
 ```yaml
 driver:
   name: openstack
-  image_ref: ubuntu-22.04
+  image_ref: ubuntu-24.04
   flavor_ref: m1.small
   key_name: my-keypair
 ```
 
-The supported environment variables are:
+Recognized variables:
 
-| Env var | Maps to |
-|---|---|
+| Environment variable | Driver option |
+| --- | --- |
+| `OS_CLOUD` | `openstack_cloud` |
 | `OS_AUTH_URL` | `openstack_auth_url` |
 | `OS_USERNAME` | `openstack_username` |
 | `OS_PASSWORD` | `openstack_api_key` |
@@ -151,38 +245,340 @@ The supported environment variables are:
 | `OS_APPLICATION_CREDENTIAL_SECRET` | `openstack_application_credential_secret` |
 | `OS_CACERT` | `ssl_ca_file` |
 
-#### Configuration precedence
+An exported-but-empty variable is ignored, so `OS_REGION_NAME=""` will not
+shadow a region set in `clouds.yaml`.
+
+### Putting credentials in `kitchen.yml`
+
+Supported, but avoid committing secrets. Prefer reading them from the
+environment:
+
+```yaml
+driver:
+  name: openstack
+  openstack_username: <%= ENV["OS_USERNAME"] %>
+  openstack_api_key: <%= ENV["OS_PASSWORD"] %>
+  openstack_auth_url: https://keystone.example.com:5000/v3
+  openstack_domain_id: default
+  openstack_project_name: my-project
+```
+
+### Application credentials
+
+Preferred over a password where your cloud supports them:
 
-The driver follows the upstream OpenStack SDK precedence order:
+```yaml
+driver:
+  name: openstack
+  openstack_auth_url: https://keystone.example.com:5000/v3
+  openstack_application_credential_id: <%= ENV["OS_APPLICATION_CREDENTIAL_ID"] %>
+  openstack_application_credential_secret: <%= ENV["OS_APPLICATION_CREDENTIAL_SECRET"] %>
+```
+
+## Configuration reference
 
-1. **`kitchen.yml`** — explicit driver config always wins
-2. **`OS_*` env vars** — override `clouds.yaml` values
-3. **`clouds.yaml`** (merged with `secure.yaml`) — base configuration
+Everything below goes under `driver:` in `kitchen.yml`.
 
-#### New driver config options
+### Choosing what to boot
 
 | Option | Default | Description |
-|---|---|---|
-| `openstack_cloud` | `nil` | Name of the cloud entry in `clouds.yaml`. Falls back to the `OS_CLOUD` env var. |
-| `clouds_yaml_path` | `nil` | Explicit path to a `clouds.yaml` file, inserted into the search path. |
+| --- | --- | --- |
+| `image_ref` | — | Image to boot, by name, ID, or `/regex/`. Mutually exclusive with `image_id`. |
+| `image_id` | — | Image UUID, used verbatim with no lookup. |
+| `flavor_ref` | — | Flavor, by name, ID, or `/regex/`. Mutually exclusive with `flavor_id`. |
+| `flavor_id` | — | Flavor UUID, used verbatim with no lookup. |
+| `key_name` | `nil` | Name of an SSH keypair already uploaded to OpenStack. |
+| `availability_zone` | `nil` | Availability zone to boot into. |
+| `security_groups` | `nil` | List of security group names. **Must be a list**, even for one group. |
+| `metadata` | `nil` | Hash of Nova instance metadata. |
+
+Set exactly one of `image_ref`/`image_id`, and exactly one of
+`flavor_ref`/`flavor_id`. Setting both members of a pair is an error.
+
+The `_ref` options accept three forms:
+
+```yaml
+image_ref: 8a8c0f4d-...        # exact ID (checked first)
+image_ref: ubuntu-24.04        # exact name
+image_ref: /^ubuntu-24\.04/    # regex, first match wins
+```
+
+### Naming the instance
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `server_name` | generated | Exact instance name. Overrides everything below. |
+| `server_name_prefix` | `nil` | Prefix, plus a random 8-character suffix. |
+
+With neither set, the name is `<suite-platform>-<user>-<host>-<random>`,
+truncated to OpenStack's 63-character limit. Non-word characters are stripped.
+
+### Networking
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `network_ref` | `nil` | Network(s) to attach, by name, ID, or `/regex/`. A string or a list. Mutually exclusive with `network_id`. |
+| `network_id` | `nil` | Network UUID(s), used verbatim. A string or a list. |
+| `openstack_network_name` | `nil` | Which network's address Test Kitchen should connect to. |
+| `floating_ip` | `nil` | A specific floating IP to attach. |
+| `floating_ip_pool` | `nil` | Pool (external network) to take a floating IP from. |
+| `allocate_floating_ip` | `false` | Allocate a *new* floating IP rather than reusing a free one. Released on `destroy`. |
+| `public_ip_order` | `0` | Index into the public addresses when several exist. |
+| `private_ip_order` | `0` | Index into the private addresses when several exist. |
+| `use_ipv6` | `false` | Connect over IPv6 instead of IPv4. |
+
+Address selection, in order: `floating_ip` if set, then
+`openstack_network_name` if set, then the public addresses at
+`public_ip_order`, then the private addresses at `private_ip_order`.
+
+### Storage
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `block_device_mapping` | `nil` | Boot from, or attach, a Cinder volume. See [below](#booting-from-a-volume). |
+
+### Instance customization
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `user_data` | `nil` | Path to a cloud-init file. **Must exist**, or `create` fails. |
+| `cloud_config` | `nil` | Inline cloud-config as YAML, rendered for you. Mutually exclusive with `user_data`. |
+| `config_drive` | `nil` | Attach a config drive. |
+
+### Connection and timeouts
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `connect_timeout` | `60` | Seconds to wait establishing an API connection. |
+| `read_timeout` | `60` | Seconds to wait reading an API response. |
+| `write_timeout` | `60` | Seconds to wait writing an API request. |
+| `glance_cache_wait_timeout` | `600` | Seconds to wait for the instance to reach `ACTIVE`. Raise it if your cloud caches images slowly on first boot. |
+| `server_wait` | `nil` | Extra seconds to sleep after boot before trying SSH. A blunt instrument; try it if your instances need a moment before accepting connections. |
+| `disable_ssl_validation` | `false` | Skip TLS verification. Prefer `ssl_ca_file`. |
+| `ssl_ca_file` | `nil` | Path to a CA bundle, passed to the HTTP connection. Set by `OS_CACERT` or a `cacert` entry in `clouds.yaml`. |
+
+### Credentials and endpoints
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `openstack_cloud` | `nil` | Cloud entry to read from `clouds.yaml`. Falls back to `OS_CLOUD`. |
+| `clouds_yaml_path` | `nil` | Explicit `clouds.yaml` path, inserted into the search path. |
+| `openstack_auth_url` | `nil` | Keystone endpoint. |
+| `openstack_username` | `nil` | Username. |
+| `openstack_api_key` | `nil` | Password. |
+| `openstack_project_name` | `nil` | Project (tenant) name. |
+| `openstack_project_id` | `nil` | Project ID. |
+| `openstack_domain_id` | `nil` | Domain ID. Usually `default`. |
+| `openstack_domain_name` | `nil` | Domain name. |
+| `openstack_user_domain` | `nil` | User domain name. |
+| `openstack_user_domain_id` | `nil` | User domain ID. |
+| `openstack_project_domain` | `nil` | Project domain name. |
+| `openstack_project_domain_id` | `nil` | Project domain ID. |
+| `openstack_region` | `nil` | Region name. |
+| `openstack_endpoint_type` | `nil` | Endpoint interface: `public`, `internal`, or `admin`. |
+| `openstack_identity_api_version` | `nil` | Keystone API version. |
+| `openstack_service_name` | `nil` | Compute service name. |
+| `openstack_application_credential_id` | `nil` | Application credential ID. |
+| `openstack_application_credential_secret` | `nil` | Application credential secret. |
+| `openstack_tenant` | `nil` | Tenant name. The Keystone v2 name for a project; use `openstack_project_name` on v3. |
+| `openstack_tenant_id` | `nil` | Tenant ID. The Keystone v2 name for a project ID. |
+| `openstack_service_type` | `nil` | Compute service type to look up in the catalog. |
+
+Any other `openstack_*` option that fog-openstack recognizes is forwarded as
+well, including `openstack_auth_token`, `openstack_identity_endpoint`,
+`openstack_management_url`, and `openstack_cache_ttl`. To see the full list
+your installed version supports:
+
+```bash
+ruby -r fog/openstack -e 'puts Fog::OpenStack::Compute.recognized.grep(/^openstack/).sort'
+```
+
+### Settings that are not driver options
+
+Commonly mistaken for driver options:
+
+- **`username`, `ssh_key`, `port`, `connection_timeout`** belong under
+  `transport:`. The driver builds the instance; the transport connects to it.
+- **`no_ssh_tcp_check` and `no_ssh_tcp_check_sleep`** are accepted but have no
+  effect. They are leftovers from an earlier version and are not read anywhere
+  in the driver.
+- **`pre_create_command`** is declared by Test Kitchen's base driver, but this
+  driver overrides `create` without invoking it, so setting it does nothing
+  here.
+
+## Common setups
+
+### Attaching a floating IP
+
+Reuse an already-allocated but unattached address from a pool:
+
+```yaml
+driver:
+  name: openstack
+  floating_ip_pool: public
+```
+
+Or allocate a fresh one, which is released again on `kitchen destroy`:
+
+```yaml
+driver:
+  name: openstack
+  floating_ip_pool: public
+  allocate_floating_ip: true
+```
+
+Or pin a specific address:
+
+```yaml
+driver:
+  name: openstack
+  floating_ip: 203.0.113.10
+```
+
+### Choosing a network
+
+```yaml
+driver:
+  name: openstack
+  network_ref: my-private-net           # name, ID, or /regex/
+```
+
+Attach several:
+
+```yaml
+driver:
+  name: openstack
+  network_ref:
+    - my-private-net
+    - my-storage-net
+  openstack_network_name: my-private-net   # which one to connect over
+```
+
+### Running cloud-init
+
+Inline, which is usually easier to read:
+
+```yaml
+driver:
+  name: openstack
+  cloud_config:
+    packages:
+      - htop
+    runcmd:
+      - [systemctl, restart, sshd]
+```
+
+Or from a file, which must exist:
+
+```yaml
+driver:
+  name: openstack
+  user_data: files/cloud-init.yml
+```
+
+### Booting from a volume
+
+```yaml
+driver:
+  name: openstack
+  block_device_mapping:
+    make_volume: true
+    volume_size: 20
+    device_name: vda
+    delete_on_termination: true
+    creation_timeout: 60      # seconds to wait for the volume to be available
+    attach_timeout: 5         # extra seconds before attaching
+```
+
+`make_volume: true` creates a new volume; source it from `snapshot_id`,
+`imageRef`, or `source_volid`. To attach a volume you already have, drop
+`make_volume` and give `volume_id`.
+
+### A cloud with a private CA
+
+Point at your CA bundle rather than turning verification off:
+
+```bash
+export OS_CACERT=/etc/ssl/certs/my-ca.pem
+```
+
+or in `clouds.yaml`:
+
+```yaml
+clouds:
+  mycloud:
+    cacert: /etc/ssl/certs/my-ca.pem
+```
+
+Either is passed through to the HTTP connection. `verify: false` in
+`clouds.yaml` disables verification entirely, equivalent to setting
+`disable_ssl_validation: true`.
+
+## Troubleshooting
+
+Start with `kitchen diagnose`, which prints the fully resolved driver config
+after `clouds.yaml` and `OS_*` have been merged in. If a credential is not
+there, the driver never saw it.
+
+```bash
+kitchen diagnose --all
+kitchen create --log-level=debug
+```
+
+| Symptom | Likely cause |
+| --- | --- |
+| `Image not found` / `Flavor not found` | The `_ref` matched nothing. Check `openstack image list`. A `/regex/` needs the surrounding slashes. |
+| `Cannot specify both image_ref and image_id` | Set one, not both. Same for flavor and network. |
+| `Could not find an IP` | The instance has no address of the family you asked for. Check `use_ipv6`, and whether you need a floating IP. |
+| `Server is not attached to network <name>` | `openstack_network_name` does not match any network on the instance. |
+| `Floating IP pool <name> not found` | The pool name is wrong; it is the external *network* name. |
+| `No available IPs in pool <name>` | Every address is in use. Set `allocate_floating_ip: true` to make a new one. |
+| `The user_data file <path> does not exist` | The path is wrong. It is resolved relative to where you run `kitchen`. |
+| `The security_groups config must be an array` | Use a list, even for a single group. |
+| Hangs at "Waiting for server to be ready" | The instance booted but SSH is unreachable. Check the security group allows port 22, that a floating IP is attached if you need one, and that `transport: username:` matches the image's default user. |
+| Times out reaching `ACTIVE` | Raise `glance_cache_wait_timeout`. First boot of a large image can be slow. |
+| TLS errors | Set `ssl_ca_file` (or `OS_CACERT`) to your CA bundle. |
+
+The instance is destroyed automatically if it never becomes reachable, so a
+failed `kitchen create` should not leak a server. If one does leak, `kitchen
+destroy` or `openstack server delete` will clear it.
+
+## Using with Chef
+
+This driver is not tied to Cinc. The examples above use Cinc Workstation and the
+`cinc_infra` provisioner, but the driver works exactly the same with
+[Chef Workstation](https://www.chef.io/downloads/tools/workstation) — run
+`kitchen` instead of `cinc kitchen`, and use `chef_infra` instead of
+`cinc_infra`:
+
+```yaml
+provisioner:
+  name: chef_infra
+
+verifier:
+  name: inspec
+```
+
+No driver configuration changes are needed.
+
+## Contributing
 
-## Development
+Pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for
+development setup, how to run the tests, how the suite is built, and the
+release process.
 
-Pull requests are very welcome! Make sure your patches are well tested.
-Ideally create a topic branch for every separate change you make. For
-example:
+## Credits
 
-1. Fork the repo
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Run the tests and rubocop, `bundle exec rake spec` and `bundle exec rake rubocop`
-4. Commit your changes (`git commit -am 'Added some feature'`)
-5. Push to the branch (`git push origin my-new-feature`)
-6. Create new Pull Request
+Originally created by Jonathan Hartman.
 
-## Authors
+Structure borrowed from [Fletcher Nichol](https://github.com/fnichol)'s
+[kitchen-ec2](https://github.com/test-kitchen/kitchen-ec2) and [Adam
+Leff](https://github.com/adamleff)'s
+[kitchen-vro](https://github.com/chef-partners/kitchen-vro).
 
-Created by Jonathan Hartman
+Further reference documentation is at
+<https://kitchen.ci/docs/drivers/openstack/>.
 
 ## License
 
-Apache 2.0 (see LICENSE.txt file)
+Apache 2.0. See [LICENSE.txt](LICENSE.txt).