What is YAML?

YAML is a data serialization language most commonly used for configuration files. Its easy readability and rich feature set have made it an increasingly popular choice over the years, for everything from configuration files to object serialization. Originally named “Yet Another Markup Language,” the creators changed the name to “YAML Ain’t a Markup Language” in order to better reflect its strength as a data-oriented language rather than simply markup.

How To Get Started With YAML#

Many of YAML’s strongest features were inspired by other programming languages. Like Python, YAML uses whitespace indentation for defining the structure of your file. Strings, integers, floats, lists, and dictionaries are all natively supported, and it does also allow you to define custom data types. Dig far enough into the history of YAML, and you’ll find pieces of the PERL, C, and HTML specs.

While YAML is frequently compared to JSON, it’s important to note that the two are very closely related. YAML is actually a superset of JSON, and so it is capable of parsing JSON directly.

The following is an example of YAML:

---
# An easy-to-read set of data on the Pulumi mascot, in YAML
name: Pulumipus
breed: platypus
color: purple
mascot: True
age: 5
hobbies:
  - Kayaking
  - Bouldering
  - Reading
  - Coding
languages:
  python:
    level: Expert
    version: 3.7
  typescript: Expert
  go: Expert
  csharp: Expert
  java: Expert
  yaml: Expert

The beginning of a YAML file is usually three dashes (---) on the first line. From there, your file is built out of key-value pairs.

name: Pulumipus
breed: platypus
color: purple

The first three key-value pairs are strings indicating that this creature is a purple platypus named Pulumipus, but YAML also supports integers, floats, and booleans to give their age and current status as a mascot:

mascot: True
age: 5

We also have access to lists (or arrays), indicated by preceding an indented item with a dash:

hobbies:
  - Kayaking
  - Bouldering
  - Reading
  - Coding

You can even nest these key-value pairs for more granular information:

languages:
  python:
    level: Expert
    version: 3.7
  typescript: Expert
  go: Expert
  csharp: Expert
  java: Expert
  yaml: Expert

The Benefits of YAML With Pulumi#

If a high degree of readability is your concern and you do not need the expressivity of a full-fledged programming language like Python or TypeScript, YAML is a great option for defining and deploying your infrastructure with Pulumi. Take the following example, which creates an AWS S3 bucket and deploys a simple “hello world” website before returning the URL of your bucket:

---
name: simple-yaml
runtime: yaml
resources:
  my-bucket:
    type: aws:s3:Bucket
  my-bucket-ownership-controls:
    type: aws:s3:BucketOwnershipControls
    properties:
      bucket: ${my-bucket.id}
      rule:
        objectOwnership: ObjectWriter
  my-bucket-acl:
    type: aws:s3:BucketAclV2
    properties:
      bucket: ${my-bucket.bucket}
      acl: public-read
    options:
      dependsOn:
        - ${my-bucket-ownership-controls}
  my-bucket-public-access-block:
    type: aws:s3:BucketPublicAccessBlock
    properties:
      bucket: ${my-bucket.id}
      blockPublicAcls: false
  my-bucket-website:
    type: aws:s3:BucketWebsiteConfigurationV2
    properties:
      bucket: ${my-bucket.bucket}
      indexDocument:
        suffix: index.html
  index.html:
    type: aws:s3:BucketObject
    properties:
      bucket: ${my-bucket}
      source:
        fn::stringAsset: <h1>Hello, world!</h1>
      acl: public-read
      contentType: text/html
outputs:
  bucketEndpoint: http://${my-bucket-website.websiteEndpoint}

There are a few Pulumi-specific things happening in this YAML. Let’s take a closer look.

name: simple-yaml
runtime: yaml

To begin with, we’re naming our program simple-yaml, and defining the runtime for Pulumi as yaml.

resources:
  my-bucket:
    type: aws:s3:Bucket
  my-bucket-website:
    type: aws:s3:BucketWebsiteConfigurationV2
    properties:
      bucket: ${my-bucket.bucket}
      indexDocument:
        suffix: index.html
  index.html:
    type: aws:s3:BucketObject
    properties:
      bucket: ${my-bucket}
      source:
        fn::stringAsset: <h1>Hello, world!</h1>
      acl: public-read
      contentType: text/html
  my-bucket-ownership-controls:
    type: aws:s3:BucketOwnershipControls
    properties:
      bucket: ${my-bucket.id}
      rule:
        objectOwnership: ObjectWriter
  my-bucket-acl:
    type: aws:s3:BucketAclV2
    properties:
      bucket: ${my-bucket.bucket}
      acl: public-read
    options:
      dependsOn:
        - ${my-bucket-ownership-controls}
  my-bucket-public-access-block:
    type: aws:s3:BucketPublicAccessBlock
    properties:
      bucket: ${my-bucket.id}
      blockPublicAcls: false

Next, we are defining the resources Pulumi should create for you. First, my-bucket creates an AWS S3 bucket and my-bucket-website makes it act like a website. Then index.html resource uploads a document containing a simple “Hello, world!” message to serve as the main page to the bucket. Finally my-bucket-ownership-controls, my-bucket-acl, and my-bucket-public-access-block configure AWS networking to allow the public Internet traffic to flow to the bucket.

outputs:
  bucketEndpoint: http://${my-bucket.websiteEndpoint}

Finally, we have an output. This is a value handed to you by Pulumi, after the completion of any work required on behalf of relevant resources. If you’re familiar with JavaScript, you can think of it sort of like a promise. In this case, we’re asking for the URL our document will be visible at.

Conclusion#

The reason to reach for YAML isn’t that it’s simpler than a programming language. It’s that infrastructure work often doesn’t need a programming language at all. When your stack is little more than a declared set of resources and their relationships, the loops, conditionals, and abstractions of Python or TypeScript are overhead you pay for capability you aren’t using. YAML strips that back to the part that actually describes your infrastructure, and because Pulumi treats runtime: yaml as a first-class option, choosing it costs you nothing on the platform side: the same engine, state, and providers back your program whether it’s written in YAML or code. Start in YAML, and you can move to a richer language later if your needs outgrow it.

Try it yourself and get started with any major cloud provider.