diff --git a/docs/content/docs/drivers/aws.md b/docs/content/docs/drivers/aws.md index 0b4fea126..0c70ddaf2 100644 --- a/docs/content/docs/drivers/aws.md +++ b/docs/content/docs/drivers/aws.md @@ -8,59 +8,6 @@ menu: kitchen-ec2 is a Test Kitchen *driver* for EC2 in Amazon AWS. -Example **kitchen.yml**: - -```yaml ---- -driver: - name: ec2 - aws_ssh_key_id: id_rsa-aws - security_group_ids: ["sg-1a2b3c4d"] - region: us-west-2 - availability_zone: b - subnet_id: subnet-6e5d4c3b - iam_profile_name: chef-client - instance_type: m3.medium - associate_public_ip: true - interface: dns - -provisioner: - name: chef_infra - -verifier: - name: inspec - -transport: - ssh_key: /path/to/id_rsa-aws - connection_timeout: 10 - connection_retries: 5 - username: ubuntu - -platforms: - - name: ubuntu-16.04 - - name: centos-6.9 - - name: centos-7 - driver: - image_id: ami-c7d092f7 - block_device_mappings: - - device_name: /dev/sdb - ebs: - volume_type: gp2 - virtual_name: test - volume_size: 8 - delete_on_termination: true - transport: - username: centos - - name: windows-2012r2 - - name: windows-2016 - -suites: - - name: default - run_list: - - recipe[my_cookbook::default] - attributes: -``` - ### Setting Driver Configuration The Amazon AWS driver for Test Kitchen includes many configuration options that can be set globally in the driver section of your kitchen.yml config file or within each platform configuration. Global settings apply to all platforms in the `kitchen.yml`, while platform level driver configuration is applied to only those platforms and override globally set configuration options. Even if you use platform level configuration options, it's a good idea to specify the driver you use to use globally. @@ -481,3 +428,56 @@ If the `Private DNS Name` is preferred over the private IP, it must be specified driver: interface: private_dns ``` + +### Example **kitchen.yml** + +```yaml +--- +driver: + name: ec2 + aws_ssh_key_id: id_rsa-aws + security_group_ids: ["sg-1a2b3c4d"] + region: us-west-2 + availability_zone: b + subnet_id: subnet-6e5d4c3b + iam_profile_name: chef-client + instance_type: m3.medium + associate_public_ip: true + interface: dns + +provisioner: + name: chef_infra + +verifier: + name: inspec + +transport: + ssh_key: /path/to/id_rsa-aws + connection_timeout: 10 + connection_retries: 5 + username: ubuntu + +platforms: + - name: ubuntu-16.04 + - name: centos-6.9 + - name: centos-7 + driver: + image_id: ami-c7d092f7 + block_device_mappings: + - device_name: /dev/sdb + ebs: + volume_type: gp2 + virtual_name: test + volume_size: 8 + delete_on_termination: true + transport: + username: centos + - name: windows-2012r2 + - name: windows-2016 + +suites: + - name: default + run_list: + - recipe[my_cookbook::default] + attributes: +``` diff --git a/docs/content/docs/drivers/azurerm.md b/docs/content/docs/drivers/azurerm.md index ed58d7051..6e544d198 100644 --- a/docs/content/docs/drivers/azurerm.md +++ b/docs/content/docs/drivers/azurerm.md @@ -8,37 +8,6 @@ menu: kitchen-azurerm is a Test Kitchen *driver* for Microsoft Azure. -### Example **kitchen.yml** - -```yaml ---- -driver: - name: azurerm - subscription_id: '4801fa9d-YOUR-GUID-HERE-b265ff49ce21' - location: 'West Europe' - machine_size: 'Standard_D2_V2' - -provisioner: - name: chef_infra - -verifier: - name: inspec - -platforms: - - name: windows2016 - driver: - image_urn: MicrosoftWindowsServer:WindowsServer:2016-Datacenter:latest - transport: - name: winrm - elevated: true - -suites: - - name: default - run_list: - - recipe[my_cookbook::default] - attributes: -``` - ### Setting Driver Configuration The Microsoft Azure driver for Test Kitchen includes many configuration options that can be set globally in the driver section of your kitchen.yml config file or within each platform configuration. Global settings apply to all platforms in the `kitchen.yml`, while platform level driver configuration is applied to only those platforms and override globally set configuration options. Even if you use platform level configuration options, it's a good idea to specify the driver you use to use globally. @@ -330,4 +299,35 @@ identities. #### use_fqdn_hostname * _boolean_ : When true, Kitchen will use the FQDN that is assigned to the Virtual Machine. When false, kitchen will use the public IP address of the machine. This may overcome issues with Corporate firewalls or VPNs blocking Public IP addresses. - * Default Value: `false` \ No newline at end of file + * Default Value: `false` + +### Example **kitchen.yml** + +```yaml +--- +driver: + name: azurerm + subscription_id: '4801fa9d-YOUR-GUID-HERE-b265ff49ce21' + location: 'West Europe' + machine_size: 'Standard_D2_V2' + +provisioner: + name: chef_infra + +verifier: + name: inspec + +platforms: + - name: windows2016 + driver: + image_urn: MicrosoftWindowsServer:WindowsServer:2016-Datacenter:latest + transport: + name: winrm + elevated: true + +suites: + - name: default + run_list: + - recipe[my_cookbook::default] + attributes: +``` \ No newline at end of file diff --git a/docs/content/docs/drivers/digitalocean.md b/docs/content/docs/drivers/digitalocean.md index b5efa61b4..3c41febae 100644 --- a/docs/content/docs/drivers/digitalocean.md +++ b/docs/content/docs/drivers/digitalocean.md @@ -8,39 +8,6 @@ menu: kitchen-digitalocean is a Test Kitchen *driver* for DigitalOcean that runs against the DigitalOcean V2 API. -### Example **kitchen.yml** - -```yaml ---- -driver: - name: digitalocean - -provisioner: - name: chef_infra - -verifier: - name: inspec - -platforms: - - name: ubuntu-20 - - name: ubuntu-18 - region: sfo1 - driver: - tags: - - test-kitchen-instance - monitoring: true # disabled by default - vpcs: - - 3a92ae2d-f1b7-4589-81b8-8ef144374453 - ipv6: true # disabled by default - private_networking: false # enabled by default - -suites: - - name: default - run_list: - - recipe[my_cookbook::default] - attributes: -``` - ### Setting Driver Configuration The DigitalOcean driver for Test Kitchen includes many configuration options that can be set globally in the driver section of your kitchen.yml config file or within each platform configuration. Global settings apply to all platforms in the `kitchen.yml`, while platform level driver configuration is applied to only those platforms and override globally set configuration options. Even if you use platform level configuration options, it's a good idea to specify the driver you use to use globally. @@ -252,3 +219,36 @@ Note that your `vpc_uuid` must be the numeric ids of your vpc. To get the numeri ```bash curl -X GET https://api.digitalocean.com/v2/vpcs -H "Authorization: Bearer $DIGITALOCEAN_ACCESS_TOKEN" ``` + +### Example **kitchen.yml** + +```yaml +--- +driver: + name: digitalocean + +provisioner: + name: chef_infra + +verifier: + name: inspec + +platforms: + - name: ubuntu-20 + - name: ubuntu-18 + region: sfo1 + driver: + tags: + - test-kitchen-instance + monitoring: true # disabled by default + vpcs: + - 3a92ae2d-f1b7-4589-81b8-8ef144374453 + ipv6: true # disabled by default + private_networking: false # enabled by default + +suites: + - name: default + run_list: + - recipe[my_cookbook::default] + attributes: +``` diff --git a/docs/content/docs/drivers/dokken.md b/docs/content/docs/drivers/dokken.md index 5c07f6461..82beaa818 100644 --- a/docs/content/docs/drivers/dokken.md +++ b/docs/content/docs/drivers/dokken.md @@ -10,45 +10,6 @@ kitchen-dokken is a Test Kitchen *plugin* for Docker that uses specially created Unlike all other Test Kitchen drivers, kitchen-dokken handles all the tasks of the driver, transport, and provisioner itself. This approach focuses purely on Chef Infra cookbook testing to provide ultra-fast testing times. Docker containers have a fast creation and start time, and kitchen-dokken uses the official Chef Infra Client containers instead of spending the time to download and install the Chef Infra Client packages. These design decisions result in tests that run in seconds instead of minutes and don't require high bandwidth Internet connections. -### Example **kitchen.yml** - -```yaml ---- -driver: - name: dokken - privileged: true # allows systemd services to start - -provisioner: - name: dokken - -transport: - name: dokken - -verifier: - name: inspec - -platforms: - - name: ubuntu-20.04 - driver: - image: dokken/ubuntu-20.04 - pid_one_command: /bin/systemd - intermediate_instructions: - - RUN /usr/bin/apt-get update - - - name: centos-8 - driver: - image: dokken/centos-8 - pid_one_command: /usr/lib/systemd/systemd - -suites: - - name: default - run_list: - - recipe[my_cookbook::default] - verifier: - inspec_tests: - - test/integration/default -``` - ### Driver vs. Provisioner vs. Transport Since kitchen-dokken combines driver, transport, and provisioner functionality into a single plugin, its configuration differs from other Test Kitchen drivers. kitchen-dokken includes specific configuration options that can be set in the driver, provisioner, or transport sections or in the individual platforms / suites. At a bare minimum to use kitchen-dokken you must specify dokken as the driver, provisioner, and transport sections of your `kitchen.yml` file: @@ -537,3 +498,42 @@ The `timeout` configuration option specifies the timeout in seconds for communic ### Dokken Linux Containers Specially created containers for kitchen-dokken, build off official Linux distro images, but include all of the packages and services necessary to test Chef Infra cookbooks. These containers are produced for leading Linux distributions such as CentOS, OpenSUSE, Amazon Linux, and Ubuntu. For a complete list of available dokken specific container images see [u/dokken](https://hub.docker.com/u/dokken) on Docker Hub. + +### Example **kitchen.yml** + +```yaml +--- +driver: + name: dokken + privileged: true # allows systemd services to start + +provisioner: + name: dokken + +transport: + name: dokken + +verifier: + name: inspec + +platforms: + - name: ubuntu-20.04 + driver: + image: dokken/ubuntu-20.04 + pid_one_command: /bin/systemd + intermediate_instructions: + - RUN /usr/bin/apt-get update + + - name: centos-8 + driver: + image: dokken/centos-8 + pid_one_command: /usr/lib/systemd/systemd + +suites: + - name: default + run_list: + - recipe[my_cookbook::default] + verifier: + inspec_tests: + - test/integration/default +``` diff --git a/docs/content/docs/drivers/hyperv.md b/docs/content/docs/drivers/hyperv.md index 21d3cb1cf..571e59bc7 100644 --- a/docs/content/docs/drivers/hyperv.md +++ b/docs/content/docs/drivers/hyperv.md @@ -8,7 +8,7 @@ menu: kitchen-hyperv is a Test Kitchen *driver* for Microsoft Hyper-V. -Example **kitchen.yml**: +## Example **kitchen.yml** ```yaml --- diff --git a/docs/content/docs/drivers/openstack.md b/docs/content/docs/drivers/openstack.md index f9810e18a..c6514d64b 100644 --- a/docs/content/docs/drivers/openstack.md +++ b/docs/content/docs/drivers/openstack.md @@ -8,54 +8,6 @@ menu: kitchen-openstack is a Test Kitchen *driver* for OpenStack. -Example **kitchen.yml**: - -```yaml ---- -driver: - name: openstack - openstack_username: [YOUR OPENSTACK USERNAME] - openstack_api_key: [YOUR OPENSTACK API KEY] # AKA your OPENSTACK PASSWORD - openstack_auth_url: [YOUR OPENSTACK AUTH URL] - openstack_domain_id: [default is 'default'; otherwise YOUR OPENSTACK DOMAIN ID] - require_chef_omnibus: [e.g. 'true' or a version number if you need Chef] - image_ref: [SERVER IMAGE ID] - flavor_ref: [SERVER FLAVOR ID] - key_name: [KEY NAME] - read_timeout: 180 - write_timeout: 180 - connect_timeout: 180 - -provisioner: - name: chef_infra - -verifier: - name: inspec - -transport: - ssh_key: /path/to/id_rsa #Path to private key that matches the above openstack key_name - connection_timeout: 10 - connection_retries: 5 - username: ubuntu - password: mysecreatpassword - -platforms: - - name: ubuntu-18.04 - - name: ubuntu-20.04 - - name: centos-8 - transport: - username: centos - - name: windows-2022 - transport: - password: myadministratorpassword - -suites: - - name: default - run_list: - - recipe[my_cookbook::default] - attributes: -``` - ## Minimum Configuration ```yaml @@ -84,50 +36,50 @@ All of Fog's `openstack` options (`openstack_domain_name`, `openstack_project_na **Required** Tell test-kitchen what driver to use. ;) -### openstack\_username +### openstack_username **Required** Your OpenStack username. -### openstack\_api\_key +### openstack_api_key **Required** Your OpenStack API Key, aka your OpenStack password. -### openstack\_auth\_url +### openstack_auth_url **Required** Your OpenStack auth url. If you are using ID v3, you'll need to use `API_URL/v3/auth/tokens`. -### require\_chef_omnibus +### require_chef_omnibus **Required** Set to `true` otherwise the specific version of Chef omnibus you want installed. -### image\_ref +### image_ref **image_ref or image_id required** Server Image Name or ID. -### image\_id +### image_id **image_ref or image_id required** Server Image ID. Specifying the ID instead of reference results in a faster create time. **Note** If the image UUID changes this value will need to be updated. -### flavor\_ref +### flavor_ref **flavor_ref or flavor_id required** Server Flavor Name or ID. -### flavor\_ref +### flavor_id -**flavor_ref or flavor_id required** Server Flavor ID. Specifying the ID instead of reference results in a faster create time. +**flavor_ref or flavor_id required** Specifying the ID instead of reference results in a faster create time. **Note** If the flavor UUID changes this value will need to be updated. -### server\_name +### server_name If a `server_name_prefix` is specified then this prefix will be used when generating random names of the form `-` e.g. `myproject-asdfghjk`. If both `server_name_prefix` and `server_name` are specified then the `server_name` takes precedence. -### server\_name\_prefix +### server_name_prefix If you want to have a static prefix for a random server name. @@ -135,38 +87,42 @@ If you want to have a static prefix for a random server name. Set the SSH port for the remote access. -### openstack\_tenant +### openstack_tenant Your OpenStack tenant id. -### openstack\_region +### openstack_region Your OpenStack region id. -### availability\_zone +### availability_zone Your OpenStack availablity zone. -### openstack\_service\_name +### openstack_service_name Your OpenStack compute service name. -### openstack\_network\_name +### openstack_network_name Your OpenStack network name used to connect to, if you have only private network connections you want declare this. -### glance\_cache\_wait\_timeout +### glance_cache_wait_timeout + When OpenStack downloads the image into cache, it takes extra time to provision. Timeout controls maximum amount of time to wait for machine to move from the Build/Spawn phase to Active. -### connect\_timeout +### connect_timeout + Connect timeout controls maximum amount of time to wait for machine to respond to ssh login request. -### read\_timeout -### write\_timeout +### read_timeout + +### write_timeout + Expose read/write timeout parameters passed down to HTTP connection created via [excon](https://github.com/excon/excon). Default timeouts (from excon) are 60 seconds. -### server\_wait +### server_wait `server_wait` is a workaround to deal with how some VMs with `cloud-init`. Some clouds need this some, most OpenStack instances don't. This is a stop gap @@ -179,7 +135,7 @@ in a good state. The default is `0`. -### security\_groups +### security_groups A list of `security_groups` to join: @@ -189,12 +145,12 @@ security_groups: - [...SECURITY GROUPS TO JOIN] ``` -### user\_data +### user_data If your VMs have `cloud-init` enabled you can use the `user_data` in your kitchen.yml to inject commands at boot time. -``` +```yaml driver_config: user_data: userdata.txt ``` @@ -202,16 +158,16 @@ kitchen.yml to inject commands at boot time. Then create a `userdata.txt` in the same directory as your .kitchen.yml, for example: -``` +```shell #!/bin/sh echo "do whatever you want to pre-configure your machine" ``` -### cloud\_config +### cloud_config If your VMs have `cloud-init` enabled you can use `cloud_config` to generate userdata for use by cloud-init in the [cloud-config format](https://cloudinit.readthedocs.io/en/latest/topics/format.html#cloud-config-data). This provides a convenient way to specify cloud-init config inline. As the cloud-config format uses YAML the resulting userdata is essentially a copy+paste of `cloud_config` with the header line '#cloud-config' -``` +```yaml driver_config: cloud_config: hostname: my-hostname @@ -226,15 +182,15 @@ hostname: my-hostname The `cloud_config` and `user_data` options are mutually exclusive. -### config\_drive +### config_drive If your VMs require config drive. -``` +```yaml config_drive: true ``` -### network\_ref +### network_ref **Deprecated** A list of network names to create instances with. @@ -244,7 +200,7 @@ network_ref: - [CREATE INSTANCE WITH] ``` -### network\_id +### network_id A list of network ids to create instances with. Specifying the id instead of reference results in a faster create time. @@ -256,66 +212,68 @@ network_ref: - [TO CREATE INSTANCE WITH] ``` -### no\_ssh\_tcp\_check +### no_ssh_tcp_check **Deprecated** You should be using transport now. This will skip the ssh check to automatically connect. The default is `false`. -### no\_ssh\_tcp\_check\_sleep +### no_ssh_tcp_check_sleep **Deprecated** You should be using transport now. This will sleep for so many seconds. `no_ssh_tcp_check` needs to be set to `true`. -### private\_key\_path +### private_key_path **Deprecated** You should be using transport now. The guest image should use `cloud-init` or some other method to fetch key from meta-data service. -### public\_key\_path +### public_key_path **Deprecated** You should be using transport now. The guest image should use `cloud-init` or some other method to fetch key from meta-data service. ## Disk Configuration -### block\_device\_mapping +### block_device_mapping -#### make\_volume +#### make_volume Makes a new volume when set to `true`. The default is `false`. -#### snapshot\_id +#### snapshot_id When set, will make a volume from that snapshot id. -#### volume\_id +#### volume_id When set, will attach the volume id. -#### device\_name +#### device_name Set this to `vda` unless you really know what you are doing. -#### availability\_zone +#### availability_zone The block storage availability zone. The default is `nova`. -#### volume\_type +#### volume_type The volume type, this is optional. -#### delete\_on\_termination +#### delete_on_termination This will delete the volume on the instance when `destroy` happens, if set to true. Otherwise set this to `false`. -#### creation\_timeout +#### creation_timeout + Timeout to wait for volume to become available. If a large volume is provisioned, it might take time to provision it on the backend. Maximum amount of time to wait for volume to be created and be available. -#### attach\_timeout +#### attach_timeout + If using a customized version of Openstack such a VMWare Integrated OPenstack (VIO), it may mark a volume active even though it is still performing some actions which may cause test kitchen to attach the volume to early which results in errors. Specify in seconds the amount of time to delay attaching the volume after its been marked active. Default timeout is 0. #### Example @@ -333,12 +291,12 @@ block_device_mapping: ## Network and Communication Configuration -### floating\_ip +### floating_ip A specific `floating_ip` can be provided to bind a floating IP to the node. Any floating IP will be the IP used for Test Kitchen's Remote calls to the node. -### floating\_ip\_pool +### floating_ip_pool A `floating_ip_pool` can be provided to allocate a floating IP from the pool to the instance. If `allocate_floating_ip` is true, the IP will be allocated, @@ -346,12 +304,12 @@ otherwise the first free floating IP will be used. It will be the IP used for Test Kitchen's Remote calls to the node. If allocated, the floating IP will be released once the instance is destroyed. -### allocate\_floating\_ip +### allocate_floating_ip If true, allocate a new IP from the specified `floating_ip_pool` and release is afterwards. Otherwise, if false (the default), an existing allocated IP. -### \[public\|private\]\_ip\_order +### \[public\|private\]_ip_order In some complex network scenarios you can have several IP addresses designated as public or private. Use `public_ip_order` or `private_ip_order` to control @@ -372,6 +330,7 @@ to use second `10.0.1.1` IP address you need to specify ```yaml private_ip_order: 1 ``` + assuming that test network is configured as private. ### use_ipv6 @@ -379,7 +338,7 @@ assuming that test network is configured as private. If true use IPv6 addresses to for SSH connections. If false, the default, use IPv4 addresses for SSH connections. -### network\_ref +### network_ref The `network_ref` option can be specified as an exact id, an exact name, or as a regular expression matching the name of the network. You can pass one @@ -403,8 +362,7 @@ instance to provide more control over network connectivity. Please note that `network_ref` relies on Network Services (`Fog::Network`) and it can be unavailable in your OpenStack installation. - -### disable\_ssl\_validation +### disable_ssl_validation ```yaml disable_ssl_validation: true @@ -412,3 +370,51 @@ it can be unavailable in your OpenStack installation. Only disable SSL cert validation if you absolutely know what you are doing, but are stuck with an OpenStack deployment without valid SSL certs. + +## Example **kitchen.yml** + +```yaml +--- +driver: + name: openstack + openstack_username: [YOUR OPENSTACK USERNAME] + openstack_api_key: [YOUR OPENSTACK API KEY] # AKA your OPENSTACK PASSWORD + openstack_auth_url: [YOUR OPENSTACK AUTH URL] + openstack_domain_id: [default is 'default'; otherwise YOUR OPENSTACK DOMAIN ID] + require_chef_omnibus: [e.g. 'true' or a version number if you need Chef] + image_ref: [SERVER IMAGE ID] + flavor_ref: [SERVER FLAVOR ID] + key_name: [KEY NAME] + read_timeout: 180 + write_timeout: 180 + connect_timeout: 180 + +provisioner: + name: chef_infra + +verifier: + name: inspec + +transport: + ssh_key: /path/to/id_rsa #Path to private key that matches the above openstack key_name + connection_timeout: 10 + connection_retries: 5 + username: ubuntu + password: mysecreatpassword + +platforms: + - name: ubuntu-18.04 + - name: ubuntu-20.04 + - name: centos-8 + transport: + username: centos + - name: windows-2022 + transport: + password: myadministratorpassword + +suites: + - name: default + run_list: + - recipe[my_cookbook::default] + attributes: +```