Merge branch 'doc_update' into 'master'

feat(doc-templates): added doc templates See merge request rackn/terraform-provider-drp!101
rackn · Apr 10, 2023 · 226460d · 226460d
2 parents f7d4bb9 + 14fa996
commit 226460d
Show file tree

Hide file tree

Showing 6 changed files with 181 additions and 35 deletions.
diff --git a/README.md b/README.md
@@ -1,27 +1,20 @@
-Terraform Provider for Digital Rebar v4.4+
-==========================================
+# Terraform Provider for Digital Rebar v4.4+
 
 - Hashicorp Website: https://www.terraform.io
 - RackN Website: https://rackn.com
-- Digital Rebar (DRP) Community:  http://rebar.digital
+- Digital Rebar: http://rackn.com/rebar
 
-NOTE: For new users, you should use the release managed binaries from https://gitlab.com/rackn/terraform-provider-drp/releases.
+## NOT Usage Documentation!
 
-NOT Documentation!
-------------------
+This page is about building, NOT about using, the provider! DRP Terraform Provider documentation is maintained with the project integrations documentation, please see https://docs.rackn.io/en/latest/doc/integrations/terraform.html
 
-This page is about building, NOT about using, the provider!  DRP Terraform Provider documentation is maintained with the project integrations documentation, please see https://provision.readthedocs.io/en/latest/doc/integrations/terraform.html
+## Build Requirements
 
-Build Requirements
-------------------
+- [Terraform](https://www.terraform.io/downloads.html) 0.13.x
+- [Go](https://golang.org/doc/install) 1.13 (to build the provider plugin)
+- Digital Rebar terraform/[params] in system (can be imported from RackN content)
 
--	[Terraform](https://www.terraform.io/downloads.html) 0.13.x
--	[Go](https://golang.org/doc/install) 1.13 (to build the provider plugin)
--	Digital Rebar terraform/[params] in system (can be imported from RackN content)
-
-
-Building The Provider
----------------------
+## Building The Provider
 
 Clone repository to: `$GOPATH/src/gitlab.com/rackn/terraform-provider-drp`
 
@@ -37,40 +30,33 @@ $ cd $GOPATH/src/gitlab.com/rackn/terraform-provider-drp
 $ make build
 ```
 
-Building The Provider (v0.13+)
-------------------------------
-
-v0.13+ requres use of the required_providers stanza for your your OS and architecture!  Then it will infer the cache path.  You must copy your build output to the correct cache path.
+## Building The Provider (v0.13+)
 
+v0.13+ requres use of the required_providers stanza for your your OS and architecture! Then it will infer the cache path. You must copy your build output to the correct cache path.
 
 ```sh
 $ mkdir -p .terraform/plugins/rackn/drp/2.0/linux_amd64
 $ ln -s bin/linux/amd64/terraform-provider-drp .terraform/plugins/extras.rackn.io/rackn/drp/2.0.0/linux_amd64
 ```
 
-Tests
------
+## Tests
 
 At this time, no tests are available for the provider.
 
-
-Requirements for the Digital Rebar Provision (DRP) provider
------------------------------------------------------------
+## Requirements for the Digital Rebar Provision (DRP) provider
 
 DRP Terraform Provider documentation is maintained with the project integrations documentation, please see https://provision.readthedocs.io/en/tip/doc/integrations/terraform.html
 
 The DRP Terraform Provider uses the DRP v4.4+ Pooling API to allocate and release
 machines from pools.
 
-By design, the only limited state is exposed via this provider.  This prevents Terraform state from overriding or changing DRP machine information.
+By design, the only limited state is exposed via this provider. This prevents Terraform state from overriding or changing DRP machine information.
 
 The Terraform Provider update interactions are limited to the allocation/release methods.
 
 The Terraform Provider can read additional fields ("computed" valutes) when requesting inventory. In this way, users find additional characteristics; however, these are
 added to the provider carefully.
 
-
-To create and upload the 3rd party registery
-=============================================
+# To create and upload the 3rd party registery
 
 See registery/readme.md
diff --git a/docs/index.md b/docs/index.md
@@ -1,16 +1,24 @@
 ---
-# generated by https://github.com/hashicorp/terraform-plugin-docs
-page_title: "drp Provider"
-subcategory: ""
+page_title: "Digital Rebar (drp) Provider"
 description: |-
-  
+  Provider Information
+subcategory: "Infrastructure"
 ---
+# Digital Rebar (drp) Provider
 
-# drp Provider
+The Digital Rebar provider makes controlling Bare Metal simple, powerful and cloud-like.
 
+Manage physical servers, bare metal, virtual machines and cloud infrastructure via Terraform machines by leveraging Digital Rebar Machine Pools and Infrastructure PIpelines. These features provide powerful operational governance and transparency behind the scenes for infrastructure teams while keeping the Terraform "give me a machine" experience simple and cloud-like for development teams.
 
+Digital Rebar is a self-contained user-managed software platform: no external networking or cloud service is required. Further information about installing, licenses and operation of Digital Rebar can be found on the RackN websites: https://RackN.com/rebar.
 
+## Prerequisites & Usage
 
+You _must_ install Digital Rebar before using this provider. See https://portal.rackn.io for instructions.
+
+Integration documentation: https://docs.rackn.io/en/latest/doc/integrations/terraform.html
+
+Note: once installed, export `RS_KEY` environmental variable to define the "user:password" credentials (recommended over including the the plan provider stanza)
 
 <!-- schema generated by tfplugindocs -->
 ## Schema
@@ -25,3 +33,97 @@ description: |-
 - `password` (String) The DRP password
 - `token` (String) Granted DRP token (use instead of RS_KEY)
 - `username` (String) The DRP user
+
+## Provider Example
+
+```terraform
+provider "drp" {
+  username = "rocketskates"
+  password = "r0cketsk8ts"
+  endpoint = "https://192.168.1.93:8092"
+  # token  = will read from RS_TOKEN if set
+  # key    = will read from RS_KEY if set
+}
+```
+
+## Example of Complete tf File
+
+```terraform
+# RackN 2020
+# Digital Rebar v4.4+ Terraform v0.13+ Provider
+
+terraform {
+  required_version = ">= 0.13.0"
+  required_providers {
+    drp = {
+      version = "2.0.0"
+      source  = "extras.rackn.io/rackn/drp"
+    }
+  }
+}
+
+provider "drp" {
+  username = "rocketskates"
+  password = "r0cketsk8ts"
+  endpoint = "https://192.168.1.93:8092"
+  # token  = will read from RS_TOKEN if set
+  # key    = will read from RS_KEY if set
+}
+
+resource "drp_machine" "one_random_node" {
+
+  # Required values
+  # there are none!
+
+  # Settable values
+  # pool = name of an existing DRP pool (defaults to "default")
+  # allocate_workflow = Name of workflow to set when a machine is allocated from the pool
+  # if none is set the default pool/workflow defined by the drp admin will be used
+  # deallocate_workflow = Name of workflow to set when the machine is released back to the pool
+  # setting this overrides the defaults defined by the DRP admin
+  # timeout = time string for max wait time (default to 5m)
+  # 
+  # List of public SSH keys to be installed (written as Param.access-keys)
+  # authorized_keys = ["ssh key"]
+  # 
+  # List of profiles to apply to node (must already exist)
+  # add_profiles = ["mandy", "clause"]
+  #
+  # list of parameters to set with their string value forms
+  # add_parameters = ["param1: value1", "param2: value2"]
+  #
+  # Use filters to hone your machine to a specific set of criteria, or exclude them based on criteria
+  # follows the Digital Rebar CLI command line pattern
+  # This example looks for a machine named esxi-7-testing.example.local where the "Address" field on the
+  # DRP Machine object is not empty/blank
+  # filters = ["Name=esxi-7-testing.example.local", "Address=Ne()"]
+  # This example excludes machines that do not have an Address
+  # filters = ["Address=Ne()"]
+  # Returned values
+  # name = machine name
+  # address = machine address
+  # status = machine status (typically "InUse")
+  # If your machine does not have an Address it will report the "address" as nil/null
+}
+
+output "machine_ip" {
+  value       = drp_machine.one_random_node.address
+  description = "Machine.Address (the Machine's primary IP)"
+}
+
+output "machine_id" {
+  value       = drp_machine.one_random_node.id
+  description = "Machine.Uuid"
+}
+
+output "machine_name" {
+  value       = drp_machine.one_random_node.name
+  description = "Machine.Name"
+}
+
+output "machine_status" {
+  value       = drp_machine.one_random_node.status
+  description = "Machine.PoolStatus"
+}
+```
+
diff --git a/docs/resources/machine.md b/docs/resources/machine.md
@@ -10,7 +10,18 @@ description: |-
 
 Machine resource
 
-
+## Example Usage
+
+```terraform
+resource "drp_machine" "one_random_node" {
+  pool                = k8s_pool
+  allocate_workflow   = universal_k8s_build
+  deallocate_workflow = universal_k8s_decom
+  timeout             = "120m"
+  add_profiles        = ["admin_access_keys", "k8s_node_network_settings"]
+  filters             = ["Address=Ne()"]
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema

diff --git a/examples/provider/provider.tf b/examples/provider/provider.tf
@@ -0,0 +1,7 @@
+provider "drp" {
+  username = "rocketskates"
+  password = "r0cketsk8ts"
+  endpoint = "https://192.168.1.93:8092"
+  # token  = will read from RS_TOKEN if set
+  # key    = will read from RS_KEY if set
+}
diff --git a/examples/resources/drp_machine/resource.tf b/examples/resources/drp_machine/resource.tf
@@ -0,0 +1,8 @@
+resource "drp_machine" "one_random_node" {
+  pool                = k8s_pool
+  allocate_workflow   = universal_k8s_build
+  deallocate_workflow = universal_k8s_decom
+  timeout             = "120m"
+  add_profiles        = ["admin_access_keys", "k8s_node_network_settings"]
+  filters             = ["Address=Ne()"]
+}
diff --git a/templates/index.md.tmpl b/templates/index.md.tmpl
@@ -0,0 +1,32 @@
+---
+page_title: "Digital Rebar (drp) Provider"
+description: |-
+  Provider Information
+subcategory: "Infrastructure"
+---
+# Digital Rebar (drp) Provider
+
+The Digital Rebar provider makes controlling Bare Metal simple, powerful and cloud-like.
+
+Manage physical servers, bare metal, virtual machines and cloud infrastructure via Terraform machines by leveraging Digital Rebar Machine Pools and Infrastructure PIpelines. These features provide powerful operational governance and transparency behind the scenes for infrastructure teams while keeping the Terraform "give me a machine" experience simple and cloud-like for development teams.
+
+Digital Rebar is a self-contained user-managed software platform: no external networking or cloud service is required. Further information about installing, licenses and operation of Digital Rebar can be found on the RackN websites: https://RackN.com/rebar.
+
+## Prerequisites & Usage
+
+You _must_ install Digital Rebar before using this provider. See https://portal.rackn.io for instructions.
+
+Integration documentation: https://docs.rackn.io/en/latest/doc/integrations/terraform.html
+
+Note: once installed, export `RS_KEY` environmental variable to define the "user:password" credentials (recommended over including the the plan provider stanza)
+
+{{ .SchemaMarkdown | trimspace }}
+
+## Provider Example
+
+{{ tffile "examples/provider/provider.tf" }}
+
+## Example of Complete tf File
+
+{{ tffile "examples/example.tf" }}
+