Front matter

Conventions Used in This Book

Consistency matters in a technical book. The following conventions are used throughout the examples.

Shell prompts §

A dollar sign represents a command run as an unprivileged user:

$ gcloud projects list

A hash mark represents a command that requires root privileges on a Unix-like host:

# systemctl restart example.service

Do not type the prompt character itself unless the text explicitly says to do so.

Commands §

Commands intended to be copied are shown in fenced code blocks.

Long commands may be split across lines with a backslash:

gcloud compute instances create app-01 \
  --zone=us-central1-a \
  --machine-type=e2-standard-4

Always review a command before running it.

Long identifiers that wrap §

Google Cloud identifiers are long. Some do not fit on one printed line, so they wrap. Wherever that happens, the continuation line begins with a hook mark:

constraints/iam.managed.disableServiceAccountKeyCreat
↪ion

The mark is not part of the identifier. Read the two fragments as one unbroken string with nothing between them — in the example above, the value is constraints/iam.managed.disableServiceAccountKeyCreation.

The same mark appears at the start of a wrapped line inside a code block:

gcloud org-policies describe iam.managed.disableServiceAccountKeyCreation
↪ --organization=ORG_ID

Commands are written so this is rare: long commands are split explicitly with a trailing backslash instead (see Commands, above), which is a real shell line continuation you can copy as-is.

URLs are different. A URL that wraps breaks after a slash, a dot, or a hyphen, and carries no hook mark, because the break always falls on a boundary already visible in the address:

https://cloud.google.com/resource-manager/docs/
cloud-platform-resource-hierarchy

Join the fragments with nothing between them.

File names and paths §

File names and paths appear in inline code:

main.tf

/etc/ssh/sshd_config

environments/prod/

Environment variables §

Environment variables are written in uppercase:

GOOGLE_CLOUD_PROJECT

GOOGLE_APPLICATION_CREDENTIALS

TF_VAR_region

A value beginning with $ refers to the current value of that variable in the shell:

echo "$GOOGLE_CLOUD_PROJECT"

Placeholder values §

Values that must be replaced are written using angle brackets or obvious example values:

<PROJECT_ID>
<REGION>
<SERVICE_ACCOUNT>

Do not deploy literal placeholder values.

Examples use rickcollette.domain and ent.rickcollette.domain. .domain is not a delegated top-level domain, so nothing in this book resolves to a real host. Replace them with domains you control. See The Example Environment.

Terraform §

Terraform examples normally use HashiCorp Configuration Language:

resource "google_storage_bucket" "logs" {
  name     = var.bucket_name
  location = var.region
}

Provider and module versions should be pinned in real environments.

OpenTofu §

When an example works identically with Terraform and OpenTofu, the text may refer to both rather than duplicating the same configuration.

Where behavior differs, the difference is called out explicitly.

Commands use tofu when demonstrating OpenTofu:

tofu plan

and terraform when demonstrating Terraform:

terraform plan

Ansible §

Ansible examples use YAML:

- name: Ensure required packages are installed
  ansible.builtin.package:
    name:
      - curl
      - jq
    state: present

Fully qualified collection names are preferred where doing so makes the module source clearer.

YAML §

YAML depends on indentation.

Examples use spaces, not tabs.

service:
  name: api
  replicas: 3

JSON §

JSON examples follow strict JSON syntax:

{
  "environment": "production",
  "region": "us-central1"
}

Comments are not valid in standard JSON.

Notes §

A Note provides useful context, an explanation, or a detail that is easy to miss.

Warnings §

A Warning identifies an action that may cause service interruption, unexpected cost, data loss, security exposure, or another meaningful operational consequence.

Security notes §

A Security Note explains a trust boundary, privilege implication, exposure, control, threat, or hardening recommendation that deserves explicit attention.

Production notes §

A Production Note describes something that may be acceptable in a small example but must be handled differently in a real production environment.

Output §

Command output is shortened when the omitted material does not affect the explanation.

Ellipses indicate omitted output:

...

Do not assume shortened output is byte-for-byte identical to what your environment will return.

Destructive examples §

Commands capable of deleting or replacing resources are identified clearly.

Examples involving deletion are intentionally explicit. The book does not normalize running destructive commands casually.

Read the command. Verify the project. Verify the account. Verify the target.

Then run it.