mirror of
https://github.com/inspec/inspec
synced 2025-02-17 06:28:40 +00:00
Update related docs
Signed-off-by: Clinton Wolfe <clintoncwolfe@gmail.com>
This commit is contained in:
Clinton Wolfe
parent
35b27ee109
commit
aecd11b45c
2 changed files with 13 additions and 164 deletions
|
|
@ -108,11 +108,7 @@ _be >=_ is an [operator matcher](#operator matcher). It allows you to perform nu
|
|||
|
||||
### attribute
|
||||
|
||||
An _attribute_ is a parameter that Chef InSpec reads from a YAML file provided on the command line. You can use this feature either to change a [profile's](#profile) behavior by passing different attribute files or to store secrets that should not be directly present in a profile. Chef InSpec attributes are unrelated to Chef attributes.
|
||||
|
||||
The CLI syntax for attributes is documented under the [`inspec exec`](https://www.inspec.io/docs/reference/cli/#exec) command.
|
||||
|
||||
The syntax for accessing attributes within a profile is documented in the [profiles documentation](https://www.inspec.io/docs/reference/profiles/#profile-attributes).
|
||||
Deprecated name for [input](#input).
|
||||
|
||||
### control
|
||||
|
||||
|
|
@ -204,6 +200,16 @@ describe cars.where { engine_cylinders >= 6 } do
|
|||
end
|
||||
```
|
||||
|
||||
### input
|
||||
|
||||
An _input_ is a value that Chef InSpec can source from a number of providers, including from the command line, profile metadata, or withing the control file DSL itself. You can use this feature either to change a [profile's](#profile) behavior by passing different attribute files or to store secrets that should not be directly present in a profile.
|
||||
|
||||
Inputs were formerly known as `attributes`. Chef InSpec Inputs are unrelated to Chef attributes.
|
||||
|
||||
The CLI syntax for inputs is documented under the [`inspec exec`](https://www.inspec.io/docs/reference/cli/#exec) command.
|
||||
|
||||
Inputs are documented in detail in the [input documentation](/docs/reference/inputs/).
|
||||
|
||||
### it
|
||||
|
||||
Within a [describe block](#describe), _`it`_ declares an individual [test](#test) directly against the [resource](#resource) (as opposed to testing against one of the resource's [properties](#property), as [its](#its) does). Though it is possible to use [universal matchers](#universal-matcher) with `it`, it is much more typical to use [resource-specific matchers](#resource-specific-matchers).
|
||||
|
|
|
|||
161
docs/profiles.md
161
docs/profiles.md
|
|
@ -335,166 +335,9 @@ require_resource(profile: 'my_dep', resource: 'my_res',
|
|||
This will allow you to reference the resource `my_res` from the
|
||||
profile `my_dep` using the name `my_res2`.
|
||||
|
||||
# Profile Attributes
|
||||
# Profile Inputs
|
||||
|
||||
Attributes are frequently used to parameterize a profile for use in different environments or targets. It can also be used define secrets, such as user names and passwords, that should not otherwise be stored in plain-text in a cookbook. Attributes may be set for the whole profile in the `inspec.yml`.
|
||||
|
||||
Attributes may contain the following options:
|
||||
|
||||
* Use `value` to set a value for the attribute.
|
||||
* Use `type` to restrict an attribute to a specific type (any, string, numeric, array, hash, boolean, regex).
|
||||
* Use `required` to mandate the attribute has a value at the time of evaluation.
|
||||
* Use `description` to set a brief description for the attribute.
|
||||
|
||||
|
||||
## Setting Attributes in the Profile Metadata File
|
||||
|
||||
You can specify attributes in your `inspec.yml` using the `attributes` setting. For example, to add a `user` attribute for your profile:
|
||||
|
||||
```YAML
|
||||
attributes:
|
||||
- name: user
|
||||
type: string
|
||||
value: bob
|
||||
```
|
||||
|
||||
Example of adding a array object of servers:
|
||||
|
||||
```YAML
|
||||
attributes:
|
||||
- name: servers
|
||||
type: array
|
||||
value:
|
||||
- server1
|
||||
- server2
|
||||
- server3
|
||||
```
|
||||
|
||||
To access an attribute you will use the `attribute` keyword. You can use this anywhere in your control code.
|
||||
|
||||
For example:
|
||||
|
||||
```Ruby
|
||||
current_user = attribute('user')
|
||||
|
||||
control 'system-users' do
|
||||
describe attribute('user') do
|
||||
it { should eq 'bob' }
|
||||
end
|
||||
|
||||
describe current_user do
|
||||
it { should eq attribute('user') }
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
## Setting Attributes in an External YAML Attributes File
|
||||
|
||||
For sensitive data it is recommended to use a YAML file located on the local machine to populate the values of attributes. To read values from a YAML file, use run `inspec exec` and specify the path to that YAML file using the `--attrs` attribute.
|
||||
|
||||
For example, your profile's metadata file, inspec.yml:
|
||||
|
||||
```YAML
|
||||
attributes:
|
||||
- name: username
|
||||
type: string
|
||||
required: true
|
||||
- name: password
|
||||
type: string
|
||||
required: true
|
||||
```
|
||||
|
||||
The control:
|
||||
|
||||
```Ruby
|
||||
control 'system-users' do
|
||||
impact 0.8
|
||||
desc '
|
||||
This test assures that the user "Bob" has a user installed on the system, along with a
|
||||
specified password.
|
||||
'
|
||||
|
||||
describe attribute('username') do
|
||||
it { should eq 'bob' }
|
||||
end
|
||||
|
||||
describe attribute('password') do
|
||||
it { should eq 'secret' }
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
And a YAML file named `profile-attribute.yml`:
|
||||
|
||||
```YAML
|
||||
username: bob
|
||||
password: secret
|
||||
```
|
||||
|
||||
The following command runs the tests and applies the secrets specified in `profile-attribute.yml`:
|
||||
|
||||
```bash
|
||||
$ inspec exec examples/profile-attribute --attrs examples/profile-attribute.yml
|
||||
```
|
||||
|
||||
To change your attributes for platform specific cases you can setup multiple `--attrs` files.
|
||||
|
||||
For example, a inspec.yml:
|
||||
|
||||
```YAML
|
||||
attributes:
|
||||
- name: users
|
||||
type: array
|
||||
required: true
|
||||
```
|
||||
|
||||
A YAML file named `windows.yml`
|
||||
|
||||
```YAML
|
||||
users:
|
||||
- Administrator
|
||||
- Guest
|
||||
- Randy
|
||||
```
|
||||
|
||||
A YAML file named `linux.yml`
|
||||
|
||||
```YAML
|
||||
users:
|
||||
- root
|
||||
- shadow
|
||||
- rmadison
|
||||
```
|
||||
|
||||
The control file:
|
||||
|
||||
```RUBY
|
||||
control 'system-users' do
|
||||
impact 0.8
|
||||
desc 'Confirm the proper users are created on the system'
|
||||
|
||||
describe users do
|
||||
its('usernames') { should eq attribute('users') }
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
The following command runs the tests and applies the attributes specified:
|
||||
|
||||
```bash
|
||||
$ inspec exec examples/profile-attribute --attrs examples/windows.yml
|
||||
$ inspec exec examples/profile-attribute --attrs examples/linux.yml
|
||||
```
|
||||
|
||||
See the full example in the Chef InSpec open source repository: [Example Chef InSpec Profile with Attributes](https://github.com/chef/inspec/tree/master/examples/profile-attribute)
|
||||
|
||||
## Attribute Value Precedence
|
||||
|
||||
Attribute values are always set in the following precedence (highest to lowest):
|
||||
|
||||
1. Values from a file specified on the command line using --attrs
|
||||
2. Values from a profile metadata file - an inspec.yml with an `attributes:` section
|
||||
3. Values provided directly in control code - `attribute('user', value: 'bob')`
|
||||
Our documentation on [Inputs](docs/reference/inputs/) is now on a dedicated page.
|
||||
|
||||
# Profile files
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue