Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Resource Docs cleanup - For Clinton's Review #663

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Resource Docs cleanup - For Clinton's Review #663

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 9 additions & 10 deletions docs-chef-io/content/inspec/resources/azure_active_directory_domain_service.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ Either one of the following parameters is mandatory.
: The fully qualified name of the domain. Key, immutable, not nullable, unique.

`authenticationType`
: Indicates the configured authentication type for the domain.The value is either `Managed` or `Federated`.
: Indicates the configured authentication type for the domain. The value is either `Managed` or `Federated`.

`availabilityStatus`
: This property is always `null` except when the verify action is used.
Expand All @@ -52,10 +52,10 @@ Either one of the following parameters is mandatory.
: The value of the property is `false` if the DNS record management of the domain has been delegated to Microsoft 365.

`isDefault`
: `true` if this is the default domain that is used for user creation. There is only one default domain per company. Not nullable.
: `true` if this is the default domain used for user creation. There is only one default domain per company. Not nullable.

`isInitial`
: `true` if this is the initial domain created by Microsoft Online Services (companyname.onmicrosoft.com). There is only one initial domain per company.
: `true` if this is the initial domain created by Microsoft Online Services (`companyname.microsoft.com`). There is only one initial domain per company.

`isRoot`
: `true` if the domain is a verified root domain. Otherwise, `false` if the domain is a subdomain or unverified.
Expand All @@ -64,10 +64,10 @@ Either one of the following parameters is mandatory.
: `true` if the domain has completed domain ownership verification.

`passwordNotificationWindowInDays`
: Specifies the number of days before a user receives notification that their password will expire. If the property is not set, a default value of 14 days will be used.
: Specifies the number of days before a user receives a password expiry notification. A default value of 14 days is used if the property is not set.

`passwordValidityPeriodInDays`
: Specifies the length of time that a password is valid before it must be changed. If the property is not set, a default value of 90 days will be used.
: Specifies the length of time that a password is valid before it must be changed. A default value of 90 days is used if the property is not set.

`supportedServices`
: The capabilities assigned to the domain.
Expand All @@ -77,15 +77,15 @@ Either one of the following parameters is mandatory.

## Examples

**Test If an Active Directory Domain is Referenced with a Valid ID.**
### Test to ensure if an active directory domain is referenced with a Valid ID

```ruby
describe azure_active_directory_domain_service(id: 'example.com') do
it { should exist }
end
```

**Test If an Active Directory Domain is Referenced with an Invalid ID.**
### Test to ensure if an active directory domain is referenced with an Invalid ID

```ruby
describe azure_active_directory_domain_service(id: 'example.com') do
Expand All @@ -97,7 +97,7 @@ end

{{% inspec_matchers_link %}}

### exists
### Exists
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
### Exists
### exists


```ruby
describe azure_active_directory_domain_service(id: 'example.onmicrosoft.com') do
Expand All @@ -107,5 +107,4 @@ end

## Azure Permissions

Graph resources require specific privileges granted to your service principal.
Please refer to the [Microsoft Documentation](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-integrating-applications#updating-an-application) for information on how to grant these permissions to your application.
Graph resources require specific privileges granted to your service principal. Please refer to the [Microsoft Documentation](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-integrating-applications#updating-an-application) for information on how to grant these permissions to your application.
19 changes: 9 additions & 10 deletions docs-chef-io/content/inspec/resources/azure_active_directory_domain_services.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ end
The following parameters can be passed for targeting specific domains.

`filter`
: A hash containing the filtering options and their values. The `starts_with_` operator can be used for fuzzy string matching. Parameter names are in snake case.
: A hash containing the filtering options and their values. The `starts_with_` operator can be used for fuzzy string matching. Parameter names are in the snake case.

: **Example**: `{ starts_with_given_name: 'J', starts_with_department: 'Core', country: 'United Kingdom', given_name: John}`

Expand All @@ -44,7 +44,7 @@ The following parameters can be passed for targeting specific domains.

: **Example**: `"startswith(displayName,'J') and surname eq 'Doe'"` or `"userType eq 'Guest'"`

It is advised to use these parameters to narrow down the targeted resources at the server side, Azure Graph API, for a more efficient test.
It is advised to use these parameters to narrow down the targeted resources at the server-side, Azure Graph API, for a more efficient test.

## Properties

Expand All @@ -64,7 +64,7 @@ It is advised to use these parameters to narrow down the targeted resources at t
: **Field**: `availabilityStatus`

`is_admin_manageds`
: A list of admin managed configuration.
: A list of admin-managed configuration.

: **Field**: `isAdminManaged`

Expand Down Expand Up @@ -114,23 +114,23 @@ It is advised to use these parameters to narrow down the targeted resources at t

The following examples show how to use this InSpec audit resource.

**Check domains with some filtering parameters applied at server side using `filter`.**
### Test to ensure domains with some filtering parameters are applied at server side using `filter`

```ruby
describe azure_active_directory_domain_services(filter: {authenticationType: "authenticationType-value"}) do
it { should exist }
end
```

**Check domains with some filtering parameters applied at server side using `filter_free_text`.**
### Test to ensure domains with some filtering parameters are applied at the server side using `filter_free_text`

```ruby
describe azure_active_directory_domain_services(filter_free_text: "startswith(authenticationType,'authenticationType-value')") do
it { should exist }
end
```

**Ensure there are supported services using client-side filtering.**
### Test to ensure there are supported services using client-side filtering

```ruby
describe azure_active_directory_domain_services.supportedServices do
Expand All @@ -142,9 +142,9 @@ end

{{% inspec_matchers_link %}}

### exists
### Exists
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
### Exists
### exists


The control will pass if the filter returns at least one result. Use `should_not` if you expect zero matches.
The control passes if the filter returns at least one result. Use `should_not` if you expect zero matches.

```ruby
describe azure_active_directory_domain_services do
Expand All @@ -154,5 +154,4 @@ end

## Azure Permissions

Graph resources require specific privileges granted to your service principal.
Please refer to the [Microsoft Documentation](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-integrating-applications#updating-an-application) for information on how to grant these permissions to your application.
Graph resources require specific privileges granted to your service principal. Please refer to the [Microsoft Documentation](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-integrating-applications#updating-an-application) for information on how to grant these permissions to your application.
55 changes: 32 additions & 23 deletions docs-chef-io/content/inspec/resources/azure_aks_cluster.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ identifier = "inspec/resources/azure/azure_aks_cluster Resource"
parent = "inspec/resources/azure"
+++

Use the `azure_aks_cluster` InSpec audit resource to test properties of an Azure AKS Cluster.
Use the `azure_aks_cluster` InSpec audit resource to test the properties of an Azure AKS Cluster.

## Azure REST API Version, Endpoint, and HTTP Client Parameters

Expand All @@ -22,12 +22,14 @@ Use the `azure_aks_cluster` InSpec audit resource to test properties of an Azure

## Syntax

An `azure_aks_cluster` resource block identifies an AKS Cluster by `name` and `resource_group` or the `resource_id`.
An `azure_aks_cluster` resource block identifies an AKS Cluster by `name` and `resource_group`, or the `resource_id`.

```ruby
describe azure_aks_cluster(resource_group: 'example', name: 'ClusterName') do
describe azure_aks_cluster(resource_group: 'RESOURCE_GROUP', name: 'CLUSTER_NAME') do
it { should exist }
end
```

```ruby
describe azure_aks_cluster(resource_id: '/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/Microsoft.ContainerService/managedClusters/{ClusterName}') do
it { should exist }
Expand All @@ -37,17 +39,18 @@ end
## Parameters

`resource_group`
: Azure resource group that the targeted resource resides in. `MyResourceGroup`.
: Azure resource group where the targeted resource resides.

`name`
: Name of the AKS cluster to test. `ClusterName`.
: Name of the AKS cluster to test.

`resource_id`
: The unique resource ID. `/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/Microsoft.ContainerService/managedClusters/{ClusterName}`.

Either one of the parameter sets can be provided for a valid query:
Either one of the following parameter sets can be provided for a valid query:

- `resource_id`
- `resource_group` and `name`
- `resource_group` and `name`.

## Properties

Expand All @@ -66,70 +69,76 @@ Either one of the parameter sets can be provided for a valid query:
`disabled_logging_types`
: The logging types that are disabled for the AKS cluster.

For properties applicable to all resources, such as `type`, `name`, `id`, `properties`, refer to [`azure_generic_resource`]({{< relref "azure_generic_resource.md#properties" >}}).
For properties applicable to all resources, such as `type`, `name`, `id`, and `properties`, refer to [`azure_generic_resource`]({{< relref "azure_generic_resource.md#properties" >}}).

Also, refer to [Azure documentation](https://docs.microsoft.com/en-us/rest/api/aks/managedclusters/get#managedcluster) for other properties available.

Also, refer to [Azure documentation](https://docs.microsoft.com/en-us/rest/api/aks/managedclusters/get#managedcluster) for other properties available.
Any attribute in the response may be accessed with the key names separated by dots (`.`).

## Examples

**Test that an AKS Cluster has the Desired Network Plug-in.**
### Test to ensure that an AKS Cluster has the desired network plug-in

```ruby
describe azure_aks_cluster(resource_group: 'example', name: 'ClusterName') do
describe azure_aks_cluster(resource_group: 'RESOURCE_GROUP', name: 'CLUSTER_NAME') do
its('properties.networkProfile.networkPlugin') { should cmp 'kubenet' }
end
```

**Loop through All Clusters within The Subscription.**
### Test to loop through all clusters within the subscription

```ruby
azure_aks_clusters.ids.each do |resource_id|
describe azure_aks_cluster(resource_id: resource_id) do
its('properties.networkProfile.networkPlugin') { should cmp 'kubenet' }
end
end
end
```

**Test that a Specified AKS Cluster has the Correct Number of Nodes in Pool.**
### Test to ensure a specified AKS Cluster has the correct number of nodes in the pool

```ruby
describe azure_aks_cluster(resource_group: 'example', name: 'ClusterName') do
describe azure_aks_cluster(resource_group: 'RESOURCE_GROUP', name: 'CLUSTER_NAME') do
its('properties.agentPoolProfiles.first.count') { should cmp 5 }
end
```

**Test that a Specified AKS Cluster has kube-audit logging enabled.**
### Test to ensure a specified AKS Cluster has kube-audit logging enabled

```ruby
describe azure_aks_cluster(resource_group: 'example', name: 'ClusterName') do
describe azure_aks_cluster(resource_group: 'RESOURCE_GROUP', name: 'CLUSTER_NAME') do
its('enabled_logging_types') { should include "kube-audit" }
end
```

**Test that a Specified AKS Cluster has logging enabled on it and no forms of logging disabled.**
### Test to ensure a specified AKS Cluster has logging enabled on it and no forms of logging disabled

```ruby
describe azure_aks_cluster(resource_group: 'example', name: 'ClusterName') do
describe azure_aks_cluster(resource_group: 'RESOURCE_GROUP', name: 'CLUSTER_NAME') do
its('disabled_logging_types.count') { should eq 0 }
end
```

See [integration tests](../../test/integration/verify/controls/azurerm_aks_cluster.rb) for more examples.

## Matchers

This InSpec audit resource has the following special matchers. For a full list of available matchers, please visit our [Universal Matchers page](https://docs.chef.io/inspec/matchers/).

### exists
### Exists

```ruby
# If we expect 'ClusterName' to always exist
describe azure_aks_cluster(resource_group: 'example', name: 'ClusterName') do
describe azure_aks_cluster(resource_group: 'RESOURCE_GROUP', name: 'CLUSTER_NAME') do
it { should exist }
end
```

# If we expect 'ClusterName' to never exist
describe azure_aks_cluster(resource_group: 'example', name: 'ClusterName') do
### Not Exists

```ruby
# If we expect 'ClusterName' to not exist
describe azure_aks_cluster(resource_group: 'RESOURCE_GROUP', name: 'CLUSTER_NAME') do
it { should_not exist }
end
```
Expand Down
22 changes: 13 additions & 9 deletions docs-chef-io/content/inspec/resources/azure_aks_clusters.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ Use the `azure_aks_clusters` InSpec audit resource to test properties and config

## Syntax

An `azure_aks_clusters` resource block returns all AKS Clusters, either within a Resource Group (if provided), or within an entire Subscription.
An `azure_aks_clusters` resource block returns all AKS Clusters, either within a resource group (if provided) or an entire subscription.

```ruby
describe azure_aks_clusters do
Expand All @@ -33,7 +33,7 @@ end
or

```ruby
describe azure_aks_clusters(resource_group: 'my-rg') do
describe azure_aks_clusters(resource_group: 'RESOURCE_GROUP') do
#...
end
```
Expand All @@ -47,7 +47,7 @@ end
## Properties

`ids`
: A list of the unique resource ids.
: A list of the unique resource IDs.

: **Field**: `id`

Expand Down Expand Up @@ -78,27 +78,31 @@ end
**Test that an Example Resource Group has the Named AKS Cluster.**

```ruby
describe azure_aks_clusters(resource_group: 'ExampleGroup') do
its('names') { should include('ClusterName') }
describe azure_aks_clusters(resource_group: 'RESOURCE_GROUP') do
its('names') { should include('CLUSTER_NAME') }
end
```

## Matchers

{{% inspec_matchers_link %}}

### exists
### Exists
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
### Exists
### exists


The control will pass if the filter returns at least one result. Use `should_not` if you expect zero matches.
The control passes if the filter returns at least one result. Use `should_not` if you expect zero matches.

```ruby
# If we expect 'ExampleGroup' Resource Group to have AKS Clusters
describe azure_aks_clusters(resource_group: 'ExampleGroup') do
describe azure_aks_clusters(resource_group: 'RESOURCE_GROUP') do
it { should exist }
end
```

### Not Exists

```ruby
# If we expect 'EmptyExampleGroup' Resource Group to not have AKS Clusters
describe azure_aks_clusters(resource_group: 'EmptyExampleGroup') do
describe azure_aks_clusters(resource_group: 'EMPTY_RESOURCE_GROUP') do
it { should_not exist }
end
```
Expand Down
Loading