Refactors azure_virtual_machine_data_disk doc (#2701)

* Refactors azure_virtual_machine_data_disk doc

Signed-off-by: kagarmoe <kgarmoe@chef.io>
This commit is contained in:
Kimberly Garmoe 2018-02-19 18:12:53 -08:00 committed by Jared Quick
parent a83123444f
commit 696dde39ef

View file

@ -1,52 +1,26 @@
---
title: About the azure_virtual_machine_datadisk Resource
platform: azure
---
# azure\_virtual\_machine\_datadisk
Use this resource to ensure that a specific data disk attached to a machine has been created properly.
## References
- [Azure Ruby SDK - Compute](https://github.com/Azure/azure-sdk-for-ruby/tree/master/management/azure_mgmt_compute)
## Syntax
The name of the resource group and machine are required to use this resource.
describe azure_virtual_machine_data_disk(group_name: 'MyResourceGroup', name: 'MyVM') do
describe azure_virtual_machine_data_disk(group_name: 'InSpec-Azure', name: 'MyVM') do
its('property') { should eq 'value' }
end
where
* `MyVm` is the name of the virtual machine as seen in Azure. (It is **not** the hostname of the machine)
* `MyResourceGroup` is the name of the resouce group that the machine is in.
* `InSpec-Azure` is the name of the resouce group that the machine is in.
* `property` is a resource property
* `value` is the expected output fdrom the matcher
The `count`, `have_data_disks` and `have_managed_disks` are catchall tests that give information about the virtual machine. The specific tests need to be used in conjunction with the `where` option as shown below.
| Name | Description | Required | Example |
|-------------|---------------------------------------------------------------------------------------------------------------------|----------|-----------------------------------|
| group_name: | Azure Resource Group to be tested | yes | MyResourceGroup |
| name: | Name of the Azure resource to test | no | MyVM |
| apiversion: | API Version to use when interrogating the resource. If not set then the latest version for the resoure type is used | no | 2017-10-9 |
These options can also be set using the environment variables:
- `AZURE_RESOURCE_GROUP_NAME`
- `AZURE_RESOURCE_NAME`
- `AZURE_RESOURCE_API_VERSION`
When the options have been set as well as the environment variables, the environment variables take priority.
For example:
describe azure_virtual_machine_data_disk(group_name: 'Inspec-Azure', name: 'Linux-Internal-VM') do
its('count') { should cmp > 0 }
it { should have_data_disks }
end
* `value` is the expected output from the matcher
<br>
@ -54,23 +28,83 @@ For example:
The following examples show to use this InSpec audit resource.
Please refer to the following integration tests for more in depth examples:
- [Linux Internal Data Disks](../../test/integration/verify/controls/virtual_machine_linux_external_vm_datadisk.rb)
- [Windows Internal Data Disk](../../test/integration/verify/controls/virtual_machine_windows_internal_vm_datadisk.rb)
### Check that the first data disk is of the correct size
describe azure_virtual_machine_data_disk(group_name: 'Inspec-Azure', name: 'Linux-Internal-VM').where(number: 1) do
describe azure_virtual_machine_data_disk(group_name: 'InSpec-Azure', name: 'Linux-Internal-VM').where(number: 1) do
its('size') { should cmp >= 15 }
end
<br>
## Resource Parameters
* `group_name`, `name`, `apiversion`
## Parameter Examples
The options that can be passed to the resource are as follows.
### group_name (required)
Use this parameter to define the Azure Resource Group to be tested.
describe azure_virtual_machine_data_disk(group_name: 'InSpec-Azure') do
...
end
### name
Use this parameter to define the name of the Azure resource to test.
describe azure_virtual_machine_data_disk(group_name: 'InSpec-Azure', name: 'Windows-Internal-VM') do
...
end
### apiversion
The API Version to use when querying the resource. Defaults to the latest version for the resoure type is used.
describe azure_virtual_machine_data_disk(group_name: 'InSpec-Azure', name: 'Windows-Internal-VM', apiversion: '2.0') do
...
end
These options can also be set using the environment variables:
* `AZURE_RESOURCE_GROUP_NAME`
* `AZURE_RESOURCE_NAME`
* `AZURE_RESOURCE_API_VERSION`
When the options have been set as well as the environment variables, the environment variables take priority.
<br>
## Filter Criteria
* `number`, `disk`
<br>
## Filter Examples
### disk
The zero based index of the disk attached to the machine.
describe azure_virtual_machine_data_disk(group_name: 'InSpec-Azure', name: 'Windows-Internal-VM').where(disk: 0)
end
### number
The '1' based index of the disk attached to the machine.
describe azure_virtual_machine_data_disk(group_name: 'InSpec-Azure', name: 'Windows-Internal-VM').where(number: 1)
end
<br>
## Properties
* `count`, `have_data_disks`, `have_managed_disks`, `disk`, `number`, `name`, `size`, `lun`
, `caching`, `create_option`, `is_managed_disk?`, `vhd_uri`, `storage_account_name`, `storage_account_type`, `id`, `subscription_id`, `resource_group`
* `count`, `disk`, `number`, `name`, `size`, `lun`, `caching`, `create_option`, `is_managed_disk?`, `vhd_uri`, `storage_account_name`, `storage_account_type`, `id`, `subscription_id`, `resource_group`
<br>
@ -82,9 +116,96 @@ Returns the number of data disks attached to the machine
its('count') { should eq 1 }
### name
Returns a string of the name of the disk.
its('name') { should cmp 'linux-external-datadisk-1' }
### size
Returns an integer of size of this disk in GB.
its('size') { should cmp >= 15 }
### lun
The disk number as reported by Azure. This is a zero based index value.
its('lun') { should cmp 0 }
### caching
String stating the caching that has been set on the disk.
its('caching') { should cmp 'none' }
### create\_option
How the disk was created. Typically for data disks this will be the string value 'Empty'.
its('create_option') { should cmp 'Empty' }
### is\_managed\_disk?
Boolean stating if the disk is a managed disk or not. If it is not a managed disk then it is one that is stored in a Storage Account.
its('is_managed_disk?') { should cmp 'false' }
### vhd\_uri
If this _not_ a managed disk then the `vhd_uri` will be the full URI to the disk in the storage account.
its('vhd_uri') { should cmp '
https://primary_storage.blob.core.windows.net/container_name/vm_name.vhd' }
### storage\_account\_name
If this is _not_ a managed disk this will be the storage account name in which the disk is stored.
This derived from the `vhd_uri`.
its('storage_account_name') { should cmp 'primary_storage' }
### storage\_account\_type
If this is a managed disk this is the storage account type, e.g. `Standard_LRS`
its('storage_account_type') { should cmp 'Standard_LRS' }
### id
If this is a managed disk then this is the fully qualified id for the disk in Azure.
its('id') { should cmp '/subscriptions/1234abcd-e567-890f-g123-456h78i9jkl0/resourceGroups/InSpec-Azure' }
### subscription\_id
If this is a managed disk, this returns the subscription id of where the disk is stored.
This is derived from the `id`.
its('subscription_id') { should cmp '1234abcd-e567-890f-g123-456h78i9jkl0' }
### resource\_group
If this is a managed disk, this returns the resource group in which the disk is stored.
This is derived from the `id`.
its('resource_group') { should cmp 'InSpec-Azure' }
<br>
## Matchers
This InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
The following properties are applied to the virtual machine itself and not specfic disks.
### have\_data\_disks
Returns a boolean denoting if any data disks are attached to the machine
Returns a boolean denoting if any data disks are attached to the machine.
it { should have_data_disks }
@ -94,89 +215,10 @@ Returns a boolean stating if the machine has Managed Disks for data disks.
it { should have_managed_disks }
**The next set of attributes require the `where` operation to be used on the describe.**
The following code shows an example of how to use the where clause.
describe azure_virtual_machine_data_disk(group_name: 'Inspec-Azure', name: 'Windows-Internal-VM').where(number: 1)
end
### disk
The zero based index of the disk attached to the machine.
Typically used in the `where` clause
### number
The '1' based index of the disk attached to the machine.
Typically used in the `where` clause as showm above.
### name
Returns a string of the name of the disk.
### size
Returns an integer of size of this disk in GB.
### lun
The disk number as reported by Azure. This is a zero based index value.
### caching
String stating the caching that has been set on the disk.
### create\_option
How the disk was created. Typically for data disks this will be the string value 'Empty'.
### is\_managed\_disk?
Boolean stating if the disk is a managed disk or not. If it is not a managed disk then it is one that is stored in a Storage Account.
### vhd\_uri
If this _not_ a managed disk then the `vhd_uri` will be the full URI to the disk in the storage account.
### storage\_account\_name
If this is _not_ a managed disk this will be the storage account name in which the disk is stored.
This derived from the `vhd_uri`.
### storage\_account\_type
If this is a managed disk this is the storage account type, e.g. `Standard_LRS`
### id
If this is a managed disk then this is the fully qualified id to the disk in Azure.
### subscription\_id
If this is a managed disk, this returns the subscription id of where the disk is stored.
This is derived from the `id`.
### resource\_group
If this is a managed disk, this returns the resource group in which the disk is stored.
This is derived from the `id`.
<br>
## Matchers
## References
This InSpec audit resource has the following matchers:
### eq
Use the `eq` matcher to test the equality of two values: `its('Port') { should eq '22' }`.
Using `its('Port') { should eq 22 }` will fail because `22` is not a string value! Use the `cmp` matcher for less restrictive value comparisons.
**The following properties are ones that are applied to the virtual machine itself and not specfic disks**
* [Azure Ruby SDK - Compute](https://github.com/Azure/azure-sdk-for-ruby/tree/master/management/azure_mgmt_compute)
* [Linux Internal Data Disks](https://github.com/chef/inspec/blob/master/test/azure/verify/controls/virtual_machine_linux_external_vm_datadisk.rb)
* [Windows Internal Data Disk](https://github.com/chef/inspec/blob/master/test/azure/verify/controls/virtual_machine_windows_internal_vm_datadisk.rb)