Add reference docs for Pulumi HCL

content/docs/iac/languages-sdks/hcl/_index.md

@@ -0,0 +1,93 @@
+---
+title_tag: "HCL | Languages & SDKs"
+meta_desc: An overview of Pulumi HCL, a language plugin for writing infrastructure as code in Terraform-like HCL syntax on any cloud.
+title: HCL
+h1: Pulumi & HCL
+meta_image: /images/docs/meta-images/docs-meta.png
+menu:
+    iac:
+        name: HCL
+        parent: iac-languages
+        weight: 7
+        identifier: iac-languages-hcl
+    languages:
+        identifier: hcl-language
+        weight: 7
+
+aliases:
+- /docs/languages-sdks/hcl/
+---
+
+Pulumi supports writing your infrastructure as code using Pulumi HCL, a language plugin that lets you author Pulumi programs in [Terraform](https://developer.hashicorp.com/terraform)-like HCL syntax. You get familiar HCL blocks, expressions, and built-in functions while using Pulumi's state management, secrets handling, and deployment engine.
+
+Pulumi HCL is developed in the [pulumi-labs/pulumi-hcl](https://github.com/pulumi-labs/pulumi-hcl) repository.
+
+## Prerequisites
+
+All you need to use Pulumi HCL is the [Pulumi CLI](/docs/install/), version 3.235.0 or later. The HCL language and converter plugins ship with the CLI.
+
+## Example
+
+A Pulumi HCL project consists of a `Pulumi.yaml` with `runtime: hcl` and one or more `.hcl` files in the project directory.
+
+`Pulumi.yaml`:
+
+```yaml
+name: simple-hcl
+runtime: hcl
+description: A simple Pulumi HCL project
+```
+
+`main.hcl`:
+
+```hcl
+pulumi {
+  required_providers {
+    random = {
+      source  = "pulumi/random"
+      version = ">= 4.0.0"
+    }
+  }
+}
+
+variable "prefix" {
+  type    = string
+  default = "test"
+}
+
+resource "random_pet" "my_pet" {
+  prefix = var.prefix
+  length = 2
+}
+
+output "pet_name" {
+  value = random_pet.my_pet.id
+}
+```
+
+{{% notes "info" %}}
+Provider sources must use the `pulumi/` namespace (for example, `pulumi/aws`), not `hashicorp/`.
+{{% /notes %}}
+
+Further examples are available in the [Pulumi HCL GitHub repository](https://github.com/pulumi-labs/pulumi-hcl/tree/master/examples). The specification for Pulumi HCL programs is in the [Pulumi HCL reference](/docs/iac/languages-sdks/hcl/hcl-language-reference/).
+
+## Pulumi programming model
+
+The Pulumi programming model defines the core concepts you will use when creating infrastructure as code programs using Pulumi. [Concepts](/docs/iac/concepts/) describes these concepts with examples available in all supported languages.
+
+To learn how the Pulumi programming model is implemented for Pulumi HCL, refer to the [Pulumi HCL reference](/docs/iac/languages-sdks/hcl/hcl-language-reference/).
+
+## Terraform compatibility
+
+Pulumi HCL is broadly compatible with Terraform-like HCL syntax. Resources, data sources, variables, locals, outputs, modules, expressions, and most built-in functions work as documented by HashiCorp, with two notable behavioral differences:
+
+- Provider sources must use the `pulumi/` namespace, not `hashicorp/`.
+- Resource replacement creates the new resource before deleting the old one (the opposite of Terraform). Set `create_before_destroy = false` in a `lifecycle` block to opt into delete-first behavior.
+
+For the full list of differences and unsupported features, see the [Terraform compatibility section](/docs/iac/languages-sdks/hcl/hcl-language-reference/#terraform-compatibility) of the reference.
+
+## HCL packages
+
+The [Pulumi Registry](/registry/) houses 100+ packages that can be consumed from Pulumi HCL programs by declaring them in a `pulumi` `required_providers` block.
+
+For Terraform or OpenTofu providers that aren't published in the Pulumi Registry, use [Any Terraform Provider](/docs/iac/concepts/providers/any-terraform-provider/) to generate a local package on the fly. This is especially relevant for Pulumi HCL users who are bringing existing programs from a Terraform codebase that depends on community or internal providers without bridged Pulumi equivalents.

content/docs/iac/languages-sdks/hcl/hcl-component-reference.md

@@ -0,0 +1,104 @@
+---
+title_tag: "Pulumi HCL Component Reference | Languages & SDKs"
+meta_desc: Specification for authoring Pulumi multi-language components in HCL.
+title: Component Reference
+h1: Pulumi HCL component reference
+meta_image: /images/docs/meta-images/docs-meta.png
+menu:
+    iac:
+        name: Component Reference
+        parent: iac-languages-hcl
+        weight: 2
+    languages:
+        parent: hcl-language
+        weight: 2
+---
+
+Pulumi HCL modules can be authored as reusable Pulumi components consumable from any Pulumi language (TypeScript, Python, Go, .NET, Java, YAML, or HCL). This is known as a multi-language component (MLC).
+
+An HCL module becomes an MLC when it has a `PulumiPlugin.yaml` containing `runtime: hcl` and declares a `component` block (and optionally a `package` block) inside the module's `pulumi` block. The rest of the module is an ordinary Pulumi HCL program — see the [Pulumi HCL reference](/docs/iac/languages-sdks/hcl/hcl-language-reference/) for the full program model.
+
+## Example
+
+`PulumiPlugin.yaml`:
+
+```yaml
+runtime: hcl
+```
+
+`main.hcl`:
+
+```hcl
+pulumi {
+  component {
+    name = "VpcNetwork"
+  }
+  package {
+    name    = "my-networking"
+    version = "1.0.0"
+  }
+  required_providers {
+    aws = {
+      source  = "pulumi/aws"
+      version = ">= 6.0"
+    }
+  }
+}
+
+variable "cidr_block" {
+  type    = string
+  default = "10.0.0.0/16"
+}
+
+resource "aws_vpc" "vpc" {
+  cidr_block = var.cidr_block
+}
+
+output "vpc_id" {
+  value = aws_vpc.vpc.id
+}
+```
+
+The module's [`variable`](/docs/iac/languages-sdks/hcl/hcl-language-reference/#variables) blocks become the component's inputs and its [`output`](/docs/iac/languages-sdks/hcl/hcl-language-reference/#outputs) blocks become the component's outputs.
+
+## Component definition
+
+### `component` block
+
+Declares the HCL module as a component resource.
+
+| Field    | Type   | Required | Default   | Description |
+| - | - | - | - | - |
+| `name`   | string | Yes      | —         | Component name. Must be a valid Pulumi name (alphanumeric, hyphens, underscores; must start with a letter or underscore). |
+| `module` | string | No       | `"index"` | Module segment of the component's resource token. Must be a valid Pulumi name. |
+
+### `package` block
+
+Declares the package identity for the component.
+
+| Field     | Type   | Required | Default                         | Description |
+| - | - | - | - | - |
+| `name`    | string | No       | Directory name of the module    | Package name. Must be a valid Pulumi name when specified. |
+| `version` | string | No       | `"0.0.0-dev"`                   | Package version. Must be a valid [semver](https://semver.org/) string when specified. |
+
+Only one `component` block and one `package` block are allowed per `pulumi` block. Using `component` or `package` in a regular Pulumi program (one invoked directly via `pulumi up`) produces an error.
+
+## Resource token
+
+The component's Pulumi resource token is formed as:
+
+```
+{package.name}:{component.module}:{component.name}
+```
+
+For the example above the token is `my-networking:index:VpcNetwork`.
+
+## PulumiPlugin.yaml
+
+The `PulumiPlugin.yaml` file tells the Pulumi engine how to run the component provider. For HCL MLCs it should specify the `hcl` runtime:
+
+```yaml
+runtime: hcl
+```
+
+The `component` and `package` blocks in the HCL source supply the provider name and version, so they do not need to be hardcoded elsewhere.