pulumi/pkg/codegen/docs/templates/resource.tmpl

{{ template "header" .Header }}

{{ htmlSafe "<!-- WARNING: this file was generated by" }} {{ .Tool }}. {{ htmlSafe "-->" }}
{{ htmlSafe "<!-- Do not edit by hand unless you're certain you know what you are doing! -->" }}

{{- if .DeprecationMessage }}
<div class="resource-deprecated">Deprecated: {{ markdownify .DeprecationMessage -}}</div>
{{- end }}

{{ htmlSafe .Comment }}

{{- if ne (len .ExamplesSection) 0 }}
{{ template "examples" .ExamplesSection }}
{{- end }}

<!-- Create resource -->
## Create {{ .Header.Title }} Resource {#create}

Resources are created with functions called constructors. To learn more about declaring and configuring resources, see [Resources](/docs/concepts/resources/).

### Constructor syntax

{{- if eq .LangChooserLanguages "" }}
<div>
<pulumi-chooser type="language" options="typescript,python,go,csharp,java,yaml"></pulumi-chooser>
</div>
{{- else }}
<div>
<pulumi-chooser type="language" options="{{ .LangChooserLanguages }}"></pulumi-chooser>
</div>
{{- end }}

{{/*
    Render the specific snippet to construct the resource, e.g.
    "new Bucket(name: string, args?: BucketArgs, opts?: pulumi.ResourceOptions);"
    "def Bucket(resource_name, opts=None, acceleration_status=None, ..."
*/}}
<div>
<pulumi-choosable type="language" values="javascript,typescript">
<div class="no-copy"><div class="highlight"><pre class="chroma"><code class="language-typescript" data-lang="typescript"><span class="k">new </span>{{ template "linkify_param" .ConstructorResource.nodejs }}<span class="p">(</span>{{ htmlSafe .ConstructorParams.nodejs }}<span class="p">);</span></code></pre></div>
</div></pulumi-choosable>
</div>

<div>
<pulumi-choosable type="language" values="python">
<div class="no-copy"><div class="highlight"><pre class="chroma"><code class="language-python" data-lang="python"><span class=nd>@overload</span>
<span class="k">def </span>{{ template "linkify_param" .ConstructorResource.python }}<span class="p">(</span>{{ htmlSafe .ConstructorParams.pythonargs }}<span class="p">)</span>
<span></span>
<span class=nd>@overload</span>
<span class="k">def </span>{{ template "linkify_param" .ConstructorResource.python }}<span class="p">(</span>{{ htmlSafe .ConstructorParams.python }}<span class="p">)</span></code></pre></div>
</div></pulumi-choosable>
</div>

<div>
<pulumi-choosable type="language" values="go">
<div class="no-copy"><div class="highlight"><pre class="chroma"><code class="language-go" data-lang="go"><span class="k">func </span>{{ template "linkify_go_param" .ConstructorResource.go }}<span class="p">(</span>{{ htmlSafe .ConstructorParams.go }}<span class="p">) (*{{ template "linkify_param" .ConstructorResource.go }}, error)</span></code></pre></div>
</div></pulumi-choosable>
</div>

<div>
<pulumi-choosable type="language" values="csharp">
<div class="no-copy"><div class="highlight"><pre class="chroma"><code class="language-csharp" data-lang="csharp"><span class="k">public </span>{{ template "linkify_param" .ConstructorResource.csharp }}<span class="p">(</span>{{ htmlSafe .ConstructorParams.csharp }}<span class="p">)</span></code></pre></div>
</div></pulumi-choosable>
</div>

<div>
<pulumi-choosable type="language" values="java">
<div class="no-copy"><div class="highlight"><pre class="chroma">
<code class="language-java" data-lang="java"><span class="k">public </span>{{ template "linkify_param" .ConstructorResource.java }}<span class="p">(</span>{{ htmlSafe .ConstructorParams.javaargs }}<span class="p">)</span>
<span class="k">public </span>{{ template "linkify_param" .ConstructorResource.java }}<span class="p">(</span>{{ htmlSafe .ConstructorParams.java }}<span class="p">)</span>
</code></pre></div></div>
</pulumi-choosable>
</div>

<div>
<pulumi-choosable type="language" values="yaml">
<div class="no-copy"><div class="highlight"><pre class="chroma"><code class="language-yaml" data-lang="yaml">type: {{ template "linkify_param" .ConstructorResource.yaml }}<span class="p"></span>
{{ template "yaml_constructor" .ConstructorParamsTyped.yaml }}
</code></pre></div></div>
</pulumi-choosable>
</div>

#### Parameters

<div>
<pulumi-choosable type="language" values="javascript,typescript">
{{ template "constructor_args" .ConstructorParamsTyped.nodejs }}
</pulumi-choosable>
</div>

<div>
<pulumi-choosable type="language" values="python">
{{ template "constructor_args" .ConstructorParamsTyped.pythonargs }}
</pulumi-choosable>
</div>

<div>
<pulumi-choosable type="language" values="go">
{{ template "constructor_args" .ConstructorParamsTyped.go }}
</pulumi-choosable>
</div>

<div>
<pulumi-choosable type="language" values="csharp">
{{ template "constructor_args" .ConstructorParamsTyped.csharp }}
</pulumi-choosable>
</div>

<div>
<pulumi-choosable type="language" values="java">
{{ template "constructor_args" .ConstructorParamsTyped.java }}
</pulumi-choosable>
</div>

{{ if ne (len .CreationExampleSyntax) 0 }}

### Example

The following reference example uses placeholder values for all [input properties](#inputs).

{{- if eq .LangChooserLanguages "" }}
<div>
<pulumi-chooser type="language" options="typescript,python,go,csharp,java,yaml"></pulumi-chooser>
</div>
{{- else }}
<div>
<pulumi-chooser type="language" options="{{ .LangChooserLanguages }}"></pulumi-chooser>
</div>
{{- end }}

{{ range $lang, $code := .CreationExampleSyntax }}
<div>
{{ htmlSafe "<pulumi-choosable type=\"language\" values=\"" }}{{ $lang }}{{ htmlSafe "\">" }}

```{{ $lang }}
{{ htmlSafe $code }}
```

</pulumi-choosable>
</div>

{{ end }}
{{- end }}

## {{ .Header.Title }} Resource Properties {#properties}

To learn more about resource properties and how to use them, see [Inputs and Outputs](/docs/intro/concepts/inputs-outputs) in the Architecture and Concepts docs.

### Inputs

The {{ .Header.Title }} resource accepts the following [input](/docs/intro/concepts/inputs-outputs) properties:

{{ template "properties" .InputProperties }}

<!-- Output properties -->
### Outputs

All [input](#inputs) properties are implicitly available as output properties. Additionally, the {{ .Header.Title }} resource produces the following output properties:

{{ template "properties" .OutputProperties }}

<!-- Methods -->
{{- if ne (len .Methods) 0 }}
## {{ .Header.Title }} Resource Methods {#methods}

{{ range .Methods }}
### {{ .Title }} Method {#method_{{ .Title }}}

{{- if .DeprecationMessage }}
<div class="resource-deprecated">Deprecated: {{ markdownify .DeprecationMessage -}}</div>
{{- end }}

{{ htmlSafe .Comment }}
{{- if ne (len .ExamplesSection) 0 }}
{{ template "examples" .ExamplesSection }}
{{- end }}

#### Using {{ .Title }}

<div>
<pulumi-chooser type="language" options="typescript,python,go,csharp,java,yaml"></pulumi-chooser>
</div>

<!-- TS/JS -->
<div>
<pulumi-choosable type="language" values="javascript,typescript">
<div class="highlight"><pre class="chroma"><code class="language-typescript" data-lang="typescript">{{ .MethodName.nodejs }}<span class="p">(</span>{{ if ne .MethodArgs.nodejs "" }}{{ htmlSafe .MethodArgs.nodejs }}{{ end }}<span class="p">): {{ if ne .MethodResult.nodejs.Name "" }}Output&lt;{{ template "linkify_param" .MethodResult.nodejs }}&gt;{{ else }}void{{ end }}</span></code></pre></div>
</pulumi-choosable>
</div>

<!-- Python -->
<div>
<pulumi-choosable type="language" values="python">
<div class="highlight"><pre class="chroma"><code class="language-python" data-lang="python"><span class="k">def </span>{{ .MethodName.python }}(</span>{{ if ne .MethodArgs.python "" }}{{ htmlSafe .MethodArgs.python }}{{ end }}<span class="p">) -&gt;</span> {{ if ne .MethodResult.python.Name "" }}Output[{{ template "linkify_param" .MethodResult.python }}]{{ else }}None{{ end }}</code></pre></div>
</pulumi-choosable>
</div>

<!-- Go -->
<div>
<pulumi-choosable type="language" values="go">
<div class="highlight"><pre class="chroma"><code class="language-go" data-lang="go"><span class="k">func</span> <span class="p">(r *{{ .ResourceName }})</span> {{ .MethodName.go }}<span class="p">(</span>{{ if ne .MethodArgs.go "" }}{{ htmlSafe .MethodArgs.go }}{{ end }}<span class="p">) {{ if ne .MethodResult.go.Name "" }}({{ template "linkify_param" .MethodResult.go }}, error){{ else }}error{{ end }}</span></code></pre></div>
</pulumi-choosable>
</div>

<!-- C# -->
<div>
<pulumi-choosable type="language" values="csharp">
<div class="highlight"><pre class="chroma"><code class="language-csharp" data-lang="csharp"><span class="k">public </span>{{ if ne .MethodResult.csharp.Name "" }}Output&lt;{{ template "linkify_param" .MethodResult.csharp }}&gt;{{ else }}void{{ end }} <span class="nx">{{ .MethodName.csharp }}</span><span class="p">({{ if ne .MethodArgs.csharp "" }}{{ htmlSafe .MethodArgs.csharp }}{{ end }})</span></code></pre></div>
</pulumi-choosable>
</div>

{{ if ne (len .InputProperties) 0 }}

The following arguments are supported:
{{ template "properties" .InputProperties }}
{{ end }}

{{ if ne (len .OutputProperties) 0 }}
#### {{ .Title }} Result {#method_{{ .Title }}_result}
{{ template "properties" .OutputProperties }}
{{ end }}

{{ end }}
{{- end -}}

<!-- Read resource -->
{{ if ne (len .StateInputs) 0 }}
## Look up Existing {{.Header.Title}} Resource {#look-up}

Get an existing {{.Header.Title}} resource's state with the given name, ID, and optional extra properties used to qualify the lookup.

{{- if eq .LangChooserLanguages "" }}
<div>
<pulumi-chooser type="language" options="typescript,python,go,csharp,java,yaml"></pulumi-chooser>
</div>
{{- else }}
<div>
<pulumi-chooser type="language" options="{{ .LangChooserLanguages }}"></pulumi-chooser>
</div>
{{- end }}

<div>
<pulumi-choosable type="language" values="javascript,typescript">
<div class="no-copy"><div class="highlight"><pre class="chroma"><code class="language-typescript" data-lang="typescript"><span class="k">public static </span><span class="nf">get</span><span class="p">(</span>{{ htmlSafe .LookupParams.nodejs }}<span class="p">): </span>{{ template "linkify_param" .ConstructorResource.nodejs }}</code></pre></div>
</div></pulumi-choosable>
</div>

<div>
<pulumi-choosable type="language" values="python">
<div class="no-copy"><div class="highlight"><pre class="chroma"><code class="language-python" data-lang="python"><span class=nd>@staticmethod</span>
<span class="k">def </span><span class="nf">get</span><span class="p">(</span><span class="nx">resource_name</span><span class="p">:</span> <span class="nx">str</span><span class="p">,</span>
        <span class="nx">id</span><span class="p">:</span> <span class="nx">str</span><span class="p">,</span>
        <span class="nx">opts</span><span class="p">:</span> <span class="nx"><a href="/docs/reference/pkg/python/pulumi/#pulumi.ResourceOptions">Optional[ResourceOptions]</a></span> = None<span class="p">,</span>
        {{ htmlSafe .LookupParams.python }}<span class="p">) -&gt;</span> {{ .ConstructorResource.python.Name }}</code></pre></div>
</div></pulumi-choosable>
</div>

<div>
<pulumi-choosable type="language" values="go">
<div class="no-copy"><div class="highlight"><pre class="chroma"><code class="language-go" data-lang="go"><span class="k">func </span>Get{{ .Header.Title }}<span class="p">(</span>{{ htmlSafe .LookupParams.go }}<span class="p">) (*{{ template "linkify_param" .ConstructorResource.go }}, error)</span></code></pre></div>
</div></pulumi-choosable>
</div>

<div>
<pulumi-choosable type="language" values="csharp">
<div class="no-copy"><div class="highlight"><pre class="chroma"><code class="language-csharp" data-lang="csharp"><span class="k">public static </span>{{ template "linkify_param" .ConstructorResource.csharp }}<span class="nf"> Get</span><span class="p">(</span>{{ htmlSafe .LookupParams.csharp }}<span class="p">)</span></code></pre></div>
</div></pulumi-choosable>
</div>

<div>
<pulumi-choosable type="language" values="java">
<div class="no-copy"><div class="highlight"><pre class="chroma"><code class="language-java" data-lang="java"><span class="k">public static </span>{{ template "linkify_param" .ConstructorResource.java }}<span class="nf"> get</span><span class="p">(</span>{{ htmlSafe .LookupParams.java }}<span class="p">)</span></code></pre></div>
</div></pulumi-choosable>
</div>

<div>
<pulumi-choosable type="language" values="yaml">
<div class="no-copy"><div class="highlight"><pre class="chroma"><code class="language-yaml" data-lang="yaml">Resource lookup is not supported in YAML</code></pre></div>
</div></pulumi-choosable>
</div>

<div>
<pulumi-choosable type="language" values="javascript,typescript">
{{ template "read_inputs" }}
</pulumi-choosable>
</div>

<div>
<pulumi-choosable type="language" values="python">
<dl class="resources-properties">
    <dt class="property-required" title="Required">
        <span>resource_name</span>
        <span class="property-indicator"></span>
    </dt>
    <dd>The unique name of the resulting resource.</dd>
    <dt class="property-required" title="Optional">
        <span>id</span>
        <span class="property-indicator"></span>
    </dt>
    <dd>The <em>unique</em> provider ID of the resource to lookup.</dd>
</dl>
</pulumi-choosable>
</div>

<div>
<pulumi-choosable type="language" values="go">
{{ template "read_inputs" }}
</pulumi-choosable>
</div>

<div>
<pulumi-choosable type="language" values="csharp">
{{ template "read_inputs" }}
</pulumi-choosable>
</div>

<div>
<pulumi-choosable type="language" values="java">
{{ template "read_inputs" }}
</pulumi-choosable>
</div>

<div>
<pulumi-choosable type="language" values="typescript,javascript,python,go,csharp,java">
The following state arguments are supported:
{{ template "properties" .StateInputs }}
</pulumi-choosable>
</div>

{{ end }}

<!-- Supporting types -->
{{ if ne (len .NestedTypes) 0 }}

## Supporting Types

{{- if ge (len .NestedTypes) .MaxNestedTypes }}
> **Note:** There are over {{ .MaxNestedTypes }} nested types for this resource.
Only the first {{ .MaxNestedTypes }} types are included in this documentation.
{{ end }}

{{ range $index, $elem := .NestedTypes }}
{{ if lt $index $.MaxNestedTypes }}
<h4 id="{{ $elem.AnchorID }}">
{{ htmlSafe $elem.Name }}<pulumi-choosable type="language" values="python,go" class="inline">, {{ htmlSafe $elem.Name }}<wbr>Args</pulumi-choosable>
</h4>

{{- if $elem.Properties }}{{template "properties" $elem.Properties -}}{{ end -}}
{{- if $elem.EnumValues }}{{- template "enums" $elem.EnumValues -}}{{ end -}}
{{- end -}}
{{- end -}}
{{- end -}}

{{ if .ImportDocs  }}

## Import

{{ htmlSafe .ImportDocs }}

To learn more about importing existing cloud resources, see [Importing resources](/docs/using-pulumi/adopting-pulumi/import/).

{{ end }}

{{ template "package_details" .PackageDetails }}