Add installation docs (#887)

Part of pulumi/home#3598
pulumi · Aug 23, 2024 · 3aefaf5 · 3aefaf5
1 parent df514c7
commit 3aefaf5
Show file tree

Hide file tree

Showing 3 changed files with 228 additions and 0 deletions.
diff --git a/docs/_index.md b/docs/_index.md
@@ -0,0 +1,5 @@
+---
+title: Cloudflare
+meta_desc: The Cloudflare provider for Pulumi can be used to provision any of the cloud resources available in Cloudflare.
+layout: package
+---
diff --git a/docs/installation-configuration.md b/docs/installation-configuration.md
@@ -0,0 +1,204 @@
+---
+title: Cloudflare Provider Installation & Configuration
+meta_desc: Provides an overview on how to configure the Pulumi Cloudflare Provider.
+layout: package
+---
+## Installation
+
+The cloudflare provider is available as a package in all Pulumi languages:
+
+* JavaScript/TypeScript: [`@pulumi/cloudflare`](https://www.npmjs.com/package/@pulumi/cloudflare)
+* Python: [`pulumi-cloudflare`](https://pypi.org/project/pulumi-cloudflare/)
+* Go: [`github.com/pulumi/pulumi-cloudflare/sdk/v5/go/cloudflare`](https://github.com/pulumi/pulumi-cloudflare)
+* .NET: [`Pulumi.Cloudflare`](https://www.nuget.org/packages/Pulumi.Cloudflare)
+* Java: [`com.pulumi/cloudflare`](https://central.sonatype.com/artifact/com.pulumi/cloudflare)
+
+The Cloudflare provider is used to interact with resources supported by
+Cloudflare. The provider needs to be configured with the proper credentials
+before it can be used.
+## Example Usage
+
+{{< chooser language "typescript,python,go,csharp,java,yaml" >}}
+{{% choosable language typescript %}}
+```yaml
+# Pulumi.yaml provider configuration file
+name: configuration-example
+runtime: nodejs
+config:
+    cloudflare:apiToken:
+        value: 'TODO: var.cloudflare_api_token'
+
+```
+```typescript
+import * as pulumi from "@pulumi/pulumi";
+import * as cloudflare from "@pulumi/cloudflare";
+
+// Create a record
+const www = new cloudflare.Record("www", {});
+// Create a page rule
+const wwwPageRule = new cloudflare.PageRule("www", {});
+```
+{{% /choosable %}}
+{{% choosable language python %}}
+```yaml
+# Pulumi.yaml provider configuration file
+name: configuration-example
+runtime: python
+config:
+    cloudflare:apiToken:
+        value: 'TODO: var.cloudflare_api_token'
+
+```
+```python
+import pulumi
+import pulumi_cloudflare as cloudflare
+
+# Create a record
+www = cloudflare.Record("www")
+# Create a page rule
+www_page_rule = cloudflare.PageRule("www")
+```
+{{% /choosable %}}
+{{% choosable language csharp %}}
+```yaml
+# Pulumi.yaml provider configuration file
+name: configuration-example
+runtime: dotnet
+config:
+    cloudflare:apiToken:
+        value: 'TODO: var.cloudflare_api_token'
+
+```
+```csharp
+using System.Collections.Generic;
+using System.Linq;
+using Pulumi;
+using Cloudflare = Pulumi.Cloudflare;
+
+return await Deployment.RunAsync(() =>
+{
+    // Create a record
+    var www = new Cloudflare.Record("www");
+
+    // Create a page rule
+    var wwwPageRule = new Cloudflare.PageRule("www");
+
+});
+
+```
+{{% /choosable %}}
+{{% choosable language go %}}
+```yaml
+# Pulumi.yaml provider configuration file
+name: configuration-example
+runtime: go
+config:
+    cloudflare:apiToken:
+        value: 'TODO: var.cloudflare_api_token'
+
+```
+```go
+package main
+
+import (
+	"github.com/pulumi/pulumi-cloudflare/sdk/v5/go/cloudflare"
+	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
+)
+
+func main() {
+	pulumi.Run(func(ctx *pulumi.Context) error {
+		// Create a record
+		_, err := cloudflare.NewRecord(ctx, "www", nil)
+		if err != nil {
+			return err
+		}
+		// Create a page rule
+		_, err = cloudflare.NewPageRule(ctx, "www", nil)
+		if err != nil {
+			return err
+		}
+		return nil
+	})
+}
+```
+{{% /choosable %}}
+{{% choosable language yaml %}}
+```yaml
+# Pulumi.yaml provider configuration file
+name: configuration-example
+runtime: yaml
+config:
+    cloudflare:apiToken:
+        value: 'TODO: var.cloudflare_api_token'
+
+```
+```yaml
+resources:
+  # Create a record
+  www:
+    type: cloudflare:Record
+  # Create a page rule
+  wwwPageRule:
+    type: cloudflare:PageRule
+    name: www
+```
+{{% /choosable %}}
+{{% choosable language java %}}
+```yaml
+# Pulumi.yaml provider configuration file
+name: configuration-example
+runtime: java
+config:
+    cloudflare:apiToken:
+        value: 'TODO: var.cloudflare_api_token'
+
+```
+```java
+package generated_program;
+
+import com.pulumi.Context;
+import com.pulumi.Pulumi;
+import com.pulumi.core.Output;
+import com.pulumi.cloudflare.Record;
+import com.pulumi.cloudflare.PageRule;
+import java.util.List;
+import java.util.ArrayList;
+import java.util.Map;
+import java.io.File;
+import java.nio.file.Files;
+import java.nio.file.Paths;
+
+public class App {
+    public static void main(String[] args) {
+        Pulumi.run(App::stack);
+    }
+
+    public static void stack(Context ctx) {
+        // Create a record
+        var www = new Record("www");
+
+        // Create a page rule
+        var wwwPageRule = new PageRule("wwwPageRule");
+
+    }
+}
+```
+{{% /choosable %}}
+{{< /chooser >}}
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+### Optional
+
+- `apiBasePath` (String) Configure the base path used by the API client. Alternatively, can be configured using the `CLOUDFLARE_API_BASE_PATH` environment variable.
+- `apiClientLogging` (Boolean) Whether to print logs from the API client (using the default log library logger). Alternatively, can be configured using the `CLOUDFLARE_API_CLIENT_LOGGING` environment variable.
+- `apiHostname` (String) Configure the hostname used by the API client. Alternatively, can be configured using the `CLOUDFLARE_API_HOSTNAME` environment variable.
+- `apiKey` (String) The API key for operations. Alternatively, can be configured using the `CLOUDFLARE_API_KEY` environment variable. API keys are [now considered legacy by Cloudflare](https://developers.cloudflare.com/fundamentals/api/get-started/keys/#limitations), API tokens should be used instead. Must provide only one of `apiKey`, `apiToken`, `apiUserServiceKey`.
+- `apiToken` (String) The API Token for operations. Alternatively, can be configured using the `CLOUDFLARE_API_TOKEN` environment variable. Must provide only one of `apiKey`, `apiToken`, `apiUserServiceKey`.
+- `apiUserServiceKey` (String) A special Cloudflare API key good for a restricted set of endpoints. Alternatively, can be configured using the `CLOUDFLARE_API_USER_SERVICE_KEY` environment variable. Must provide only one of `apiKey`, `apiToken`, `apiUserServiceKey`.
+- `email` (String) A registered Cloudflare email address. Alternatively, can be configured using the `CLOUDFLARE_EMAIL` environment variable. Required when using `apiKey`. Conflicts with `apiToken`.
+- `maxBackoff` (Number) Maximum backoff period in seconds after failed API calls. Alternatively, can be configured using the `CLOUDFLARE_MAX_BACKOFF` environment variable.
+- `minBackoff` (Number) Minimum backoff period in seconds after failed API calls. Alternatively, can be configured using the `CLOUDFLARE_MIN_BACKOFF` environment variable.
+- `retries` (Number) Maximum number of retries to perform when an API request fails. Alternatively, can be configured using the `CLOUDFLARE_RETRIES` environment variable.
+- `rps` (Number) RPS limit to apply when making calls to the API. Alternatively, can be configured using the `CLOUDFLARE_RPS` environment variable.
+- `userAgentOperatorSuffix` (String) A value to append to the HTTP User Agent for all API calls. This value is not something most users need to modify however, if you are using a non-standard provider or operator configuration, this is recommended to assist in uniquely identifying your traffic. **Setting this value will remove the Pulumi version from the HTTP User Agent string and may have unintended consequences**. Alternatively, can be configured using the `CLOUDFLARE_USER_AGENT_OPERATOR_SUFFIX` environment variable.
diff --git a/provider/resources.go b/provider/resources.go
@@ -27,6 +27,7 @@ import (
 	pfbridge "github.com/pulumi/pulumi-terraform-bridge/pf/tfbridge"
 	"github.com/pulumi/pulumi-terraform-bridge/v3/pkg/tfbridge"
 	tfbridgetokens "github.com/pulumi/pulumi-terraform-bridge/v3/pkg/tfbridge/tokens"
+	"github.com/pulumi/pulumi-terraform-bridge/v3/pkg/tfgen"
 	shimv2 "github.com/pulumi/pulumi-terraform-bridge/v3/pkg/tfshim/sdk-v2"
 	"github.com/pulumi/pulumi/sdk/v3/go/common/resource"
 
@@ -73,6 +74,7 @@ func Provider() tfbridge.ProviderInfo {
 		UpstreamRepoPath: "./upstream",
 		Version:          version.Version,
 		MetadataInfo:     tfbridge.NewProviderMetadata(metadata),
+		DocRules:         &tfbridge.DocRuleInfo{EditRules: docEditRules},
 		Config: map[string]*tfbridge.SchemaInfo{
 			"rps": {
 				Default: &tfbridge.DefaultInfo{
@@ -199,3 +201,20 @@ func Provider() tfbridge.ProviderInfo {
 
 	return prov
 }
+
+func docEditRules(defaults []tfbridge.DocsEdit) []tfbridge.DocsEdit {
+	return append(
+		defaults,
+		skipGettingStartedSection,
+	)
+}
+
+// Removes a "Getting Started" section that links to a tF tutorial
+var skipGettingStartedSection = tfbridge.DocsEdit{
+	Path: "index.md",
+	Edit: func(_ string, content []byte) ([]byte, error) {
+		return tfgen.SkipSectionByHeaderContent(content, func(headerText string) bool {
+			return headerText == "Getting Started"
+		})
+	},
+}