# knife role

A role is a way to define certain patterns and processes that exist across nodes in an organization as belonging to a single job function. Each role consists of zero (or more) attributes and a run-list. Each node can have zero (or more) roles assigned to it. When a role is run against a node, the configuration details of that node are compared against the attributes of the role, and then the contents of that role’s run-list are applied to the node’s configuration details. When a chef-client runs, it merges its own attributes and run-lists with those contained within each assigned role.

The knife role subcommand is used to manage the roles that are associated with one or more nodes on a Chef server.

Note

To add a role to a node and then build out the run-list for that node, use the knife node sub-command and its `run_list add` argument.

Note

Review the list of common options available to this (and all) knife subcommands and plugins.

## bulk delete

The `bulk delete` argument is used to delete one or more roles that match a pattern defined by a regular expression. The regular expression must be within quotes and not be surrounded by forward slashes (/).

### Syntax

This argument has the following syntax:

    $ knife role bulk delete REGEX

### Options

This command does not have any specific options.

### Examples

The following examples show how to use this knife subcommand:

Bulk delete roles

Use a regular expression to define the pattern used to bulk delete roles:

    $ knife role bulk delete "^[0-9]{3}$"

## create

The `create` argument is used to add a role to the Chef server. Role data is saved as JSON on the Chef server.

### Syntax

This argument has the following syntax:

    $ knife role create ROLE_NAME (options)

### Options

This argument has the following options:

`-d DESCRIPTION`, `--description DESCRIPTION`
  The description of the role. This value will populate the description field for the role on the Chef server.

### Examples

The following examples show how to use this knife subcommand:

Create a role

To add a role named `role1`, enter:

    $ knife role create role1

In the $EDITOR enter the role data in JSON:

    ## sample:
    {
       "name": "role1",
       "default_attributes": {
       },
       "json_class": "Chef::Role",
       "run_list": ['recipe[cookbook_name::recipe_name],
                     role[role_name]'
       ],
       "description": "",
       "chef_type": "role",
       "override_attributes": {
       }
    }

When finished, save it.

## delete

The `delete` argument is used to delete a role from the Chef server.

### Syntax

This argument has the following syntax:

    $ knife role delete ROLE_NAME

### Options

This command does not have any specific options.

### Examples

The following examples show how to use this knife subcommand:

Delete a role

    $ knife role delete devops

Type `Y` to confirm a deletion.

## edit

The `edit` argument is used to edit role details on the Chef server.

### Syntax

This argument has the following syntax:

    $ knife role edit ROLE_NAME

### Options

This command does not have any specific options.

### Examples

The following examples show how to use this knife subcommand:

Edit a role

To edit the data for a role named `role1`, enter:

    $ knife role edit role1

Update the role data in JSON:

    ## sample:
    {
       "name": "role1",
       "default_attributes": {
       },
       "json_class": "Chef::Role",
       "run_list": ['recipe[cookbook_name::recipe_name],
                     role[role_name]'
       ],
       "description": "This is the description for the role1 role.",
       "chef_type": "role",
       "override_attributes": {
       }
    }

When finished, save it.

## from file

The `from file` argument is used to create a role using existing JSON data as a template.

### Syntax

This argument has the following syntax:

    $ knife role from file FILE

### Options

This command does not have any specific options.

### Examples

The following examples show how to use this knife subcommand:

Create a role using JSON data

To view role details based on the values contained in a JSON file:

    $ knife role from file "path to JSON file"

## list

The `list` argument is used to view a list of roles that are currently available on the Chef server.

### Syntax

This argument has the following syntax:

    $ knife role list

### Options

This argument has the following options:

`-w`, `--with-uri`
  Use to show the corresponding URIs.

### Examples

The following examples show how to use this knife subcommand:

View a list of roles

To view a list of roles on the Chef server and display the URI for each role returned, enter:

    $ knife role list -w

## show

The `show` argument is used to view the details of a role.

### Syntax

This argument has the following syntax:

    $ knife role show ROLE_NAME

### Options

This argument has the following options:

`-a ATTR`, `--attribute ATTR`
  The attribute (or attributes) to show.

### Examples

The following examples show how to use this knife subcommand:

Show as JSON data

To view information in JSON format, use the `-F` common option as part of the command like this:

    $ knife role show devops -F json

Other formats available include `text`, `yaml`, and `pp`.

Show as raw JSON data

To view node information in raw JSON, use the `-l` or `--long` option:

    knife node show -l -F json <node_name>

and/or:

    knife node show -l --format=json <node_name>