Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/sethvargo/terraform-provider-filesystem
A @HashiCorp Terraform provider for interacting with the filesystem
https://github.com/sethvargo/terraform-provider-filesystem
hashicorp terraform terraform-provider
Last synced: about 1 month ago
JSON representation
A @HashiCorp Terraform provider for interacting with the filesystem
- Host: GitHub
- URL: https://github.com/sethvargo/terraform-provider-filesystem
- Owner: sethvargo
- License: apache-2.0
- Created: 2018-05-08T21:13:16.000Z (over 6 years ago)
- Default Branch: main
- Last Pushed: 2024-04-19T15:16:01.000Z (8 months ago)
- Last Synced: 2024-10-29T16:44:42.435Z (about 1 month ago)
- Topics: hashicorp, terraform, terraform-provider
- Language: Go
- Size: 8.6 MB
- Stars: 61
- Watchers: 5
- Forks: 9
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome - terraform-provider-filesystem - A @HashiCorp Terraform provider for interacting with the filesystem (Go)
README
# Terraform FileSystem Provider
This is a [Terraform][terraform] provider for managing the local filesystem with
Terraform. It enables you to treat "files as code" the same way you already
treat infrastructure as code!
## Installation
1. Download the latest compiled binary from [GitHub releases][releases].
1. Untar the archive.
1. Move it into `$HOME/.terraform.d/plugins`:
```sh
$ mkdir -p $HOME/.terraform.d/plugins
$ mv terraform-provider-filesystem $HOME/.terraform.d/plugins/terraform-provider-filesystem
```
1. Create your Terraform configurations as normal, and run `terraform init`:
```sh
$ terraform init
```
This will find the plugin locally.
## Usage
1. Create a Terraform configuration file:
```hcl
resource "filesystem_file_writer" "example" {
path = "file.txt"
contents = "hello world"
}
resource "filesystem_file_reader" "example" {
path = "${filesystem_file_writer.example.path}"
}
```
1. Run `terraform init` to pull in the provider:
```sh
$ terraform init
```
1. Run `terraform plan` and `terraform apply` to interact with the filesystem:
```sh
$ terraform plan
$ terraform apply
```
## Examples
For more examples, please see the [examples][examples] folder in this
repository.
## Reference
### Filesystem Reader
#### Usage
```hcl
resource "filesystem_file_reader" "read" {
path = "my-file.txt"
}
```
#### Arguments
Arguments are provided as inputs to the resource, in the `*.tf` file.
- `path` `(string, required)` - the path to the file on disk.
- `root` `(string: $CWD)` - the root of the Terraform configurations. By
default, this will be the current working directory. If you're running
Terraform against configurations outside of the working directory (like
`terraform apply ../../foo`), set this value to `${path.module}`.
#### Attributes
Attributes are values that are only known after creation.
- `contents` `(string)` - the contents of the file as a string. Contents are
converted to a string, so it is not recommended you use this resource on
binary files.
- `name` `(string)` - the name of the file.
- `size` `(int)` - the size of the file in bytes.
- `mode` `(int)` - the permissions on the file in octal.
### Filesystem Writer
#### Usage
```hcl
resource "filesystem_file_writer" "write" {
path = "my-file.txt"
contents = "hello world!"
}
```
#### Arguments
- `path` `(string, required)` - the path to the file on disk.
- `contents` `(string, required)` - the contents of the file as a string.
- `root` `(string: $CWD)` - the root of the Terraform configurations. By
default, this will be the current working directory. If you're running
Terraform against configurations outside of the working directory (like
`terraform apply ../../foo`), set this value to `${path.module}`.
- `create_parent_dirs` `(bool: true)` - create parent directories if they do not
exist. By default, this is true. If set to false, the parent directories of
the file must exist or this resource will error.
- `delete_on_destroy` `(bool: true)` - delete this file on destroy. Set this to
false and Terraform will leave the file on disk on `terraform destroy`.
- `mode` `(int)` - the permissions on the file in octal.
#### Attributes
- `name` `(string)` - the name of the file.
- `size` `(int)` - the size of the file in bytes.
## FAQ
**Q: How is this different than the built-in `${file()}` function?**
A: The built-in `file` function resolves paths and files at compile time. This
means the file must exist before Terraform can begin executing. In some
situations, the Terraform run itself may create files, but they will not exist
at start time. This Terraform provider enables you to treat files just like
other cloud resources, resolving them at runtime. This allows you to read and
write files from other sources without worrying about dependency ordering.
**Q: How is this different than [terraform-provider-local][terraform-provider-local]?**
A: There are quite a few differences:
1. The equivalent "reader" is a data source. Data sources are resolved before
resources run, meaning it is not possible to use the data source to read a file
that is created _during_ the terraform run. Terraform will fail early that it
could not read the file. This provider specifically addresses that challenge by
using a resource instead of a data source.
1. The equivalent "reader" does not expose all the fields of the stat file (like
mode and owner permissions).
1. The equivalent "writer" does not allow setting file permissions, controlling
parent directory creation, or controlling deletion behavior. Additionally, as a
**super ultra bad thing**, the file permissions are written as 0777 (globally
executable), leaving a large security loophole.
1. The equivalent "writer" does not use an atomic file write. For large file
chunks, this can result in a partially committed file and/or improper
permissions that compromise security.
1. Neither the equivalent "reader" nor the "writer" limit the size of the file
being read/written. This poses a security threat as an attacker could overflow
the process (think about Terraform running arbitrary configuration as a hosted
service).
1. The terraform-provider-local stores the full path of the file in the state,
rendering the configurations un-portable. This provider calculates the filepath
relative to the Terraform module, allowing for more flexibility.
**Q: Is it secure?**
A: The contents of files written and read are stored **in plain text** in the
statefile. They are marked as sensitive in the output, but they will still be
stored in the state. This is required in order for other resources to be able to
read the values. If you are using these resources with sensitive data, you
should encrypt your state using [remote state][remote-state].
## License & Author
```
Copyright 2018 Google, Inc.
Copyright 2018 Seth Vargo
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
```
[terraform]: https://www.terraform.io/
[releases]: https://github.com/sethvargo/terraform-provider-filesystem/releases
[examples]: https://github.com/sethvargo/terraform-provider-filesystem/tree/master/examples
[remote-state]: https://www.terraform.io/docs/state/remote.html
[terraform-provider-local]: https://github.com/terraform-providers/terraform-provider-local