From c824cc44bb7db68637c0f3e9a912ad24becd6614 Mon Sep 17 00:00:00 2001 From: Guinevere Saenger Date: Wed, 30 Oct 2024 17:58:18 -0700 Subject: [PATCH] Add provider installation docs and automation (#465) This PR automates docsgen for this provider's installation doc. Part of pulumi/home#3598. - **Add docs automation** - **Add a find/replace so we can translate the example** --- .ci-mgmt.yaml | 1 + Makefile | 6 +- docs/_index.md | 143 +++++++++++++++++++++ docs/index-md-replaces/examples-desired.md | 10 ++ docs/index-md-replaces/examples-input.md | 21 +++ provider/resources.go | 36 ++++++ 6 files changed, 216 insertions(+), 1 deletion(-) create mode 100644 docs/_index.md create mode 100644 docs/index-md-replaces/examples-desired.md create mode 100644 docs/index-md-replaces/examples-input.md diff --git a/.ci-mgmt.yaml b/.ci-mgmt.yaml index de5a5997..14ae87eb 100644 --- a/.ci-mgmt.yaml +++ b/.ci-mgmt.yaml @@ -8,6 +8,7 @@ env: makeTemplate: bridged team: ecosystem pulumiConvert: 1 +registryDocs: true plugins: - name: terraform version: "1.0.16" diff --git a/Makefile b/Makefile index a6ac1de5..329e735d 100644 --- a/Makefile +++ b/Makefile @@ -29,7 +29,7 @@ development: install_plugins provider build_sdks install_sdks build: install_plugins provider build_sdks install_sdks -build_sdks: build_nodejs build_python build_dotnet build_go build_java +build_sdks: build_nodejs build_python build_dotnet build_go build_java build_registry_docs install_go_sdk: @@ -96,6 +96,10 @@ build_python: upstream cd ./bin && \ ../venv/bin/python -m build . +# Run the bridge's registry-docs command to generated the content of the installation docs/ folder at provider repo root +build_registry_docs: + $(WORKING_DIR)/bin/$(TFGEN) registry-docs --out $(WORKING_DIR)/docs + clean: rm -rf sdk/{dotnet,nodejs,go,python} diff --git a/docs/_index.md b/docs/_index.md new file mode 100644 index 00000000..d5c7728b --- /dev/null +++ b/docs/_index.md @@ -0,0 +1,143 @@ +--- +title: Splunk Provider +meta_desc: Provides an overview on how to configure the Pulumi Splunk provider. +layout: package +--- +## Installation + +The splunk provider is available as a package in all Pulumi languages: + +* JavaScript/TypeScript: [`@pulumi/splunk`](https://www.npmjs.com/package/@pulumi/splunk) +* Python: [`pulumi-splunk`](https://pypi.org/project/pulumi-splunk/) +* Go: [`github.com/pulumi/pulumi-splunk/sdk/go/splunk`](https://github.com/pulumi/pulumi-splunk) +* .NET: [`Pulumi.Splunk`](https://www.nuget.org/packages/Pulumi.Splunk) +* Java: [`com.pulumi/splunk`](https://central.sonatype.com/artifact/com.pulumi/splunk) +## Overview + +The Splunk provider can interact with the resources supported by Splunk. 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: + splunk:insecureSkipVerify: + value: true + splunk:password: + value: changeme + splunk:url: + value: localhost:8089 + splunk:username: + value: admin + +``` + +{{% /choosable %}} +{{% choosable language python %}} +```yaml +# Pulumi.yaml provider configuration file +name: configuration-example +runtime: python +config: + splunk:insecureSkipVerify: + value: true + splunk:password: + value: changeme + splunk:url: + value: localhost:8089 + splunk:username: + value: admin + +``` + +{{% /choosable %}} +{{% choosable language csharp %}} +```yaml +# Pulumi.yaml provider configuration file +name: configuration-example +runtime: dotnet +config: + splunk:insecureSkipVerify: + value: true + splunk:password: + value: changeme + splunk:url: + value: localhost:8089 + splunk:username: + value: admin + +``` + +{{% /choosable %}} +{{% choosable language go %}} +```yaml +# Pulumi.yaml provider configuration file +name: configuration-example +runtime: go +config: + splunk:insecureSkipVerify: + value: true + splunk:password: + value: changeme + splunk:url: + value: localhost:8089 + splunk:username: + value: admin + +``` + +{{% /choosable %}} +{{% choosable language yaml %}} +```yaml +# Pulumi.yaml provider configuration file +name: configuration-example +runtime: yaml +config: + splunk:insecureSkipVerify: + value: true + splunk:password: + value: changeme + splunk:url: + value: localhost:8089 + splunk:username: + value: admin + +``` + +{{% /choosable %}} +{{% choosable language java %}} +```yaml +# Pulumi.yaml provider configuration file +name: configuration-example +runtime: java +config: + splunk:insecureSkipVerify: + value: true + splunk:password: + value: changeme + splunk:url: + value: localhost:8089 + splunk:username: + value: admin + +``` + +{{% /choosable %}} +{{< /chooser >}} +## Configuration Reference + +Below arguments for the provider can also be set as environment variables. + +* `url` or `SPLUNK_URL` - (Required) The URL for the Splunk instance to be configured. (The provider uses `https` as the default schema as prefix to the URL) +* `username` or `SPLUNK_USERNAME` - (Optional) The username to access the Splunk instance to be configured. +* `password` or `SPLUNK_PASSWORD` - (Optional) The password to access the Splunk instance to be configured. +* `authToken` or `SPLUNK_AUTH_TOKEN` - (Optional) Use auth token instead of username and password to configure Splunk instance. + If specified, auth token takes priority over username/password. +* `insecureSkipVerify` or `SPLUNK_INSECURE_SKIP_VERIFY` - (Optional) Insecure skip verification flag (Defaults to `true`) +* `timeout` or `SPLUNK_TIMEOUT` - (Optional) Timeout when making calls to Splunk server. (Defaults to `60 seconds`) + +(NOTE: Auth token can only be used with certain type of Splunk deployments. +Read more on authentication with tokens here: ) \ No newline at end of file diff --git a/docs/index-md-replaces/examples-desired.md b/docs/index-md-replaces/examples-desired.md new file mode 100644 index 00000000..733a08d8 --- /dev/null +++ b/docs/index-md-replaces/examples-desired.md @@ -0,0 +1,10 @@ +## Example Usage + +```terraform +provider "splunk" { + url = "localhost:8089" + username = "admin" + password = "changeme" + insecure_skip_verify = true +} +``` \ No newline at end of file diff --git a/docs/index-md-replaces/examples-input.md b/docs/index-md-replaces/examples-input.md new file mode 100644 index 00000000..a5006bb9 --- /dev/null +++ b/docs/index-md-replaces/examples-input.md @@ -0,0 +1,21 @@ +## Example Usage + +``` +provider "splunk" { + url = "localhost:8089" + username = "admin" + password = "changeme" + insecure_skip_verify = true +} +``` + +Terraform 0.13 and later must add: +``` +terraform { + required_providers { + splunk = { + source = "splunk/splunk" + } + } +} +``` \ No newline at end of file diff --git a/provider/resources.go b/provider/resources.go index 2d15f252..a8abb5f7 100644 --- a/provider/resources.go +++ b/provider/resources.go @@ -15,7 +15,9 @@ package splunk import ( + "bytes" "fmt" + "os" "path/filepath" "unicode" @@ -77,6 +79,7 @@ func Provider() tfbridge.ProviderInfo { Repository: "https://github.com/pulumi/pulumi-splunk", GitHubOrg: "splunk", Config: map[string]*tfbridge.SchemaInfo{}, + DocRules: &tfbridge.DocRuleInfo{EditRules: docEditRules}, Resources: map[string]*tfbridge.ResourceInfo{ "splunk_admin_saml_groups": { Tok: makeResource(mainMod, "AdminSamlGroups"), @@ -246,3 +249,36 @@ func Provider() tfbridge.ProviderInfo { return prov } +func docEditRules(defaults []tfbridge.DocsEdit) []tfbridge.DocsEdit { + return append( + defaults, + cleanUpExample, + ) +} + +var cleanUpExample = tfbridge.DocsEdit{ + Path: "index.md", + Edit: func(_ string, content []byte) ([]byte, error) { + replacesDir := "docs/index-md-replaces/" + + input, err := os.ReadFile(replacesDir + "examples-input.md") + if err != nil { + return nil, err + } + desired, err := os.ReadFile(replacesDir + "examples-desired.md") + if err != nil { + return nil, err + } + if bytes.Contains(content, input) { + content = bytes.ReplaceAll( + content, + input, + desired) + } else { + // Hard error to ensure we keep this content up to date + return nil, fmt.Errorf("could not find text in upstream index.md, "+ + "please verify file content at %s\n*****\n%s\n*****\n", replacesDir+"overview-input.md", string(input)) + } + return content, nil + }, +}