add even more documentation

CHANGELOG.md

@@ -1,3 +1,9 @@
+## 1.2.0
+
+FEATURES:
+
+- Add more examples in the documentation and further expand it
+
 ## 1.1.0
 
 FEATURES:

docs/index.md

@@ -26,7 +26,7 @@ terraform {
 }
 
 provider "storagegrid" {
-  address   = "https://grid.firm.com:9443/api/v3"
+  address   = "https://grid.firm.com:9443"
   username  = "grid"
   password  = "change_me"
   tenant    = "<int>" # Tenant ID

docs/resources/groups.md

@@ -1,16 +1,41 @@
 ---
 # generated by https://github.com/hashicorp/terraform-plugin-docs
 page_title: "storagegrid_groups Resource - storagegrid"
-subcategory: ""
 description: |-
   Create new group - a resource
 ---
 
 # storagegrid_groups (Resource)
 
-Create new group - a resource
-
-
+Create a new group - a resource. The group then contains users.
+See [StorageGrid documentation](https://docs.netapp.com/us-en/storagegrid-118/tenant/creating-groups-for-s3-tenant.html).
+
+```terraform
+resource "storagegrid_groups" "new-local-group" {
+  unique_name          = "group/my_new_test_group_tf_stroragegrid_provider"
+  display_name         = "StorageGrid TF Provider plugin"
+  management_read_only = "false"
+  policies = {
+    management = {
+      manage_all_containers        = false
+      manage_endpoints             = false
+      manage_own_container_objects = false
+      manage_own_s3_credentials    = true
+      root_access                  = false
+    }
+    s3 = {
+      statement = [
+        {
+          sid      = "681616"
+          effect   = "Deny"
+          action   = ["s3:GetObject"]
+          resource = ["arn:aws:s3:::mybucket/myobject"]
+        }
+      ]
+    }
+  }
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema

docs/resources/users.md

@@ -1,16 +1,25 @@
 ---
 # generated by https://github.com/hashicorp/terraform-plugin-docs
 page_title: "storagegrid_users Resource - storagegrid"
-subcategory: ""
 description: |-
   Create a new user - a resource
 ---
 
 # storagegrid_users (Resource)
 
-Create a new user - a resource
-
+Create a new user - a resource. Must be a member of some group.
+See [StorageGrid documentation](https://docs.netapp.com/us-en/storagegrid-118/tenant/managing-local-users.html).
 
+```terraform
+resource "storagegrid_users" "new-local-user" {
+  unique_name = "user/my_new_test_user_tf_stroragegrid_provider"
+  full_name   = "My StorageGrid TF Provider plugin"
+  disable     = "false"
+  member_of = [
+    "a9dd4848-a863-4716-82eb-d0939a6d643b"
+  ]
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema
@@ -31,3 +40,4 @@ Create a new user - a resource
 - `federated` (Boolean) True if the User is federated, for example, an LDAP User
 - `id` (String) The ID of this resource.
 - `user_urn` (String)
+

examples/provider/main.tf

@@ -8,7 +8,7 @@ terraform {
 }
 
 provider "storagegrid" {
-  address   = "https://grid.firm.com:9443/api/v3"
+  address   = "https://grid.firm.com:9443"
   username  = "grid"
   password  = "change_me"
   tenant    = "<int>" # Tenant ID

examples/resources/groups.tf

@@ -0,0 +1,24 @@
+resource "storagegrid_groups" "new-local-group" {
+  unique_name          = "group/my_new_test_group_tf_stroragegrid_provider"
+  display_name         = "StorageGrid TF Provider plugin"
+  management_read_only = "false"
+  policies = {
+    management = {
+      manage_all_containers        = false
+      manage_endpoints             = false
+      manage_own_container_objects = false
+      manage_own_s3_credentials    = true
+      root_access                  = false
+    }
+    s3 = {
+      statement = [
+        {
+          sid      = "681616"
+          effect   = "Deny"
+          action   = ["s3:GetObject"]
+          resource = ["arn:aws:s3:::mybucket/myobject"]
+        }
+      ]
+    }
+  }
+}

examples/resources/users.tf

@@ -0,0 +1,8 @@
+resource "storagegrid_users" "new-local-user" {
+  unique_name = "user/my_new_test_user_tf_stroragegrid_provider"
+  full_name   = "My StorageGrid TF Provider plugin"
+  disable     = "false"
+  member_of = [
+    "a9dd4848-a863-4716-82eb-d0939a6d643b"
+  ]
+}

readme.md

@@ -2,28 +2,9 @@
 
 This is a terraform provider plugin for [NetApp StorageGRID S3](https://www.netapp.com/data-storage/storagegrid/) system.
 
-Version `v1.0.0` has been tested & validated to work against [11.7 version](https://docs.netapp.com/us-en/storagegrid-117/).
+Version `v1.0.0` has been tested & validated to work against [11.8 version](https://docs.netapp.com/us-en/storagegrid-118/).
 
-# Very important information
-
-:warning: There exist 2 git repositories. One is hosted internally and another (this) one is public.
-
-There are many differences.
-
-Among them, the most important given the access to the real-life NetApp StorageGRID, 
-are Terraform **tests**. These make sure that this Terraform plugin has been tested and works actually.
-
-Unfortunately, there are far from ideal state and cannot be published completely - at this very moment - in this repository.
-
-For instance, they have dependencies to internal Vault system, and have other issues such as hardcoded URLs, etc.
-
-At such, only a selected number of them is published, without a guarantee that they (will) work when executing them.
-
-# How does sync between internal and this public repo work?
-
-There is no automatic sync'ing available. Any updates are first reviewed and only then pushed to GitHub manually.
-
-# What is working and what is not working?
+## What is working and what is not working?
 
 This provider aims to cover selected **Tenant** [REST API endpoints such](https://docs.netapp.com/us-en/storagegrid/tenant/understanding-tenant-management-api.html) `users`, `groups` or `s3` (which creates access/secret keys). 
 
@@ -46,7 +27,6 @@ terraform {
 }
 ```
 
-
 ### Authentication
 
 The StorageGRID provider offers 2 different ways of providing credentials for authentication.
@@ -56,7 +36,6 @@ The following methods are supported:
 * Static credentials
 * Environment variables
 
-
 #### Static credentials
 
 Default static credentials can be provided by adding the `tenant`, `username`, 
@@ -66,7 +45,7 @@ Only `insecure` is optional (default is `false`). It could be used when using se
 
 ```terraform
 provider "storagegrid" {
-  address   = "https://grid.firm.com:9443/api/v3"
+  address   = "https://grid.firm.com:9443"
   username  = "grid"
   password  = "change_me"
   tenant    = "<int>" # Tenant ID
@@ -102,25 +81,24 @@ Contributions are always welcome! In order to develop this provider your system
 - `golang`
 - `terraform` for running real life tests
 
-The GitHub workflow is very simple: 
+The GitHub workflow is very simple:
 
 1. Fork this repo.
-2. Push your changes to some branch, and create Pull Request against this repo. 
+2. Push your changes to some branch, and create Pull Request against this repo.
 3. Then either ping me or assign me for review.
 
 Please, make sure that your changes either:
 
 - a) include tests (in `golang`, `terraform` or `terraform-in-golang`, etc.) OR
 - b) your confirmation that if you cannot publish your tests, your changes have been tested with real StorageGRID system.
 
-
-## Some additional information: 
+## Some additional information:
 
 - I followed this guideline fow how to create new provider: <https://developer.hashicorp.com/terraform/tutorials/providers-plugin-framework>.
-- We use only the modern [Terraform Plugin Framework](https://github.com/hashicorp/terraform-plugin-framework) SDK. 
+- We use only the modern [Terraform Plugin Framework](https://github.com/hashicorp/terraform-plugin-framework) SDK.
 Not the `SDKv2` and support for it (whatever the reason) will not be accepted.
-- An early attempt was done with [Code Generation](https://developer.hashicorp.com/terraform/plugin/code-generation) approach, but I have failed to 
-overcome several issues with StorageGRID REST API (=json file) without doing manual changes to the Swagger API.
+- An early attempt was done with [Code Generation](https://developer.hashicorp.com/terraform/plugin/code-generation) approach, but I
+have failed to overcome several issues with StorageGRID REST API (=json file) without doing manual changes to the Swagger API.
 
 
 ## Code repository structure
@@ -134,7 +112,7 @@ Additionally, in `tools/rest-api`, it contains Swagger/OpenAPI export for specif
   - `.terraformrc` file which is used for local development. You may not need it. But you will, if your tests will include other Terraform providers (such as my internal tests that use HashiCorp Vault etc.)
   - `makefile` which essentially governs developing this provider. Execute as 
 
-  ```
+  ```bash
   make install_dnf
   make lint
   make fmt
@@ -149,4 +127,4 @@ docker run -it -v $(pwd):/home storagegrid_dev:latest
 $ make build
 $ make lint
 ....
-```
+```

templates/resources/groups.md.tmpl

@@ -0,0 +1,15 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "storagegrid_groups Resource - storagegrid"
+description: |-
+  Create new group - a resource
+---
+
+# storagegrid_groups (Resource)
+
+Create a new group - a resource. The group then contains users.
+See [StorageGrid documentation](https://docs.netapp.com/us-en/storagegrid-118/tenant/creating-groups-for-s3-tenant.html).
+
+{{ tffile "examples/resources/groups.tf" }}
+
+{{ .SchemaMarkdown | trimspace }}

templates/resources/users.md.tmpl

@@ -0,0 +1,16 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "storagegrid_users Resource - storagegrid"
+description: |-
+  Create a new user - a resource
+---
+
+# storagegrid_users (Resource)
+
+Create a new user - a resource. Must be a member of some group.
+See [StorageGrid documentation](https://docs.netapp.com/us-en/storagegrid-118/tenant/managing-local-users.html).
+
+{{ tffile "examples/resources/users.tf" }}
+
+{{ .SchemaMarkdown | trimspace }}
+