diff --git a/.ci-mgmt.yaml b/.ci-mgmt.yaml index 1651386..2c4e3e2 100644 --- a/.ci-mgmt.yaml +++ b/.ci-mgmt.yaml @@ -13,3 +13,4 @@ plugins: version: "4.2.0" team: ecosystem pulumiConvert: 1 +registryDocs: true diff --git a/Makefile b/Makefile index a046e99..70de19a 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 0000000..2ce86a3 --- /dev/null +++ b/docs/_index.md @@ -0,0 +1,185 @@ +--- +title: Nomad Provider +meta_desc: Provides an overview on how to configure the Pulumi Nomad provider. +layout: package +--- +## Installation + +The nomad provider is available as a package in all Pulumi languages: + +* JavaScript/TypeScript: [`@pulumi/nomad`](https://www.npmjs.com/package/@pulumi/nomad) +* Python: [`pulumi-nomad`](https://pypi.org/project/pulumi-nomad/) +* Go: [`github.com/pulumi/pulumi-nomad/sdk/v2/go/nomad`](https://github.com/pulumi/pulumi-nomad) +* .NET: [`Pulumi.Nomad`](https://www.nuget.org/packages/Pulumi.Nomad) +* Java: [`com.pulumi/nomad`](https://central.sonatype.com/artifact/com.pulumi/nomad) +## Overview + +[HashiCorp Nomad](https://www.nomadproject.io) is an application scheduler. The +Nomad provider exposes resources to interact with a Nomad cluster. + +Use the navigation to the left to read about the available resources. +## 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: + nomad:address: + value: http://nomad.mycompany.com:4646 + nomad:region: + value: us-east-2 + +``` +```typescript +Example currently unavailable in this language +``` +{{% /choosable %}} +{{% choosable language python %}} +```yaml +# Pulumi.yaml provider configuration file +name: configuration-example +runtime: python +config: + nomad:address: + value: http://nomad.mycompany.com:4646 + nomad:region: + value: us-east-2 + +``` +```python +Example currently unavailable in this language +``` +{{% /choosable %}} +{{% choosable language csharp %}} +```yaml +# Pulumi.yaml provider configuration file +name: configuration-example +runtime: dotnet +config: + nomad:address: + value: http://nomad.mycompany.com:4646 + nomad:region: + value: us-east-2 + +``` +```csharp +Example currently unavailable in this language +``` +{{% /choosable %}} +{{% choosable language go %}} +```yaml +# Pulumi.yaml provider configuration file +name: configuration-example +runtime: go +config: + nomad:address: + value: http://nomad.mycompany.com:4646 + nomad:region: + value: us-east-2 + +``` +```go +Example currently unavailable in this language +``` +{{% /choosable %}} +{{% choosable language yaml %}} +```yaml +# Pulumi.yaml provider configuration file +name: configuration-example +runtime: yaml +config: + nomad:address: + value: http://nomad.mycompany.com:4646 + nomad:region: + value: us-east-2 + +``` +```yaml +Example currently unavailable in this language +``` +{{% /choosable %}} +{{% choosable language java %}} +```yaml +# Pulumi.yaml provider configuration file +name: configuration-example +runtime: java +config: + nomad:address: + value: http://nomad.mycompany.com:4646 + nomad:region: + value: us-east-2 + +``` +```java +Example currently unavailable in this language +``` +{{% /choosable %}} +{{< /chooser >}} +## Configuration Reference + +The following configuration inputs are supported: + +- `address` `(string: "http://127.0.0.1:4646")` - The HTTP(S) API address of the + Nomad agent. This must include the leading protocol (e.g. `https://`). This + can also be specified as the `NOMAD_ADDR` environment variable. + +- `region` `(string: "")` - The Nomad region to target. This can also be + specified as the `NOMAD_REGION` environment variable. + +- `httpAuth` `(string: "")` - HTTP Basic Authentication credentials to be used + when communicating with Nomad, in the format of either `user` or `user:pass`. + This can also be specified using the `NOMAD_HTTP_AUTH` environment variable. + +- `caFile` `(string: "")` - A local file path to a PEM-encoded certificate + authority used to verify the remote agent's certificate. This can also be + specified as the `NOMAD_CACERT` environment variable. + +- `caPem` `(string: "")` - PEM-encoded certificate authority used to verify + the remote agent's certificate. + +- `certFile` `(string: "")` - A local file path to a PEM-encoded certificate + provided to the remote agent. If this is specified, `keyFile` or `keyPem` + is also required. This can also be specified as the `NOMAD_CLIENT_CERT` + environment variable. + +- `certPem` `(string: "")` - PEM-encoded certificate provided to the remote + agent. If this is specified, `keyFile` or `keyPem` is also required. + +- `keyFile` `(string: "")` - A local file path to a PEM-encoded private key. + This is required if `certFile` or `certPem` is specified. This can also be + specified via the `NOMAD_CLIENT_KEY` environment variable. + +- `keyPem` `(string: "")` - PEM-encoded private key. This is required if + `certFile` or `certPem` is specified. + +- `skipVerify` `(boolean: false)` - Set this to true if you want to skip TLS verification on the client side. + This can also be specified via the `NOMAD_SKIP_VERIFY` environment variable. + +- `headers` - (Optional) A configuration block, described below, that provides headers + to be sent along with all requests to Nomad. This block can be specified + multiple times. + +- `vaultToken` `(string: "")` - A Vault token used when [submitting the job](https://www.nomadproject.io/docs/job-specification/job#vault_token). + This can also be specified as the `VAULT_TOKEN` environment variable or using a + Vault token helper (see [Vault's documentation](https://www.vaultproject.io/docs/commands/token-helper.html) + for more details). See below for strategies when + multiple Vault tokens are required. + +- `consulToken` `(string: "")` - A Consul token used when [submitting the job](https://www.nomadproject.io/docs/job-specification/job#consul_token). + This can also be specified as the `CONSUL_HTTP_TOKEN` environment variable. + See below for strategies when multiple Consul tokens are required. + +- `secretId` `(string: "")` - The Secret ID of an ACL token to make requests with, + for ACL-enabled clusters. This can also be specified via the `NOMAD_TOKEN` + environment variable. + +- `ignoreEnvVars` `(map[string]bool: {})` - A map of environment variables + that are ignored by the provider when configuring the Nomad API client. + Supported keys are: `NOMAD_NAMESPACE` and `NOMAD_REGION`. + +The `headers` nested type accepts the following arguments: +* `name` - (Required) The name of the header. +* `value` - (Required) The value of the header. \ No newline at end of file diff --git a/docs/index-md-replaces/env-vars-desired.md b/docs/index-md-replaces/env-vars-desired.md new file mode 100644 index 0000000..21d9836 --- /dev/null +++ b/docs/index-md-replaces/env-vars-desired.md @@ -0,0 +1,7 @@ +- `ignore_env_vars` `(map[string]bool: {})` - A map of environment variables + that are ignored by the provider when configuring the Nomad API client. + Supported keys are: `NOMAD_NAMESPACE` and `NOMAD_REGION`. + +The `headers` nested type accepts the following arguments: +* `name` - (Required) The name of the header. +* `value` - (Required) The value of the header. \ No newline at end of file diff --git a/docs/index-md-replaces/env-vars-input.md b/docs/index-md-replaces/env-vars-input.md new file mode 100644 index 0000000..03832c6 --- /dev/null +++ b/docs/index-md-replaces/env-vars-input.md @@ -0,0 +1,34 @@ +- `ignore_env_vars` `(map[string]bool: {})` - A map of environment variables + that are ignored by the provider when configuring the Nomad API client. + Supported keys are: `NOMAD_NAMESPACE` and `NOMAD_REGION`. When using the + provider within Terraform Cloud, the default value is set to + ``` + { + NOMAD_NAMESPACE: true, + NOMAD_REGION: true, + } + ```. + Set these values to `false` if you need to load these environment variables. + +The `headers` configuration block accepts the following arguments: +* `name` - (Required) The name of the header. +* `value` - (Required) The value of the header. + +An example using the `headers` configuration block with repeated blocks and +headers: +```hcl +provider "nomad" { + headers { + name = "Test-Header-1" + value = "a" + } + headers { + name = "Test-header-1" + value = "b" + } + headers { + name = "test-header-2" + value = "c" + } +} +``` \ No newline at end of file diff --git a/provider/resources.go b/provider/resources.go index 343f849..bbe7806 100644 --- a/provider/resources.go +++ b/provider/resources.go @@ -15,7 +15,10 @@ package nomad import ( + "bytes" "fmt" + "github.com/pulumi/pulumi-terraform-bridge/v3/pkg/tfgen" + "os" "path/filepath" "unicode" @@ -83,6 +86,7 @@ func Provider() tfbridge.ProviderInfo { GitHubOrg: "hashicorp", Repository: "https://github.com/pulumi/pulumi-nomad", Config: map[string]*tfbridge.SchemaInfo{}, + DocRules: &tfbridge.DocRuleInfo{EditRules: docEditRules}, Resources: map[string]*tfbridge.ResourceInfo{ "nomad_acl_policy": {Tok: makeResource(mainMod, "AclPolicy")}, "nomad_acl_role": {Tok: makeResource(mainMod, "AclRole")}, @@ -158,5 +162,63 @@ func Provider() tfbridge.ProviderInfo { return prov } +func docEditRules(defaults []tfbridge.DocsEdit) []tfbridge.DocsEdit { + edits := []tfbridge.DocsEdit{ + cleanUpEnvVars, + } + edits = append(edits, defaults...) + return append( + edits, + skipSections()..., + ) +} + +// Removes sections with TF specific instructions. +func skipSections() []tfbridge.DocsEdit { + edits := []tfbridge.DocsEdit{} + titles := []string{ + "Configuring Multiple Tokens", + "Multi-Region Deployments", + } + for _, title := range titles { + edits = append(edits, tfbridge.DocsEdit{ + Path: "index.html.markdown", + Edit: func(_ string, content []byte) ([]byte, error) { + return tfgen.SkipSectionByHeaderContent(content, func(headerText string) bool { + return headerText == title + }) + }, + }) + } + return edits +} + +// Cleans up TF Cloud specific references from env var documentation. +var cleanUpEnvVars = tfbridge.DocsEdit{ + Path: "index.html.markdown", + Edit: func(_ string, content []byte) ([]byte, error) { + replacesDir := "docs/index-md-replaces/" + input, err := os.ReadFile(replacesDir + "env-vars-input.md") + if err != nil { + return nil, err + } + desired, err := os.ReadFile(replacesDir + "env-vars-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.html.markdown, "+ + "please verify file content at %s\n*****\n%s\n*****\n", replacesDir+"overview-input.md", string(input)) + } + return content, nil + }, +} + //go:embed cmd/pulumi-resource-nomad/bridge-metadata.json var metadata []byte