# terraform-provider-incus

Incus Resource provider for Terraform

## Prerequisites

- [Terraform](http://terraform.io)
- [Incus](https://linuxcontainers.org/incus)

## Installation

This provider is published in the [Terraform Registry](https://registry.terraform.io/providers/lxc/incus).

Follow the official instructions for declaring providers in your Terraform configuration
[here](https://www.terraform.io/docs/configuration/provider-requirements.html).

### Quick Example

Add the following to your Terraform configuration:

```hcl
terraform {
  required_providers {
    incus = {
      source = "lxc/incus"
    }
  }
}
```

### Development

#### Setup

1. Follow these [instructions](https://golang.org/doc/install) to setup a Golang development environment.
2. Checkout the repository `git clone ...`
3. Compile from sources to a development binary:

```shell
cd terraform-provider-incus
go build -v
```

4. Configure Terraform (`~/.terraformrc`) to use the development binary provider:

```shell
$ cat ~/.terraformrc
provider_installation {
  dev_overrides {
    "lxc/incus" = "/home/<REPLACE_ME>/git/terraform-provider-incus"
  }
}
```

#### Formatting

This project uses [`gofumpt`](https://github.com/mvdan/gofumpt) to format the
code, which is a stricter version of `gofmt`.

For your best experience, make sure your editor is configured to run
`gofumpt` on save. Find the installation section in
[`gofumpt`'s README.md](https://github.com/mvdan/gofumpt?tab=readme-ov-file#installation).

#### Static Code Analysis

This project uses [`golangci-lint`](https://golangci-lint.run/) and `terraform fmt`
to perform linting and static code analysis.

To run the linters locally, use:

```shell
make static-analysis
```

If your editor is configured to run `golangci-lint` on save, it is expected to
automatically pick up the configuration from `.golangci.yml`.

#### Generated code

Most of the data sources are generated using the tool located in
`./cmd/generate-datasources`. The generated files have the suffix `_gen.go` as
well as a comment `// Code generated by generate-datasources; DO NOT EDIT.`.
Do not edit these files manually but instead change the respective template in
`./cmd/generate-datasources/tmpl` and the generator if necessary.

The generator tool is controlled by the config file `generate-datasources.yaml`.

If the generator code, the templates of the generator's config file are changed,
the generated files need to be regenerated.

Use the following command to regenerate the data sources:

```shell
make generate
```

For more details about the inner working of the generator tool as well as the
settings in the config file please refer to
[`cmd/generate-datasources/README.md`](cmd/generate-datasources/README.md).

#### Testing

There are two test suites, unit and acceptance. By default the acceptance tests are not run as they require a functional
Incus environment.

##### Unit tests

```shell
make test
```

##### Acceptance tests

```shell
make testacc
# or run an individual test
TESTARGS="-run TestAccImage_basicVM" make testacc
# increase test verbosity. options are trace, debug, info, warn, or error (default)
TF_LOG=info make testacc
```

## Documentation

Full documentation can be found in the [`docs`](docs) directory.

## Known Limitations

Many of the base Incus images don't include an SSH server, therefore terraform
will be unable to execute any `provisioners`. Either use the base ubuntu images
from the `ubuntu` or `ubuntu-daily` or manually prepare a base image that
includes SSH.

## Contributors

Some recognition for great contributors to this project:

- [jgraichen](https://github.com/jgraichen)
- [jtopjian](https://github.com/jtopjian)
- [mjrider](https://github.com/mjrider)
- [sl1pm4t](https://github.com/sl1pm4t)
- [yobert](https://github.com/yobert)
