Version 0.7.0 update (#83)

- added support for "hide links" node resource property, fixes #80
- added external connector data source
- fixed integration test for groups data source
- return error for external connector configuration when device name
  is provided instead of "NAT" or "System Bridge", fixes #81
- updated all package dependencies
- fix CPULimit property for UMS and ExtConn (they are now always NULL
  starting with 2.6.0)
- some cosmetic and test changes
- added a add-to-booted-lab lifecycle test
- formatted codebase w/ gofumpt
- removed cmlclient go.mod local replace and updated cmlclient to 0.0.22 in go.mod
- added / updated docs and ran generate
- bumped go version to 1.21 in the workflows
- added an extconn schema test
- updated gh action components, only run one test suite in parallel

.github/workflows/codeql-analysis.yml

@@ -40,7 +40,7 @@ jobs:
 
     steps:
     - name: Checkout repository
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
 
     # Initializes the CodeQL tools for scanning.
     - name: Initialize CodeQL

.github/workflows/combine-prs-workflow.yml

@@ -31,7 +31,7 @@ jobs:
 
     # Steps represent a sequence of tasks that will be executed as part of the job
     steps:
-      - uses: actions/github-script@v6
+      - uses: actions/github-script@v7
         id: create-combined-pr
         name: Create Combined PR
         with:

.github/workflows/release.yml

@@ -17,17 +17,17 @@ permissions:
 env:
   # Go language version to use for building. This value should also be updated
   # in the testing workflow if changed.
-  GO_VERSION: "1.19"
+  GO_VERSION: "1.21"
 
 jobs:
   goreleaser:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           # Allow goreleaser to access older tag information.
           fetch-depth: 0
-      - uses: actions/setup-go@v4
+      - uses: actions/setup-go@v5
         with:
           go-version: ${{ env.GO_VERSION }}
       # This uses an action (hashicorp/ghaction-import-gpg) that assumes you set your
@@ -36,7 +36,7 @@ jobs:
       # or use an alternative one for key handling.
       - name: Import GPG key
         id: import_gpg
-        uses: crazy-max/ghaction-import-gpg@v5.3.0
+        uses: crazy-max/ghaction-import-gpg@v6.1.0
         with:
           gpg_private_key: ${{ secrets.GPG_PRIVATE_KEY }}
           passphrase: ${{ secrets.GPG_PASSPHRASE }}

.github/workflows/test.yml

@@ -21,7 +21,7 @@ permissions:
 env:
   # Go language version to use for building. This value should also be updated
   # in the release workflow if changed.
-  GO_VERSION: "1.19"
+  GO_VERSION: "1.21"
 
 jobs:
   # Ensure project builds before running testing matrix
@@ -30,20 +30,20 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 5
     steps:
-      - uses: actions/setup-go@v4
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
         with:
           go-version: ${{ env.GO_VERSION }}
-      - uses: actions/checkout@v3
       - run: go mod download
       - run: go build -v .
 
   generate:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/setup-go@v4
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
         with:
           go-version: ${{ env.GO_VERSION }}
-      - uses: actions/checkout@v3
       - run: go generate ./...
       - name: git diff
         run: |
@@ -57,24 +57,31 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 30
     strategy:
+      max-parallel: 1
       fail-fast: false
       matrix:
         # list whatever Terraform versions here you would like to support
+        # jobs run in parallel -- some tests create resources with
+        # specific IDs which must be unique... some test resource randomization
+        # is needed but doesn't exist... Currently only testing w/ 1.6
+        # max-parallel: 1 should fix this!
+        # NOTE: required tests are configured in branch protection!
         terraform:
           # - "1.0.*"
           # - "1.1.*"
           # - "1.3.*"
           - "1.4.*"
+          - "1.6.*"
     steps:
-      - uses: actions/setup-go@v4
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
         with:
           go-version: ${{ env.GO_VERSION }}
-      - uses: hashicorp/setup-terraform@v2
+      - run: go mod download
+      - uses: hashicorp/setup-terraform@v3
         with:
           terraform_version: ${{ matrix.terraform }}
           terraform_wrapper: false
-      - uses: actions/checkout@v3
-      - run: go mod download
 
       - env:
           # for the time being, only do unit tests, below needs to be changed

CHANGELOG.md

@@ -2,6 +2,23 @@
 
 Lists the changes in the provider.
 
+## Version 0.7.0
+
+- added support for "hide links" node resource property, fixes #80
+- added external connector data source
+- fixed integration test for groups data source
+- return error for external connector configuration when device name is provided instead of "NAT" or "System Bridge", fixes #81
+- updated all package dependencies
+- fix CPULimit property for UMS and ExtConn (they are now always NULL starting with 2.6.0)
+- some cosmetic and test changes
+- added a add-to-booted-lab lifecycle test (addresses #75 but can't reproduce)
+- formatted codebase w/ gofumpt
+- removed cmlclient go.mod local replace and updated cmlclient to 0.0.22 in go.mod
+- added / updated docs and ran generate
+- bumped go version to 1.21 in the workflows
+- added an extconn schema test
+- updated gh action components, only run one test suite in parallel
+
 ## Version 0.6.2
 
 - The provider (via gocmlclient) now honors proxy configuration provided via environment variables `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY` (or the lowercase versions thereof). `HTTPS_PROXY` takes precedence over `HTTP_PROXY` for https requests.

README.md

@@ -17,17 +17,23 @@ The current implementation provides:
   - resource `cml2_node` to create, update and destroy nodes in a lab
   - resource `cml2_link` to create, update and destroy links between nodes in a lab
   - resource `cml2_lifecycle` to control the state of a lab (like `STARTED`, `STOPPED`), including staged starting and configuration injection
+  - resource `cml2_group` to create, update and destroy groups
+  - resource `cml2_user` to create, update and destroy users
   - data source `cml2_lab` to retrieve state of an existing lab
   - data source `cml2_node` to retrieve state of an existing node in a lab
-  - data source `cml2_image` to retrieve the available node images from the controller
+  - data source `cml2_images` to retrieve the available node images from the controller
+  - data source `cml2_groups` to retrieve user groups from the controller
+  - data source `cml2_extconn` to retrieve external connector information from the controller
+  - data source `cml2_system` to retrieve system state (ready state, version, ...) from the controller
+  - data source `cml2_users` to retrieve users from the controller
 - Examples (`examples/`) and generated documentation (`docs/`),
 - Miscellaneous meta files.
 
 ## Requirements
 
 - [Terraform](https://www.terraform.io/downloads.html) >= 1.0
-- [Go](https://golang.org/doc/install) >= 1.18
-- [CML2](https://cisco.com/go/cml) >= 2.4.0
+- [Go](https://golang.org/doc/install) >= 1.21
+- [CML2](https://cisco.com/go/cml) >= 2.6.0
 
 ## Building The Provider
 

TODO.md

@@ -4,12 +4,14 @@ As this provider is "work-in-progress", there's still plenty of work to do.
 
 - additional resources and data sources
 - better test coverage(unit/acceptance)
+- figure out if/how <https://github.frangipane.io/> fits this provider
 
 Especially the first bullet requires some discussion in terms of what makes
 sense and what doesn't.
 
 ## Items Done
 
+- added external connector data source
 - added group and user resources and data sources
 - basic acceptance tests
 - documentation (content, consistency)

docs/data-sources/connector.md

@@ -0,0 +1,38 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "cml2_connector Data Source - terraform-provider-cml2"
+subcategory: ""
+description: |-
+  A data source that retrieves external connectors information from the controller.
+---
+
+# cml2_connector (Data Source)
+
+A data source that retrieves external connectors information from the controller.
+
+
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Optional
+
+- `label` (String) A connector label to filter the connector list returned by the controller. Connector labels must be unique, so it's either one group or no group at all if a name filter is provided.
+- `tag` (String) A tag name to filter the groups list returned by the controller. Connector tags can be defined on multiple connectors, a list can be returned.
+
+### Read-Only
+
+- `connectors` (Attributes List) A list of all permission groups available on the controller. (see [below for nested schema](#nestedatt--connectors))
+- `id` (String) A UUID. The presence of the ID attribute is mandated by the framework. The attribute is a random UUID and has no actual significance.
+
+<a id="nestedatt--connectors"></a>
+### Nested Schema for `connectors`
+
+Read-Only:
+
+- `device_name` (String) the actual (Linux network) device name of the external connector.
+- `id` (String) External connector identifier, a UUID.
+- `label` (String) The label of the external connector, like "NAT" or "System Bridge".
+- `protected` (Boolean) Whether the connector is protected, e.g. BPDUs are filtered or not.
+- `snooped` (Boolean) True if the IP address snooper listens on this connector.
+- `tags` (Set of String) The external connector tag set.

docs/data-sources/groups.md

@@ -58,5 +58,3 @@ Read-Only:
 
 - `id` (String) Lab ID (UUID).
 - `permission` (String) Permission.
-
-

docs/data-sources/images.md

@@ -63,5 +63,3 @@ Read-Only:
 - `ram` (Number) Image specific RAM value, can be null
 - `read_only` (Boolean) Is this image definition read only?
 - `schema_version` (String) Version of the image definition schemage
-
-

docs/data-sources/lab.md

@@ -66,5 +66,3 @@ Read-Only:
 - `id` (String) Group ID (UUID).
 - `name` (String) Descriptive group name.
 - `permission` (String) Permission, either `read_only` or `read_write`.
-
-

docs/data-sources/node.md

@@ -48,6 +48,7 @@ Read-Only:
 - `cpu_limit` (Number) CPU limit in %, 20-100. Can be changed until the node is started once. Will require a replace in that case.
 - `cpus` (Number) Number of CPUs. Can be changed until the node is started once. Will require a replace in that case.
 - `data_volume` (Number) Size of data volume, in GB. Can be changed until the node is started once. Will require a replace in that case.
+- `hide_links` (Boolean) If true, links are not shown in the topology. This is a visual cue and does not influence any simulation function.
 - `id` (String) Node ID (UUID).
 - `imagedefinition` (String) Image definition, must match the node type. Can be changed until the node is started once. Will require a replace in that case.
 - `interfaces` (Attributes List) List of interfaces on the node. (see [below for nested schema](#nestedatt--node--interfaces))
@@ -83,5 +84,3 @@ Read-Only:
 
 - `console_key` (String)
 - `device_number` (Number)
-
-

docs/data-sources/system.md

@@ -37,5 +37,3 @@ output "readiness" {
 
 - `id` (String) A UUID. The presence of the ID attribute is mandated by the framework. The attribute is a random UUID and has no actual significance.
 - `version` (String) The system software version.
-
-

docs/data-sources/users.md

@@ -57,5 +57,3 @@ Read-Only:
 - `password` (String, Sensitive) Password of the user.
 - `resource_pool` (String) Resource pool ID, if any.
 - `username` (String) Login name of the user.
-
-

docs/resources/group.md

@@ -76,5 +76,3 @@ Required:
 
 - `id` (String) Lab ID (UUID).
 - `permission` (String) Permission.
-
-

docs/resources/lab.md

@@ -93,5 +93,3 @@ Optional:
 Read-Only:
 
 - `name` (String) Descriptive group name.
-
-

docs/resources/lifecycle.md

@@ -198,6 +198,7 @@ Optional:
 - `cpu_limit` (Number) CPU limit in %, 20-100. Can be changed until the node is started once. Will require a replace in that case.
 - `cpus` (Number) Number of CPUs. Can be changed until the node is started once. Will require a replace in that case.
 - `data_volume` (Number) Size of data volume, in GB. Can be changed until the node is started once. Will require a replace in that case.
+- `hide_links` (Boolean) If true, links are not shown in the topology. This is a visual cue and does not influence any simulation function.
 - `imagedefinition` (String) Image definition, must match the node type. Can be changed until the node is started once. Will require a replace in that case.
 - `ram` (Number) Amount of RAM, megabytes. Can be changed until the node is started once. Will require a replace in that case.
 - `tags` (Set of String) Set of tags of the node.
@@ -234,5 +235,3 @@ Read-Only:
 
 - `console_key` (String)
 - `device_number` (Number)
-
-

docs/resources/link.md

@@ -34,5 +34,3 @@ A link resource represents a CML link. At create time, the lab ID, source and de
 - `label` (String) link label (auto generated).
 - `link_capture_key` (String) link capture key (when running).
 - `state` (String) Link state.
-
-

docs/resources/node.md

@@ -3,12 +3,12 @@
 page_title: "cml2_node Resource - terraform-provider-cml2"
 subcategory: ""
 description: |-
-  A node resource represents a CML node. At create time, the lab ID, a node definition and a label must be provided.  Other attributes are optional.  Note that some attributes can't be changed after the node state has changed to STARTED (see the lifecyle resource) once. Changing attributes will then require a replace.
+  A node resource represents a CML node. At create time, the lab ID, a node definition and a label must be provided.  Other attributes are optional.  Note that some attributes can't be changed after the node state has changed to STARTED (see the lifecyle resource) once. Changing attributes will then require a replace.  Node configurations are "day zero" configurations. Replacing a configuration typically requires a node replacement if the node has been started.  No Configurations can be provided for unmanaged switches. External connectors require the connector label (like "NAT"), not the device name (like "virbr0"). The available connectors can be retrieved via the external connector data source.
 ---
 
 # cml2_node (Resource)
 
-A node resource represents a CML node. At create time, the lab ID, a node definition and a label must be provided.  Other attributes are optional.  Note that some attributes can't be changed after the node state has changed to `STARTED` (see the lifecyle resource) once. Changing attributes will then require a replace.
+A node resource represents a CML node. At create time, the lab ID, a node definition and a label must be provided.  Other attributes are optional.  Note that some attributes can't be changed after the node state has changed to `STARTED` (see the `lifecyle` resource) once. Changing attributes will then require a replace.  Node configurations are "day zero" configurations. Replacing a configuration typically requires a node replacement if the node has been started.  No Configurations can be provided for unmanaged switches. External connectors require the connector label (like "NAT"), not the device name (like "virbr0"). The available connectors can be retrieved via the external connector data source.
 
 
 
@@ -28,6 +28,7 @@ A node resource represents a CML node. At create time, the lab ID, a node defini
 - `cpu_limit` (Number) CPU limit in %, 20-100. Can be changed until the node is started once. Will require a replace in that case.
 - `cpus` (Number) Number of CPUs. Can be changed until the node is started once. Will require a replace in that case.
 - `data_volume` (Number) Size of data volume, in GB. Can be changed until the node is started once. Will require a replace in that case.
+- `hide_links` (Boolean) If true, links are not shown in the topology. This is a visual cue and does not influence any simulation function.
 - `imagedefinition` (String) Image definition, must match the node type. Can be changed until the node is started once. Will require a replace in that case.
 - `ram` (Number) Amount of RAM, megabytes. Can be changed until the node is started once. Will require a replace in that case.
 - `tags` (Set of String) Set of tags of the node.
@@ -64,5 +65,3 @@ Read-Only:
 
 - `console_key` (String)
 - `device_number` (Number)
-
-

docs/resources/user.md

@@ -48,5 +48,3 @@ resource "cml2_user" "student1" {
 - `id` (String) User ID (UUID).
 - `labs` (Set of String) Set of lab IDs the user owns.
 - `opt_in` (Boolean) True if has opted in to sending telemetry data.
-
-

examples/data-sources/cml2_connector/data_source.tf

@@ -0,0 +1,15 @@
+# Get a list of all connectors on the system with either the provided tag (the
+# result can have multiple elements) or with a specific name/label (the result
+# has exactly one or zero elements if the label does not exist).
+
+data "cml2_connector" "nat" {
+  tag = "NAT"
+  # Alternatively (or in combination, logical AND):
+  # label = "System Bridge"
+}
+
+output "nat_connector" {
+  # The label can be used as the configuration of an external connector node
+  # The ID is mostly for internal use.
+  value = data.cml2_connector.nat.connectors[0].label
+}