unsible

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

★ 9 Open GitHub ↗

Opinionated Ansible linter

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Unsible

Unsible (_/ˈʌnzəbəl/_) is, currently, a static analysis tool for Ansible playbooks.

It parses playbooks and statically evaluates templates/conditions where possible.

Unsible tries to be compatible with Ansible, any found incompatibility or divergence is a bug.

## Usage

```bash
# Lint playbooks (structure and rule checks)
unsible lint [--format {fancy,basic,github}] [-c FILE] playbook [playbook ...]

# Evaluate templates against inventory hosts
unsible eval [-i INVENTORY] [-l LIMIT] [-C] [-e FILE] [--format {fancy,basic,github}] [-c FILE] [--strict-templates] playbook [playbook ...]

# Show inventory information
unsible-inventory [-i INVENTORY] [--list] [-l LIMIT]
```

Currently, we have implemented:

- Type-checking for standard modules (`command`, `shell`, `set_fact`, `systemd`, ...)
- Lookup compatibility layer
- Filter compatibility layer

Be aware that filters from expressions **will** be executed during analysis.

If you have a custom filter such as:

```yaml
- set_fact:
    var: "{{ something | destroy_computer }}"
```

the filter **will** be executed. You shouldn't be doing I/O in filters anyway (use an action plugins or lookups instead).

Because lookups are dangerous to execute, you need to whitelist any custom lookups in the config, for them to be evaluated.

## Features

### Undeclared var detection

In a template, such as `{{ undefined_var }}`, if the variable is not

- Host vars
- Group vars
- Marked as `register` in a module
- Marked as `set_fact`

Then it will be considered undefined, and Unsible will reject the template.

The filter `default` and the test `defined` (`undef_var | default(5)`, `undef_var is defined`) are
special-cased to operate on undefined variables.

### Partial evaluation

The main feature of Unsible is its ability to partially evaluate templates, given its ability
to statically prove some branches will be taken.

Examples:

```yaml
- command: ls
  register: runtime_var

- assert:
    that:
      - false
      - runtime_var == 5
```

Upon evaluation of this play, Unsible will reject it, with "Assertion will always fail due to 'False'".

The same partial evaluation is useful in case you have templates where variables are not always defined:

```jinja
{% if var is defined %}
  {{ var }}
{% else %}
  {{ other_var }}
{% endif %}
```

In this case, if `var` is defined, Unsible will **not** check `other_var` at all.

If you want to ensure all variables in your templates are always defined, you can run with `--strict-templates`.

### Loop evaluation

As specialization of partial evaluation, statically-derivable loops are 'unrolled' and evaluated with every option, for example:

```yaml
- template:
    content: "{{ lookup('module', item) }}"
  loop:
    - item1
    - item2
```

This template will be rendered with both `item1` and `item2`.

### Module type safety

Standard modules have type information defined within Unsible, so attempting to access invalid properties will fail:

```yaml
- command: ls
  register: out

- debug: msg={{ out.invalid_field }}
```

This play will be rejected:

```
Invalid field access: out.invalid_field. Module 'command' only returns fields:
    ['changed', 'diff', 'failed', 'msg', 'rc', 'results', 'skipped', 'stderr', 'stderr_lines', 'stdout', 'stdout_lines']
```

### Helpful diagnostics

Diagnostics are a first-class feature, and work both in Jinja and Ansible domains.

```
$ unsible eval -i inventory.ini playbook.yaml

error: Undefined variables: ['nginx_config']
  --> roles/webserver/templates/nginx-proxy-service.xml.j2:4
  |
4 |   <port port="{{ nginx_config.ports.http }}" protocol="tcp"/>
  |                  ^^^^^^^^^^^^ undefined variable
5 |   <port port="{{ nginx_config.ports.https }}" protocol="tcp"/>
  |                  ^^^^^^^^^^^^ undefined variable
6 |   <port port="{{ nginx_config.ports.metrics }}" protocol="tcp"/>
  |                  ^^^^^^^^^^^^ undefined variable
  |
  = note: from this task:
    --> roles/webserver/tasks/main.yml:42
      |
   42 | - name: Deploy nginx proxy config
   43 |   template:
   44 |     dest: "/etc/nginx/sites-available/{{ item }}.conf"
   45 |     src: "nginx-proxy-{{ item }}.xml.j2"
      |           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ this template
      |
  = host: web01
```

### Linting

There are some opinionated lints, emitted as warnings, right now:

- Warn when using `set` inside a template
- Warn when using `vars["some_constant_string"]`

You can control the format of these warnings (and errors) with `--format {fancy,basic,github}`.

## Limitations

### Facts are not available

If your templates, checks, or tasks depend on Ansible facts, they will not be available.

If you want to evaluate playbooks which depend on facts, you can pass extra vars with `-e`, like:

```yaml
ansible_processor_vcpus: 1
ansible_user: root
```

which is also useful if you want to test out your plans with different facts.

### Runtime-derived paths for template files

The main difference is that it will never be able
to evaluate a template where the filename contains a runtime-derived path:

```yaml
- command: ls
  register: cmd

- template:
    src: "a_file_{{ cmd.rc }}.j2"
```

as Unsible does not _actually_ execute the commands while performing checks.

Also, please don't do this.

### Runtime-dependent paths will be checked

If there are runtime-dependent tasks which cannot be statically proven, they will be checked.

For example

```yaml
- command: ls
  register: cmd

- import_role: some_role
  when: cmd.rc == 7
```

The `import_role` task will be assumed possible and checked.

unsible

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README