357f7c70a7
* feat(nodes): Initial support to manage APT repositories
> Summary
This commit implements initial support for managing APT repositories
which is (currently) limited to…
- …adding "standard" repositories to allow to configure it.
- toggling the activation status (enabled/disabled) of any configured
repository.
+ !WARNING!
+ Note that deleting or modifying a repository in any other way is
+ (sadly) not possible (yet?)!
+ The limited functionality is due to the (current) capabilities of
+ the Proxmox VE APT repository API [1] itself.
>> Why are there two resources for one API entity?
Even though an APT repository should be seen as a single API entity, it
was required to implement standard repositories as dedicated
`proxmox_virtual_environment_apt_standard_repository`. This is because
standard repositories must be configured (added) first to the default
source list files because their activation status can be toggled. This
is handled by the HTTP `PUT` request, but the modifying request is
`POST` which would require two calls within the same Terraform execution
cycle. I tried to implement it in a single resource and it worked out
mostly after some handling some edges cases, but in the end there were
still too many situations an edge cases where it might break due to
Terraform state drifts between states. In the end the dedicated
resources are way cleaner and easier to use without no complexity and
conditional attribute juggling for practitioners.
>> Other "specialties"
Unfortunately the Proxmox VE API responses to HTTP `GET` requests with
four larger arrays which are, more or less, kind of connected to each
other, but they also somehow stand on their own. This means that there
is a `files` array that contains the `repositories` again which again
contains all repositories with their metadata of every source file. On
the other hand available standard repositories are listed in the
`standard-repos` array, but their activation status is only stored when
they have already been added through a `PUT` request. The `infos` array
is more less useless.
So in order to get the required data and store them in the state the
`importFromAPI` methods of the models must loop through all the
deep-nested arrays and act based on specific attributes like a matching
file path, comparing it to the activation status and so on.
In the end the implementation is really stable after testing it with all
possible conditions and state combinations.
@bpg if you'd like me to create a small data logic flow chart to make it
easier to understand some parts of the code let me know. I can make my
local notes "shareable" which I created to not loose track of the logic.
>> What is the way to manage the activation status of a "standard" repository?
Because the two resources are modular and scoped they can be simply
combined to manage an APT "standard" repository, e.g. toggling its
activation status. The following examples are also included in the
documentations.
```hcl
// This resource ensure that the "no-subscription" standard repository
// is added to the source list.
// It represents the `PUT` API request.
resource "proxmox_virtual_environment_apt_standard_repository" "example" {
handle = "no-subscription"
node = "pve"
}
// This resource allows to actually modify the activation status of the
// standard repository as it represents the `POST`.
// Using the values from the dedicated standard repository resource
// makes sure that Terraform correctly resolves dependency order.
resource "proxmox_virtual_environment_apt_repository" "example" {
enabled = true
file_path = proxmox_virtual_environment_apt_standard_repository.example.file_path
index = proxmox_virtual_environment_apt_standard_repository.example.index
node = proxmox_virtual_environment_apt_standard_repository.example.node
}
```
[1]: https://pve.proxmox.com/pve-docs/api-viewer/#/nodes/{node}/apt/repositories
---------
Signed-off-by: Sven Greb <development@svengreb.de>
Signed-off-by: Pavel Boldyrev <627562+bpg@users.noreply.github.com>
Co-authored-by: Pavel Boldyrev <627562+bpg@users.noreply.github.com>
|
||
|---|---|---|
| .devcontainer | ||
| .github | ||
| .vscode | ||
| docs | ||
| example | ||
| examples | ||
| fwprovider | ||
| proxmox | ||
| proxmoxtf | ||
| templates | ||
| tools | ||
| utils | ||
| .all-contributorsrc | ||
| .gitignore | ||
| .golangci.yml | ||
| .goreleaser.yaml | ||
| .lycheeignore | ||
| .markdownlint.json | ||
| .markdownlintignore | ||
| .mergify.yml | ||
| .release-please-manifest.json | ||
| CHANGELOG.md | ||
| CODE_OF_CONDUCT.md | ||
| CONTRIBUTING.md | ||
| CONTRIBUTORS.md | ||
| example.tfrc | ||
| go.mod | ||
| go.sum | ||
| HISTORY.md | ||
| LICENSE | ||
| main.go | ||
| Makefile | ||
| qodana.yaml | ||
| README.md | ||
| release-please-config.json | ||
| terraform-registry-manifest.json | ||
| testacc | ||
Terraform Provider for Proxmox
A Terraform / OpenTofu Provider which adds support for Proxmox solutions.
This repository is a fork of https://github.com/danitso/terraform-provider-proxmox which is no longer maintained.
Compatibility promise
This provider is compatible with the latest version of Proxmox VE (currently 8.2). While it may work with older 7.x versions, it is not guaranteed to do so.
While provider is on version 0.x, it is not guaranteed to be backwards compatible with all previous minor versions. However, we will try to keep the backwards compatibility between provider versions as much as possible.
Requirements
- Proxmox Virtual Environment 8.x
- TLS 1.3 for the Proxmox API endpoint (legacy TLS 1.2 is optionally supported)
- Terraform 1.5.x+ or OpenTofu 1.6.x
- Go 1.22 (to build the provider plugin)
Using the provider
You can find the latest release and its documentation in the Terraform Registry.
Testing the provider
In order to test the provider, you can simply run make test.
make test
Tests are limited to regression tests, ensuring backwards compatibility.
A limited number of acceptance tests are available in the proxmoxtf/test directory, mostly for "new" functionality implemented using the Terraform Provider Framework.
These tests are not run by default, as they require a Proxmox VE environment to be available.
They can be run using make testacc, the Proxmox connection can be configured using environment variables, see provider documentation for details.
Deploying the example resources
There are number of TF examples in the example directory, which can be used to deploy a Container, VM, or other Proxmox resources on your test Proxmox environment.
The following assumptions are made about the test environment:
- It has one node named
pve - The node has local storages named
localandlocal-lvm - The "Snippets" content type is enabled in
localstorage
Create example/terraform.tfvars with the following variables:
virtual_environment_username = "root@pam"
virtual_environment_password = "put-your-password-here"
virtual_environment_endpoint = "https://<your-cluster-endpoint>:8006/"
Then run make example to deploy the example resources.
If you don't have free proxmox cluster to play with, there is dedicated how-to tutorial how to setup Proxmox inside VM and run make example on it.
Future work
The provider is using the Terraform SDKv2, which is considered legacy and is in maintenance mode. The work has started to migrate the provider to the new Terraform Plugin Framework, with aim to release it as a new major version 1.0.
Known issues
Disk images cannot be imported by non-PAM accounts
Due to limitations in the Proxmox VE API, certain actions need to be performed using SSH. This requires the use of a PAM account (standard Linux account).
Disk images from VMware cannot be uploaded or imported
Proxmox VE is not currently supporting VMware disk images directly. However, you can still use them as disk images by using this workaround:
resource "proxmox_virtual_environment_file" "vmdk_disk_image" {
content_type = "iso"
datastore_id = "datastore-id"
node_name = "node-name"
source_file {
# We must override the file extension to bypass the validation code
# in the Proxmox VE API.
file_name = "vmdk-file-name.img"
path = "path-to-vmdk-file"
}
}
resource "proxmox_virtual_environment_vm" "example" {
//...
disk {
datastore_id = "datastore-id"
# We must tell the provider that the file format is vmdk instead of qcow2.
file_format = "vmdk"
file_id = "${proxmox_virtual_environment_file.vmdk_disk_image.id}"
}
//...
}
Snippets cannot be uploaded by non-PAM accounts
Due to limitations in the Proxmox VE API, certain files (snippets, backups) need to be uploaded using SFTP. This requires the use of a PAM account (standard Linux account).
Cluster hardware mappings cannot be created by non-PAM accounts
Due to limitations in the Proxmox VE API, cluster hardware mappings must be created using the root PAM account (standard Linux account) due to IOMMU interactions.
Hardware mappings allow to use PCI "passthrough" and map physical USB ports.
Contributors
See CONTRIBUTORS.md for a list of contributors to this project.
Repository Metrics
Sponsorship
❤️ This project is sponsored by:
Thanks again for your continuous support, it is much appreciated! 🙏
Acknowledgements
This project has been developed with GoLand IDE under the JetBrains Open Source license, generously provided by JetBrains s.r.o.
