How to Add Comments in YAML (Beginners Guide)

Adding comments in a YAML file is a useful way to provide explanations, notes, or annotations within the file without affecting the actual data structure.

YAML (YAML Ain't Markup Language) has become a popular choice for configuration files and declarative syntax in various DevOps and development tools. Proper commenting in YAML files is crucial for DevOps engineers and developers for several reasons:

In this tutorial, we'll explore different ways to add comments in a YAML file using practical examples.

Single-line Comments

To add a single-line comment in YAML, use the # symbol followed by the comment text.

The comment extends until the end of the line.

Here is an example that provides additional information about the purpose of labels and the container port.

apiVersion: v1
kind: Pod
metadata:
  name: my-pod
  # Add labels to the pod
  # Labels are key-value pairs used for organizing and selecting objects
  labels:
    app: my-app
spec:
  containers:
  - name: my-container
    image: my-image:v1
    # Specify the container port
    # This is the port on which the container will listen for incoming traffic
    ports:
    - containerPort: 80

Multi-line Comments

YAML doesn't have a built-in syntax for multi-line comments.

However, you can achieve a similar effect by using a single-line comment for each line of the comment.

Here is an example multi-line comment that explains the purpose of annotations in the service definition.

apiVersion: v1
kind: Service
metadata:
  name: my-service
  # Add annotations to the service
  # Annotations are key-value pairs used for non-identifying metadata
  # They can be used for additional configuration or integration with external systems
  annotations:
    service.beta.kubernetes.io/aws-load-balancer-backend-protocol: http
spec:
  selector:
    app: my-app
  ports:
  - port: 80
    targetPort: 80

Inline Comments

You can add comments inline with the data by using the # symbol after the value.

The comment should be preceded by at least one space.

Then following YAML has the inline comments to clarify the purpose of the number of replicas and labels in the pod template.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-deployment
spec:
  replicas: 3 # Specify the number of replicas
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app # Add labels to the pod template
    spec:
      containers:
      - name: my-container
        image: my-image:v1

Document Separator Comments

YAML allows you to separate multiple documents within a single file using the --- separator.

You can add comments between the document separators to provide information about each document.

Seperators come in handy when you write kubernetes manifests where you need more than one object specification in a YAML file.

In the following example, the comments provide an overview of the purpose of the ConfigMap and Deployment resources under each document seperator.

---
# ConfigMap for application configuration
apiVersion: v1
kind: ConfigMap
metadata:
  name: my-config
data:
  config.yaml: |
    key1: value1
    key2: value2

---
# Deployment for the application
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-deployment
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
      - name: my-container
        image: my-image:v1

Comments in Multi-line Strings

If you have a multi-line string in YAML, you can include comments within the string.

The comments will be treated as part of the string value.

apiVersion: v1
kind: ConfigMap
metadata:
  name: my-config
data:
  config.yaml: |
    # Application configuration
    database:
      host: localhost
      port: 5432
      # Use environment variables for sensitive information
      username: ${DB_USERNAME}
      password: ${DB_PASSWORD}

Here the comments provide explanations about the application configuration and the use of environment variables for sensitive information.

Validating YAML

It is very important to validate the YAMl files after adding comments.

You can validate YAML file with comments using code editors.

Most of the code editors have the inbuilt mechanism or plugins & extensions for validating the YAML files. So if you use wrong comment syntax, it will highlight as an error.

Further more, you can use YAML linters to validate the configurations that has comments.

If you working on Kubernetes YAML manifests, open source tools like kube-linter and Kubeval helps you validate the YAML files and comments.

YAML Comments Best Practices

When adding comments to your YAML files, following best practices can enhance the readability, maintainability, and clarity of your code.

Here are some best practices for YAML comments

1. Add comments when they provide valuable information or clarify complex parts of the YAML structure.
2. Put comments on the line above the code they refer to, making it clear what the comment is about.
3. Maintain a consistent style for comments throughout your YAML files or follow the style documented in your organizations standards.
4. When modifying the YAML code, make sure to update the corresponding comments if necessary.
5. Be cautious not to include sensitive information, such as passwords, tokens, or confidential details, in comments.
6. Maintain proper indentation, spacing, and line breaks to ensure the YAML file remains valid and readable.

By following these best practices, you can create YAML files that are well-documented, easier to understand, and maintainable.

Conclusion

YAML commenting is an essential skill for developers and DevOps engineers working with IaC tools and configurations.

Most editors support commenting using Ctrl+/ .You can select multiple lines and comment it with this shortcut.

By following best practices, utilizing editors effectively, and leveraging validation tools, teams can create well-documented, collaborative, and maintainable YAML files.

Investing time in writing meaningful comments and regularly validating YAML syntax pays off in the long run.