starlark/types: Provider documentation and examples

starlark/types/backend.go

@@ -66,7 +66,7 @@ func BuiltinBackend(pm *terraform.PluginManager) starlark.Value {
 //
 //         fields:
 //           __kind__ string
-//             Kind of the backend. Always `backend`.
+//             Kind of the backend. Fixed value `backend`.
 //           __type__ string
 //             Type of the backend. Eg.: `local`.
 //           __dict__ Dict

starlark/types/collection.go

@@ -252,6 +252,19 @@ func getValue(r *Resource, key string) starlark.Value {
 	return r.values.Get(key).Starlark()
 }
 
+// ProviderCollection represents a nested Dict of providers, indexed by
+// provider type and provider name.
+//
+//   outline: types
+//     types:
+//       ProviderCollection
+//         ProviderCollection holds the providers in a nested dictionary,
+//         indexed by provider type and provider name. The values can be
+//         accessed by indexing or using the built-in method of `dict`.
+//
+//         examples:
+//           provider_collection.star
+//
 type ProviderCollection struct {
 	pm *terraform.PluginManager
 	*Dict

starlark/types/provider.go

@@ -51,6 +51,44 @@ func BuiltinProvider(pm *terraform.PluginManager) starlark.Value {
 }
 
 // Provider represents a provider as a starlark.Value.
+//
+//   outline: types
+//     types:
+//       Provider
+//         Terraform is used to create, manage, and update infrastructure
+//         resources such as physical machines, VMs, network switches,
+//         containers, and more. Almost any infrastructure type can be
+//         represented as a resource in Terraform.
+//
+//         examples:
+//           provider.star
+//           provider_resource.star
+//             Resource instantiation from a Provider.
+//
+//         fields:
+//           __version__ string
+//             Provider version
+//           __kind__ string
+//             Kind of the provider. Fixed value `provider`
+//           __type__ string
+//             Type of the resource. Eg.: `aws_instance`
+//           __name__ string
+//             Local name of the provider, if none was provided to the constructor
+//             the name is auto-generated following the partern `id_%s`.  At
+//             Terraform is called [`alias`](https://www.terraform.io/docs/configuration/providers.html#alias-multiple-provider-instances)
+//           __dict__ Dict
+//             A dictionary containing all the values of the resource.
+//           data MapSchema
+//             Data sources defined by the provider.
+//           resource MapSchema
+//             Resources defined by the provider.
+//           <argument> <scalar>
+//             Arguments defined by the provider schema, thus can be of any
+//             scalar type.
+//           <block> Resource
+//             Blocks defined by the provider schema, thus are nested resources,
+//             containing other arguments and/or blocks.
+//
 type Provider struct {
 	provider *plugin.GRPCProvider
 	meta     discovery.PluginMeta

starlark/types/resource.go

@@ -80,7 +80,7 @@ const (
 //             Type of the resource. Eg.: `aws_instance`
 //           __name__ string
 //             Local name of the resource, if none was provided to the constructor
-//             the name is auto-generated following the partern `id_`. Nested kind
+//             the name is auto-generated following the partern `id_%s`. Nested kind
 //             resources are unamed.
 //           __dict__ Dict
 //             A dictionary containing all the values of the resource.

starlark/types/testdata/examples/provider.star

@@ -0,0 +1,12 @@
+def print_provider_stats(p):
+    print("Provider %s[%s] (%s)" % (p.__type__, p.__name__, p.__version__))
+    print("  Defines Data Sources: %d" % len(dir(p.data)))
+    print("  Defines Resources: %d" % len(dir(p.resource)))
+
+provider = tf.provider("aws", "2.13.0")
+print_provider_stats(provider)
+
+# Output:
+# Provider aws[id_1] (2.13.0)
+#   Defines Data Sources: 131
+#   Defines Resources: 506

starlark/types/testdata/examples/provider_collection.star

@@ -0,0 +1,15 @@
+tf.provider("aws", "2.13.0", "qux")
+tf.provider("aws", "2.13.0", "bar")
+tf.provider("google")
+
+# providers can be access by indexing
+aws_names = tf.provider["aws"].keys()
+print("aws providers:", sorted(aws_names))
+
+# or by the get method
+google_names = tf.provider.get("google").keys()
+print("google providers:", google_names)
+
+# Output:
+# aws providers: ["bar", "qux"]
+# google providers: ["id_1"]

starlark/types/testdata/examples/provider_resource.star

@@ -0,0 +1,13 @@
+helm = tf.provider("helm")
+
+podinfo = helm.resource.release("podinfo")
+podinfo.chart = "podinfo"
+podinfo.version = "3.1.8"
+
+print(hcl(podinfo))
+# Output:
+# resource "helm_release" "podinfo" {
+#   provider = helm.id_1
+#   chart    = "podinfo"
+#   version  = "3.1.8"
+# }

starlark/types/testdata/terraform.star

@@ -31,6 +31,10 @@ def backendWrongType(): tf.backend = "foo"
 assert.fails(backendWrongType, "unexpected value string at backend")
 assert.eq(type(tf.backend), "Backend<local>")
 
+# pop provider
+baz = tf.provider("aws", "2.13.0", "baz", region="baz")
+pop = tf.provider["aws"].pop("baz")
+
 # hcl
 assert.eq(hcl(tf), "" +
 'terraform {\n' + \