From acfa3c16d72dd58bf0f51efc2dacf1b8e416b0c6 Mon Sep 17 00:00:00 2001 From: Fraser Waters Date: Tue, 20 Jan 2026 16:32:55 +0000 Subject: [PATCH] New HCL language docs --- content/docs/iac/languages-sdks/hcl/_index.md | 109 ++++++ .../hcl/hcl-language-reference.md | 336 ++++++++++++++++++ 2 files changed, 445 insertions(+) create mode 100644 content/docs/iac/languages-sdks/hcl/_index.md create mode 100644 content/docs/iac/languages-sdks/hcl/hcl-language-reference.md diff --git a/content/docs/iac/languages-sdks/hcl/_index.md b/content/docs/iac/languages-sdks/hcl/_index.md new file mode 100644 index 000000000000..3e7bb31ba390 --- /dev/null +++ b/content/docs/iac/languages-sdks/hcl/_index.md @@ -0,0 +1,109 @@ +--- +title_tag: "HCL | Languages & SDKs" +meta_desc: An overview of how to use Pulumi HCL for infrastructure as code on any cloud (AWS, Azure, Google Cloud, Kubernetes, etc.). +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 +--- + +Pulumi supports writing your infrastructure as code using Pulumi HCL. Pulumi HCL is a +configuration language designed to provider a familiar experience for users transitioning from Terraform while embracing Pulumi's programming model. It supports managing infrastructure on any cloud, including Azure, AWS, and Google Cloud. + +## Prerequisites + +All you need to use Pulumi HCL is the [Pulumi CLI](/docs/install/). + +## Example + +```hcl +resource "myBucket" "aws:s3/bucket:Bucket" { +} + +resource "myBucketWebsite" "aws:s3/bucketWebsiteConfigurationV2:BucketWebsiteConfigurationV2" { + bucket = myBucket.bucket + indexDocument = { + suffix = "index.html" + } +} + +resource "ownershipControls" "aws:s3/bucketOwnershipControls:BucketOwnershipControls" { + bucket = myBucket.id + rule = { + objectOwnership = "ObjectWriter" + } +} + +resource "publicAccessBlock" "aws:s3/bucketPublicAccessBlock:BucketPublicAccessBlock" { + bucket = myBucket.id + blockPublicAcls = false +} + +resource "indexHtml" "aws:s3/bucketObject:BucketObject" { + bucket = myBucket.id + source = "

Hello, world!

" + acl = "public-read" + contentType = "text/html" + options { + dependsOn = [ownershipControls, publicAccessBlock] + } +} + +output "bucketEndpoint" { + value = "http://${myBucket.websiteEndpoint}" +} +``` + +Further examples are available in the [Pulumi examples repository](https://github.com/pulumi/examples). The specification for Pulumi HCL documents is in the [Pulumi HCL reference](/docs/iac/languages-sdks/hcl/hcl-language-reference/). + +## Templates + +The fastest way to start a new project is to use a template. The template will initialize a Pulumi +project and set up starter resources for the chosen cloud. The `hcl` template is cloud agnostic. + +- `pulumi new aws-hcl`: creates a starter AWS Pulumi HCL project +- `pulumi new azure-hcl`: creates a starter Azure Pulumi HCL project +- `pulumi new gcp-hcl`: creates a starter Google Cloud Pulumi HCL project +- `pulumi new kubernetes-hcl`: creates a starter Kubernetes Pulumi HCL project + +By default, `pulumi new` provides a number of templates provided by Pulumi, but it can also use your own custom templates. + +To learn more about building and working with custom templates, see [Custom Templates](/docs/idp/developer-portals/templates) and the [`pulumi new`](/docs/cli/commands/pulumi_new/) docs. + +You can also convert existing Terraform HCL projects to Pulumi HCL using the `pulumi convert` command: + +```bash +pulumi convert --from terraform --language pcl +``` + +This will convert your Terraform files to HCL (`.hcl` files) that you can then use with Pulumi. + +## Pulumi programming model + +The Pulumi programming model defines the core concepts you will use when creating infrastructure as code programs using Pulumi. [Concepts](/docs/intro/concepts) describes these concepts with examples available in all supported languages, including Pulumi HCL. + +To learn how the Pulumi programming model is implemented for Pulumi HCL, refer to the [Pulumi HCL reference guide](/docs/iac/languages-sdks/hcl/hcl-language-reference/). + +## Converting from Terraform + +Pulumi HCL provides an excellent migration path for Terraform users: + +1. **Automated conversion**: Use `pulumi convert --from terraform --language pcl` to automatically convert Terraform HCL to Pulumi HCL +1. **Familiar syntax**: Pulumi HCL is inspired by Terraform's HCL, making it easy to read and understand +1. **Enhanced capabilities**: Access Pulumi's state management, secrets, and stack features while using familiar syntax + +After conversion, you may need to make manual adjustments such as: + +- Reviewing naming conventions (Pulumi uses camelCase) +- Verifying resource types are correctly mapped +- Updating function calls where needed +- Testing with `pulumi preview` + +## HCL packages + +The [Pulumi Registry](/registry/) houses 100+ HCL packages. diff --git a/content/docs/iac/languages-sdks/hcl/hcl-language-reference.md b/content/docs/iac/languages-sdks/hcl/hcl-language-reference.md new file mode 100644 index 000000000000..d0afb8cd97da --- /dev/null +++ b/content/docs/iac/languages-sdks/hcl/hcl-language-reference.md @@ -0,0 +1,336 @@ +--- +title_tag: "Pulumi HCL Reference | Languages & SDKs" +meta_desc: Specification for the Pulumi HCL format and built-in functions +title: Reference +h1: Pulumi HCL reference +meta_image: /images/docs/meta-images/docs-meta.png +menu: + iac: + name: Reference + parent: iac-languages-hcl + weight: 1 + languages: + parent: hcl-language + weight: 1 +--- + +Pulumi programs can be defined in many languages, and the Pulumi HCL dialect offers an additional language for authoring Pulumi programs. + +HCL programs are written in `.hcl` files. The programs include several top-level constructs: + +| Type | Block or Expression | Description | +| - | - | - | +| `config` | Block | Config specifies the [Pulumi config](/docs/concepts/config/) inputs to the deployment. | +| `resources` | Block | Resources declares the [Pulumi resources](/docs/concepts/resources/) that will be deployed and managed by the program | +| `variables` | Expression | Variables specifies intermediate values of the program, the values of variables are expressions that can be re-used. | +| `outputs` | Block | Outputs specifies the [Pulumi stack outputs](/docs/concepts/stack#outputs) of the program and how they are computed from the `resources` is a value of the appropriate type for the template to use if no value is specified. | + +## Config + +`config` is a map of config property keys to either values or structured declarations ([see here](/docs/reference/pulumi-hcl/#config-options)). + +### Basic syntax + +```hcl +config name "type" { + description = "Optional description" + default = value +} +``` + +| Property | Type | Required | Description | +| - | - | - | - | +| *name* | string | Yes | The logical name by which this config input will be referenced. | +| *type* | string | Yes | Type is the (required) data type for the parameter. | +| `description` | string | No | Human-readable description of the config value. | +| `default` | any | No | Default is a value of the appropriate type for the template to use if no value is specified. | +| `secret` | bool | No | Secret specifies if the config value should be encrypted as a secret. | + +### Type specifications + +PCL supports the following types: + +**Primitive types:** +- `string` - Text values +- `number` - Numeric values (integers and floats) +- `bool` - Boolean values (true/false) + +**Collection types:** +- `list(T)` - Ordered sequences +- `map(T)` - String key to value mappings + +**Structural types:** +- `object({key=type, ...})` - Objects with specific fields + +**Special types:** +- `any` - Any type (avoid when possible for type safety) + +### Accessing config values + +Reference configuration values directly by their name: + +```hcl +resource "vpc" "aws:ec2/vpc:Vpc" { + cidrBlock = "10.0.0.0/16" + tags = tags // References config "tags" +} +``` + +## Resources + +`resource` blocks represent a resource which will be managed by the Pulumi program. + +### Resource syntax + +```hcl +resource "" { + __logicalName = "" + = + ... +} +``` + +| Component | Description | +| - | - | +| *name* | The local identifier (camelCase). | +| *type* | Fully qualified resource type in format `package:module/submodule:ResourceType`. | +| `__logicalName` | Optional original Terraform name for compatibility. | +| *properties* | Resource-specific configuration. | +| `options` | Options contains all resource options supported by Pulumi. | + +#### Resource Options + +The value of the `options` property of a resource is an object whose keys are [resource option names](/docs/concepts/options/) and whose values are elements of the schema below. No resource options are required. + + +| Property | Type | Description | +| - | - | - | +| `additionalSecretOutputs` | list(string) | AdditionalSecretOutputs specifies properties that must be encrypted as secrets | +| `aliases` | string[] | Aliases specifies names that this resource used to have, so that renaming or refactoring doesn’t replace it | +| `customTimeouts` | [Custom Timeout](#custom-timeout) | CustomTimeouts overrides the default retry/timeout behavior for resource provisioning | +| `deleteBeforeReplace` | bool | DeleteBeforeReplace overrides the default create-before-delete behavior when replacing | +| `dependsOn` | list(any) | DependsOn makes this resource explicitly depend on another resource, by name, so that it won't be created before the dependent finishes being created (and the reverse for destruction). Normally, Pulumi automatically tracks implicit dependencies through inputs/outputs, but this can be used when dependencies aren't captured purely from input/output edges.| +| `ignoreChanges` | list(string) | IgnoreChanges declares that changes to certain properties should be ignored during diffing | +| `import` | string | Import adopts an existing resource from your cloud account under the control of Pulumi | +| `parent` | resource | Parent specifies a parent for the resource | +| `protect` | bool | Protect prevents accidental deletion of a resource | +| `provider` | resource | Provider specifies an explicitly configured provider, instead of using the default global provider | +| `providers` | map[string]resource | Map of providers for a resource and its children. | +| `version` | string | Version specifies a provider plugin version that should be used when operating on a resource | +| `pluginDownloadURL` | string | PluginDownloadURL specifies a provider plugin download URL | +| `replaceOnChanges` | list(string) | ReplaceOnChanges specifies if changes to certain properties on a resource should force replacement instead of an in-place update. | +| `retainOnDelete` | bool | RetainOnDelete causes a resource to be preserved in the cloud even when it is deleted from the Pulumi state. | +| `range` | list(any) or number | Create multiple instances of a resource using the `range` option. | + +## Data sources (invoke) + +Data sources allow you to query existing infrastructure or compute values without creating resources. In HCL, data sources use the `invoke` function. + +### Basic invoke + +```hcl +ami = invoke("aws:ec2/getAmi:getAmi", { + mostRecent = true + owners = ["amazon"] + filters = [{ + name = "name" + values = ["amzn2-ami-hvm-*-x86_64-gp2"] + }] +}) + +resource "instance" "aws:ec2/instance:Instance" { + ami = ami.id + instanceType = "t2.micro" +} +``` + +### Invoke syntax + +The `invoke()` function takes two arguments: + +1. **function name** - Fully qualified function name in format `package:module/submodule:functionName` +2. **arguments** - Map of input arguments to the function + +The function returns an object with the result properties that can be accessed using dot notation. + +## Outputs + +Outputs export values from your program, making them available to other stacks or displaying them after deployment. + +```hcl +output "bucketName" { + value = bucket.id +} + +output "bucketArn" { + value = bucket.arn + description = "The ARN of the S3 bucket" +} + +output "instanceIps" { + value = [for server in webServers : server.publicIp] +} +``` + +| Property | Type | Required | Description | +| - | - | - | - | +| `value` | expression | Yes | The value to output. | +| `description` | string | No | Human-readable description of the output. | + +Outputs are displayed after `pulumi up` completes and can be accessed via: +```bash +pulumi stack output bucketName +``` + +## Expressions + +See the main HCL documentation for all expressions supported: https://github.com/hashicorp/hcl/blob/main/hclsyntax/spec.md + +## Built-in functions + +HCL provides access to functions through globally accessible function names, such as the `invoke` function from earlier. +Use standard function call syntax in any expression, for example `join("-", ["app", stack()])`. + +### `element` + +Returns the element at the given index from a list or tuple. + +### `entries` + +Converts a map or object into a list of objects with `key` and `value` fields. + +### `fileArchive` + +Creates an archive from a local file or directory path. + +### `remoteArchive` + +Creates an archive from a remote URL. + +### `assetArchive` + +Creates an archive from a map of assets and archives. + +### `fileAsset` + +Creates an asset from a local file path. + +### `stringAsset` + +Creates an asset from an inline string value. + +### `remoteAsset` + +Creates an asset from a remote URL. + +### `join` + +Joins a list of strings with a separator. + +### `length` + +Returns the length of a list, map, object, tuple, or string. + +### `lookup` + +Returns the value for a key in a map, with an optional default if the key is missing. + +### `mimeType` + +Returns the MIME type for a file path. + +### `range` + +Returns a list of integers from zero to `to - 1`, or from `from` to `to - 1` when two arguments are provided. + +### `readDir` + +Returns the entries of a directory as a list of strings. + +### `readFile` + +Returns the contents of a file as a string. + +### `filebase64` + +Returns the Base64-encoded contents of a file. + +### `filebase64sha256` + +Returns the Base64-encoded SHA-256 hash of a file's contents. + +### `secret` + +Marks a value as a secret. + +### `unsecret` + +Removes the secret designation from a value. + +### `sha1` + +Returns the SHA-1 hash of a string. + +### `split` + +Splits a string into a list using a separator. + +### `toBase64` + +Encodes a UTF-8 string as Base64. + +### `fromBase64` + +Decodes a Base64-encoded string to UTF-8. + +### `toJSON` + +Encodes a value as a JSON string. + +### `stack` + +Returns the name of the current stack. + +### `project` + +Returns the name of the current project. + +### `organization` + +Returns the name of the current organization. + +### `cwd` + +Returns the current working directory for the Pulumi program. + +### `notImplemented` + +Raises an error with a custom message to indicate an unsupported operation. + +### `singleOrNone` + +Returns the single element of a list or tuple, or null if the collection is empty. + +### `getOutput` + +Fetches a named output from a stack reference. + +### `try` + +Evaluates arguments in order and returns the first one that does not error. + +### `can` + +Returns whether an expression can be evaluated without error. + +### `rootDirectory` + +Returns the root directory of the Pulumi program. + +### `pulumiResourceType` + +Returns the Pulumi resource type for a resource. + +### `pulumiResourceName` + +Returns the Pulumi resource name for a resource.