<commit_before>---
layout: default
nav_order: 6
---

# Upgrading Configs
{: .no_toc }

Occasionally, there are changes made to Ignition's configuration that break backward compatibility. While this is not a concern for running machines (since Ignition only runs one time during first boot), it is a concern for those who maintain configuration files. This document serves to detail each of the breaking changes and tries to provide some reasoning for the change. This does not cover all of the changes to the spec - just those that need to be considered when migrating from one version to the next.

1. TOC
{:toc}

## From Version 3.2.0 to 3.3.0

There are not any breaking changes between versions 3.2.0 and 3.3.0 of the configuration specification. Any valid 3.2.0 configuration can be updated to a 3.3.0 configuration by simply changing the version string in the config.

The following is a list of notable new features, deprecations, and changes.

### Kernel arguments

The config gained a new top-level `kernelArguments` section. It allows specifying arguments that should be included or excluded from the kernel command line.

<!-- ignition -->
```json
{
  "ignition": { "version": "3.3.0" },
  "kernelArguments": {
    "shouldExist": [
      "foobar",
      "baz boo"
    ],
    "shouldNotExist": [
      "raboof"
    ]
  }
}
```

The config above will ensure that the kernel argument `foobar` is present, and the kernel argument `raboof` is absent. It will also ensure that the kernel arguments `baz boo` are present exactly in that order.

This feature requires integration with the distribution where Ignition is used. See the [distributor notes][distributor-notes] for details.

### New special filesystem format 'none'

The `format` field of the `filesystems` section can now also be set to `none`. This allows skipping the creation of any filesystem (if `wipeFilesystem` is true), or triggering an error if there are any filesystem (if `wipeFilesystem` is false).

<!-- ignition -->
```json
{
  "ignition": { "version": "3.3.0" },
  "storage": {
    "filesystems": [{
      "device": "/dev/vdb1",
      "wipeFilesystem": true,
      "format": "none"
    }]
  }
}
```

See the [operator notes][operator-notes] for more details.

## From Version 3.1.0 to 3.2.0

There are not any breaking changes between versions 3.1.0 and 3.2.0 of the configuration specification. Any valid 3.1.0 configuration can be updated to a 3.2.0 configuration by simply changing the version string in the config.

The following is a list of notable new features, deprecations, and changes.

### Partition resizing

The `partition` section gained a new `resize` field. When true, Ignition will resize an existing partition if it matches the config in all respects except the partition size.

<!-- ignition -->
```json
{
  "ignition": { "version": "3.2.0" },
  "storage": {
    "disks": [{
      "device": "/dev/sda",
      "partitions": [{
        "label": "root",
        "sizeMiB": 16384,<commit_msg>docs/migrating-configs: wording updates for filesystem format `none`<commit_after>---
layout: default
nav_order: 6
---

# Upgrading Configs
{: .no_toc }

Occasionally, there are changes made to Ignition's configuration that break backward compatibility. While this is not a concern for running machines (since Ignition only runs one time during first boot), it is a concern for those who maintain configuration files. This document serves to detail each of the breaking changes and tries to provide some reasoning for the change. This does not cover all of the changes to the spec - just those that need to be considered when migrating from one version to the next.

1. TOC
{:toc}

## From Version 3.2.0 to 3.3.0

There are not any breaking changes between versions 3.2.0 and 3.3.0 of the configuration specification. Any valid 3.2.0 configuration can be updated to a 3.3.0 configuration by simply changing the version string in the config.

The following is a list of notable new features, deprecations, and changes.

### Kernel arguments

The config gained a new top-level `kernelArguments` section. It allows specifying arguments that should be included or excluded from the kernel command line.

<!-- ignition -->
```json
{
  "ignition": { "version": "3.3.0" },
  "kernelArguments": {
    "shouldExist": [
      "foobar",
      "baz boo"
    ],
    "shouldNotExist": [
      "raboof"
    ]
  }
}
```

The config above will ensure that the kernel argument `foobar` is present, and the kernel argument `raboof` is absent. It will also ensure that the kernel arguments `baz boo` are present exactly in that order.

This feature requires integration with the distribution where Ignition is used. See the [distributor notes][distributor-notes] for details.

### New filesystem format `none`

The `format` field of the `filesystems` section can now be set to `none`. This setting erases an existing filesystem signature without creating a new filesystem (if `wipeFilesystem` is true), or fails if there is any existing filesystem (if `wipeFilesystem` is false).

<!-- ignition -->
```json
{
  "ignition": { "version": "3.3.0" },
  "storage": {
    "filesystems": [{
      "device": "/dev/vdb1",
      "wipeFilesystem": true,
      "format": "none"
    }]
  }
}
```

Refer to the [filesystem reuse semantics](operator-notes.md#filesystem-reuse-semantics) for more information.

## From Version 3.1.0 to 3.2.0

There are not any breaking changes between versions 3.1.0 and 3.2.0 of the configuration specification. Any valid 3.1.0 configuration can be updated to a 3.2.0 configuration by simply changing the version string in the config.

The following is a list of notable new features, deprecations, and changes.

### Partition resizing

The `partition` section gained a new `resize` field. When true, Ignition will resize an existing partition if it matches the config in all respects except the partition size.

<!-- ignition -->
```json
{
  "ignition": { "version": "3.2.0" },
  "storage": {
    "disks": [{
      "device": "/dev/sda",
      "partitions": [{
        "label": "root",
        "sizeMiB": 16384,
{'fraction_non_alphanumeric': 0.09790095113151853, 'fraction_numerical': 0.017382748442112166, 'mean_word_length': 3.6664116296863045, 'pattern_counts': {'":': 40, '<': 9, '<?xml version=': 0, '>': 9, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1971512', 'n_tokens_mistral': 1780, 'n_tokens_neox': 1663, 'n_words': 802}