Merge pull request #108 from pulumi/guin/installation-docs

Add installation docs
pulumi · Aug 26, 2024 · 89c2778 · 89c2778
2 parents c67e0a7 + c2b86ee
commit 89c2778
Show file tree

Hide file tree

Showing 3 changed files with 115 additions and 118 deletions.
diff --git a/docs/_index.md b/docs/_index.md
@@ -1,84 +1,5 @@
 ---
 title: dbt Cloud
-meta_desc: Provides an overview of the dbt Cloud Provider for Pulumi.
+meta_desc: The dbt Cloud provider for Pulumi can be used to provision any of the cloud resources available in dbt Cloud.
 layout: package
 ---
-
-The dbt Cloud Resource Provider lets you manage [dbt Cloud](https://www.getdbt.com/) resources. This is a bridged provider from the terraform dbt Cloud provider, located at:
-
-[github.com/dbt-labs/terraform-provider-dbtcloud](https://github.com/dbt-labs/terraform-provider-dbtcloud/)
-
-## Example
-
-{{< chooser language "typescript,python,go,csharp" >}}
-{{% choosable language typescript %}}
-
-```typescript
-import * as pulumi from "@pulumi/pulumi";
-import * as dbtcloud from "@pulumi/dbtcloud";
-
-const project =  new dbtcloud.Project("ts-project", {name: "ts-project"});
-
-export const projectname = project.name;
-```
-
-{{% /choosable %}}
-{{% choosable language python %}}
-
-```python
-import pulumi
-import pulumi_dbtcloud as dbtcloud
-
-project = dbtcloud.Project("py-project", name="py-project")
-
-pulumi.export("project_name", project.name)
-```
-
-{{% /choosable %}}
-{{% choosable language go %}}
-
-```go
-package main
-
-import (
-	"github.com/pulumi/pulumi-dbtcloud/sdk/go/dbtcloud"
-	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
-)
-
-func main() {
-	pulumi.Run(func(ctx *pulumi.Context) error {
-		project, err := dbtcloud.NewProject(ctx, "go-project", &dbtcloud.ProjectArgs{
-			Name: pulumi.String("go-project"),
-		})
-		if err != nil {
-			return err
-		}
-		ctx.Export("project_name", project.Name)
-		return nil
-	})
-}
-```
-
-{{% /choosable %}}
-{{% choosable language csharp %}}
-
-```csharp
-using System.Collections.Generic;
-using Pulumi;
-using Pulumi.DbtCloud;
-
-return await Deployment.RunAsync(() =>
-{
-    var project = new Project("cs-project", new ProjectArgs { Name = "cs-project" });
-
-    return new Dictionary<string, object?>
-    {
-        ["ProjectName"] = project.Name
-    };
-});
-```
-
-{{% /choosable %}}
-
-{{< /chooser >}}
-
diff --git a/docs/installation-configuration.md b/docs/installation-configuration.md
@@ -1,62 +1,121 @@
 ---
-title: dbt Cloud Installation & Configuration
-meta_desc: Information on how to install the dbt Cloud provider.
+title: dbtcloud Provider Installation & Configuration
+meta_desc: Provides an overview on how to configure the Pulumi dbtcloud Provider.
 layout: package
 ---
-
 ## Installation
 
-This package is available for several languages/platforms:
-
-- JavaScript/TypeScript: [`@pulumi/dbtcloud`](https://www.npmjs.com/package/@pulumi/dbtcloud)
-- Python: [`pulumi-dbtcloud`](https://pypi.org/project/pulumi-dbtcloud/)
-- Go: [`github.com/pulumi/pulumi-dbtcloud/sdk/go/dbtcloud`](https://pkg.go.dev/github.com/pulumi/pulumi-dbtcloud/sdk/go/dbtcloud)
-- .NET: [`Pulumi.DbtCloud`](https://www.nuget.org/packages/Pulumi.DbtCloud)
+The dbtcloud provider is available as a package in all Pulumi languages:
+
+* JavaScript/TypeScript: [`@pulumi/dbtcloud`](https://www.npmjs.com/package/@pulumi/dbtcloud)
+* Python: [`pulumi-dbtcloud`](https://pypi.org/project/pulumi-dbtcloud/)
+* Go: [`github.com/pulumi/pulumi-dbtcloud/sdk/go/dbtcloud`](https://github.com/pulumi/pulumi-dbtcloud)
+* .NET: [`Pulumi.Dbtcloud`](https://www.nuget.org/packages/Pulumi.Dbtcloud)
+* Java: [`com.pulumi/dbtcloud`](https://central.sonatype.com/artifact/com.pulumi/dbtcloud)
+## Provider configuration
+
+{{< chooser language "typescript,python,go,csharp,java,yaml" >}}
+{{% choosable language typescript %}}
+```yaml
+# Pulumi.yaml provider configuration file
+name: configuration-example
+runtime: nodejs
+config:
+    dbtcloud:accountId:
+        value: 'TODO: var.dbt_cloud_account_id'
+    dbtcloud:hostUrl:
+        value: https://cloud.getdbt.com/api
+    dbtcloud:token:
+        value: 'TODO: var.dbt_cloud_token'
 
-### Node.js (JavaScript/TypeScript)
+```
 
-To use from JavaScript or TypeScript in Node.js, install using either `npm`:
+{{% /choosable %}}
+{{% choosable language python %}}
+```yaml
+# Pulumi.yaml provider configuration file
+name: configuration-example
+runtime: python
+config:
+    dbtcloud:accountId:
+        value: 'TODO: var.dbt_cloud_account_id'
+    dbtcloud:hostUrl:
+        value: https://cloud.getdbt.com/api
+    dbtcloud:token:
+        value: 'TODO: var.dbt_cloud_token'
 
-```bash
-npm install @pulumi/dbtcloud
 ```
 
-or `yarn`:
+{{% /choosable %}}
+{{% choosable language csharp %}}
+```yaml
+# Pulumi.yaml provider configuration file
+name: configuration-example
+runtime: dotnet
+config:
+    dbtcloud:accountId:
+        value: 'TODO: var.dbt_cloud_account_id'
+    dbtcloud:hostUrl:
+        value: https://cloud.getdbt.com/api
+    dbtcloud:token:
+        value: 'TODO: var.dbt_cloud_token'
 
-```bash
-yarn add @pulumi/dbtcloud
 ```
 
-### Python
+{{% /choosable %}}
+{{% choosable language go %}}
+```yaml
+# Pulumi.yaml provider configuration file
+name: configuration-example
+runtime: go
+config:
+    dbtcloud:accountId:
+        value: 'TODO: var.dbt_cloud_account_id'
+    dbtcloud:hostUrl:
+        value: https://cloud.getdbt.com/api
+    dbtcloud:token:
+        value: 'TODO: var.dbt_cloud_token'
 
-To use from Python, install using `pip`:
-
-```bash
-pip install pulumi-dbtcloud
 ```
 
-### Go
-
-To use from Go, use `go get` to grab the latest version of the library:
+{{% /choosable %}}
+{{% choosable language yaml %}}
+```yaml
+# Pulumi.yaml provider configuration file
+name: configuration-example
+runtime: yaml
+config:
+    dbtcloud:accountId:
+        value: 'TODO: var.dbt_cloud_account_id'
+    dbtcloud:hostUrl:
+        value: https://cloud.getdbt.com/api
+    dbtcloud:token:
+        value: 'TODO: var.dbt_cloud_token'
 
-```bash
-go get github.com/pulumi/pulumi-dbtcloud/sdk/go/dbtcloud
 ```
 
-### .NET
-
-To use from .NET, install using `dotnet add package`:
+{{% /choosable %}}
+{{% choosable language java %}}
+```yaml
+# Pulumi.yaml provider configuration file
+name: configuration-example
+runtime: java
+config:
+    dbtcloud:accountId:
+        value: 'TODO: var.dbt_cloud_account_id'
+    dbtcloud:hostUrl:
+        value: https://cloud.getdbt.com/api
+    dbtcloud:token:
+        value: 'TODO: var.dbt_cloud_token'
 
-```bash
-dotnet add package Pulumi.DbtCloud
 ```
 
-## Configuration Options
+{{% /choosable %}}
+{{< /chooser >}}
 
-Use `pulumi config set dbtcloud:<option> (--secret)`.
+<!-- schema generated by tfplugindocs -->
+## Configuration Reference
 
-| Option     | Environment Variable   | Required/Optional | Default                                                      | Description                             |
-|------------|------------------------|-------------------|--------------------------------------------------------------|-----------------------------------------|
-| `token`    | `DBT_CLOUD_TOKEN`      | Required          |                                                              | The API token for your dbt Cloud user   |
-| `accountId`| `DBT_CLOUD_ACCOUNT_ID` | Required          |                                                              | The ID for your dbt Cloud account       |
-| `hostUrl`  | `DBT_CLOUD_HOST_URL`   | Optional          | [https://cloud.getdbt.com/api](https://cloud.getdbt.com/api) | The host URL for your dbt Cloud account |
+- `accountId` (Number) Account identifier for your dbt Cloud implementation. Instead of setting the parameter, you can set the environment variable `DBT_CLOUD_ACCOUNT_ID`
+- `hostUrl` (String) URL for your dbt Cloud deployment. Instead of setting the parameter, you can set the environment variable `DBT_CLOUD_HOST_URL` - Defaults to <https://cloud.getdbt.com/api>
+- `token` (String, Sensitive) API token for your dbt Cloud. Instead of setting the parameter, you can set the environment variable `DBT_CLOUD_TOKEN`
diff --git a/provider/doc_edits.go b/provider/doc_edits.go
@@ -18,6 +18,7 @@ const postProjectExample string = `data "dbtcloud_project" "another_test_project
 func editRules(defaults []tfbridge.DocsEdit) []tfbridge.DocsEdit {
 	return append(
 		defaults,
+		removeContent(warning, "index.md"),
 		simpleReplace("appplication_id", "applicationId"),
 		simpleReplace("appplication_id", "application_id"),
 		simpleReplace(preProjectExample, postProjectExample),
@@ -51,3 +52,19 @@ func reReplace(from string, to string) tfbridge.DocsEdit {
 		},
 	}
 }
+
+var warning = []byte("~> 🚧 IMPORTANT! 🚧  \nSince 0.3, only resources starting with `dbtcloud_xxx` are allowed. " +
+	"If you use the legacy `dbt_cloud_xxx` ones, you will have to stay on 0.2.x or move to the new resources.\n" +
+	"Instruction on how to do it is available in the 0.2.x docs.")
+
+// Helper func to remove a content byte from a file
+func removeContent(text []byte, path string) tfbridge.DocsEdit {
+	return tfbridge.DocsEdit{
+		Path: path,
+		Edit: func(_ string, content []byte) ([]byte, error) {
+			contentSplit := bytes.Split(content, text)
+			content = bytes.Join(contentSplit, []byte(" "))
+			return content, nil
+		},
+	}
+}