Skip to content

Commit cc2c1e3

Browse files
Vasu1105Vasu1105
authored
Merge pull request #96 from inspec/im/update_resource_docs
Reorganize resource docs
2 parents bfd542d + 02d4367 commit cc2c1e3

File tree

6 files changed

+187
-88
lines changed

6 files changed

+187
-88
lines changed

‎docs-chef-io/content/_index.md‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
+++
2+
title = "About the Chef InSpec Habitat resource pack"
3+
4+
draft = false
5+
6+
linkTitle = "Habitat resource pack"
7+
summary = "Chef InSpec resources for auditing Habitat packages and services."
8+
9+
[cascade]
10+
[cascade.params]
11+
platform = "habitat"
12+
13+
[menu.habitat]
14+
title = "About Habitat resources"
15+
identifier = "inspec/resources/habitat/About"
16+
parent = "inspec/resources/habitat"
17+
weight = 10
18+
+++
19+
20+
The Chef InSpec Habitat resources allow you to audit and test Chef Habitat packages and services in your infrastructure. You can verify package installations, check service configurations, and validate the operational state of your Habitat-managed applications.
21+
22+
{{< note >}}
23+
24+
This resource pack is in the early stages of development. Functionality may be defective, incomplete, or be withdrawn in the future. If you are interested in helping this project mature, please join the conversation or contribute code at the [inspec-habitat project](https://github.com/inspec/inspec-habitat).
25+
26+
{{< /note >}}
27+
28+
## Prerequisites
29+
30+
- Chef InSpec v4.7.3 or later
31+
- A running Habitat Supervisor that you can access using SSH, the HTTP API, or (ideally) both.
32+
33+
## Connecting to Habitat
34+
35+
The `inspec-habitat` resources connect to Habitat using two methods:
36+
37+
- **SSH connection with `hab` CLI**: Required for package information and some service data
38+
- **HTTP API connection**: Provides access to the Habitat Supervisor API for real-time service status
39+
40+
For the most comprehensive testing capabilities, configure both connection methods. If only one method is available, InSpec will use the available connection and skip tests that require the unavailable method.
41+
42+
### Configure Habitat connections
43+
44+
Configure your Habitat connections in the [InSpec configuration file](https://docs.chef.io/inspec/config/) at `~/.inspec/config.json`. You can create multiple connection profiles for different environments (for example, development, staging, and production).
45+
46+
Use the following format in your configuration file:
47+
48+
```json
49+
{
50+
"file_version": "1.1",
51+
"credentials": {
52+
"habitat": {
53+
"<CONFIG_NAME>": {
54+
"api_url": "http://dev-hab.example.com",
55+
"api_auth_token": "<TOKEN>",
56+
"cli_ssh_host": "dev-hab.example.com",
57+
"cli_ssh_user": "username",
58+
"cli_ssh_key_files": "~/.ssh/KEYNAME"
59+
}
60+
}
61+
}
62+
}
63+
```
64+
65+
Habitat Supervisor API options:
66+
67+
`api_url`
68+
: The URL to the Habitat Supervisor API. InSpec defaults to port 9631 if a port isn't specified.
69+
70+
`api_auth_token`
71+
: The bearer token for API authentication. This is required only if your Habitat Supervisor is configured to expect a token.
72+
73+
SSH connection options:
74+
75+
`cli_ssh_host`
76+
: The IP or hostname of the machine to connect to. If omitted, it is assumed that the CLI interface isn't available.
77+
78+
`cli_ssh_user`
79+
: The SSH username. It defaults to the current OS user if a value isn't specified.
80+
81+
`cli_ssh_key_files`
82+
: The SSH key file paths for authentication. This can be a single string or an array of paths.
83+
84+
{{< note >}}
85+
86+
The `train-habitat` driver has many additional connection options. For further details, see the [`train-habitat` documentation](https://github.com/inspec/train-habitat#using-train-habitat-from-ruby).
87+
88+
{{< /note >}}
89+
90+
### Run InSpec profiles against Habitat
91+
92+
Execute your InSpec profiles against Habitat using the `--target` option to specify your configured Habitat connection:
93+
94+
```sh
95+
inspec exec <PROFILE_NAME> --target habitat://<CONFIG_NAME>
96+
```
97+
98+
In this command:
99+
100+
- `habitat://` tells InSpec to use the [train-habitat driver](https://github.com/inspec/train) to connect to Habitat
101+
- `<CONFIG_NAME>` references the connection configuration defined in your InSpec configuration file
102+
103+
For example, to run a profile using a configuration named "production":
104+
105+
```sh
106+
inspec exec profile-name --target habitat://production
107+
```
108+
109+
## Habitat resources
110+
111+
{{< inspec_resources_filter >}}
112+
113+
The following Chef InSpec Habitat resources are available in this resource pack.
114+
115+
{{< inspec_resources section="habitat" platform="habitat" >}}

docs-chef-io/content/inspec/resources/habitat_package.md renamed to docs-chef-io/content/habitat_package.md

Lines changed: 16 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,14 @@
11
+++
22
title = "habitat_package resource"
33
draft = false
4-
platform = "habitat"
54

6-
[menu]
7-
[menu.inspec]
5+
6+
[menu.habitat]
87
title = "habitat_package"
98
identifier = "inspec/resources/habitat/habitat_package.md habitat_package resource"
109
parent = "inspec/resources/habitat"
1110
+++
1211

13-
[\[edit on GitHub\]](https://github.com/inspec/inspec-habitat/blob/master/docs/resources/habitat_package.md)
14-
1512
Use the `habitat_package` InSpec audit resource to test properties of a single Habitat package.
1613

1714
## Availability
@@ -20,10 +17,18 @@ Use the `habitat_package` InSpec audit resource to test properties of a single H
2017

2118
This resource, like all of the inspec-habitat resource pack, is in the early stages of research and development. Functionality may be defective, incomplete, or be withdrawn in the future. If you are interested in helping this project mature, please join the conversation or contribute code at the [inspec-habitat project](https://github.com/inspec/inspec-habitat).
2219

23-
### Connecting to Habitat
20+
### Connect to Habitat
2421

2522
To configure `inspec` to be able to communicate with Chef Habitat, be sure [to follow the instructions](https://github.com/inspec/inspec-habitat#configuring-inspec-to-reach-habitat) regarding configuring the connection options. This will prevent 'unsupported platform' errors.
2623

24+
### Installation
25+
26+
This resource is in the `inspec-habitat` resource pack. You can use the resource by setting an InSpec profile dependency on this resource pack. See [inspec-habitat instructions](https://github.com/inspec/inspec-habitat#installation)
27+
28+
### Version
29+
30+
This resource was first available in version 0.1.0 of the resource pack.
31+
2732
## Examples
2833

2934
### Check for core/httpd package
@@ -65,19 +70,9 @@ To avoid this possibility, fully specify the resource parameters, including `ver
6570

6671
To list all installed versions and releases of a named package, use the plural resource `habitat_packages`.
6772

68-
## Availability
69-
70-
### Installation
71-
72-
This resource is in the `inspec-habitat` resource pack. You can use the resource by setting an InSpec profile dependency on this resource pack. See [inspec-habitat instructions](https://github.com/inspec/inspec-habitat#installation)
73-
74-
### Version
75-
76-
This resource was first available in version 0.1.0 of the resource pack.
77-
78-
## Resource Parameters
73+
## Resource parameters
7974

80-
Use [resource parameters](/inspec/glossary/#resource-parameter) to identify the particular package you wish to test.
75+
Use [resource parameters](https://docs.chef.io/inspec/glossary/#resource-parameter) to identify the particular package you wish to test.
8176

8277
`habitat_package` can accept a single resource parameter, a `String` package identifier; or it can accept a `Hash` of identifier components.
8378

@@ -143,7 +138,7 @@ end
143138

144139
## Properties
145140

146-
Use [properties](/inspec/glossary/#property) to create tests that compare an expected value to the actual value.
141+
Use [properties](https://docs.chef.io/inspec/glossary/#property) to create tests that compare an expected value to the actual value.
147142

148143
### identifier
149144

@@ -207,8 +202,8 @@ end
207202

208203
## Matchers
209204

210-
Use [matchers](/inspec/glossary/#matcher) to create tests that test a true or false question.
205+
Use [matchers](https://docs.chef.io/inspec/glossary/#matcher) to create tests that test a true or false question.
211206

212-
InSpec includes a number of [universal matchers](/inspec/matchers/). See below for matchers specific to this resource.
207+
InSpec includes a number of [universal matchers](https://docs.chef.io/inspec/matchers/). See below for matchers specific to this resource.
213208

214209
This resource does not provide any resource-specific matchers.

docs-chef-io/content/inspec/resources/habitat_packages.md renamed to docs-chef-io/content/habitat_packages.md

Lines changed: 18 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,14 @@
11
+++
22
title = "habitat_packages resource"
33
draft = false
4-
platform = "habitat"
54

6-
[menu]
7-
[menu.inspec]
5+
6+
[menu.habitat]
87
title = "habitat_packages"
98
identifier = "inspec/resources/habitat/habitat_packages.md habitat_packages resource"
109
parent = "inspec/resources/habitat"
1110
+++
1211

13-
[\[edit on GitHub\]](https://github.com/inspec/inspec-habitat/blob/master/docs/resources/habitat_packages.md)
14-
1512
Use the `habitat_package` (singular) InSpec audit resource to perform in-depth auditing of a single package.
1613

1714
Use the `habitat_packages` (plural) InSpec audit resource to list Habitat packages, and perform bulk operations.
@@ -22,10 +19,18 @@ Use the `habitat_packages` (plural) InSpec audit resource to list Habitat packag
2219

2320
This resource, like all of the inspec-habitat resource pack, is in the early stages of research and development. Functionality may be defective, incomplete, or be withdrawn in the future. If you are interested in helping this project mature, please join the conversation or contribute code at the [inspec-habitat project](https://github.com/inspec/inspec-habitat).
2421

25-
### Connecting to Habitat
22+
### Connect to Habitat
2623

2724
To configure `inspec` to be able to communicate with Chef Habitat, be sure [to follow the instructions](https://github.com/inspec/inspec-habitat#configuring-inspec-to-reach-habitat) regarding configuring the connection options. This will prevent 'unsupported platform' errors.
2825

26+
### Installation
27+
28+
This resource is in the `inspec-habitat` resource pack. You can use this resource by setting an InSpec profile dependency on the resource pack. See [inspec-habitat instructions](https://github.com/inspec/inspec-habitat#installation).
29+
30+
### Version
31+
32+
This resource was first available in version 0.1.0 of the resource pack.
33+
2934
## Examples
3035

3136
### Ensure httpd and memcached are installed
@@ -65,25 +70,15 @@ Habitat exposes certain data via the CLI, and other data via the HTTP Gateway AP
6570

6671
If you use this resource without the CLI, this resource will always return zero matches.
6772

68-
## Availability
69-
70-
### Installation
71-
72-
This resource is in the `inspec-habitat` resource pack. You can use this resource by setting an InSpec profile dependency on the resource pack. See [inspec-habitat instructions](https://github.com/inspec/inspec-habitat#installation).
73-
74-
### Version
75-
76-
This resource was first available in version 0.1.0 of the resource pack.
77-
78-
## Resource Parameters
73+
## Resource parameters
7974

80-
[Resource parameters](/inspec/glossary/#resource-parameter) are arguments passed to the resource in the control code.
75+
[Resource parameters](https://docs.chef.io/inspec/glossary/#resource-parameter) are arguments passed to the resource in the control code.
8176

8277
This resource does not accept resource parameters, which is typical for plural resources.
8378

84-
## Filter Criteria
79+
## Filter criteria
8580

86-
[Filter criteria](/inspec/glossary/#filter-criteria) are used to select which packages you wish to examine. If no filter criteria are used, all packages are selected.
81+
[Filter criteria](https://docs.chef.io/inspec/glossary/#filter-criteria) are used to select which packages you wish to examine. If no filter criteria are used, all packages are selected.
8782

8883
### name
8984

@@ -131,7 +126,7 @@ end
131126

132127
## Properties
133128

134-
Use [properties](/inspec/glossary/#property) to create tests that compare an expected value to the actual value.
129+
Use [properties](https://docs.chef.io/inspec/glossary/#property) to create tests that compare an expected value to the actual value.
135130

136131
### count
137132

@@ -198,8 +193,8 @@ end
198193

199194
## Matchers
200195

201-
Use [matchers](/inspec/glossary/#matcher) to create tests that test a true or false question.
196+
Use [matchers](https://docs.chef.io/inspec/glossary/#matcher) to create tests that test a true or false question.
202197

203-
InSpec includes a number of [universal matchers](/inspec/matchers/).
198+
InSpec includes a number of [universal matchers](https://docs.chef.io/inspec/matchers/).
204199

205200
This resource does not define any resource-specific matchers.

docs-chef-io/content/inspec/resources/habitat_service.md renamed to docs-chef-io/content/habitat_service.md

Lines changed: 16 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,14 @@
11
+++
22
title = "habitat_service resource"
33
draft = false
4-
platform = "habitat"
54

6-
[menu]
7-
[menu.inspec]
5+
6+
[menu.habitat]
87
title = "habitat_service"
98
identifier = "inspec/resources/habitat/habitat_service.md habitat_service resource"
109
parent = "inspec/resources/habitat"
1110
+++
1211

13-
[\[edit on GitHub\]](https://github.com/inspec/inspec-habitat/blob/master/docs/resources/habitat_service.md)
14-
1512
Use the `habitat_service` InSpec audit resource to test properties of a single Habitat service.
1613

1714
## Availability
@@ -20,10 +17,18 @@ Use the `habitat_service` InSpec audit resource to test properties of a single H
2017

2118
This resource, like all of the inspec-habitat resource pack, is in the early stages of research and development. Functionality may be defective, incomplete, or be withdrawn in the future. If you are interested in helping this project mature, please join the conversation or contribute code at the [inspec-habitat project](https://github.com/inspec/inspec-habitat).
2219

23-
### Connecting to Habitat
20+
### Connect to Habitat
2421

2522
To configure `inspec` to be able to communicate with Chef Habitat, be sure [to follow the instructions](https://github.com/inspec/inspec-habitat#configuring-inspec-to-reach-habitat) regarding configuring the connection options. This will prevent 'unsupported platform' errors.
2623

24+
### Installation
25+
26+
This resource is in the `inspec-habitat` resource pack. You can use the resource by setting an InSpec profile dependency on the resource pack. See [inspec-habitat instructions](https://github.com/inspec/inspec-habitat#installation)
27+
28+
### Version
29+
30+
This resource was first available in version 0.1.0 of the resource pack.
31+
2732
## Examples
2833

2934
### Check for core/httpd service
@@ -55,19 +60,9 @@ If the service is not found, then this resource behaves as follows:
5560
- All array and hash-valued properties will return empty objects.
5661
- All matchers will return false.
5762

58-
## Availability
59-
60-
### Installation
61-
62-
This resource is in the `inspec-habitat` resource pack. You can use the resource by setting an InSpec profile dependency on the resource pack. See [inspec-habitat instructions](https://github.com/inspec/inspec-habitat#installation)
63-
64-
### Version
65-
66-
This resource was first available in version 0.1.0 of the resource pack.
67-
68-
## Resource Parameters
63+
## Resource parameters
6964

70-
Use [resource parameters](/inspec/glossary/#resource-parameter) to identify the particular service you wish to test.
65+
Use [resource parameters](https://docs.chef.io/inspec/glossary/#resource-parameter) to identify the particular service you wish to test.
7166

7267
### origin
7368

@@ -99,7 +94,7 @@ end
9994

10095
## Properties
10196

102-
Use [properties](/inspec/glossary/#property) to create tests that compare an expected value to the actual value.
97+
Use [properties](https://docs.chef.io/inspec/glossary/#property) to create tests that compare an expected value to the actual value.
10398

10499
### dependency_names
105100

@@ -179,9 +174,9 @@ end
179174

180175
## Matchers
181176

182-
Use [matchers](/inspec/glossary/#matcher) to create tests that test a true or false question.
177+
Use [matchers](https://docs.chef.io/inspec/glossary/#matcher) to create tests that test a true or false question.
183178

184-
InSpec includes a number of [universal matchers](/inspec/matchers/). See below for matchers specific to this resource.
179+
InSpec includes a number of [universal matchers](https://docs.chef.io/inspec/matchers/). See below for matchers specific to this resource.
185180

186181
### have_standalone_topology
187182

0 commit comments

Comments
 (0)