import{createRequire}from'module';const require=createRequire(import.meta.url);
var __create = Object.create;
var __defProp = Object.defineProperty;
var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
var __getOwnPropNames = Object.getOwnPropertyNames;
var __getProtoOf = Object.getPrototypeOf;
var __hasOwnProp = Object.prototype.hasOwnProperty;
var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
}) : x)(function(x) {
  if (typeof require !== "undefined") return require.apply(this, arguments);
  throw Error('Dynamic require of "' + x + '" is not supported');
});
var __commonJS = (cb, mod) => function __require2() {
  try {
    return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
  } catch (e) {
    throw mod = 0, e;
  }
};
var __copyProps = (to, from, except, desc) => {
  if (from && typeof from === "object" || typeof from === "function") {
    for (let key of __getOwnPropNames(from))
      if (!__hasOwnProp.call(to, key) && key !== except)
        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
  }
  return to;
};
var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
  // If the importer is in node compatibility mode or this is not an ESM
  // file that has been converted to a CommonJS file using a Babel-
  // compatible transform (i.e. "__esModule" has not been set), then set
  // "default" to the CommonJS "module.exports" for node compatibility.
  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
  mod
));

// ../../node_modules/yaml/dist/nodes/identity.js
var require_identity = __commonJS({
  "../../node_modules/yaml/dist/nodes/identity.js"(exports) {
    "use strict";
    var ALIAS = /* @__PURE__ */ Symbol.for("yaml.alias");
    var DOC = /* @__PURE__ */ Symbol.for("yaml.document");
    var MAP = /* @__PURE__ */ Symbol.for("yaml.map");
    var PAIR = /* @__PURE__ */ Symbol.for("yaml.pair");
    var SCALAR = /* @__PURE__ */ Symbol.for("yaml.scalar");
    var SEQ = /* @__PURE__ */ Symbol.for("yaml.seq");
    var NODE_TYPE = /* @__PURE__ */ Symbol.for("yaml.node.type");
    var isAlias = (node) => !!node && typeof node === "object" && node[NODE_TYPE] === ALIAS;
    var isDocument = (node) => !!node && typeof node === "object" && node[NODE_TYPE] === DOC;
    var isMap = (node) => !!node && typeof node === "object" && node[NODE_TYPE] === MAP;
    var isPair = (node) => !!node && typeof node === "object" && node[NODE_TYPE] === PAIR;
    var isScalar = (node) => !!node && typeof node === "object" && node[NODE_TYPE] === SCALAR;
    var isSeq = (node) => !!node && typeof node === "object" && node[NODE_TYPE] === SEQ;
    function isCollection(node) {
      if (node && typeof node === "object")
        switch (node[NODE_TYPE]) {
          case MAP:
          case SEQ:
            return true;
        }
      return false;
    }
    function isNode(node) {
      if (node && typeof node === "object")
        switch (node[NODE_TYPE]) {
          case ALIAS:
          case MAP:
          case SCALAR:
          case SEQ:
            return true;
        }
      return false;
    }
    var hasAnchor = (node) => (isScalar(node) || isCollection(node)) && !!node.anchor;
    exports.ALIAS = ALIAS;
    exports.DOC = DOC;
    exports.MAP = MAP;
    exports.NODE_TYPE = NODE_TYPE;
    exports.PAIR = PAIR;
    exports.SCALAR = SCALAR;
    exports.SEQ = SEQ;
    exports.hasAnchor = hasAnchor;
    exports.isAlias = isAlias;
    exports.isCollection = isCollection;
    exports.isDocument = isDocument;
    exports.isMap = isMap;
    exports.isNode = isNode;
    exports.isPair = isPair;
    exports.isScalar = isScalar;
    exports.isSeq = isSeq;
  }
});

// ../../node_modules/yaml/dist/visit.js
var require_visit = __commonJS({
  "../../node_modules/yaml/dist/visit.js"(exports) {
    "use strict";
    var identity = require_identity();
    var BREAK = /* @__PURE__ */ Symbol("break visit");
    var SKIP = /* @__PURE__ */ Symbol("skip children");
    var REMOVE = /* @__PURE__ */ Symbol("remove node");
    function visit(node, visitor) {
      const visitor_ = initVisitor(visitor);
      if (identity.isDocument(node)) {
        const cd = visit_(null, node.contents, visitor_, Object.freeze([node]));
        if (cd === REMOVE)
          node.contents = null;
      } else
        visit_(null, node, visitor_, Object.freeze([]));
    }
    visit.BREAK = BREAK;
    visit.SKIP = SKIP;
    visit.REMOVE = REMOVE;
    function visit_(key, node, visitor, path) {
      const ctrl = callVisitor(key, node, visitor, path);
      if (identity.isNode(ctrl) || identity.isPair(ctrl)) {
        replaceNode(key, path, ctrl);
        return visit_(key, ctrl, visitor, path);
      }
      if (typeof ctrl !== "symbol") {
        if (identity.isCollection(node)) {
          path = Object.freeze(path.concat(node));
          for (let i = 0; i < node.items.length; ++i) {
            const ci = visit_(i, node.items[i], visitor, path);
            if (typeof ci === "number")
              i = ci - 1;
            else if (ci === BREAK)
              return BREAK;
            else if (ci === REMOVE) {
              node.items.splice(i, 1);
              i -= 1;
            }
          }
        } else if (identity.isPair(node)) {
          path = Object.freeze(path.concat(node));
          const ck = visit_("key", node.key, visitor, path);
          if (ck === BREAK)
            return BREAK;
          else if (ck === REMOVE)
            node.key = null;
          const cv = visit_("value", node.value, visitor, path);
          if (cv === BREAK)
            return BREAK;
          else if (cv === REMOVE)
            node.value = null;
        }
      }
      return ctrl;
    }
    async function visitAsync(node, visitor) {
      const visitor_ = initVisitor(visitor);
      if (identity.isDocument(node)) {
        const cd = await visitAsync_(null, node.contents, visitor_, Object.freeze([node]));
        if (cd === REMOVE)
          node.contents = null;
      } else
        await visitAsync_(null, node, visitor_, Object.freeze([]));
    }
    visitAsync.BREAK = BREAK;
    visitAsync.SKIP = SKIP;
    visitAsync.REMOVE = REMOVE;
    async function visitAsync_(key, node, visitor, path) {
      const ctrl = await callVisitor(key, node, visitor, path);
      if (identity.isNode(ctrl) || identity.isPair(ctrl)) {
        replaceNode(key, path, ctrl);
        return visitAsync_(key, ctrl, visitor, path);
      }
      if (typeof ctrl !== "symbol") {
        if (identity.isCollection(node)) {
          path = Object.freeze(path.concat(node));
          for (let i = 0; i < node.items.length; ++i) {
            const ci = await visitAsync_(i, node.items[i], visitor, path);
            if (typeof ci === "number")
              i = ci - 1;
            else if (ci === BREAK)
              return BREAK;
            else if (ci === REMOVE) {
              node.items.splice(i, 1);
              i -= 1;
            }
          }
        } else if (identity.isPair(node)) {
          path = Object.freeze(path.concat(node));
          const ck = await visitAsync_("key", node.key, visitor, path);
          if (ck === BREAK)
            return BREAK;
          else if (ck === REMOVE)
            node.key = null;
          const cv = await visitAsync_("value", node.value, visitor, path);
          if (cv === BREAK)
            return BREAK;
          else if (cv === REMOVE)
            node.value = null;
        }
      }
      return ctrl;
    }
    function initVisitor(visitor) {
      if (typeof visitor === "object" && (visitor.Collection || visitor.Node || visitor.Value)) {
        return Object.assign({
          Alias: visitor.Node,
          Map: visitor.Node,
          Scalar: visitor.Node,
          Seq: visitor.Node
        }, visitor.Value && {
          Map: visitor.Value,
          Scalar: visitor.Value,
          Seq: visitor.Value
        }, visitor.Collection && {
          Map: visitor.Collection,
          Seq: visitor.Collection
        }, visitor);
      }
      return visitor;
    }
    function callVisitor(key, node, visitor, path) {
      if (typeof visitor === "function")
        return visitor(key, node, path);
      if (identity.isMap(node))
        return visitor.Map?.(key, node, path);
      if (identity.isSeq(node))
        return visitor.Seq?.(key, node, path);
      if (identity.isPair(node))
        return visitor.Pair?.(key, node, path);
      if (identity.isScalar(node))
        return visitor.Scalar?.(key, node, path);
      if (identity.isAlias(node))
        return visitor.Alias?.(key, node, path);
      return void 0;
    }
    function replaceNode(key, path, node) {
      const parent = path[path.length - 1];
      if (identity.isCollection(parent)) {
        parent.items[key] = node;
      } else if (identity.isPair(parent)) {
        if (key === "key")
          parent.key = node;
        else
          parent.value = node;
      } else if (identity.isDocument(parent)) {
        parent.contents = node;
      } else {
        const pt = identity.isAlias(parent) ? "alias" : "scalar";
        throw new Error(`Cannot replace node with ${pt} parent`);
      }
    }
    exports.visit = visit;
    exports.visitAsync = visitAsync;
  }
});

// ../../node_modules/yaml/dist/doc/directives.js
var require_directives = __commonJS({
  "../../node_modules/yaml/dist/doc/directives.js"(exports) {
    "use strict";
    var identity = require_identity();
    var visit = require_visit();
    var escapeChars = {
      "!": "%21",
      ",": "%2C",
      "[": "%5B",
      "]": "%5D",
      "{": "%7B",
      "}": "%7D"
    };
    var escapeTagName = (tn) => tn.replace(/[!,[\]{}]/g, (ch) => escapeChars[ch]);
    var Directives = class _Directives {
      constructor(yaml, tags) {
        this.docStart = null;
        this.docEnd = false;
        this.yaml = Object.assign({}, _Directives.defaultYaml, yaml);
        this.tags = Object.assign({}, _Directives.defaultTags, tags);
      }
      clone() {
        const copy = new _Directives(this.yaml, this.tags);
        copy.docStart = this.docStart;
        return copy;
      }
      /**
       * During parsing, get a Directives instance for the current document and
       * update the stream state according to the current version's spec.
       */
      atDocument() {
        const res = new _Directives(this.yaml, this.tags);
        switch (this.yaml.version) {
          case "1.1":
            this.atNextDocument = true;
            break;
          case "1.2":
            this.atNextDocument = false;
            this.yaml = {
              explicit: _Directives.defaultYaml.explicit,
              version: "1.2"
            };
            this.tags = Object.assign({}, _Directives.defaultTags);
            break;
        }
        return res;
      }
      /**
       * @param onError - May be called even if the action was successful
       * @returns `true` on success
       */
      add(line, onError) {
        if (this.atNextDocument) {
          this.yaml = { explicit: _Directives.defaultYaml.explicit, version: "1.1" };
          this.tags = Object.assign({}, _Directives.defaultTags);
          this.atNextDocument = false;
        }
        const parts = line.trim().split(/[ \t]+/);
        const name = parts.shift();
        switch (name) {
          case "%TAG": {
            if (parts.length !== 2) {
              onError(0, "%TAG directive should contain exactly two parts");
              if (parts.length < 2)
                return false;
            }
            const [handle, prefix] = parts;
            this.tags[handle] = prefix;
            return true;
          }
          case "%YAML": {
            this.yaml.explicit = true;
            if (parts.length !== 1) {
              onError(0, "%YAML directive should contain exactly one part");
              return false;
            }
            const [version] = parts;
            if (version === "1.1" || version === "1.2") {
              this.yaml.version = version;
              return true;
            } else {
              const isValid = /^\d+\.\d+$/.test(version);
              onError(6, `Unsupported YAML version ${version}`, isValid);
              return false;
            }
          }
          default:
            onError(0, `Unknown directive ${name}`, true);
            return false;
        }
      }
      /**
       * Resolves a tag, matching handles to those defined in %TAG directives.
       *
       * @returns Resolved tag, which may also be the non-specific tag `'!'` or a
       *   `'!local'` tag, or `null` if unresolvable.
       */
      tagName(source, onError) {
        if (source === "!")
          return "!";
        if (source[0] !== "!") {
          onError(`Not a valid tag: ${source}`);
          return null;
        }
        if (source[1] === "<") {
          const verbatim = source.slice(2, -1);
          if (verbatim === "!" || verbatim === "!!") {
            onError(`Verbatim tags aren't resolved, so ${source} is invalid.`);
            return null;
          }
          if (source[source.length - 1] !== ">")
            onError("Verbatim tags must end with a >");
          return verbatim;
        }
        const [, handle, suffix] = source.match(/^(.*!)([^!]*)$/s);
        if (!suffix)
          onError(`The ${source} tag has no suffix`);
        const prefix = this.tags[handle];
        if (prefix) {
          try {
            return prefix + decodeURIComponent(suffix);
          } catch (error) {
            onError(String(error));
            return null;
          }
        }
        if (handle === "!")
          return source;
        onError(`Could not resolve tag: ${source}`);
        return null;
      }
      /**
       * Given a fully resolved tag, returns its printable string form,
       * taking into account current tag prefixes and defaults.
       */
      tagString(tag) {
        for (const [handle, prefix] of Object.entries(this.tags)) {
          if (tag.startsWith(prefix))
            return handle + escapeTagName(tag.substring(prefix.length));
        }
        return tag[0] === "!" ? tag : `!<${tag}>`;
      }
      toString(doc) {
        const lines = this.yaml.explicit ? [`%YAML ${this.yaml.version || "1.2"}`] : [];
        const tagEntries = Object.entries(this.tags);
        let tagNames;
        if (doc && tagEntries.length > 0 && identity.isNode(doc.contents)) {
          const tags = {};
          visit.visit(doc.contents, (_key, node) => {
            if (identity.isNode(node) && node.tag)
              tags[node.tag] = true;
          });
          tagNames = Object.keys(tags);
        } else
          tagNames = [];
        for (const [handle, prefix] of tagEntries) {
          if (handle === "!!" && prefix === "tag:yaml.org,2002:")
            continue;
          if (!doc || tagNames.some((tn) => tn.startsWith(prefix)))
            lines.push(`%TAG ${handle} ${prefix}`);
        }
        return lines.join("\n");
      }
    };
    Directives.defaultYaml = { explicit: false, version: "1.2" };
    Directives.defaultTags = { "!!": "tag:yaml.org,2002:" };
    exports.Directives = Directives;
  }
});

// ../../node_modules/yaml/dist/doc/anchors.js
var require_anchors = __commonJS({
  "../../node_modules/yaml/dist/doc/anchors.js"(exports) {
    "use strict";
    var identity = require_identity();
    var visit = require_visit();
    function anchorIsValid(anchor) {
      if (/[\x00-\x19\s,[\]{}]/.test(anchor)) {
        const sa = JSON.stringify(anchor);
        const msg = `Anchor must not contain whitespace or control characters: ${sa}`;
        throw new Error(msg);
      }
      return true;
    }
    function anchorNames(root) {
      const anchors = /* @__PURE__ */ new Set();
      visit.visit(root, {
        Value(_key, node) {
          if (node.anchor)
            anchors.add(node.anchor);
        }
      });
      return anchors;
    }
    function findNewAnchor(prefix, exclude) {
      for (let i = 1; true; ++i) {
        const name = `${prefix}${i}`;
        if (!exclude.has(name))
          return name;
      }
    }
    function createNodeAnchors(doc, prefix) {
      const aliasObjects = [];
      const sourceObjects = /* @__PURE__ */ new Map();
      let prevAnchors = null;
      return {
        onAnchor: (source) => {
          aliasObjects.push(source);
          prevAnchors ?? (prevAnchors = anchorNames(doc));
          const anchor = findNewAnchor(prefix, prevAnchors);
          prevAnchors.add(anchor);
          return anchor;
        },
        /**
         * With circular references, the source node is only resolved after all
         * of its child nodes are. This is why anchors are set only after all of
         * the nodes have been created.
         */
        setAnchors: () => {
          for (const source of aliasObjects) {
            const ref = sourceObjects.get(source);
            if (typeof ref === "object" && ref.anchor && (identity.isScalar(ref.node) || identity.isCollection(ref.node))) {
              ref.node.anchor = ref.anchor;
            } else {
              const error = new Error("Failed to resolve repeated object (this should not happen)");
              error.source = source;
              throw error;
            }
          }
        },
        sourceObjects
      };
    }
    exports.anchorIsValid = anchorIsValid;
    exports.anchorNames = anchorNames;
    exports.createNodeAnchors = createNodeAnchors;
    exports.findNewAnchor = findNewAnchor;
  }
});

// ../../node_modules/yaml/dist/doc/applyReviver.js
var require_applyReviver = __commonJS({
  "../../node_modules/yaml/dist/doc/applyReviver.js"(exports) {
    "use strict";
    function applyReviver(reviver, obj, key, val) {
      if (val && typeof val === "object") {
        if (Array.isArray(val)) {
          for (let i = 0, len = val.length; i < len; ++i) {
            const v0 = val[i];
            const v1 = applyReviver(reviver, val, String(i), v0);
            if (v1 === void 0)
              delete val[i];
            else if (v1 !== v0)
              val[i] = v1;
          }
        } else if (val instanceof Map) {
          for (const k of Array.from(val.keys())) {
            const v0 = val.get(k);
            const v1 = applyReviver(reviver, val, k, v0);
            if (v1 === void 0)
              val.delete(k);
            else if (v1 !== v0)
              val.set(k, v1);
          }
        } else if (val instanceof Set) {
          for (const v0 of Array.from(val)) {
            const v1 = applyReviver(reviver, val, v0, v0);
            if (v1 === void 0)
              val.delete(v0);
            else if (v1 !== v0) {
              val.delete(v0);
              val.add(v1);
            }
          }
        } else {
          for (const [k, v0] of Object.entries(val)) {
            const v1 = applyReviver(reviver, val, k, v0);
            if (v1 === void 0)
              delete val[k];
            else if (v1 !== v0)
              val[k] = v1;
          }
        }
      }
      return reviver.call(obj, key, val);
    }
    exports.applyReviver = applyReviver;
  }
});

// ../../node_modules/yaml/dist/nodes/toJS.js
var require_toJS = __commonJS({
  "../../node_modules/yaml/dist/nodes/toJS.js"(exports) {
    "use strict";
    var identity = require_identity();
    function toJS(value, arg, ctx) {
      if (Array.isArray(value))
        return value.map((v, i) => toJS(v, String(i), ctx));
      if (value && typeof value.toJSON === "function") {
        if (!ctx || !identity.hasAnchor(value))
          return value.toJSON(arg, ctx);
        const data = { aliasCount: 0, count: 1, res: void 0 };
        ctx.anchors.set(value, data);
        ctx.onCreate = (res2) => {
          data.res = res2;
          delete ctx.onCreate;
        };
        const res = value.toJSON(arg, ctx);
        if (ctx.onCreate)
          ctx.onCreate(res);
        return res;
      }
      if (typeof value === "bigint" && !ctx?.keep)
        return Number(value);
      return value;
    }
    exports.toJS = toJS;
  }
});

// ../../node_modules/yaml/dist/nodes/Node.js
var require_Node = __commonJS({
  "../../node_modules/yaml/dist/nodes/Node.js"(exports) {
    "use strict";
    var applyReviver = require_applyReviver();
    var identity = require_identity();
    var toJS = require_toJS();
    var NodeBase = class {
      constructor(type) {
        Object.defineProperty(this, identity.NODE_TYPE, { value: type });
      }
      /** Create a copy of this node.  */
      clone() {
        const copy = Object.create(Object.getPrototypeOf(this), Object.getOwnPropertyDescriptors(this));
        if (this.range)
          copy.range = this.range.slice();
        return copy;
      }
      /** A plain JavaScript representation of this node. */
      toJS(doc, { mapAsMap, maxAliasCount, onAnchor, reviver } = {}) {
        if (!identity.isDocument(doc))
          throw new TypeError("A document argument is required");
        const ctx = {
          anchors: /* @__PURE__ */ new Map(),
          doc,
          keep: true,
          mapAsMap: mapAsMap === true,
          mapKeyWarned: false,
          maxAliasCount: typeof maxAliasCount === "number" ? maxAliasCount : 100
        };
        const res = toJS.toJS(this, "", ctx);
        if (typeof onAnchor === "function")
          for (const { count, res: res2 } of ctx.anchors.values())
            onAnchor(res2, count);
        return typeof reviver === "function" ? applyReviver.applyReviver(reviver, { "": res }, "", res) : res;
      }
    };
    exports.NodeBase = NodeBase;
  }
});

// ../../node_modules/yaml/dist/nodes/Alias.js
var require_Alias = __commonJS({
  "../../node_modules/yaml/dist/nodes/Alias.js"(exports) {
    "use strict";
    var anchors = require_anchors();
    var visit = require_visit();
    var identity = require_identity();
    var Node = require_Node();
    var toJS = require_toJS();
    var Alias = class extends Node.NodeBase {
      constructor(source) {
        super(identity.ALIAS);
        this.source = source;
        Object.defineProperty(this, "tag", {
          set() {
            throw new Error("Alias nodes cannot have tags");
          }
        });
      }
      /**
       * Resolve the value of this alias within `doc`, finding the last
       * instance of the `source` anchor before this node.
       */
      resolve(doc, ctx) {
        if (ctx?.maxAliasCount === 0)
          throw new ReferenceError("Alias resolution is disabled");
        let nodes;
        if (ctx?.aliasResolveCache) {
          nodes = ctx.aliasResolveCache;
        } else {
          nodes = [];
          visit.visit(doc, {
            Node: (_key, node) => {
              if (identity.isAlias(node) || identity.hasAnchor(node))
                nodes.push(node);
            }
          });
          if (ctx)
            ctx.aliasResolveCache = nodes;
        }
        let found = void 0;
        for (const node of nodes) {
          if (node === this)
            break;
          if (node.anchor === this.source)
            found = node;
        }
        if (found && ctx) {
          const { anchors: anchors2, doc: doc2, maxAliasCount } = ctx;
          let data = anchors2.get(found);
          if (!data) {
            toJS.toJS(found, null, ctx);
            data = anchors2.get(found);
          }
          if (data?.res === void 0) {
            const msg = "This should not happen: Alias anchor was not resolved?";
            throw new ReferenceError(msg);
          }
          if (maxAliasCount >= 0) {
            data.count += 1;
            if (data.aliasCount === 0)
              data.aliasCount = getAliasCount(doc2, found, anchors2);
            if (data.count * data.aliasCount > maxAliasCount) {
              const msg = "Excessive alias count indicates a resource exhaustion attack";
              throw new ReferenceError(msg);
            }
          }
        }
        return found;
      }
      toJSON(_arg, ctx) {
        if (!ctx)
          return { source: this.source };
        const source = this.resolve(ctx.doc, ctx);
        if (!source) {
          const msg = `Unresolved alias (the anchor must be set before the alias): ${this.source}`;
          throw new ReferenceError(msg);
        }
        return ctx.anchors.get(source).res;
      }
      toString(ctx, _onComment, _onChompKeep) {
        const src = `*${this.source}`;
        if (ctx) {
          anchors.anchorIsValid(this.source);
          if (ctx.options.verifyAliasOrder && !ctx.anchors.has(this.source)) {
            const msg = `Unresolved alias (the anchor must be set before the alias): ${this.source}`;
            throw new Error(msg);
          }
          if (ctx.implicitKey)
            return `${src} `;
        }
        return src;
      }
    };
    function getAliasCount(doc, node, anchors2) {
      if (identity.isAlias(node)) {
        const source = node.resolve(doc);
        const anchor = anchors2 && source && anchors2.get(source);
        return anchor ? anchor.count * anchor.aliasCount : 0;
      } else if (identity.isCollection(node)) {
        let count = 0;
        for (const item of node.items) {
          const c = getAliasCount(doc, item, anchors2);
          if (c > count)
            count = c;
        }
        return count;
      } else if (identity.isPair(node)) {
        const kc = getAliasCount(doc, node.key, anchors2);
        const vc = getAliasCount(doc, node.value, anchors2);
        return Math.max(kc, vc);
      }
      return 1;
    }
    exports.Alias = Alias;
  }
});

// ../../node_modules/yaml/dist/nodes/Scalar.js
var require_Scalar = __commonJS({
  "../../node_modules/yaml/dist/nodes/Scalar.js"(exports) {
    "use strict";
    var identity = require_identity();
    var Node = require_Node();
    var toJS = require_toJS();
    var isScalarValue = (value) => !value || typeof value !== "function" && typeof value !== "object";
    var Scalar = class extends Node.NodeBase {
      constructor(value) {
        super(identity.SCALAR);
        this.value = value;
      }
      toJSON(arg, ctx) {
        return ctx?.keep ? this.value : toJS.toJS(this.value, arg, ctx);
      }
      toString() {
        return String(this.value);
      }
    };
    Scalar.BLOCK_FOLDED = "BLOCK_FOLDED";
    Scalar.BLOCK_LITERAL = "BLOCK_LITERAL";
    Scalar.PLAIN = "PLAIN";
    Scalar.QUOTE_DOUBLE = "QUOTE_DOUBLE";
    Scalar.QUOTE_SINGLE = "QUOTE_SINGLE";
    exports.Scalar = Scalar;
    exports.isScalarValue = isScalarValue;
  }
});

// ../../node_modules/yaml/dist/doc/createNode.js
var require_createNode = __commonJS({
  "../../node_modules/yaml/dist/doc/createNode.js"(exports) {
    "use strict";
    var Alias = require_Alias();
    var identity = require_identity();
    var Scalar = require_Scalar();
    var defaultTagPrefix = "tag:yaml.org,2002:";
    function findTagObject(value, tagName, tags) {
      if (tagName) {
        const match = tags.filter((t) => t.tag === tagName);
        const tagObj = match.find((t) => !t.format) ?? match[0];
        if (!tagObj)
          throw new Error(`Tag ${tagName} not found`);
        return tagObj;
      }
      return tags.find((t) => t.identify?.(value) && !t.format);
    }
    function createNode(value, tagName, ctx) {
      if (identity.isDocument(value))
        value = value.contents;
      if (identity.isNode(value))
        return value;
      if (identity.isPair(value)) {
        const map = ctx.schema[identity.MAP].createNode?.(ctx.schema, null, ctx);
        map.items.push(value);
        return map;
      }
      if (value instanceof String || value instanceof Number || value instanceof Boolean || typeof BigInt !== "undefined" && value instanceof BigInt) {
        value = value.valueOf();
      }
      const { aliasDuplicateObjects, onAnchor, onTagObj, schema, sourceObjects } = ctx;
      let ref = void 0;
      if (aliasDuplicateObjects && value && typeof value === "object") {
        ref = sourceObjects.get(value);
        if (ref) {
          ref.anchor ?? (ref.anchor = onAnchor(value));
          return new Alias.Alias(ref.anchor);
        } else {
          ref = { anchor: null, node: null };
          sourceObjects.set(value, ref);
        }
      }
      if (tagName?.startsWith("!!"))
        tagName = defaultTagPrefix + tagName.slice(2);
      let tagObj = findTagObject(value, tagName, schema.tags);
      if (!tagObj) {
        if (value && typeof value.toJSON === "function") {
          value = value.toJSON();
        }
        if (!value || typeof value !== "object") {
          const node2 = new Scalar.Scalar(value);
          if (ref)
            ref.node = node2;
          return node2;
        }
        tagObj = value instanceof Map ? schema[identity.MAP] : Symbol.iterator in Object(value) ? schema[identity.SEQ] : schema[identity.MAP];
      }
      if (onTagObj) {
        onTagObj(tagObj);
        delete ctx.onTagObj;
      }
      const node = tagObj?.createNode ? tagObj.createNode(ctx.schema, value, ctx) : typeof tagObj?.nodeClass?.from === "function" ? tagObj.nodeClass.from(ctx.schema, value, ctx) : new Scalar.Scalar(value);
      if (tagName)
        node.tag = tagName;
      else if (!tagObj.default)
        node.tag = tagObj.tag;
      if (ref)
        ref.node = node;
      return node;
    }
    exports.createNode = createNode;
  }
});

// ../../node_modules/yaml/dist/nodes/Collection.js
var require_Collection = __commonJS({
  "../../node_modules/yaml/dist/nodes/Collection.js"(exports) {
    "use strict";
    var createNode = require_createNode();
    var identity = require_identity();
    var Node = require_Node();
    function collectionFromPath(schema, path, value) {
      let v = value;
      for (let i = path.length - 1; i >= 0; --i) {
        const k = path[i];
        if (typeof k === "number" && Number.isInteger(k) && k >= 0) {
          const a = [];
          a[k] = v;
          v = a;
        } else {
          v = /* @__PURE__ */ new Map([[k, v]]);
        }
      }
      return createNode.createNode(v, void 0, {
        aliasDuplicateObjects: false,
        keepUndefined: false,
        onAnchor: () => {
          throw new Error("This should not happen, please report a bug.");
        },
        schema,
        sourceObjects: /* @__PURE__ */ new Map()
      });
    }
    var isEmptyPath = (path) => path == null || typeof path === "object" && !!path[Symbol.iterator]().next().done;
    var Collection = class extends Node.NodeBase {
      constructor(type, schema) {
        super(type);
        Object.defineProperty(this, "schema", {
          value: schema,
          configurable: true,
          enumerable: false,
          writable: true
        });
      }
      /**
       * Create a copy of this collection.
       *
       * @param schema - If defined, overwrites the original's schema
       */
      clone(schema) {
        const copy = Object.create(Object.getPrototypeOf(this), Object.getOwnPropertyDescriptors(this));
        if (schema)
          copy.schema = schema;
        copy.items = copy.items.map((it) => identity.isNode(it) || identity.isPair(it) ? it.clone(schema) : it);
        if (this.range)
          copy.range = this.range.slice();
        return copy;
      }
      /**
       * Adds a value to the collection. For `!!map` and `!!omap` the value must
       * be a Pair instance or a `{ key, value }` object, which may not have a key
       * that already exists in the map.
       */
      addIn(path, value) {
        if (isEmptyPath(path))
          this.add(value);
        else {
          const [key, ...rest] = path;
          const node = this.get(key, true);
          if (identity.isCollection(node))
            node.addIn(rest, value);
          else if (node === void 0 && this.schema)
            this.set(key, collectionFromPath(this.schema, rest, value));
          else
            throw new Error(`Expected YAML collection at ${key}. Remaining path: ${rest}`);
        }
      }
      /**
       * Removes a value from the collection.
       * @returns `true` if the item was found and removed.
       */
      deleteIn(path) {
        const [key, ...rest] = path;
        if (rest.length === 0)
          return this.delete(key);
        const node = this.get(key, true);
        if (identity.isCollection(node))
          return node.deleteIn(rest);
        else
          throw new Error(`Expected YAML collection at ${key}. Remaining path: ${rest}`);
      }
      /**
       * Returns item at `key`, or `undefined` if not found. By default unwraps
       * scalar values from their surrounding node; to disable set `keepScalar` to
       * `true` (collections are always returned intact).
       */
      getIn(path, keepScalar) {
        const [key, ...rest] = path;
        const node = this.get(key, true);
        if (rest.length === 0)
          return !keepScalar && identity.isScalar(node) ? node.value : node;
        else
          return identity.isCollection(node) ? node.getIn(rest, keepScalar) : void 0;
      }
      hasAllNullValues(allowScalar) {
        return this.items.every((node) => {
          if (!identity.isPair(node))
            return false;
          const n = node.value;
          return n == null || allowScalar && identity.isScalar(n) && n.value == null && !n.commentBefore && !n.comment && !n.tag;
        });
      }
      /**
       * Checks if the collection includes a value with the key `key`.
       */
      hasIn(path) {
        const [key, ...rest] = path;
        if (rest.length === 0)
          return this.has(key);
        const node = this.get(key, true);
        return identity.isCollection(node) ? node.hasIn(rest) : false;
      }
      /**
       * Sets a value in this collection. For `!!set`, `value` needs to be a
       * boolean to add/remove the item from the set.
       */
      setIn(path, value) {
        const [key, ...rest] = path;
        if (rest.length === 0) {
          this.set(key, value);
        } else {
          const node = this.get(key, true);
          if (identity.isCollection(node))
            node.setIn(rest, value);
          else if (node === void 0 && this.schema)
            this.set(key, collectionFromPath(this.schema, rest, value));
          else
            throw new Error(`Expected YAML collection at ${key}. Remaining path: ${rest}`);
        }
      }
    };
    exports.Collection = Collection;
    exports.collectionFromPath = collectionFromPath;
    exports.isEmptyPath = isEmptyPath;
  }
});

// ../../node_modules/yaml/dist/stringify/stringifyComment.js
var require_stringifyComment = __commonJS({
  "../../node_modules/yaml/dist/stringify/stringifyComment.js"(exports) {
    "use strict";
    var stringifyComment = (str) => str.replace(/^(?!$)(?: $)?/gm, "#");
    function indentComment(comment, indent) {
      if (/^\n+$/.test(comment))
        return comment.substring(1);
      return indent ? comment.replace(/^(?! *$)/gm, indent) : comment;
    }
    var lineComment = (str, indent, comment) => str.endsWith("\n") ? indentComment(comment, indent) : comment.includes("\n") ? "\n" + indentComment(comment, indent) : (str.endsWith(" ") ? "" : " ") + comment;
    exports.indentComment = indentComment;
    exports.lineComment = lineComment;
    exports.stringifyComment = stringifyComment;
  }
});

// ../../node_modules/yaml/dist/stringify/foldFlowLines.js
var require_foldFlowLines = __commonJS({
  "../../node_modules/yaml/dist/stringify/foldFlowLines.js"(exports) {
    "use strict";
    var FOLD_FLOW = "flow";
    var FOLD_BLOCK = "block";
    var FOLD_QUOTED = "quoted";
    function foldFlowLines(text, indent, mode = "flow", { indentAtStart, lineWidth = 80, minContentWidth = 20, onFold, onOverflow } = {}) {
      if (!lineWidth || lineWidth < 0)
        return text;
      if (lineWidth < minContentWidth)
        minContentWidth = 0;
      const endStep = Math.max(1 + minContentWidth, 1 + lineWidth - indent.length);
      if (text.length <= endStep)
        return text;
      const folds = [];
      const escapedFolds = {};
      let end = lineWidth - indent.length;
      if (typeof indentAtStart === "number") {
        if (indentAtStart > lineWidth - Math.max(2, minContentWidth))
          folds.push(0);
        else
          end = lineWidth - indentAtStart;
      }
      let split = void 0;
      let prev = void 0;
      let overflow = false;
      let i = -1;
      let escStart = -1;
      let escEnd = -1;
      if (mode === FOLD_BLOCK) {
        i = consumeMoreIndentedLines(text, i, indent.length);
        if (i !== -1)
          end = i + endStep;
      }
      for (let ch; ch = text[i += 1]; ) {
        if (mode === FOLD_QUOTED && ch === "\\") {
          escStart = i;
          switch (text[i + 1]) {
            case "x":
              i += 3;
              break;
            case "u":
              i += 5;
              break;
            case "U":
              i += 9;
              break;
            default:
              i += 1;
          }
          escEnd = i;
        }
        if (ch === "\n") {
          if (mode === FOLD_BLOCK)
            i = consumeMoreIndentedLines(text, i, indent.length);
          end = i + indent.length + endStep;
          split = void 0;
        } else {
          if (ch === " " && prev && prev !== " " && prev !== "\n" && prev !== "	") {
            const next = text[i + 1];
            if (next && next !== " " && next !== "\n" && next !== "	")
              split = i;
          }
          if (i >= end) {
            if (split) {
              folds.push(split);
              end = split + endStep;
              split = void 0;
            } else if (mode === FOLD_QUOTED) {
              while (prev === " " || prev === "	") {
                prev = ch;
                ch = text[i += 1];
                overflow = true;
              }
              const j = i > escEnd + 1 ? i - 2 : escStart - 1;
              if (escapedFolds[j])
                return text;
              folds.push(j);
              escapedFolds[j] = true;
              end = j + endStep;
              split = void 0;
            } else {
              overflow = true;
            }
          }
        }
        prev = ch;
      }
      if (overflow && onOverflow)
        onOverflow();
      if (folds.length === 0)
        return text;
      if (onFold)
        onFold();
      let res = text.slice(0, folds[0]);
      for (let i2 = 0; i2 < folds.length; ++i2) {
        const fold = folds[i2];
        const end2 = folds[i2 + 1] || text.length;
        if (fold === 0)
          res = `
${indent}${text.slice(0, end2)}`;
        else {
          if (mode === FOLD_QUOTED && escapedFolds[fold])
            res += `${text[fold]}\\`;
          res += `
${indent}${text.slice(fold + 1, end2)}`;
        }
      }
      return res;
    }
    function consumeMoreIndentedLines(text, i, indent) {
      let end = i;
      let start = i + 1;
      let ch = text[start];
      while (ch === " " || ch === "	") {
        if (i < start + indent) {
          ch = text[++i];
        } else {
          do {
            ch = text[++i];
          } while (ch && ch !== "\n");
          end = i;
          start = i + 1;
          ch = text[start];
        }
      }
      return end;
    }
    exports.FOLD_BLOCK = FOLD_BLOCK;
    exports.FOLD_FLOW = FOLD_FLOW;
    exports.FOLD_QUOTED = FOLD_QUOTED;
    exports.foldFlowLines = foldFlowLines;
  }
});

// ../../node_modules/yaml/dist/stringify/stringifyString.js
var require_stringifyString = __commonJS({
  "../../node_modules/yaml/dist/stringify/stringifyString.js"(exports) {
    "use strict";
    var Scalar = require_Scalar();
    var foldFlowLines = require_foldFlowLines();
    var getFoldOptions = (ctx, isBlock) => ({
      indentAtStart: isBlock ? ctx.indent.length : ctx.indentAtStart,
      lineWidth: ctx.options.lineWidth,
      minContentWidth: ctx.options.minContentWidth
    });
    var containsDocumentMarker = (str) => /^(%|---|\.\.\.)/m.test(str);
    function lineLengthOverLimit(str, lineWidth, indentLength) {
      if (!lineWidth || lineWidth < 0)
        return false;
      const limit = lineWidth - indentLength;
      const strLen = str.length;
      if (strLen <= limit)
        return false;
      for (let i = 0, start = 0; i < strLen; ++i) {
        if (str[i] === "\n") {
          if (i - start > limit)
            return true;
          start = i + 1;
          if (strLen - start <= limit)
            return false;
        }
      }
      return true;
    }
    function doubleQuotedString(value, ctx) {
      const json2 = JSON.stringify(value);
      if (ctx.options.doubleQuotedAsJSON)
        return json2;
      const { implicitKey } = ctx;
      const minMultiLineLength = ctx.options.doubleQuotedMinMultiLineLength;
      const indent = ctx.indent || (containsDocumentMarker(value) ? "  " : "");
      let str = "";
      let start = 0;
      for (let i = 0, ch = json2[i]; ch; ch = json2[++i]) {
        if (ch === " " && json2[i + 1] === "\\" && json2[i + 2] === "n") {
          str += json2.slice(start, i) + "\\ ";
          i += 1;
          start = i;
          ch = "\\";
        }
        if (ch === "\\")
          switch (json2[i + 1]) {
            case "u":
              {
                str += json2.slice(start, i);
                const code = json2.substr(i + 2, 4);
                switch (code) {
                  case "0000":
                    str += "\\0";
                    break;
                  case "0007":
                    str += "\\a";
                    break;
                  case "000b":
                    str += "\\v";
                    break;
                  case "001b":
                    str += "\\e";
                    break;
                  case "0085":
                    str += "\\N";
                    break;
                  case "00a0":
                    str += "\\_";
                    break;
                  case "2028":
                    str += "\\L";
                    break;
                  case "2029":
                    str += "\\P";
                    break;
                  default:
                    if (code.substr(0, 2) === "00")
                      str += "\\x" + code.substr(2);
                    else
                      str += json2.substr(i, 6);
                }
                i += 5;
                start = i + 1;
              }
              break;
            case "n":
              if (implicitKey || json2[i + 2] === '"' || json2.length < minMultiLineLength) {
                i += 1;
              } else {
                str += json2.slice(start, i) + "\n\n";
                while (json2[i + 2] === "\\" && json2[i + 3] === "n" && json2[i + 4] !== '"') {
                  str += "\n";
                  i += 2;
                }
                str += indent;
                if (json2[i + 2] === " ")
                  str += "\\";
                i += 1;
                start = i + 1;
              }
              break;
            default:
              i += 1;
          }
      }
      str = start ? str + json2.slice(start) : json2;
      return implicitKey ? str : foldFlowLines.foldFlowLines(str, indent, foldFlowLines.FOLD_QUOTED, getFoldOptions(ctx, false));
    }
    function singleQuotedString(value, ctx) {
      if (ctx.options.singleQuote === false || ctx.implicitKey && value.includes("\n") || /[ \t]\n|\n[ \t]/.test(value))
        return doubleQuotedString(value, ctx);
      const indent = ctx.indent || (containsDocumentMarker(value) ? "  " : "");
      const res = "'" + value.replace(/'/g, "''").replace(/\n+/g, `$&
${indent}`) + "'";
      return ctx.implicitKey ? res : foldFlowLines.foldFlowLines(res, indent, foldFlowLines.FOLD_FLOW, getFoldOptions(ctx, false));
    }
    function quotedString(value, ctx) {
      const { singleQuote } = ctx.options;
      let qs;
      if (singleQuote === false)
        qs = doubleQuotedString;
      else {
        const hasDouble = value.includes('"');
        const hasSingle = value.includes("'");
        if (hasDouble && !hasSingle)
          qs = singleQuotedString;
        else if (hasSingle && !hasDouble)
          qs = doubleQuotedString;
        else
          qs = singleQuote ? singleQuotedString : doubleQuotedString;
      }
      return qs(value, ctx);
    }
    var blockEndNewlines;
    try {
      blockEndNewlines = new RegExp("(^|(?<!\n))\n+(?!\n|$)", "g");
    } catch {
      blockEndNewlines = /\n+(?!\n|$)/g;
    }
    function blockString({ comment, type, value }, ctx, onComment, onChompKeep) {
      const { blockQuote, commentString, lineWidth } = ctx.options;
      if (!blockQuote || /\n[\t ]+$/.test(value)) {
        return quotedString(value, ctx);
      }
      const indent = ctx.indent || (ctx.forceBlockIndent || containsDocumentMarker(value) ? "  " : "");
      const literal = blockQuote === "literal" ? true : blockQuote === "folded" || type === Scalar.Scalar.BLOCK_FOLDED ? false : type === Scalar.Scalar.BLOCK_LITERAL ? true : !lineLengthOverLimit(value, lineWidth, indent.length);
      if (!value)
        return literal ? "|\n" : ">\n";
      let chomp;
      let endStart;
      for (endStart = value.length; endStart > 0; --endStart) {
        const ch = value[endStart - 1];
        if (ch !== "\n" && ch !== "	" && ch !== " ")
          break;
      }
      let end = value.substring(endStart);
      const endNlPos = end.indexOf("\n");
      if (endNlPos === -1) {
        chomp = "-";
      } else if (value === end || endNlPos !== end.length - 1) {
        chomp = "+";
        if (onChompKeep)
          onChompKeep();
      } else {
        chomp = "";
      }
      if (end) {
        value = value.slice(0, -end.length);
        if (end[end.length - 1] === "\n")
          end = end.slice(0, -1);
        end = end.replace(blockEndNewlines, `$&${indent}`);
      }
      let startWithSpace = false;
      let startEnd;
      let startNlPos = -1;
      for (startEnd = 0; startEnd < value.length; ++startEnd) {
        const ch = value[startEnd];
        if (ch === " ")
          startWithSpace = true;
        else if (ch === "\n")
          startNlPos = startEnd;
        else
          break;
      }
      let start = value.substring(0, startNlPos < startEnd ? startNlPos + 1 : startEnd);
      if (start) {
        value = value.substring(start.length);
        start = start.replace(/\n+/g, `$&${indent}`);
      }
      const indentSize = indent ? "2" : "1";
      let header = (startWithSpace ? indentSize : "") + chomp;
      if (comment) {
        header += " " + commentString(comment.replace(/ ?[\r\n]+/g, " "));
        if (onComment)
          onComment();
      }
      if (!literal) {
        const foldedValue = value.replace(/\n+/g, "\n$&").replace(/(?:^|\n)([\t ].*)(?:([\n\t ]*)\n(?![\n\t ]))?/g, "$1$2").replace(/\n+/g, `$&${indent}`);
        let literalFallback = false;
        const foldOptions = getFoldOptions(ctx, true);
        if (blockQuote !== "folded" && type !== Scalar.Scalar.BLOCK_FOLDED) {
          foldOptions.onOverflow = () => {
            literalFallback = true;
          };
        }
        const body = foldFlowLines.foldFlowLines(`${start}${foldedValue}${end}`, indent, foldFlowLines.FOLD_BLOCK, foldOptions);
        if (!literalFallback)
          return `>${header}
${indent}${body}`;
      }
      value = value.replace(/\n+/g, `$&${indent}`);
      return `|${header}
${indent}${start}${value}${end}`;
    }
    function plainString(item, ctx, onComment, onChompKeep) {
      const { type, value } = item;
      const { actualString, implicitKey, indent, indentStep, inFlow } = ctx;
      if (implicitKey && value.includes("\n") || inFlow && /[[\]{},]/.test(value)) {
        return quotedString(value, ctx);
      }
      if (/^[\n\t ,[\]{}#&*!|>'"%@`]|^[?-]$|^[?-][ \t]|[\n:][ \t]|[ \t]\n|[\n\t ]#|[\n\t :]$/.test(value)) {
        return implicitKey || inFlow || !value.includes("\n") ? quotedString(value, ctx) : blockString(item, ctx, onComment, onChompKeep);
      }
      if (!implicitKey && !inFlow && type !== Scalar.Scalar.PLAIN && value.includes("\n")) {
        return blockString(item, ctx, onComment, onChompKeep);
      }
      if (containsDocumentMarker(value)) {
        if (indent === "") {
          ctx.forceBlockIndent = true;
          return blockString(item, ctx, onComment, onChompKeep);
        } else if (implicitKey && indent === indentStep) {
          return quotedString(value, ctx);
        }
      }
      const str = value.replace(/\n+/g, `$&
${indent}`);
      if (actualString) {
        const test = (tag) => tag.default && tag.tag !== "tag:yaml.org,2002:str" && tag.test?.test(str);
        const { compat, tags } = ctx.doc.schema;
        if (tags.some(test) || compat?.some(test))
          return quotedString(value, ctx);
      }
      return implicitKey ? str : foldFlowLines.foldFlowLines(str, indent, foldFlowLines.FOLD_FLOW, getFoldOptions(ctx, false));
    }
    function stringifyString(item, ctx, onComment, onChompKeep) {
      const { implicitKey, inFlow } = ctx;
      const ss = typeof item.value === "string" ? item : Object.assign({}, item, { value: String(item.value) });
      let { type } = item;
      if (type !== Scalar.Scalar.QUOTE_DOUBLE) {
        if (/[\x00-\x08\x0b-\x1f\x7f-\x9f\u{D800}-\u{DFFF}]/u.test(ss.value))
          type = Scalar.Scalar.QUOTE_DOUBLE;
      }
      const _stringify = (_type) => {
        switch (_type) {
          case Scalar.Scalar.BLOCK_FOLDED:
          case Scalar.Scalar.BLOCK_LITERAL:
            return implicitKey || inFlow ? quotedString(ss.value, ctx) : blockString(ss, ctx, onComment, onChompKeep);
          case Scalar.Scalar.QUOTE_DOUBLE:
            return doubleQuotedString(ss.value, ctx);
          case Scalar.Scalar.QUOTE_SINGLE:
            return singleQuotedString(ss.value, ctx);
          case Scalar.Scalar.PLAIN:
            return plainString(ss, ctx, onComment, onChompKeep);
          default:
            return null;
        }
      };
      let res = _stringify(type);
      if (res === null) {
        const { defaultKeyType, defaultStringType } = ctx.options;
        const t = implicitKey && defaultKeyType || defaultStringType;
        res = _stringify(t);
        if (res === null)
          throw new Error(`Unsupported default string type ${t}`);
      }
      return res;
    }
    exports.stringifyString = stringifyString;
  }
});

// ../../node_modules/yaml/dist/stringify/stringify.js
var require_stringify = __commonJS({
  "../../node_modules/yaml/dist/stringify/stringify.js"(exports) {
    "use strict";
    var anchors = require_anchors();
    var identity = require_identity();
    var stringifyComment = require_stringifyComment();
    var stringifyString = require_stringifyString();
    function createStringifyContext(doc, options) {
      const opt = Object.assign({
        blockQuote: true,
        commentString: stringifyComment.stringifyComment,
        defaultKeyType: null,
        defaultStringType: "PLAIN",
        directives: null,
        doubleQuotedAsJSON: false,
        doubleQuotedMinMultiLineLength: 40,
        falseStr: "false",
        flowCollectionPadding: true,
        indentSeq: true,
        lineWidth: 80,
        minContentWidth: 20,
        nullStr: "null",
        simpleKeys: false,
        singleQuote: null,
        trailingComma: false,
        trueStr: "true",
        verifyAliasOrder: true
      }, doc.schema.toStringOptions, options);
      let inFlow;
      switch (opt.collectionStyle) {
        case "block":
          inFlow = false;
          break;
        case "flow":
          inFlow = true;
          break;
        default:
          inFlow = null;
      }
      return {
        anchors: /* @__PURE__ */ new Set(),
        doc,
        flowCollectionPadding: opt.flowCollectionPadding ? " " : "",
        indent: "",
        indentStep: typeof opt.indent === "number" ? " ".repeat(opt.indent) : "  ",
        inFlow,
        options: opt
      };
    }
    function getTagObject(tags, item) {
      if (item.tag) {
        const match = tags.filter((t) => t.tag === item.tag);
        if (match.length > 0)
          return match.find((t) => t.format === item.format) ?? match[0];
      }
      let tagObj = void 0;
      let obj;
      if (identity.isScalar(item)) {
        obj = item.value;
        let match = tags.filter((t) => t.identify?.(obj));
        if (match.length > 1) {
          const testMatch = match.filter((t) => t.test);
          if (testMatch.length > 0)
            match = testMatch;
        }
        tagObj = match.find((t) => t.format === item.format) ?? match.find((t) => !t.format);
      } else {
        obj = item;
        tagObj = tags.find((t) => t.nodeClass && obj instanceof t.nodeClass);
      }
      if (!tagObj) {
        const name = obj?.constructor?.name ?? (obj === null ? "null" : typeof obj);
        throw new Error(`Tag not resolved for ${name} value`);
      }
      return tagObj;
    }
    function stringifyProps(node, tagObj, { anchors: anchors$1, doc }) {
      if (!doc.directives)
        return "";
      const props = [];
      const anchor = (identity.isScalar(node) || identity.isCollection(node)) && node.anchor;
      if (anchor && anchors.anchorIsValid(anchor)) {
        anchors$1.add(anchor);
        props.push(`&${anchor}`);
      }
      const tag = node.tag ?? (tagObj.default ? null : tagObj.tag);
      if (tag)
        props.push(doc.directives.tagString(tag));
      return props.join(" ");
    }
    function stringify(item, ctx, onComment, onChompKeep) {
      if (identity.isPair(item))
        return item.toString(ctx, onComment, onChompKeep);
      if (identity.isAlias(item)) {
        if (ctx.doc.directives)
          return item.toString(ctx);
        if (ctx.resolvedAliases?.has(item)) {
          throw new TypeError(`Cannot stringify circular structure without alias nodes`);
        } else {
          if (ctx.resolvedAliases)
            ctx.resolvedAliases.add(item);
          else
            ctx.resolvedAliases = /* @__PURE__ */ new Set([item]);
          item = item.resolve(ctx.doc);
        }
      }
      let tagObj = void 0;
      const node = identity.isNode(item) ? item : ctx.doc.createNode(item, { onTagObj: (o) => tagObj = o });
      tagObj ?? (tagObj = getTagObject(ctx.doc.schema.tags, node));
      const props = stringifyProps(node, tagObj, ctx);
      if (props.length > 0)
        ctx.indentAtStart = (ctx.indentAtStart ?? 0) + props.length + 1;
      const str = typeof tagObj.stringify === "function" ? tagObj.stringify(node, ctx, onComment, onChompKeep) : identity.isScalar(node) ? stringifyString.stringifyString(node, ctx, onComment, onChompKeep) : node.toString(ctx, onComment, onChompKeep);
      if (!props)
        return str;
      return identity.isScalar(node) || str[0] === "{" || str[0] === "[" ? `${props} ${str}` : `${props}
${ctx.indent}${str}`;
    }
    exports.createStringifyContext = createStringifyContext;
    exports.stringify = stringify;
  }
});

// ../../node_modules/yaml/dist/stringify/stringifyPair.js
var require_stringifyPair = __commonJS({
  "../../node_modules/yaml/dist/stringify/stringifyPair.js"(exports) {
    "use strict";
    var identity = require_identity();
    var Scalar = require_Scalar();
    var stringify = require_stringify();
    var stringifyComment = require_stringifyComment();
    function stringifyPair({ key, value }, ctx, onComment, onChompKeep) {
      const { allNullValues, doc, indent, indentStep, options: { commentString, indentSeq, simpleKeys } } = ctx;
      let keyComment = identity.isNode(key) && key.comment || null;
      if (simpleKeys) {
        if (keyComment) {
          throw new Error("With simple keys, key nodes cannot have comments");
        }
        if (identity.isCollection(key) || !identity.isNode(key) && typeof key === "object") {
          const msg = "With simple keys, collection cannot be used as a key value";
          throw new Error(msg);
        }
      }
      let explicitKey = !simpleKeys && (!key || keyComment && value == null && !ctx.inFlow || identity.isCollection(key) || (identity.isScalar(key) ? key.type === Scalar.Scalar.BLOCK_FOLDED || key.type === Scalar.Scalar.BLOCK_LITERAL : typeof key === "object"));
      ctx = Object.assign({}, ctx, {
        allNullValues: false,
        implicitKey: !explicitKey && (simpleKeys || !allNullValues),
        indent: indent + indentStep
      });
      let keyCommentDone = false;
      let chompKeep = false;
      let str = stringify.stringify(key, ctx, () => keyCommentDone = true, () => chompKeep = true);
      if (!explicitKey && !ctx.inFlow && str.length > 1024) {
        if (simpleKeys)
          throw new Error("With simple keys, single line scalar must not span more than 1024 characters");
        explicitKey = true;
      }
      if (ctx.inFlow) {
        if (allNullValues || value == null) {
          if (keyCommentDone && onComment)
            onComment();
          return str === "" ? "?" : explicitKey ? `? ${str}` : str;
        }
      } else if (allNullValues && !simpleKeys || value == null && explicitKey) {
        str = `? ${str}`;
        if (keyComment && !keyCommentDone) {
          str += stringifyComment.lineComment(str, ctx.indent, commentString(keyComment));
        } else if (chompKeep && onChompKeep)
          onChompKeep();
        return str;
      }
      if (keyCommentDone)
        keyComment = null;
      if (explicitKey) {
        if (keyComment)
          str += stringifyComment.lineComment(str, ctx.indent, commentString(keyComment));
        str = `? ${str}
${indent}:`;
      } else {
        str = `${str}:`;
        if (keyComment)
          str += stringifyComment.lineComment(str, ctx.indent, commentString(keyComment));
      }
      let vsb, vcb, valueComment;
      if (identity.isNode(value)) {
        vsb = !!value.spaceBefore;
        vcb = value.commentBefore;
        valueComment = value.comment;
      } else {
        vsb = false;
        vcb = null;
        valueComment = null;
        if (value && typeof value === "object")
          value = doc.createNode(value);
      }
      ctx.implicitKey = false;
      if (!explicitKey && !keyComment && identity.isScalar(value))
        ctx.indentAtStart = str.length + 1;
      chompKeep = false;
      if (!indentSeq && indentStep.length >= 2 && !ctx.inFlow && !explicitKey && identity.isSeq(value) && !value.flow && !value.tag && !value.anchor) {
        ctx.indent = ctx.indent.substring(2);
      }
      let valueCommentDone = false;
      const valueStr = stringify.stringify(value, ctx, () => valueCommentDone = true, () => chompKeep = true);
      let ws = " ";
      if (keyComment || vsb || vcb) {
        ws = vsb ? "\n" : "";
        if (vcb) {
          const cs = commentString(vcb);
          ws += `
${stringifyComment.indentComment(cs, ctx.indent)}`;
        }
        if (valueStr === "" && !ctx.inFlow) {
          if (ws === "\n" && valueComment)
            ws = "\n\n";
        } else {
          ws += `
${ctx.indent}`;
        }
      } else if (!explicitKey && identity.isCollection(value)) {
        const vs0 = valueStr[0];
        const nl0 = valueStr.indexOf("\n");
        const hasNewline = nl0 !== -1;
        const flow = ctx.inFlow ?? value.flow ?? value.items.length === 0;
        if (hasNewline || !flow) {
          let hasPropsLine = false;
          if (hasNewline && (vs0 === "&" || vs0 === "!")) {
            let sp0 = valueStr.indexOf(" ");
            if (vs0 === "&" && sp0 !== -1 && sp0 < nl0 && valueStr[sp0 + 1] === "!") {
              sp0 = valueStr.indexOf(" ", sp0 + 1);
            }
            if (sp0 === -1 || nl0 < sp0)
              hasPropsLine = true;
          }
          if (!hasPropsLine)
            ws = `
${ctx.indent}`;
        }
      } else if (valueStr === "" || valueStr[0] === "\n") {
        ws = "";
      }
      str += ws + valueStr;
      if (ctx.inFlow) {
        if (valueCommentDone && onComment)
          onComment();
      } else if (valueComment && !valueCommentDone) {
        str += stringifyComment.lineComment(str, ctx.indent, commentString(valueComment));
      } else if (chompKeep && onChompKeep) {
        onChompKeep();
      }
      return str;
    }
    exports.stringifyPair = stringifyPair;
  }
});

// ../../node_modules/yaml/dist/log.js
var require_log = __commonJS({
  "../../node_modules/yaml/dist/log.js"(exports) {
    "use strict";
    var node_process = __require("process");
    function debug(logLevel, ...messages) {
      if (logLevel === "debug")
        console.log(...messages);
    }
    function warn(logLevel, warning) {
      if (logLevel === "debug" || logLevel === "warn") {
        if (typeof node_process.emitWarning === "function")
          node_process.emitWarning(warning);
        else
          console.warn(warning);
      }
    }
    exports.debug = debug;
    exports.warn = warn;
  }
});

// ../../node_modules/yaml/dist/schema/yaml-1.1/merge.js
var require_merge = __commonJS({
  "../../node_modules/yaml/dist/schema/yaml-1.1/merge.js"(exports) {
    "use strict";
    var identity = require_identity();
    var Scalar = require_Scalar();
    var MERGE_KEY = "<<";
    var merge = {
      identify: (value) => value === MERGE_KEY || typeof value === "symbol" && value.description === MERGE_KEY,
      default: "key",
      tag: "tag:yaml.org,2002:merge",
      test: /^<<$/,
      resolve: () => Object.assign(new Scalar.Scalar(Symbol(MERGE_KEY)), {
        addToJSMap: addMergeToJSMap
      }),
      stringify: () => MERGE_KEY
    };
    var isMergeKey = (ctx, key) => (merge.identify(key) || identity.isScalar(key) && (!key.type || key.type === Scalar.Scalar.PLAIN) && merge.identify(key.value)) && ctx?.doc.schema.tags.some((tag) => tag.tag === merge.tag && tag.default);
    function addMergeToJSMap(ctx, map, value) {
      const source = resolveAliasValue(ctx, value);
      if (identity.isSeq(source))
        for (const it of source.items)
          mergeValue(ctx, map, it);
      else if (Array.isArray(source))
        for (const it of source)
          mergeValue(ctx, map, it);
      else
        mergeValue(ctx, map, source);
    }
    function mergeValue(ctx, map, value) {
      const source = resolveAliasValue(ctx, value);
      if (!identity.isMap(source))
        throw new Error("Merge sources must be maps or map aliases");
      const srcMap = source.toJSON(null, ctx, Map);
      for (const [key, value2] of srcMap) {
        if (map instanceof Map) {
          if (!map.has(key))
            map.set(key, value2);
        } else if (map instanceof Set) {
          map.add(key);
        } else if (!Object.prototype.hasOwnProperty.call(map, key)) {
          Object.defineProperty(map, key, {
            value: value2,
            writable: true,
            enumerable: true,
            configurable: true
          });
        }
      }
      return map;
    }
    function resolveAliasValue(ctx, value) {
      return ctx && identity.isAlias(value) ? value.resolve(ctx.doc, ctx) : value;
    }
    exports.addMergeToJSMap = addMergeToJSMap;
    exports.isMergeKey = isMergeKey;
    exports.merge = merge;
  }
});

// ../../node_modules/yaml/dist/nodes/addPairToJSMap.js
var require_addPairToJSMap = __commonJS({
  "../../node_modules/yaml/dist/nodes/addPairToJSMap.js"(exports) {
    "use strict";
    var log2 = require_log();
    var merge = require_merge();
    var stringify = require_stringify();
    var identity = require_identity();
    var toJS = require_toJS();
    function addPairToJSMap(ctx, map, { key, value }) {
      if (identity.isNode(key) && key.addToJSMap)
        key.addToJSMap(ctx, map, value);
      else if (merge.isMergeKey(ctx, key))
        merge.addMergeToJSMap(ctx, map, value);
      else {
        const jsKey = toJS.toJS(key, "", ctx);
        if (map instanceof Map) {
          map.set(jsKey, toJS.toJS(value, jsKey, ctx));
        } else if (map instanceof Set) {
          map.add(jsKey);
        } else {
          const stringKey = stringifyKey(key, jsKey, ctx);
          const jsValue = toJS.toJS(value, stringKey, ctx);
          if (stringKey in map)
            Object.defineProperty(map, stringKey, {
              value: jsValue,
              writable: true,
              enumerable: true,
              configurable: true
            });
          else
            map[stringKey] = jsValue;
        }
      }
      return map;
    }
    function stringifyKey(key, jsKey, ctx) {
      if (jsKey === null)
        return "";
      if (typeof jsKey !== "object")
        return String(jsKey);
      if (identity.isNode(key) && ctx?.doc) {
        const strCtx = stringify.createStringifyContext(ctx.doc, {});
        strCtx.anchors = /* @__PURE__ */ new Set();
        for (const node of ctx.anchors.keys())
          strCtx.anchors.add(node.anchor);
        strCtx.inFlow = true;
        strCtx.inStringifyKey = true;
        const strKey = key.toString(strCtx);
        if (!ctx.mapKeyWarned) {
          let jsonStr = JSON.stringify(strKey);
          if (jsonStr.length > 40)
            jsonStr = jsonStr.substring(0, 36) + '..."';
          log2.warn(ctx.doc.options.logLevel, `Keys with collection values will be stringified due to JS Object restrictions: ${jsonStr}. Set mapAsMap: true to use object keys.`);
          ctx.mapKeyWarned = true;
        }
        return strKey;
      }
      return JSON.stringify(jsKey);
    }
    exports.addPairToJSMap = addPairToJSMap;
  }
});

// ../../node_modules/yaml/dist/nodes/Pair.js
var require_Pair = __commonJS({
  "../../node_modules/yaml/dist/nodes/Pair.js"(exports) {
    "use strict";
    var createNode = require_createNode();
    var stringifyPair = require_stringifyPair();
    var addPairToJSMap = require_addPairToJSMap();
    var identity = require_identity();
    function createPair(key, value, ctx) {
      const k = createNode.createNode(key, void 0, ctx);
      const v = createNode.createNode(value, void 0, ctx);
      return new Pair(k, v);
    }
    var Pair = class _Pair {
      constructor(key, value = null) {
        Object.defineProperty(this, identity.NODE_TYPE, { value: identity.PAIR });
        this.key = key;
        this.value = value;
      }
      clone(schema) {
        let { key, value } = this;
        if (identity.isNode(key))
          key = key.clone(schema);
        if (identity.isNode(value))
          value = value.clone(schema);
        return new _Pair(key, value);
      }
      toJSON(_, ctx) {
        const pair = ctx?.mapAsMap ? /* @__PURE__ */ new Map() : {};
        return addPairToJSMap.addPairToJSMap(ctx, pair, this);
      }
      toString(ctx, onComment, onChompKeep) {
        return ctx?.doc ? stringifyPair.stringifyPair(this, ctx, onComment, onChompKeep) : JSON.stringify(this);
      }
    };
    exports.Pair = Pair;
    exports.createPair = createPair;
  }
});

// ../../node_modules/yaml/dist/stringify/stringifyCollection.js
var require_stringifyCollection = __commonJS({
  "../../node_modules/yaml/dist/stringify/stringifyCollection.js"(exports) {
    "use strict";
    var identity = require_identity();
    var stringify = require_stringify();
    var stringifyComment = require_stringifyComment();
    function stringifyCollection(collection, ctx, options) {
      const flow = ctx.inFlow ?? collection.flow;
      const stringify2 = flow ? stringifyFlowCollection : stringifyBlockCollection;
      return stringify2(collection, ctx, options);
    }
    function stringifyBlockCollection({ comment, items }, ctx, { blockItemPrefix, flowChars, itemIndent, onChompKeep, onComment }) {
      const { indent, options: { commentString } } = ctx;
      const itemCtx = Object.assign({}, ctx, { indent: itemIndent, type: null });
      let chompKeep = false;
      const lines = [];
      for (let i = 0; i < items.length; ++i) {
        const item = items[i];
        let comment2 = null;
        if (identity.isNode(item)) {
          if (!chompKeep && item.spaceBefore)
            lines.push("");
          addCommentBefore(ctx, lines, item.commentBefore, chompKeep);
          if (item.comment)
            comment2 = item.comment;
        } else if (identity.isPair(item)) {
          const ik = identity.isNode(item.key) ? item.key : null;
          if (ik) {
            if (!chompKeep && ik.spaceBefore)
              lines.push("");
            addCommentBefore(ctx, lines, ik.commentBefore, chompKeep);
          }
        }
        chompKeep = false;
        let str2 = stringify.stringify(item, itemCtx, () => comment2 = null, () => chompKeep = true);
        if (comment2)
          str2 += stringifyComment.lineComment(str2, itemIndent, commentString(comment2));
        if (chompKeep && comment2)
          chompKeep = false;
        lines.push(blockItemPrefix + str2);
      }
      let str;
      if (lines.length === 0) {
        str = flowChars.start + flowChars.end;
      } else {
        str = lines[0];
        for (let i = 1; i < lines.length; ++i) {
          const line = lines[i];
          str += line ? `
${indent}${line}` : "\n";
        }
      }
      if (comment) {
        str += "\n" + stringifyComment.indentComment(commentString(comment), indent);
        if (onComment)
          onComment();
      } else if (chompKeep && onChompKeep)
        onChompKeep();
      return str;
    }
    function stringifyFlowCollection({ items }, ctx, { flowChars, itemIndent }) {
      const { indent, indentStep, flowCollectionPadding: fcPadding, options: { commentString } } = ctx;
      itemIndent += indentStep;
      const itemCtx = Object.assign({}, ctx, {
        indent: itemIndent,
        inFlow: true,
        type: null
      });
      let reqNewline = false;
      let linesAtValue = 0;
      const lines = [];
      for (let i = 0; i < items.length; ++i) {
        const item = items[i];
        let comment = null;
        if (identity.isNode(item)) {
          if (item.spaceBefore)
            lines.push("");
          addCommentBefore(ctx, lines, item.commentBefore, false);
          if (item.comment)
            comment = item.comment;
        } else if (identity.isPair(item)) {
          const ik = identity.isNode(item.key) ? item.key : null;
          if (ik) {
            if (ik.spaceBefore)
              lines.push("");
            addCommentBefore(ctx, lines, ik.commentBefore, false);
            if (ik.comment)
              reqNewline = true;
          }
          const iv = identity.isNode(item.value) ? item.value : null;
          if (iv) {
            if (iv.comment)
              comment = iv.comment;
            if (iv.commentBefore)
              reqNewline = true;
          } else if (item.value == null && ik?.comment) {
            comment = ik.comment;
          }
        }
        if (comment)
          reqNewline = true;
        let str = stringify.stringify(item, itemCtx, () => comment = null);
        reqNewline || (reqNewline = lines.length > linesAtValue || str.includes("\n"));
        if (i < items.length - 1) {
          str += ",";
        } else if (ctx.options.trailingComma) {
          if (ctx.options.lineWidth > 0) {
            reqNewline || (reqNewline = lines.reduce((sum, line) => sum + line.length + 2, 2) + (str.length + 2) > ctx.options.lineWidth);
          }
          if (reqNewline) {
            str += ",";
          }
        }
        if (comment)
          str += stringifyComment.lineComment(str, itemIndent, commentString(comment));
        lines.push(str);
        linesAtValue = lines.length;
      }
      const { start, end } = flowChars;
      if (lines.length === 0) {
        return start + end;
      } else {
        if (!reqNewline) {
          const len = lines.reduce((sum, line) => sum + line.length + 2, 2);
          reqNewline = ctx.options.lineWidth > 0 && len > ctx.options.lineWidth;
        }
        if (reqNewline) {
          let str = start;
          for (const line of lines)
            str += line ? `
${indentStep}${indent}${line}` : "\n";
          return `${str}
${indent}${end}`;
        } else {
          return `${start}${fcPadding}${lines.join(" ")}${fcPadding}${end}`;
        }
      }
    }
    function addCommentBefore({ indent, options: { commentString } }, lines, comment, chompKeep) {
      if (comment && chompKeep)
        comment = comment.replace(/^\n+/, "");
      if (comment) {
        const ic = stringifyComment.indentComment(commentString(comment), indent);
        lines.push(ic.trimStart());
      }
    }
    exports.stringifyCollection = stringifyCollection;
  }
});

// ../../node_modules/yaml/dist/nodes/YAMLMap.js
var require_YAMLMap = __commonJS({
  "../../node_modules/yaml/dist/nodes/YAMLMap.js"(exports) {
    "use strict";
    var stringifyCollection = require_stringifyCollection();
    var addPairToJSMap = require_addPairToJSMap();
    var Collection = require_Collection();
    var identity = require_identity();
    var Pair = require_Pair();
    var Scalar = require_Scalar();
    function findPair(items, key) {
      const k = identity.isScalar(key) ? key.value : key;
      for (const it of items) {
        if (identity.isPair(it)) {
          if (it.key === key || it.key === k)
            return it;
          if (identity.isScalar(it.key) && it.key.value === k)
            return it;
        }
      }
      return void 0;
    }
    var YAMLMap = class extends Collection.Collection {
      static get tagName() {
        return "tag:yaml.org,2002:map";
      }
      constructor(schema) {
        super(identity.MAP, schema);
        this.items = [];
      }
      /**
       * A generic collection parsing method that can be extended
       * to other node classes that inherit from YAMLMap
       */
      static from(schema, obj, ctx) {
        const { keepUndefined, replacer } = ctx;
        const map = new this(schema);
        const add = (key, value) => {
          if (typeof replacer === "function")
            value = replacer.call(obj, key, value);
          else if (Array.isArray(replacer) && !replacer.includes(key))
            return;
          if (value !== void 0 || keepUndefined)
            map.items.push(Pair.createPair(key, value, ctx));
        };
        if (obj instanceof Map) {
          for (const [key, value] of obj)
            add(key, value);
        } else if (obj && typeof obj === "object") {
          for (const key of Object.keys(obj))
            add(key, obj[key]);
        }
        if (typeof schema.sortMapEntries === "function") {
          map.items.sort(schema.sortMapEntries);
        }
        return map;
      }
      /**
       * Adds a value to the collection.
       *
       * @param overwrite - If not set `true`, using a key that is already in the
       *   collection will throw. Otherwise, overwrites the previous value.
       */
      add(pair, overwrite) {
        let _pair;
        if (identity.isPair(pair))
          _pair = pair;
        else if (!pair || typeof pair !== "object" || !("key" in pair)) {
          _pair = new Pair.Pair(pair, pair?.value);
        } else
          _pair = new Pair.Pair(pair.key, pair.value);
        const prev = findPair(this.items, _pair.key);
        const sortEntries = this.schema?.sortMapEntries;
        if (prev) {
          if (!overwrite)
            throw new Error(`Key ${_pair.key} already set`);
          if (identity.isScalar(prev.value) && Scalar.isScalarValue(_pair.value))
            prev.value.value = _pair.value;
          else
            prev.value = _pair.value;
        } else if (sortEntries) {
          const i = this.items.findIndex((item) => sortEntries(_pair, item) < 0);
          if (i === -1)
            this.items.push(_pair);
          else
            this.items.splice(i, 0, _pair);
        } else {
          this.items.push(_pair);
        }
      }
      delete(key) {
        const it = findPair(this.items, key);
        if (!it)
          return false;
        const del = this.items.splice(this.items.indexOf(it), 1);
        return del.length > 0;
      }
      get(key, keepScalar) {
        const it = findPair(this.items, key);
        const node = it?.value;
        return (!keepScalar && identity.isScalar(node) ? node.value : node) ?? void 0;
      }
      has(key) {
        return !!findPair(this.items, key);
      }
      set(key, value) {
        this.add(new Pair.Pair(key, value), true);
      }
      /**
       * @param ctx - Conversion context, originally set in Document#toJS()
       * @param {Class} Type - If set, forces the returned collection type
       * @returns Instance of Type, Map, or Object
       */
      toJSON(_, ctx, Type) {
        const map = Type ? new Type() : ctx?.mapAsMap ? /* @__PURE__ */ new Map() : {};
        if (ctx?.onCreate)
          ctx.onCreate(map);
        for (const item of this.items)
          addPairToJSMap.addPairToJSMap(ctx, map, item);
        return map;
      }
      toString(ctx, onComment, onChompKeep) {
        if (!ctx)
          return JSON.stringify(this);
        for (const item of this.items) {
          if (!identity.isPair(item))
            throw new Error(`Map items must all be pairs; found ${JSON.stringify(item)} instead`);
        }
        if (!ctx.allNullValues && this.hasAllNullValues(false))
          ctx = Object.assign({}, ctx, { allNullValues: true });
        return stringifyCollection.stringifyCollection(this, ctx, {
          blockItemPrefix: "",
          flowChars: { start: "{", end: "}" },
          itemIndent: ctx.indent || "",
          onChompKeep,
          onComment
        });
      }
    };
    exports.YAMLMap = YAMLMap;
    exports.findPair = findPair;
  }
});

// ../../node_modules/yaml/dist/schema/common/map.js
var require_map = __commonJS({
  "../../node_modules/yaml/dist/schema/common/map.js"(exports) {
    "use strict";
    var identity = require_identity();
    var YAMLMap = require_YAMLMap();
    var map = {
      collection: "map",
      default: true,
      nodeClass: YAMLMap.YAMLMap,
      tag: "tag:yaml.org,2002:map",
      resolve(map2, onError) {
        if (!identity.isMap(map2))
          onError("Expected a mapping for this tag");
        return map2;
      },
      createNode: (schema, obj, ctx) => YAMLMap.YAMLMap.from(schema, obj, ctx)
    };
    exports.map = map;
  }
});

// ../../node_modules/yaml/dist/nodes/YAMLSeq.js
var require_YAMLSeq = __commonJS({
  "../../node_modules/yaml/dist/nodes/YAMLSeq.js"(exports) {
    "use strict";
    var createNode = require_createNode();
    var stringifyCollection = require_stringifyCollection();
    var Collection = require_Collection();
    var identity = require_identity();
    var Scalar = require_Scalar();
    var toJS = require_toJS();
    var YAMLSeq = class extends Collection.Collection {
      static get tagName() {
        return "tag:yaml.org,2002:seq";
      }
      constructor(schema) {
        super(identity.SEQ, schema);
        this.items = [];
      }
      add(value) {
        this.items.push(value);
      }
      /**
       * Removes a value from the collection.
       *
       * `key` must contain a representation of an integer for this to succeed.
       * It may be wrapped in a `Scalar`.
       *
       * @returns `true` if the item was found and removed.
       */
      delete(key) {
        const idx = asItemIndex(key);
        if (typeof idx !== "number")
          return false;
        const del = this.items.splice(idx, 1);
        return del.length > 0;
      }
      get(key, keepScalar) {
        const idx = asItemIndex(key);
        if (typeof idx !== "number")
          return void 0;
        const it = this.items[idx];
        return !keepScalar && identity.isScalar(it) ? it.value : it;
      }
      /**
       * Checks if the collection includes a value with the key `key`.
       *
       * `key` must contain a representation of an integer for this to succeed.
       * It may be wrapped in a `Scalar`.
       */
      has(key) {
        const idx = asItemIndex(key);
        return typeof idx === "number" && idx < this.items.length;
      }
      /**
       * Sets a value in this collection. For `!!set`, `value` needs to be a
       * boolean to add/remove the item from the set.
       *
       * If `key` does not contain a representation of an integer, this will throw.
       * It may be wrapped in a `Scalar`.
       */
      set(key, value) {
        const idx = asItemIndex(key);
        if (typeof idx !== "number")
          throw new Error(`Expected a valid index, not ${key}.`);
        const prev = this.items[idx];
        if (identity.isScalar(prev) && Scalar.isScalarValue(value))
          prev.value = value;
        else
          this.items[idx] = value;
      }
      toJSON(_, ctx) {
        const seq = [];
        if (ctx?.onCreate)
          ctx.onCreate(seq);
        let i = 0;
        for (const item of this.items)
          seq.push(toJS.toJS(item, String(i++), ctx));
        return seq;
      }
      toString(ctx, onComment, onChompKeep) {
        if (!ctx)
          return JSON.stringify(this);
        return stringifyCollection.stringifyCollection(this, ctx, {
          blockItemPrefix: "- ",
          flowChars: { start: "[", end: "]" },
          itemIndent: (ctx.indent || "") + "  ",
          onChompKeep,
          onComment
        });
      }
      static from(schema, obj, ctx) {
        const { replacer } = ctx;
        const seq = new this(schema);
        if (obj && Symbol.iterator in Object(obj)) {
          let i = 0;
          for (let it of obj) {
            if (typeof replacer === "function") {
              const key = obj instanceof Set ? it : String(i++);
              it = replacer.call(obj, key, it);
            }
            seq.items.push(createNode.createNode(it, void 0, ctx));
          }
        }
        return seq;
      }
    };
    function asItemIndex(key) {
      let idx = identity.isScalar(key) ? key.value : key;
      if (idx && typeof idx === "string")
        idx = Number(idx);
      return typeof idx === "number" && Number.isInteger(idx) && idx >= 0 ? idx : null;
    }
    exports.YAMLSeq = YAMLSeq;
  }
});

// ../../node_modules/yaml/dist/schema/common/seq.js
var require_seq = __commonJS({
  "../../node_modules/yaml/dist/schema/common/seq.js"(exports) {
    "use strict";
    var identity = require_identity();
    var YAMLSeq = require_YAMLSeq();
    var seq = {
      collection: "seq",
      default: true,
      nodeClass: YAMLSeq.YAMLSeq,
      tag: "tag:yaml.org,2002:seq",
      resolve(seq2, onError) {
        if (!identity.isSeq(seq2))
          onError("Expected a sequence for this tag");
        return seq2;
      },
      createNode: (schema, obj, ctx) => YAMLSeq.YAMLSeq.from(schema, obj, ctx)
    };
    exports.seq = seq;
  }
});

// ../../node_modules/yaml/dist/schema/common/string.js
var require_string = __commonJS({
  "../../node_modules/yaml/dist/schema/common/string.js"(exports) {
    "use strict";
    var stringifyString = require_stringifyString();
    var string = {
      identify: (value) => typeof value === "string",
      default: true,
      tag: "tag:yaml.org,2002:str",
      resolve: (str) => str,
      stringify(item, ctx, onComment, onChompKeep) {
        ctx = Object.assign({ actualString: true }, ctx);
        return stringifyString.stringifyString(item, ctx, onComment, onChompKeep);
      }
    };
    exports.string = string;
  }
});

// ../../node_modules/yaml/dist/schema/common/null.js
var require_null = __commonJS({
  "../../node_modules/yaml/dist/schema/common/null.js"(exports) {
    "use strict";
    var Scalar = require_Scalar();
    var nullTag = {
      identify: (value) => value == null,
      createNode: () => new Scalar.Scalar(null),
      default: true,
      tag: "tag:yaml.org,2002:null",
      test: /^(?:~|[Nn]ull|NULL)?$/,
      resolve: () => new Scalar.Scalar(null),
      stringify: ({ source }, ctx) => typeof source === "string" && nullTag.test.test(source) ? source : ctx.options.nullStr
    };
    exports.nullTag = nullTag;
  }
});

// ../../node_modules/yaml/dist/schema/core/bool.js
var require_bool = __commonJS({
  "../../node_modules/yaml/dist/schema/core/bool.js"(exports) {
    "use strict";
    var Scalar = require_Scalar();
    var boolTag = {
      identify: (value) => typeof value === "boolean",
      default: true,
      tag: "tag:yaml.org,2002:bool",
      test: /^(?:[Tt]rue|TRUE|[Ff]alse|FALSE)$/,
      resolve: (str) => new Scalar.Scalar(str[0] === "t" || str[0] === "T"),
      stringify({ source, value }, ctx) {
        if (source && boolTag.test.test(source)) {
          const sv = source[0] === "t" || source[0] === "T";
          if (value === sv)
            return source;
        }
        return value ? ctx.options.trueStr : ctx.options.falseStr;
      }
    };
    exports.boolTag = boolTag;
  }
});

// ../../node_modules/yaml/dist/stringify/stringifyNumber.js
var require_stringifyNumber = __commonJS({
  "../../node_modules/yaml/dist/stringify/stringifyNumber.js"(exports) {
    "use strict";
    function stringifyNumber({ format, minFractionDigits, tag, value }) {
      if (typeof value === "bigint")
        return String(value);
      const num = typeof value === "number" ? value : Number(value);
      if (!isFinite(num))
        return isNaN(num) ? ".nan" : num < 0 ? "-.inf" : ".inf";
      let n = Object.is(value, -0) ? "-0" : JSON.stringify(value);
      if (!format && minFractionDigits && (!tag || tag === "tag:yaml.org,2002:float") && /^-?\d/.test(n) && !n.includes("e")) {
        let i = n.indexOf(".");
        if (i < 0) {
          i = n.length;
          n += ".";
        }
        let d = minFractionDigits - (n.length - i - 1);
        while (d-- > 0)
          n += "0";
      }
      return n;
    }
    exports.stringifyNumber = stringifyNumber;
  }
});

// ../../node_modules/yaml/dist/schema/core/float.js
var require_float = __commonJS({
  "../../node_modules/yaml/dist/schema/core/float.js"(exports) {
    "use strict";
    var Scalar = require_Scalar();
    var stringifyNumber = require_stringifyNumber();
    var floatNaN = {
      identify: (value) => typeof value === "number",
      default: true,
      tag: "tag:yaml.org,2002:float",
      test: /^(?:[-+]?\.(?:inf|Inf|INF)|\.nan|\.NaN|\.NAN)$/,
      resolve: (str) => str.slice(-3).toLowerCase() === "nan" ? NaN : str[0] === "-" ? Number.NEGATIVE_INFINITY : Number.POSITIVE_INFINITY,
      stringify: stringifyNumber.stringifyNumber
    };
    var floatExp = {
      identify: (value) => typeof value === "number",
      default: true,
      tag: "tag:yaml.org,2002:float",
      format: "EXP",
      test: /^[-+]?(?:\.[0-9]+|[0-9]+(?:\.[0-9]*)?)[eE][-+]?[0-9]+$/,
      resolve: (str) => parseFloat(str),
      stringify(node) {
        const num = Number(node.value);
        return isFinite(num) ? num.toExponential() : stringifyNumber.stringifyNumber(node);
      }
    };
    var float = {
      identify: (value) => typeof value === "number",
      default: true,
      tag: "tag:yaml.org,2002:float",
      test: /^[-+]?(?:\.[0-9]+|[0-9]+\.[0-9]*)$/,
      resolve(str) {
        const node = new Scalar.Scalar(parseFloat(str));
        const dot = str.indexOf(".");
        if (dot !== -1 && str[str.length - 1] === "0")
          node.minFractionDigits = str.length - dot - 1;
        return node;
      },
      stringify: stringifyNumber.stringifyNumber
    };
    exports.float = float;
    exports.floatExp = floatExp;
    exports.floatNaN = floatNaN;
  }
});

// ../../node_modules/yaml/dist/schema/core/int.js
var require_int = __commonJS({
  "../../node_modules/yaml/dist/schema/core/int.js"(exports) {
    "use strict";
    var stringifyNumber = require_stringifyNumber();
    var intIdentify = (value) => typeof value === "bigint" || Number.isInteger(value);
    var intResolve = (str, offset, radix, { intAsBigInt }) => intAsBigInt ? BigInt(str) : parseInt(str.substring(offset), radix);
    function intStringify(node, radix, prefix) {
      const { value } = node;
      if (intIdentify(value) && value >= 0)
        return prefix + value.toString(radix);
      return stringifyNumber.stringifyNumber(node);
    }
    var intOct = {
      identify: (value) => intIdentify(value) && value >= 0,
      default: true,
      tag: "tag:yaml.org,2002:int",
      format: "OCT",
      test: /^0o[0-7]+$/,
      resolve: (str, _onError, opt) => intResolve(str, 2, 8, opt),
      stringify: (node) => intStringify(node, 8, "0o")
    };
    var int = {
      identify: intIdentify,
      default: true,
      tag: "tag:yaml.org,2002:int",
      test: /^[-+]?[0-9]+$/,
      resolve: (str, _onError, opt) => intResolve(str, 0, 10, opt),
      stringify: stringifyNumber.stringifyNumber
    };
    var intHex = {
      identify: (value) => intIdentify(value) && value >= 0,
      default: true,
      tag: "tag:yaml.org,2002:int",
      format: "HEX",
      test: /^0x[0-9a-fA-F]+$/,
      resolve: (str, _onError, opt) => intResolve(str, 2, 16, opt),
      stringify: (node) => intStringify(node, 16, "0x")
    };
    exports.int = int;
    exports.intHex = intHex;
    exports.intOct = intOct;
  }
});

// ../../node_modules/yaml/dist/schema/core/schema.js
var require_schema = __commonJS({
  "../../node_modules/yaml/dist/schema/core/schema.js"(exports) {
    "use strict";
    var map = require_map();
    var _null = require_null();
    var seq = require_seq();
    var string = require_string();
    var bool = require_bool();
    var float = require_float();
    var int = require_int();
    var schema = [
      map.map,
      seq.seq,
      string.string,
      _null.nullTag,
      bool.boolTag,
      int.intOct,
      int.int,
      int.intHex,
      float.floatNaN,
      float.floatExp,
      float.float
    ];
    exports.schema = schema;
  }
});

// ../../node_modules/yaml/dist/schema/json/schema.js
var require_schema2 = __commonJS({
  "../../node_modules/yaml/dist/schema/json/schema.js"(exports) {
    "use strict";
    var Scalar = require_Scalar();
    var map = require_map();
    var seq = require_seq();
    function intIdentify(value) {
      return typeof value === "bigint" || Number.isInteger(value);
    }
    var stringifyJSON = ({ value }) => JSON.stringify(value);
    var jsonScalars = [
      {
        identify: (value) => typeof value === "string",
        default: true,
        tag: "tag:yaml.org,2002:str",
        resolve: (str) => str,
        stringify: stringifyJSON
      },
      {
        identify: (value) => value == null,
        createNode: () => new Scalar.Scalar(null),
        default: true,
        tag: "tag:yaml.org,2002:null",
        test: /^null$/,
        resolve: () => null,
        stringify: stringifyJSON
      },
      {
        identify: (value) => typeof value === "boolean",
        default: true,
        tag: "tag:yaml.org,2002:bool",
        test: /^true$|^false$/,
        resolve: (str) => str === "true",
        stringify: stringifyJSON
      },
      {
        identify: intIdentify,
        default: true,
        tag: "tag:yaml.org,2002:int",
        test: /^-?(?:0|[1-9][0-9]*)$/,
        resolve: (str, _onError, { intAsBigInt }) => intAsBigInt ? BigInt(str) : parseInt(str, 10),
        stringify: ({ value }) => intIdentify(value) ? value.toString() : JSON.stringify(value)
      },
      {
        identify: (value) => typeof value === "number",
        default: true,
        tag: "tag:yaml.org,2002:float",
        test: /^-?(?:0|[1-9][0-9]*)(?:\.[0-9]*)?(?:[eE][-+]?[0-9]+)?$/,
        resolve: (str) => parseFloat(str),
        stringify: stringifyJSON
      }
    ];
    var jsonError = {
      default: true,
      tag: "",
      test: /^/,
      resolve(str, onError) {
        onError(`Unresolved plain scalar ${JSON.stringify(str)}`);
        return str;
      }
    };
    var schema = [map.map, seq.seq].concat(jsonScalars, jsonError);
    exports.schema = schema;
  }
});

// ../../node_modules/yaml/dist/schema/yaml-1.1/binary.js
var require_binary = __commonJS({
  "../../node_modules/yaml/dist/schema/yaml-1.1/binary.js"(exports) {
    "use strict";
    var node_buffer = __require("buffer");
    var Scalar = require_Scalar();
    var stringifyString = require_stringifyString();
    var binary = {
      identify: (value) => value instanceof Uint8Array,
      // Buffer inherits from Uint8Array
      default: false,
      tag: "tag:yaml.org,2002:binary",
      /**
       * Returns a Buffer in node and an Uint8Array in browsers
       *
       * To use the resulting buffer as an image, you'll want to do something like:
       *
       *   const blob = new Blob([buffer], { type: 'image/jpeg' })
       *   document.querySelector('#photo').src = URL.createObjectURL(blob)
       */
      resolve(src, onError) {
        if (typeof node_buffer.Buffer === "function") {
          return node_buffer.Buffer.from(src, "base64");
        } else if (typeof atob === "function") {
          const str = atob(src.replace(/[\n\r]/g, ""));
          const buffer = new Uint8Array(str.length);
          for (let i = 0; i < str.length; ++i)
            buffer[i] = str.charCodeAt(i);
          return buffer;
        } else {
          onError("This environment does not support reading binary tags; either Buffer or atob is required");
          return src;
        }
      },
      stringify({ comment, type, value }, ctx, onComment, onChompKeep) {
        if (!value)
          return "";
        const buf = value;
        let str;
        if (typeof node_buffer.Buffer === "function") {
          str = buf instanceof node_buffer.Buffer ? buf.toString("base64") : node_buffer.Buffer.from(buf.buffer).toString("base64");
        } else if (typeof btoa === "function") {
          let s = "";
          for (let i = 0; i < buf.length; ++i)
            s += String.fromCharCode(buf[i]);
          str = btoa(s);
        } else {
          throw new Error("This environment does not support writing binary tags; either Buffer or btoa is required");
        }
        type ?? (type = Scalar.Scalar.BLOCK_LITERAL);
        if (type !== Scalar.Scalar.QUOTE_DOUBLE) {
          const lineWidth = Math.max(ctx.options.lineWidth - ctx.indent.length, ctx.options.minContentWidth);
          const n = Math.ceil(str.length / lineWidth);
          const lines = new Array(n);
          for (let i = 0, o = 0; i < n; ++i, o += lineWidth) {
            lines[i] = str.substr(o, lineWidth);
          }
          str = lines.join(type === Scalar.Scalar.BLOCK_LITERAL ? "\n" : " ");
        }
        return stringifyString.stringifyString({ comment, type, value: str }, ctx, onComment, onChompKeep);
      }
    };
    exports.binary = binary;
  }
});

// ../../node_modules/yaml/dist/schema/yaml-1.1/pairs.js
var require_pairs = __commonJS({
  "../../node_modules/yaml/dist/schema/yaml-1.1/pairs.js"(exports) {
    "use strict";
    var identity = require_identity();
    var Pair = require_Pair();
    var Scalar = require_Scalar();
    var YAMLSeq = require_YAMLSeq();
    function resolvePairs(seq, onError) {
      if (identity.isSeq(seq)) {
        for (let i = 0; i < seq.items.length; ++i) {
          let item = seq.items[i];
          if (identity.isPair(item))
            continue;
          else if (identity.isMap(item)) {
            if (item.items.length > 1)
              onError("Each pair must have its own sequence indicator");
            const pair = item.items[0] || new Pair.Pair(new Scalar.Scalar(null));
            if (item.commentBefore)
              pair.key.commentBefore = pair.key.commentBefore ? `${item.commentBefore}
${pair.key.commentBefore}` : item.commentBefore;
            if (item.comment) {
              const cn = pair.value ?? pair.key;
              cn.comment = cn.comment ? `${item.comment}
${cn.comment}` : item.comment;
            }
            item = pair;
          }
          seq.items[i] = identity.isPair(item) ? item : new Pair.Pair(item);
        }
      } else
        onError("Expected a sequence for this tag");
      return seq;
    }
    function createPairs(schema, iterable, ctx) {
      const { replacer } = ctx;
      const pairs2 = new YAMLSeq.YAMLSeq(schema);
      pairs2.tag = "tag:yaml.org,2002:pairs";
      let i = 0;
      if (iterable && Symbol.iterator in Object(iterable))
        for (let it of iterable) {
          if (typeof replacer === "function")
            it = replacer.call(iterable, String(i++), it);
          let key, value;
          if (Array.isArray(it)) {
            if (it.length === 2) {
              key = it[0];
              value = it[1];
            } else
              throw new TypeError(`Expected [key, value] tuple: ${it}`);
          } else if (it && it instanceof Object) {
            const keys = Object.keys(it);
            if (keys.length === 1) {
              key = keys[0];
              value = it[key];
            } else {
              throw new TypeError(`Expected tuple with one key, not ${keys.length} keys`);
            }
          } else {
            key = it;
          }
          pairs2.items.push(Pair.createPair(key, value, ctx));
        }
      return pairs2;
    }
    var pairs = {
      collection: "seq",
      default: false,
      tag: "tag:yaml.org,2002:pairs",
      resolve: resolvePairs,
      createNode: createPairs
    };
    exports.createPairs = createPairs;
    exports.pairs = pairs;
    exports.resolvePairs = resolvePairs;
  }
});

// ../../node_modules/yaml/dist/schema/yaml-1.1/omap.js
var require_omap = __commonJS({
  "../../node_modules/yaml/dist/schema/yaml-1.1/omap.js"(exports) {
    "use strict";
    var identity = require_identity();
    var toJS = require_toJS();
    var YAMLMap = require_YAMLMap();
    var YAMLSeq = require_YAMLSeq();
    var pairs = require_pairs();
    var YAMLOMap = class _YAMLOMap extends YAMLSeq.YAMLSeq {
      constructor() {
        super();
        this.add = YAMLMap.YAMLMap.prototype.add.bind(this);
        this.delete = YAMLMap.YAMLMap.prototype.delete.bind(this);
        this.get = YAMLMap.YAMLMap.prototype.get.bind(this);
        this.has = YAMLMap.YAMLMap.prototype.has.bind(this);
        this.set = YAMLMap.YAMLMap.prototype.set.bind(this);
        this.tag = _YAMLOMap.tag;
      }
      /**
       * If `ctx` is given, the return type is actually `Map<unknown, unknown>`,
       * but TypeScript won't allow widening the signature of a child method.
       */
      toJSON(_, ctx) {
        if (!ctx)
          return super.toJSON(_);
        const map = /* @__PURE__ */ new Map();
        if (ctx?.onCreate)
          ctx.onCreate(map);
        for (const pair of this.items) {
          let key, value;
          if (identity.isPair(pair)) {
            key = toJS.toJS(pair.key, "", ctx);
            value = toJS.toJS(pair.value, key, ctx);
          } else {
            key = toJS.toJS(pair, "", ctx);
          }
          if (map.has(key))
            throw new Error("Ordered maps must not include duplicate keys");
          map.set(key, value);
        }
        return map;
      }
      static from(schema, iterable, ctx) {
        const pairs$1 = pairs.createPairs(schema, iterable, ctx);
        const omap2 = new this();
        omap2.items = pairs$1.items;
        return omap2;
      }
    };
    YAMLOMap.tag = "tag:yaml.org,2002:omap";
    var omap = {
      collection: "seq",
      identify: (value) => value instanceof Map,
      nodeClass: YAMLOMap,
      default: false,
      tag: "tag:yaml.org,2002:omap",
      resolve(seq, onError) {
        const pairs$1 = pairs.resolvePairs(seq, onError);
        const seenKeys = [];
        for (const { key } of pairs$1.items) {
          if (identity.isScalar(key)) {
            if (seenKeys.includes(key.value)) {
              onError(`Ordered maps must not include duplicate keys: ${key.value}`);
            } else {
              seenKeys.push(key.value);
            }
          }
        }
        return Object.assign(new YAMLOMap(), pairs$1);
      },
      createNode: (schema, iterable, ctx) => YAMLOMap.from(schema, iterable, ctx)
    };
    exports.YAMLOMap = YAMLOMap;
    exports.omap = omap;
  }
});

// ../../node_modules/yaml/dist/schema/yaml-1.1/bool.js
var require_bool2 = __commonJS({
  "../../node_modules/yaml/dist/schema/yaml-1.1/bool.js"(exports) {
    "use strict";
    var Scalar = require_Scalar();
    function boolStringify({ value, source }, ctx) {
      const boolObj = value ? trueTag : falseTag;
      if (source && boolObj.test.test(source))
        return source;
      return value ? ctx.options.trueStr : ctx.options.falseStr;
    }
    var trueTag = {
      identify: (value) => value === true,
      default: true,
      tag: "tag:yaml.org,2002:bool",
      test: /^(?:Y|y|[Yy]es|YES|[Tt]rue|TRUE|[Oo]n|ON)$/,
      resolve: () => new Scalar.Scalar(true),
      stringify: boolStringify
    };
    var falseTag = {
      identify: (value) => value === false,
      default: true,
      tag: "tag:yaml.org,2002:bool",
      test: /^(?:N|n|[Nn]o|NO|[Ff]alse|FALSE|[Oo]ff|OFF)$/,
      resolve: () => new Scalar.Scalar(false),
      stringify: boolStringify
    };
    exports.falseTag = falseTag;
    exports.trueTag = trueTag;
  }
});

// ../../node_modules/yaml/dist/schema/yaml-1.1/float.js
var require_float2 = __commonJS({
  "../../node_modules/yaml/dist/schema/yaml-1.1/float.js"(exports) {
    "use strict";
    var Scalar = require_Scalar();
    var stringifyNumber = require_stringifyNumber();
    var floatNaN = {
      identify: (value) => typeof value === "number",
      default: true,
      tag: "tag:yaml.org,2002:float",
      test: /^(?:[-+]?\.(?:inf|Inf|INF)|\.nan|\.NaN|\.NAN)$/,
      resolve: (str) => str.slice(-3).toLowerCase() === "nan" ? NaN : str[0] === "-" ? Number.NEGATIVE_INFINITY : Number.POSITIVE_INFINITY,
      stringify: stringifyNumber.stringifyNumber
    };
    var floatExp = {
      identify: (value) => typeof value === "number",
      default: true,
      tag: "tag:yaml.org,2002:float",
      format: "EXP",
      test: /^[-+]?(?:[0-9][0-9_]*)?(?:\.[0-9_]*)?[eE][-+]?[0-9]+$/,
      resolve: (str) => parseFloat(str.replace(/_/g, "")),
      stringify(node) {
        const num = Number(node.value);
        return isFinite(num) ? num.toExponential() : stringifyNumber.stringifyNumber(node);
      }
    };
    var float = {
      identify: (value) => typeof value === "number",
      default: true,
      tag: "tag:yaml.org,2002:float",
      test: /^[-+]?(?:[0-9][0-9_]*)?\.[0-9_]*$/,
      resolve(str) {
        const node = new Scalar.Scalar(parseFloat(str.replace(/_/g, "")));
        const dot = str.indexOf(".");
        if (dot !== -1) {
          const f = str.substring(dot + 1).replace(/_/g, "");
          if (f[f.length - 1] === "0")
            node.minFractionDigits = f.length;
        }
        return node;
      },
      stringify: stringifyNumber.stringifyNumber
    };
    exports.float = float;
    exports.floatExp = floatExp;
    exports.floatNaN = floatNaN;
  }
});

// ../../node_modules/yaml/dist/schema/yaml-1.1/int.js
var require_int2 = __commonJS({
  "../../node_modules/yaml/dist/schema/yaml-1.1/int.js"(exports) {
    "use strict";
    var stringifyNumber = require_stringifyNumber();
    var intIdentify = (value) => typeof value === "bigint" || Number.isInteger(value);
    function intResolve(str, offset, radix, { intAsBigInt }) {
      const sign = str[0];
      if (sign === "-" || sign === "+")
        offset += 1;
      str = str.substring(offset).replace(/_/g, "");
      if (intAsBigInt) {
        switch (radix) {
          case 2:
            str = `0b${str}`;
            break;
          case 8:
            str = `0o${str}`;
            break;
          case 16:
            str = `0x${str}`;
            break;
        }
        const n2 = BigInt(str);
        return sign === "-" ? BigInt(-1) * n2 : n2;
      }
      const n = parseInt(str, radix);
      return sign === "-" ? -1 * n : n;
    }
    function intStringify(node, radix, prefix) {
      const { value } = node;
      if (intIdentify(value)) {
        const str = value.toString(radix);
        return value < 0 ? "-" + prefix + str.substr(1) : prefix + str;
      }
      return stringifyNumber.stringifyNumber(node);
    }
    var intBin = {
      identify: intIdentify,
      default: true,
      tag: "tag:yaml.org,2002:int",
      format: "BIN",
      test: /^[-+]?0b[0-1_]+$/,
      resolve: (str, _onError, opt) => intResolve(str, 2, 2, opt),
      stringify: (node) => intStringify(node, 2, "0b")
    };
    var intOct = {
      identify: intIdentify,
      default: true,
      tag: "tag:yaml.org,2002:int",
      format: "OCT",
      test: /^[-+]?0[0-7_]+$/,
      resolve: (str, _onError, opt) => intResolve(str, 1, 8, opt),
      stringify: (node) => intStringify(node, 8, "0")
    };
    var int = {
      identify: intIdentify,
      default: true,
      tag: "tag:yaml.org,2002:int",
      test: /^[-+]?[0-9][0-9_]*$/,
      resolve: (str, _onError, opt) => intResolve(str, 0, 10, opt),
      stringify: stringifyNumber.stringifyNumber
    };
    var intHex = {
      identify: intIdentify,
      default: true,
      tag: "tag:yaml.org,2002:int",
      format: "HEX",
      test: /^[-+]?0x[0-9a-fA-F_]+$/,
      resolve: (str, _onError, opt) => intResolve(str, 2, 16, opt),
      stringify: (node) => intStringify(node, 16, "0x")
    };
    exports.int = int;
    exports.intBin = intBin;
    exports.intHex = intHex;
    exports.intOct = intOct;
  }
});

// ../../node_modules/yaml/dist/schema/yaml-1.1/set.js
var require_set = __commonJS({
  "../../node_modules/yaml/dist/schema/yaml-1.1/set.js"(exports) {
    "use strict";
    var identity = require_identity();
    var Pair = require_Pair();
    var YAMLMap = require_YAMLMap();
    var YAMLSet = class _YAMLSet extends YAMLMap.YAMLMap {
      constructor(schema) {
        super(schema);
        this.tag = _YAMLSet.tag;
      }
      add(key) {
        let pair;
        if (identity.isPair(key))
          pair = key;
        else if (key && typeof key === "object" && "key" in key && "value" in key && key.value === null)
          pair = new Pair.Pair(key.key, null);
        else
          pair = new Pair.Pair(key, null);
        const prev = YAMLMap.findPair(this.items, pair.key);
        if (!prev)
          this.items.push(pair);
      }
      /**
       * If `keepPair` is `true`, returns the Pair matching `key`.
       * Otherwise, returns the value of that Pair's key.
       */
      get(key, keepPair) {
        const pair = YAMLMap.findPair(this.items, key);
        return !keepPair && identity.isPair(pair) ? identity.isScalar(pair.key) ? pair.key.value : pair.key : pair;
      }
      set(key, value) {
        if (typeof value !== "boolean")
          throw new Error(`Expected boolean value for set(key, value) in a YAML set, not ${typeof value}`);
        const prev = YAMLMap.findPair(this.items, key);
        if (prev && !value) {
          this.items.splice(this.items.indexOf(prev), 1);
        } else if (!prev && value) {
          this.items.push(new Pair.Pair(key));
        }
      }
      toJSON(_, ctx) {
        return super.toJSON(_, ctx, Set);
      }
      toString(ctx, onComment, onChompKeep) {
        if (!ctx)
          return JSON.stringify(this);
        if (this.hasAllNullValues(true))
          return super.toString(Object.assign({}, ctx, { allNullValues: true }), onComment, onChompKeep);
        else
          throw new Error("Set items must all have null values");
      }
      static from(schema, iterable, ctx) {
        const { replacer } = ctx;
        const set2 = new this(schema);
        if (iterable && Symbol.iterator in Object(iterable))
          for (let value of iterable) {
            if (typeof replacer === "function")
              value = replacer.call(iterable, value, value);
            set2.items.push(Pair.createPair(value, null, ctx));
          }
        return set2;
      }
    };
    YAMLSet.tag = "tag:yaml.org,2002:set";
    var set = {
      collection: "map",
      identify: (value) => value instanceof Set,
      nodeClass: YAMLSet,
      default: false,
      tag: "tag:yaml.org,2002:set",
      createNode: (schema, iterable, ctx) => YAMLSet.from(schema, iterable, ctx),
      resolve(map, onError) {
        if (identity.isMap(map)) {
          if (map.hasAllNullValues(true))
            return Object.assign(new YAMLSet(), map);
          else
            onError("Set items must all have null values");
        } else
          onError("Expected a mapping for this tag");
        return map;
      }
    };
    exports.YAMLSet = YAMLSet;
    exports.set = set;
  }
});

// ../../node_modules/yaml/dist/schema/yaml-1.1/timestamp.js
var require_timestamp = __commonJS({
  "../../node_modules/yaml/dist/schema/yaml-1.1/timestamp.js"(exports) {
    "use strict";
    var stringifyNumber = require_stringifyNumber();
    function parseSexagesimal(str, asBigInt) {
      const sign = str[0];
      const parts = sign === "-" || sign === "+" ? str.substring(1) : str;
      const num = (n) => asBigInt ? BigInt(n) : Number(n);
      const res = parts.replace(/_/g, "").split(":").reduce((res2, p) => res2 * num(60) + num(p), num(0));
      return sign === "-" ? num(-1) * res : res;
    }
    function stringifySexagesimal(node) {
      let { value } = node;
      let num = (n) => n;
      if (typeof value === "bigint")
        num = (n) => BigInt(n);
      else if (isNaN(value) || !isFinite(value))
        return stringifyNumber.stringifyNumber(node);
      let sign = "";
      if (value < 0) {
        sign = "-";
        value *= num(-1);
      }
      const _60 = num(60);
      const parts = [value % _60];
      if (value < 60) {
        parts.unshift(0);
      } else {
        value = (value - parts[0]) / _60;
        parts.unshift(value % _60);
        if (value >= 60) {
          value = (value - parts[0]) / _60;
          parts.unshift(value);
        }
      }
      return sign + parts.map((n) => String(n).padStart(2, "0")).join(":").replace(/000000\d*$/, "");
    }
    var intTime = {
      identify: (value) => typeof value === "bigint" || Number.isInteger(value),
      default: true,
      tag: "tag:yaml.org,2002:int",
      format: "TIME",
      test: /^[-+]?[0-9][0-9_]*(?::[0-5]?[0-9])+$/,
      resolve: (str, _onError, { intAsBigInt }) => parseSexagesimal(str, intAsBigInt),
      stringify: stringifySexagesimal
    };
    var floatTime = {
      identify: (value) => typeof value === "number",
      default: true,
      tag: "tag:yaml.org,2002:float",
      format: "TIME",
      test: /^[-+]?[0-9][0-9_]*(?::[0-5]?[0-9])+\.[0-9_]*$/,
      resolve: (str) => parseSexagesimal(str, false),
      stringify: stringifySexagesimal
    };
    var timestamp = {
      identify: (value) => value instanceof Date,
      default: true,
      tag: "tag:yaml.org,2002:timestamp",
      // If the time zone is omitted, the timestamp is assumed to be specified in UTC. The time part
      // may be omitted altogether, resulting in a date format. In such a case, the time part is
      // assumed to be 00:00:00Z (start of day, UTC).
      test: RegExp("^([0-9]{4})-([0-9]{1,2})-([0-9]{1,2})(?:(?:t|T|[ \\t]+)([0-9]{1,2}):([0-9]{1,2}):([0-9]{1,2}(\\.[0-9]+)?)(?:[ \\t]*(Z|[-+][012]?[0-9](?::[0-9]{2})?))?)?$"),
      resolve(str) {
        const match = str.match(timestamp.test);
        if (!match)
          throw new Error("!!timestamp expects a date, starting with yyyy-mm-dd");
        const [, year, month, day, hour, minute, second] = match.map(Number);
        const millisec = match[7] ? Number((match[7] + "00").substr(1, 3)) : 0;
        let date = Date.UTC(year, month - 1, day, hour || 0, minute || 0, second || 0, millisec);
        const tz = match[8];
        if (tz && tz !== "Z") {
          let d = parseSexagesimal(tz, false);
          if (Math.abs(d) < 30)
            d *= 60;
          date -= 6e4 * d;
        }
        return new Date(date);
      },
      stringify: ({ value }) => value?.toISOString().replace(/(T00:00:00)?\.000Z$/, "") ?? ""
    };
    exports.floatTime = floatTime;
    exports.intTime = intTime;
    exports.timestamp = timestamp;
  }
});

// ../../node_modules/yaml/dist/schema/yaml-1.1/schema.js
var require_schema3 = __commonJS({
  "../../node_modules/yaml/dist/schema/yaml-1.1/schema.js"(exports) {
    "use strict";
    var map = require_map();
    var _null = require_null();
    var seq = require_seq();
    var string = require_string();
    var binary = require_binary();
    var bool = require_bool2();
    var float = require_float2();
    var int = require_int2();
    var merge = require_merge();
    var omap = require_omap();
    var pairs = require_pairs();
    var set = require_set();
    var timestamp = require_timestamp();
    var schema = [
      map.map,
      seq.seq,
      string.string,
      _null.nullTag,
      bool.trueTag,
      bool.falseTag,
      int.intBin,
      int.intOct,
      int.int,
      int.intHex,
      float.floatNaN,
      float.floatExp,
      float.float,
      binary.binary,
      merge.merge,
      omap.omap,
      pairs.pairs,
      set.set,
      timestamp.intTime,
      timestamp.floatTime,
      timestamp.timestamp
    ];
    exports.schema = schema;
  }
});

// ../../node_modules/yaml/dist/schema/tags.js
var require_tags = __commonJS({
  "../../node_modules/yaml/dist/schema/tags.js"(exports) {
    "use strict";
    var map = require_map();
    var _null = require_null();
    var seq = require_seq();
    var string = require_string();
    var bool = require_bool();
    var float = require_float();
    var int = require_int();
    var schema = require_schema();
    var schema$1 = require_schema2();
    var binary = require_binary();
    var merge = require_merge();
    var omap = require_omap();
    var pairs = require_pairs();
    var schema$2 = require_schema3();
    var set = require_set();
    var timestamp = require_timestamp();
    var schemas = /* @__PURE__ */ new Map([
      ["core", schema.schema],
      ["failsafe", [map.map, seq.seq, string.string]],
      ["json", schema$1.schema],
      ["yaml11", schema$2.schema],
      ["yaml-1.1", schema$2.schema]
    ]);
    var tagsByName = {
      binary: binary.binary,
      bool: bool.boolTag,
      float: float.float,
      floatExp: float.floatExp,
      floatNaN: float.floatNaN,
      floatTime: timestamp.floatTime,
      int: int.int,
      intHex: int.intHex,
      intOct: int.intOct,
      intTime: timestamp.intTime,
      map: map.map,
      merge: merge.merge,
      null: _null.nullTag,
      omap: omap.omap,
      pairs: pairs.pairs,
      seq: seq.seq,
      set: set.set,
      timestamp: timestamp.timestamp
    };
    var coreKnownTags = {
      "tag:yaml.org,2002:binary": binary.binary,
      "tag:yaml.org,2002:merge": merge.merge,
      "tag:yaml.org,2002:omap": omap.omap,
      "tag:yaml.org,2002:pairs": pairs.pairs,
      "tag:yaml.org,2002:set": set.set,
      "tag:yaml.org,2002:timestamp": timestamp.timestamp
    };
    function getTags(customTags, schemaName, addMergeTag) {
      const schemaTags = schemas.get(schemaName);
      if (schemaTags && !customTags) {
        return addMergeTag && !schemaTags.includes(merge.merge) ? schemaTags.concat(merge.merge) : schemaTags.slice();
      }
      let tags = schemaTags;
      if (!tags) {
        if (Array.isArray(customTags))
          tags = [];
        else {
          const keys = Array.from(schemas.keys()).filter((key) => key !== "yaml11").map((key) => JSON.stringify(key)).join(", ");
          throw new Error(`Unknown schema "${schemaName}"; use one of ${keys} or define customTags array`);
        }
      }
      if (Array.isArray(customTags)) {
        for (const tag of customTags)
          tags = tags.concat(tag);
      } else if (typeof customTags === "function") {
        tags = customTags(tags.slice());
      }
      if (addMergeTag)
        tags = tags.concat(merge.merge);
      return tags.reduce((tags2, tag) => {
        const tagObj = typeof tag === "string" ? tagsByName[tag] : tag;
        if (!tagObj) {
          const tagName = JSON.stringify(tag);
          const keys = Object.keys(tagsByName).map((key) => JSON.stringify(key)).join(", ");
          throw new Error(`Unknown custom tag ${tagName}; use one of ${keys}`);
        }
        if (!tags2.includes(tagObj))
          tags2.push(tagObj);
        return tags2;
      }, []);
    }
    exports.coreKnownTags = coreKnownTags;
    exports.getTags = getTags;
  }
});

// ../../node_modules/yaml/dist/schema/Schema.js
var require_Schema = __commonJS({
  "../../node_modules/yaml/dist/schema/Schema.js"(exports) {
    "use strict";
    var identity = require_identity();
    var map = require_map();
    var seq = require_seq();
    var string = require_string();
    var tags = require_tags();
    var sortMapEntriesByKey = (a, b) => a.key < b.key ? -1 : a.key > b.key ? 1 : 0;
    var Schema = class _Schema {
      constructor({ compat, customTags, merge, resolveKnownTags, schema, sortMapEntries, toStringDefaults }) {
        this.compat = Array.isArray(compat) ? tags.getTags(compat, "compat") : compat ? tags.getTags(null, compat) : null;
        this.name = typeof schema === "string" && schema || "core";
        this.knownTags = resolveKnownTags ? tags.coreKnownTags : {};
        this.tags = tags.getTags(customTags, this.name, merge);
        this.toStringOptions = toStringDefaults ?? null;
        Object.defineProperty(this, identity.MAP, { value: map.map });
        Object.defineProperty(this, identity.SCALAR, { value: string.string });
        Object.defineProperty(this, identity.SEQ, { value: seq.seq });
        this.sortMapEntries = typeof sortMapEntries === "function" ? sortMapEntries : sortMapEntries === true ? sortMapEntriesByKey : null;
      }
      clone() {
        const copy = Object.create(_Schema.prototype, Object.getOwnPropertyDescriptors(this));
        copy.tags = this.tags.slice();
        return copy;
      }
    };
    exports.Schema = Schema;
  }
});

// ../../node_modules/yaml/dist/stringify/stringifyDocument.js
var require_stringifyDocument = __commonJS({
  "../../node_modules/yaml/dist/stringify/stringifyDocument.js"(exports) {
    "use strict";
    var identity = require_identity();
    var stringify = require_stringify();
    var stringifyComment = require_stringifyComment();
    function stringifyDocument(doc, options) {
      const lines = [];
      let hasDirectives = options.directives === true;
      if (options.directives !== false && doc.directives) {
        const dir = doc.directives.toString(doc);
        if (dir) {
          lines.push(dir);
          hasDirectives = true;
        } else if (doc.directives.docStart)
          hasDirectives = true;
      }
      if (hasDirectives)
        lines.push("---");
      const ctx = stringify.createStringifyContext(doc, options);
      const { commentString } = ctx.options;
      if (doc.commentBefore) {
        if (lines.length !== 1)
          lines.unshift("");
        const cs = commentString(doc.commentBefore);
        lines.unshift(stringifyComment.indentComment(cs, ""));
      }
      let chompKeep = false;
      let contentComment = null;
      if (doc.contents) {
        if (identity.isNode(doc.contents)) {
          if (doc.contents.spaceBefore && hasDirectives)
            lines.push("");
          if (doc.contents.commentBefore) {
            const cs = commentString(doc.contents.commentBefore);
            lines.push(stringifyComment.indentComment(cs, ""));
          }
          ctx.forceBlockIndent = !!doc.comment;
          contentComment = doc.contents.comment;
        }
        const onChompKeep = contentComment ? void 0 : () => chompKeep = true;
        let body = stringify.stringify(doc.contents, ctx, () => contentComment = null, onChompKeep);
        if (contentComment)
          body += stringifyComment.lineComment(body, "", commentString(contentComment));
        if ((body[0] === "|" || body[0] === ">") && lines[lines.length - 1] === "---") {
          lines[lines.length - 1] = `--- ${body}`;
        } else
          lines.push(body);
      } else {
        lines.push(stringify.stringify(doc.contents, ctx));
      }
      if (doc.directives?.docEnd) {
        if (doc.comment) {
          const cs = commentString(doc.comment);
          if (cs.includes("\n")) {
            lines.push("...");
            lines.push(stringifyComment.indentComment(cs, ""));
          } else {
            lines.push(`... ${cs}`);
          }
        } else {
          lines.push("...");
        }
      } else {
        let dc = doc.comment;
        if (dc && chompKeep)
          dc = dc.replace(/^\n+/, "");
        if (dc) {
          if ((!chompKeep || contentComment) && lines[lines.length - 1] !== "")
            lines.push("");
          lines.push(stringifyComment.indentComment(commentString(dc), ""));
        }
      }
      return lines.join("\n") + "\n";
    }
    exports.stringifyDocument = stringifyDocument;
  }
});

// ../../node_modules/yaml/dist/doc/Document.js
var require_Document = __commonJS({
  "../../node_modules/yaml/dist/doc/Document.js"(exports) {
    "use strict";
    var Alias = require_Alias();
    var Collection = require_Collection();
    var identity = require_identity();
    var Pair = require_Pair();
    var toJS = require_toJS();
    var Schema = require_Schema();
    var stringifyDocument = require_stringifyDocument();
    var anchors = require_anchors();
    var applyReviver = require_applyReviver();
    var createNode = require_createNode();
    var directives = require_directives();
    var Document = class _Document {
      constructor(value, replacer, options) {
        this.commentBefore = null;
        this.comment = null;
        this.errors = [];
        this.warnings = [];
        Object.defineProperty(this, identity.NODE_TYPE, { value: identity.DOC });
        let _replacer = null;
        if (typeof replacer === "function" || Array.isArray(replacer)) {
          _replacer = replacer;
        } else if (options === void 0 && replacer) {
          options = replacer;
          replacer = void 0;
        }
        const opt = Object.assign({
          intAsBigInt: false,
          keepSourceTokens: false,
          logLevel: "warn",
          prettyErrors: true,
          strict: true,
          stringKeys: false,
          uniqueKeys: true,
          version: "1.2"
        }, options);
        this.options = opt;
        let { version } = opt;
        if (options?._directives) {
          this.directives = options._directives.atDocument();
          if (this.directives.yaml.explicit)
            version = this.directives.yaml.version;
        } else
          this.directives = new directives.Directives({ version });
        this.setSchema(version, options);
        this.contents = value === void 0 ? null : this.createNode(value, _replacer, options);
      }
      /**
       * Create a deep copy of this Document and its contents.
       *
       * Custom Node values that inherit from `Object` still refer to their original instances.
       */
      clone() {
        const copy = Object.create(_Document.prototype, {
          [identity.NODE_TYPE]: { value: identity.DOC }
        });
        copy.commentBefore = this.commentBefore;
        copy.comment = this.comment;
        copy.errors = this.errors.slice();
        copy.warnings = this.warnings.slice();
        copy.options = Object.assign({}, this.options);
        if (this.directives)
          copy.directives = this.directives.clone();
        copy.schema = this.schema.clone();
        copy.contents = identity.isNode(this.contents) ? this.contents.clone(copy.schema) : this.contents;
        if (this.range)
          copy.range = this.range.slice();
        return copy;
      }
      /** Adds a value to the document. */
      add(value) {
        if (assertCollection(this.contents))
          this.contents.add(value);
      }
      /** Adds a value to the document. */
      addIn(path, value) {
        if (assertCollection(this.contents))
          this.contents.addIn(path, value);
      }
      /**
       * Create a new `Alias` node, ensuring that the target `node` has the required anchor.
       *
       * If `node` already has an anchor, `name` is ignored.
       * Otherwise, the `node.anchor` value will be set to `name`,
       * or if an anchor with that name is already present in the document,
       * `name` will be used as a prefix for a new unique anchor.
       * If `name` is undefined, the generated anchor will use 'a' as a prefix.
       */
      createAlias(node, name) {
        if (!node.anchor) {
          const prev = anchors.anchorNames(this);
          node.anchor = // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
          !name || prev.has(name) ? anchors.findNewAnchor(name || "a", prev) : name;
        }
        return new Alias.Alias(node.anchor);
      }
      createNode(value, replacer, options) {
        let _replacer = void 0;
        if (typeof replacer === "function") {
          value = replacer.call({ "": value }, "", value);
          _replacer = replacer;
        } else if (Array.isArray(replacer)) {
          const keyToStr = (v) => typeof v === "number" || v instanceof String || v instanceof Number;
          const asStr = replacer.filter(keyToStr).map(String);
          if (asStr.length > 0)
            replacer = replacer.concat(asStr);
          _replacer = replacer;
        } else if (options === void 0 && replacer) {
          options = replacer;
          replacer = void 0;
        }
        const { aliasDuplicateObjects, anchorPrefix, flow, keepUndefined, onTagObj, tag } = options ?? {};
        const { onAnchor, setAnchors, sourceObjects } = anchors.createNodeAnchors(
          this,
          // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
          anchorPrefix || "a"
        );
        const ctx = {
          aliasDuplicateObjects: aliasDuplicateObjects ?? true,
          keepUndefined: keepUndefined ?? false,
          onAnchor,
          onTagObj,
          replacer: _replacer,
          schema: this.schema,
          sourceObjects
        };
        const node = createNode.createNode(value, tag, ctx);
        if (flow && identity.isCollection(node))
          node.flow = true;
        setAnchors();
        return node;
      }
      /**
       * Convert a key and a value into a `Pair` using the current schema,
       * recursively wrapping all values as `Scalar` or `Collection` nodes.
       */
      createPair(key, value, options = {}) {
        const k = this.createNode(key, null, options);
        const v = this.createNode(value, null, options);
        return new Pair.Pair(k, v);
      }
      /**
       * Removes a value from the document.
       * @returns `true` if the item was found and removed.
       */
      delete(key) {
        return assertCollection(this.contents) ? this.contents.delete(key) : false;
      }
      /**
       * Removes a value from the document.
       * @returns `true` if the item was found and removed.
       */
      deleteIn(path) {
        if (Collection.isEmptyPath(path)) {
          if (this.contents == null)
            return false;
          this.contents = null;
          return true;
        }
        return assertCollection(this.contents) ? this.contents.deleteIn(path) : false;
      }
      /**
       * Returns item at `key`, or `undefined` if not found. By default unwraps
       * scalar values from their surrounding node; to disable set `keepScalar` to
       * `true` (collections are always returned intact).
       */
      get(key, keepScalar) {
        return identity.isCollection(this.contents) ? this.contents.get(key, keepScalar) : void 0;
      }
      /**
       * Returns item at `path`, or `undefined` if not found. By default unwraps
       * scalar values from their surrounding node; to disable set `keepScalar` to
       * `true` (collections are always returned intact).
       */
      getIn(path, keepScalar) {
        if (Collection.isEmptyPath(path))
          return !keepScalar && identity.isScalar(this.contents) ? this.contents.value : this.contents;
        return identity.isCollection(this.contents) ? this.contents.getIn(path, keepScalar) : void 0;
      }
      /**
       * Checks if the document includes a value with the key `key`.
       */
      has(key) {
        return identity.isCollection(this.contents) ? this.contents.has(key) : false;
      }
      /**
       * Checks if the document includes a value at `path`.
       */
      hasIn(path) {
        if (Collection.isEmptyPath(path))
          return this.contents !== void 0;
        return identity.isCollection(this.contents) ? this.contents.hasIn(path) : false;
      }
      /**
       * Sets a value in this document. For `!!set`, `value` needs to be a
       * boolean to add/remove the item from the set.
       */
      set(key, value) {
        if (this.contents == null) {
          this.contents = Collection.collectionFromPath(this.schema, [key], value);
        } else if (assertCollection(this.contents)) {
          this.contents.set(key, value);
        }
      }
      /**
       * Sets a value in this document. For `!!set`, `value` needs to be a
       * boolean to add/remove the item from the set.
       */
      setIn(path, value) {
        if (Collection.isEmptyPath(path)) {
          this.contents = value;
        } else if (this.contents == null) {
          this.contents = Collection.collectionFromPath(this.schema, Array.from(path), value);
        } else if (assertCollection(this.contents)) {
          this.contents.setIn(path, value);
        }
      }
      /**
       * Change the YAML version and schema used by the document.
       * A `null` version disables support for directives, explicit tags, anchors, and aliases.
       * It also requires the `schema` option to be given as a `Schema` instance value.
       *
       * Overrides all previously set schema options.
       */
      setSchema(version, options = {}) {
        if (typeof version === "number")
          version = String(version);
        let opt;
        switch (version) {
          case "1.1":
            if (this.directives)
              this.directives.yaml.version = "1.1";
            else
              this.directives = new directives.Directives({ version: "1.1" });
            opt = { resolveKnownTags: false, schema: "yaml-1.1" };
            break;
          case "1.2":
          case "next":
            if (this.directives)
              this.directives.yaml.version = version;
            else
              this.directives = new directives.Directives({ version });
            opt = { resolveKnownTags: true, schema: "core" };
            break;
          case null:
            if (this.directives)
              delete this.directives;
            opt = null;
            break;
          default: {
            const sv = JSON.stringify(version);
            throw new Error(`Expected '1.1', '1.2' or null as first argument, but found: ${sv}`);
          }
        }
        if (options.schema instanceof Object)
          this.schema = options.schema;
        else if (opt)
          this.schema = new Schema.Schema(Object.assign(opt, options));
        else
          throw new Error(`With a null YAML version, the { schema: Schema } option is required`);
      }
      // json & jsonArg are only used from toJSON()
      toJS({ json: json2, jsonArg, mapAsMap, maxAliasCount, onAnchor, reviver } = {}) {
        const ctx = {
          anchors: /* @__PURE__ */ new Map(),
          doc: this,
          keep: !json2,
          mapAsMap: mapAsMap === true,
          mapKeyWarned: false,
          maxAliasCount: typeof maxAliasCount === "number" ? maxAliasCount : 100
        };
        const res = toJS.toJS(this.contents, jsonArg ?? "", ctx);
        if (typeof onAnchor === "function")
          for (const { count, res: res2 } of ctx.anchors.values())
            onAnchor(res2, count);
        return typeof reviver === "function" ? applyReviver.applyReviver(reviver, { "": res }, "", res) : res;
      }
      /**
       * A JSON representation of the document `contents`.
       *
       * @param jsonArg Used by `JSON.stringify` to indicate the array index or
       *   property name.
       */
      toJSON(jsonArg, onAnchor) {
        return this.toJS({ json: true, jsonArg, mapAsMap: false, onAnchor });
      }
      /** A YAML representation of the document. */
      toString(options = {}) {
        if (this.errors.length > 0)
          throw new Error("Document with errors cannot be stringified");
        if ("indent" in options && (!Number.isInteger(options.indent) || Number(options.indent) <= 0)) {
          const s = JSON.stringify(options.indent);
          throw new Error(`"indent" option must be a positive integer, not ${s}`);
        }
        return stringifyDocument.stringifyDocument(this, options);
      }
    };
    function assertCollection(contents) {
      if (identity.isCollection(contents))
        return true;
      throw new Error("Expected a YAML collection as document contents");
    }
    exports.Document = Document;
  }
});

// ../../node_modules/yaml/dist/errors.js
var require_errors = __commonJS({
  "../../node_modules/yaml/dist/errors.js"(exports) {
    "use strict";
    var YAMLError = class extends Error {
      constructor(name, pos, code, message) {
        super();
        this.name = name;
        this.code = code;
        this.message = message;
        this.pos = pos;
      }
    };
    var YAMLParseError = class extends YAMLError {
      constructor(pos, code, message) {
        super("YAMLParseError", pos, code, message);
      }
    };
    var YAMLWarning = class extends YAMLError {
      constructor(pos, code, message) {
        super("YAMLWarning", pos, code, message);
      }
    };
    var prettifyError = (src, lc) => (error) => {
      if (error.pos[0] === -1)
        return;
      error.linePos = error.pos.map((pos) => lc.linePos(pos));
      const { line, col } = error.linePos[0];
      error.message += ` at line ${line}, column ${col}`;
      let ci = col - 1;
      let lineStr = src.substring(lc.lineStarts[line - 1], lc.lineStarts[line]).replace(/[\n\r]+$/, "");
      if (ci >= 60 && lineStr.length > 80) {
        const trimStart = Math.min(ci - 39, lineStr.length - 79);
        lineStr = "\u2026" + lineStr.substring(trimStart);
        ci -= trimStart - 1;
      }
      if (lineStr.length > 80)
        lineStr = lineStr.substring(0, 79) + "\u2026";
      if (line > 1 && /^ *$/.test(lineStr.substring(0, ci))) {
        let prev = src.substring(lc.lineStarts[line - 2], lc.lineStarts[line - 1]);
        if (prev.length > 80)
          prev = prev.substring(0, 79) + "\u2026\n";
        lineStr = prev + lineStr;
      }
      if (/[^ ]/.test(lineStr)) {
        let count = 1;
        const end = error.linePos[1];
        if (end?.line === line && end.col > col) {
          count = Math.max(1, Math.min(end.col - col, 80 - ci));
        }
        const pointer = " ".repeat(ci) + "^".repeat(count);
        error.message += `:

${lineStr}
${pointer}
`;
      }
    };
    exports.YAMLError = YAMLError;
    exports.YAMLParseError = YAMLParseError;
    exports.YAMLWarning = YAMLWarning;
    exports.prettifyError = prettifyError;
  }
});

// ../../node_modules/yaml/dist/compose/resolve-props.js
var require_resolve_props = __commonJS({
  "../../node_modules/yaml/dist/compose/resolve-props.js"(exports) {
    "use strict";
    function resolveProps(tokens, { flow, indicator, next, offset, onError, parentIndent, startOnNewline }) {
      let spaceBefore = false;
      let atNewline = startOnNewline;
      let hasSpace = startOnNewline;
      let comment = "";
      let commentSep = "";
      let hasNewline = false;
      let reqSpace = false;
      let tab = null;
      let anchor = null;
      let tag = null;
      let newlineAfterProp = null;
      let comma = null;
      let found = null;
      let start = null;
      for (const token of tokens) {
        if (reqSpace) {
          if (token.type !== "space" && token.type !== "newline" && token.type !== "comma")
            onError(token.offset, "MISSING_CHAR", "Tags and anchors must be separated from the next token by white space");
          reqSpace = false;
        }
        if (tab) {
          if (atNewline && token.type !== "comment" && token.type !== "newline") {
            onError(tab, "TAB_AS_INDENT", "Tabs are not allowed as indentation");
          }
          tab = null;
        }
        switch (token.type) {
          case "space":
            if (!flow && (indicator !== "doc-start" || next?.type !== "flow-collection") && token.source.includes("	")) {
              tab = token;
            }
            hasSpace = true;
            break;
          case "comment": {
            if (!hasSpace)
              onError(token, "MISSING_CHAR", "Comments must be separated from other tokens by white space characters");
            const cb = token.source.substring(1) || " ";
            if (!comment)
              comment = cb;
            else
              comment += commentSep + cb;
            commentSep = "";
            atNewline = false;
            break;
          }
          case "newline":
            if (atNewline) {
              if (comment)
                comment += token.source;
              else if (!found || indicator !== "seq-item-ind")
                spaceBefore = true;
            } else
              commentSep += token.source;
            atNewline = true;
            hasNewline = true;
            if (anchor || tag)
              newlineAfterProp = token;
            hasSpace = true;
            break;
          case "anchor":
            if (anchor)
              onError(token, "MULTIPLE_ANCHORS", "A node can have at most one anchor");
            if (token.source.endsWith(":"))
              onError(token.offset + token.source.length - 1, "BAD_ALIAS", "Anchor ending in : is ambiguous", true);
            anchor = token;
            start ?? (start = token.offset);
            atNewline = false;
            hasSpace = false;
            reqSpace = true;
            break;
          case "tag": {
            if (tag)
              onError(token, "MULTIPLE_TAGS", "A node can have at most one tag");
            tag = token;
            start ?? (start = token.offset);
            atNewline = false;
            hasSpace = false;
            reqSpace = true;
            break;
          }
          case indicator:
            if (anchor || tag)
              onError(token, "BAD_PROP_ORDER", `Anchors and tags must be after the ${token.source} indicator`);
            if (found)
              onError(token, "UNEXPECTED_TOKEN", `Unexpected ${token.source} in ${flow ?? "collection"}`);
            found = token;
            atNewline = indicator === "seq-item-ind" || indicator === "explicit-key-ind";
            hasSpace = false;
            break;
          case "comma":
            if (flow) {
              if (comma)
                onError(token, "UNEXPECTED_TOKEN", `Unexpected , in ${flow}`);
              comma = token;
              atNewline = false;
              hasSpace = false;
              break;
            }
          // else fallthrough
          default:
            onError(token, "UNEXPECTED_TOKEN", `Unexpected ${token.type} token`);
            atNewline = false;
            hasSpace = false;
        }
      }
      const last = tokens[tokens.length - 1];
      const end = last ? last.offset + last.source.length : offset;
      if (reqSpace && next && next.type !== "space" && next.type !== "newline" && next.type !== "comma" && (next.type !== "scalar" || next.source !== "")) {
        onError(next.offset, "MISSING_CHAR", "Tags and anchors must be separated from the next token by white space");
      }
      if (tab && (atNewline && tab.indent <= parentIndent || next?.type === "block-map" || next?.type === "block-seq"))
        onError(tab, "TAB_AS_INDENT", "Tabs are not allowed as indentation");
      return {
        comma,
        found,
        spaceBefore,
        comment,
        hasNewline,
        anchor,
        tag,
        newlineAfterProp,
        end,
        start: start ?? end
      };
    }
    exports.resolveProps = resolveProps;
  }
});

// ../../node_modules/yaml/dist/compose/util-contains-newline.js
var require_util_contains_newline = __commonJS({
  "../../node_modules/yaml/dist/compose/util-contains-newline.js"(exports) {
    "use strict";
    function containsNewline(key) {
      if (!key)
        return null;
      switch (key.type) {
        case "alias":
        case "scalar":
        case "double-quoted-scalar":
        case "single-quoted-scalar":
          if (key.source.includes("\n"))
            return true;
          if (key.end) {
            for (const st of key.end)
              if (st.type === "newline")
                return true;
          }
          return false;
        case "flow-collection":
          for (const it of key.items) {
            for (const st of it.start)
              if (st.type === "newline")
                return true;
            if (it.sep) {
              for (const st of it.sep)
                if (st.type === "newline")
                  return true;
            }
            if (containsNewline(it.key) || containsNewline(it.value))
              return true;
          }
          return false;
        default:
          return true;
      }
    }
    exports.containsNewline = containsNewline;
  }
});

// ../../node_modules/yaml/dist/compose/util-flow-indent-check.js
var require_util_flow_indent_check = __commonJS({
  "../../node_modules/yaml/dist/compose/util-flow-indent-check.js"(exports) {
    "use strict";
    var utilContainsNewline = require_util_contains_newline();
    function flowIndentCheck(indent, fc, onError) {
      if (fc?.type === "flow-collection") {
        const end = fc.end[0];
        if (end.indent === indent && (end.source === "]" || end.source === "}") && utilContainsNewline.containsNewline(fc)) {
          const msg = "Flow end indicator should be more indented than parent";
          onError(end, "BAD_INDENT", msg, true);
        }
      }
    }
    exports.flowIndentCheck = flowIndentCheck;
  }
});

// ../../node_modules/yaml/dist/compose/util-map-includes.js
var require_util_map_includes = __commonJS({
  "../../node_modules/yaml/dist/compose/util-map-includes.js"(exports) {
    "use strict";
    var identity = require_identity();
    function mapIncludes(ctx, items, search) {
      const { uniqueKeys } = ctx.options;
      if (uniqueKeys === false)
        return false;
      const isEqual = typeof uniqueKeys === "function" ? uniqueKeys : (a, b) => a === b || identity.isScalar(a) && identity.isScalar(b) && a.value === b.value;
      return items.some((pair) => isEqual(pair.key, search));
    }
    exports.mapIncludes = mapIncludes;
  }
});

// ../../node_modules/yaml/dist/compose/resolve-block-map.js
var require_resolve_block_map = __commonJS({
  "../../node_modules/yaml/dist/compose/resolve-block-map.js"(exports) {
    "use strict";
    var Pair = require_Pair();
    var YAMLMap = require_YAMLMap();
    var resolveProps = require_resolve_props();
    var utilContainsNewline = require_util_contains_newline();
    var utilFlowIndentCheck = require_util_flow_indent_check();
    var utilMapIncludes = require_util_map_includes();
    var startColMsg = "All mapping items must start at the same column";
    function resolveBlockMap({ composeNode, composeEmptyNode }, ctx, bm, onError, tag) {
      const NodeClass = tag?.nodeClass ?? YAMLMap.YAMLMap;
      const map = new NodeClass(ctx.schema);
      if (ctx.atRoot)
        ctx.atRoot = false;
      let offset = bm.offset;
      let commentEnd = null;
      for (const collItem of bm.items) {
        const { start, key, sep, value } = collItem;
        const keyProps = resolveProps.resolveProps(start, {
          indicator: "explicit-key-ind",
          next: key ?? sep?.[0],
          offset,
          onError,
          parentIndent: bm.indent,
          startOnNewline: true
        });
        const implicitKey = !keyProps.found;
        if (implicitKey) {
          if (key) {
            if (key.type === "block-seq")
              onError(offset, "BLOCK_AS_IMPLICIT_KEY", "A block sequence may not be used as an implicit map key");
            else if ("indent" in key && key.indent !== bm.indent)
              onError(offset, "BAD_INDENT", startColMsg);
          }
          if (!keyProps.anchor && !keyProps.tag && !sep) {
            commentEnd = keyProps.end;
            if (keyProps.comment) {
              if (map.comment)
                map.comment += "\n" + keyProps.comment;
              else
                map.comment = keyProps.comment;
            }
            continue;
          }
          if (keyProps.newlineAfterProp || utilContainsNewline.containsNewline(key)) {
            onError(key ?? start[start.length - 1], "MULTILINE_IMPLICIT_KEY", "Implicit keys need to be on a single line");
          }
        } else if (keyProps.found?.indent !== bm.indent) {
          onError(offset, "BAD_INDENT", startColMsg);
        }
        ctx.atKey = true;
        const keyStart = keyProps.end;
        const keyNode = key ? composeNode(ctx, key, keyProps, onError) : composeEmptyNode(ctx, keyStart, start, null, keyProps, onError);
        if (ctx.schema.compat)
          utilFlowIndentCheck.flowIndentCheck(bm.indent, key, onError);
        ctx.atKey = false;
        if (utilMapIncludes.mapIncludes(ctx, map.items, keyNode))
          onError(keyStart, "DUPLICATE_KEY", "Map keys must be unique");
        const valueProps = resolveProps.resolveProps(sep ?? [], {
          indicator: "map-value-ind",
          next: value,
          offset: keyNode.range[2],
          onError,
          parentIndent: bm.indent,
          startOnNewline: !key || key.type === "block-scalar"
        });
        offset = valueProps.end;
        if (valueProps.found) {
          if (implicitKey) {
            if (value?.type === "block-map" && !valueProps.hasNewline)
              onError(offset, "BLOCK_AS_IMPLICIT_KEY", "Nested mappings are not allowed in compact mappings");
            if (ctx.options.strict && keyProps.start < valueProps.found.offset - 1024)
              onError(keyNode.range, "KEY_OVER_1024_CHARS", "The : indicator must be at most 1024 chars after the start of an implicit block mapping key");
          }
          const valueNode = value ? composeNode(ctx, value, valueProps, onError) : composeEmptyNode(ctx, offset, sep, null, valueProps, onError);
          if (ctx.schema.compat)
            utilFlowIndentCheck.flowIndentCheck(bm.indent, value, onError);
          offset = valueNode.range[2];
          const pair = new Pair.Pair(keyNode, valueNode);
          if (ctx.options.keepSourceTokens)
            pair.srcToken = collItem;
          map.items.push(pair);
        } else {
          if (implicitKey)
            onError(keyNode.range, "MISSING_CHAR", "Implicit map keys need to be followed by map values");
          if (valueProps.comment) {
            if (keyNode.comment)
              keyNode.comment += "\n" + valueProps.comment;
            else
              keyNode.comment = valueProps.comment;
          }
          const pair = new Pair.Pair(keyNode);
          if (ctx.options.keepSourceTokens)
            pair.srcToken = collItem;
          map.items.push(pair);
        }
      }
      if (commentEnd && commentEnd < offset)
        onError(commentEnd, "IMPOSSIBLE", "Map comment with trailing content");
      map.range = [bm.offset, offset, commentEnd ?? offset];
      return map;
    }
    exports.resolveBlockMap = resolveBlockMap;
  }
});

// ../../node_modules/yaml/dist/compose/resolve-block-seq.js
var require_resolve_block_seq = __commonJS({
  "../../node_modules/yaml/dist/compose/resolve-block-seq.js"(exports) {
    "use strict";
    var YAMLSeq = require_YAMLSeq();
    var resolveProps = require_resolve_props();
    var utilFlowIndentCheck = require_util_flow_indent_check();
    function resolveBlockSeq({ composeNode, composeEmptyNode }, ctx, bs, onError, tag) {
      const NodeClass = tag?.nodeClass ?? YAMLSeq.YAMLSeq;
      const seq = new NodeClass(ctx.schema);
      if (ctx.atRoot)
        ctx.atRoot = false;
      if (ctx.atKey)
        ctx.atKey = false;
      let offset = bs.offset;
      let commentEnd = null;
      for (const { start, value } of bs.items) {
        const props = resolveProps.resolveProps(start, {
          indicator: "seq-item-ind",
          next: value,
          offset,
          onError,
          parentIndent: bs.indent,
          startOnNewline: true
        });
        if (!props.found) {
          if (props.anchor || props.tag || value) {
            if (value?.type === "block-seq")
              onError(props.end, "BAD_INDENT", "All sequence items must start at the same column");
            else
              onError(offset, "MISSING_CHAR", "Sequence item without - indicator");
          } else {
            commentEnd = props.end;
            if (props.comment)
              seq.comment = props.comment;
            continue;
          }
        }
        const node = value ? composeNode(ctx, value, props, onError) : composeEmptyNode(ctx, props.end, start, null, props, onError);
        if (ctx.schema.compat)
          utilFlowIndentCheck.flowIndentCheck(bs.indent, value, onError);
        offset = node.range[2];
        seq.items.push(node);
      }
      seq.range = [bs.offset, offset, commentEnd ?? offset];
      return seq;
    }
    exports.resolveBlockSeq = resolveBlockSeq;
  }
});

// ../../node_modules/yaml/dist/compose/resolve-end.js
var require_resolve_end = __commonJS({
  "../../node_modules/yaml/dist/compose/resolve-end.js"(exports) {
    "use strict";
    function resolveEnd(end, offset, reqSpace, onError) {
      let comment = "";
      if (end) {
        let hasSpace = false;
        let sep = "";
        for (const token of end) {
          const { source, type } = token;
          switch (type) {
            case "space":
              hasSpace = true;
              break;
            case "comment": {
              if (reqSpace && !hasSpace)
                onError(token, "MISSING_CHAR", "Comments must be separated from other tokens by white space characters");
              const cb = source.substring(1) || " ";
              if (!comment)
                comment = cb;
              else
                comment += sep + cb;
              sep = "";
              break;
            }
            case "newline":
              if (comment)
                sep += source;
              hasSpace = true;
              break;
            default:
              onError(token, "UNEXPECTED_TOKEN", `Unexpected ${type} at node end`);
          }
          offset += source.length;
        }
      }
      return { comment, offset };
    }
    exports.resolveEnd = resolveEnd;
  }
});

// ../../node_modules/yaml/dist/compose/resolve-flow-collection.js
var require_resolve_flow_collection = __commonJS({
  "../../node_modules/yaml/dist/compose/resolve-flow-collection.js"(exports) {
    "use strict";
    var identity = require_identity();
    var Pair = require_Pair();
    var YAMLMap = require_YAMLMap();
    var YAMLSeq = require_YAMLSeq();
    var resolveEnd = require_resolve_end();
    var resolveProps = require_resolve_props();
    var utilContainsNewline = require_util_contains_newline();
    var utilMapIncludes = require_util_map_includes();
    var blockMsg = "Block collections are not allowed within flow collections";
    var isBlock = (token) => token && (token.type === "block-map" || token.type === "block-seq");
    function resolveFlowCollection({ composeNode, composeEmptyNode }, ctx, fc, onError, tag) {
      const isMap = fc.start.source === "{";
      const fcName = isMap ? "flow map" : "flow sequence";
      const NodeClass = tag?.nodeClass ?? (isMap ? YAMLMap.YAMLMap : YAMLSeq.YAMLSeq);
      const coll = new NodeClass(ctx.schema);
      coll.flow = true;
      const atRoot = ctx.atRoot;
      if (atRoot)
        ctx.atRoot = false;
      if (ctx.atKey)
        ctx.atKey = false;
      let offset = fc.offset + fc.start.source.length;
      for (let i = 0; i < fc.items.length; ++i) {
        const collItem = fc.items[i];
        const { start, key, sep, value } = collItem;
        const props = resolveProps.resolveProps(start, {
          flow: fcName,
          indicator: "explicit-key-ind",
          next: key ?? sep?.[0],
          offset,
          onError,
          parentIndent: fc.indent,
          startOnNewline: false
        });
        if (!props.found) {
          if (!props.anchor && !props.tag && !sep && !value) {
            if (i === 0 && props.comma)
              onError(props.comma, "UNEXPECTED_TOKEN", `Unexpected , in ${fcName}`);
            else if (i < fc.items.length - 1)
              onError(props.start, "UNEXPECTED_TOKEN", `Unexpected empty item in ${fcName}`);
            if (props.comment) {
              if (coll.comment)
                coll.comment += "\n" + props.comment;
              else
                coll.comment = props.comment;
            }
            offset = props.end;
            continue;
          }
          if (!isMap && ctx.options.strict && utilContainsNewline.containsNewline(key))
            onError(
              key,
              // checked by containsNewline()
              "MULTILINE_IMPLICIT_KEY",
              "Implicit keys of flow sequence pairs need to be on a single line"
            );
        }
        if (i === 0) {
          if (props.comma)
            onError(props.comma, "UNEXPECTED_TOKEN", `Unexpected , in ${fcName}`);
        } else {
          if (!props.comma)
            onError(props.start, "MISSING_CHAR", `Missing , between ${fcName} items`);
          if (props.comment) {
            let prevItemComment = "";
            loop: for (const st of start) {
              switch (st.type) {
                case "comma":
                case "space":
                  break;
                case "comment":
                  prevItemComment = st.source.substring(1);
                  break loop;
                default:
                  break loop;
              }
            }
            if (prevItemComment) {
              let prev = coll.items[coll.items.length - 1];
              if (identity.isPair(prev))
                prev = prev.value ?? prev.key;
              if (prev.comment)
                prev.comment += "\n" + prevItemComment;
              else
                prev.comment = prevItemComment;
              props.comment = props.comment.substring(prevItemComment.length + 1);
            }
          }
        }
        if (!isMap && !sep && !props.found) {
          const valueNode = value ? composeNode(ctx, value, props, onError) : composeEmptyNode(ctx, props.end, sep, null, props, onError);
          coll.items.push(valueNode);
          offset = valueNode.range[2];
          if (isBlock(value))
            onError(valueNode.range, "BLOCK_IN_FLOW", blockMsg);
        } else {
          ctx.atKey = true;
          const keyStart = props.end;
          const keyNode = key ? composeNode(ctx, key, props, onError) : composeEmptyNode(ctx, keyStart, start, null, props, onError);
          if (isBlock(key))
            onError(keyNode.range, "BLOCK_IN_FLOW", blockMsg);
          ctx.atKey = false;
          const valueProps = resolveProps.resolveProps(sep ?? [], {
            flow: fcName,
            indicator: "map-value-ind",
            next: value,
            offset: keyNode.range[2],
            onError,
            parentIndent: fc.indent,
            startOnNewline: false
          });
          if (valueProps.found) {
            if (!isMap && !props.found && ctx.options.strict) {
              if (sep)
                for (const st of sep) {
                  if (st === valueProps.found)
                    break;
                  if (st.type === "newline") {
                    onError(st, "MULTILINE_IMPLICIT_KEY", "Implicit keys of flow sequence pairs need to be on a single line");
                    break;
                  }
                }
              if (props.start < valueProps.found.offset - 1024)
                onError(valueProps.found, "KEY_OVER_1024_CHARS", "The : indicator must be at most 1024 chars after the start of an implicit flow sequence key");
            }
          } else if (value) {
            if ("source" in value && value.source?.[0] === ":")
              onError(value, "MISSING_CHAR", `Missing space after : in ${fcName}`);
            else
              onError(valueProps.start, "MISSING_CHAR", `Missing , or : between ${fcName} items`);
          }
          const valueNode = value ? composeNode(ctx, value, valueProps, onError) : valueProps.found ? composeEmptyNode(ctx, valueProps.end, sep, null, valueProps, onError) : null;
          if (valueNode) {
            if (isBlock(value))
              onError(valueNode.range, "BLOCK_IN_FLOW", blockMsg);
          } else if (valueProps.comment) {
            if (keyNode.comment)
              keyNode.comment += "\n" + valueProps.comment;
            else
              keyNode.comment = valueProps.comment;
          }
          const pair = new Pair.Pair(keyNode, valueNode);
          if (ctx.options.keepSourceTokens)
            pair.srcToken = collItem;
          if (isMap) {
            const map = coll;
            if (utilMapIncludes.mapIncludes(ctx, map.items, keyNode))
              onError(keyStart, "DUPLICATE_KEY", "Map keys must be unique");
            map.items.push(pair);
          } else {
            const map = new YAMLMap.YAMLMap(ctx.schema);
            map.flow = true;
            map.items.push(pair);
            const endRange = (valueNode ?? keyNode).range;
            map.range = [keyNode.range[0], endRange[1], endRange[2]];
            coll.items.push(map);
          }
          offset = valueNode ? valueNode.range[2] : valueProps.end;
        }
      }
      const expectedEnd = isMap ? "}" : "]";
      const [ce, ...ee] = fc.end;
      let cePos = offset;
      if (ce?.source === expectedEnd)
        cePos = ce.offset + ce.source.length;
      else {
        const name = fcName[0].toUpperCase() + fcName.substring(1);
        const msg = atRoot ? `${name} must end with a ${expectedEnd}` : `${name} in block collection must be sufficiently indented and end with a ${expectedEnd}`;
        onError(offset, atRoot ? "MISSING_CHAR" : "BAD_INDENT", msg);
        if (ce && ce.source.length !== 1)
          ee.unshift(ce);
      }
      if (ee.length > 0) {
        const end = resolveEnd.resolveEnd(ee, cePos, ctx.options.strict, onError);
        if (end.comment) {
          if (coll.comment)
            coll.comment += "\n" + end.comment;
          else
            coll.comment = end.comment;
        }
        coll.range = [fc.offset, cePos, end.offset];
      } else {
        coll.range = [fc.offset, cePos, cePos];
      }
      return coll;
    }
    exports.resolveFlowCollection = resolveFlowCollection;
  }
});

// ../../node_modules/yaml/dist/compose/compose-collection.js
var require_compose_collection = __commonJS({
  "../../node_modules/yaml/dist/compose/compose-collection.js"(exports) {
    "use strict";
    var identity = require_identity();
    var Scalar = require_Scalar();
    var YAMLMap = require_YAMLMap();
    var YAMLSeq = require_YAMLSeq();
    var resolveBlockMap = require_resolve_block_map();
    var resolveBlockSeq = require_resolve_block_seq();
    var resolveFlowCollection = require_resolve_flow_collection();
    function resolveCollection(CN, ctx, token, onError, tagName, tag) {
      const coll = token.type === "block-map" ? resolveBlockMap.resolveBlockMap(CN, ctx, token, onError, tag) : token.type === "block-seq" ? resolveBlockSeq.resolveBlockSeq(CN, ctx, token, onError, tag) : resolveFlowCollection.resolveFlowCollection(CN, ctx, token, onError, tag);
      const Coll = coll.constructor;
      if (tagName === "!" || tagName === Coll.tagName) {
        coll.tag = Coll.tagName;
        return coll;
      }
      if (tagName)
        coll.tag = tagName;
      return coll;
    }
    function composeCollection(CN, ctx, token, props, onError) {
      const tagToken = props.tag;
      const tagName = !tagToken ? null : ctx.directives.tagName(tagToken.source, (msg) => onError(tagToken, "TAG_RESOLVE_FAILED", msg));
      if (token.type === "block-seq") {
        const { anchor, newlineAfterProp: nl } = props;
        const lastProp = anchor && tagToken ? anchor.offset > tagToken.offset ? anchor : tagToken : anchor ?? tagToken;
        if (lastProp && (!nl || nl.offset < lastProp.offset)) {
          const message = "Missing newline after block sequence props";
          onError(lastProp, "MISSING_CHAR", message);
        }
      }
      const expType = token.type === "block-map" ? "map" : token.type === "block-seq" ? "seq" : token.start.source === "{" ? "map" : "seq";
      if (!tagToken || !tagName || tagName === "!" || tagName === YAMLMap.YAMLMap.tagName && expType === "map" || tagName === YAMLSeq.YAMLSeq.tagName && expType === "seq") {
        return resolveCollection(CN, ctx, token, onError, tagName);
      }
      let tag = ctx.schema.tags.find((t) => t.tag === tagName && t.collection === expType);
      if (!tag) {
        const kt = ctx.schema.knownTags[tagName];
        if (kt?.collection === expType) {
          ctx.schema.tags.push(Object.assign({}, kt, { default: false }));
          tag = kt;
        } else {
          if (kt) {
            onError(tagToken, "BAD_COLLECTION_TYPE", `${kt.tag} used for ${expType} collection, but expects ${kt.collection ?? "scalar"}`, true);
          } else {
            onError(tagToken, "TAG_RESOLVE_FAILED", `Unresolved tag: ${tagName}`, true);
          }
          return resolveCollection(CN, ctx, token, onError, tagName);
        }
      }
      const coll = resolveCollection(CN, ctx, token, onError, tagName, tag);
      const res = tag.resolve?.(coll, (msg) => onError(tagToken, "TAG_RESOLVE_FAILED", msg), ctx.options) ?? coll;
      const node = identity.isNode(res) ? res : new Scalar.Scalar(res);
      node.range = coll.range;
      node.tag = tagName;
      if (tag?.format)
        node.format = tag.format;
      return node;
    }
    exports.composeCollection = composeCollection;
  }
});

// ../../node_modules/yaml/dist/compose/resolve-block-scalar.js
var require_resolve_block_scalar = __commonJS({
  "../../node_modules/yaml/dist/compose/resolve-block-scalar.js"(exports) {
    "use strict";
    var Scalar = require_Scalar();
    function resolveBlockScalar(ctx, scalar, onError) {
      const start = scalar.offset;
      const header = parseBlockScalarHeader(scalar, ctx.options.strict, onError);
      if (!header)
        return { value: "", type: null, comment: "", range: [start, start, start] };
      const type = header.mode === ">" ? Scalar.Scalar.BLOCK_FOLDED : Scalar.Scalar.BLOCK_LITERAL;
      const lines = scalar.source ? splitLines(scalar.source) : [];
      let chompStart = lines.length;
      for (let i = lines.length - 1; i >= 0; --i) {
        const content = lines[i][1];
        if (content === "" || content === "\r")
          chompStart = i;
        else
          break;
      }
      if (chompStart === 0) {
        const value2 = header.chomp === "+" && lines.length > 0 ? "\n".repeat(Math.max(1, lines.length - 1)) : "";
        let end2 = start + header.length;
        if (scalar.source)
          end2 += scalar.source.length;
        return { value: value2, type, comment: header.comment, range: [start, end2, end2] };
      }
      let trimIndent = scalar.indent + header.indent;
      let offset = scalar.offset + header.length;
      let contentStart = 0;
      for (let i = 0; i < chompStart; ++i) {
        const [indent, content] = lines[i];
        if (content === "" || content === "\r") {
          if (header.indent === 0 && indent.length > trimIndent)
            trimIndent = indent.length;
        } else {
          if (indent.length < trimIndent) {
            const message = "Block scalars with more-indented leading empty lines must use an explicit indentation indicator";
            onError(offset + indent.length, "MISSING_CHAR", message);
          }
          if (header.indent === 0)
            trimIndent = indent.length;
          contentStart = i;
          if (trimIndent === 0 && !ctx.atRoot) {
            const message = "Block scalar values in collections must be indented";
            onError(offset, "BAD_INDENT", message);
          }
          break;
        }
        offset += indent.length + content.length + 1;
      }
      for (let i = lines.length - 1; i >= chompStart; --i) {
        if (lines[i][0].length > trimIndent)
          chompStart = i + 1;
      }
      let value = "";
      let sep = "";
      let prevMoreIndented = false;
      for (let i = 0; i < contentStart; ++i)
        value += lines[i][0].slice(trimIndent) + "\n";
      for (let i = contentStart; i < chompStart; ++i) {
        let [indent, content] = lines[i];
        offset += indent.length + content.length + 1;
        const crlf = content[content.length - 1] === "\r";
        if (crlf)
          content = content.slice(0, -1);
        if (content && indent.length < trimIndent) {
          const src = header.indent ? "explicit indentation indicator" : "first line";
          const message = `Block scalar lines must not be less indented than their ${src}`;
          onError(offset - content.length - (crlf ? 2 : 1), "BAD_INDENT", message);
          indent = "";
        }
        if (type === Scalar.Scalar.BLOCK_LITERAL) {
          value += sep + indent.slice(trimIndent) + content;
          sep = "\n";
        } else if (indent.length > trimIndent || content[0] === "	") {
          if (sep === " ")
            sep = "\n";
          else if (!prevMoreIndented && sep === "\n")
            sep = "\n\n";
          value += sep + indent.slice(trimIndent) + content;
          sep = "\n";
          prevMoreIndented = true;
        } else if (content === "") {
          if (sep === "\n")
            value += "\n";
          else
            sep = "\n";
        } else {
          value += sep + content;
          sep = " ";
          prevMoreIndented = false;
        }
      }
      switch (header.chomp) {
        case "-":
          break;
        case "+":
          for (let i = chompStart; i < lines.length; ++i)
            value += "\n" + lines[i][0].slice(trimIndent);
          if (value[value.length - 1] !== "\n")
            value += "\n";
          break;
        default:
          value += "\n";
      }
      const end = start + header.length + scalar.source.length;
      return { value, type, comment: header.comment, range: [start, end, end] };
    }
    function parseBlockScalarHeader({ offset, props }, strict, onError) {
      if (props[0].type !== "block-scalar-header") {
        onError(props[0], "IMPOSSIBLE", "Block scalar header not found");
        return null;
      }
      const { source } = props[0];
      const mode = source[0];
      let indent = 0;
      let chomp = "";
      let error = -1;
      for (let i = 1; i < source.length; ++i) {
        const ch = source[i];
        if (!chomp && (ch === "-" || ch === "+"))
          chomp = ch;
        else {
          const n = Number(ch);
          if (!indent && n)
            indent = n;
          else if (error === -1)
            error = offset + i;
        }
      }
      if (error !== -1)
        onError(error, "UNEXPECTED_TOKEN", `Block scalar header includes extra characters: ${source}`);
      let hasSpace = false;
      let comment = "";
      let length = source.length;
      for (let i = 1; i < props.length; ++i) {
        const token = props[i];
        switch (token.type) {
          case "space":
            hasSpace = true;
          // fallthrough
          case "newline":
            length += token.source.length;
            break;
          case "comment":
            if (strict && !hasSpace) {
              const message = "Comments must be separated from other tokens by white space characters";
              onError(token, "MISSING_CHAR", message);
            }
            length += token.source.length;
            comment = token.source.substring(1);
            break;
          case "error":
            onError(token, "UNEXPECTED_TOKEN", token.message);
            length += token.source.length;
            break;
          /* istanbul ignore next should not happen */
          default: {
            const message = `Unexpected token in block scalar header: ${token.type}`;
            onError(token, "UNEXPECTED_TOKEN", message);
            const ts = token.source;
            if (ts && typeof ts === "string")
              length += ts.length;
          }
        }
      }
      return { mode, indent, chomp, comment, length };
    }
    function splitLines(source) {
      const split = source.split(/\n( *)/);
      const first = split[0];
      const m = first.match(/^( *)/);
      const line0 = m?.[1] ? [m[1], first.slice(m[1].length)] : ["", first];
      const lines = [line0];
      for (let i = 1; i < split.length; i += 2)
        lines.push([split[i], split[i + 1]]);
      return lines;
    }
    exports.resolveBlockScalar = resolveBlockScalar;
  }
});

// ../../node_modules/yaml/dist/compose/resolve-flow-scalar.js
var require_resolve_flow_scalar = __commonJS({
  "../../node_modules/yaml/dist/compose/resolve-flow-scalar.js"(exports) {
    "use strict";
    var Scalar = require_Scalar();
    var resolveEnd = require_resolve_end();
    function resolveFlowScalar(scalar, strict, onError) {
      const { offset, type, source, end } = scalar;
      let _type;
      let value;
      const _onError = (rel, code, msg) => onError(offset + rel, code, msg);
      switch (type) {
        case "scalar":
          _type = Scalar.Scalar.PLAIN;
          value = plainValue(source, _onError);
          break;
        case "single-quoted-scalar":
          _type = Scalar.Scalar.QUOTE_SINGLE;
          value = singleQuotedValue(source, _onError);
          break;
        case "double-quoted-scalar":
          _type = Scalar.Scalar.QUOTE_DOUBLE;
          value = doubleQuotedValue(source, _onError);
          break;
        /* istanbul ignore next should not happen */
        default:
          onError(scalar, "UNEXPECTED_TOKEN", `Expected a flow scalar value, but found: ${type}`);
          return {
            value: "",
            type: null,
            comment: "",
            range: [offset, offset + source.length, offset + source.length]
          };
      }
      const valueEnd = offset + source.length;
      const re = resolveEnd.resolveEnd(end, valueEnd, strict, onError);
      return {
        value,
        type: _type,
        comment: re.comment,
        range: [offset, valueEnd, re.offset]
      };
    }
    function plainValue(source, onError) {
      let badChar = "";
      switch (source[0]) {
        /* istanbul ignore next should not happen */
        case "	":
          badChar = "a tab character";
          break;
        case ",":
          badChar = "flow indicator character ,";
          break;
        case "%":
          badChar = "directive indicator character %";
          break;
        case "|":
        case ">": {
          badChar = `block scalar indicator ${source[0]}`;
          break;
        }
        case "@":
        case "`": {
          badChar = `reserved character ${source[0]}`;
          break;
        }
      }
      if (badChar)
        onError(0, "BAD_SCALAR_START", `Plain value cannot start with ${badChar}`);
      return unfoldLines(source);
    }
    function singleQuotedValue(source, onError) {
      if (source[source.length - 1] !== "'" || source.length === 1)
        onError(source.length, "MISSING_CHAR", "Missing closing 'quote");
      return unfoldLines(source.slice(1, -1)).replace(/''/g, "'");
    }
    function unfoldLines(source) {
      const line = /(.*?)\r?\n/sy;
      let match = line.exec(source);
      if (!match)
        return source;
      let trimEnd, trimBoth;
      try {
        trimEnd = new RegExp("(?<![ 	])[ 	]+$");
        trimBoth = new RegExp("^[ 	]+|(?<![ 	])[ 	]+$", "g");
      } catch {
        trimEnd = /[ \t]+$/;
        trimBoth = /^[ \t]+|[ \t]+$/g;
      }
      let res = match[1].replace(trimEnd, "");
      let sep = " ";
      let pos = line.lastIndex;
      while (match = line.exec(source)) {
        const lm = match[1].replace(trimBoth, "");
        if (lm === "") {
          if (sep === "\n")
            res += sep;
          else
            sep = "\n";
        } else {
          res += sep + lm;
          sep = " ";
        }
        pos = line.lastIndex;
      }
      const last = /[ \t]*(.*)/sy;
      last.lastIndex = pos;
      match = last.exec(source);
      return res + sep + (match?.[1] ?? "");
    }
    function doubleQuotedValue(source, onError) {
      let res = "";
      for (let i = 1; i < source.length - 1; ++i) {
        const ch = source[i];
        if (ch === "\r" && source[i + 1] === "\n")
          continue;
        if (ch === "\n") {
          const { fold, offset } = foldNewline(source, i);
          res += fold;
          i = offset;
        } else if (ch === "\\") {
          let next = source[++i];
          const cc = escapeCodes[next];
          if (cc)
            res += cc;
          else if (next === "\n") {
            next = source[i + 1];
            while (next === " " || next === "	")
              next = source[++i + 1];
          } else if (next === "\r" && source[i + 1] === "\n") {
            next = source[++i + 1];
            while (next === " " || next === "	")
              next = source[++i + 1];
          } else if (next === "x" || next === "u" || next === "U") {
            const length = next === "x" ? 2 : next === "u" ? 4 : 8;
            res += parseCharCode(source, i + 1, length, onError);
            i += length;
          } else {
            const raw = source.substr(i - 1, 2);
            onError(i - 1, "BAD_DQ_ESCAPE", `Invalid escape sequence ${raw}`);
            res += raw;
          }
        } else if (ch === " " || ch === "	") {
          const wsStart = i;
          let next = source[i + 1];
          while (next === " " || next === "	")
            next = source[++i + 1];
          if (next !== "\n" && !(next === "\r" && source[i + 2] === "\n"))
            res += i > wsStart ? source.slice(wsStart, i + 1) : ch;
        } else {
          res += ch;
        }
      }
      if (source[source.length - 1] !== '"' || source.length === 1)
        onError(source.length, "MISSING_CHAR", 'Missing closing "quote');
      return res;
    }
    function foldNewline(source, offset) {
      let fold = "";
      let ch = source[offset + 1];
      while (ch === " " || ch === "	" || ch === "\n" || ch === "\r") {
        if (ch === "\r" && source[offset + 2] !== "\n")
          break;
        if (ch === "\n")
          fold += "\n";
        offset += 1;
        ch = source[offset + 1];
      }
      if (!fold)
        fold = " ";
      return { fold, offset };
    }
    var escapeCodes = {
      "0": "\0",
      // null character
      a: "\x07",
      // bell character
      b: "\b",
      // backspace
      e: "\x1B",
      // escape character
      f: "\f",
      // form feed
      n: "\n",
      // line feed
      r: "\r",
      // carriage return
      t: "	",
      // horizontal tab
      v: "\v",
      // vertical tab
      N: "\x85",
      // Unicode next line
      _: "\xA0",
      // Unicode non-breaking space
      L: "\u2028",
      // Unicode line separator
      P: "\u2029",
      // Unicode paragraph separator
      " ": " ",
      '"': '"',
      "/": "/",
      "\\": "\\",
      "	": "	"
    };
    function parseCharCode(source, offset, length, onError) {
      const cc = source.substr(offset, length);
      const ok = cc.length === length && /^[0-9a-fA-F]+$/.test(cc);
      const code = ok ? parseInt(cc, 16) : NaN;
      try {
        return String.fromCodePoint(code);
      } catch {
        const raw = source.substr(offset - 2, length + 2);
        onError(offset - 2, "BAD_DQ_ESCAPE", `Invalid escape sequence ${raw}`);
        return raw;
      }
    }
    exports.resolveFlowScalar = resolveFlowScalar;
  }
});

// ../../node_modules/yaml/dist/compose/compose-scalar.js
var require_compose_scalar = __commonJS({
  "../../node_modules/yaml/dist/compose/compose-scalar.js"(exports) {
    "use strict";
    var identity = require_identity();
    var Scalar = require_Scalar();
    var resolveBlockScalar = require_resolve_block_scalar();
    var resolveFlowScalar = require_resolve_flow_scalar();
    function composeScalar(ctx, token, tagToken, onError) {
      const { value, type, comment, range } = token.type === "block-scalar" ? resolveBlockScalar.resolveBlockScalar(ctx, token, onError) : resolveFlowScalar.resolveFlowScalar(token, ctx.options.strict, onError);
      const tagName = tagToken ? ctx.directives.tagName(tagToken.source, (msg) => onError(tagToken, "TAG_RESOLVE_FAILED", msg)) : null;
      let tag;
      if (ctx.options.stringKeys && ctx.atKey) {
        tag = ctx.schema[identity.SCALAR];
      } else if (tagName)
        tag = findScalarTagByName(ctx.schema, value, tagName, tagToken, onError);
      else if (token.type === "scalar")
        tag = findScalarTagByTest(ctx, value, token, onError);
      else
        tag = ctx.schema[identity.SCALAR];
      let scalar;
      try {
        const res = tag.resolve(value, (msg) => onError(tagToken ?? token, "TAG_RESOLVE_FAILED", msg), ctx.options);
        scalar = identity.isScalar(res) ? res : new Scalar.Scalar(res);
      } catch (error) {
        const msg = error instanceof Error ? error.message : String(error);
        onError(tagToken ?? token, "TAG_RESOLVE_FAILED", msg);
        scalar = new Scalar.Scalar(value);
      }
      scalar.range = range;
      scalar.source = value;
      if (type)
        scalar.type = type;
      if (tagName)
        scalar.tag = tagName;
      if (tag.format)
        scalar.format = tag.format;
      if (comment)
        scalar.comment = comment;
      return scalar;
    }
    function findScalarTagByName(schema, value, tagName, tagToken, onError) {
      if (tagName === "!")
        return schema[identity.SCALAR];
      const matchWithTest = [];
      for (const tag of schema.tags) {
        if (!tag.collection && tag.tag === tagName) {
          if (tag.default && tag.test)
            matchWithTest.push(tag);
          else
            return tag;
        }
      }
      for (const tag of matchWithTest)
        if (tag.test?.test(value))
          return tag;
      const kt = schema.knownTags[tagName];
      if (kt && !kt.collection) {
        schema.tags.push(Object.assign({}, kt, { default: false, test: void 0 }));
        return kt;
      }
      onError(tagToken, "TAG_RESOLVE_FAILED", `Unresolved tag: ${tagName}`, tagName !== "tag:yaml.org,2002:str");
      return schema[identity.SCALAR];
    }
    function findScalarTagByTest({ atKey, directives, schema }, value, token, onError) {
      const tag = schema.tags.find((tag2) => (tag2.default === true || atKey && tag2.default === "key") && tag2.test?.test(value)) || schema[identity.SCALAR];
      if (schema.compat) {
        const compat = schema.compat.find((tag2) => tag2.default && tag2.test?.test(value)) ?? schema[identity.SCALAR];
        if (tag.tag !== compat.tag) {
          const ts = directives.tagString(tag.tag);
          const cs = directives.tagString(compat.tag);
          const msg = `Value may be parsed as either ${ts} or ${cs}`;
          onError(token, "TAG_RESOLVE_FAILED", msg, true);
        }
      }
      return tag;
    }
    exports.composeScalar = composeScalar;
  }
});

// ../../node_modules/yaml/dist/compose/util-empty-scalar-position.js
var require_util_empty_scalar_position = __commonJS({
  "../../node_modules/yaml/dist/compose/util-empty-scalar-position.js"(exports) {
    "use strict";
    function emptyScalarPosition(offset, before, pos) {
      if (before) {
        pos ?? (pos = before.length);
        for (let i = pos - 1; i >= 0; --i) {
          let st = before[i];
          switch (st.type) {
            case "space":
            case "comment":
            case "newline":
              offset -= st.source.length;
              continue;
          }
          st = before[++i];
          while (st?.type === "space") {
            offset += st.source.length;
            st = before[++i];
          }
          break;
        }
      }
      return offset;
    }
    exports.emptyScalarPosition = emptyScalarPosition;
  }
});

// ../../node_modules/yaml/dist/compose/compose-node.js
var require_compose_node = __commonJS({
  "../../node_modules/yaml/dist/compose/compose-node.js"(exports) {
    "use strict";
    var Alias = require_Alias();
    var identity = require_identity();
    var composeCollection = require_compose_collection();
    var composeScalar = require_compose_scalar();
    var resolveEnd = require_resolve_end();
    var utilEmptyScalarPosition = require_util_empty_scalar_position();
    var CN = { composeNode, composeEmptyNode };
    function composeNode(ctx, token, props, onError) {
      const atKey = ctx.atKey;
      const { spaceBefore, comment, anchor, tag } = props;
      let node;
      let isSrcToken = true;
      switch (token.type) {
        case "alias":
          node = composeAlias(ctx, token, onError);
          if (anchor || tag)
            onError(token, "ALIAS_PROPS", "An alias node must not specify any properties");
          break;
        case "scalar":
        case "single-quoted-scalar":
        case "double-quoted-scalar":
        case "block-scalar":
          node = composeScalar.composeScalar(ctx, token, tag, onError);
          if (anchor)
            node.anchor = anchor.source.substring(1);
          break;
        case "block-map":
        case "block-seq":
        case "flow-collection":
          try {
            node = composeCollection.composeCollection(CN, ctx, token, props, onError);
            if (anchor)
              node.anchor = anchor.source.substring(1);
          } catch (error) {
            const message = error instanceof Error ? error.message : String(error);
            onError(token, "RESOURCE_EXHAUSTION", message);
          }
          break;
        default: {
          const message = token.type === "error" ? token.message : `Unsupported token (type: ${token.type})`;
          onError(token, "UNEXPECTED_TOKEN", message);
          isSrcToken = false;
        }
      }
      node ?? (node = composeEmptyNode(ctx, token.offset, void 0, null, props, onError));
      if (anchor && node.anchor === "")
        onError(anchor, "BAD_ALIAS", "Anchor cannot be an empty string");
      if (atKey && ctx.options.stringKeys && (!identity.isScalar(node) || typeof node.value !== "string" || node.tag && node.tag !== "tag:yaml.org,2002:str")) {
        const msg = "With stringKeys, all keys must be strings";
        onError(tag ?? token, "NON_STRING_KEY", msg);
      }
      if (spaceBefore)
        node.spaceBefore = true;
      if (comment) {
        if (token.type === "scalar" && token.source === "")
          node.comment = comment;
        else
          node.commentBefore = comment;
      }
      if (ctx.options.keepSourceTokens && isSrcToken)
        node.srcToken = token;
      return node;
    }
    function composeEmptyNode(ctx, offset, before, pos, { spaceBefore, comment, anchor, tag, end }, onError) {
      const token = {
        type: "scalar",
        offset: utilEmptyScalarPosition.emptyScalarPosition(offset, before, pos),
        indent: -1,
        source: ""
      };
      const node = composeScalar.composeScalar(ctx, token, tag, onError);
      if (anchor) {
        node.anchor = anchor.source.substring(1);
        if (node.anchor === "")
          onError(anchor, "BAD_ALIAS", "Anchor cannot be an empty string");
      }
      if (spaceBefore)
        node.spaceBefore = true;
      if (comment) {
        node.comment = comment;
        node.range[2] = end;
      }
      return node;
    }
    function composeAlias({ options }, { offset, source, end }, onError) {
      const alias = new Alias.Alias(source.substring(1));
      if (alias.source === "")
        onError(offset, "BAD_ALIAS", "Alias cannot be an empty string");
      if (alias.source.endsWith(":"))
        onError(offset + source.length - 1, "BAD_ALIAS", "Alias ending in : is ambiguous", true);
      const valueEnd = offset + source.length;
      const re = resolveEnd.resolveEnd(end, valueEnd, options.strict, onError);
      alias.range = [offset, valueEnd, re.offset];
      if (re.comment)
        alias.comment = re.comment;
      return alias;
    }
    exports.composeEmptyNode = composeEmptyNode;
    exports.composeNode = composeNode;
  }
});

// ../../node_modules/yaml/dist/compose/compose-doc.js
var require_compose_doc = __commonJS({
  "../../node_modules/yaml/dist/compose/compose-doc.js"(exports) {
    "use strict";
    var Document = require_Document();
    var composeNode = require_compose_node();
    var resolveEnd = require_resolve_end();
    var resolveProps = require_resolve_props();
    function composeDoc(options, directives, { offset, start, value, end }, onError) {
      const opts = Object.assign({ _directives: directives }, options);
      const doc = new Document.Document(void 0, opts);
      const ctx = {
        atKey: false,
        atRoot: true,
        directives: doc.directives,
        options: doc.options,
        schema: doc.schema
      };
      const props = resolveProps.resolveProps(start, {
        indicator: "doc-start",
        next: value ?? end?.[0],
        offset,
        onError,
        parentIndent: 0,
        startOnNewline: true
      });
      if (props.found) {
        doc.directives.docStart = true;
        if (value && (value.type === "block-map" || value.type === "block-seq") && !props.hasNewline)
          onError(props.end, "MISSING_CHAR", "Block collection cannot start on same line with directives-end marker");
      }
      doc.contents = value ? composeNode.composeNode(ctx, value, props, onError) : composeNode.composeEmptyNode(ctx, props.end, start, null, props, onError);
      const contentEnd = doc.contents.range[2];
      const re = resolveEnd.resolveEnd(end, contentEnd, false, onError);
      if (re.comment)
        doc.comment = re.comment;
      doc.range = [offset, contentEnd, re.offset];
      return doc;
    }
    exports.composeDoc = composeDoc;
  }
});

// ../../node_modules/yaml/dist/compose/composer.js
var require_composer = __commonJS({
  "../../node_modules/yaml/dist/compose/composer.js"(exports) {
    "use strict";
    var node_process = __require("process");
    var directives = require_directives();
    var Document = require_Document();
    var errors = require_errors();
    var identity = require_identity();
    var composeDoc = require_compose_doc();
    var resolveEnd = require_resolve_end();
    function getErrorPos(src) {
      if (typeof src === "number")
        return [src, src + 1];
      if (Array.isArray(src))
        return src.length === 2 ? src : [src[0], src[1]];
      const { offset, source } = src;
      return [offset, offset + (typeof source === "string" ? source.length : 1)];
    }
    function parsePrelude(prelude) {
      let comment = "";
      let atComment = false;
      let afterEmptyLine = false;
      for (let i = 0; i < prelude.length; ++i) {
        const source = prelude[i];
        switch (source[0]) {
          case "#":
            comment += (comment === "" ? "" : afterEmptyLine ? "\n\n" : "\n") + (source.substring(1) || " ");
            atComment = true;
            afterEmptyLine = false;
            break;
          case "%":
            if (prelude[i + 1]?.[0] !== "#")
              i += 1;
            atComment = false;
            break;
          default:
            if (!atComment)
              afterEmptyLine = true;
            atComment = false;
        }
      }
      return { comment, afterEmptyLine };
    }
    var Composer = class {
      constructor(options = {}) {
        this.doc = null;
        this.atDirectives = false;
        this.prelude = [];
        this.errors = [];
        this.warnings = [];
        this.onError = (source, code, message, warning) => {
          const pos = getErrorPos(source);
          if (warning)
            this.warnings.push(new errors.YAMLWarning(pos, code, message));
          else
            this.errors.push(new errors.YAMLParseError(pos, code, message));
        };
        this.directives = new directives.Directives({ version: options.version || "1.2" });
        this.options = options;
      }
      decorate(doc, afterDoc) {
        const { comment, afterEmptyLine } = parsePrelude(this.prelude);
        if (comment) {
          const dc = doc.contents;
          if (afterDoc) {
            doc.comment = doc.comment ? `${doc.comment}
${comment}` : comment;
          } else if (afterEmptyLine || doc.directives.docStart || !dc) {
            doc.commentBefore = comment;
          } else if (identity.isCollection(dc) && !dc.flow && dc.items.length > 0) {
            let it = dc.items[0];
            if (identity.isPair(it))
              it = it.key;
            const cb = it.commentBefore;
            it.commentBefore = cb ? `${comment}
${cb}` : comment;
          } else {
            const cb = dc.commentBefore;
            dc.commentBefore = cb ? `${comment}
${cb}` : comment;
          }
        }
        if (afterDoc) {
          for (let i = 0; i < this.errors.length; ++i)
            doc.errors.push(this.errors[i]);
          for (let i = 0; i < this.warnings.length; ++i)
            doc.warnings.push(this.warnings[i]);
        } else {
          doc.errors = this.errors;
          doc.warnings = this.warnings;
        }
        this.prelude = [];
        this.errors = [];
        this.warnings = [];
      }
      /**
       * Current stream status information.
       *
       * Mostly useful at the end of input for an empty stream.
       */
      streamInfo() {
        return {
          comment: parsePrelude(this.prelude).comment,
          directives: this.directives,
          errors: this.errors,
          warnings: this.warnings
        };
      }
      /**
       * Compose tokens into documents.
       *
       * @param forceDoc - If the stream contains no document, still emit a final document including any comments and directives that would be applied to a subsequent document.
       * @param endOffset - Should be set if `forceDoc` is also set, to set the document range end and to indicate errors correctly.
       */
      *compose(tokens, forceDoc = false, endOffset = -1) {
        for (const token of tokens)
          yield* this.next(token);
        yield* this.end(forceDoc, endOffset);
      }
      /** Advance the composer by one CST token. */
      *next(token) {
        if (node_process.env.LOG_STREAM)
          console.dir(token, { depth: null });
        switch (token.type) {
          case "directive":
            this.directives.add(token.source, (offset, message, warning) => {
              const pos = getErrorPos(token);
              pos[0] += offset;
              this.onError(pos, "BAD_DIRECTIVE", message, warning);
            });
            this.prelude.push(token.source);
            this.atDirectives = true;
            break;
          case "document": {
            const doc = composeDoc.composeDoc(this.options, this.directives, token, this.onError);
            if (this.atDirectives && !doc.directives.docStart)
              this.onError(token, "MISSING_CHAR", "Missing directives-end/doc-start indicator line");
            this.decorate(doc, false);
            if (this.doc)
              yield this.doc;
            this.doc = doc;
            this.atDirectives = false;
            break;
          }
          case "byte-order-mark":
          case "space":
            break;
          case "comment":
          case "newline":
            this.prelude.push(token.source);
            break;
          case "error": {
            const msg = token.source ? `${token.message}: ${JSON.stringify(token.source)}` : token.message;
            const error = new errors.YAMLParseError(getErrorPos(token), "UNEXPECTED_TOKEN", msg);
            if (this.atDirectives || !this.doc)
              this.errors.push(error);
            else
              this.doc.errors.push(error);
            break;
          }
          case "doc-end": {
            if (!this.doc) {
              const msg = "Unexpected doc-end without preceding document";
              this.errors.push(new errors.YAMLParseError(getErrorPos(token), "UNEXPECTED_TOKEN", msg));
              break;
            }
            this.doc.directives.docEnd = true;
            const end = resolveEnd.resolveEnd(token.end, token.offset + token.source.length, this.doc.options.strict, this.onError);
            this.decorate(this.doc, true);
            if (end.comment) {
              const dc = this.doc.comment;
              this.doc.comment = dc ? `${dc}
${end.comment}` : end.comment;
            }
            this.doc.range[2] = end.offset;
            break;
          }
          default:
            this.errors.push(new errors.YAMLParseError(getErrorPos(token), "UNEXPECTED_TOKEN", `Unsupported token ${token.type}`));
        }
      }
      /**
       * Call at end of input to yield any remaining document.
       *
       * @param forceDoc - If the stream contains no document, still emit a final document including any comments and directives that would be applied to a subsequent document.
       * @param endOffset - Should be set if `forceDoc` is also set, to set the document range end and to indicate errors correctly.
       */
      *end(forceDoc = false, endOffset = -1) {
        if (this.doc) {
          this.decorate(this.doc, true);
          yield this.doc;
          this.doc = null;
        } else if (forceDoc) {
          const opts = Object.assign({ _directives: this.directives }, this.options);
          const doc = new Document.Document(void 0, opts);
          if (this.atDirectives)
            this.onError(endOffset, "MISSING_CHAR", "Missing directives-end indicator line");
          doc.range = [0, endOffset, endOffset];
          this.decorate(doc, false);
          yield doc;
        }
      }
    };
    exports.Composer = Composer;
  }
});

// ../../node_modules/yaml/dist/parse/cst-scalar.js
var require_cst_scalar = __commonJS({
  "../../node_modules/yaml/dist/parse/cst-scalar.js"(exports) {
    "use strict";
    var resolveBlockScalar = require_resolve_block_scalar();
    var resolveFlowScalar = require_resolve_flow_scalar();
    var errors = require_errors();
    var stringifyString = require_stringifyString();
    function resolveAsScalar(token, strict = true, onError) {
      if (token) {
        const _onError = (pos, code, message) => {
          const offset = typeof pos === "number" ? pos : Array.isArray(pos) ? pos[0] : pos.offset;
          if (onError)
            onError(offset, code, message);
          else
            throw new errors.YAMLParseError([offset, offset + 1], code, message);
        };
        switch (token.type) {
          case "scalar":
          case "single-quoted-scalar":
          case "double-quoted-scalar":
            return resolveFlowScalar.resolveFlowScalar(token, strict, _onError);
          case "block-scalar":
            return resolveBlockScalar.resolveBlockScalar({ options: { strict } }, token, _onError);
        }
      }
      return null;
    }
    function createScalarToken(value, context) {
      const { implicitKey = false, indent, inFlow = false, offset = -1, type = "PLAIN" } = context;
      const source = stringifyString.stringifyString({ type, value }, {
        implicitKey,
        indent: indent > 0 ? " ".repeat(indent) : "",
        inFlow,
        options: { blockQuote: true, lineWidth: -1 }
      });
      const end = context.end ?? [
        { type: "newline", offset: -1, indent, source: "\n" }
      ];
      switch (source[0]) {
        case "|":
        case ">": {
          const he = source.indexOf("\n");
          const head = source.substring(0, he);
          const body = source.substring(he + 1) + "\n";
          const props = [
            { type: "block-scalar-header", offset, indent, source: head }
          ];
          if (!addEndtoBlockProps(props, end))
            props.push({ type: "newline", offset: -1, indent, source: "\n" });
          return { type: "block-scalar", offset, indent, props, source: body };
        }
        case '"':
          return { type: "double-quoted-scalar", offset, indent, source, end };
        case "'":
          return { type: "single-quoted-scalar", offset, indent, source, end };
        default:
          return { type: "scalar", offset, indent, source, end };
      }
    }
    function setScalarValue(token, value, context = {}) {
      let { afterKey = false, implicitKey = false, inFlow = false, type } = context;
      let indent = "indent" in token ? token.indent : null;
      if (afterKey && typeof indent === "number")
        indent += 2;
      if (!type)
        switch (token.type) {
          case "single-quoted-scalar":
            type = "QUOTE_SINGLE";
            break;
          case "double-quoted-scalar":
            type = "QUOTE_DOUBLE";
            break;
          case "block-scalar": {
            const header = token.props[0];
            if (header.type !== "block-scalar-header")
              throw new Error("Invalid block scalar header");
            type = header.source[0] === ">" ? "BLOCK_FOLDED" : "BLOCK_LITERAL";
            break;
          }
          default:
            type = "PLAIN";
        }
      const source = stringifyString.stringifyString({ type, value }, {
        implicitKey: implicitKey || indent === null,
        indent: indent !== null && indent > 0 ? " ".repeat(indent) : "",
        inFlow,
        options: { blockQuote: true, lineWidth: -1 }
      });
      switch (source[0]) {
        case "|":
        case ">":
          setBlockScalarValue(token, source);
          break;
        case '"':
          setFlowScalarValue(token, source, "double-quoted-scalar");
          break;
        case "'":
          setFlowScalarValue(token, source, "single-quoted-scalar");
          break;
        default:
          setFlowScalarValue(token, source, "scalar");
      }
    }
    function setBlockScalarValue(token, source) {
      const he = source.indexOf("\n");
      const head = source.substring(0, he);
      const body = source.substring(he + 1) + "\n";
      if (token.type === "block-scalar") {
        const header = token.props[0];
        if (header.type !== "block-scalar-header")
          throw new Error("Invalid block scalar header");
        header.source = head;
        token.source = body;
      } else {
        const { offset } = token;
        const indent = "indent" in token ? token.indent : -1;
        const props = [
          { type: "block-scalar-header", offset, indent, source: head }
        ];
        if (!addEndtoBlockProps(props, "end" in token ? token.end : void 0))
          props.push({ type: "newline", offset: -1, indent, source: "\n" });
        for (const key of Object.keys(token))
          if (key !== "type" && key !== "offset")
            delete token[key];
        Object.assign(token, { type: "block-scalar", indent, props, source: body });
      }
    }
    function addEndtoBlockProps(props, end) {
      if (end)
        for (const st of end)
          switch (st.type) {
            case "space":
            case "comment":
              props.push(st);
              break;
            case "newline":
              props.push(st);
              return true;
          }
      return false;
    }
    function setFlowScalarValue(token, source, type) {
      switch (token.type) {
        case "scalar":
        case "double-quoted-scalar":
        case "single-quoted-scalar":
          token.type = type;
          token.source = source;
          break;
        case "block-scalar": {
          const end = token.props.slice(1);
          let oa = source.length;
          if (token.props[0].type === "block-scalar-header")
            oa -= token.props[0].source.length;
          for (const tok of end)
            tok.offset += oa;
          delete token.props;
          Object.assign(token, { type, source, end });
          break;
        }
        case "block-map":
        case "block-seq": {
          const offset = token.offset + source.length;
          const nl = { type: "newline", offset, indent: token.indent, source: "\n" };
          delete token.items;
          Object.assign(token, { type, source, end: [nl] });
          break;
        }
        default: {
          const indent = "indent" in token ? token.indent : -1;
          const end = "end" in token && Array.isArray(token.end) ? token.end.filter((st) => st.type === "space" || st.type === "comment" || st.type === "newline") : [];
          for (const key of Object.keys(token))
            if (key !== "type" && key !== "offset")
              delete token[key];
          Object.assign(token, { type, indent, source, end });
        }
      }
    }
    exports.createScalarToken = createScalarToken;
    exports.resolveAsScalar = resolveAsScalar;
    exports.setScalarValue = setScalarValue;
  }
});

// ../../node_modules/yaml/dist/parse/cst-stringify.js
var require_cst_stringify = __commonJS({
  "../../node_modules/yaml/dist/parse/cst-stringify.js"(exports) {
    "use strict";
    var stringify = (cst) => "type" in cst ? stringifyToken(cst) : stringifyItem(cst);
    function stringifyToken(token) {
      switch (token.type) {
        case "block-scalar": {
          let res = "";
          for (const tok of token.props)
            res += stringifyToken(tok);
          return res + token.source;
        }
        case "block-map":
        case "block-seq": {
          let res = "";
          for (const item of token.items)
            res += stringifyItem(item);
          return res;
        }
        case "flow-collection": {
          let res = token.start.source;
          for (const item of token.items)
            res += stringifyItem(item);
          for (const st of token.end)
            res += st.source;
          return res;
        }
        case "document": {
          let res = stringifyItem(token);
          if (token.end)
            for (const st of token.end)
              res += st.source;
          return res;
        }
        default: {
          let res = token.source;
          if ("end" in token && token.end)
            for (const st of token.end)
              res += st.source;
          return res;
        }
      }
    }
    function stringifyItem({ start, key, sep, value }) {
      let res = "";
      for (const st of start)
        res += st.source;
      if (key)
        res += stringifyToken(key);
      if (sep)
        for (const st of sep)
          res += st.source;
      if (value)
        res += stringifyToken(value);
      return res;
    }
    exports.stringify = stringify;
  }
});

// ../../node_modules/yaml/dist/parse/cst-visit.js
var require_cst_visit = __commonJS({
  "../../node_modules/yaml/dist/parse/cst-visit.js"(exports) {
    "use strict";
    var BREAK = /* @__PURE__ */ Symbol("break visit");
    var SKIP = /* @__PURE__ */ Symbol("skip children");
    var REMOVE = /* @__PURE__ */ Symbol("remove item");
    function visit(cst, visitor) {
      if ("type" in cst && cst.type === "document")
        cst = { start: cst.start, value: cst.value };
      _visit(Object.freeze([]), cst, visitor);
    }
    visit.BREAK = BREAK;
    visit.SKIP = SKIP;
    visit.REMOVE = REMOVE;
    visit.itemAtPath = (cst, path) => {
      let item = cst;
      for (const [field, index] of path) {
        const tok = item?.[field];
        if (tok && "items" in tok) {
          item = tok.items[index];
        } else
          return void 0;
      }
      return item;
    };
    visit.parentCollection = (cst, path) => {
      const parent = visit.itemAtPath(cst, path.slice(0, -1));
      const field = path[path.length - 1][0];
      const coll = parent?.[field];
      if (coll && "items" in coll)
        return coll;
      throw new Error("Parent collection not found");
    };
    function _visit(path, item, visitor) {
      let ctrl = visitor(item, path);
      if (typeof ctrl === "symbol")
        return ctrl;
      for (const field of ["key", "value"]) {
        const token = item[field];
        if (token && "items" in token) {
          for (let i = 0; i < token.items.length; ++i) {
            const ci = _visit(Object.freeze(path.concat([[field, i]])), token.items[i], visitor);
            if (typeof ci === "number")
              i = ci - 1;
            else if (ci === BREAK)
              return BREAK;
            else if (ci === REMOVE) {
              token.items.splice(i, 1);
              i -= 1;
            }
          }
          if (typeof ctrl === "function" && field === "key")
            ctrl = ctrl(item, path);
        }
      }
      return typeof ctrl === "function" ? ctrl(item, path) : ctrl;
    }
    exports.visit = visit;
  }
});

// ../../node_modules/yaml/dist/parse/cst.js
var require_cst = __commonJS({
  "../../node_modules/yaml/dist/parse/cst.js"(exports) {
    "use strict";
    var cstScalar = require_cst_scalar();
    var cstStringify = require_cst_stringify();
    var cstVisit = require_cst_visit();
    var BOM = "\uFEFF";
    var DOCUMENT = "";
    var FLOW_END = "";
    var SCALAR = "";
    var isCollection = (token) => !!token && "items" in token;
    var isScalar = (token) => !!token && (token.type === "scalar" || token.type === "single-quoted-scalar" || token.type === "double-quoted-scalar" || token.type === "block-scalar");
    function prettyToken(token) {
      switch (token) {
        case BOM:
          return "<BOM>";
        case DOCUMENT:
          return "<DOC>";
        case FLOW_END:
          return "<FLOW_END>";
        case SCALAR:
          return "<SCALAR>";
        default:
          return JSON.stringify(token);
      }
    }
    function tokenType(source) {
      switch (source) {
        case BOM:
          return "byte-order-mark";
        case DOCUMENT:
          return "doc-mode";
        case FLOW_END:
          return "flow-error-end";
        case SCALAR:
          return "scalar";
        case "---":
          return "doc-start";
        case "...":
          return "doc-end";
        case "":
        case "\n":
        case "\r\n":
          return "newline";
        case "-":
          return "seq-item-ind";
        case "?":
          return "explicit-key-ind";
        case ":":
          return "map-value-ind";
        case "{":
          return "flow-map-start";
        case "}":
          return "flow-map-end";
        case "[":
          return "flow-seq-start";
        case "]":
          return "flow-seq-end";
        case ",":
          return "comma";
      }
      switch (source[0]) {
        case " ":
        case "	":
          return "space";
        case "#":
          return "comment";
        case "%":
          return "directive-line";
        case "*":
          return "alias";
        case "&":
          return "anchor";
        case "!":
          return "tag";
        case "'":
          return "single-quoted-scalar";
        case '"':
          return "double-quoted-scalar";
        case "|":
        case ">":
          return "block-scalar-header";
      }
      return null;
    }
    exports.createScalarToken = cstScalar.createScalarToken;
    exports.resolveAsScalar = cstScalar.resolveAsScalar;
    exports.setScalarValue = cstScalar.setScalarValue;
    exports.stringify = cstStringify.stringify;
    exports.visit = cstVisit.visit;
    exports.BOM = BOM;
    exports.DOCUMENT = DOCUMENT;
    exports.FLOW_END = FLOW_END;
    exports.SCALAR = SCALAR;
    exports.isCollection = isCollection;
    exports.isScalar = isScalar;
    exports.prettyToken = prettyToken;
    exports.tokenType = tokenType;
  }
});

// ../../node_modules/yaml/dist/parse/lexer.js
var require_lexer = __commonJS({
  "../../node_modules/yaml/dist/parse/lexer.js"(exports) {
    "use strict";
    var cst = require_cst();
    function isEmpty(ch) {
      switch (ch) {
        case void 0:
        case " ":
        case "\n":
        case "\r":
        case "	":
          return true;
        default:
          return false;
      }
    }
    var hexDigits = new Set("0123456789ABCDEFabcdef");
    var tagChars = new Set("0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz-#;/?:@&=+$_.!~*'()");
    var flowIndicatorChars = new Set(",[]{}");
    var invalidAnchorChars = new Set(" ,[]{}\n\r	");
    var isNotAnchorChar = (ch) => !ch || invalidAnchorChars.has(ch);
    var Lexer = class {
      constructor() {
        this.atEnd = false;
        this.blockScalarIndent = -1;
        this.blockScalarKeep = false;
        this.buffer = "";
        this.flowKey = false;
        this.flowLevel = 0;
        this.indentNext = 0;
        this.indentValue = 0;
        this.lineEndPos = null;
        this.next = null;
        this.pos = 0;
      }
      /**
       * Generate YAML tokens from the `source` string. If `incomplete`,
       * a part of the last line may be left as a buffer for the next call.
       *
       * @returns A generator of lexical tokens
       */
      *lex(source, incomplete = false) {
        if (source) {
          if (typeof source !== "string")
            throw TypeError("source is not a string");
          this.buffer = this.buffer ? this.buffer + source : source;
          this.lineEndPos = null;
        }
        this.atEnd = !incomplete;
        let next = this.next ?? "stream";
        while (next && (incomplete || this.hasChars(1)))
          next = yield* this.parseNext(next);
      }
      atLineEnd() {
        let i = this.pos;
        let ch = this.buffer[i];
        while (ch === " " || ch === "	")
          ch = this.buffer[++i];
        if (!ch || ch === "#" || ch === "\n")
          return true;
        if (ch === "\r")
          return this.buffer[i + 1] === "\n";
        return false;
      }
      charAt(n) {
        return this.buffer[this.pos + n];
      }
      continueScalar(offset) {
        let ch = this.buffer[offset];
        if (this.indentNext > 0) {
          let indent = 0;
          while (ch === " ")
            ch = this.buffer[++indent + offset];
          if (ch === "\r") {
            const next = this.buffer[indent + offset + 1];
            if (next === "\n" || !next && !this.atEnd)
              return offset + indent + 1;
          }
          return ch === "\n" || indent >= this.indentNext || !ch && !this.atEnd ? offset + indent : -1;
        }
        if (ch === "-" || ch === ".") {
          const dt = this.buffer.substr(offset, 3);
          if ((dt === "---" || dt === "...") && isEmpty(this.buffer[offset + 3]))
            return -1;
        }
        return offset;
      }
      getLine() {
        let end = this.lineEndPos;
        if (typeof end !== "number" || end !== -1 && end < this.pos) {
          end = this.buffer.indexOf("\n", this.pos);
          this.lineEndPos = end;
        }
        if (end === -1)
          return this.atEnd ? this.buffer.substring(this.pos) : null;
        if (this.buffer[end - 1] === "\r")
          end -= 1;
        return this.buffer.substring(this.pos, end);
      }
      hasChars(n) {
        return this.pos + n <= this.buffer.length;
      }
      setNext(state) {
        this.buffer = this.buffer.substring(this.pos);
        this.pos = 0;
        this.lineEndPos = null;
        this.next = state;
        return null;
      }
      peek(n) {
        return this.buffer.substr(this.pos, n);
      }
      *parseNext(next) {
        switch (next) {
          case "stream":
            return yield* this.parseStream();
          case "line-start":
            return yield* this.parseLineStart();
          case "block-start":
            return yield* this.parseBlockStart();
          case "doc":
            return yield* this.parseDocument();
          case "flow":
            return yield* this.parseFlowCollection();
          case "quoted-scalar":
            return yield* this.parseQuotedScalar();
          case "block-scalar":
            return yield* this.parseBlockScalar();
          case "plain-scalar":
            return yield* this.parsePlainScalar();
        }
      }
      *parseStream() {
        let line = this.getLine();
        if (line === null)
          return this.setNext("stream");
        if (line[0] === cst.BOM) {
          yield* this.pushCount(1);
          line = line.substring(1);
        }
        if (line[0] === "%") {
          let dirEnd = line.length;
          let cs = line.indexOf("#");
          while (cs !== -1) {
            const ch = line[cs - 1];
            if (ch === " " || ch === "	") {
              dirEnd = cs - 1;
              break;
            } else {
              cs = line.indexOf("#", cs + 1);
            }
          }
          while (true) {
            const ch = line[dirEnd - 1];
            if (ch === " " || ch === "	")
              dirEnd -= 1;
            else
              break;
          }
          const n = (yield* this.pushCount(dirEnd)) + (yield* this.pushSpaces(true));
          yield* this.pushCount(line.length - n);
          this.pushNewline();
          return "stream";
        }
        if (this.atLineEnd()) {
          const sp = yield* this.pushSpaces(true);
          yield* this.pushCount(line.length - sp);
          yield* this.pushNewline();
          return "stream";
        }
        yield cst.DOCUMENT;
        return yield* this.parseLineStart();
      }
      *parseLineStart() {
        const ch = this.charAt(0);
        if (!ch && !this.atEnd)
          return this.setNext("line-start");
        if (ch === "-" || ch === ".") {
          if (!this.atEnd && !this.hasChars(4))
            return this.setNext("line-start");
          const s = this.peek(3);
          if ((s === "---" || s === "...") && isEmpty(this.charAt(3))) {
            yield* this.pushCount(3);
            this.indentValue = 0;
            this.indentNext = 0;
            return s === "---" ? "doc" : "stream";
          }
        }
        this.indentValue = yield* this.pushSpaces(false);
        if (this.indentNext > this.indentValue && !isEmpty(this.charAt(1)))
          this.indentNext = this.indentValue;
        return yield* this.parseBlockStart();
      }
      *parseBlockStart() {
        const [ch0, ch1] = this.peek(2);
        if (!ch1 && !this.atEnd)
          return this.setNext("block-start");
        if ((ch0 === "-" || ch0 === "?" || ch0 === ":") && isEmpty(ch1)) {
          const n = (yield* this.pushCount(1)) + (yield* this.pushSpaces(true));
          this.indentNext = this.indentValue + 1;
          this.indentValue += n;
          return "block-start";
        }
        return "doc";
      }
      *parseDocument() {
        yield* this.pushSpaces(true);
        const line = this.getLine();
        if (line === null)
          return this.setNext("doc");
        let n = yield* this.pushIndicators();
        switch (line[n]) {
          case "#":
            yield* this.pushCount(line.length - n);
          // fallthrough
          case void 0:
            yield* this.pushNewline();
            return yield* this.parseLineStart();
          case "{":
          case "[":
            yield* this.pushCount(1);
            this.flowKey = false;
            this.flowLevel = 1;
            return "flow";
          case "}":
          case "]":
            yield* this.pushCount(1);
            return "doc";
          case "*":
            yield* this.pushUntil(isNotAnchorChar);
            return "doc";
          case '"':
          case "'":
            return yield* this.parseQuotedScalar();
          case "|":
          case ">":
            n += yield* this.parseBlockScalarHeader();
            n += yield* this.pushSpaces(true);
            yield* this.pushCount(line.length - n);
            yield* this.pushNewline();
            return yield* this.parseBlockScalar();
          default:
            return yield* this.parsePlainScalar();
        }
      }
      *parseFlowCollection() {
        let nl, sp;
        let indent = -1;
        do {
          nl = yield* this.pushNewline();
          if (nl > 0) {
            sp = yield* this.pushSpaces(false);
            this.indentValue = indent = sp;
          } else {
            sp = 0;
          }
          sp += yield* this.pushSpaces(true);
        } while (nl + sp > 0);
        const line = this.getLine();
        if (line === null)
          return this.setNext("flow");
        if (indent !== -1 && indent < this.indentNext && line[0] !== "#" || indent === 0 && (line.startsWith("---") || line.startsWith("...")) && isEmpty(line[3])) {
          const atFlowEndMarker = indent === this.indentNext - 1 && this.flowLevel === 1 && (line[0] === "]" || line[0] === "}");
          if (!atFlowEndMarker) {
            this.flowLevel = 0;
            yield cst.FLOW_END;
            return yield* this.parseLineStart();
          }
        }
        let n = 0;
        while (line[n] === ",") {
          n += yield* this.pushCount(1);
          n += yield* this.pushSpaces(true);
          this.flowKey = false;
        }
        n += yield* this.pushIndicators();
        switch (line[n]) {
          case void 0:
            return "flow";
          case "#":
            yield* this.pushCount(line.length - n);
            return "flow";
          case "{":
          case "[":
            yield* this.pushCount(1);
            this.flowKey = false;
            this.flowLevel += 1;
            return "flow";
          case "}":
          case "]":
            yield* this.pushCount(1);
            this.flowKey = true;
            this.flowLevel -= 1;
            return this.flowLevel ? "flow" : "doc";
          case "*":
            yield* this.pushUntil(isNotAnchorChar);
            return "flow";
          case '"':
          case "'":
            this.flowKey = true;
            return yield* this.parseQuotedScalar();
          case ":": {
            const next = this.charAt(1);
            if (this.flowKey || isEmpty(next) || next === ",") {
              this.flowKey = false;
              yield* this.pushCount(1);
              yield* this.pushSpaces(true);
              return "flow";
            }
          }
          // fallthrough
          default:
            this.flowKey = false;
            return yield* this.parsePlainScalar();
        }
      }
      *parseQuotedScalar() {
        const quote = this.charAt(0);
        let end = this.buffer.indexOf(quote, this.pos + 1);
        if (quote === "'") {
          while (end !== -1 && this.buffer[end + 1] === "'")
            end = this.buffer.indexOf("'", end + 2);
        } else {
          while (end !== -1) {
            let n = 0;
            while (this.buffer[end - 1 - n] === "\\")
              n += 1;
            if (n % 2 === 0)
              break;
            end = this.buffer.indexOf('"', end + 1);
          }
        }
        const qb = this.buffer.substring(0, end);
        let nl = qb.indexOf("\n", this.pos);
        if (nl !== -1) {
          while (nl !== -1) {
            const cs = this.continueScalar(nl + 1);
            if (cs === -1)
              break;
            nl = qb.indexOf("\n", cs);
          }
          if (nl !== -1) {
            end = nl - (qb[nl - 1] === "\r" ? 2 : 1);
          }
        }
        if (end === -1) {
          if (!this.atEnd)
            return this.setNext("quoted-scalar");
          end = this.buffer.length;
        }
        yield* this.pushToIndex(end + 1, false);
        return this.flowLevel ? "flow" : "doc";
      }
      *parseBlockScalarHeader() {
        this.blockScalarIndent = -1;
        this.blockScalarKeep = false;
        let i = this.pos;
        while (true) {
          const ch = this.buffer[++i];
          if (ch === "+")
            this.blockScalarKeep = true;
          else if (ch > "0" && ch <= "9")
            this.blockScalarIndent = Number(ch) - 1;
          else if (ch !== "-")
            break;
        }
        return yield* this.pushUntil((ch) => isEmpty(ch) || ch === "#");
      }
      *parseBlockScalar() {
        let nl = this.pos - 1;
        let indent = 0;
        let ch;
        loop: for (let i2 = this.pos; ch = this.buffer[i2]; ++i2) {
          switch (ch) {
            case " ":
              indent += 1;
              break;
            case "\n":
              nl = i2;
              indent = 0;
              break;
            case "\r": {
              const next = this.buffer[i2 + 1];
              if (!next && !this.atEnd)
                return this.setNext("block-scalar");
              if (next === "\n")
                break;
            }
            // fallthrough
            default:
              break loop;
          }
        }
        if (!ch && !this.atEnd)
          return this.setNext("block-scalar");
        if (indent >= this.indentNext) {
          if (this.blockScalarIndent === -1)
            this.indentNext = indent;
          else {
            this.indentNext = this.blockScalarIndent + (this.indentNext === 0 ? 1 : this.indentNext);
          }
          do {
            const cs = this.continueScalar(nl + 1);
            if (cs === -1)
              break;
            nl = this.buffer.indexOf("\n", cs);
          } while (nl !== -1);
          if (nl === -1) {
            if (!this.atEnd)
              return this.setNext("block-scalar");
            nl = this.buffer.length;
          }
        }
        let i = nl + 1;
        ch = this.buffer[i];
        while (ch === " ")
          ch = this.buffer[++i];
        if (ch === "	") {
          while (ch === "	" || ch === " " || ch === "\r" || ch === "\n")
            ch = this.buffer[++i];
          nl = i - 1;
        } else if (!this.blockScalarKeep) {
          do {
            let i2 = nl - 1;
            let ch2 = this.buffer[i2];
            if (ch2 === "\r")
              ch2 = this.buffer[--i2];
            const lastChar = i2;
            while (ch2 === " ")
              ch2 = this.buffer[--i2];
            if (ch2 === "\n" && i2 >= this.pos && i2 + 1 + indent > lastChar)
              nl = i2;
            else
              break;
          } while (true);
        }
        yield cst.SCALAR;
        yield* this.pushToIndex(nl + 1, true);
        return yield* this.parseLineStart();
      }
      *parsePlainScalar() {
        const inFlow = this.flowLevel > 0;
        let end = this.pos - 1;
        let i = this.pos - 1;
        let ch;
        while (ch = this.buffer[++i]) {
          if (ch === ":") {
            const next = this.buffer[i + 1];
            if (isEmpty(next) || inFlow && flowIndicatorChars.has(next))
              break;
            end = i;
          } else if (isEmpty(ch)) {
            let next = this.buffer[i + 1];
            if (ch === "\r") {
              if (next === "\n") {
                i += 1;
                ch = "\n";
                next = this.buffer[i + 1];
              } else
                end = i;
            }
            if (next === "#" || inFlow && flowIndicatorChars.has(next))
              break;
            if (ch === "\n") {
              const cs = this.continueScalar(i + 1);
              if (cs === -1)
                break;
              i = Math.max(i, cs - 2);
            }
          } else {
            if (inFlow && flowIndicatorChars.has(ch))
              break;
            end = i;
          }
        }
        if (!ch && !this.atEnd)
          return this.setNext("plain-scalar");
        yield cst.SCALAR;
        yield* this.pushToIndex(end + 1, true);
        return inFlow ? "flow" : "doc";
      }
      *pushCount(n) {
        if (n > 0) {
          yield this.buffer.substr(this.pos, n);
          this.pos += n;
          return n;
        }
        return 0;
      }
      *pushToIndex(i, allowEmpty) {
        const s = this.buffer.slice(this.pos, i);
        if (s) {
          yield s;
          this.pos += s.length;
          return s.length;
        } else if (allowEmpty)
          yield "";
        return 0;
      }
      *pushIndicators() {
        let n = 0;
        loop: while (true) {
          switch (this.charAt(0)) {
            case "!":
              n += yield* this.pushTag();
              n += yield* this.pushSpaces(true);
              continue loop;
            case "&":
              n += yield* this.pushUntil(isNotAnchorChar);
              n += yield* this.pushSpaces(true);
              continue loop;
            case "-":
            // this is an error
            case "?":
            // this is an error outside flow collections
            case ":": {
              const inFlow = this.flowLevel > 0;
              const ch1 = this.charAt(1);
              if (isEmpty(ch1) || inFlow && flowIndicatorChars.has(ch1)) {
                if (!inFlow)
                  this.indentNext = this.indentValue + 1;
                else if (this.flowKey)
                  this.flowKey = false;
                n += yield* this.pushCount(1);
                n += yield* this.pushSpaces(true);
                continue loop;
              }
            }
          }
          break loop;
        }
        return n;
      }
      *pushTag() {
        if (this.charAt(1) === "<") {
          let i = this.pos + 2;
          let ch = this.buffer[i];
          while (!isEmpty(ch) && ch !== ">")
            ch = this.buffer[++i];
          return yield* this.pushToIndex(ch === ">" ? i + 1 : i, false);
        } else {
          let i = this.pos + 1;
          let ch = this.buffer[i];
          while (ch) {
            if (tagChars.has(ch))
              ch = this.buffer[++i];
            else if (ch === "%" && hexDigits.has(this.buffer[i + 1]) && hexDigits.has(this.buffer[i + 2])) {
              ch = this.buffer[i += 3];
            } else
              break;
          }
          return yield* this.pushToIndex(i, false);
        }
      }
      *pushNewline() {
        const ch = this.buffer[this.pos];
        if (ch === "\n")
          return yield* this.pushCount(1);
        else if (ch === "\r" && this.charAt(1) === "\n")
          return yield* this.pushCount(2);
        else
          return 0;
      }
      *pushSpaces(allowTabs) {
        let i = this.pos - 1;
        let ch;
        do {
          ch = this.buffer[++i];
        } while (ch === " " || allowTabs && ch === "	");
        const n = i - this.pos;
        if (n > 0) {
          yield this.buffer.substr(this.pos, n);
          this.pos = i;
        }
        return n;
      }
      *pushUntil(test) {
        let i = this.pos;
        let ch = this.buffer[i];
        while (!test(ch))
          ch = this.buffer[++i];
        return yield* this.pushToIndex(i, false);
      }
    };
    exports.Lexer = Lexer;
  }
});

// ../../node_modules/yaml/dist/parse/line-counter.js
var require_line_counter = __commonJS({
  "../../node_modules/yaml/dist/parse/line-counter.js"(exports) {
    "use strict";
    var LineCounter = class {
      constructor() {
        this.lineStarts = [];
        this.addNewLine = (offset) => this.lineStarts.push(offset);
        this.linePos = (offset) => {
          let low = 0;
          let high = this.lineStarts.length;
          while (low < high) {
            const mid = low + high >> 1;
            if (this.lineStarts[mid] < offset)
              low = mid + 1;
            else
              high = mid;
          }
          if (this.lineStarts[low] === offset)
            return { line: low + 1, col: 1 };
          if (low === 0)
            return { line: 0, col: offset };
          const start = this.lineStarts[low - 1];
          return { line: low, col: offset - start + 1 };
        };
      }
    };
    exports.LineCounter = LineCounter;
  }
});

// ../../node_modules/yaml/dist/parse/parser.js
var require_parser = __commonJS({
  "../../node_modules/yaml/dist/parse/parser.js"(exports) {
    "use strict";
    var node_process = __require("process");
    var cst = require_cst();
    var lexer = require_lexer();
    function includesToken(list, type) {
      for (let i = 0; i < list.length; ++i)
        if (list[i].type === type)
          return true;
      return false;
    }
    function findNonEmptyIndex(list) {
      for (let i = 0; i < list.length; ++i) {
        switch (list[i].type) {
          case "space":
          case "comment":
          case "newline":
            break;
          default:
            return i;
        }
      }
      return -1;
    }
    function isFlowToken(token) {
      switch (token?.type) {
        case "alias":
        case "scalar":
        case "single-quoted-scalar":
        case "double-quoted-scalar":
        case "flow-collection":
          return true;
        default:
          return false;
      }
    }
    function getPrevProps(parent) {
      switch (parent.type) {
        case "document":
          return parent.start;
        case "block-map": {
          const it = parent.items[parent.items.length - 1];
          return it.sep ?? it.start;
        }
        case "block-seq":
          return parent.items[parent.items.length - 1].start;
        /* istanbul ignore next should not happen */
        default:
          return [];
      }
    }
    function getFirstKeyStartProps(prev) {
      if (prev.length === 0)
        return [];
      let i = prev.length;
      loop: while (--i >= 0) {
        switch (prev[i].type) {
          case "doc-start":
          case "explicit-key-ind":
          case "map-value-ind":
          case "seq-item-ind":
          case "newline":
            break loop;
        }
      }
      while (prev[++i]?.type === "space") {
      }
      return prev.splice(i, prev.length);
    }
    function arrayPushArray(target, source) {
      if (source.length < 1e5)
        Array.prototype.push.apply(target, source);
      else
        for (let i = 0; i < source.length; ++i)
          target.push(source[i]);
    }
    function fixFlowSeqItems(fc) {
      if (fc.start.type === "flow-seq-start") {
        for (const it of fc.items) {
          if (it.sep && !it.value && !includesToken(it.start, "explicit-key-ind") && !includesToken(it.sep, "map-value-ind")) {
            if (it.key)
              it.value = it.key;
            delete it.key;
            if (isFlowToken(it.value)) {
              if (it.value.end)
                arrayPushArray(it.value.end, it.sep);
              else
                it.value.end = it.sep;
            } else
              arrayPushArray(it.start, it.sep);
            delete it.sep;
          }
        }
      }
    }
    var Parser = class {
      /**
       * @param onNewLine - If defined, called separately with the start position of
       *   each new line (in `parse()`, including the start of input).
       */
      constructor(onNewLine) {
        this.atNewLine = true;
        this.atScalar = false;
        this.indent = 0;
        this.offset = 0;
        this.onKeyLine = false;
        this.stack = [];
        this.source = "";
        this.type = "";
        this.lexer = new lexer.Lexer();
        this.onNewLine = onNewLine;
      }
      /**
       * Parse `source` as a YAML stream.
       * If `incomplete`, a part of the last line may be left as a buffer for the next call.
       *
       * Errors are not thrown, but yielded as `{ type: 'error', message }` tokens.
       *
       * @returns A generator of tokens representing each directive, document, and other structure.
       */
      *parse(source, incomplete = false) {
        if (this.onNewLine && this.offset === 0)
          this.onNewLine(0);
        for (const lexeme of this.lexer.lex(source, incomplete))
          yield* this.next(lexeme);
        if (!incomplete)
          yield* this.end();
      }
      /**
       * Advance the parser by the `source` of one lexical token.
       */
      *next(source) {
        this.source = source;
        if (node_process.env.LOG_TOKENS)
          console.log("|", cst.prettyToken(source));
        if (this.atScalar) {
          this.atScalar = false;
          yield* this.step();
          this.offset += source.length;
          return;
        }
        const type = cst.tokenType(source);
        if (!type) {
          const message = `Not a YAML token: ${source}`;
          yield* this.pop({ type: "error", offset: this.offset, message, source });
          this.offset += source.length;
        } else if (type === "scalar") {
          this.atNewLine = false;
          this.atScalar = true;
          this.type = "scalar";
        } else {
          this.type = type;
          yield* this.step();
          switch (type) {
            case "newline":
              this.atNewLine = true;
              this.indent = 0;
              if (this.onNewLine)
                this.onNewLine(this.offset + source.length);
              break;
            case "space":
              if (this.atNewLine && source[0] === " ")
                this.indent += source.length;
              break;
            case "explicit-key-ind":
            case "map-value-ind":
            case "seq-item-ind":
              if (this.atNewLine)
                this.indent += source.length;
              break;
            case "doc-mode":
            case "flow-error-end":
              return;
            default:
              this.atNewLine = false;
          }
          this.offset += source.length;
        }
      }
      /** Call at end of input to push out any remaining constructions */
      *end() {
        while (this.stack.length > 0)
          yield* this.pop();
      }
      get sourceToken() {
        const st = {
          type: this.type,
          offset: this.offset,
          indent: this.indent,
          source: this.source
        };
        return st;
      }
      *step() {
        const top = this.peek(1);
        if (this.type === "doc-end" && top?.type !== "doc-end") {
          while (this.stack.length > 0)
            yield* this.pop();
          this.stack.push({
            type: "doc-end",
            offset: this.offset,
            source: this.source
          });
          return;
        }
        if (!top)
          return yield* this.stream();
        switch (top.type) {
          case "document":
            return yield* this.document(top);
          case "alias":
          case "scalar":
          case "single-quoted-scalar":
          case "double-quoted-scalar":
            return yield* this.scalar(top);
          case "block-scalar":
            return yield* this.blockScalar(top);
          case "block-map":
            return yield* this.blockMap(top);
          case "block-seq":
            return yield* this.blockSequence(top);
          case "flow-collection":
            return yield* this.flowCollection(top);
          case "doc-end":
            return yield* this.documentEnd(top);
        }
        yield* this.pop();
      }
      peek(n) {
        return this.stack[this.stack.length - n];
      }
      *pop(error) {
        const token = error ?? this.stack.pop();
        if (!token) {
          const message = "Tried to pop an empty stack";
          yield { type: "error", offset: this.offset, source: "", message };
        } else if (this.stack.length === 0) {
          yield token;
        } else {
          const top = this.peek(1);
          if (token.type === "block-scalar") {
            token.indent = "indent" in top ? top.indent : 0;
          } else if (token.type === "flow-collection" && top.type === "document") {
            token.indent = 0;
          }
          if (token.type === "flow-collection")
            fixFlowSeqItems(token);
          switch (top.type) {
            case "document":
              top.value = token;
              break;
            case "block-scalar":
              top.props.push(token);
              break;
            case "block-map": {
              const it = top.items[top.items.length - 1];
              if (it.value) {
                top.items.push({ start: [], key: token, sep: [] });
                this.onKeyLine = true;
                return;
              } else if (it.sep) {
                it.value = token;
              } else {
                Object.assign(it, { key: token, sep: [] });
                this.onKeyLine = !it.explicitKey;
                return;
              }
              break;
            }
            case "block-seq": {
              const it = top.items[top.items.length - 1];
              if (it.value)
                top.items.push({ start: [], value: token });
              else
                it.value = token;
              break;
            }
            case "flow-collection": {
              const it = top.items[top.items.length - 1];
              if (!it || it.value)
                top.items.push({ start: [], key: token, sep: [] });
              else if (it.sep)
                it.value = token;
              else
                Object.assign(it, { key: token, sep: [] });
              return;
            }
            /* istanbul ignore next should not happen */
            default:
              yield* this.pop();
              yield* this.pop(token);
          }
          if ((top.type === "document" || top.type === "block-map" || top.type === "block-seq") && (token.type === "block-map" || token.type === "block-seq")) {
            const last = token.items[token.items.length - 1];
            if (last && !last.sep && !last.value && last.start.length > 0 && findNonEmptyIndex(last.start) === -1 && (token.indent === 0 || last.start.every((st) => st.type !== "comment" || st.indent < token.indent))) {
              if (top.type === "document")
                top.end = last.start;
              else
                top.items.push({ start: last.start });
              token.items.splice(-1, 1);
            }
          }
        }
      }
      *stream() {
        switch (this.type) {
          case "directive-line":
            yield { type: "directive", offset: this.offset, source: this.source };
            return;
          case "byte-order-mark":
          case "space":
          case "comment":
          case "newline":
            yield this.sourceToken;
            return;
          case "doc-mode":
          case "doc-start": {
            const doc = {
              type: "document",
              offset: this.offset,
              start: []
            };
            if (this.type === "doc-start")
              doc.start.push(this.sourceToken);
            this.stack.push(doc);
            return;
          }
        }
        yield {
          type: "error",
          offset: this.offset,
          message: `Unexpected ${this.type} token in YAML stream`,
          source: this.source
        };
      }
      *document(doc) {
        if (doc.value)
          return yield* this.lineEnd(doc);
        switch (this.type) {
          case "doc-start": {
            if (findNonEmptyIndex(doc.start) !== -1) {
              yield* this.pop();
              yield* this.step();
            } else
              doc.start.push(this.sourceToken);
            return;
          }
          case "anchor":
          case "tag":
          case "space":
          case "comment":
          case "newline":
            doc.start.push(this.sourceToken);
            return;
        }
        const bv = this.startBlockValue(doc);
        if (bv)
          this.stack.push(bv);
        else {
          yield {
            type: "error",
            offset: this.offset,
            message: `Unexpected ${this.type} token in YAML document`,
            source: this.source
          };
        }
      }
      *scalar(scalar) {
        if (this.type === "map-value-ind") {
          const prev = getPrevProps(this.peek(2));
          const start = getFirstKeyStartProps(prev);
          let sep;
          if (scalar.end) {
            sep = scalar.end;
            sep.push(this.sourceToken);
            delete scalar.end;
          } else
            sep = [this.sourceToken];
          const map = {
            type: "block-map",
            offset: scalar.offset,
            indent: scalar.indent,
            items: [{ start, key: scalar, sep }]
          };
          this.onKeyLine = true;
          this.stack[this.stack.length - 1] = map;
        } else
          yield* this.lineEnd(scalar);
      }
      *blockScalar(scalar) {
        switch (this.type) {
          case "space":
          case "comment":
          case "newline":
            scalar.props.push(this.sourceToken);
            return;
          case "scalar":
            scalar.source = this.source;
            this.atNewLine = true;
            this.indent = 0;
            if (this.onNewLine) {
              let nl = this.source.indexOf("\n") + 1;
              while (nl !== 0) {
                this.onNewLine(this.offset + nl);
                nl = this.source.indexOf("\n", nl) + 1;
              }
            }
            yield* this.pop();
            break;
          /* istanbul ignore next should not happen */
          default:
            yield* this.pop();
            yield* this.step();
        }
      }
      *blockMap(map) {
        const it = map.items[map.items.length - 1];
        switch (this.type) {
          case "newline":
            this.onKeyLine = false;
            if (it.value) {
              const end = "end" in it.value ? it.value.end : void 0;
              const last = Array.isArray(end) ? end[end.length - 1] : void 0;
              if (last?.type === "comment")
                end?.push(this.sourceToken);
              else
                map.items.push({ start: [this.sourceToken] });
            } else if (it.sep) {
              it.sep.push(this.sourceToken);
            } else {
              it.start.push(this.sourceToken);
            }
            return;
          case "space":
          case "comment":
            if (it.value) {
              map.items.push({ start: [this.sourceToken] });
            } else if (it.sep) {
              it.sep.push(this.sourceToken);
            } else {
              if (this.atIndentedComment(it.start, map.indent)) {
                const prev = map.items[map.items.length - 2];
                const end = prev?.value?.end;
                if (Array.isArray(end)) {
                  arrayPushArray(end, it.start);
                  end.push(this.sourceToken);
                  map.items.pop();
                  return;
                }
              }
              it.start.push(this.sourceToken);
            }
            return;
        }
        if (this.indent >= map.indent) {
          const atMapIndent = !this.onKeyLine && this.indent === map.indent;
          const atNextItem = atMapIndent && (it.sep || it.explicitKey) && this.type !== "seq-item-ind";
          let start = [];
          if (atNextItem && it.sep && !it.value) {
            const nl = [];
            for (let i = 0; i < it.sep.length; ++i) {
              const st = it.sep[i];
              switch (st.type) {
                case "newline":
                  nl.push(i);
                  break;
                case "space":
                  break;
                case "comment":
                  if (st.indent > map.indent)
                    nl.length = 0;
                  break;
                default:
                  nl.length = 0;
              }
            }
            if (nl.length >= 2)
              start = it.sep.splice(nl[1]);
          }
          switch (this.type) {
            case "anchor":
            case "tag":
              if (atNextItem || it.value) {
                start.push(this.sourceToken);
                map.items.push({ start });
                this.onKeyLine = true;
              } else if (it.sep) {
                it.sep.push(this.sourceToken);
              } else {
                it.start.push(this.sourceToken);
              }
              return;
            case "explicit-key-ind":
              if (!it.sep && !it.explicitKey) {
                it.start.push(this.sourceToken);
                it.explicitKey = true;
              } else if (atNextItem || it.value) {
                start.push(this.sourceToken);
                map.items.push({ start, explicitKey: true });
              } else {
                this.stack.push({
                  type: "block-map",
                  offset: this.offset,
                  indent: this.indent,
                  items: [{ start: [this.sourceToken], explicitKey: true }]
                });
              }
              this.onKeyLine = true;
              return;
            case "map-value-ind":
              if (it.explicitKey) {
                if (!it.sep) {
                  if (includesToken(it.start, "newline")) {
                    Object.assign(it, { key: null, sep: [this.sourceToken] });
                  } else {
                    const start2 = getFirstKeyStartProps(it.start);
                    this.stack.push({
                      type: "block-map",
                      offset: this.offset,
                      indent: this.indent,
                      items: [{ start: start2, key: null, sep: [this.sourceToken] }]
                    });
                  }
                } else if (it.value) {
                  map.items.push({ start: [], key: null, sep: [this.sourceToken] });
                } else if (includesToken(it.sep, "map-value-ind")) {
                  this.stack.push({
                    type: "block-map",
                    offset: this.offset,
                    indent: this.indent,
                    items: [{ start, key: null, sep: [this.sourceToken] }]
                  });
                } else if (isFlowToken(it.key) && !includesToken(it.sep, "newline")) {
                  const start2 = getFirstKeyStartProps(it.start);
                  const key = it.key;
                  const sep = it.sep;
                  sep.push(this.sourceToken);
                  delete it.key;
                  delete it.sep;
                  this.stack.push({
                    type: "block-map",
                    offset: this.offset,
                    indent: this.indent,
                    items: [{ start: start2, key, sep }]
                  });
                } else if (start.length > 0) {
                  it.sep = it.sep.concat(start, this.sourceToken);
                } else {
                  it.sep.push(this.sourceToken);
                }
              } else {
                if (!it.sep) {
                  Object.assign(it, { key: null, sep: [this.sourceToken] });
                } else if (it.value || atNextItem) {
                  map.items.push({ start, key: null, sep: [this.sourceToken] });
                } else if (includesToken(it.sep, "map-value-ind")) {
                  this.stack.push({
                    type: "block-map",
                    offset: this.offset,
                    indent: this.indent,
                    items: [{ start: [], key: null, sep: [this.sourceToken] }]
                  });
                } else {
                  it.sep.push(this.sourceToken);
                }
              }
              this.onKeyLine = true;
              return;
            case "alias":
            case "scalar":
            case "single-quoted-scalar":
            case "double-quoted-scalar": {
              const fs = this.flowScalar(this.type);
              if (atNextItem || it.value) {
                map.items.push({ start, key: fs, sep: [] });
                this.onKeyLine = true;
              } else if (it.sep) {
                this.stack.push(fs);
              } else {
                Object.assign(it, { key: fs, sep: [] });
                this.onKeyLine = true;
              }
              return;
            }
            default: {
              const bv = this.startBlockValue(map);
              if (bv) {
                if (bv.type === "block-seq") {
                  if (!it.explicitKey && it.sep && !includesToken(it.sep, "newline")) {
                    yield* this.pop({
                      type: "error",
                      offset: this.offset,
                      message: "Unexpected block-seq-ind on same line with key",
                      source: this.source
                    });
                    return;
                  }
                } else if (atMapIndent) {
                  map.items.push({ start });
                }
                this.stack.push(bv);
                return;
              }
            }
          }
        }
        yield* this.pop();
        yield* this.step();
      }
      *blockSequence(seq) {
        const it = seq.items[seq.items.length - 1];
        switch (this.type) {
          case "newline":
            if (it.value) {
              const end = "end" in it.value ? it.value.end : void 0;
              const last = Array.isArray(end) ? end[end.length - 1] : void 0;
              if (last?.type === "comment")
                end?.push(this.sourceToken);
              else
                seq.items.push({ start: [this.sourceToken] });
            } else
              it.start.push(this.sourceToken);
            return;
          case "space":
          case "comment":
            if (it.value)
              seq.items.push({ start: [this.sourceToken] });
            else {
              if (this.atIndentedComment(it.start, seq.indent)) {
                const prev = seq.items[seq.items.length - 2];
                const end = prev?.value?.end;
                if (Array.isArray(end)) {
                  arrayPushArray(end, it.start);
                  end.push(this.sourceToken);
                  seq.items.pop();
                  return;
                }
              }
              it.start.push(this.sourceToken);
            }
            return;
          case "anchor":
          case "tag":
            if (it.value || this.indent <= seq.indent)
              break;
            it.start.push(this.sourceToken);
            return;
          case "seq-item-ind":
            if (this.indent !== seq.indent)
              break;
            if (it.value || includesToken(it.start, "seq-item-ind"))
              seq.items.push({ start: [this.sourceToken] });
            else
              it.start.push(this.sourceToken);
            return;
        }
        if (this.indent > seq.indent) {
          const bv = this.startBlockValue(seq);
          if (bv) {
            this.stack.push(bv);
            return;
          }
        }
        yield* this.pop();
        yield* this.step();
      }
      *flowCollection(fc) {
        const it = fc.items[fc.items.length - 1];
        if (this.type === "flow-error-end") {
          let top;
          do {
            yield* this.pop();
            top = this.peek(1);
          } while (top?.type === "flow-collection");
        } else if (fc.end.length === 0) {
          switch (this.type) {
            case "comma":
            case "explicit-key-ind":
              if (!it || it.sep)
                fc.items.push({ start: [this.sourceToken] });
              else
                it.start.push(this.sourceToken);
              return;
            case "map-value-ind":
              if (!it || it.value)
                fc.items.push({ start: [], key: null, sep: [this.sourceToken] });
              else if (it.sep)
                it.sep.push(this.sourceToken);
              else
                Object.assign(it, { key: null, sep: [this.sourceToken] });
              return;
            case "space":
            case "comment":
            case "newline":
            case "anchor":
            case "tag":
              if (!it || it.value)
                fc.items.push({ start: [this.sourceToken] });
              else if (it.sep)
                it.sep.push(this.sourceToken);
              else
                it.start.push(this.sourceToken);
              return;
            case "alias":
            case "scalar":
            case "single-quoted-scalar":
            case "double-quoted-scalar": {
              const fs = this.flowScalar(this.type);
              if (!it || it.value)
                fc.items.push({ start: [], key: fs, sep: [] });
              else if (it.sep)
                this.stack.push(fs);
              else
                Object.assign(it, { key: fs, sep: [] });
              return;
            }
            case "flow-map-end":
            case "flow-seq-end":
              fc.end.push(this.sourceToken);
              return;
          }
          const bv = this.startBlockValue(fc);
          if (bv)
            this.stack.push(bv);
          else {
            yield* this.pop();
            yield* this.step();
          }
        } else {
          const parent = this.peek(2);
          if (parent.type === "block-map" && (this.type === "map-value-ind" && parent.indent === fc.indent || this.type === "newline" && !parent.items[parent.items.length - 1].sep)) {
            yield* this.pop();
            yield* this.step();
          } else if (this.type === "map-value-ind" && parent.type !== "flow-collection") {
            const prev = getPrevProps(parent);
            const start = getFirstKeyStartProps(prev);
            fixFlowSeqItems(fc);
            const sep = fc.end.splice(1, fc.end.length);
            sep.push(this.sourceToken);
            const map = {
              type: "block-map",
              offset: fc.offset,
              indent: fc.indent,
              items: [{ start, key: fc, sep }]
            };
            this.onKeyLine = true;
            this.stack[this.stack.length - 1] = map;
          } else {
            yield* this.lineEnd(fc);
          }
        }
      }
      flowScalar(type) {
        if (this.onNewLine) {
          let nl = this.source.indexOf("\n") + 1;
          while (nl !== 0) {
            this.onNewLine(this.offset + nl);
            nl = this.source.indexOf("\n", nl) + 1;
          }
        }
        return {
          type,
          offset: this.offset,
          indent: this.indent,
          source: this.source
        };
      }
      startBlockValue(parent) {
        switch (this.type) {
          case "alias":
          case "scalar":
          case "single-quoted-scalar":
          case "double-quoted-scalar":
            return this.flowScalar(this.type);
          case "block-scalar-header":
            return {
              type: "block-scalar",
              offset: this.offset,
              indent: this.indent,
              props: [this.sourceToken],
              source: ""
            };
          case "flow-map-start":
          case "flow-seq-start":
            return {
              type: "flow-collection",
              offset: this.offset,
              indent: this.indent,
              start: this.sourceToken,
              items: [],
              end: []
            };
          case "seq-item-ind":
            return {
              type: "block-seq",
              offset: this.offset,
              indent: this.indent,
              items: [{ start: [this.sourceToken] }]
            };
          case "explicit-key-ind": {
            this.onKeyLine = true;
            const prev = getPrevProps(parent);
            const start = getFirstKeyStartProps(prev);
            start.push(this.sourceToken);
            return {
              type: "block-map",
              offset: this.offset,
              indent: this.indent,
              items: [{ start, explicitKey: true }]
            };
          }
          case "map-value-ind": {
            this.onKeyLine = true;
            const prev = getPrevProps(parent);
            const start = getFirstKeyStartProps(prev);
            return {
              type: "block-map",
              offset: this.offset,
              indent: this.indent,
              items: [{ start, key: null, sep: [this.sourceToken] }]
            };
          }
        }
        return null;
      }
      atIndentedComment(start, indent) {
        if (this.type !== "comment")
          return false;
        if (this.indent <= indent)
          return false;
        return start.every((st) => st.type === "newline" || st.type === "space");
      }
      *documentEnd(docEnd) {
        if (this.type !== "doc-mode") {
          if (docEnd.end)
            docEnd.end.push(this.sourceToken);
          else
            docEnd.end = [this.sourceToken];
          if (this.type === "newline")
            yield* this.pop();
        }
      }
      *lineEnd(token) {
        switch (this.type) {
          case "comma":
          case "doc-start":
          case "doc-end":
          case "flow-seq-end":
          case "flow-map-end":
          case "map-value-ind":
            yield* this.pop();
            yield* this.step();
            break;
          case "newline":
            this.onKeyLine = false;
          // fallthrough
          case "space":
          case "comment":
          default:
            if (token.end)
              token.end.push(this.sourceToken);
            else
              token.end = [this.sourceToken];
            if (this.type === "newline")
              yield* this.pop();
        }
      }
    };
    exports.Parser = Parser;
  }
});

// ../../node_modules/yaml/dist/public-api.js
var require_public_api = __commonJS({
  "../../node_modules/yaml/dist/public-api.js"(exports) {
    "use strict";
    var composer = require_composer();
    var Document = require_Document();
    var errors = require_errors();
    var log2 = require_log();
    var identity = require_identity();
    var lineCounter = require_line_counter();
    var parser = require_parser();
    function parseOptions(options) {
      const prettyErrors = options.prettyErrors !== false;
      const lineCounter$1 = options.lineCounter || prettyErrors && new lineCounter.LineCounter() || null;
      return { lineCounter: lineCounter$1, prettyErrors };
    }
    function parseAllDocuments2(source, options = {}) {
      const { lineCounter: lineCounter2, prettyErrors } = parseOptions(options);
      const parser$1 = new parser.Parser(lineCounter2?.addNewLine);
      const composer$1 = new composer.Composer(options);
      const docs = Array.from(composer$1.compose(parser$1.parse(source)));
      if (prettyErrors && lineCounter2)
        for (const doc of docs) {
          doc.errors.forEach(errors.prettifyError(source, lineCounter2));
          doc.warnings.forEach(errors.prettifyError(source, lineCounter2));
        }
      if (docs.length > 0)
        return docs;
      return Object.assign([], { empty: true }, composer$1.streamInfo());
    }
    function parseDocument(source, options = {}) {
      const { lineCounter: lineCounter2, prettyErrors } = parseOptions(options);
      const parser$1 = new parser.Parser(lineCounter2?.addNewLine);
      const composer$1 = new composer.Composer(options);
      let doc = null;
      for (const _doc of composer$1.compose(parser$1.parse(source), true, source.length)) {
        if (!doc)
          doc = _doc;
        else if (doc.options.logLevel !== "silent") {
          doc.errors.push(new errors.YAMLParseError(_doc.range.slice(0, 2), "MULTIPLE_DOCS", "Source contains multiple documents; please use YAML.parseAllDocuments()"));
          break;
        }
      }
      if (prettyErrors && lineCounter2) {
        doc.errors.forEach(errors.prettifyError(source, lineCounter2));
        doc.warnings.forEach(errors.prettifyError(source, lineCounter2));
      }
      return doc;
    }
    function parse(src, reviver, options) {
      let _reviver = void 0;
      if (typeof reviver === "function") {
        _reviver = reviver;
      } else if (options === void 0 && reviver && typeof reviver === "object") {
        options = reviver;
      }
      const doc = parseDocument(src, options);
      if (!doc)
        return null;
      doc.warnings.forEach((warning) => log2.warn(doc.options.logLevel, warning));
      if (doc.errors.length > 0) {
        if (doc.options.logLevel !== "silent")
          throw doc.errors[0];
        else
          doc.errors = [];
      }
      return doc.toJS(Object.assign({ reviver: _reviver }, options));
    }
    function stringify(value, replacer, options) {
      let _replacer = null;
      if (typeof replacer === "function" || Array.isArray(replacer)) {
        _replacer = replacer;
      } else if (options === void 0 && replacer) {
        options = replacer;
      }
      if (typeof options === "string")
        options = options.length;
      if (typeof options === "number") {
        const indent = Math.round(options);
        options = indent < 1 ? void 0 : indent > 8 ? { indent: 8 } : { indent };
      }
      if (value === void 0) {
        const { keepUndefined } = options ?? replacer ?? {};
        if (!keepUndefined)
          return void 0;
      }
      if (identity.isDocument(value) && !_replacer)
        return value.toString(options);
      return new Document.Document(value, _replacer, options).toString(options);
    }
    exports.parse = parse;
    exports.parseAllDocuments = parseAllDocuments2;
    exports.parseDocument = parseDocument;
    exports.stringify = stringify;
  }
});

// ../../node_modules/yaml/dist/index.js
var require_dist = __commonJS({
  "../../node_modules/yaml/dist/index.js"(exports) {
    "use strict";
    var composer = require_composer();
    var Document = require_Document();
    var Schema = require_Schema();
    var errors = require_errors();
    var Alias = require_Alias();
    var identity = require_identity();
    var Pair = require_Pair();
    var Scalar = require_Scalar();
    var YAMLMap = require_YAMLMap();
    var YAMLSeq = require_YAMLSeq();
    var cst = require_cst();
    var lexer = require_lexer();
    var lineCounter = require_line_counter();
    var parser = require_parser();
    var publicApi = require_public_api();
    var visit = require_visit();
    exports.Composer = composer.Composer;
    exports.Document = Document.Document;
    exports.Schema = Schema.Schema;
    exports.YAMLError = errors.YAMLError;
    exports.YAMLParseError = errors.YAMLParseError;
    exports.YAMLWarning = errors.YAMLWarning;
    exports.Alias = Alias.Alias;
    exports.isAlias = identity.isAlias;
    exports.isCollection = identity.isCollection;
    exports.isDocument = identity.isDocument;
    exports.isMap = identity.isMap;
    exports.isNode = identity.isNode;
    exports.isPair = identity.isPair;
    exports.isScalar = identity.isScalar;
    exports.isSeq = identity.isSeq;
    exports.Pair = Pair.Pair;
    exports.Scalar = Scalar.Scalar;
    exports.YAMLMap = YAMLMap.YAMLMap;
    exports.YAMLSeq = YAMLSeq.YAMLSeq;
    exports.CST = cst;
    exports.Lexer = lexer.Lexer;
    exports.LineCounter = lineCounter.LineCounter;
    exports.Parser = parser.Parser;
    exports.parse = publicApi.parse;
    exports.parseAllDocuments = publicApi.parseAllDocuments;
    exports.parseDocument = publicApi.parseDocument;
    exports.stringify = publicApi.stringify;
    exports.visit = visit.visit;
    exports.visitAsync = visit.visitAsync;
  }
});

// src/server.ts
import { createServer } from "node:http";
import { createReadStream, existsSync, statSync } from "node:fs";
import { extname, join, normalize, resolve } from "node:path";

// ../../packages/engine/src/search.ts
var STOP = new Set(
  "a an and are as at be but by can do does for from how i if in into is it its me my of on or so than that the their them then there these they this to was what when where which who why will with you your".split(
    " "
  )
);
function tokenize(text) {
  return text.toLowerCase().replace(/[`*_#>()[\]{}"',;:!?|=]/g, " ").split(/\s+/).map((t) => t.replace(/^[.-]+|[.-]+$/g, "")).filter((t) => t.length > 1 && !STOP.has(t)).flatMap((t) => t.includes("-") || t.includes("/") ? [t, ...t.split(/[-/]/).filter((p) => p.length > 1)] : [t]).map(stem);
}
function stem(t) {
  if (t.length > 4 && t.endsWith("ies")) return t.slice(0, -3) + "y";
  if (t.length > 3 && t.endsWith("es") && /(ss|x|ch|sh)es$/.test(t)) return t.slice(0, -2);
  if (t.length > 3 && t.endsWith("s") && !t.endsWith("ss") && !t.endsWith("us")) return t.slice(0, -1);
  return t;
}
var KIND_BOOST = {
  lesson: 1.3,
  section: 1,
  faq: 1,
  glossary: 1.2,
  comparison: 1.15,
  question: 0.8,
  lab: 0.9,
  flashcard: 0.85
};
var SearchIndex = class {
  docs = [];
  tf = [];
  titleTokens = [];
  len = [];
  df = /* @__PURE__ */ new Map();
  avgLen = 0;
  constructor(docs) {
    for (const d of docs) this.add(d);
    this.avgLen = this.len.reduce((a, b) => a + b, 0) / Math.max(1, this.len.length);
  }
  add(doc) {
    const tokens = tokenize(`${doc.title} ${doc.title} ${doc.text}`);
    const tf = /* @__PURE__ */ new Map();
    for (const t of tokens) tf.set(t, (tf.get(t) ?? 0) + 1);
    for (const t of tf.keys()) this.df.set(t, (this.df.get(t) ?? 0) + 1);
    this.docs.push(doc);
    this.tf.push(tf);
    this.titleTokens.push(new Set(tokenize(doc.title)));
    this.len.push(tokens.length);
  }
  get size() {
    return this.docs.length;
  }
  search(query, opts = {}) {
    const q = [...new Set(tokenize(query))];
    if (!q.length) return [];
    const N = this.docs.length;
    const k1 = 1.4;
    const b = 0.75;
    const hits = [];
    for (let i = 0; i < N; i++) {
      const doc = this.docs[i];
      if (opts.kinds && !opts.kinds.includes(doc.kind)) continue;
      const tf = this.tf[i];
      let score = 0;
      let matched = 0;
      for (const term of q) {
        const f = tf.get(term);
        if (!f) continue;
        matched++;
        const df = this.df.get(term) ?? 0;
        const idf = Math.log(1 + (N - df + 0.5) / (df + 0.5));
        score += idf * (f * (k1 + 1) / (f + k1 * (1 - b + b * this.len[i] / this.avgLen)));
        if (this.titleTokens[i].has(term)) score += idf * 0.6;
      }
      if (!score) continue;
      score *= KIND_BOOST[doc.kind] * (0.6 + 0.4 * matched / q.length);
      if (opts.boostLesson && doc.lessonId === opts.boostLesson) score *= 1.5;
      hits.push({ doc, score });
    }
    hits.sort((a, b2) => b2.score - a.score);
    return hits.slice(0, opts.limit ?? 10);
  }
};

// ../../packages/content/src/lessons/a.ts
var lessonsA = [
  // ───────────────────────────── Stage 0 · Foundations ─────────────────────────────
  {
    id: "linux-essentials",
    title: "Linux essentials for containers",
    stage: 0,
    order: 1,
    objectives: ["kf-containerization"],
    scope: "foundation",
    estMinutes: 20,
    summary: "A container is an ordinary Linux process wrapped in kernel namespaces (what it can see), cgroups (what it can use) and its own root filesystem. Signals decide how it stops.",
    what: `Containers are not a kernel feature of their own. They are a **combination of Linux kernel features** applied to a normal process:

- **Processes** \u2013 every running program has a PID, a parent, a user ID and open files. A container's main process is just a process on the host.
- **Namespaces** \u2013 give a process its own private *view* of a system resource: process IDs, network stack, mount points, hostname, IPC and users.
- **cgroups (control groups)** \u2013 limit and account for what a group of processes may *consume*: CPU time, memory, PIDs, I/O.
- **Root filesystem** \u2013 the process sees a directory tree (unpacked from an image) as its \`/\`, instead of the host's.
- **Signals** \u2013 asynchronous notifications like \`SIGTERM\` (please stop) and \`SIGKILL\` (stop now, cannot be caught) that the runtime and Kubernetes use to shut containers down.`,
    why: `Kubernetes settings map almost one-to-one onto these primitives. A memory **limit** becomes a cgroup memory limit; exceeding it gets the process killed by the kernel (\`OOMKilled\`). Pods sharing \`localhost\` works because the containers in a Pod share one **network namespace**. A graceful shutdown works only if your process handles \`SIGTERM\`.

When you debug a container you are debugging a Linux process. Knowing that removes most of the "magic".`,
    problem: `Before containers, running two applications on one server meant they shared everything: the same PID space, the same ports, the same \`/etc\`, the same library versions. One runaway process could eat all memory and take the neighbours down. The options were to buy another machine or run a full virtual machine per app.

Namespaces and cgroups solve this cheaply: each app gets an isolated view and a resource budget, while all apps still share one kernel.`,
    how: `What a runtime such as runc does when it starts a container, step by step:

- **Prepare the filesystem.** Image layers are stacked (usually with an overlay filesystem) into one directory that will become the container's root.
- **Create namespaces.** The runtime asks the kernel (via \`clone\`/\`unshare\`) for new PID, mount, network, UTS (hostname), IPC and optionally user namespaces. Inside the new PID namespace the first process sees itself as **PID 1**.
- **Place the process in a cgroup.** The runtime writes limits such as \`memory.max\` and \`cpu.max\` (cgroup v2) for that cgroup. The kernel enforces them: CPU over the limit is **throttled**; memory over the limit triggers the **OOM killer**.
- **Switch the root.** The process's root is changed to the prepared directory (\`pivot_root\`), so the host filesystem is invisible.
- **Drop privileges.** Linux capabilities are reduced, and seccomp/AppArmor/SELinux profiles may restrict system calls.
- **Exec the entrypoint.** The image's command replaces the runtime's setup code. From here on it is just your program.
- **Stop.** To stop it, the runtime sends \`SIGTERM\` to PID 1, waits, then sends \`SIGKILL\`. In Kubernetes the wait is the Pod's \`terminationGracePeriodSeconds\` (default 30).`,
    components: [
      { name: "Namespaces", description: "Isolate what a process can **see**: `pid`, `net`, `mnt`, `uts`, `ipc`, `user`, `cgroup` (and `time` on newer kernels)." },
      { name: "cgroups", description: "Limit and meter what a process can **use**: CPU, memory, PIDs, block I/O. Modern distributions use the unified cgroup v2 hierarchy." },
      { name: "Root filesystem / overlayfs", description: "Read-only image layers plus a thin writable layer, merged into one view that becomes the container's `/`." },
      { name: "PID 1", description: "The first process in a PID namespace. It receives signals from the runtime and must reap zombie children; the kernel does not apply default signal actions to it, so an unhandled `SIGTERM` is simply ignored." },
      { name: "Signals", description: "`SIGTERM` (15) asks for graceful shutdown and can be handled; `SIGKILL` (9) is enforced by the kernel and cannot be caught." },
      { name: "Capabilities & seccomp", description: "Split root privileges into small units (e.g. `NET_BIND_SERVICE`) and filter which syscalls are allowed." }
    ],
    misconceptions: [
      {
        myth: "A container has its own kernel.",
        reality: "All containers on a host share the **host kernel**. Only the view (namespaces) and budget (cgroups) differ. That is why a Linux container cannot run natively on a Windows kernel and why a kernel exploit affects every container on the node."
      },
      {
        myth: "A CPU limit kills the container when exceeded, just like memory.",
        reality: "CPU is **compressible**: exceeding the limit causes **throttling** (the process waits). Memory is **incompressible**: exceeding the limit causes the kernel OOM killer to terminate a process, which Kubernetes reports as `OOMKilled`."
      },
      {
        myth: 'root inside a container is harmless because it is "inside".',
        reality: "Without user namespaces, UID 0 in the container is UID 0 on the host, only constrained by capabilities, seccomp and the other layers. Escaping the namespace gives host root. That is why running as non-root is a security baseline."
      }
    ],
    example: {
      title: "See that a container is just a process",
      description: `On a Linux host with Docker (or any runtime), start a container and look at it from both sides. The same process has two PIDs: one inside its PID namespace and one on the host.`,
      language: "bash",
      code: `# start a long-running container
docker run -d --name demo --memory 64m busybox sleep 3600

# inside: the process believes it is PID 1
docker exec demo ps
# PID   USER     TIME  COMMAND
#     1 root      0:00 sleep 3600

# outside: the same sleep is an ordinary host process
ps -ef | grep "sleep 3600"

# compare namespaces of the host shell and the container process
HOSTPID=$(docker inspect -f '{{.State.Pid}}' demo)
sudo ls -l /proc/$HOSTPID/ns/      # net, pid, mnt ... differ from /proc/self/ns/

# graceful stop: SIGTERM, then SIGKILL after the timeout
docker stop -t 10 demo`
    },
    exercise: {
      prompt: `A Pod's container is configured with \`limits.memory: 128Mi\` and \`limits.cpu: 500m\`. Under load it uses 300m CPU and grows to 140Mi of memory. Describe what the kernel does for each resource, and what Kubernetes will report.`,
      solution: `CPU at 300m is under the 500m limit, so nothing happens. (Above 500m it would be throttled, never killed.)

Memory at 140Mi exceeds the 128Mi cgroup limit. The kernel's OOM killer terminates the process in that cgroup. The kubelet reports the container's last state as **Terminated** with reason \`OOMKilled\` (exit code 137 = 128 + signal 9), and the container is restarted according to the Pod's \`restartPolicy\`. Repeated failures produce \`CrashLoopBackOff\`.`
    },
    faq: [
      {
        q: "Why does my container take exactly 30 seconds to stop?",
        a: "Your process probably ignores `SIGTERM` (common when a shell script is PID 1 and does not forward signals). Kubernetes waits `terminationGracePeriodSeconds` (default 30) and then sends `SIGKILL`. Handle `SIGTERM` in the app, or use `exec` in the entrypoint script so the app itself becomes PID 1."
      },
      {
        q: "Do I need to memorize every namespace type for the KCNA?",
        a: "No. Know the concept: namespaces isolate what a process sees, cgroups limit what it uses, and containers share the host kernel. Recognizing `net` and `pid` namespaces helps explain why containers in a Pod share `localhost`."
      },
      {
        q: "Are Linux namespaces the same as Kubernetes namespaces?",
        a: "No. A Kubernetes Namespace is an API-level grouping of objects (names, RBAC, quotas). It has nothing to do with kernel namespaces, which isolate processes on one host."
      }
    ],
    keyTerms: ["process", "PID 1", "Linux namespace", "cgroup", "OOM killer", "SIGTERM", "SIGKILL", "capabilities"],
    deeper: `Exit code 137 means "killed by signal 9" (128 + 9); 143 means \`SIGTERM\` (128 + 15). Tiny init processes such as \`tini\` exist solely to forward signals and reap zombies when your app is not written to be PID 1. Kubernetes can also share a single PID namespace across a Pod's containers with \`shareProcessNamespace: true\`. User namespaces for Pods (\`hostUsers: false\`) map container root to an unprivileged host UID; check its feature state for your cluster version before relying on it.`,
    references: [
      { title: "namespaces(7) \u2013 Linux manual page", url: "https://man7.org/linux/man-pages/man7/namespaces.7.html" },
      { title: "cgroups(7) \u2013 Linux manual page", url: "https://man7.org/linux/man-pages/man7/cgroups.7.html" },
      { title: "Pod lifecycle \u2013 termination of Pods", url: "https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/" }
    ]
  },
  {
    id: "networking-fundamentals",
    title: "Networking fundamentals",
    stage: 0,
    order: 2,
    objectives: ["co-networking"],
    scope: "foundation",
    estMinutes: 25,
    summary: "IP addresses identify hosts, ports identify processes, TCP and UDP carry data, DNS turns names into addresses, NAT rewrites addresses at boundaries, and load balancers spread traffic across backends.",
    what: `Kubernetes networking is built from a handful of classic ideas:

- **IP address and CIDR** \u2013 \`10.244.1.17\` identifies an interface; \`10.244.0.0/16\` describes a range (the first 16 bits are the network part).
- **Port** \u2013 a 16-bit number (0\u201365535) that identifies which process on a host gets a connection. An endpoint is \`IP:port\`.
- **TCP vs UDP** \u2013 TCP is connection-oriented, ordered and retransmits lost data. UDP sends independent datagrams with no delivery guarantee but less overhead (DNS queries usually use UDP).
- **DNS** \u2013 a distributed directory mapping names to records: \`A\` (IPv4), \`AAAA\` (IPv6), \`CNAME\` (alias), \`SRV\` (service + port).
- **HTTP** \u2013 an application-layer (L7) request/response protocol with methods (\`GET\`, \`POST\`), paths, headers and status codes.
- **NAT** \u2013 rewriting source (SNAT) or destination (DNAT) addresses as packets cross a boundary.
- **Load balancing** \u2013 distributing connections or requests over several backends, at L4 (IP/port) or L7 (HTTP paths, headers).`,
    why: `Every Kubernetes networking object is one of these ideas wearing a new name. A **Service** is a stable virtual IP plus DNAT and L4 load balancing. **CoreDNS** is DNS. An **Ingress** or **Gateway** is an L7 HTTP load balancer. A **NodePort** is "open this port on every node". **NetworkPolicy** is a firewall on IPs and ports.

If you can trace a plain \`curl\` across a network, you can trace a request into a cluster.`,
    problem: `Applications need to find and talk to each other while the machines underneath change. Hard-coding \`192.168.1.20:8080\` breaks the moment that server is replaced. DNS gives stable names, load balancers give one entry point for many replicas, and NAT lets many private addresses share fewer public ones. Kubernetes leans on exactly these tools because its backends (Pods) are replaced constantly.`,
    how: `Trace what happens when you run \`curl http://shop.example.com/cart\`:

- **Resolve the name.** The client asks its configured resolver (see \`/etc/resolv.conf\`) for the \`A\` record of \`shop.example.com\`. The answer, say \`203.0.113.10\`, is cached for the record's TTL.
- **Pick a source port.** The OS picks an ephemeral source port, e.g. \`54012\`. The connection is identified by the 5-tuple: protocol, source IP, source port, destination IP, destination port (80).
- **Route the packet.** The host checks its routing table; the destination is not local, so the packet goes to the default gateway.
- **NAT at the edge.** A home or cloud router rewrites the private source IP to a public one (**SNAT**) and remembers the mapping so replies come back.
- **TCP handshake.** \`SYN\` \u2192 \`SYN-ACK\` \u2192 \`ACK\` establishes the connection.
- **Load balancer.** \`203.0.113.10\` is a load balancer. An L4 balancer picks a backend by IP/port and forwards the connection (often using **DNAT**). An L7 balancer terminates the connection, reads the HTTP request, and can route \`/cart\` to a different backend pool than \`/search\`.
- **HTTP exchange.** The backend receives \`GET /cart\`, returns \`200 OK\` (or \`404\`, \`503\`...), and the reply follows the NAT mappings back to the client.`,
    components: [
      { name: "IP & CIDR", description: "Addresses and ranges. Private ranges such as `10.0.0.0/8`, `172.16.0.0/12` and `192.168.0.0/16` are not routable on the internet." },
      { name: "Ports & sockets", description: "Ports below 1024 are privileged on Linux. Only one process can listen on a given IP:port at a time." },
      { name: "DNS resolver", description: "Turns names into records. Search domains in `/etc/resolv.conf` let short names like `db` expand to longer ones; Kubernetes uses this heavily." },
      { name: "NAT (SNAT/DNAT)", description: "Rewrites source or destination addresses. kube-proxy uses DNAT to send Service traffic to a Pod IP." },
      { name: "L4 vs L7 load balancer", description: "L4 sees only IPs, ports and protocol; L7 understands HTTP and can route by host, path or header." }
    ],
    misconceptions: [
      {
        myth: "DNS is only for websites on the internet.",
        reality: "Internal service discovery is DNS too. Inside Kubernetes, `my-svc.my-namespace.svc.cluster.local` is answered by the cluster DNS server (CoreDNS)."
      },
      {
        myth: 'UDP is "unreliable" so nothing important uses it.',
        reality: "UDP simply leaves reliability to the application. DNS, many VPNs, video streaming and HTTP/3 (QUIC) all run on UDP."
      },
      {
        myth: "A load balancer always understands HTTP.",
        reality: "Only L7 balancers do. An L4 balancer (like a Kubernetes Service of type `LoadBalancer` in most clouds) forwards TCP/UDP connections without looking at paths or headers."
      }
    ],
    example: {
      title: "Inspecting each layer from a shell",
      description: "These standard tools show the layers in order: name resolution, routing, and the HTTP exchange.",
      language: "bash",
      code: `# DNS: which IP does the name resolve to?
dig +short example.com A
nslookup example.com

# Routing: which interface and gateway would be used?
ip route get 1.1.1.1

# Listening sockets on this host (which process owns which port)
ss -tlnp

# HTTP: verbose output shows the TCP connect, request headers and status code
curl -v http://example.com/`
    },
    exercise: {
      prompt: `Three Pods run the same web app at \`10.244.1.5:8080\`, \`10.244.2.9:8080\` and \`10.244.3.4:8080\`. Clients should use one stable address and should not care when Pods are replaced. Using only the vocabulary of this lesson, describe the pieces you would need.`,
      solution: `- A **stable virtual IP** (and port) that clients connect to.
- A **DNS name** that resolves to that virtual IP, so clients use a name rather than an address.
- **DNAT + L4 load balancing** that rewrites each new connection's destination from the virtual IP to one of the healthy backend \`IP:8080\` endpoints.
- A way to **update the backend list** whenever Pods come and go.

That is exactly what a Kubernetes Service (ClusterIP), CoreDNS, kube-proxy and EndpointSlices provide together.`
    },
    faq: [
      {
        q: "What is the difference between a port and a protocol?",
        a: "The protocol (TCP or UDP) decides how data is carried; the port decides which process receives it. `53/UDP` and `53/TCP` are different sockets, which is why Kubernetes Service ports declare a `protocol` field (default TCP)."
      },
      {
        q: "Why does /etc/resolv.conf matter in Kubernetes?",
        a: "The kubelet writes a `resolv.conf` into each Pod pointing at the cluster DNS Service and adding search domains like `<namespace>.svc.cluster.local`. That is how a Pod can reach another Service by its short name."
      },
      {
        q: "Is NAT the same as a firewall?",
        a: "No. NAT rewrites addresses; a firewall allows or drops traffic. They often run on the same box (and both use Linux netfilter), but they are separate functions."
      }
    ],
    keyTerms: ["CIDR", "port", "TCP", "UDP", "DNS A record", "SNAT/DNAT", "L4 load balancer", "L7 load balancer"],
    deeper: `Linux implements NAT and packet filtering in the kernel's netfilter framework, programmed by \`iptables\` or the newer \`nftables\`. kube-proxy writes such rules to implement Services. Some CNI plugins (e.g. Cilium) replace this path with eBPF programs attached in the kernel, which avoids long rule chains in very large clusters.`,
    references: [
      { title: "Kubernetes \u2013 Services, Load Balancing, and Networking", url: "https://kubernetes.io/docs/concepts/services-networking/" },
      { title: "MDN \u2013 An overview of HTTP", url: "https://developer.mozilla.org/en-US/docs/Web/HTTP/Overview" }
    ]
  },
  {
    id: "virtualization-and-containers",
    title: "Virtual machines vs containers",
    stage: 0,
    order: 3,
    objectives: ["kf-containerization"],
    scope: "kcna",
    estMinutes: 15,
    summary: "A VM virtualizes hardware and runs its own kernel; a container virtualizes the operating system view and shares the host kernel. That one difference explains their size, speed and isolation trade-offs.",
    what: `Think of a building.

A **virtual machine** is a detached house: its own foundation, plumbing and walls. A **hypervisor** carves physical hardware into virtual hardware, and every VM boots a full **guest operating system with its own kernel**.

A **container** is an apartment in a block: private rooms and a front door, but shared foundation and plumbing. Containers share the **host kernel** and get isolation from kernel features (namespaces, cgroups), not from virtual hardware.

- **Type 1 hypervisor** \u2013 runs directly on hardware (e.g. KVM, Xen, ESXi, Hyper-V). Used by cloud providers.
- **Type 2 hypervisor** \u2013 runs as an application on a host OS (e.g. VirtualBox). Common on laptops.
- **Container runtime** \u2013 sets up namespaces, cgroups and the root filesystem and starts a process (e.g. containerd + runc).`,
    why: `The KCNA expects you to explain why the industry moved application packaging to containers and where VMs still fit. In practice they are combined: almost every managed Kubernetes cluster runs its **nodes as VMs**, and containers inside them. VMs give strong tenant isolation between customers; containers give fast, dense, portable packaging of apps.`,
    problem: `VMs solved "one app per physical server" waste, but each VM still carries a whole OS: gigabytes of disk, a boot sequence measured in tens of seconds, its own patching. Teams that wanted to deploy many small services dozens of times a day found that too heavy. They also suffered "works on my machine" bugs because the app's dependencies were not packaged with it.

Containers package the app with its userland dependencies, start in well under a second (no kernel to boot), and pack many workloads onto one host.`,
    how: `Compare how each one starts an nginx web server:

- **VM:** the hypervisor allocates virtual CPUs, RAM and disks \u2192 virtual firmware runs \u2192 the guest kernel boots \u2192 init system starts services \u2192 nginx starts. Isolation boundary: **virtual hardware**. A guest kernel bug stays inside the VM.
- **Container:** the runtime unpacks the image layers \u2192 creates namespaces and a cgroup \u2192 switches the root filesystem \u2192 execs \`nginx\` as a process on the host kernel. Isolation boundary: **kernel features**. A host kernel bug can affect every container.

Middle ground exists for untrusted workloads:

- **Sandboxed runtimes** such as **gVisor** (a user-space kernel that intercepts syscalls) and **Kata Containers** (each Pod in a lightweight VM) keep the container workflow but add a stronger boundary. Kubernetes selects them per Pod with a **RuntimeClass**.`,
    components: [
      { name: "Hypervisor", description: "Software that presents virtual hardware to guest OSes. Type 1 runs on bare metal; type 2 runs on top of a host OS." },
      { name: "Guest OS / kernel", description: "Each VM boots its own kernel, so VMs can run different OS families (Linux and Windows) side by side." },
      { name: "Container runtime", description: "Creates isolated processes on the shared host kernel; e.g. containerd or CRI-O with runc underneath." },
      { name: "Sandboxed runtime", description: "gVisor or Kata Containers: container interface, VM-like isolation, some performance cost." }
    ],
    misconceptions: [
      {
        myth: "Containers are just lightweight VMs.",
        reality: 'They are a different mechanism. A VM emulates hardware and boots a kernel; a container is an isolated **process** on an already-running kernel. That is why there is no "boot" when a container starts.'
      },
      {
        myth: "Kubernetes replaces virtual machines.",
        reality: "Kubernetes schedules containers onto **nodes**, and nodes are very often VMs. The layers are complementary."
      },
      {
        myth: "A Linux container image runs on any OS.",
        reality: "Because the kernel is shared, a Linux image needs a Linux kernel. Docker Desktop on macOS or Windows quietly runs a small Linux VM to provide one. Windows containers likewise need a Windows host."
      }
    ],
    example: {
      title: "Side-by-side comparison",
      description: "Typical, order-of-magnitude characteristics. Exact numbers vary by workload and platform.",
      language: "text",
      code: `                    Virtual machine            Container
Isolation boundary  virtual hardware           kernel namespaces + cgroups
Kernel              own guest kernel           shared host kernel
Typical size        gigabytes (full OS)        megabytes (app + userland libs)
Start time          seconds to minutes         milliseconds to seconds
Density per host    tens                       hundreds
Mixed OS families   yes (Linux + Windows)      no (must match host kernel)
Typical use         tenant isolation, nodes    packaging and running apps`
    },
    exercise: {
      prompt: `A SaaS company runs code uploaded by untrusted customers. They want container-style packaging and Kubernetes scheduling, but are worried that one customer could exploit a kernel bug to reach another customer's workload. What options does this lesson give them?`,
      solution: `- Run those Pods with a **sandboxed runtime** (gVisor or Kata Containers) selected through a **RuntimeClass**, adding a boundary beyond the shared kernel.
- Or give each customer **separate nodes (VMs)** or even separate clusters, so the hypervisor is the boundary between tenants.

Plain containers alone share the host kernel, so they are a weaker boundary for hostile multi-tenancy.`
    },
    faq: [
      {
        q: "If containers share the kernel, how can an Alpine container run on an Ubuntu host?",
        a: "Distributions differ in **userland** (libraries, package manager, shell), not in the kernel interface. The Alpine image brings its own userland files; it only borrows the Ubuntu host's Linux kernel."
      },
      {
        q: "Are containers secure enough for production?",
        a: "Yes for most workloads, when combined with good practices: non-root users, dropped capabilities, seccomp, read-only root filesystems and Pod Security Admission. For hostile multi-tenant code, add sandboxed runtimes or VM boundaries."
      },
      {
        q: "What is RuntimeClass on the exam?",
        a: "Know it exists: a Kubernetes object that lets a Pod choose which runtime configuration (for example a gVisor or Kata handler) the node should use, via `spec.runtimeClassName`."
      }
    ],
    keyTerms: ["hypervisor", "virtual machine", "guest kernel", "container", "shared kernel", "gVisor", "Kata Containers", "RuntimeClass"],
    deeper: `Hardware virtualization extensions (Intel VT-x, AMD-V) make type 1 hypervisors fast. MicroVM projects such as Firecracker shrink the VM to the essentials so it boots in a fraction of a second; serverless platforms use them to get VM isolation with near-container speed.`,
    references: [
      { title: "Kubernetes \u2013 Containers", url: "https://kubernetes.io/docs/concepts/containers/" },
      { title: "Kubernetes \u2013 Runtime Class", url: "https://kubernetes.io/docs/concepts/containers/runtime-class/" }
    ]
  },
  {
    id: "container-images-and-oci",
    title: "Container images, OCI and registries",
    stage: 0,
    order: 4,
    objectives: ["kf-containerization"],
    scope: "kcna",
    estMinutes: 25,
    summary: "An image is a stack of read-only filesystem layers plus a config, described by a manifest and addressed by content digests. The OCI specifications standardize image format, runtime behaviour and registry distribution so any compliant tool can build, push, pull and run it.",
    what: `A **container image** is a portable, read-only template for a container. Concretely it is:

- a set of **layers** \u2013 compressed tarballs, each holding the filesystem changes of one build step;
- an **image config** \u2013 JSON with the default command, environment, working directory, user and the ordered list of layer digests;
- a **manifest** \u2013 JSON that points to the config and the layers by **digest** (\`sha256:...\`). An **image index** can point to several manifests, one per platform (e.g. \`linux/amd64\`, \`linux/arm64\`).

**Docker** popularized this format and the \`Dockerfile\` build recipe. The **Open Container Initiative (OCI)**, a Linux Foundation project, now standardizes it in three specs:

- **Image spec** \u2013 the manifest, config and layer formats.
- **Runtime spec** \u2013 how to run an unpacked "bundle" (filesystem + \`config.json\`); \`runc\` is the reference implementation.
- **Distribution spec** \u2013 the HTTP API registries use for push and pull.`,
    why: `Kubernetes never builds images; it only **pulls** them by reference and asks a runtime to run them. Because of OCI, an image built with Docker, Buildah, kaniko or BuildKit runs on containerd or CRI-O and can live in any compliant registry (Docker Hub, GHCR, Harbor, cloud registries). That is also why removing dockershim in Kubernetes 1.24 did **not** break Docker-built images.

Tags vs digests is a frequent exam and production topic: it decides whether a rollout is reproducible.`,
    problem: `"It works on my machine" usually means the machine had a library, a config file or a runtime version the server did not. Images freeze the userland into an artifact you can version and ship. Layering then fixes the next problem: shipping a 500 MB file for every one-line change would be wasteful, so only changed layers are rebuilt, pushed and pulled.`,
    how: `Trace a build and a pull:

- **Build.** Each filesystem-changing Dockerfile instruction (\`FROM\`, \`COPY\`, \`RUN\`, \`ADD\`) produces a layer. Metadata instructions (\`CMD\`, \`ENV\`, \`EXPOSE\`, \`USER\`) only change the config.
- **Cache.** If an instruction and its inputs are unchanged, the builder reuses the cached layer. A change invalidates that layer **and every layer after it** \u2013 so put rarely-changing steps (installing dependencies) before frequently-changing ones (copying source).
- **Hash.** Every layer and the config get a SHA-256 **digest** of their content. The manifest lists these digests; the manifest's own digest identifies the whole image.
- **Push.** The client uploads blobs the registry does not already have, then uploads the manifest under a **tag** such as \`v1.4.2\`.
- **Pull.** The node resolves the tag to a manifest digest, downloads only missing layers, and verifies every blob against its digest.
- **Run.** The runtime stacks the read-only layers with overlayfs and adds a thin **writable container layer** on top. Files written there disappear with the container.`,
    components: [
      { name: "Layer", description: "Read-only, content-addressed tarball of filesystem changes. Shared between images that use the same base." },
      { name: "Manifest / image index", description: `Manifest lists config + layers for one platform; an index (multi-arch "manifest list") picks the right manifest for the node's OS/CPU.` },
      { name: "Tag", description: "Human-friendly, **mutable** pointer like `nginx:1.27` or `latest`. Can be moved to a different image at any time." },
      { name: "Digest", description: "**Immutable** content hash like `nginx@sha256:...`. The same digest always means exactly the same bytes." },
      { name: "Registry", description: "Server implementing the OCI distribution API, organized into repositories. Public or private (credentials via `imagePullSecrets`)." },
      { name: "OCI runtime (runc)", description: "Low-level runtime that takes an unpacked bundle and creates the container process with namespaces and cgroups." }
    ],
    misconceptions: [
      {
        myth: "Kubernetes needs Docker installed on every node.",
        reality: "Since 1.24 the kubelet talks only to CRI runtimes such as **containerd** or **CRI-O**. Docker-built images are OCI images, so they still run unchanged."
      },
      {
        myth: "The tag `latest` means the newest version.",
        reality: "`latest` is just the default tag name when none is given. It points wherever someone last pushed it. In Kubernetes, `:latest` (or no tag) also makes the default `imagePullPolicy` `Always`."
      },
      {
        myth: "Deleting a file in a later Dockerfile step makes the image smaller.",
        reality: 'Earlier layers are immutable; the deletion is only a "whiteout" marker in a new layer. The bytes still ship. Clean up in the **same** `RUN` step, or use a multi-stage build.'
      }
    ],
    example: {
      title: "A cache-friendly, multi-stage Dockerfile",
      description: `Dependencies are copied and installed before the source code, so a code-only change reuses the dependency layer. The final stage copies only the built binary into a small base, leaving compilers behind.`,
      language: "text",
      code: `# ---- build stage ----
FROM golang:1.23 AS build
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download            # cached until go.mod/go.sum change
COPY . .
RUN CGO_ENABLED=0 go build -o /out/app ./cmd/app

# ---- runtime stage ----
FROM gcr.io/distroless/static:nonroot
COPY --from=build /out/app /app
USER nonroot
ENTRYPOINT ["/app"]

# Build, tag and push; then deploy by digest for reproducibility:
#   docker build -t registry.example.com/shop/app:1.4.2 .
#   docker push registry.example.com/shop/app:1.4.2
#   image: registry.example.com/shop/app@sha256:<digest printed by push>`
    },
    exercise: {
      prompt: `Your Deployment uses \`image: shop/api:prod\`. Someone re-pushes the \`prod\` tag with a broken build. Two nodes already have the old image cached; a third node pulls fresh. Explain what happens and how to prevent it.`,
      solution: `With an explicit non-\`latest\` tag, the default \`imagePullPolicy\` is \`IfNotPresent\`. The two nodes reuse their cached (old) image; the new node pulls the moved tag and gets the broken build. The same Deployment now runs **two different images**.

Prevent it by deploying **immutable references**: a unique tag per build (e.g. a version or commit SHA) that is never re-pushed, or better, pin the **digest** (\`shop/api@sha256:...\`). Many registries can also enforce tag immutability.`
    },
    faq: [
      {
        q: "Is a Dockerfile part of the OCI standard?",
        a: "No. OCI standardizes the **resulting** image, the runtime bundle and the registry API. The Dockerfile is just one popular build recipe; Buildpacks or other tools can produce OCI images without one."
      },
      {
        q: "What is the difference between containerd and runc?",
        a: "**containerd** is a high-level runtime: it pulls images, manages storage and snapshots, and exposes the CRI to the kubelet. **runc** is the low-level OCI runtime that containerd invokes to actually create each container process."
      },
      {
        q: "How does a node pull from a private registry?",
        a: "Create a Secret of type `kubernetes.io/dockerconfigjson` and reference it in the Pod's `imagePullSecrets` (directly or through the ServiceAccount). Some clouds also provide node-level credential plugins."
      }
    ],
    keyTerms: ["image layer", "manifest", "digest", "tag", "registry", "OCI image spec", "OCI runtime spec", "OCI distribution spec"],
    deeper: `Because OCI registries store arbitrary content-addressed blobs, they now hold more than images: Helm charts, signatures and SBOMs (OCI "artifacts" and the \`subject\`/referrers mechanism). Supply-chain tools such as Sigstore cosign attach signatures to an image digest this way, so a signature can never silently follow a moved tag.`,
    references: [
      { title: "Open Container Initiative", url: "https://opencontainers.org/" },
      { title: "Kubernetes \u2013 Images", url: "https://kubernetes.io/docs/concepts/containers/images/" },
      { title: "Kubernetes \u2013 Container Runtime Interface", url: "https://kubernetes.io/docs/concepts/architecture/cri/" }
    ],
    diagram: "container-layers"
  },
  {
    id: "yaml-for-kubernetes",
    title: "YAML for Kubernetes manifests",
    stage: 0,
    order: 5,
    objectives: ["kf-core"],
    scope: "foundation",
    estMinutes: 20,
    summary: "YAML expresses maps, lists and scalars through indentation. Every Kubernetes manifest uses the same top-level shape: apiVersion, kind, metadata, spec \u2013 and the cluster writes back status.",
    what: `**YAML** is a human-friendly data format (a superset of JSON). Kubernetes reads it, converts it to JSON, and sends it to the API server. You only need three building blocks:

- **Mapping** (key: value) \u2013 \`name: web\`
- **Sequence** (list) \u2013 items start with \`- \`
- **Scalar** \u2013 strings, numbers, booleans, null

Indentation with **spaces** (never tabs) shows nesting. \`#\` starts a comment. \`---\` separates multiple documents in one file.

Every Kubernetes object has the same skeleton:

- \`apiVersion\` \u2013 API group and version, e.g. \`v1\` (core group) or \`apps/v1\`
- \`kind\` \u2013 the type, e.g. \`Pod\`, \`Deployment\`
- \`metadata\` \u2013 \`name\`, \`namespace\`, \`labels\`, \`annotations\`
- \`spec\` \u2013 the **desired state** you write
- \`status\` \u2013 the **observed state** the cluster writes; you do not author it`,
    why: `Declarative Kubernetes is "write YAML, apply it". Most beginner errors are YAML errors, not Kubernetes errors: wrong indentation turns a field into a sibling of the field it belonged to, a missing \`-\` turns a list into a map, and an unquoted value becomes the wrong type. Reading YAML fluently is a prerequisite for every later lesson and for the exam's manifest-reading questions.`,
    problem: `Raw JSON is noisy to read and cannot hold comments; ad-hoc command flags cannot be reviewed or versioned. YAML gives a readable, diffable text form for API objects that can live in Git. The cost is that whitespace and typing rules are strict and sometimes surprising.`,
    how: `Read any manifest in this order:

- **Find the type.** \`apiVersion\` + \`kind\` tell you which schema applies. \`kubectl explain <kind>.<field>\` shows that schema.
- **Find the identity.** \`metadata.name\` (+ \`namespace\`) identifies the object; labels are for selection, annotations for extra notes.
- **Walk the spec by indentation.** Children are indented further than their parent. Items at the same indentation are siblings.
- **Spot lists.** A \`- \` begins a new list item; every key indented under it belongs to that item. \`containers:\` is always a list, even with one container.
- **Check scalar types.** \`8080\` is a number, \`"8080"\` a string, \`true\` a boolean. Fields typed as strings (like env \`value\`) need quotes around numbers or booleans.
- **Submit.** \`kubectl apply -f file.yaml\` parses the YAML, validates it against the schema on the server, and stores it.`,
    components: [
      { name: "apiVersion", description: "`<group>/<version>` such as `apps/v1`, or just `v1` for the core group (Pods, Services, ConfigMaps)." },
      { name: "kind", description: "Object type, CamelCase: `Pod`, `Deployment`, `Service`." },
      { name: "metadata", description: "Identity and tags: `name`, `namespace`, `labels`, `annotations`. The server adds `uid`, `resourceVersion`, `creationTimestamp`." },
      { name: "spec", description: "Desired state; structure depends on `kind`." },
      { name: "status", description: "Observed state written by controllers and the kubelet. Ignored if you include it in `apply`." }
    ],
    misconceptions: [
      {
        myth: "Tabs and spaces are interchangeable in YAML.",
        reality: "Tabs are **not allowed** for indentation. Use spaces (2 per level is the Kubernetes convention)."
      },
      {
        myth: "Every value is a string, so quoting does not matter.",
        reality: 'YAML infers types. `value: 8080` in an env var is a number and the API rejects it because the field must be a string; write `value: "8080"`. Words like `yes`, `no`, `on`, `true` can also be read as booleans.'
      },
      {
        myth: "You should copy the `status` section when saving a manifest.",
        reality: "`status` is owned by the cluster. Strip it (and server fields like `uid`, `resourceVersion`) from manifests you keep in Git."
      }
    ],
    example: {
      title: "Spot the three bugs",
      description: `This Pod manifest is broken in three ways: the \`env\` value is an unquoted number, \`image\` is indented as a sibling of \`containers\` instead of inside the list item, and \`ports\` is a map where a list is required. The corrected version follows.`,
      language: "yaml",
      code: `# BROKEN
apiVersion: v1
kind: Pod
metadata:
  name: web
spec:
  containers:
  - name: web
  image: nginx:1.27          # wrong level: belongs to the container item
    ports:
      containerPort: 80      # must be a list item
    env:
    - name: PORT
      value: 8080            # must be a string
---
# FIXED
apiVersion: v1
kind: Pod
metadata:
  name: web
  labels:
    app: web
spec:
  containers:
  - name: web
    image: nginx:1.27
    ports:
    - containerPort: 80
    env:
    - name: PORT
      value: "8080"`
    },
    exercise: {
      prompt: `Without running anything, answer: in the FIXED manifest above, (1) how many containers are defined, (2) what is the full field path to the container port, and (3) which API group does \`v1\` refer to?`,
      solution: `(1) One container \u2013 \`containers\` is a list with a single \`- name: web\` item.

(2) \`spec.containers[0].ports[0].containerPort\`.

(3) The **core** (legacy) API group, which has no group name \u2013 hence just \`v1\` rather than \`<group>/v1\`.`
    },
    faq: [
      {
        q: "How do I find which fields a kind supports?",
        a: "Use `kubectl explain`, e.g. `kubectl explain pod.spec.containers` or add `--recursive` for the whole tree. It reads the schema from your cluster, so it matches your version."
      },
      {
        q: "Can I write manifests in JSON instead?",
        a: "Yes. kubectl accepts JSON, and `kubectl get <resource> <name> -o json` prints objects that way. YAML is the convention because it is easier to read and comment."
      },
      {
        q: "Where do apiVersion values like apps/v1 come from?",
        a: "From the API groups your cluster serves. `kubectl api-resources` lists each resource with its group/version and whether it is namespaced."
      }
    ],
    keyTerms: ["mapping", "sequence", "scalar", "apiVersion", "kind", "metadata", "spec", "status"],
    deeper: `Kubernetes converts YAML to JSON before validation, so anything YAML can express beyond JSON (anchors \`&\`/\`*\`, merge keys) is resolved client-side and never reaches the API server. Block scalars \`|\` (keep newlines) and \`>\` (fold lines) are handy for embedding scripts or config files in ConfigMaps.`,
    references: [
      { title: "Kubernetes \u2013 Objects in Kubernetes", url: "https://kubernetes.io/docs/concepts/overview/working-with-objects/" },
      { title: "YAML 1.2.2 specification", url: "https://yaml.org/spec/1.2.2/" },
      { title: "kubectl reference", url: "https://kubernetes.io/docs/reference/kubectl/" }
    ]
  },
  {
    id: "distributed-systems-basics",
    title: "Distributed systems basics",
    stage: 0,
    order: 6,
    objectives: ["cna-ecosystem"],
    scope: "foundation",
    estMinutes: 20,
    summary: "In a distributed system, networks drop messages and machines die. Kubernetes copes with consensus (Raft in etcd), idempotent operations, retries, and eventual consistency driven by control loops.",
    what: `A **distributed system** is several computers cooperating over a network so that they appear as one service. Four ideas carry most of the weight:

- **Partial failure** \u2013 some parts fail while others keep running; a slow node and a dead node can look identical.
- **Consensus** \u2013 getting a group of machines to agree on one value (or one ordered log) despite failures. **Raft** does this with an elected leader and a **majority quorum**.
- **Idempotency** \u2013 an operation that has the same effect whether it is applied once or many times ("set replicas to 3" vs "add 1 replica"). Idempotent operations make retries safe.
- **Eventual consistency** \u2013 the system may be temporarily out of sync but converges to the correct state if no new changes arrive.`,
    why: `A Kubernetes cluster *is* a distributed system. etcd uses Raft, so you must run an odd number of members and keep a majority alive. Controllers converge **eventually** \u2013 a new Deployment is not "done" when \`kubectl apply\` returns. Rolling updates, retries and self-healing only work because operations are expressed as idempotent desired state. These ideas explain dozens of exam answers that otherwise look arbitrary.`,
    problem: `Three short failure stories:

- **The double charge.** A payment request times out; the client retries; both requests actually succeeded. The fix: an **idempotency key** so the second request is recognized and ignored.
- **The split brain.** A network splits two database servers; each thinks the other is dead and both accept writes. The fix: require a **majority quorum** \u2013 at most one side can have a majority, so only it may write.
- **The stale read.** A cache still shows a deleted item for a few seconds. Often acceptable \u2013 that is **eventual consistency** \u2013 as long as the system converges.`,
    how: `How Raft (used by etcd) keeps one consistent log:

- **Roles.** Each member is a **follower**, **candidate** or **leader**. Normally there is exactly one leader.
- **Election.** If a follower hears no heartbeat within a randomized timeout, it becomes a candidate, increments the **term**, and asks for votes. A candidate with votes from a **majority** becomes leader.
- **Replication.** All writes go to the leader, which appends them to its log and sends them to followers.
- **Commit.** Once a **majority** has stored the entry, it is committed and applied; the client gets success.
- **Fault tolerance.** With *n* members, quorum is \u230An/2\u230B+1. Three members tolerate one failure; five tolerate two. Four members still tolerate only one, which is why odd sizes are recommended.
- **Losing quorum.** If a majority is unreachable, the cluster refuses writes rather than risk divergence \u2013 it chooses **consistency over availability** during the partition (the CAP trade-off).`,
    components: [
      { name: "Raft leader", description: "Single member that orders all writes; re-elected automatically if it fails." },
      { name: "Quorum", description: "A majority of members, \u230An/2\u230B+1. Needed both to elect a leader and to commit a write." },
      { name: "Idempotent operation", description: 'Safe to repeat. Declarative "make it look like this" requests are naturally idempotent.' },
      { name: "Optimistic concurrency", description: "Writers include the version they read; the write fails if someone changed it meanwhile. Kubernetes uses `metadata.resourceVersion` for this." },
      { name: "Eventual consistency", description: "Components converge to the desired state over time instead of all at once." }
    ],
    misconceptions: [
      {
        myth: "More etcd members always means more resilience.",
        reality: "Fault tolerance only increases at odd sizes (3 \u2192 1 failure, 5 \u2192 2). Every extra member also adds replication latency to every write. 3 or 5 is typical."
      },
      {
        myth: "If an API call succeeded, the change is already in effect everywhere.",
        reality: "A successful `kubectl apply` means the desired state was **stored in etcd**. Scheduling, image pulls and container starts happen afterwards, asynchronously."
      },
      {
        myth: "Retries are always safe.",
        reality: 'Only for **idempotent** operations. Retrying a non-idempotent "increment" or "charge" can apply it twice.'
      }
    ],
    example: {
      title: "Optimistic concurrency in Kubernetes",
      description: `Every object carries a \`resourceVersion\`. If two clients read version 4812 and both try to update, the first update wins and the second gets an HTTP **409 Conflict**; it must re-read and retry. Nothing is locked, and no update is silently lost.`,
      language: "bash",
      code: `kubectl get deployment web -o jsonpath='{.metadata.resourceVersion}'
# 4812

# client A and client B both edit based on 4812
# A's update is accepted -> resourceVersion becomes 4830
# B's update still claims 4812 -> rejected:
#   Error from server (Conflict): Operation cannot be fulfilled on
#   deployments.apps "web": the object has been modified;
#   please apply your changes to the latest version and try again`
    },
    exercise: {
      prompt: `An etcd cluster has 5 members spread across 3 zones as 2 + 2 + 1. Zone A (2 members) goes offline. Can the cluster still accept writes? What if zone B also fails?`,
      solution: `Quorum for 5 members is 3. After zone A fails, 3 members remain (zone B: 2, zone C: 1) \u2013 still a majority, so the cluster elects a leader if needed and keeps accepting writes.

If zone B also fails, only 1 member remains. It cannot form a majority, so the cluster **stops accepting writes** (reads of possibly-stale data aside) until quorum is restored. Running Pods keep running \u2013 the kubelets just cannot get new instructions.`
    },
    faq: [
      {
        q: "What is the difference between level-triggered and edge-triggered?",
        a: 'Edge-triggered logic reacts to **events** ("a Pod was deleted"); if an event is missed, the system is wrong forever. Level-triggered logic looks at the **current state** each time ("are there 3 Pods?"). Kubernetes controllers are level-triggered, which makes them robust to missed events and restarts.'
      },
      {
        q: "Does the KCNA test the Raft algorithm in detail?",
        a: "No. Know that etcd uses Raft-based consensus, needs a majority quorum, and is usually run with an odd number of members (3 or 5)."
      },
      {
        q: 'Is Kubernetes "eventually consistent" in its storage?',
        a: "etcd itself is strongly consistent (linearizable writes via Raft). The **cluster as a whole** \u2013 Pods, endpoints, DNS \u2013 is eventually consistent, because many independent controllers converge the actual state towards the stored desired state."
      }
    ],
    keyTerms: ["partial failure", "consensus", "Raft", "quorum", "idempotency", "eventual consistency", "CAP theorem", "resourceVersion"],
    deeper: `The CAP theorem says that during a network partition a system must choose between consistency and availability. etcd chooses consistency (a minority partition rejects writes). Many caches and DNS systems choose availability and accept stale answers. The "fallacies of distributed computing" (the network is reliable, latency is zero, ...) are a useful checklist when designing cloud-native services.`,
    references: [
      { title: "The Raft consensus algorithm", url: "https://raft.github.io/" },
      { title: "etcd documentation", url: "https://etcd.io/docs/" },
      { title: "Kubernetes \u2013 Controllers", url: "https://kubernetes.io/docs/concepts/architecture/controller/" }
    ]
  },
  // ───────────────────────────── Stage 1 · Architecture ─────────────────────────────
  {
    id: "cluster-architecture",
    title: "Cluster architecture: control plane and nodes",
    stage: 1,
    order: 1,
    objectives: ["kf-core"],
    scope: "kcna",
    estMinutes: 20,
    summary: "A Kubernetes cluster is a control plane that stores and decides, plus worker nodes that run containers. Every component talks through the API server; only the API server talks to etcd.",
    what: `A **cluster** has two halves.

The **control plane** is the brain. It stores the desired state and makes decisions:

- **kube-apiserver** \u2013 the front door; every read and write goes through it.
- **etcd** \u2013 consistent key-value store holding all cluster data.
- **kube-scheduler** \u2013 picks a node for each new Pod.
- **kube-controller-manager** \u2013 runs the built-in control loops (Deployments, ReplicaSets, Nodes, Jobs...).
- **cloud-controller-manager** \u2013 optional; integrates with a cloud provider (load balancers, node lifecycle, routes).

**Worker nodes** are the muscle. Each one runs:

- **kubelet** \u2013 the node agent that makes the containers for its Pods actually run.
- **container runtime** \u2013 containerd or CRI-O, behind the CRI.
- **kube-proxy** \u2013 programs node networking for Services (optional with some CNI plugins).

Cluster **add-ons** such as CoreDNS and a CNI network plugin run on top, usually as Pods themselves.`,
    why: `The KCNA's largest domain starts here: you will be asked which component does what, which component stores state, and what happens when one fails. The picture also explains the design principle that runs through all of Kubernetes: components are **decoupled** and communicate only through the API, so each can be replaced, scaled or restarted independently.`,
    problem: `Running containers by hand on many servers raises questions no single machine can answer: which server has room? What happens when a server dies at 3 a.m.? Who notices that only 2 of 3 copies are running? Kubernetes centralizes the **record of what should exist** and distributes the **work of making it so** to small, specialized components and node agents.`,
    how: `Think of it as a company:

- **etcd** is the filing cabinet: the only place the truth is written down.
- **kube-apiserver** is the front desk. Nobody opens the cabinet directly; everyone files and reads through the desk, which checks identity and permissions.
- **Controllers** are department managers who keep reading the files and issuing work orders: "the Deployment wants 3 Pods, I see 2, file one more Pod".
- **kube-scheduler** is the dispatcher who assigns each new Pod to a node by writing the node's name onto it.
- **kubelets** are site supervisors on each node. Each watches the front desk for Pods assigned to its node, gets them running through the container runtime, and reports status back.
- **kube-proxy** on each node maintains the routing so traffic for a Service reaches one of its Pods.

Important consequences:

- **Hub and spoke.** Components do not call each other; they all **watch** the API server. Only the API server talks to etcd.
- **Running Pods survive control-plane outages.** If the control plane is down, existing containers keep running; you just cannot change anything, and failed Pods are not replaced.
- **High availability** means running several API servers behind a load balancer, an odd number of etcd members, and leader election for the scheduler and controller manager (one active instance each).`,
    components: [
      { name: "kube-apiserver", description: "REST front end and the only component that reads/writes etcd. Horizontally scalable." },
      { name: "etcd", description: "Raft-replicated key-value store; the cluster's single source of truth. Back it up." },
      { name: "kube-scheduler", description: "Assigns unscheduled Pods to nodes; does not start containers itself." },
      { name: "kube-controller-manager", description: "One binary running many controllers (Deployment, ReplicaSet, Node, Job, EndpointSlice, ServiceAccount...)." },
      { name: "kubelet", description: "Node agent: registers the node, runs Pods assigned to it via the CRI, executes probes, reports status." },
      { name: "kube-proxy", description: "Implements Service virtual IPs on each node using iptables, IPVS or nftables rules." }
    ],
    misconceptions: [
      {
        myth: "The scheduler starts containers on the chosen node.",
        reality: "The scheduler only **records the decision** (it binds the Pod, setting `spec.nodeName`). The kubelet on that node notices and starts the containers."
      },
      {
        myth: "If the control plane goes down, all applications stop.",
        reality: "Running containers keep running and kube-proxy rules stay in place. What stops is change: no new scheduling, no self-healing, no `kubectl` operations."
      },
      {
        myth: "The kubelet runs only on worker nodes.",
        reality: "In kubeadm-style clusters the control-plane machines also run a kubelet, which starts the control-plane components as **static Pods** from manifest files on disk."
      }
    ],
    example: {
      title: "Look at the architecture of a running cluster",
      description: "In a kubeadm or kind cluster the control-plane components are visible as Pods in `kube-system`. In managed services (EKS, GKE, AKS) the control plane is hidden and you see only nodes and add-ons.",
      language: "bash",
      code: `kubectl get nodes -o wide
# NAME                 STATUS   ROLES           VERSION
# kind-control-plane   Ready    control-plane   v1.31.0
# kind-worker          Ready    <none>          v1.31.0

kubectl get pods -n kube-system
# etcd-kind-control-plane                      1/1  Running
# kube-apiserver-kind-control-plane            1/1  Running
# kube-controller-manager-kind-control-plane   1/1  Running
# kube-scheduler-kind-control-plane            1/1  Running
# kube-proxy-7xk2p                             1/1  Running
# coredns-6f6b679f8f-9q2lw                     1/1  Running

kubectl cluster-info`
    },
    exercise: {
      prompt: `For each event, name the component that reacts first: (a) a user runs \`kubectl apply\`; (b) a new Pod object exists with no node assigned; (c) a Pod has been assigned to \`node-3\`; (d) a ReplicaSet wants 3 Pods but only 2 exist; (e) the cluster needs a cloud load balancer for a Service.`,
      solution: `(a) **kube-apiserver** \u2013 authenticates, authorizes, admits and stores the object in etcd.

(b) **kube-scheduler** \u2013 selects a node and binds the Pod.

(c) The **kubelet on node-3** \u2013 asks the container runtime (via CRI) to start the containers.

(d) The **ReplicaSet controller** in kube-controller-manager \u2013 creates one more Pod object.

(e) The service controller in the **cloud-controller-manager** \u2013 provisions the load balancer through the cloud API.`
    },
    faq: [
      {
        q: "How many control-plane nodes should production have?",
        a: "Commonly **3** (with stacked etcd, matching an odd etcd member count) so one can fail. Managed Kubernetes services run and scale the control plane for you."
      },
      {
        q: "Is CoreDNS part of the control plane?",
        a: "It is a **cluster add-on**, not one of the core control-plane components, but nearly every cluster runs it because Service discovery depends on DNS."
      },
      {
        q: "Can I run my own Pods on control-plane nodes?",
        a: "Control-plane nodes are normally **tainted** (`node-role.kubernetes.io/control-plane:NoSchedule`) so ordinary Pods avoid them. Single-node test clusters often remove that taint."
      }
    ],
    keyTerms: ["control plane", "worker node", "kube-apiserver", "etcd", "kube-scheduler", "kube-controller-manager", "kubelet", "kube-proxy"],
    deeper: `Nodes send heartbeats by renewing **Lease** objects in the \`kube-node-lease\` namespace; the node controller marks a node \`NotReady\`/\`Unknown\` when leases stop and, after a grace period, Pods on it are evicted via taints. etcd can be **stacked** (on the control-plane nodes) or **external** (its own machines), trading simplicity against failure isolation.`,
    references: [
      { title: "Kubernetes Components", url: "https://kubernetes.io/docs/concepts/overview/components/" },
      { title: "Cluster Architecture", url: "https://kubernetes.io/docs/concepts/architecture/" }
    ],
    diagram: "cluster-architecture"
  },
  {
    id: "api-server-and-etcd",
    title: "The API server and etcd",
    stage: 1,
    order: 2,
    objectives: ["kf-core"],
    scope: "kcna",
    estMinutes: 25,
    summary: "Every request to Kubernetes passes through the API server: authentication, authorization, mutating admission, validation, validating admission, then persistence in etcd. Clients then learn about changes through watches.",
    what: `**kube-apiserver** exposes the Kubernetes API as RESTful HTTP resources such as \`/api/v1/namespaces/default/pods\` and \`/apis/apps/v1/namespaces/default/deployments\`. kubectl, controllers, the scheduler, kubelets and your own tools are all just clients of it.

**etcd** is a distributed, strongly consistent key-value store. The API server serializes every object and stores it under keys (by default with the prefix \`/registry/\`). etcd is the **single source of truth**: if it is not in etcd, the cluster does not know about it.

The API server is the **only** component that talks to etcd. Everything else goes through the API server, which enforces security and validation consistently.`,
    why: `Exam questions love the request chain ("which step rejects a request with an invalid token?", "where would a policy that injects a sidecar run?"). Operationally, etcd is the one stateful thing whose loss destroys the cluster's memory \u2013 which is why backing it up is a core admin task.`,
    problem: `If every component wrote directly to the database, each would need to re-implement authentication, permission checks, schema validation and defaults, and one buggy component could corrupt everything. Centralizing access in one API server gives one place for security policy, one place for validation, and one consistent change feed that every client can watch.`,
    how: `Follow \`kubectl apply -f deploy.yaml\` through the API server:

- **Transport.** kubectl reads kubeconfig and sends an HTTPS request with credentials (client certificate, bearer token, or OIDC token).
- **Authentication (who are you?).** Authenticator modules identify the user or ServiceAccount. Failure \u2192 \`401 Unauthorized\`.
- **Authorization (may you do this?).** Usually **RBAC** (with the Node authorizer for kubelets) checks verb + resource + namespace. Denied \u2192 \`403 Forbidden\`.
- **Mutating admission.** Admission controllers and mutating webhooks may **change** the object \u2013 e.g. set defaults, inject a sidecar, add a default StorageClass.
- **Schema validation.** The object is checked against the API schema (field types, required fields).
- **Validating admission.** Controllers, webhooks and ValidatingAdmissionPolicies may **reject** the object \u2013 e.g. Pod Security Admission, ResourceQuota. They cannot modify it.
- **Persist.** The object is written to etcd; \`resourceVersion\` is updated. The client gets \`200\`/\`201\`.
- **Notify.** Every client **watching** that resource type receives an event (ADDED/MODIFIED/DELETED) \u2013 this is how the Deployment controller learns it has work to do.`,
    components: [
      { name: "Authentication", description: "Identifies the caller: X.509 client certs, bearer/ServiceAccount tokens, OIDC. Kubernetes has no User objects; users are external identities." },
      { name: "Authorization", description: "Decides allow/deny, typically via RBAC and the Node authorizer. Default is deny." },
      { name: "Admission control", description: "Mutating phase (may modify) then validating phase (may only reject). Built-in plugins plus webhooks and CEL-based ValidatingAdmissionPolicy." },
      { name: "Watch", description: "Long-lived request that streams changes after a given `resourceVersion`; the basis of every controller." },
      { name: "etcd", description: "Raft-replicated key-value store holding all API objects. Run 3 or 5 members; take regular snapshots." }
    ],
    misconceptions: [
      {
        myth: "The scheduler and controllers read etcd directly for speed.",
        reality: "Only the API server reads and writes etcd. Other components use the API (with local caches fed by watches) \u2013 which keeps security and validation in one place."
      },
      {
        myth: "Admission controllers run before authorization.",
        reality: "Order is **authentication \u2192 authorization \u2192 mutating admission \u2192 schema validation \u2192 validating admission \u2192 etcd**. Admission only sees requests that are already authenticated and authorized."
      },
      {
        myth: "Secrets in etcd are encrypted by default.",
        reality: "By default Secrets are stored **base64-encoded, not encrypted**. Encryption at rest must be configured on the API server (an EncryptionConfiguration, optionally with a KMS provider)."
      }
    ],
    example: {
      title: "Watching the API, and backing up etcd",
      description: `\`--watch\` uses the same streaming mechanism controllers use. The etcd snapshot command is what an administrator runs on a control-plane node (certificate paths vary per installation).`,
      language: "bash",
      code: `# Stream changes to Pods in the current namespace (a client-side watch)
kubectl get pods --watch

# See raw API paths and the request chain at high verbosity
kubectl get deployments -v=6
# ... GET https://127.0.0.1:6443/apis/apps/v1/namespaces/default/deployments 200 OK

# Ask the API server what you are allowed to do (authorization check)
kubectl auth can-i create deployments --namespace default

# On a control-plane node: snapshot etcd
ETCDCTL_API=3 etcdctl snapshot save /backup/etcd.db \\
  --endpoints=https://127.0.0.1:2379 \\
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \\
  --cert=/etc/kubernetes/pki/etcd/server.crt \\
  --key=/etc/kubernetes/pki/etcd/server.key`
    },
    exercise: {
      prompt: `For each outcome, name the stage of the request chain responsible: (a) \`error: You must be logged in to the server (Unauthorized)\`; (b) a Pod created without a ServiceAccount ends up with \`serviceAccountName: default\`; (c) a privileged Pod is rejected in a namespace labelled \`pod-security.kubernetes.io/enforce: restricted\`; (d) \`User "dev" cannot delete resource "pods"\`.`,
      solution: `(a) **Authentication** \u2013 the credentials were missing or invalid (401).

(b) **Mutating admission** \u2013 the ServiceAccount admission plugin defaults the field.

(c) **Validating admission** \u2013 Pod Security Admission enforces the Pod Security Standards.

(d) **Authorization** \u2013 RBAC found no rule granting \`delete\` on \`pods\` (403).`
    },
    faq: [
      {
        q: "What happens to the cluster if etcd loses all its data?",
        a: "The cluster forgets every object: Deployments, Services, Secrets, RBAC. Containers already running keep going for a while, but nothing can be managed or recovered without restoring an etcd **snapshot**."
      },
      {
        q: "Why do some API paths start with /api and others with /apis?",
        a: "`/api/v1` is the **core** (legacy) group: Pods, Services, ConfigMaps, Secrets, Namespaces. Named groups live under `/apis/<group>/<version>`, e.g. `/apis/apps/v1` for Deployments."
      },
      {
        q: "Can I extend the API?",
        a: "Yes. **CustomResourceDefinitions** add new resource types that the API server stores in etcd like built-ins; aggregated API servers are the less common alternative. Operators build on CRDs."
      }
    ],
    keyTerms: ["kube-apiserver", "etcd", "authentication", "authorization", "admission controller", "mutating webhook", "watch", "API group"],
    deeper: `To avoid hammering the API server, clients use **informers**: one list + watch per resource type, a local in-memory cache, and event handlers that enqueue work. The API server also has its own watch cache in front of etcd. **API Priority and Fairness** queues requests by priority so a noisy client cannot starve system components.`,
    references: [
      { title: "Controlling Access to the Kubernetes API", url: "https://kubernetes.io/docs/concepts/security/controlling-access/" },
      { title: "Admission Control in Kubernetes", url: "https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/" },
      { title: "etcd documentation", url: "https://etcd.io/docs/" }
    ],
    diagram: "request-flow"
  },
  {
    id: "control-plane-controllers",
    title: "Scheduler and controller managers",
    stage: 1,
    order: 3,
    objectives: ["kf-core", "kf-scheduling"],
    scope: "kcna",
    estMinutes: 20,
    summary: "kube-scheduler decides where each Pod runs by filtering and scoring nodes. kube-controller-manager runs the built-in control loops. cloud-controller-manager holds the loops that need a cloud provider API.",
    what: `Three control-plane programs make decisions; none of them runs containers.

- **kube-scheduler** watches for Pods with no \`spec.nodeName\` and picks the best node for each.
- **kube-controller-manager** is one process bundling many independent **controllers**, each a loop that watches some resources and nudges the cluster towards their spec: ReplicaSet, Deployment, StatefulSet, DaemonSet, Job, CronJob, Node, Namespace, EndpointSlice, ServiceAccount, garbage collector, and more.
- **cloud-controller-manager** (CCM) contains the controllers that must call a cloud provider: the **node** controller (match nodes to cloud instances, remove deleted ones), **route** controller (configure cloud routes for Pod networks) and **service** controller (create cloud load balancers for \`type: LoadBalancer\`).`,
    why: `KCNA asks you to distinguish these clearly: "which component chooses the node?", "which component creates replacement Pods?", "what provisions a cloud load balancer?". Scheduling concepts (resources, taints, affinity) are their own objective, and they all plug into the filter-and-score process described here.`,
    problem: `Separating decisions into small loops makes each one simple and replaceable. One giant "cluster manager" would be hard to extend and a single bug would stall everything. Splitting cloud logic into the CCM let Kubernetes remove provider-specific code from the core and lets each provider release its integration independently.`,
    how: `Follow a single Pod from creation to placement:

- **A controller creates the Pod.** The ReplicaSet controller sees 2 Pods but wants 3, so it creates a Pod object from its template. The Pod has no node yet; it is \`Pending\`.
- **The scheduler queues it.** The scheduler's watch delivers the unscheduled Pod; it enters a priority-ordered **scheduling queue**.
- **Filtering.** The scheduler removes nodes that cannot run the Pod: not enough unreserved CPU/memory for the Pod's **requests**, a **taint** the Pod does not tolerate, a mismatched **nodeSelector** or required **node affinity**, port conflicts, volume topology constraints.
- **Scoring.** Remaining nodes are ranked by plugins \u2013 e.g. spreading Pods across nodes/zones, preferring nodes that already have the image, balancing resource use, preferred affinities.
- **Binding.** The highest-scoring node wins (ties broken randomly). The scheduler writes a **Binding**, which sets \`spec.nodeName\`.
- **Unschedulable?** If no node passes filtering, the Pod stays \`Pending\` with a \`FailedScheduling\` event explaining why (e.g. \`0/3 nodes are available: 3 Insufficient cpu\`). Higher-priority Pods may trigger **preemption** of lower-priority ones.
- **Hand-off.** The kubelet on the chosen node takes over.`,
    components: [
      { name: "kube-scheduler", description: "Filter \u2192 score \u2192 bind. Considers requests (not actual usage), taints/tolerations, affinity, topology spread." },
      { name: "kube-controller-manager", description: "Runs built-in controllers in one binary; one active instance via leader election." },
      { name: "cloud-controller-manager", description: "Node, route and service controllers that talk to the cloud provider API. Absent on bare metal unless a provider integration is installed." },
      { name: "Leader election", description: "Multiple replicas of scheduler/controller managers run for HA, but only the lease holder acts." }
    ],
    misconceptions: [
      {
        myth: "The scheduler places Pods based on current CPU usage.",
        reality: `Filtering uses resource **requests** compared to node allocatable minus other Pods' requests. A node can look idle in metrics and still be "full" for scheduling.`
      },
      {
        myth: "The scheduler moves Pods to better nodes later.",
        reality: 'Scheduling happens **once** per Pod. A bound Pod is never moved; to "move" it, it must be deleted and a new Pod scheduled. (The separate Descheduler project can evict Pods to trigger this.)'
      },
      {
        myth: "kube-controller-manager is a single controller.",
        reality: "It is a **process** containing dozens of independent controllers, each with its own loop."
      }
    ],
    example: {
      title: "Reading a scheduling failure",
      description: `The scheduler explains filter failures in events. Here, no node had enough CPU for the Pod's requests, and one node was excluded by a taint.`,
      language: "bash",
      code: `kubectl describe pod api-7c9d5b7f6-xq2lp
# ...
# Status:  Pending
# Events:
#   Type     Reason            From               Message
#   Warning  FailedScheduling  default-scheduler  0/3 nodes are available:
#     1 node(s) had untolerated taint {node-role.kubernetes.io/control-plane: },
#     2 Insufficient cpu. preemption: 0/3 nodes are available:
#     1 Preemption is not helpful for scheduling,
#     2 No preemption victims found for incoming pod.`
    },
    exercise: {
      prompt: `A Pod requests \`cpu: 2\`. Node A has 4 allocatable CPUs with Pods requesting 3; node B has 8 allocatable CPUs with Pods requesting 5 but carries the taint \`gpu=true:NoSchedule\`; node C has 4 allocatable CPUs with Pods requesting 1. The Pod has no tolerations. Which nodes pass filtering, and where does it go?`,
      solution: `- Node A: 4 \u2212 3 = 1 CPU free < 2 \u2192 **filtered out**.
- Node B: 3 CPUs free, but the Pod does not tolerate \`gpu=true:NoSchedule\` \u2192 **filtered out**.
- Node C: 4 \u2212 1 = 3 CPUs free \u2265 2 \u2192 **passes**.

Only node C is feasible, so the Pod is bound to node C (scoring is trivial with one candidate).`
    },
    faq: [
      {
        q: "Can I run more than one scheduler?",
        a: "Yes. A Pod can choose one with `spec.schedulerName`; Pods without it use `default-scheduler`."
      },
      {
        q: "Who sets a Node to NotReady?",
        a: "The **node lifecycle controller** in kube-controller-manager, when the kubelet stops renewing its heartbeat. After a timeout, taints cause Pods on that node to be evicted so their controllers replace them elsewhere."
      },
      {
        q: "What if I bypass the scheduler by setting nodeName myself?",
        a: "Setting `spec.nodeName` in the manifest skips scheduling entirely; the named node's kubelet just tries to run it. Filtering (resources, taints) is not checked, so the Pod may be rejected by that kubelet."
      }
    ],
    keyTerms: ["kube-scheduler", "filtering", "scoring", "binding", "kube-controller-manager", "cloud-controller-manager", "leader election", "FailedScheduling"],
    deeper: `The scheduler is built on the **scheduling framework**: extension points (PreFilter, Filter, Score, Reserve, Permit, Bind...) where plugins hook in, configured through scheduler profiles. Custom schedulers for batch/AI workloads (e.g. gang scheduling) plug in this way or run alongside the default scheduler.`,
    references: [
      { title: "Kubernetes Scheduler", url: "https://kubernetes.io/docs/concepts/scheduling-eviction/kube-scheduler/" },
      { title: "Controllers", url: "https://kubernetes.io/docs/concepts/architecture/controller/" },
      { title: "Cloud Controller Manager", url: "https://kubernetes.io/docs/concepts/architecture/cloud-controller/" }
    ]
  },
  {
    id: "node-components",
    title: "Node components: kubelet, runtime, kube-proxy",
    stage: 1,
    order: 4,
    objectives: ["kf-core", "kf-containerization"],
    scope: "kcna",
    estMinutes: 20,
    summary: "On each node the kubelet turns Pod specs into running containers by calling a container runtime through the CRI (containerd or CRI-O, which call runc). kube-proxy programs Service routing.",
    what: `Look at the cluster from a single node's point of view:

- **kubelet** \u2013 the node's agent. It registers the node with the API server, watches for Pods bound to it, makes their containers run, mounts volumes, runs probes, and reports Pod and node status.
- **Container Runtime Interface (CRI)** \u2013 a gRPC API between the kubelet and the runtime. Any runtime implementing it works.
- **High-level runtime** \u2013 **containerd** or **CRI-O**: pulls images, manages storage, creates the Pod sandbox and containers.
- **Low-level OCI runtime** \u2013 usually **runc** (alternatives: crun, gVisor's runsc, Kata). Creates the actual namespaced, cgrouped process.
- **kube-proxy** \u2013 watches Services and EndpointSlices and programs rules (iptables, IPVS, or nftables in newer versions) so a Service IP reaches a backend Pod. Some CNI plugins replace it entirely.
- **CNI plugin** \u2013 called by the runtime to give each Pod sandbox a network interface and IP.`,
    why: `The 1.24 **dockershim removal** made "Kubernetes runtime" a common exam topic: the kubelet only speaks CRI, and Docker Engine does not implement CRI natively. Knowing the chain kubelet \u2192 CRI \u2192 containerd/CRI-O \u2192 runc also tells you where to look when a Pod is stuck in \`ContainerCreating\` or \`ImagePullBackOff\`.`,
    problem: `Early Kubernetes hard-coded Docker support into the kubelet (dockershim). Every new runtime needed kubelet changes, and the extra Docker daemon layer added complexity. The CRI defined a stable plug-in boundary, so the kubelet stays the same while runtimes evolve independently \u2013 the same "define an interface" pattern as CNI for networking and CSI for storage.`,
    how: `What the kubelet does when a Pod is bound to its node:

- **Observe.** Its watch on the API server delivers a Pod with \`spec.nodeName\` equal to this node.
- **Admit.** It checks node-level conditions (enough resources, no node pressure that blocks admission).
- **Create the sandbox.** CRI \`RunPodSandbox\`: the runtime creates the Pod's shared namespaces (notably the network namespace, held by a tiny "pause" container in containerd/CRI-O). The **CNI plugin** attaches a network interface and assigns the Pod IP.
- **Prepare volumes.** ConfigMaps, Secrets, emptyDirs and persistent volumes are mounted.
- **Pull images.** CRI \`PullImage\` according to \`imagePullPolicy\`.
- **Start containers.** Init containers run first, one by one, to completion; then the app containers start via CRI \`CreateContainer\`/\`StartContainer\`. The runtime hands an OCI bundle to runc, which creates the process.
- **Supervise.** The kubelet runs liveness/readiness/startup probes, restarts failed containers per \`restartPolicy\` (with exponential back-off), and reports status (\`Running\`, \`Ready\`, restart counts) to the API server.
- **Heartbeat.** It updates the node's Lease and status so the control plane knows the node is alive.`,
    components: [
      { name: "kubelet", description: "Node agent; the only component that actually causes containers to start on a node. Also runs **static Pods** from local manifest files." },
      { name: "CRI", description: "gRPC interface (RuntimeService + ImageService) between kubelet and runtime." },
      { name: "containerd", description: "CNCF graduated high-level runtime with a built-in CRI plugin; default in many distributions and managed services." },
      { name: "CRI-O", description: "Lightweight runtime built specifically for the Kubernetes CRI; a CNCF project used e.g. by OpenShift." },
      { name: "runc", description: "Reference OCI runtime that creates container processes from bundles." },
      { name: "kube-proxy", description: "Per-node Service implementation; typically a DaemonSet. Does not proxy traffic in user space in modern modes \u2013 it programs the kernel." }
    ],
    misconceptions: [
      {
        myth: "After dockershim removal, images built with Docker no longer work.",
        reality: "Docker builds standard OCI images; containerd and CRI-O run them unchanged. Only using **Docker Engine as the node runtime** was affected (it now needs the external cri-dockerd adapter)."
      },
      {
        myth: "kube-proxy carries all Service traffic through itself.",
        reality: "In iptables/IPVS/nftables modes kube-proxy only **writes kernel rules**; packets are redirected by the kernel. kube-proxy can be down briefly without breaking existing rules."
      },
      {
        myth: "The kubelet manages any container on the node.",
        reality: "The kubelet manages containers for **Pods** (from the API server or static manifests). Containers started directly with a runtime CLI are invisible to Kubernetes."
      }
    ],
    example: {
      title: "Inspecting the node layer",
      description: `\`crictl\` is the CRI debugging CLI; it talks to the same socket the kubelet uses, so it shows exactly what the kubelet sees. Run it on a node (e.g. \`docker exec -it kind-worker bash\` in kind).`,
      language: "bash",
      code: `# Which runtime does each node use?
kubectl get nodes -o wide
# NAME          ...  CONTAINER-RUNTIME
# kind-worker   ...  containerd://1.7.18

# On the node: list Pod sandboxes and containers through the CRI
crictl pods
crictl ps
crictl images

# kubelet logs on a systemd-based node
journalctl -u kubelet --since "10 min ago"`
    },
    exercise: {
      prompt: `A Pod is stuck in \`ContainerCreating\` for several minutes. List which node-level component could be responsible at each step of the kubelet's start-up sequence, and one concrete thing that could go wrong for each.`,
      solution: `- **Sandbox / CNI:** the CNI plugin is missing or failing \u2192 events like \`failed to setup network for sandbox\`.
- **Volumes (kubelet):** a referenced ConfigMap/Secret does not exist, or a persistent volume cannot attach/mount \u2192 \`FailedMount\` events.
- **Image pull (runtime):** pull is slow or failing \u2192 usually shown as \`ErrImagePull\`/\`ImagePullBackOff\` rather than \`ContainerCreating\`.
- **Runtime itself:** containerd/CRI-O is unhealthy \u2192 kubelet logs show CRI errors and the node may go \`NotReady\`.

\`kubectl describe pod\` (events) is the first place to look; kubelet logs on the node are the next.`
    },
    faq: [
      {
        q: "Is Docker still useful with Kubernetes?",
        a: "Yes \u2013 for **building** images and local development. It is just not the recommended node runtime. Tools like kind even run whole Kubernetes nodes inside Docker containers."
      },
      {
        q: "What is the pause container?",
        a: "A tiny container that holds the Pod's shared namespaces (especially the network namespace) so app containers can restart without losing the Pod IP. It is an implementation detail of runtimes like containerd and CRI-O."
      },
      {
        q: "Do I always need kube-proxy?",
        a: "Most clusters run it. Some CNI plugins (Cilium in kube-proxy replacement mode, for example) implement Services with eBPF instead, so kube-proxy is not deployed."
      }
    ],
    keyTerms: ["kubelet", "CRI", "containerd", "CRI-O", "runc", "kube-proxy", "dockershim", "static Pod"],
    deeper: `Static Pods are how kubeadm runs the control plane: the kubelet reads manifests from a directory (commonly \`/etc/kubernetes/manifests\`) and creates the Pods without any API server involvement, then publishes read-only "mirror Pods" to the API. The kubelet also enforces node-pressure **eviction** when memory or disk runs low, evicting Pods by QoS class and usage.`,
    references: [
      { title: "Kubernetes Components", url: "https://kubernetes.io/docs/concepts/overview/components/" },
      { title: "Container Runtime Interface (CRI)", url: "https://kubernetes.io/docs/concepts/architecture/cri/" },
      { title: "Container Runtimes", url: "https://kubernetes.io/docs/setup/production-environment/container-runtimes/" }
    ]
  },
  {
    id: "declarative-reconciliation",
    title: "Desired state and reconciliation",
    stage: 1,
    order: 5,
    objectives: ["kf-core"],
    scope: "kcna",
    estMinutes: 20,
    summary: "You declare what should exist; controllers repeatedly observe actual state, compare it with desired state, and act to close the gap. kubectl apply is the declarative way to submit desired state.",
    what: `**Desired state** is what you write in an object's \`spec\` ("3 replicas of image v2"). **Actual state** is what is really running, reported in \`status\`. A **controller** is a loop that never stops trying to make actual match desired. This pattern is called **reconciliation**.

Two ways to talk to Kubernetes:

- **Imperative** \u2013 tell it *what to do*: \`kubectl create deployment\`, \`kubectl scale --replicas=5\`, \`kubectl delete pod\`. Fast for experiments; nothing records why.
- **Declarative** \u2013 tell it *what you want*: keep manifests in files (ideally Git) and run \`kubectl apply -f\`. Kubernetes works out the changes.`,
    why: `Reconciliation is the single most important idea in Kubernetes: it explains self-healing, rolling updates, scaling, GitOps and operators. Exam questions often describe a symptom ("I deleted a Pod and it came back") whose answer is "a controller reconciled it".`,
    problem: `Scripts that execute steps ("start 3 containers") work only if the world is exactly as the script expected and nothing changes afterwards. Servers crash, someone deletes something by hand, a step fails half-way. A declarative system does not care how you got here \u2013 it compares where you are with where you should be and corrects the difference, every time.`,
    how: `A thermostat is the classic analogy: you set 21 \xB0C (desired), it measures 19 \xB0C (actual), it turns on the heat (act), and it keeps checking. A Kubernetes controller does the same:

- **Observe.** Watch the relevant objects through the API server (e.g. a ReplicaSet and the Pods it owns).
- **Compare.** Desired: \`spec.replicas: 3\`. Actual: 2 Pods match the selector.
- **Act.** Make the smallest change that moves towards desired: create 1 Pod. Never "start from scratch".
- **Report.** Update \`status\` (e.g. \`readyReplicas\`) so others can observe progress.
- **Repeat.** Triggered by watch events **and** periodic resyncs. Because the logic is based on current state (level-triggered), a missed event or a controller restart does no harm.

How \`kubectl apply\` fits in:

- On the first apply, the object is created. kubectl records what you applied (client-side: in the \`kubectl.kubernetes.io/last-applied-configuration\` annotation; server-side apply: as **managed fields** per field manager).
- On later applies, kubectl computes a **three-way merge** of your file, the last-applied state and the live object, and sends a patch. Fields you removed from the file are removed; fields set by others (e.g. an autoscaler) are left alone.
- \`kubectl diff -f\` shows what an apply would change before you run it.`,
    components: [
      { name: "spec", description: "Desired state, written by users or higher-level controllers." },
      { name: "status", description: "Observed state, written by controllers and kubelets." },
      { name: "Controller / control loop", description: "Observe \u2192 compare \u2192 act \u2192 repeat. Each controller owns one concern." },
      { name: "kubectl apply", description: "Declarative create-or-update from files using a merge of file, last-applied and live state." },
      { name: "Operator", description: "A custom controller (usually with CRDs) that encodes operational knowledge for an application, e.g. a database." }
    ],
    misconceptions: [
      {
        myth: "Declarative means kubectl never changes anything until I re-apply.",
        reality: "Controllers act continuously. If a Pod dies, a replacement appears without any new apply \u2013 the desired state is still stored."
      },
      {
        myth: "`kubectl apply` and `kubectl create` are interchangeable.",
        reality: "`create` fails if the object exists (`AlreadyExists`). `apply` creates **or** updates and tracks what you manage. Mixing them on the same object is a common source of surprises."
      },
      {
        myth: "Fixing a running Pod by hand is a permanent fix.",
        reality: "If the Pod is owned by a controller, the next replacement Pod comes from the **template**. Manual changes to live objects (`kubectl edit`) also drift from what is in Git and may be overwritten by the next apply or a GitOps sync."
      }
    ],
    example: {
      title: "Watch a control loop heal",
      description: "Delete a Pod owned by a Deployment and the ReplicaSet controller restores the count. Then change the desired state declaratively and preview it first.",
      language: "bash",
      code: `kubectl apply -f web-deployment.yaml          # replicas: 3
kubectl get pods -l app=web
# web-5d8f7c6b9-2kq4x  Running
# web-5d8f7c6b9-8hz7m  Running
# web-5d8f7c6b9-tw9pd  Running

kubectl delete pod web-5d8f7c6b9-2kq4x
kubectl get pods -l app=web
# web-5d8f7c6b9-8hz7m  Running
# web-5d8f7c6b9-tw9pd  Running
# web-5d8f7c6b9-x7n2c  ContainerCreating    <- replacement

# change replicas: 3 -> 5 in the file, then:
kubectl diff -f web-deployment.yaml          # preview the change
kubectl apply -f web-deployment.yaml`
    },
    exercise: {
      prompt: `A teammate runs \`kubectl scale deployment web --replicas=10\` during an incident. The manifest in Git says \`replicas: 3\`, and a GitOps tool applies Git every few minutes. What happens next, and what should they have done instead?`,
      solution: `The imperative scale changes the live desired state to 10, and the controller creates 7 Pods. On the next sync the GitOps tool re-applies Git, setting \`replicas\` back to **3**, and the extra Pods are removed \u2013 possibly mid-incident.

Better: change \`replicas\` in Git (so the declared state is the real intent), or let a HorizontalPodAutoscaler own the replica count and remove \`replicas\` from the manifest so the two do not fight.`
    },
    faq: [
      {
        q: "If everything is declarative, why does kubectl have imperative commands?",
        a: "They are convenient for learning, debugging and generating starter YAML (`kubectl create deployment web --image=nginx --dry-run=client -o yaml`). For anything long-lived, store manifests and apply them."
      },
      {
        q: "What is server-side apply?",
        a: "`kubectl apply --server-side` performs the merge on the API server and records which **field manager** owns each field, reporting conflicts when two managers set the same field. It replaces the last-applied annotation mechanism."
      },
      {
        q: "How fast does reconciliation happen?",
        a: "Usually within seconds, because controllers react to watch events. But it is asynchronous: `apply` returning success means the desired state was stored, not that it is achieved. Use `kubectl rollout status` or `kubectl get -w` to watch convergence."
      }
    ],
    keyTerms: ["desired state", "actual state", "reconciliation", "control loop", "declarative", "imperative", "kubectl apply", "operator"],
    deeper: `Controllers are written as a work queue fed by informers: events only enqueue an object key, and a worker re-reads the latest state before acting. This is why controllers are idempotent and tolerate duplicate or out-of-order events. The same pattern scales out to GitOps: Argo CD and Flux are reconcilers whose "desired state" lives in Git instead of etcd.`,
    references: [
      { title: "Controllers", url: "https://kubernetes.io/docs/concepts/architecture/controller/" },
      { title: "Declarative Management of Kubernetes Objects Using Configuration Files", url: "https://kubernetes.io/docs/tasks/manage-kubernetes-objects/declarative-config/" },
      { title: "Kubernetes Object Management", url: "https://kubernetes.io/docs/concepts/overview/working-with-objects/object-management/" }
    ],
    diagram: "reconciliation-loop"
  },
  // ───────────────────────────── Stage 2 · Workloads ─────────────────────────────
  {
    id: "pods",
    title: "Pods",
    stage: 2,
    order: 1,
    objectives: ["kf-core"],
    scope: "kcna",
    estMinutes: 25,
    summary: "A Pod is the smallest deployable unit: one or more containers that share a network namespace and volumes and are always scheduled together. Pods are disposable; controllers recreate them.",
    what: `A **Pod** wraps one or more containers that must live together:

- They are **scheduled onto the same node** as a unit.
- They share one **network namespace**: one Pod IP, one port space; containers talk over \`localhost\`.
- They can share **volumes** declared at Pod level.
- They share a lifecycle: the Pod is created, runs, and is deleted as one object.

Container roles inside a Pod:

- **App containers** \u2013 the main workload; started together, run in parallel.
- **Init containers** \u2013 run **one at a time, to completion**, before app containers start (wait for a dependency, run a migration, fetch config).
- **Sidecar containers** \u2013 helpers that run alongside the app for the Pod's whole life (log shipping, proxies). Native sidecars are declared as init containers with \`restartPolicy: Always\` (stable since Kubernetes 1.33): they start before the app containers, keep running, and are stopped after them.`,
    why: `Everything that runs in Kubernetes runs in a Pod \u2013 Deployments, Jobs, StatefulSets all create Pods. Pod phases, restart policies and container states are exactly what you see in \`kubectl get pods\` when something is wrong, and they come up repeatedly on the exam.`,
    problem: `Some processes are tightly coupled: a web server and the agent that ships its logs, or an app and its local proxy. Putting them in one container breaks "one process per container" and couples their images and releases. Putting them in separate, independently scheduled units loses \`localhost\` and shared files. The Pod is the middle ground: separate images, shared context.`,
    how: `Follow the Pod lifecycle as a state machine.

**Pod phase** (\`status.phase\`) \u2013 a coarse summary:

- \`Pending\` \u2013 accepted, but not all containers are running yet: waiting to be scheduled, pulling images, or running init containers.
- \`Running\` \u2013 bound to a node, all containers created, at least one running (or starting/restarting).
- \`Succeeded\` \u2013 all containers exited 0 and will not restart.
- \`Failed\` \u2013 all containers terminated and at least one failed (non-zero exit or killed) and will not restart.
- \`Unknown\` \u2013 the node cannot be reached, so status cannot be obtained.

**Container state** (per container) \u2013 \`Waiting\` (with a reason such as \`ContainerCreating\`, \`ImagePullBackOff\`, \`CrashLoopBackOff\`), \`Running\`, or \`Terminated\` (with exit code and reason such as \`Completed\`, \`Error\`, \`OOMKilled\`).

**restartPolicy** (Pod-level, applies to app containers): \`Always\` (default; required for Deployments), \`OnFailure\` (restart only on non-zero exit; common for Jobs), \`Never\`. Restarts happen **in place on the same node** with exponential back-off (10s, 20s, 40s ... capped at 5 minutes) \u2013 that back-off is what \`CrashLoopBackOff\` means.

**Termination:** on delete, the Pod is marked terminating, removed from Service endpoints, any \`preStop\` hook runs, containers get \`SIGTERM\`, and after \`terminationGracePeriodSeconds\` (default 30) the remaining ones get \`SIGKILL\`.`,
    components: [
      { name: "Pod IP / network namespace", description: "One IP per Pod, shared by all its containers. Two containers in a Pod cannot both listen on the same port." },
      { name: "Init containers", description: "Sequential, run-to-completion setup steps. If one fails, the kubelet retries it (per restartPolicy) and app containers do not start." },
      { name: "Sidecar containers", description: "Init containers with `restartPolicy: Always`; run for the Pod's lifetime and do not block Job completion." },
      { name: "restartPolicy", description: "`Always` | `OnFailure` | `Never`, set once for the whole Pod." },
      { name: "Phase vs conditions", description: "Phase is a summary; conditions (`PodScheduled`, `Initialized`, `ContainersReady`, `Ready`) give detail. `Ready` controls Service traffic." }
    ],
    misconceptions: [
      {
        myth: "`CrashLoopBackOff` is a Pod phase.",
        reality: "It is a **container waiting reason**: the container keeps crashing and the kubelet is backing off before the next restart. The Pod phase is usually still `Running`."
      },
      {
        myth: "A Pod that crashes gets rescheduled to another node.",
        reality: "Containers are restarted **in place** by the kubelet. A Pod is never moved; only a controller can create a **new** Pod (with a new name and IP) elsewhere \u2013 for example after the Pod is deleted or its node fails."
      },
      {
        myth: "Each container in a Pod gets its own IP.",
        reality: "The **Pod** gets one IP. Containers inside share it and distinguish themselves by port."
      }
    ],
    example: {
      title: "Init container, native sidecar and app in one Pod",
      description: `The init container waits for the \`db\` Service to resolve. The sidecar (an init container with \`restartPolicy: Always\`) tails the app's log file from a shared \`emptyDir\` volume and keeps running alongside the app.`,
      language: "yaml",
      code: `apiVersion: v1
kind: Pod
metadata:
  name: shop
  labels:
    app: shop
spec:
  restartPolicy: Always
  volumes:
  - name: logs
    emptyDir: {}
  initContainers:
  - name: wait-for-db
    image: busybox:1.36
    command: ["sh", "-c", "until nslookup db; do echo waiting; sleep 2; done"]
  - name: log-shipper              # native sidecar
    image: busybox:1.36
    restartPolicy: Always
    command: ["sh", "-c", "tail -F /var/log/app/app.log"]
    volumeMounts:
    - name: logs
      mountPath: /var/log/app
  containers:
  - name: app
    image: registry.example.com/shop/app:1.4.2
    ports:
    - containerPort: 8080
    volumeMounts:
    - name: logs
      mountPath: /var/log/app`
    },
    exercise: {
      prompt: `Predict \`kubectl get pod\` output for each case: (a) the \`db\` Service in the example does not exist yet; (b) the app container exits with code 1 every few seconds; (c) the app container finishes with exit code 0 (restartPolicy \`Always\`).`,
      solution: `(a) The first init container never completes. STATUS shows \`Init:0/2\`, phase \`Pending\`; the app container never starts.

(b) The kubelet restarts it with growing back-off. STATUS alternates between \`Error\` and \`CrashLoopBackOff\`, the RESTARTS count climbs, phase stays \`Running\`.

(c) With \`Always\`, even a clean exit triggers a restart, so you again see RESTARTS increasing (and eventually \`CrashLoopBackOff\`). A run-to-completion task belongs in a **Job** with \`OnFailure\` or \`Never\`.`
    },
    faq: [
      {
        q: "When should I put two containers in one Pod?",
        a: "Only when they must share lifecycle, network or files \u2013 a sidecar proxy, log shipper or config reloader. If they could scale independently (a web app and its database), use separate Pods."
      },
      {
        q: "Should I create Pods directly?",
        a: "Rarely. A bare Pod is not recreated if it is deleted or its node fails. Use a controller \u2013 Deployment, StatefulSet, DaemonSet or Job \u2013 that manages Pods from a template. Note that `kubectl run` creates only a single bare Pod."
      },
      {
        q: "Can I change a running Pod's spec?",
        a: "Mostly no \u2013 most Pod spec fields are immutable (image is a notable exception). In practice you change the controller's template and let it replace Pods."
      },
      {
        q: "What is the difference between Running and Ready?",
        a: "`Running` means the containers are started. `Ready` means readiness probes pass and the Pod should receive Service traffic. A Pod can be Running but not Ready."
      }
    ],
    keyTerms: ["Pod", "init container", "sidecar container", "Pod phase", "container state", "restartPolicy", "CrashLoopBackOff", "terminationGracePeriodSeconds"],
    deeper: `**Ephemeral containers** can be added to a running Pod for debugging (\`kubectl debug\`); they cannot be restarted and have no ports or probes. **Static Pods** are created by a kubelet from local files rather than the API. The **Pod overhead** and **Pod-level resources** features let the scheduler account for sandbox costs or set budgets for the whole Pod \u2013 check feature states for your version.`,
    references: [
      { title: "Pods", url: "https://kubernetes.io/docs/concepts/workloads/pods/" },
      { title: "Pod Lifecycle", url: "https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/" },
      { title: "Sidecar Containers", url: "https://kubernetes.io/docs/concepts/workloads/pods/sidecar-containers/" }
    ]
  },
  {
    id: "replicasets-and-deployments",
    title: "ReplicaSets and Deployments",
    stage: 2,
    order: 2,
    objectives: ["kf-core"],
    scope: "kcna",
    estMinutes: 25,
    summary: "A ReplicaSet keeps N identical Pods running. A Deployment manages ReplicaSets to add rolling updates and rollbacks. Ownership links the three levels, and garbage collection cleans up children.",
    what: `Two controllers stacked on top of each other:

- **ReplicaSet** \u2013 ensures that a specified number of Pods matching its **selector** exist. It creates Pods from its **Pod template** when there are too few and deletes some when there are too many. It does not know about versions.
- **Deployment** \u2013 the object you normally write for stateless apps. It owns ReplicaSets: one per version of the Pod template. Changing the template creates a new ReplicaSet and gradually shifts Pods to it (**rolling update**); old ReplicaSets are kept (scaled to 0) to allow **rollback**.

The chain is **Deployment \u2192 ReplicaSet \u2192 Pods**, linked by \`metadata.ownerReferences\` on each child.`,
    why: `Deployments are the default way to run stateless workloads, and most exam workload questions touch them: scaling, self-healing, update strategy, rollback, and "who created this Pod?". Understanding the ReplicaSet layer explains the odd Pod names (\`web-5d8f7c6b9-x7n2c\`) and what happens during a rollout.`,
    problem: `Running one Pod is fragile. Running N Pods by hand means noticing failures and replacing them yourself. And updating N Pods by deleting them all and creating new ones causes downtime and gives no way back if the new version is broken. ReplicaSets solve "keep N", Deployments solve "change versions safely".`,
    how: `Run an experiment in your head (or on a cluster):

- **Create.** You apply a Deployment \`web\` with \`replicas: 3\` and image \`nginx:1.26\`. The Deployment controller creates ReplicaSet \`web-<hash>\` (the hash comes from the Pod template and is also added as a \`pod-template-hash\` label). The ReplicaSet controller creates 3 Pods.
- **Break something.** Delete a Pod. The **ReplicaSet** controller (not the Deployment controller) sees 2 < 3 and creates one more.
- **Scale.** \`kubectl scale deployment web --replicas=5\` \u2013 the Deployment updates its current ReplicaSet's replica count; no new ReplicaSet is created because the template did not change.
- **Update.** Change the image to \`nginx:1.27\`. The template hash changes, so a **new ReplicaSet** is created. With the default **RollingUpdate** strategy (\`maxSurge: 25%\`, \`maxUnavailable: 25%\`), the controller scales the new one up and the old one down step by step, waiting for new Pods to become Ready.
- **Roll back.** \`kubectl rollout undo deployment/web\` points the Deployment back at the previous template; the old ReplicaSet is scaled up again. How many old ReplicaSets are kept is set by \`revisionHistoryLimit\` (default 10).
- **Delete.** Deleting the Deployment triggers **cascading deletion**: the garbage collector follows ownerReferences and removes the ReplicaSets and Pods.

The **Recreate** strategy is the alternative: scale old Pods to zero first, then create new ones (downtime, but never two versions at once).`,
    components: [
      { name: "Pod template", description: "`spec.template` \u2013 the blueprint for every Pod. Any change to it triggers a rollout." },
      { name: "Selector", description: "`spec.selector` must match the template's labels; immutable for `apps/v1` Deployments after creation." },
      { name: "ReplicaSet", description: "Keeps the replica count for one template version. Rarely created directly." },
      { name: "Rolling update parameters", description: "`maxSurge` (extra Pods allowed above desired) and `maxUnavailable` (Pods allowed below desired); both default to 25%." },
      { name: "ownerReferences & garbage collection", description: "Children point to their owner; deleting the owner removes dependents (cascading deletion) unless orphaning is requested." }
    ],
    misconceptions: [
      {
        myth: "Scaling a Deployment creates a new revision.",
        reality: "Only changes to `spec.template` create a new ReplicaSet/revision. Changing `replicas` adjusts the existing ReplicaSet."
      },
      {
        myth: "You should edit the ReplicaSet to change the image.",
        reality: "The Deployment owns the ReplicaSet and will revert or ignore such changes. Always change the **Deployment**; for a bare ReplicaSet, an edited template only affects Pods created later."
      },
      {
        myth: "Rollback restores the previous number of replicas too.",
        reality: "`rollout undo` restores the previous **Pod template**. The replica count is not part of the revision."
      }
    ],
    example: {
      title: "A Deployment with an explicit rolling update strategy",
      description: `With 4 replicas, \`maxSurge: 1\` and \`maxUnavailable: 0\`, the rollout never drops below 4 ready Pods and runs at most 5 Pods at a time \u2013 zero-downtime at the cost of one extra Pod of capacity.`,
      language: "yaml",
      code: `apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
  labels:
    app: web
spec:
  replicas: 4
  revisionHistoryLimit: 5
  selector:
    matchLabels:
      app: web
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0
  template:
    metadata:
      labels:
        app: web          # must match spec.selector
    spec:
      containers:
      - name: web
        image: nginx:1.27
        ports:
        - containerPort: 80
# kubectl set image deployment/web web=nginx:1.28
# kubectl rollout status deployment/web
# kubectl rollout history deployment/web
# kubectl rollout undo deployment/web --to-revision=2`
    },
    exercise: {
      prompt: `You have Deployment \`api\` with 10 replicas and default rolling update settings. You change the image. (a) What is the maximum number of Pods that may exist during the rollout? (b) The minimum number that must be available? (c) Afterwards, how many ReplicaSets does \`kubectl get rs\` show for \`api\`, and with what replica counts?`,
      solution: `(a) \`maxSurge\` 25% of 10 = 2.5, rounded **up** \u2192 3, so up to **13** Pods.

(b) \`maxUnavailable\` 25% of 10 = 2.5, rounded **down** \u2192 2, so at least **8** available.

(c) **Two** ReplicaSets: the new one with 10 replicas and the old one scaled to **0** (kept for rollback, within \`revisionHistoryLimit\`).`
    },
    faq: [
      {
        q: "Why are Pod names like web-5d8f7c6b9-x7n2c?",
        a: "`web` is the Deployment, `5d8f7c6b9` is the ReplicaSet's Pod template hash, and `x7n2c` is a random suffix for the individual Pod. It lets you see at a glance which version a Pod belongs to."
      },
      {
        q: "How do I find out who owns a Pod?",
        a: "Look at `metadata.ownerReferences` (`kubectl get pod <name> -o yaml`) or the `Controlled By:` line in `kubectl describe pod`."
      },
      {
        q: "When would I use a ReplicaSet directly?",
        a: "Almost never. Deployments give you everything a ReplicaSet does plus updates and rollbacks. Use StatefulSets for stable identity and DaemonSets for one-Pod-per-node instead."
      }
    ],
    keyTerms: ["ReplicaSet", "Deployment", "Pod template", "RollingUpdate", "Recreate", "maxSurge", "maxUnavailable", "ownerReferences"],
    deeper: `\`kubectl rollout pause\` lets you batch several template changes into one rollout. \`progressDeadlineSeconds\` (default 600) marks a rollout as failed (\`ProgressDeadlineExceeded\`) if it stops making progress \u2013 it reports, but does not roll back automatically. Garbage collection supports **foreground**, **background** (default) and **orphan** propagation policies, e.g. \`kubectl delete deployment web --cascade=orphan\` keeps the ReplicaSets and Pods.`,
    references: [
      { title: "Deployments", url: "https://kubernetes.io/docs/concepts/workloads/controllers/deployment/" },
      { title: "ReplicaSet", url: "https://kubernetes.io/docs/concepts/workloads/controllers/replicaset/" },
      { title: "Garbage Collection", url: "https://kubernetes.io/docs/concepts/architecture/garbage-collection/" }
    ],
    diagram: "deployment-hierarchy"
  },
  {
    id: "namespaces-labels-selectors",
    title: "Namespaces, labels, selectors and annotations",
    stage: 2,
    order: 3,
    objectives: ["kf-core", "kf-admin"],
    scope: "kcna",
    estMinutes: 20,
    summary: "Namespaces partition names, permissions and quotas. Labels are queryable key/value tags; selectors are the queries that wire Services, Deployments and policies to Pods. Annotations hold non-identifying metadata.",
    what: `Think of the cluster as a database and these as its organizing tools.

- **Namespace** \u2013 a scope for names. Two Deployments called \`web\` can coexist in \`team-a\` and \`team-b\`. Namespaces are also the unit for RBAC Roles, ResourceQuotas, LimitRanges, and (by label) Pod Security Admission. Default ones: \`default\`, \`kube-system\`, \`kube-public\`, \`kube-node-lease\`.
- **Labels** \u2013 key/value pairs in \`metadata.labels\` that **identify** objects: \`app: web\`, \`tier: frontend\`, \`env: prod\`. Keys may have a DNS prefix (\`app.kubernetes.io/name\`); the name part is at most 63 characters.
- **Selectors** \u2013 queries over labels. **Equality-based**: \`app=web\`, \`env!=prod\`. **Set-based**: \`env in (staging,prod)\`, \`tier notin (cache)\`, \`release\` (key exists), \`!release\` (key absent).
- **Annotations** \u2013 key/value pairs in \`metadata.annotations\` for **non-identifying** data: build info, contact, tool configuration. Values can be large; they cannot be selected on.`,
    why: `Labels and selectors are the glue of Kubernetes. Objects are not linked by name but by **label queries**: a Service finds its Pods by selector, a Deployment's ReplicaSet counts Pods by selector, NetworkPolicies and affinity rules select Pods by label. When a Service has no endpoints, a label mismatch is the first suspect. Namespaces are the first tool for multi-team clusters.`,
    problem: `In a cluster with thousands of objects you need to answer "show me all production frontend Pods" and "let team A manage only its own things". Folder-like hierarchies cannot express overlapping views (a Pod is both "frontend" and "prod" and "v2"). Free-form labels with a query language can, and namespaces add hard naming and permission boundaries where you need them.`,
    how: `How a selector connects objects, step by step, using a Service:

- **Label the Pods.** The Deployment template sets \`labels: {app: web, tier: frontend}\` on every Pod it creates.
- **Write the query.** The Service declares \`selector: {app: web}\`. Services support only equality-based selectors (all listed pairs must match).
- **Controller evaluates it.** The EndpointSlice controller lists Pods **in the Service's namespace** that carry \`app=web\` and are Ready, and writes their IPs into EndpointSlices.
- **Labels change \u2192 membership changes.** Remove the \`app=web\` label from one Pod and it drops out of the Service (and out of the ReplicaSet's count, so the ReplicaSet creates a replacement \u2013 a handy trick for debugging a Pod in isolation).
- **Namespace boundary.** Selectors in Services, ReplicaSets and Deployments only match objects in the same namespace. Cross-namespace access uses DNS names like \`web.team-a.svc.cluster.local\`.

Note that not everything is namespaced: **Nodes, PersistentVolumes, StorageClasses, Namespaces, ClusterRoles** and CRDs are cluster-scoped. \`kubectl api-resources --namespaced=false\` lists them.`,
    components: [
      { name: "Namespace", description: "Scope for names and for RBAC, quotas and policies. Not a network or security boundary by itself." },
      { name: "Label", description: "Identifying key/value pair; indexed and selectable. Recommended keys: `app.kubernetes.io/name`, `/instance`, `/version`, `/component`, `/part-of`, `/managed-by`." },
      { name: "Equality-based selector", description: "`=`, `==`, `!=`. Used by Services and `matchLabels`." },
      { name: "Set-based selector", description: "`in`, `notin`, exists, does-not-exist. Used by `matchExpressions` (Deployments, Jobs, affinity) and kubectl `-l`." },
      { name: "Annotation", description: "Non-identifying metadata for tools and humans; not selectable." }
    ],
    misconceptions: [
      {
        myth: "Namespaces isolate network traffic between teams.",
        reality: "By default every Pod can reach every other Pod across namespaces. Isolation needs **NetworkPolicies** (and a CNI that enforces them); permission isolation needs **RBAC**."
      },
      {
        myth: "Annotations and labels are interchangeable.",
        reality: "Only labels can be used in selectors. Annotations are for data you want to attach but never query, e.g. a git commit or a tool setting."
      },
      {
        myth: "A Service can select Pods in any namespace by label.",
        reality: "A Service selector only matches Pods in **its own namespace**."
      }
    ],
    example: {
      title: "Querying with labels and working across namespaces",
      description: "Common label and namespace operations with kubectl.",
      language: "bash",
      code: `kubectl create namespace team-a
kubectl config set-context --current --namespace=team-a   # change default namespace

kubectl get pods --show-labels
kubectl get pods -l app=web                          # equality-based
kubectl get pods -l 'env in (staging,prod),tier!=cache'   # set-based + equality
kubectl get pods -l '!canary'                        # label key absent
kubectl get pods -A -l app=web                       # all namespaces

kubectl label pod web-5d8f7c6b9-x7n2c env=prod       # add a label
kubectl label pod web-5d8f7c6b9-x7n2c env=staging --overwrite
kubectl label pod web-5d8f7c6b9-x7n2c env-           # remove a label
kubectl annotate deployment web owner="team-a@example.com"

kubectl api-resources --namespaced=false             # cluster-scoped kinds`
    },
    exercise: {
      prompt: `A Service in namespace \`shop\` has \`selector: {app: cart, tier: backend}\`. Pods: (1) \`app=cart, tier=backend\` in \`shop\`; (2) \`app=cart\` in \`shop\`; (3) \`app=cart, tier=backend, version=v2\` in \`shop\`; (4) \`app=cart, tier=backend\` in \`default\`. Which Pods become endpoints (assume all are Ready)?`,
      solution: `**Pods 1 and 3.** A selector requires **all** its pairs to match; extra labels on the Pod (\`version=v2\`) do not matter.

Pod 2 lacks \`tier=backend\`. Pod 4 matches the labels but is in another namespace, and Service selectors only match within the Service's own namespace.`
    },
    faq: [
      {
        q: "Does deleting a namespace delete everything inside it?",
        a: "Yes \u2013 all namespaced objects in it are deleted. The namespace sits in `Terminating` until that finishes. Cluster-scoped objects (e.g. PersistentVolumes) are not inside namespaces and follow their own rules."
      },
      {
        q: "Should I use namespaces for environments like dev and prod?",
        a: "It works for small setups, but many organizations put production in a **separate cluster** for stronger isolation. Namespaces are the usual unit for teams or applications within a cluster."
      },
      {
        q: "Can I change a Deployment's selector later?",
        a: "No \u2013 in `apps/v1` the selector is immutable. Create a new Deployment instead. You *can* add labels to the template, as long as the selector still matches."
      }
    ],
    keyTerms: ["namespace", "label", "label selector", "matchLabels", "matchExpressions", "annotation", "cluster-scoped", "namespaced"],
    deeper: `Field selectors (\`--field-selector status.phase=Running\`) filter on a small set of built-in fields, not on arbitrary spec values. Hierarchical namespaces and virtual clusters (e.g. vcluster) are ecosystem projects for stronger multi-tenancy than plain namespaces provide.`,
    references: [
      { title: "Labels and Selectors", url: "https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/" },
      { title: "Namespaces", url: "https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/" },
      { title: "Annotations", url: "https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/" }
    ]
  }
];

// ../../packages/content/src/lessons/b.ts
var lessonsB = [
  // ───────────────────────────── Stage 2 · Workloads ─────────────────────────────
  {
    id: "jobs-and-cronjobs",
    title: "Jobs and CronJobs",
    stage: 2,
    order: 4,
    objectives: ["kf-core"],
    scope: "kcna",
    estMinutes: 18,
    summary: "Jobs run Pods until a task finishes successfully; CronJobs create Jobs on a schedule. They are the workload controllers for work that is supposed to end.",
    what: `A **Job** is a controller that creates one or more Pods and keeps creating replacements until a specified number of them **complete successfully** (exit code 0). Then it stops. The Job object stays around as a record of the run.

A **CronJob** is a controller one level higher: on a cron schedule (for example \`0 2 * * *\` = every day at 02:00) it creates a new Job from a \`jobTemplate\`. The chain is CronJob \u2192 Job \u2192 Pod, the same "controller owns controller" pattern you saw with Deployment \u2192 ReplicaSet \u2192 Pod.`,
    why: `A Deployment assumes its Pods should run forever: if a Pod exits, the ReplicaSet replaces it. That is exactly wrong for a database migration, a report generator or a batch image resize. Those tasks should run, finish, and **stay finished**.

Jobs give batch work the same self-healing as long-running services: if the node dies halfway through, the Job controller notices the missing Pod and starts another, but once the work succeeds nothing gets restarted.`,
    problem: `Imagine running a nightly backup with a plain Pod. If the node reboots at 02:05, the Pod is gone and nothing retries it. If you wrap it in a Deployment instead, the backup "succeeds", exits, and is immediately started again in an endless loop.

Before Kubernetes, the usual answer was a crontab on one specific server: a single point of failure that nobody remembered to migrate. CronJob moves the schedule into the cluster, where it survives the loss of any single machine.`,
    how: `Follow one run of a CronJob from schedule to cleanup:

- The **CronJob controller** (part of kube-controller-manager) checks schedules. When a schedule time arrives, it creates a **Job** object from \`spec.jobTemplate\`.
- If the previous Job is still running, \`concurrencyPolicy\` decides: \`Allow\` (default, run both), \`Forbid\` (skip this run) or \`Replace\` (cancel the old one, start the new one).
- The **Job controller** sees the new Job and creates Pods from its Pod template. \`parallelism\` caps how many run at once; \`completions\` says how many must succeed (both default to 1).
- Each Pod's \`restartPolicy\` must be \`Never\` or \`OnFailure\` \u2014 \`Always\` is rejected for Jobs. With \`OnFailure\` the kubelet restarts the failed container in place; with \`Never\` the Job controller creates a fresh Pod.
- Failures are counted against \`backoffLimit\` (default 6), with exponential back-off between retries. When the limit is exceeded the Job is marked **Failed**. \`activeDeadlineSeconds\` puts a hard wall-clock limit on the whole Job.
- When enough Pods succeed, the Job gets a **Complete** condition. Its Pods are left in \`Completed\` status so you can still read their logs.
- Cleanup: the CronJob keeps the last \`successfulJobsHistoryLimit\` (default 3) and \`failedJobsHistoryLimit\` (default 1) Jobs. A plain Job can clean itself up with \`ttlSecondsAfterFinished\`.`,
    components: [
      { name: "Job", description: "Runs Pods until `completions` successes are recorded, retrying failures up to `backoffLimit`." },
      { name: "CronJob", description: "Creates a Job from `jobTemplate` each time `schedule` (standard 5-field cron syntax) fires." },
      { name: "completions / parallelism", description: "How many successful Pods are needed in total, and how many may run at the same time." },
      { name: "backoffLimit", description: "Number of retries before the Job is marked Failed (default 6)." },
      { name: "concurrencyPolicy", description: "CronJob behaviour when the previous run is still active: `Allow`, `Forbid` or `Replace`." },
      { name: "ttlSecondsAfterFinished", description: "Lets the TTL controller delete a finished Job (and its Pods) after N seconds." }
    ],
    misconceptions: [
      {
        myth: "A Job can use restartPolicy: Always like any other Pod.",
        reality: `No. The API server rejects a Job whose Pod template uses \`Always\`. Only \`Never\` and \`OnFailure\` make sense for work that is meant to finish.`
      },
      {
        myth: "Deleting a finished Job is necessary to see it stopped \u2014 Completed Pods are still running.",
        reality: `A \`Completed\` Pod has exited and uses no CPU or memory. It is kept only so you can read logs and status. Remove it with \`ttlSecondsAfterFinished\` or history limits when you no longer need it.`
      },
      {
        myth: "A CronJob guarantees exactly one run per schedule tick.",
        reality: `CronJobs are approximately once. A run can be skipped (controller down, \`Forbid\` policy, missed \`startingDeadlineSeconds\`) or, rarely, happen twice. Batch tasks should be **idempotent** \u2014 safe to run again.`
      }
    ],
    example: {
      title: "A nightly report CronJob",
      description: `Runs at 02:30 every day, never overlaps with itself, retries twice, and keeps only a short history. Trigger it manually for testing with \`kubectl create job report-manual --from=cronjob/nightly-report\`.`,
      language: "yaml",
      code: `apiVersion: batch/v1
kind: CronJob
metadata:
  name: nightly-report
spec:
  schedule: "30 2 * * *"
  concurrencyPolicy: Forbid
  successfulJobsHistoryLimit: 3
  failedJobsHistoryLimit: 1
  jobTemplate:
    spec:
      backoffLimit: 2
      activeDeadlineSeconds: 600
      template:
        spec:
          restartPolicy: Never
          containers:
            - name: report
              image: busybox:1.36
              command: ["sh", "-c", "echo generating report; sleep 5"]`
    },
    exercise: {
      prompt: `You need to process 12 files. Each Pod handles one file, and you want at most 3 Pods running at the same time. Which two Job fields do you set, and to what values? What happens if one Pod crashes?`,
      solution: `Set \`completions: 12\` and \`parallelism: 3\`. The Job controller keeps up to 3 Pods running until 12 have succeeded.

If a Pod crashes, the failure counts against \`backoffLimit\`. With \`restartPolicy: Never\` the controller creates a replacement Pod after a back-off delay; with \`OnFailure\` the container is restarted in the same Pod. Once failures exceed \`backoffLimit\`, the whole Job is marked Failed.`
    },
    faq: [
      {
        q: "Which API group are Jobs and CronJobs in?",
        a: `Both are in \`batch/v1\`. CronJob graduated to \`batch/v1\` (GA) in Kubernetes 1.21.`
      },
      {
        q: "What time zone does a CronJob schedule use?",
        a: `By default, the time zone of the kube-controller-manager. You can set \`spec.timeZone\` (for example \`"Europe/Berlin"\`) to make it explicit.`
      },
      {
        q: "How do I see why a Job failed?",
        a: `\`kubectl describe job <name>\` shows conditions and events; then \`kubectl logs\` on one of its Pods (they carry the label \`job-name=<name>\`) shows the application output.`
      }
    ],
    keyTerms: ["Job", "CronJob", "completions", "parallelism", "backoffLimit", "concurrencyPolicy", "ttlSecondsAfterFinished", "idempotency"],
    deeper: `**Indexed Jobs** (\`completionMode: Indexed\`) give each Pod a stable index (exposed as the \`JOB_COMPLETION_INDEX\` environment variable), so Pod 0 processes shard 0, and so on \u2014 the basis for static work partitioning. A **podFailurePolicy** lets a Job fail fast on non-retryable exit codes or ignore Pod disruptions (such as preemption) instead of burning \`backoffLimit\`. Jobs can also be suspended with \`spec.suspend: true\`, which queueing systems such as Kueue use to admit batch work only when capacity is available.`,
    references: [
      { title: "Kubernetes docs: Jobs", url: "https://kubernetes.io/docs/concepts/workloads/controllers/job/" },
      { title: "Kubernetes docs: CronJob", url: "https://kubernetes.io/docs/concepts/workloads/controllers/cron-jobs/" }
    ]
  },
  {
    id: "daemonsets-and-statefulsets",
    title: "DaemonSets and StatefulSets",
    stage: 2,
    order: 5,
    objectives: ["kf-core"],
    scope: "kcna",
    estMinutes: 20,
    summary: "DaemonSets run one Pod per eligible node for node-level agents; StatefulSets give Pods stable names, ordered rollout and their own persistent volumes for stateful apps.",
    what: `Both are workload controllers that exist because a Deployment's assumption \u2014 "all replicas are identical and interchangeable" \u2014 does not always hold.

A **DaemonSet** ensures that **every eligible node runs exactly one copy** of a Pod. You do not set a replica count; the number of nodes is the replica count. Add a node and a Pod appears on it; remove the node and the Pod is garbage-collected.

A **StatefulSet** manages Pods that each have a **persistent identity**: a stable ordinal name (\`db-0\`, \`db-1\`, \`db-2\`), a stable DNS name via a headless Service, and **its own PersistentVolumeClaim** that follows that name across rescheduling.`,
    why: `Think of a Deployment as a taxi rank: any car will do. A DaemonSet is a security guard posted at **every** building entrance. A StatefulSet is a numbered seat in a parliament: seat 2 is always seat 2, keeps its own desk drawer (volume), and members are sworn in in order.

Log shippers (Fluent Bit), node metrics exporters, CNI agents and kube-proxy itself need to be on every node \u2014 that is the DaemonSet case. Databases, message brokers and consensus systems (PostgreSQL replicas, Kafka, etcd, ZooKeeper) need peers to find each other by name and keep their data \u2014 that is the StatefulSet case.`,
    problem: `Try running a three-node database with a Deployment. Pods get random names like \`db-7c9d4-xk2lp\`; when one is replaced, its name and IP change, so the other members no longer recognise it. Worse, all replicas share one PVC template \u2014 or none \u2014 so a replacement Pod starts with an empty disk.

Try running a log agent with a Deployment of 5 replicas on 5 nodes. The scheduler may place two on one node and none on another, and when you scale the cluster to 8 nodes, three nodes are silently uncovered.`,
    how: `**DaemonSet, step by step:**

- The DaemonSet controller lists nodes and checks which ones match the Pod template's \`nodeSelector\`/affinity and tolerate the node's taints.
- For each eligible node without a Pod, it creates one with node affinity pinning it to that node; the default scheduler then binds it there.
- It automatically adds tolerations for conditions such as \`not-ready\` and \`unreachable\`, so node agents keep running on unhealthy nodes. To run on control-plane nodes you must add a toleration for the control-plane taint yourself.
- Updates use \`RollingUpdate\` (default) or \`OnDelete\`.

**StatefulSet, step by step (default \`OrderedReady\` policy):**

- \`spec.serviceName\` points at a **headless Service** (\`clusterIP: None\`) that gives each Pod a DNS name: \`db-0.db.<namespace>.svc.cluster.local\`.
- The controller creates \`db-0\`, waits until it is Running and Ready, then creates \`db-1\`, and so on.
- For each Pod it creates a PVC from \`volumeClaimTemplates\`, named \`<template>-<pod>\` (e.g. \`data-db-0\`). If \`db-1\` is rescheduled to another node, it re-attaches to \`data-db-1\`.
- Scaling down removes the highest ordinal first. Rolling updates also go from the highest ordinal down.
- PVCs are **kept** by default when Pods are deleted or the StatefulSet is scaled down \u2014 data safety over tidiness.`,
    components: [
      { name: "DaemonSet", description: "One Pod per eligible node; replica count follows the node count." },
      { name: "StatefulSet", description: "Ordered, uniquely named Pods with stable network identity and per-Pod storage." },
      { name: "Headless Service", description: "A Service with `clusterIP: None`; DNS returns individual Pod records instead of one virtual IP. Required by `serviceName`." },
      { name: "volumeClaimTemplates", description: "PVC template stamped out once per StatefulSet Pod (`data-db-0`, `data-db-1` \u2026)." },
      { name: "podManagementPolicy", description: "`OrderedReady` (default, one at a time) or `Parallel` (create/delete all at once)." }
    ],
    misconceptions: [
      {
        myth: "A StatefulSet makes your application highly available and replicates its data.",
        reality: `It only provides identity, ordering and per-Pod storage. Replication, leader election and failover are the **application's** job (or an operator's). Three StatefulSet Pods running a non-clustered database are three unrelated databases.`
      },
      {
        myth: "DaemonSet Pods always run on every node, including control-plane nodes.",
        reality: `Only on nodes they are eligible for. Control-plane nodes usually carry the \`node-role.kubernetes.io/control-plane:NoSchedule\` taint, so you must add a matching toleration to cover them. A \`nodeSelector\` can restrict a DaemonSet to a subset (e.g. only GPU nodes).`
      },
      {
        myth: "Deleting a StatefulSet deletes its data.",
        reality: `By default the PVCs created from \`volumeClaimTemplates\` remain. You delete them explicitly (or configure a retention policy) when you really want the data gone.`
      }
    ],
    example: {
      title: "A minimal StatefulSet with its headless Service",
      description: `Each Pod gets its own 1 GiB volume and a predictable DNS name. Watch the ordered start with \`kubectl get pods -l app=db -w\`: \`db-0\` becomes Ready before \`db-1\` is created.`,
      language: "yaml",
      code: `apiVersion: v1
kind: Service
metadata:
  name: db
spec:
  clusterIP: None
  selector:
    app: db
  ports:
    - port: 5432
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: db
spec:
  serviceName: db
  replicas: 3
  selector:
    matchLabels:
      app: db
  template:
    metadata:
      labels:
        app: db
    spec:
      containers:
        - name: postgres
          image: postgres:16
          env:
            - name: POSTGRES_PASSWORD
              value: example-only
          volumeMounts:
            - name: data
              mountPath: /var/lib/postgresql/data
  volumeClaimTemplates:
    - metadata:
        name: data
      spec:
        accessModes: ["ReadWriteOnce"]
        resources:
          requests:
            storage: 1Gi`
    },
    exercise: {
      prompt: `For each workload, pick Deployment, DaemonSet or StatefulSet: (a) a Prometheus node exporter, (b) a stateless REST API, (c) a 3-member etcd cluster, (d) a CNI agent such as Cilium's, (e) a Redis cache whose data can be lost on restart.`,
      solution: `(a) **DaemonSet** \u2014 it reads per-node metrics, so one per node. (b) **Deployment** \u2014 interchangeable replicas. (c) **StatefulSet** \u2014 members need stable names to form a quorum and keep their own data. (d) **DaemonSet** \u2014 networking must be configured on every node. (e) **Deployment** \u2014 if no data must survive and no peer identity is needed, a StatefulSet adds complexity for nothing.`
    },
    faq: [
      {
        q: "Why must the headless Service exist before the StatefulSet is useful?",
        a: `The per-Pod DNS records (\`db-0.db...\`) are published by the cluster DNS based on that Service. Without it, Pods still start but peers cannot reach each other by stable name.`
      },
      {
        q: "Can I scale a DaemonSet with kubectl scale?",
        a: `No. A DaemonSet has no \`replicas\` field. You change its footprint by adding or removing nodes, or by changing its node selector, affinity or tolerations.`
      },
      {
        q: "If db-1 crashes, does it come back as db-1?",
        a: `Yes. The StatefulSet controller recreates a Pod with the same name, the same DNS name and the same PVC (\`data-db-1\`). Its IP address may change, which is why peers should use DNS names rather than IPs.`
      }
    ],
    keyTerms: ["DaemonSet", "StatefulSet", "headless Service", "volumeClaimTemplates", "ordinal index", "stable network identity", "podManagementPolicy"],
    deeper: `StatefulSets support \`updateStrategy.rollingUpdate.partition\`: only Pods with an ordinal **greater than or equal to** the partition are updated, which enables manual canaries of stateful systems. Newer releases add \`persistentVolumeClaimRetentionPolicy\` (\`whenDeleted\` / \`whenScaled\`: \`Retain\` or \`Delete\`) to control PVC cleanup. In production, most stateful systems are run through **operators** (CRD + controller) that encode replication and failover logic on top of StatefulSets.`,
    references: [
      { title: "Kubernetes docs: DaemonSet", url: "https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/" },
      { title: "Kubernetes docs: StatefulSets", url: "https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/" }
    ]
  },
  {
    id: "resources-requests-limits",
    title: "Resource Requests, Limits and QoS",
    stage: 2,
    order: 6,
    objectives: ["kf-scheduling"],
    scope: "kcna",
    estMinutes: 22,
    summary: "Requests reserve capacity and drive scheduling; limits cap usage at runtime. Together they determine a Pod\u2019s QoS class, and namespaces can enforce defaults and totals with LimitRange and ResourceQuota.",
    what: `Each container can declare two numbers per resource (mainly \`cpu\` and \`memory\`):

- A **request** is what the container is **guaranteed**. The scheduler uses requests \u2014 not actual usage \u2014 to decide whether a Pod fits on a node.
- A **limit** is the **maximum** the container may use. The kubelet and the container runtime enforce it through Linux cgroups.

CPU is measured in cores: \`1\` = one vCPU, \`250m\` = a quarter of one (m = millicores). Memory is measured in bytes with suffixes: \`128Mi\` (mebibytes, powers of 2) or \`128M\` (megabytes, powers of 10).`,
    why: `Without requests the scheduler is flying blind: it may pack twenty Pods onto a node that can really carry five, and they all slow down or crash together. Without limits one leaking container can starve every neighbour on the node \u2014 the classic "noisy neighbour".

Requests and limits are also how Kubernetes decides **who gets evicted first** when a node runs out of memory. Declaring them is how you tell the cluster which workloads matter.`,
    problem: `A team deploys a Java service with no requests or limits. In testing it is fine. In production, under load, its heap grows to 6 GiB on an 8 GiB node. The kernel's OOM killer starts killing processes; the kubelet starts evicting Pods to recover memory. Because the Java Pod and most of its neighbours declared nothing, they are all **BestEffort** \u2014 the first in line to be evicted \u2014 and an unrelated payment service goes down with it.

With a memory request of 2 GiB and limit of 3 GiB, the scheduler would have reserved space, and the runaway process would have been OOMKilled alone at 3 GiB.`,
    how: `Trace one Pod through its life:

- **Admission**: if the namespace has a **LimitRange**, missing requests/limits are filled in with defaults (and min/max are validated). If it has a **ResourceQuota**, the Pod is rejected when it would push the namespace total over the quota.
- **Scheduling**: the scheduler sums the requests of all containers and compares them with each node's **allocatable** capacity minus the requests already placed there. If no node fits, the Pod stays \`Pending\` with an event like \`0/3 nodes are available: 3 Insufficient cpu\`.
- **Runtime \u2014 CPU**: CPU is **compressible**. A container that hits its CPU limit is **throttled** (slowed down), never killed.
- **Runtime \u2014 memory**: memory is **not compressible**. A container that exceeds its memory limit is killed by the kernel; Kubernetes reports \`OOMKilled\` (exit code 137) and restarts it according to \`restartPolicy\`.
- **Node pressure**: if the whole node runs low on memory, the kubelet evicts Pods, generally **BestEffort** first, then **Burstable** Pods using more than their requests, and **Guaranteed** last.

The **QoS class** is computed automatically from the containers' settings:

- **Guaranteed** \u2014 every container has CPU and memory requests **equal** to limits.
- **Burstable** \u2014 at least one request or limit is set, but the Guaranteed rule is not met.
- **BestEffort** \u2014 no requests or limits on any container.`,
    components: [
      { name: "requests", description: "Reserved amount; used by the scheduler for placement and by the kubelet for eviction ranking." },
      { name: "limits", description: "Hard ceiling enforced via cgroups: CPU throttling, memory OOM kill." },
      { name: "QoS class", description: "Guaranteed, Burstable or BestEffort \u2014 derived from requests/limits, visible in `status.qosClass`." },
      { name: "LimitRange", description: "Per-namespace policy that sets default requests/limits and min/max per container or Pod." },
      { name: "ResourceQuota", description: "Per-namespace cap on the **sum** of requests/limits and on object counts (Pods, Services, PVCs \u2026)." }
    ],
    misconceptions: [
      {
        myth: "The scheduler places Pods based on how much CPU and memory nodes are actually using.",
        reality: `The default scheduler uses **requests**, not live usage. A node that is 90% idle can still be "full" if Pods on it have requested all its allocatable capacity.`
      },
      {
        myth: "A container that exceeds its CPU limit is killed.",
        reality: `CPU over-use is **throttled**. Only memory over-use leads to an OOM kill. If your app is slow but never restarts, suspect CPU throttling.`
      },
      {
        myth: "If I set only a limit, the request is zero.",
        reality: `If a limit is set and the request is omitted, the request **defaults to the limit**. A container with only limits for both CPU and memory therefore ends up Guaranteed.`
      }
    ],
    example: {
      title: "A Burstable container, and how to check it",
      description: `Requests differ from limits, so this Pod is **Burstable**. After applying, confirm with \`kubectl get pod api -o jsonpath='{.status.qosClass}'\` and see live usage with \`kubectl top pod api\` (requires metrics-server).`,
      language: "yaml",
      code: `apiVersion: v1
kind: Pod
metadata:
  name: api
spec:
  containers:
    - name: api
      image: nginx:1.27
      resources:
        requests:
          cpu: 250m
          memory: 128Mi
        limits:
          cpu: 500m
          memory: 256Mi`
    },
    exercise: {
      prompt: `Classify each Pod's QoS class. Pod A: one container, requests cpu 1 / memory 1Gi, limits cpu 1 / memory 1Gi. Pod B: two containers; the first like Pod A, the second with no resources at all. Pod C: one container with limits cpu 500m / memory 512Mi and no requests. Pod D: no resources anywhere.`,
      solution: `**A: Guaranteed** \u2014 requests equal limits for both CPU and memory.

**B: Burstable** \u2014 Guaranteed requires *every* container to meet the rule; the second container breaks it, but something is set, so it is not BestEffort.

**C: Guaranteed** \u2014 omitted requests default to the limits, so requests equal limits.

**D: BestEffort** \u2014 nothing is declared; first to be evicted under memory pressure.`
    },
    faq: [
      {
        q: "Should I always set a CPU limit?",
        a: `It is debated. Memory limits are widely recommended because memory cannot be reclaimed. CPU limits can cause throttling even when the node has idle CPU, so some teams set CPU requests but no CPU limit. For the exam, know what each does; for production, measure.`
      },
      {
        q: "What does OOMKilled with exit code 137 mean?",
        a: `137 = 128 + 9: the process received SIGKILL. With reason \`OOMKilled\`, the container exceeded its memory limit (or the node ran out of memory). Raise the limit or fix the leak.`
      },
      {
        q: "What is the difference between LimitRange and ResourceQuota?",
        a: `LimitRange works **per container/Pod** (defaults and bounds for one object). ResourceQuota works **per namespace in aggregate** (the total of all objects). They are often used together: once a quota on CPU/memory exists, every Pod must declare those values, and a LimitRange supplies defaults so Pods are not rejected.`
      }
    ],
    keyTerms: ["requests", "limits", "QoS class", "Guaranteed / Burstable / BestEffort", "CPU throttling", "OOMKilled", "LimitRange", "ResourceQuota"],
    deeper: `Node **allocatable** = capacity minus \`kube-reserved\`, \`system-reserved\` and eviction thresholds, so Pods can never request the whole machine. Beyond CPU and memory you can request \`ephemeral-storage\`, hugepages and **extended resources** such as \`nvidia.com/gpu\` advertised by device plugins. Recent releases also add **in-place Pod resize**, which changes container resources without recreating the Pod \u2014 check the feature state for your cluster version before relying on it.`,
    references: [
      { title: "Kubernetes docs: Resource Management for Pods and Containers", url: "https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/" },
      { title: "Kubernetes docs: Resource Quotas", url: "https://kubernetes.io/docs/concepts/policy/resource-quotas/" },
      { title: "Kubernetes docs: Limit Ranges", url: "https://kubernetes.io/docs/concepts/policy/limit-range/" }
    ]
  },
  {
    id: "health-probes",
    title: "Health Probes: Liveness, Readiness, Startup",
    stage: 2,
    order: 7,
    objectives: ["kf-core", "co-troubleshooting"],
    scope: "kcna",
    estMinutes: 18,
    summary: "Probes let the kubelet ask a container \u201Care you alive?\u201D, \u201Ccan you take traffic?\u201D and \u201Chave you finished starting?\u201D. Each answer triggers a different action: restart, remove from load balancing, or wait.",
    what: `A **probe** is a periodic check the **kubelet** runs against a container. There are three kinds, and the exam loves to test which action each one triggers:

- **Liveness probe** \u2014 "Is the process stuck?" Failure \u2192 the kubelet **restarts the container**.
- **Readiness probe** \u2014 "Should this Pod receive traffic right now?" Failure \u2192 the Pod is marked **not Ready** and removed from Service endpoints. **No restart.**
- **Startup probe** \u2014 "Has the app finished booting?" While it has not yet succeeded, liveness and readiness probes are **not run**. If it never succeeds within its budget, the container is restarted.`,
    why: `A container whose process is running is not necessarily healthy. A web server can deadlock and still hold its port; an app can be up but waiting for its database. By default Kubernetes only knows "process running or not". Probes let the application tell the platform what "healthy" really means, so self-healing and load balancing act on the right signal.`,
    problem: `Here is a failure story worth remembering. A team adds a liveness probe that calls \`/health\`, and \`/health\` checks the database. One afternoon the database is slow for 30 seconds. Every replica's liveness probe fails at once, the kubelet restarts **every** Pod, the restarted Pods hammer the recovering database with fresh connections, and a 30-second blip becomes a 15-minute outage.

The fix: dependency checks belong in the **readiness** probe (stop sending traffic, but do not restart). The liveness probe should only check whether **this process** is able to make progress.`,
    how: `Trace the kubelet's loop for a container with all three probes:

- Container starts. If \`initialDelaySeconds\` is set, wait that long.
- **Startup phase**: run the startup probe every \`periodSeconds\`. Liveness and readiness are suspended. Success \u2192 move on. \`failureThreshold\` consecutive failures \u2192 restart the container.
- **Steady state**: run liveness and readiness probes independently, each on its own \`periodSeconds\` (default 10s), each with \`timeoutSeconds\` (default 1s).
- A probe "fails" after \`failureThreshold\` (default 3) consecutive failures, and "succeeds" after \`successThreshold\` (default 1) consecutive successes.
- Liveness failure \u2192 kill and restart the container (subject to the Pod's \`restartPolicy\`). Repeated restarts show up as \`CrashLoopBackOff\`.
- Readiness failure \u2192 the Pod's \`Ready\` condition becomes False; the EndpointSlice controller marks it not ready, so Services stop routing to it. When it passes again, traffic returns.

Each probe uses one **mechanism**:

- \`httpGet\` \u2014 success if HTTP status is 200\u2013399.
- \`tcpSocket\` \u2014 success if a TCP connection opens.
- \`exec\` \u2014 runs a command in the container; success if exit code is 0.
- \`grpc\` \u2014 uses the standard gRPC health checking protocol.`,
    components: [
      { name: "livenessProbe", description: "Detects a stuck container; failure restarts it." },
      { name: "readinessProbe", description: "Gates traffic; failure removes the Pod from Service endpoints without restarting it." },
      { name: "startupProbe", description: "Protects slow-starting apps; holds off the other probes until it succeeds once." },
      { name: "Probe mechanisms", description: "`httpGet`, `tcpSocket`, `exec`, `grpc`." },
      { name: "Timing fields", description: "`initialDelaySeconds`, `periodSeconds`, `timeoutSeconds`, `failureThreshold`, `successThreshold`." }
    ],
    misconceptions: [
      {
        myth: "A failing readiness probe restarts the container.",
        reality: `Readiness never restarts anything. It only controls whether the Pod receives Service traffic. Restarts come from liveness (or startup) probe failures, or from the process exiting.`
      },
      {
        myth: "More probes checking more dependencies is always safer.",
        reality: `A liveness probe that depends on external systems turns a dependency outage into a cluster-wide restart storm. Keep liveness local and cheap.`
      },
      {
        myth: "Probes are executed by the control plane.",
        reality: `The **kubelet** on the Pod's node runs them. The control plane only sees the results through Pod status updates.`
      }
    ],
    example: {
      title: "Three probes on one container",
      description: `The startup probe gives the app up to 30 \xD7 5 = 150 seconds to boot. After that, liveness checks a cheap local endpoint and readiness checks whether the app can actually serve.`,
      language: "yaml",
      code: `apiVersion: v1
kind: Pod
metadata:
  name: shop
  labels:
    app: shop
spec:
  containers:
    - name: shop
      image: example.com/shop:2.3.1
      ports:
        - containerPort: 8080
      startupProbe:
        httpGet:
          path: /healthz
          port: 8080
        periodSeconds: 5
        failureThreshold: 30
      livenessProbe:
        httpGet:
          path: /healthz
          port: 8080
        periodSeconds: 10
        failureThreshold: 3
      readinessProbe:
        httpGet:
          path: /ready
          port: 8080
        periodSeconds: 5`
    },
    exercise: {
      prompt: `A Pod shows \`READY 0/1\` and \`STATUS Running\` with \`RESTARTS 0\` for ten minutes. Another Pod shows \`RESTARTS 14\` and \`STATUS CrashLoopBackOff\`. For each, which probe (if any) is the likely culprit, and where do you look first?`,
      solution: `**First Pod**: running but never Ready and never restarted \u2192 the **readiness probe** is failing. Run \`kubectl describe pod\` and look for \`Readiness probe failed\` events, then check what the endpoint depends on.

**Second Pod**: repeated restarts \u2192 either the process keeps exiting by itself or the **liveness (or startup) probe** keeps failing. \`kubectl describe pod\` shows \`Liveness probe failed\` events if probes are the cause; \`kubectl logs --previous\` shows the output of the last crashed instance.`
    },
    faq: [
      {
        q: "Do I always need all three probes?",
        a: `No. Readiness is the most broadly useful for anything behind a Service. Add liveness only if your app can hang without exiting. Add startup when boot time is long or variable, instead of inflating \`initialDelaySeconds\`.`
      },
      {
        q: "What happens if I configure no probes?",
        a: `The container is considered live as long as its process runs, and ready as soon as it starts. Traffic may hit it before it can serve.`
      },
      {
        q: "Can liveness and readiness use the same endpoint?",
        a: `They can, but then a failure triggers both actions at the same threshold. Using separate endpoints (or a longer liveness \`failureThreshold\`) lets the Pod drop out of traffic first and be restarted only if it does not recover.`
      }
    ],
    keyTerms: ["liveness probe", "readiness probe", "startup probe", "kubelet", "failureThreshold", "CrashLoopBackOff", "Ready condition"],
    deeper: `Readiness interacts with rollouts: a Deployment counts a new Pod as available only after it is Ready for \`minReadySeconds\`, so a broken readiness probe stalls a rolling update instead of taking the service down. Pods can also declare **readiness gates** (\`spec.readinessGates\`) so an external controller \u2014 for example a cloud load balancer controller \u2014 must set an extra condition before the Pod counts as Ready.`,
    references: [
      { title: "Kubernetes docs: Liveness, Readiness and Startup Probes", url: "https://kubernetes.io/docs/concepts/configuration/liveness-readiness-startup-probes/" },
      { title: "Kubernetes task: Configure Liveness, Readiness and Startup Probes", url: "https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/" }
    ]
  },
  {
    id: "scheduling-placement",
    title: "Scheduling and Pod Placement",
    stage: 2,
    order: 8,
    objectives: ["kf-scheduling"],
    scope: "kcna",
    estMinutes: 25,
    summary: "The kube-scheduler filters out nodes that cannot run a Pod, scores the rest, and binds the Pod to the winner. nodeSelector, affinity, taints/tolerations and priority let you steer that decision.",
    what: `**Scheduling** is the act of choosing a node for a Pod that has none (\`spec.nodeName\` is empty). The **kube-scheduler** does this and records the decision by creating a **Binding**; the kubelet on that node then starts the Pod. The scheduler never starts containers itself.

You influence the choice with a set of tools that differ in **who expresses the preference**:

- The **Pod** asks for nodes: \`nodeSelector\`, **node affinity**.
- The **Pod** asks to be near or away from other Pods: **pod affinity / anti-affinity**.
- The **node** pushes Pods away: **taints**, which only Pods with matching **tolerations** may ignore.
- Pods compete for space: **PriorityClass** and **preemption**.`,
    why: `Not all nodes are equal. Some have GPUs or fast SSDs, some sit in a different availability zone, some are reserved for a team or for the control plane. And not all Pods should be placed independently: replicas of one service should spread across zones, while a cache may want to sit next to its app. Placement rules turn these needs into declarations the scheduler can act on.`,
    problem: `Without placement rules, all three replicas of a critical API can land on the same node \u2014 they "spread" only by accident. When that node is drained for maintenance, the service goes down even though it had three replicas.

Conversely, without taints, an expensive GPU node fills up with ordinary web Pods, and the ML job that needs the GPU stays \`Pending\`.`,
    how: `The scheduling cycle for one Pod:

- **Queue**: new Pods without a node enter the scheduling queue, ordered by priority.
- **Filter** (predicates): drop every node that cannot run the Pod \u2014 insufficient allocatable CPU/memory for the Pod's requests, \`nodeSelector\` or required node affinity not matched, an untolerated \`NoSchedule\`/\`NoExecute\` taint, a required pod anti-affinity rule violated, a host port already in use, and so on.
- **Score** (priorities): rank the remaining nodes \u2014 e.g. preferred affinity, spreading replicas, balancing resource usage, whether the image is already present.
- **Bind**: pick the highest score and write the binding to the API server.
- **No feasible node?** The Pod stays \`Pending\` with an event such as \`0/4 nodes are available: 1 node(s) had untolerated taint ..., 3 Insufficient memory\`. If the Pod has a higher priority than some running Pods, the scheduler may **preempt** (evict) lower-priority Pods to make room.

The steering tools:

- **nodeSelector** \u2014 simplest: the node must have all these labels.
- **Node affinity** \u2014 expressive version: \`requiredDuringSchedulingIgnoredDuringExecution\` (hard filter) and \`preferredDuringSchedulingIgnoredDuringExecution\` (weighted score), with operators like \`In\`, \`NotIn\`, \`Exists\`.
- **Pod affinity / anti-affinity** \u2014 relative to other Pods' labels within a \`topologyKey\` such as \`kubernetes.io/hostname\` (same node) or \`topology.kubernetes.io/zone\` (same zone).
- **Taints and tolerations** \u2014 a taint is \`key=value:Effect\` on a node. Effects: \`NoSchedule\` (no new Pods without toleration), \`PreferNoSchedule\` (avoid if possible), \`NoExecute\` (also evicts running Pods that do not tolerate it).`,
    components: [
      { name: "kube-scheduler", description: "Control-plane component that filters, scores and binds unscheduled Pods." },
      { name: "nodeSelector", description: "Hard requirement on node labels, exact key/value match." },
      { name: "Node affinity", description: "Required or preferred rules on node labels with set-based operators." },
      { name: "Pod (anti-)affinity", description: "Co-locate with or keep away from Pods matching a label selector, per topology domain." },
      { name: "Taints & tolerations", description: "Node-side repulsion; a toleration permits (but does not force) placement on a tainted node." },
      { name: "PriorityClass", description: "Gives Pods a priority value used for queue order and preemption." }
    ],
    misconceptions: [
      {
        myth: "A toleration makes a Pod run on the tainted node.",
        reality: `A toleration only **allows** it. To **attract** a Pod to dedicated nodes you combine a toleration (allowed in) with node affinity or \`nodeSelector\` (must go there).`
      },
      {
        myth: '"IgnoredDuringExecution" means the rule is ignored.',
        reality: `It means the rule is checked **at scheduling time only**. If node labels change later, already-running Pods are not evicted. (\`NoExecute\` taints, by contrast, do evict.)`
      },
      {
        myth: "The scheduler starts the Pod on the chosen node.",
        reality: `The scheduler only writes the binding. The **kubelet** on that node sees a Pod assigned to it and starts the containers via the container runtime.`
      }
    ],
    example: {
      title: "Dedicating GPU nodes and spreading replicas",
      description: `First taint and label the GPU node so ordinary Pods stay off. Then the GPU workload both tolerates the taint and requires the label, and anti-affinity keeps its replicas on different nodes.`,
      language: "yaml",
      code: `# kubectl taint nodes gpu-node-1 dedicated=gpu:NoSchedule
# kubectl label nodes gpu-node-1 accelerator=nvidia
apiVersion: apps/v1
kind: Deployment
metadata:
  name: trainer
spec:
  replicas: 2
  selector:
    matchLabels:
      app: trainer
  template:
    metadata:
      labels:
        app: trainer
    spec:
      tolerations:
        - key: dedicated
          operator: Equal
          value: gpu
          effect: NoSchedule
      affinity:
        nodeAffinity:
          requiredDuringSchedulingIgnoredDuringExecution:
            nodeSelectorTerms:
              - matchExpressions:
                  - key: accelerator
                    operator: In
                    values: ["nvidia"]
        podAntiAffinity:
          requiredDuringSchedulingIgnoredDuringExecution:
            - labelSelector:
                matchLabels:
                  app: trainer
              topologyKey: kubernetes.io/hostname
      containers:
        - name: trainer
          image: example.com/trainer:1.0`
    },
    exercise: {
      prompt: `A Pod is \`Pending\`. \`kubectl describe pod\` shows: \`0/3 nodes are available: 1 node(s) had untolerated taint {node-role.kubernetes.io/control-plane: }, 2 Insufficient cpu.\` Explain what the scheduler did and name two possible fixes.`,
      solution: `The **filter** phase eliminated all three nodes: the control-plane node because the Pod does not tolerate its \`NoSchedule\` taint, and both workers because the Pod's **CPU request** exceeds their remaining allocatable CPU. With zero feasible nodes there is nothing to score, so the Pod stays Pending.

Fixes: lower the Pod's CPU request if it is over-stated; free capacity (scale down other workloads or add nodes, e.g. via Cluster Autoscaler); or give the Pod a higher priority so it can preempt lower-priority Pods. Adding a control-plane toleration is possible but usually a bad idea for application workloads.`
    },
    faq: [
      {
        q: "What happens if I set spec.nodeName directly?",
        a: `The scheduler is bypassed entirely \u2014 the kubelet on that node just tries to run the Pod. Resource and taint checks by the scheduler are skipped, so this is rarely what you want.`
      },
      {
        q: "Why do my control-plane nodes run no application Pods?",
        a: `kubeadm-style clusters taint them with \`node-role.kubernetes.io/control-plane:NoSchedule\`. Only Pods that tolerate that taint (typically system DaemonSets) run there.`
      },
      {
        q: "Can I run more than one scheduler?",
        a: `Yes. A Pod chooses one with \`spec.schedulerName\`; the default is \`default-scheduler\`.`
      }
    ],
    keyTerms: ["kube-scheduler", "filtering and scoring", "nodeSelector", "node affinity", "pod anti-affinity", "taint", "toleration", "preemption"],
    deeper: `**topologySpreadConstraints** are a more direct way to spread Pods evenly across zones or nodes than anti-affinity, using \`maxSkew\` and \`whenUnsatisfiable\`. The scheduler itself is built on a **scheduling framework** of plugins (QueueSort, PreFilter, Filter, Score, Reserve, Permit, Bind \u2026) configured through a \`KubeSchedulerConfiguration\`, which is how features like these are implemented and how custom placement logic is added without forking the scheduler.`,
    references: [
      { title: "Kubernetes docs: Assigning Pods to Nodes", url: "https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/" },
      { title: "Kubernetes docs: Taints and Tolerations", url: "https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/" },
      { title: "Kubernetes docs: Scheduling, Preemption and Eviction", url: "https://kubernetes.io/docs/concepts/scheduling-eviction/" }
    ]
  },
  // ───────────────────────────── Stage 3 · Networking ─────────────────────────────
  {
    id: "pod-networking-and-cni",
    title: "The Pod Network Model and CNI",
    stage: 3,
    order: 1,
    objectives: ["co-networking"],
    scope: "kcna",
    estMinutes: 20,
    summary: "Kubernetes requires a flat network where every Pod has its own IP and can reach every other Pod without NAT. It does not implement that network itself \u2014 a CNI plugin such as Calico, Cilium or Flannel does.",
    what: `The **Kubernetes network model** is a short list of requirements, not an implementation:

- Every Pod gets its **own IP address**. Containers in the same Pod share it (and talk to each other over \`localhost\`).
- Every Pod can reach every other Pod, on any node, **without NAT** \u2014 the IP a Pod sees for itself is the IP others see.
- Agents on a node (such as the kubelet) can reach all Pods on that node.

The **Container Network Interface (CNI)** is a CNCF specification for plugins that set up this network. Kubernetes ships **no** Pod network of its own: a fresh cluster without a CNI plugin has nodes that stay \`NotReady\` and Pods that cannot start networking.`,
    why: `The "IP-per-Pod, no NAT" rule makes Pods behave like small VMs on a flat network. Applications can use normal ports without collisions (two Pods can both listen on 8080), service discovery can hand out real IPs, and network policies can match real source addresses.

Compare this with plain Docker on a single host, where containers sit behind NAT and you juggle host-port mappings like \`-p 8081:80\`, \`-p 8082:80\`. That model does not scale to thousands of containers across hundreds of machines.`,
    problem: `Making every Pod reachable from every node is genuinely hard: Pods come and go every second, each node needs a slice of addresses, and packets must find their way across a physical network that knows nothing about Pod IPs.

Every environment solves this differently \u2014 cloud VPC routing, BGP in a data centre, an overlay tunnel on a laptop. A pluggable interface lets Kubernetes stay neutral while each environment picks the right plugin.`,
    how: `Trace what happens when a Pod is created on a node:

- The kubelet asks the **container runtime** (containerd or CRI-O, via CRI) to create the **Pod sandbox**. The runtime creates a new **network namespace** for the Pod (held open by the small "pause" container).
- The runtime calls the configured **CNI plugin binary** (configured under \`/etc/cni/net.d/\`) with the operation \`ADD\`, the namespace path and the container ID.
- The plugin creates a virtual interface pair (a **veth pair**): one end becomes \`eth0\` inside the Pod, the other stays on the host. Its **IPAM** part allocates an IP from the node's Pod CIDR range.
- The plugin programs routes so traffic can reach this Pod: either by **routing** (e.g. Calico distributing routes via BGP, or cloud VPC routes) or by an **overlay** that wraps Pod packets in node-to-node packets (e.g. VXLAN in Flannel).
- The IP is returned to the runtime and reported in \`status.podIP\`. When the Pod is deleted, the runtime calls \`DEL\` to clean up.

Popular plugins to recognise:

- **Flannel** \u2014 simple overlay (VXLAN). Does **not** enforce NetworkPolicy by itself.
- **Calico** \u2014 routed networking (BGP) or overlay, with strong NetworkPolicy support.
- **Cilium** \u2014 built on **eBPF** in the Linux kernel; NetworkPolicy including L7, observability via Hubble, can replace kube-proxy.`,
    components: [
      { name: "CNI specification", description: "CNCF standard defining how a runtime calls network plugins (`ADD`, `DEL`, `CHECK`) and the JSON config format." },
      { name: "CNI plugin", description: "Executable (often deployed as a DaemonSet that installs it) that wires Pods into the network." },
      { name: "IPAM", description: "IP address management: hands out Pod IPs from a per-node or pooled range." },
      { name: "veth pair", description: "Virtual cable connecting the Pod\u2019s network namespace to the host." },
      { name: "Overlay vs routed", description: "Overlay encapsulates Pod traffic between nodes (VXLAN, Geneve); routed mode makes Pod IPs routable on the underlying network." }
    ],
    misconceptions: [
      {
        myth: "kube-proxy gives Pods their IP addresses.",
        reality: `Pod IPs come from the **CNI plugin**. kube-proxy deals with **Service** virtual IPs, translating them to Pod IPs.`
      },
      {
        myth: "Every CNI plugin enforces NetworkPolicies.",
        reality: `NetworkPolicy objects are accepted by the API server regardless, but they only take effect if the CNI plugin implements them. Plain Flannel silently ignores them.`
      },
      {
        myth: "Containers in the same Pod each get their own IP.",
        reality: `All containers in a Pod share one network namespace and one IP. They reach each other on \`localhost\` and must not listen on the same port.`
      }
    ],
    example: {
      title: "Seeing the flat network",
      description: `Pod IPs are visible directly and reachable from other Pods on other nodes. Here a throwaway Pod fetches a page from another Pod by IP (the IP comes from the first command).`,
      language: "bash",
      code: `kubectl get pods -o wide
# NAME          READY   STATUS    IP            NODE
# web-6d4b-abc  1/1     Running   10.244.1.12   worker-1
# web-6d4b-def  1/1     Running   10.244.2.7    worker-2

kubectl run tmp --rm -it --image=busybox:1.36 --restart=Never -- \\
  wget -qO- http://10.244.2.7:80

# Which CNI is installed? Usually a DaemonSet in kube-system:
kubectl get daemonsets -n kube-system`
    },
    exercise: {
      prompt: `You create a new cluster with kubeadm. All nodes report \`NotReady\` and CoreDNS Pods are stuck in \`Pending\` or \`ContainerCreating\`. What is the most likely missing piece, and why does it affect CoreDNS but not the static control-plane Pods?`,
      solution: `**No CNI plugin is installed.** The kubelet reports the node NotReady because the container runtime's network is not ready, and ordinary Pods like CoreDNS cannot get a Pod network.

The control-plane Pods (kube-apiserver, etcd \u2026) run with \`hostNetwork: true\`: they use the node's own network namespace, so they do not need CNI. Installing a plugin (e.g. applying the Calico, Cilium or Flannel manifests) makes nodes Ready and lets CoreDNS start.`
    },
    faq: [
      {
        q: "Is CNI only used by Kubernetes?",
        a: `No. CNI is a generic CNCF specification also used by other container platforms. Kubernetes uses it through the container runtime.`
      },
      {
        q: "Do Pod IPs stay the same when a Pod is recreated?",
        a: `Generally no. A replacement Pod gets a new IP. That is why clients use **Services** and DNS instead of Pod IPs.`
      },
      {
        q: "Can I run two CNI plugins?",
        a: `Normally one plugin owns the Pod network. Some setups chain plugins (for example a main plugin plus a bandwidth or port-mapping plugin), and meta-plugins such as Multus attach extra interfaces \u2014 that is beyond KCNA.`
      }
    ],
    keyTerms: ["Kubernetes network model", "CNI", "IP-per-Pod", "network namespace", "veth pair", "IPAM", "overlay network", "eBPF"],
    deeper: `Three address ranges coexist in a cluster: **node IPs** (the machines), the **Pod CIDR** (often split into a per-node range recorded in \`node.spec.podCIDR\`), and the **Service CIDR** (virtual IPs that exist only in kube-proxy rules, never on an interface). They must not overlap with each other or with networks the cluster needs to reach. Dual-stack (IPv4 + IPv6) clusters give each Pod one address of each family.`,
    references: [
      { title: "Kubernetes docs: Cluster Networking", url: "https://kubernetes.io/docs/concepts/cluster-administration/networking/" },
      { title: "Kubernetes docs: Services, Load Balancing, and Networking", url: "https://kubernetes.io/docs/concepts/services-networking/" },
      { title: "CNI project on GitHub", url: "https://github.com/containernetworking/cni" }
    ]
  },
  {
    id: "services",
    title: "Services and kube-proxy",
    stage: 3,
    order: 2,
    objectives: ["co-networking"],
    scope: "kcna",
    estMinutes: 25,
    summary: "A Service gives a changing set of Pods one stable name and virtual IP. Its type decides who can reach it: ClusterIP (inside), NodePort (node ports), LoadBalancer (external LB) or ExternalName (DNS alias).",
    what: `A **Service** is a stable front door for a group of Pods selected by **labels**. Pods are ephemeral \u2014 they are replaced, rescheduled, scaled, and every replacement gets a new IP. The Service stays put: it has a fixed **virtual IP (ClusterIP)**, a DNS name, and a port, and it load-balances connections across whichever matching Pods are Ready right now.

Service **types**, each building on the previous one:

- **ClusterIP** (default) \u2014 reachable only from inside the cluster.
- **NodePort** \u2014 also opens the same port (default range **30000\u201332767**) on **every node**.
- **LoadBalancer** \u2014 also asks the cloud provider (or a bare-metal implementation like MetalLB) for an external load balancer pointing at the node ports.
- **ExternalName** \u2014 no proxying at all; DNS returns a **CNAME** to an external hostname.

Plus a special case: a **headless** Service (\`clusterIP: None\`) gets no virtual IP; DNS returns the Pod IPs directly.`,
    why: `Without Services, every client would need to discover current Pod IPs itself and handle every restart. Services decouple **who provides** a function from **where it currently runs** \u2014 the core of service discovery in Kubernetes. They also give you a built-in, if basic, L4 load balancer.`,
    problem: `A frontend hard-codes the backend Pod IP \`10.244.2.7\`. The backend Deployment rolls out a new version; the new Pods have new IPs; the frontend fails with "connection refused". Then someone scales the backend to 5 replicas and the frontend keeps sending everything to one of them.

A Service named \`backend\` fixes both: clients call \`backend:8080\`, and the platform keeps the Pod list current.`,
    how: `Follow a request from a client Pod to \`backend:80\` (ClusterIP):

- The client resolves \`backend\` via cluster DNS and gets the Service's ClusterIP, e.g. \`10.96.40.12\`.
- Meanwhile the **EndpointSlice controller** has been watching Pods that match the Service's \`selector\` and recording their IPs, ports and readiness in **EndpointSlice** objects.
- **kube-proxy**, running on every node, watches Services and EndpointSlices and programs the node's packet-handling rules (iptables, IPVS or nftables mode).
- The client sends a packet to \`10.96.40.12:80\`. No interface owns this IP. The node's rules match it and rewrite (**DNAT**) the destination to one Ready Pod, e.g. \`10.244.1.12:8080\` \u2014 the Service's \`targetPort\`.
- The packet travels over the Pod network to that Pod; the reply is translated back so the client sees it coming from the Service IP.

For **NodePort**, the same rules also match traffic arriving at \`<any-node-IP>:<nodePort>\`. For **LoadBalancer**, the cloud load balancer sends traffic to the node ports (or, in some implementations, directly to Pods).

Ports to keep straight: \`port\` = the Service's port; \`targetPort\` = the container's port (defaults to \`port\`); \`nodePort\` = the port on each node.`,
    components: [
      { name: "Service", description: "Stable virtual IP + DNS name + port for a label-selected set of Pods." },
      { name: "EndpointSlice", description: "Scalable list of backend addresses and their readiness; replaced the older single Endpoints object for large Services." },
      { name: "kube-proxy", description: "Node agent that turns Services into packet-forwarding rules (iptables, IPVS or nftables). Some CNIs, like Cilium, can replace it." },
      { name: "ClusterIP / NodePort / LoadBalancer", description: "Increasingly exposed Service types; each includes the capabilities of the previous one." },
      { name: "ExternalName", description: "DNS-only alias (CNAME) to an external name; no selector, no proxying." },
      { name: "Headless Service", description: "`clusterIP: None`; DNS returns Pod IPs, used by StatefulSets and client-side load balancing." }
    ],
    misconceptions: [
      {
        myth: "You can ping a ClusterIP.",
        reality: `A ClusterIP is a virtual address that exists only in forwarding rules for the declared ports. ICMP ping usually fails even when the Service works. Test with the actual protocol, e.g. \`wget\` or \`curl\` to the port.`
      },
      {
        myth: "kube-proxy is a proxy that every request passes through.",
        reality: `In its normal modes kube-proxy only **programs kernel rules**; packets are forwarded by the kernel, not by the kube-proxy process. The name comes from an early userspace mode.`
      },
      {
        myth: "A Service sends traffic to all Pods that match its selector.",
        reality: `Only to **Ready** Pods. A Pod failing its readiness probe is marked not ready in the EndpointSlice and receives no new traffic.`
      }
    ],
    example: {
      title: "A ClusterIP Service in front of a Deployment",
      description: `The selector must match the Pod template labels, and \`targetPort\` must match the container port. Check the result with \`kubectl get endpointslices -l kubernetes.io/service-name=backend\` \u2014 an empty list of endpoints almost always means a selector or readiness problem.`,
      language: "yaml",
      code: `apiVersion: v1
kind: Service
metadata:
  name: backend
spec:
  type: ClusterIP        # the default; may be omitted
  selector:
    app: backend
  ports:
    - name: http
      port: 80           # clients connect to backend:80
      targetPort: 8080   # container listens on 8080`
    },
    exercise: {
      prompt: `A Service \`web\` of type NodePort shows \`80:31080/TCP\`. Its selector is \`app: web\`, but the Deployment's Pods are labelled \`app: website\`. List what works and what fails for (a) \`curl web\` from another Pod, (b) \`curl <nodeIP>:31080\` from outside, and say how you would detect the root cause quickly.`,
      solution: `Both **fail**: DNS resolves \`web\` and the node port is open, but the Service has **no endpoints**, so there is nowhere to forward traffic (typically "connection refused" or a timeout).

Detect it with \`kubectl get endpointslices -l kubernetes.io/service-name=web\` (or \`kubectl describe service web\`, which shows an empty \`Endpoints\` line) and compare \`kubectl get pods --show-labels\` with the Service selector. Fix the selector or the labels.`
    },
    faq: [
      {
        q: "Which Service type should I use to expose an HTTP app to the internet?",
        a: `Usually not one LoadBalancer per app. Use a ClusterIP Service behind an **Ingress** or **Gateway API** controller, which itself is exposed by one LoadBalancer and routes by host and path.`
      },
      {
        q: "Can a Service point at something outside the cluster?",
        a: `Yes: use \`ExternalName\` for a DNS alias, or create a Service **without a selector** and manage its EndpointSlices yourself to point at fixed IPs.`
      },
      {
        q: "What does kubectl expose do?",
        a: `It creates a Service for an existing resource, copying its selector \u2014 e.g. \`kubectl expose deployment backend --port=80 --target-port=8080\` creates a ClusterIP Service.`
      }
    ],
    keyTerms: ["ClusterIP", "NodePort", "LoadBalancer", "ExternalName", "headless Service", "EndpointSlice", "kube-proxy", "targetPort"],
    diagram: "service-networking",
    deeper: `\`externalTrafficPolicy: Local\` makes NodePort/LoadBalancer traffic go only to Pods on the receiving node, which preserves the client source IP and avoids an extra hop at the cost of uneven balancing. \`internalTrafficPolicy\` and topology-aware routing similarly keep in-cluster traffic close to the client. \`sessionAffinity: ClientIP\` pins a client to one backend. IPVS mode scales better than iptables for very large numbers of Services, and newer releases add an nftables mode.`,
    references: [
      { title: "Kubernetes docs: Service", url: "https://kubernetes.io/docs/concepts/services-networking/service/" },
      { title: "Kubernetes docs: EndpointSlices", url: "https://kubernetes.io/docs/concepts/services-networking/endpoint-slices/" },
      { title: "Kubernetes docs: Virtual IPs and Service Proxies", url: "https://kubernetes.io/docs/reference/networking/virtual-ips/" }
    ]
  },
  {
    id: "dns-and-coredns",
    title: "Cluster DNS and CoreDNS",
    stage: 3,
    order: 3,
    objectives: ["co-networking"],
    scope: "kcna",
    estMinutes: 16,
    summary: "CoreDNS gives every Service (and some Pods) a predictable DNS name such as backend.shop.svc.cluster.local, and each Pod\u2019s resolv.conf is set up so short names like backend just work.",
    what: `Kubernetes clusters run a DNS server \u2014 today almost always **CoreDNS**, a CNCF graduated project \u2014 as a Deployment in \`kube-system\`, exposed by a Service that is still named \`kube-dns\` for compatibility.

It answers queries for cluster names following a fixed pattern:

- Service: \`<service>.<namespace>.svc.<cluster-domain>\` \u2192 the ClusterIP (an A/AAAA record). The cluster domain is usually \`cluster.local\`.
- Headless Service: the same name \u2192 the IPs of all Ready Pods.
- StatefulSet Pod behind a headless Service: \`<pod>.<service>.<namespace>.svc.cluster.local\`, e.g. \`db-0.db.shop.svc.cluster.local\`.
- Named ports also get **SRV** records: \`_http._tcp.backend.shop.svc.cluster.local\`.

Anything outside the cluster domain is forwarded to upstream resolvers.`,
    why: `Services give stable IPs, but nobody wants to configure \`10.96.40.12\` in an app. DNS is the universal service-discovery protocol every language and library already speaks, so Kubernetes publishes Services in DNS and applications can say \`http://backend\`.`,
    problem: `Consider the question "why can my Pod reach \`backend\` but not \`backend\` in another namespace?" Answering it requires understanding search domains. Or "why are my external API lookups slow?" \u2014 that comes from the \`ndots\` setting. DNS issues are among the most common networking tickets in Kubernetes, and most come from not knowing how a short name expands.`,
    how: `Trace a lookup of \`backend\` from a Pod in namespace \`shop\`:

- When the kubelet creates the Pod (with the default \`dnsPolicy: ClusterFirst\`), it writes the Pod's \`/etc/resolv.conf\`:

\`\`\`text
nameserver 10.96.0.10
search shop.svc.cluster.local svc.cluster.local cluster.local
options ndots:5
\`\`\`

- \`nameserver\` is the ClusterIP of the \`kube-dns\` Service, so queries are load-balanced across CoreDNS Pods.
- \`backend\` has fewer than 5 dots, so the resolver tries the **search list** in order: \`backend.shop.svc.cluster.local\` first. That matches, so CoreDNS returns the ClusterIP.
- To reach a Service in another namespace, use at least \`backend.payments\` (which expands to \`backend.payments.svc.cluster.local\`) or the full name.
- CoreDNS knows the answer because its **kubernetes plugin** watches Services and EndpointSlices through the API server and builds records in memory.
- For \`api.example.com\` (2 dots < 5), the resolver first tries the search domains (all NXDOMAIN), then the name as-is, which CoreDNS **forwards** upstream.

CoreDNS behaviour is configured by a **Corefile** stored in the \`coredns\` ConfigMap in \`kube-system\`.`,
    components: [
      { name: "CoreDNS", description: "Plugin-based DNS server; the default cluster DNS since Kubernetes 1.13; CNCF graduated." },
      { name: "kube-dns Service", description: "ClusterIP Service in `kube-system` fronting the CoreDNS Pods; its IP is the Pods\u2019 nameserver." },
      { name: "Corefile", description: "CoreDNS configuration (in the `coredns` ConfigMap): kubernetes plugin, forward, cache, etc." },
      { name: "resolv.conf search list", description: "Lets short names expand to `<name>.<ns>.svc.cluster.local`." },
      { name: "dnsPolicy", description: "`ClusterFirst` (default), `Default` (inherit node resolver), `ClusterFirstWithHostNet`, `None` (use `dnsConfig`)." }
    ],
    misconceptions: [
      {
        myth: "dnsPolicy: Default is the default DNS policy.",
        reality: `Confusingly, no. The default is \`ClusterFirst\`. \`Default\` means "inherit the node's resolver" and gives the Pod **no** cluster DNS.`
      },
      {
        myth: "A short Service name resolves across all namespaces.",
        reality: `A bare name only resolves within the Pod's **own** namespace (first search domain). Other namespaces need \`name.namespace\` or the FQDN.`
      },
      {
        myth: "Every Pod gets a DNS name based on its Pod name.",
        reality: `Stable per-Pod names exist for Pods behind a headless Service with \`hostname\`/\`subdomain\` set \u2014 which StatefulSets do automatically. Ordinary Deployment Pods are addressed through their Service name.`
      }
    ],
    example: {
      title: "Debugging name resolution from inside the cluster",
      description: `A temporary Pod lets you see exactly what an application Pod sees.`,
      language: "bash",
      code: `kubectl run dnstest --rm -it --image=busybox:1.36 --restart=Never -n shop -- sh
# inside the Pod:
cat /etc/resolv.conf
nslookup backend                                # same namespace
nslookup backend.payments                       # other namespace
nslookup backend.payments.svc.cluster.local     # fully qualified
exit

# Is CoreDNS healthy?
kubectl get pods -n kube-system -l k8s-app=kube-dns
kubectl logs -n kube-system -l k8s-app=kube-dns`
    },
    exercise: {
      prompt: `A Pod in namespace \`web\` calls \`http://orders:8080\` and gets "could not resolve host". The \`orders\` Service exists in namespace \`sales\` and has endpoints. Explain the failure and give two correct names the client could use.`,
      solution: `The short name expands only through the Pod's search list, starting with \`orders.web.svc.cluster.local\` \u2014 there is no \`orders\` Service in \`web\`, and the other search domains (\`orders.svc.cluster.local\`, \`orders.cluster.local\`) do not match a Service either.

Use \`orders.sales\` or the FQDN \`orders.sales.svc.cluster.local\` (port 8080 in both cases).`
    },
    faq: [
      {
        q: "Why is the CoreDNS Service called kube-dns?",
        a: `kube-dns was the previous DNS add-on. When CoreDNS replaced it, the Service name was kept so existing configuration (and the kubelet's \`clusterDNS\` setting) kept working.`
      },
      {
        q: "Does DNS give me load balancing?",
        a: `For a normal Service, DNS returns one ClusterIP and kube-proxy does the balancing. For a headless Service, DNS returns several Pod IPs and the client decides \u2014 which is not true load balancing if the client caches the first answer.`
      }
    ],
    keyTerms: ["CoreDNS", "kube-dns", "cluster.local", "FQDN", "search domain", "ndots", "dnsPolicy", "SRV record"],
    deeper: `\`ndots:5\` means names with fewer than five dots try the search list first, so external lookups can cost several extra queries. Workarounds include using a trailing dot (\`api.example.com.\`), lowering \`ndots\` via \`dnsConfig.options\`, or running **NodeLocal DNSCache**, a DaemonSet that caches DNS on every node to cut latency and conntrack pressure.`,
    references: [
      { title: "Kubernetes docs: DNS for Services and Pods", url: "https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/" },
      { title: "Kubernetes task: Debugging DNS Resolution", url: "https://kubernetes.io/docs/tasks/administer-cluster/dns-debugging-resolution/" },
      { title: "CNCF projects", url: "https://www.cncf.io/projects/" }
    ]
  },
  {
    id: "ingress-and-gateway-api",
    title: "Ingress and the Gateway API",
    stage: 3,
    order: 4,
    objectives: ["co-networking"],
    scope: "kcna",
    estMinutes: 22,
    summary: "Ingress and Gateway API describe HTTP(S) routing from outside the cluster to Services by host and path. Both need a controller to do the work; Gateway API is the newer, role-oriented, more expressive successor.",
    what: `Both are **L7 (HTTP/HTTPS) routing APIs**: "send \`shop.example.com/api\` to Service \`api\`, everything else to Service \`web\`, terminate TLS with this certificate."

- **Ingress** (\`networking.k8s.io/v1\`) \u2014 one resource with rules (host, path \u2192 backend Service) and optional TLS. Stable, widely supported, but **feature-frozen**: no new features are being added, so controllers extend it with vendor-specific **annotations**.
- **Gateway API** (\`gateway.networking.k8s.io\`, GA since v1.0 in October 2023) \u2014 a family of resources split by role: **GatewayClass** (which implementation), **Gateway** (a listener: address, port, protocol, TLS), and **Routes** such as **HTTPRoute** (matching and forwarding rules). It is installed as **CRDs**, separately from core Kubernetes.

Neither does anything on its own. An **Ingress controller** or **Gateway API implementation** (e.g. Envoy Gateway, Istio, Cilium, NGINX Gateway Fabric, Traefik, cloud load balancer controllers) watches these objects and configures a real proxy.`,
    why: `A LoadBalancer Service per application is expensive (one cloud LB each) and only understands TCP/UDP ports. Real web traffic needs **host- and path-based routing**, TLS termination, redirects and traffic splitting \u2014 all behind **one** entry point.`,
    problem: `Ingress solved the single-entry-point problem, but its API was too small. Header matching, traffic weights, TCP/gRPC routing and cross-namespace delegation ended up in annotations that differ per controller, so a manifest written for one controller silently means nothing to another. And one Ingress object mixed concerns: the platform team's TLS/listener settings and the app team's routes lived in the same resource.

Gateway API fixes both: rich features are **portable fields**, and responsibilities are split across resources so infrastructure providers, cluster operators and app developers each own their part.`,
    how: `Trace a request to \`https://shop.example.com/api/orders\` through Gateway API:

- **Infrastructure provider** installs an implementation, which registers a **GatewayClass** (e.g. \`example-gateway-class\`).
- **Cluster operator** creates a **Gateway** in namespace \`infra\` referencing that class: listener on port 443, HTTPS, hostname \`*.example.com\`, certificate from a Secret, and \`allowedRoutes\` saying which namespaces may attach routes.
- The controller sees the Gateway and provisions/configures a data-plane proxy, usually exposed through a LoadBalancer Service with a public IP.
- **App developer** in namespace \`shop\` creates an **HTTPRoute** with \`parentRefs\` pointing at that Gateway: host \`shop.example.com\`, path prefix \`/api\` \u2192 Service \`api\` port 8080.
- The client's request hits the load balancer \u2192 proxy. The proxy terminates TLS, matches host and path, and forwards to a Ready Pod behind Service \`api\`.

With **Ingress** the same flow is collapsed: an Ingress controller (itself a Deployment exposed by a LoadBalancer Service) watches **Ingress** objects whose \`ingressClassName\` matches it, and turns each rule (\`host\`, \`path\`, \`pathType\` of \`Prefix\`/\`Exact\`/\`ImplementationSpecific\`, backend Service) into proxy configuration.`,
    components: [
      { name: "Ingress", description: "Single resource for HTTP(S) host/path routing and TLS; stable and frozen." },
      { name: "Ingress controller / IngressClass", description: "The software that implements Ingress; `ingressClassName` selects which controller handles an object." },
      { name: "GatewayClass", description: "Cluster-scoped: names a Gateway implementation (like StorageClass for storage)." },
      { name: "Gateway", description: "An instance of a load balancer/proxy with listeners (port, protocol, hostname, TLS)." },
      { name: "HTTPRoute (and GRPCRoute, \u2026)", description: "Routing rules that attach to a Gateway via `parentRefs`; support header matching, weights, redirects." }
    ],
    misconceptions: [
      {
        myth: "Creating an Ingress object exposes my app.",
        reality: `Without an Ingress controller running in the cluster, an Ingress is just stored data \u2014 nothing listens. The same is true for Gateway resources without an implementation.`
      },
      {
        myth: "Gateway API is a service mesh or an API gateway product.",
        reality: `It is a **Kubernetes API specification** (a set of CRDs). Many products implement it; some meshes also use it for east-west traffic, but the API itself is just the contract.`
      },
      {
        myth: "Ingress is deprecated and will be removed.",
        reality: `Ingress is **GA and frozen**, not deprecated. It remains supported; new capabilities go into Gateway API instead.`
      }
    ],
    example: {
      title: "The same routing as Ingress and as HTTPRoute",
      description: `Both send \`shop.example.com/api\` to Service \`api:8080\`. The HTTPRoute assumes a Gateway named \`public\` already exists in namespace \`infra\`.`,
      language: "yaml",
      code: `apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: shop
spec:
  ingressClassName: nginx
  tls:
    - hosts: ["shop.example.com"]
      secretName: shop-tls
  rules:
    - host: shop.example.com
      http:
        paths:
          - path: /api
            pathType: Prefix
            backend:
              service:
                name: api
                port:
                  number: 8080
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: shop
spec:
  parentRefs:
    - name: public
      namespace: infra
  hostnames: ["shop.example.com"]
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /api
      backendRefs:
        - name: api
          port: 8080`
    },
    exercise: {
      prompt: `You want to send 90% of traffic for \`/checkout\` to Service \`checkout-v1\` and 10% to \`checkout-v2\`, portably across implementations. Which API do you choose and which field makes it possible?`,
      solution: `**Gateway API.** An HTTPRoute rule can list several \`backendRefs\`, each with a \`weight\` (e.g. 90 and 10). Core Ingress has no standard traffic-splitting field; you would depend on controller-specific annotations.`
    },
    faq: [
      {
        q: "Does Ingress handle TCP or UDP traffic?",
        a: `Not in the standard API \u2014 Ingress is for HTTP and HTTPS. Gateway API defines \`TCPRoute\`, \`UDPRoute\` and \`TLSRoute\` (in its experimental channel at the time of writing) and \`GRPCRoute\` for gRPC.`
      },
      {
        q: "Do I need to migrate from Ingress to Gateway API now?",
        a: `For the exam, know that Gateway API is the recommended future direction and is GA. In practice, Ingress keeps working; migration is driven by needing Gateway API features or by your controller's support plans.`
      },
      {
        q: "Where does TLS get terminated?",
        a: `At the proxy run by the controller, using a certificate stored in a Kubernetes Secret (type \`kubernetes.io/tls\`) referenced from the Ingress \`tls\` section or the Gateway listener.`
      }
    ],
    keyTerms: ["Ingress", "Ingress controller", "IngressClass", "Gateway API", "GatewayClass", "Gateway", "HTTPRoute", "TLS termination"],
    diagram: "ingress-flow",
    deeper: `Gateway API ships in two release channels: **Standard** (stable resources such as GatewayClass, Gateway, HTTPRoute, GRPCRoute) and **Experimental**. **ReferenceGrant** controls cross-namespace references, for example a route in one namespace pointing at a Service in another. The **GAMMA** initiative extends Gateway API to service-mesh (east-west) traffic by attaching routes to Services instead of Gateways. Note also that the community **ingress-nginx** controller was announced for retirement by Kubernetes SIG Network; check its project status before choosing it for new clusters.`,
    references: [
      { title: "Kubernetes docs: Ingress", url: "https://kubernetes.io/docs/concepts/services-networking/ingress/" },
      { title: "Kubernetes docs: Gateway API", url: "https://kubernetes.io/docs/concepts/services-networking/gateway/" },
      { title: "Gateway API project site", url: "https://gateway-api.sigs.k8s.io/" }
    ]
  },
  {
    id: "network-policies",
    title: "NetworkPolicies",
    stage: 3,
    order: 5,
    objectives: ["co-networking", "co-security"],
    scope: "kcna",
    estMinutes: 20,
    summary: "By default every Pod can talk to every Pod. NetworkPolicies are namespaced, additive allow-lists for L3/L4 traffic, enforced by the CNI plugin, that let you move to \u201Cdeny by default, allow what is needed\u201D.",
    what: `A **NetworkPolicy** (\`networking.k8s.io/v1\`) is a namespaced object that selects Pods with a \`podSelector\` and declares which **ingress** (incoming) and/or **egress** (outgoing) connections they may have, by:

- \`podSelector\` \u2014 Pods in the same namespace with given labels;
- \`namespaceSelector\` \u2014 all Pods in namespaces with given labels;
- \`ipBlock\` \u2014 CIDR ranges (typically for traffic outside the cluster);
- \`ports\` \u2014 protocol and port.

Policies only **allow**. There is no "deny" rule. Denial comes from **isolation**: once any policy selects a Pod for a direction, everything in that direction not explicitly allowed by some policy is dropped.`,
    why: `The flat Pod network is convenient but means a compromised frontend Pod can open connections to your database, your metrics endpoints and every other namespace. NetworkPolicies give you **segmentation** \u2014 the Kubernetes version of firewall rules \u2014 and are a core part of defence in depth and zero-trust networking.`,
    problem: `Firewalls based on IP addresses do not work for Pods: IPs change every time a Pod restarts. NetworkPolicies select peers by **labels**, so "frontend may talk to backend on 8080" stays true no matter how often Pods are rescheduled.`,
    how: `Think of each Pod as having two gates, IN and OUT, both **open** by default. Evaluate a policy set like this:

- Find all policies in the Pod's namespace whose \`podSelector\` matches the Pod.
- If any of them lists \`Ingress\` in \`policyTypes\`, the IN gate becomes **isolated**: only connections matching at least one ingress rule of those policies are allowed. Same for \`Egress\` and the OUT gate.
- Allowed rules from all matching policies are **unioned** (additive). Order does not matter; there is no conflict.
- For a connection between two Pods to succeed, the source's egress **and** the destination's ingress must both allow it.
- Replies to an allowed connection are automatically permitted (policies are stateful).
- Enforcement is done by the **CNI plugin** (Calico, Cilium, etc.). The API server stores policies even if nothing enforces them.

Selector logic inside a single \`from\` entry matters:

- Two **separate list items** (\`- namespaceSelector\` and \`- podSelector\`) mean **OR**.
- \`namespaceSelector\` and \`podSelector\` in the **same** item mean **AND** (those Pods, in those namespaces).

Namespaces automatically carry the label \`kubernetes.io/metadata.name: <name>\`, which is handy for selecting a namespace by name.`,
    components: [
      { name: "podSelector (spec)", description: "Which Pods the policy applies to; `{}` selects all Pods in the namespace." },
      { name: "policyTypes", description: "`Ingress`, `Egress` or both \u2014 which directions become isolated." },
      { name: "ingress.from / egress.to", description: "Allowed peers: podSelector, namespaceSelector, ipBlock." },
      { name: "ports", description: "Allowed protocol/port pairs for the rule." },
      { name: "CNI enforcement", description: "The network plugin translates policies into data-plane rules; without support they do nothing." }
    ],
    misconceptions: [
      {
        myth: "NetworkPolicy rules are evaluated in order, like a firewall with deny rules.",
        reality: `There is no order and no deny rule in the core API. Policies are additive allow-lists; isolation provides the default deny.`
      },
      {
        myth: "Creating a NetworkPolicy always changes traffic.",
        reality: `Only if the CNI plugin enforces policies. On a cluster using plain Flannel, a default-deny policy is accepted and silently has no effect.`
      },
      {
        myth: "A default-deny egress policy only blocks external traffic.",
        reality: `It blocks **all** egress, including DNS lookups to CoreDNS. Pods suddenly cannot resolve names. You must explicitly allow UDP/TCP port 53 to the DNS Pods.`
      }
    ],
    example: {
      title: "Default-deny plus one allowed path",
      description: `The first policy isolates every Pod in \`shop\` for ingress. The second re-opens exactly one path: Pods labelled \`app: frontend\` may reach \`app: backend\` on TCP 8080.`,
      language: "yaml",
      code: `apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: default-deny-ingress
  namespace: shop
spec:
  podSelector: {}
  policyTypes: ["Ingress"]
---
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: frontend-to-backend
  namespace: shop
spec:
  podSelector:
    matchLabels:
      app: backend
  policyTypes: ["Ingress"]
  ingress:
    - from:
        - podSelector:
            matchLabels:
              app: frontend
      ports:
        - protocol: TCP
          port: 8080`
    },
    exercise: {
      prompt: `In the example above, a Pod labelled \`app: frontend\` in namespace \`web\` (not \`shop\`) tries to reach the backend. Is it allowed? How would you change the rule to allow frontends from namespace \`web\` only?`,
      solution: `**Not allowed.** A \`podSelector\` alone in a \`from\` entry only matches Pods in the **policy's own namespace** (\`shop\`).

Combine both selectors in **one** list item (AND):

\`\`\`yaml
- from:
    - namespaceSelector:
        matchLabels:
          kubernetes.io/metadata.name: web
      podSelector:
        matchLabels:
          app: frontend
\`\`\`

Writing them as two separate items (\`- namespaceSelector\` and \`- podSelector\`) would instead allow **any** Pod in \`web\` **or** frontends in \`shop\`.`
    },
    faq: [
      {
        q: "Do NetworkPolicies work at layer 7, e.g. HTTP paths?",
        a: `The core API is L3/L4 only (IPs, ports, protocols). Some CNIs (e.g. Cilium) and service meshes offer L7 policy through their own CRDs.`
      },
      {
        q: "Can a NetworkPolicy affect Pods in other namespaces?",
        a: `It only **selects** Pods in its own namespace. It can **mention** other namespaces as allowed peers via \`namespaceSelector\`.`
      },
      {
        q: "How do I test whether a policy works?",
        a: `Start a temporary Pod with the right labels in the right namespace and try to connect (e.g. \`wget\` with a short timeout). Verify that both allowed and denied paths behave as expected.`
      }
    ],
    keyTerms: ["NetworkPolicy", "podSelector", "namespaceSelector", "ipBlock", "policyTypes", "default deny", "isolation", "zero trust"],
    deeper: `Because core NetworkPolicy is namespaced and allow-only, cluster administrators who need guardrails that app teams cannot override use CNI-specific CRDs (Calico GlobalNetworkPolicy, CiliumClusterwideNetworkPolicy) or the SIG Network **AdminNetworkPolicy** API, which adds cluster scope, priorities and explicit Deny/Pass actions. \`ipBlock\` rules are also tricky for traffic that is NATed on the way in or out (e.g. through a LoadBalancer), since the source IP the Pod sees may differ from the client's.`,
    references: [
      { title: "Kubernetes docs: Network Policies", url: "https://kubernetes.io/docs/concepts/services-networking/network-policies/" },
      { title: "Kubernetes task: Declare Network Policy", url: "https://kubernetes.io/docs/tasks/administer-cluster/declare-network-policy/" }
    ]
  },
  // ─────────────────────── Stage 4 · Configuration & Storage ───────────────────────
  {
    id: "configmaps-and-secrets",
    title: "ConfigMaps and Secrets",
    stage: 4,
    order: 1,
    objectives: ["kf-core", "co-security"],
    scope: "kcna",
    estMinutes: 20,
    summary: "ConfigMaps hold non-sensitive configuration and Secrets hold sensitive values; both are injected into Pods as environment variables or files so the same image runs in every environment.",
    what: `**ConfigMap** and **Secret** are API objects that store key/value data separately from container images.

- A **ConfigMap** holds plain configuration: feature flags, URLs, whole config files.
- A **Secret** holds sensitive data: passwords, tokens, TLS keys. Values in \`data\` are **base64-encoded** \u2014 an encoding, not encryption. Secrets have a \`type\`, e.g. \`Opaque\` (generic), \`kubernetes.io/tls\`, \`kubernetes.io/dockerconfigjson\` (image pull credentials).

Both are namespaced, limited to **1 MiB**, and consumed by Pods in the same namespace in two ways: as **environment variables** or as **files in a mounted volume**.`,
    why: `The twelve-factor principle "store config in the environment" applies directly: build one immutable image, then run it in dev, staging and production with different configuration. Baking a database URL \u2014 or worse, a password \u2014 into an image means rebuilding for every environment and leaking the secret to everyone who can pull the image.

Separating Secrets from ConfigMaps also lets you apply **different access control**: many people may read ConfigMaps, very few should read Secrets.`,
    problem: `Compare two ways of getting configuration in. Option A: environment variables baked into the Dockerfile \u2014 every change is a new image build, and \`docker history\` reveals the password. Option B: values in the Pod spec directly \u2014 better, but the password now lives in your Git repository and in every \`kubectl get pod -o yaml\` output.

ConfigMaps and Secrets are Option C: the Pod **references** a named object, and the object's access can be controlled independently.`,
    how: `Walk through the life of a Secret used by a Pod:

- **Create**: \`kubectl create secret generic db --from-literal=password=s3cr3t\`. The API server stores it in **etcd**. By default it is stored unencrypted (just base64 in the API representation) unless the cluster admin configured **encryption at rest**.
- **Authorize**: only subjects whose RBAC allows \`get\` on \`secrets\` in that namespace can read it. Anyone who can create Pods in the namespace can also mount it, so Pod creation rights matter too.
- **Reference**: the Pod spec points at it via \`env.valueFrom.secretKeyRef\`, \`envFrom\`, or a \`secret\` volume.
- **Deliver**: the kubelet on the Pod's node fetches the Secret and either sets the env var at container start, or writes files into a **tmpfs** (in-memory) volume mounted into the container.
- **Update**: if you change the Secret, **mounted files** are refreshed by the kubelet after a short delay (not for \`subPath\` mounts). **Environment variables never change** in a running container \u2014 the Pod must be restarted (e.g. \`kubectl rollout restart deployment/app\`).

ConfigMaps follow exactly the same path, minus the tmpfs and the extra caution. Both can be marked \`immutable: true\`, which prevents accidental changes and reduces load on the API server.`,
    components: [
      { name: "ConfigMap", description: "Non-confidential key/value data or files; `data` (UTF-8) and `binaryData`." },
      { name: "Secret", description: "Sensitive data, base64-encoded in `data`; `stringData` accepts plain text on write." },
      { name: "env / envFrom", description: "Inject single keys (`configMapKeyRef`, `secretKeyRef`) or all keys as environment variables." },
      { name: "configMap / secret volumes", description: "Expose keys as files; updated automatically when the object changes (except subPath)." },
      { name: "Encryption at rest", description: "API server option (EncryptionConfiguration, often with a KMS provider) that encrypts Secrets in etcd." }
    ],
    misconceptions: [
      {
        myth: "Secrets are encrypted, so they are safe to commit to Git.",
        reality: `\`echo czNjcjN0 | base64 -d\` prints \`s3cr3t\`. Base64 is reversible by anyone. Never commit raw Secret manifests; use tools such as Sealed Secrets, SOPS or External Secrets Operator.`
      },
      {
        myth: "Changing a ConfigMap immediately updates the app.",
        reality: `Env vars are fixed at container start. Mounted files update eventually, but the app must also re-read them. Many apps need a restart either way.`
      },
      {
        myth: "A Pod can use a Secret from any namespace.",
        reality: `Pods can only reference ConfigMaps and Secrets in their **own** namespace.`
      }
    ],
    example: {
      title: "One ConfigMap, one Secret, two injection styles",
      description: `Created imperatively, then consumed as an env var (the password) and as a mounted file (the config). \`kubectl get secret db -o yaml\` would show \`password: czNjcjN0\` \u2014 the base64 of \`s3cr3t\`.`,
      language: "yaml",
      code: `# kubectl create configmap app-config --from-literal=LOG_LEVEL=info --from-file=app.properties
# kubectl create secret generic db --from-literal=password=s3cr3t
apiVersion: v1
kind: Pod
metadata:
  name: app
spec:
  containers:
    - name: app
      image: example.com/app:1.4
      env:
        - name: DB_PASSWORD
          valueFrom:
            secretKeyRef:
              name: db
              key: password
      envFrom:
        - configMapRef:
            name: app-config      # every key becomes an env var
      volumeMounts:
        - name: config
          mountPath: /etc/app     # app.properties appears here as a file
          readOnly: true
  volumes:
    - name: config
      configMap:
        name: app-config`
    },
    exercise: {
      prompt: `Your team rotates the database password by updating the Secret \`db\`. The app reads it from the env var \`DB_PASSWORD\`. After the rotation, the app still uses the old password. Why, and what are two ways to fix the process?`,
      solution: `Environment variables are set once when the container starts; updating the Secret does not change running containers.

Fixes: (1) restart the workload after rotation, e.g. \`kubectl rollout restart deployment/app\`; (2) mount the Secret as a **volume** and have the app re-read the file when it changes (the kubelet refreshes mounted Secrets), or use a pattern where the Secret name changes (e.g. a hash suffix generated by Kustomize) so the rollout happens automatically.`
    },
    faq: [
      {
        q: "What is the difference between data and stringData in a Secret?",
        a: `\`data\` values must be base64-encoded. \`stringData\` lets you write plain text for convenience; the API server encodes it into \`data\` on write. Reading back always shows \`data\`.`
      },
      {
        q: "Are Secrets any more secure than ConfigMaps, then?",
        a: `Somewhat: they can be encrypted at rest, are mounted on tmpfs rather than disk, are only sent to nodes running Pods that use them, and are typically guarded by stricter RBAC. But the protection comes from cluster configuration, not from base64.`
      },
      {
        q: "Can I store large files in a ConfigMap?",
        a: `No \u2014 the limit is 1 MiB per object, because it is stored in etcd. Use a volume or an object store for larger data.`
      }
    ],
    keyTerms: ["ConfigMap", "Secret", "base64", "encryption at rest", "envFrom", "secretKeyRef", "immutable", "tmpfs"],
    deeper: `Many production clusters avoid storing the source of truth for secrets in Kubernetes at all: the **Secrets Store CSI Driver** mounts secrets directly from a vault (HashiCorp Vault, cloud secret managers), and **External Secrets Operator** syncs them into Kubernetes Secrets. Encryption at rest with a **KMS v2** provider keeps the data-encryption keys outside the cluster. For least privilege, avoid granting \`list\` or \`watch\` on Secrets \u2014 both return full Secret contents, not just names.`,
    references: [
      { title: "Kubernetes docs: ConfigMaps", url: "https://kubernetes.io/docs/concepts/configuration/configmap/" },
      { title: "Kubernetes docs: Secrets", url: "https://kubernetes.io/docs/concepts/configuration/secret/" },
      { title: "The Twelve-Factor App: Config", url: "https://12factor.net/config" }
    ]
  },
  {
    id: "volumes",
    title: "Volumes: Ephemeral and Projected Storage",
    stage: 4,
    order: 2,
    objectives: ["co-storage"],
    scope: "kcna",
    estMinutes: 18,
    summary: "A container\u2019s filesystem is wiped on every restart. Volumes attach storage to the Pod instead, with lifetimes ranging from \u201Cas long as the Pod\u201D (emptyDir) to \u201Cindependent of any Pod\u201D (persistent volumes).",
    what: `A container's root filesystem is a thin writable layer on top of its image. When the container restarts, that layer is **discarded** and the container starts fresh from the image.

A **volume** is a directory defined at the **Pod** level (\`spec.volumes\`) and mounted into one or more containers (\`volumeMounts\`). Its lifetime depends on its type:

- **Ephemeral volumes** live and die with the Pod: \`emptyDir\`, \`configMap\`, \`secret\`, \`downwardAPI\`, \`projected\`, and generic ephemeral volumes.
- **Persistent volumes** outlive Pods: a \`persistentVolumeClaim\` volume pointing at storage managed by the cluster (next lesson).
- **hostPath** mounts a path from the node itself \u2014 persistent on that node, but tied to it.`,
    why: `Two everyday needs drive volumes. First, **survive a container restart**: a cache or scratch file should not vanish because the liveness probe restarted the container. Second, **share files between containers** in the same Pod: a sidecar that ships logs written by the main container, or an init container that downloads content for the web server to serve.

Volumes are also the delivery mechanism for configuration files and credentials (ConfigMap, Secret, ServiceAccount token).`,
    problem: `A web Pod has two containers: \`nginx\` serves \`/usr/share/nginx/html\`, and a \`git-sync\` sidecar pulls new content every minute. Each container has its own isolated filesystem, so whatever the sidecar writes is invisible to nginx. An \`emptyDir\` mounted into both containers is the shared directory they need.`,
    how: `Step through the lifecycle of the volume types you must know:

- **emptyDir**: created empty by the kubelet when the Pod is assigned to a node. All containers that mount it see the same files. It **survives container restarts** but is **deleted when the Pod is removed** from the node. \`medium: Memory\` backs it with tmpfs (RAM, counted against memory limits); \`sizeLimit\` caps it.
- **configMap / secret**: the kubelet writes each key as a file; updates propagate to the mounted files after a delay (not for \`subPath\` mounts). Secret volumes use tmpfs.
- **downwardAPI**: exposes Pod metadata \u2014 labels, annotations, resource limits \u2014 as files.
- **projected**: combines several of the above (secret, configMap, downwardAPI, serviceAccountToken) into **one** directory. This is how every Pod receives its short-lived ServiceAccount token at \`/var/run/secrets/kubernetes.io/serviceaccount\`.
- **hostPath**: bind-mounts a node directory. Data stays on that node, so a Pod rescheduled elsewhere sees different data. It also gives access to the host filesystem \u2014 a serious security risk, generally reserved for system agents (log collectors, CNI, CSI node plugins).
- **persistentVolumeClaim**: references a PVC; the actual storage is attached by the storage system and lives independently of the Pod.

Mounting is always two-part: declare under \`spec.volumes\` (what), then reference by name under each container's \`volumeMounts\` (where).`,
    components: [
      { name: "spec.volumes", description: "Pod-level declaration of each volume and its source type." },
      { name: "volumeMounts", description: "Per-container mount point (`mountPath`), optional `readOnly` and `subPath`." },
      { name: "emptyDir", description: "Scratch space shared by containers in a Pod; lifetime = Pod." },
      { name: "projected", description: "Merges secret, configMap, downwardAPI and serviceAccountToken sources into one mount." },
      { name: "hostPath", description: "Mounts a node path; node-bound and security-sensitive." }
    ],
    misconceptions: [
      {
        myth: "emptyDir data is lost when the container crashes.",
        reality: `It survives **container** restarts. It is lost when the **Pod** is deleted or evicted, or when the Pod is rescheduled (which means a new Pod anyway).`
      },
      {
        myth: "hostPath is a fine way to persist database data.",
        reality: `It ties data to one node and breaks when the Pod moves; it also exposes the node filesystem. Use a PersistentVolumeClaim for durable application data.`
      },
      {
        myth: "A volume belongs to a container.",
        reality: `Volumes are declared on the **Pod**. Containers opt in by mounting them, possibly at different paths and with different read/write modes.`
      }
    ],
    example: {
      title: "Sharing files between two containers via emptyDir",
      description: `The writer appends the date every 5 seconds; the reader container sees the same file. Verify with \`kubectl logs shared -c reader\`.`,
      language: "yaml",
      code: `apiVersion: v1
kind: Pod
metadata:
  name: shared
spec:
  volumes:
    - name: scratch
      emptyDir: {}
  containers:
    - name: writer
      image: busybox:1.36
      command: ["sh", "-c", "while true; do date >> /data/log.txt; sleep 5; done"]
      volumeMounts:
        - name: scratch
          mountPath: /data
    - name: reader
      image: busybox:1.36
      command: ["sh", "-c", "touch /input/log.txt; tail -f /input/log.txt"]
      volumeMounts:
        - name: scratch
          mountPath: /input
          readOnly: true`
    },
    exercise: {
      prompt: `For each event, say whether data in an \`emptyDir\` volume survives: (a) the main container is OOMKilled and restarted; (b) \`kubectl delete pod\` and the Deployment creates a replacement; (c) the node is drained; (d) a \`kubectl rollout restart\` of the Deployment.`,
      solution: `(a) **Survives** \u2014 the Pod is the same, only the container restarted.

(b), (c), (d) **Lost** \u2014 each one produces a **new Pod** (new UID, new emptyDir). If data must survive these events, it belongs in a PersistentVolumeClaim or an external store.`
    },
    faq: [
      {
        q: "What is a generic ephemeral volume?",
        a: `A volume declared with \`ephemeral.volumeClaimTemplate\` inside the Pod: Kubernetes creates a PVC for the Pod and deletes it with the Pod. You get real provisioned storage (any StorageClass) with Pod lifetime.`
      },
      {
        q: "Why use subPath?",
        a: `To mount a single file or subdirectory from a volume without hiding the rest of the target directory. Downside: subPath mounts of ConfigMaps and Secrets do not receive updates.`
      }
    ],
    keyTerms: ["volume", "volumeMounts", "emptyDir", "hostPath", "projected volume", "downwardAPI", "ephemeral volume", "subPath"],
    deeper: `Historically, many storage backends were built into Kubernetes as **in-tree** volume plugins (e.g. \`awsElasticBlockStore\`, \`gcePersistentDisk\`). These have been migrated to **CSI** drivers, with the in-tree code redirected or removed, so new clusters should always use CSI-backed storage. The **image volume** source, which mounts the contents of an OCI image as a read-only volume, is a newer addition worth watching.`,
    references: [
      { title: "Kubernetes docs: Volumes", url: "https://kubernetes.io/docs/concepts/storage/volumes/" },
      { title: "Kubernetes docs: Ephemeral Volumes", url: "https://kubernetes.io/docs/concepts/storage/ephemeral-volumes/" },
      { title: "Kubernetes docs: Projected Volumes", url: "https://kubernetes.io/docs/concepts/storage/projected-volumes/" }
    ]
  },
  {
    id: "persistent-volumes-and-csi",
    title: "PersistentVolumes, Claims, StorageClasses and CSI",
    stage: 4,
    order: 3,
    objectives: ["co-storage"],
    scope: "kcna",
    estMinutes: 25,
    summary: "A PersistentVolumeClaim is a request for storage; a PersistentVolume is the storage that fulfils it; a StorageClass lets that storage be created on demand by a CSI driver.",
    what: `Kubernetes separates **asking for storage** from **providing storage**, much like Pods ask for CPU without caring which node provides it.

- **PersistentVolume (PV)** \u2014 a cluster-scoped object representing a real piece of storage (a cloud disk, an NFS export, a SAN LUN), with a capacity, access modes and a reclaim policy.
- **PersistentVolumeClaim (PVC)** \u2014 a namespaced request: "I need 10Gi, ReadWriteOnce, of class \`fast\`". Pods mount the **claim**, never the PV directly.
- **StorageClass** \u2014 a template naming a **provisioner** (a CSI driver) plus parameters (disk type, IOPS). It enables **dynamic provisioning**: PVs are created automatically when claims appear.
- **CSI (Container Storage Interface)** \u2014 the standard plugin interface that lets any storage vendor ship a driver without changing Kubernetes code.`,
    why: `Developers should not need to know whether production uses AWS EBS, Ceph or NetApp; they should just ask for "10Gi of fast storage". Administrators should be able to change the backend without changing every application manifest. The PV/PVC split is that contract, and CSI is what makes the backend pluggable.`,
    problem: `Before dynamic provisioning, an administrator had to pre-create disks and PVs by hand and hope they matched future requests (**static provisioning**). Teams filed tickets and waited. Too-large disks sat unused; too-small ones blocked deployments. Storage drivers were compiled into Kubernetes itself, so supporting a new storage system meant changing and releasing Kubernetes.

StorageClasses with CSI drivers make storage self-service and vendor-neutral.`,
    how: `Trace dynamic provisioning for a claim named \`data\` in namespace \`shop\`:

- A developer creates the PVC: \`storageClassName: fast\`, \`accessModes: [ReadWriteOnce]\`, \`storage: 10Gi\`. If no class is named, the cluster's **default StorageClass** (marked with the annotation \`storageclass.kubernetes.io/is-default-class: "true"\`) is used.
- If the class has \`volumeBindingMode: WaitForFirstConsumer\`, nothing happens until a Pod using the claim is scheduled \u2014 so the disk is created in the **same zone** as the chosen node. With \`Immediate\`, provisioning starts right away. Until then the PVC is \`Pending\`.
- The CSI driver's **controller** component (with the \`external-provisioner\` sidecar) sees the claim and asks the storage backend to create a 10Gi volume.
- A **PV** object is created to represent the new disk and **bound** 1:1 to the claim. Both now show \`Bound\`.
- When the Pod starts on a node, the volume is **attached** to the node (for block devices) and the CSI driver's **node** component (a DaemonSet) **mounts** it into the Pod's directory.
- When the PVC is deleted, the PV's \`persistentVolumeReclaimPolicy\` decides: \`Delete\` (default for dynamically provisioned volumes) removes the backend disk; \`Retain\` keeps the PV and data for manual recovery, in state \`Released\`.

**Access modes** describe how a volume may be mounted:

- \`ReadWriteOnce\` (RWO) \u2014 read-write by a single **node**.
- \`ReadOnlyMany\` (ROX) \u2014 read-only by many nodes.
- \`ReadWriteMany\` (RWX) \u2014 read-write by many nodes (needs shared storage like NFS or CephFS).
- \`ReadWriteOncePod\` (RWOP) \u2014 read-write by a single **Pod**.`,
    components: [
      { name: "PersistentVolume", description: "Cluster-scoped representation of real storage; capacity, access modes, reclaim policy." },
      { name: "PersistentVolumeClaim", description: "Namespaced request for storage, mounted by Pods; binds 1:1 to a PV." },
      { name: "StorageClass", description: "Provisioner + parameters + reclaimPolicy + volumeBindingMode (+ allowVolumeExpansion)." },
      { name: "CSI driver", description: "Vendor plugin: a controller component (provision, attach, snapshot) and a node DaemonSet (mount)." },
      { name: "Access modes", description: "RWO, ROX, RWX, RWOP \u2014 capabilities the backend must support." },
      { name: "Reclaim policy", description: "`Delete` or `Retain` (`Recycle` is deprecated)." }
    ],
    misconceptions: [
      {
        myth: "ReadWriteOnce means only one Pod can use the volume.",
        reality: `RWO restricts to one **node**; several Pods on that same node can mount it. Use \`ReadWriteOncePod\` when you need single-Pod access.`
      },
      {
        myth: "Deleting a Pod deletes its persistent data.",
        reality: `Pods mount claims; deleting the Pod leaves the PVC and PV untouched. Data is only at risk when the **PVC** is deleted and the reclaim policy is \`Delete\`.`
      },
      {
        myth: "Any storage class can provide ReadWriteMany.",
        reality: `Access modes are capabilities of the backend. A typical cloud block disk supports RWO only; RWX needs a shared filesystem. A claim asking for an unsupported mode stays Pending.`
      }
    ],
    example: {
      title: "A StorageClass, a claim, and a Pod that uses it",
      description: `The provisioner name depends on the CSI driver installed in your cluster (\`kubectl get storageclass\` shows what exists; \`kind\` and \`minikube\` ship a default class). Check binding with \`kubectl get pvc,pv\`.`,
      language: "yaml",
      code: `apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: fast
provisioner: ebs.csi.aws.com        # example CSI driver
parameters:
  type: gp3
reclaimPolicy: Delete
volumeBindingMode: WaitForFirstConsumer
allowVolumeExpansion: true
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: data
spec:
  storageClassName: fast
  accessModes: ["ReadWriteOnce"]
  resources:
    requests:
      storage: 10Gi
---
apiVersion: v1
kind: Pod
metadata:
  name: db
spec:
  containers:
    - name: db
      image: postgres:16
      env:
        - name: POSTGRES_PASSWORD
          value: example-only
      volumeMounts:
        - name: data
          mountPath: /var/lib/postgresql/data
  volumes:
    - name: data
      persistentVolumeClaim:
        claimName: data`
    },
    exercise: {
      prompt: `A PVC has been \`Pending\` for 10 minutes. List three distinct causes you would check, and the command that reveals which one it is.`,
      solution: `Run \`kubectl describe pvc <name>\` and read the **Events**. Typical causes:

- **WaitForFirstConsumer**: no Pod using the claim has been scheduled yet \u2014 this is expected, not an error.
- **No matching provisioner/class**: the named StorageClass does not exist, there is no default class, or the CSI driver is not installed or failing.
- **No PV can satisfy it** (static provisioning): no available PV with enough capacity, the right access mode and the same class.
- Also possible: the backend rejected the request (quota, unsupported access mode such as RWX on block storage).`
    },
    faq: [
      {
        q: "Can I make a PVC bigger later?",
        a: `Yes, if the StorageClass has \`allowVolumeExpansion: true\` and the CSI driver supports it: edit \`spec.resources.requests.storage\` upward. Shrinking is not supported.`
      },
      {
        q: "Is a PV namespaced?",
        a: `No. PVs and StorageClasses are cluster-scoped; PVCs are namespaced. That is what lets administrators manage storage while teams claim it in their namespaces.`
      },
      {
        q: "Who writes CSI drivers?",
        a: `Storage vendors and projects (cloud providers, Ceph via Rook, Portworx, Longhorn \u2026). CSI is a cross-orchestrator standard, alongside CRI and CNI.`
      }
    ],
    keyTerms: ["PersistentVolume", "PersistentVolumeClaim", "StorageClass", "dynamic provisioning", "CSI", "access modes", "reclaim policy", "WaitForFirstConsumer"],
    diagram: "storage-binding",
    deeper: `CSI also powers **VolumeSnapshots** (\`VolumeSnapshot\`, \`VolumeSnapshotClass\`, \`VolumeSnapshotContent\`, mirroring PVC/StorageClass/PV) and cloning a PVC from another via \`dataSource\`. A PV can be presented as a raw block device (\`volumeMode: Block\`) instead of a filesystem. The controller side of a CSI driver is typically a Deployment running the vendor plugin plus Kubernetes-maintained sidecars (external-provisioner, external-attacher, external-resizer, external-snapshotter).`,
    references: [
      { title: "Kubernetes docs: Persistent Volumes", url: "https://kubernetes.io/docs/concepts/storage/persistent-volumes/" },
      { title: "Kubernetes docs: Storage Classes", url: "https://kubernetes.io/docs/concepts/storage/storage-classes/" },
      { title: "Kubernetes docs: Dynamic Volume Provisioning", url: "https://kubernetes.io/docs/concepts/storage/dynamic-provisioning/" }
    ]
  },
  // ─────────────────────── Stage 5 · Security & Operations ───────────────────────
  {
    id: "authentication-authorization-rbac",
    title: "Authentication, Authorization and RBAC",
    stage: 5,
    order: 1,
    objectives: ["co-security"],
    scope: "kcna",
    estMinutes: 25,
    summary: "Every API request is authenticated (who are you?), authorized (may you do this?) and admitted (is this request acceptable?). RBAC answers the second question with Roles, ClusterRoles and their bindings; ServiceAccounts give Pods an identity.",
    what: `Every call to the kube-apiserver \u2014 from \`kubectl\`, a controller or a Pod \u2014 passes three gates in order:

- **Authentication (authn)**: establishes the caller's identity \u2014 a **user** or **ServiceAccount**, plus **groups**.
- **Authorization (authz)**: decides whether that identity may perform this **verb** on this **resource** in this **namespace**.
- **Admission control**: may mutate or reject the object itself (covered in the API server lesson).

**RBAC** (Role-Based Access Control) is the standard authorizer. Its four objects:

- **Role** \u2014 a set of permissions within **one namespace**.
- **ClusterRole** \u2014 permissions that are cluster-wide or reusable across namespaces (also for cluster-scoped resources like nodes and PVs).
- **RoleBinding** \u2014 grants a Role or ClusterRole to subjects **within one namespace**.
- **ClusterRoleBinding** \u2014 grants a ClusterRole to subjects **across the whole cluster**.`,
    why: `A cluster is shared by people, CI systems, controllers and applications. Each should be able to do exactly what its job needs \u2014 the **principle of least privilege**. A CI pipeline that only deploys to \`staging\` should not be able to read Secrets in \`prod\`, and a compromised app Pod should not be able to create new Pods.`,
    problem: `A common anti-pattern: give the CI system a kubeconfig bound to \`cluster-admin\` "to make it work". Months later a leaked CI token gives an attacker full control of every namespace, every Secret and every node.

RBAC lets you replace that with a narrow, auditable grant: "\`deployments\`: get, list, update, patch \u2014 in namespace \`staging\` \u2014 for ServiceAccount \`ci-deployer\`".`,
    how: `Trace one request: ServiceAccount \`app\` in namespace \`shop\` runs \`GET /api/v1/namespaces/shop/pods\`.

- **Authenticate**: the Pod sends its **projected ServiceAccount token** (a short-lived, audience-bound JWT mounted at \`/var/run/secrets/kubernetes.io/serviceaccount/token\`). The API server validates it and identifies the caller as \`system:serviceaccount:shop:app\`, in groups \`system:serviceaccounts\` and \`system:serviceaccounts:shop\`. Humans usually authenticate with **X.509 client certificates** or **OIDC** tokens from an identity provider \u2014 Kubernetes has **no User object** and cannot create human users.
- **Build the attributes**: user, groups, verb \`list\` (a GET on a collection), resource \`pods\`, API group \`""\` (core), namespace \`shop\`.
- **Authorize**: the configured authorizers (commonly \`Node,RBAC\`) are asked in order. RBAC looks for any RoleBinding in \`shop\` or any ClusterRoleBinding whose subjects include this identity, and checks whether the referenced role has a **rule** matching apiGroup + resource + verb.
- RBAC is **additive and deny-by-default**: if no rule allows it, the answer is no (HTTP 403 Forbidden). There are no deny rules.
- If allowed, the request proceeds to admission and then to etcd.

A key pattern: a **RoleBinding can reference a ClusterRole**. The permissions then apply only inside the RoleBinding's namespace. This lets you define a role (like the built-in \`view\` or \`edit\`) once and grant it per namespace.`,
    components: [
      { name: "Role / ClusterRole", description: "Lists of rules: apiGroups + resources + verbs (get, list, watch, create, update, patch, delete \u2026)." },
      { name: "RoleBinding / ClusterRoleBinding", description: "Attach a role to subjects: User, Group or ServiceAccount." },
      { name: "ServiceAccount", description: "Namespaced identity for workloads; each namespace has a `default` one; tokens are short-lived and projected into Pods." },
      { name: "Authenticators", description: "X.509 client certs, bearer tokens (ServiceAccount, OIDC), webhook token authentication." },
      { name: "Authorization modes", description: "RBAC, Node (for kubelets), Webhook, ABAC; AlwaysAllow/AlwaysDeny for testing." },
      { name: "kubectl auth can-i", description: "Asks the API server whether an action is allowed, optionally impersonating with `--as`." }
    ],
    misconceptions: [
      {
        myth: "You can create a user with kubectl create user.",
        reality: `There is no User resource. Users are asserted by an external authenticator (certificate CN, OIDC claim). RBAC simply refers to user and group **names**.`
      },
      {
        myth: "A RoleBinding to a ClusterRole grants cluster-wide access.",
        reality: `A RoleBinding always limits the grant to its own namespace, even when it references a ClusterRole. Only a **ClusterRoleBinding** grants cluster-wide.`
      },
      {
        myth: "RBAC can deny a specific action to a user who otherwise has broad access.",
        reality: `RBAC has no deny. Permissions are the union of all bindings. To restrict, remove or narrow the broad grant.`
      }
    ],
    example: {
      title: "A read-only Pod viewer for one ServiceAccount",
      description: `Grant the ServiceAccount \`monitor\` in \`shop\` permission to read Pods and their logs, then verify by impersonating it.`,
      language: "yaml",
      code: `apiVersion: v1
kind: ServiceAccount
metadata:
  name: monitor
  namespace: shop
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: pod-reader
  namespace: shop
rules:
  - apiGroups: [""]               # "" = core API group
    resources: ["pods", "pods/log"]
    verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: monitor-reads-pods
  namespace: shop
subjects:
  - kind: ServiceAccount
    name: monitor
    namespace: shop
roleRef:
  kind: Role
  name: pod-reader
  apiGroup: rbac.authorization.k8s.io
# Verify:
#   kubectl auth can-i list pods -n shop --as=system:serviceaccount:shop:monitor     -> yes
#   kubectl auth can-i delete pods -n shop --as=system:serviceaccount:shop:monitor   -> no
#   kubectl auth can-i list pods -n prod --as=system:serviceaccount:shop:monitor     -> no`
    },
    exercise: {
      prompt: `Your platform team wants every team lead to have the built-in \`edit\` permissions, but only in their own team's namespace. Leads authenticate via OIDC and are in group \`team-a-leads\` (namespace \`team-a\`). Which objects do you create, and why not a ClusterRoleBinding?`,
      solution: `Create a **RoleBinding** in namespace \`team-a\` with subject \`kind: Group, name: team-a-leads\` and \`roleRef\` to the **ClusterRole** \`edit\`. Repeat per team namespace.

A ClusterRoleBinding to \`edit\` would grant those permissions in **every** namespace. Referencing the shared ClusterRole from a namespaced RoleBinding reuses one definition while scoping the grant.`
    },
    faq: [
      {
        q: "What identity does my Pod use if I do not set serviceAccountName?",
        a: `The \`default\` ServiceAccount of its namespace. It has no extra RBAC permissions by default, but its token is still mounted unless you set \`automountServiceAccountToken: false\`.`
      },
      {
        q: "Do ServiceAccounts still get a long-lived token Secret automatically?",
        a: `No. Since Kubernetes 1.24, token Secrets are no longer auto-generated. Pods receive short-lived projected tokens that the kubelet rotates; for other uses, \`kubectl create token <sa>\` issues a time-limited token.`
      },
      {
        q: "What is the Node authorizer for?",
        a: `It restricts each **kubelet** to reading only the Secrets, ConfigMaps and other objects related to Pods scheduled on its own node, limiting the damage if a node is compromised.`
      }
    ],
    keyTerms: ["authentication", "authorization", "Role", "ClusterRole", "RoleBinding", "ClusterRoleBinding", "ServiceAccount", "least privilege"],
    diagram: "rbac-model",
    deeper: `RBAC has built-in **escalation prevention**: you cannot create or update a Role granting permissions you do not hold yourself, unless you have the \`escalate\` verb; similarly, \`bind\` controls who may bind roles. Watch out for permissions that are effectively admin: \`create\` on Pods (can mount any Secret or ServiceAccount in the namespace), \`impersonate\`, and write access to RoleBindings. **Aggregated ClusterRoles** (\`aggregationRule\`) let CRD authors add rules to \`view\`/\`edit\`/\`admin\` automatically. The group \`system:masters\` bypasses authorization entirely, so avoid issuing certificates for it.`,
    references: [
      { title: "Kubernetes docs: Using RBAC Authorization", url: "https://kubernetes.io/docs/reference/access-authn-authz/rbac/" },
      { title: "Kubernetes docs: Authenticating", url: "https://kubernetes.io/docs/reference/access-authn-authz/authentication/" },
      { title: "Kubernetes docs: RBAC Good Practices", url: "https://kubernetes.io/docs/concepts/security/rbac-good-practices/" }
    ]
  }
];

// ../../packages/content/src/lessons/c.ts
var lessonsC = [
  // ───────────────────────────── Stage 5 ─────────────────────────────
  {
    id: "pod-security-and-least-privilege",
    title: "Pod Security and Least Privilege",
    stage: 5,
    order: 2,
    objectives: ["co-security"],
    scope: "kcna",
    estMinutes: 25,
    summary: "Harden what a container is allowed to do with securityContext, enforce cluster-wide baselines with Pod Security Standards and Pod Security Admission, and keep images trustworthy.",
    what: `RBAC decides **who may call the API**. Pod security decides **what a running container may do to the node it lands on**. They are separate layers, and you need both.

Three tools cover this lesson:

- **securityContext** \u2014 fields on a Pod or container spec that set the Linux identity and privileges of the process: user/group IDs, Linux capabilities, read-only root filesystem, privilege escalation, seccomp profile.
- **Pod Security Standards (PSS)** \u2014 three named policy levels defined by the Kubernetes project: \`privileged\`, \`baseline\` and \`restricted\`.
- **Pod Security Admission (PSA)** \u2014 the built-in admission controller that checks Pods against a PSS level, configured per namespace with labels. It replaced **PodSecurityPolicy**, which was removed in Kubernetes 1.25.

Add supply-chain basics on top: where images come from, whether they are scanned, and whether you run exactly the bytes you tested.`,
    why: `A container is just a process with namespaces and cgroups around it. If it runs as root with extra capabilities, or mounts the host filesystem, a single application bug can turn into control of the whole node \u2014 and from the node, often the whole cluster (kubelet credentials, other Pods' Secrets).

**Least privilege** shrinks the blast radius: if the process is compromised, the attacker gets a non-root user with no capabilities, a read-only filesystem and a syscall filter. Most applications need none of the defaults they get, so removing them is cheap insurance.`,
    problem: `Out of the box, Kubernetes is permissive. A Pod with no securityContext runs as whatever user the image specifies (often root), with the runtime's default capability set, and nothing stops a manifest from asking for \`privileged: true\`, \`hostNetwork: true\` or a \`hostPath\` mount of \`/\`.

Relying on every team to remember the right fields does not scale. You need a **cluster-side guardrail** that rejects dangerous Pods no matter who submits them \u2014 that is what Pod Security Admission provides.`,
    how: `Follow a Pod create request through the security layers:

- **1. Authentication and RBAC** \u2014 the API server confirms the caller may create Pods in that namespace.
- **2. Pod Security Admission** \u2014 the admission controller reads the namespace labels, e.g. \`pod-security.kubernetes.io/enforce: restricted\`. It compares the Pod spec against that level. In \`enforce\` mode a violation rejects the request; \`warn\` returns a warning to the client; \`audit\` records it in the audit log. You can set all three modes on one namespace with different levels.
- **3. Other admission policies (optional)** \u2014 ValidatingAdmissionPolicy or webhooks such as OPA Gatekeeper or Kyverno can enforce rules PSS does not cover (allowed registries, required labels).
- **4. Scheduling and kubelet** \u2014 the kubelet passes the securityContext to the container runtime, which starts the process with the requested UID, capabilities, seccomp profile and filesystem flags.
- **5. Runtime** \u2014 the kernel enforces it. A process that tries to escalate, write to a read-only root filesystem or call a blocked syscall fails.

PSA checks Pods, but the error usually surfaces on the **controller**: a Deployment is accepted, yet its ReplicaSet cannot create Pods, and the reason shows up in the ReplicaSet's events.`,
    components: [
      { name: "securityContext", description: "Pod-level (`spec.securityContext`) and container-level (`containers[].securityContext`) settings. Container-level values override Pod-level ones for the same field." },
      { name: "Pod Security Standards", description: "`privileged` (unrestricted), `baseline` (blocks known privilege escalations such as hostNetwork, hostPath, privileged containers) and `restricted` (baseline plus hardening: non-root, drop ALL capabilities, no privilege escalation, seccomp)." },
      { name: "Pod Security Admission", description: "Built-in admission controller (stable since 1.25). Configured with namespace labels `pod-security.kubernetes.io/<mode>: <level>` where mode is `enforce`, `audit` or `warn`." },
      { name: "Linux capabilities", description: 'Root\'s powers split into units such as `NET_ADMIN` or `SYS_ADMIN`. Least privilege means `drop: ["ALL"]` and add back only what is needed.' },
      { name: "seccomp", description: "A kernel syscall filter. `seccompProfile.type: RuntimeDefault` applies the container runtime's default profile, which blocks rarely needed, risky syscalls." },
      { name: "Image supply chain", description: "Trusted registries, vulnerability scanning in CI, pinning images by digest, signing images and verifying signatures at admission." }
    ],
    misconceptions: [
      { myth: "RBAC already makes my Pods secure.", reality: "RBAC controls API access. It says nothing about whether the container process runs as root or can mount the host filesystem. That is the job of securityContext and Pod Security Admission." },
      { myth: "PodSecurityPolicy is how you enforce Pod security.", reality: "PodSecurityPolicy was deprecated in 1.21 and **removed in 1.25**. The built-in replacement is Pod Security Admission with the Pod Security Standards." },
      { myth: "Containers are isolated, so running as root inside one is harmless.", reality: "Without user namespaces, UID 0 in the container is UID 0 on the host kernel. Combined with a capability, a hostPath mount or a kernel bug, that becomes host root." },
      { myth: "A pinned tag like `nginx:1.27` always gives the same image.", reality: "Tags are mutable pointers and can be re-pushed. Only a digest (`nginx@sha256:...`) identifies exact image content." }
    ],
    example: {
      title: "A namespace enforcing restricted, and a Pod that passes it",
      description: `The namespace enforces \`restricted\` and also warns on it, so \`kubectl apply\` prints a warning before rejection becomes a surprise. The Pod sets every field the restricted level requires. The image is assumed to listen on an unprivileged port such as 8080.`,
      language: "yaml",
      code: `apiVersion: v1
kind: Namespace
metadata:
  name: payments
  labels:
    pod-security.kubernetes.io/enforce: restricted
    pod-security.kubernetes.io/warn: restricted
---
apiVersion: v1
kind: Pod
metadata:
  name: api
  namespace: payments
spec:
  securityContext:
    runAsNonRoot: true
    runAsUser: 10001
    seccompProfile:
      type: RuntimeDefault
  containers:
    - name: api
      image: registry.example.com/payments/api@sha256:<digest>
      securityContext:
        allowPrivilegeEscalation: false
        readOnlyRootFilesystem: true
        capabilities:
          drop: ["ALL"]`
    },
    exercise: {
      prompt: `A Deployment in a namespace labelled \`pod-security.kubernetes.io/enforce: baseline\` contains a container with \`securityContext.privileged: true\`. \`kubectl apply\` succeeds, yet \`kubectl get pods\` shows nothing for it.

Explain what happened, where you would see the error, and two ways to resolve it.`,
      solution: `The Deployment object itself is not a Pod, so it is admitted. Its ReplicaSet then tries to create Pods, and **Pod Security Admission rejects each one** because privileged containers violate \`baseline\`.

The error appears in the ReplicaSet's events: \`kubectl describe rs <name>\` shows a \`FailedCreate\` event mentioning the violated policy.

Fixes, in order of preference:

- Remove \`privileged: true\` and grant only the specific capability or setting the app truly needs (if baseline allows it).
- If the workload genuinely needs privilege (for example a node-level agent), run it in a dedicated namespace labelled \`privileged\`, tightly restricted by RBAC.`
    },
    faq: [
      { q: "Which PSS level should I start with?", a: "Use `restricted` for ordinary application namespaces and `baseline` where a workload needs something restricted forbids. Reserve `privileged` for system namespaces running node agents (CNI, storage, monitoring daemons)." },
      { q: "How can I roll out restricted without breaking existing apps?", a: "Label the namespace with `warn` and `audit` set to `restricted` while `enforce` stays at a looser level. Fix the warnings, then raise `enforce`. You can also run `kubectl label --dry-run=server` on the namespace to see which existing Pods would violate a level." },
      { q: "Does PSA check Deployments?", a: "Enforcement applies to Pods. For workload resources, `warn` and `audit` also evaluate the Pod template so you get early feedback, but the actual rejection happens when the controller creates Pods." }
    ],
    keyTerms: ["securityContext", "Pod Security Standards", "Pod Security Admission", "least privilege", "runAsNonRoot", "Linux capabilities", "seccomp", "image digest"],
    deeper: `PSA is deliberately simple: three fixed levels, namespace granularity. Organisations needing custom rules (only images from our registry, every Pod must have resource limits) add **ValidatingAdmissionPolicy** (CEL expressions evaluated in the API server, stable since 1.30) or a policy engine webhook such as OPA Gatekeeper or Kyverno.

On the supply-chain side, the common building blocks are an **SBOM** (a list of what is inside the image), **signatures** (for example with Sigstore's cosign) verified by an admission policy, and **runtime detection** with a tool such as Falco, which watches syscalls for suspicious behaviour after the container has started.`,
    references: [
      { title: "Pod Security Standards", url: "https://kubernetes.io/docs/concepts/security/pod-security-standards/" },
      { title: "Pod Security Admission", url: "https://kubernetes.io/docs/concepts/security/pod-security-admission/" },
      { title: "Configure a Security Context for a Pod or Container", url: "https://kubernetes.io/docs/tasks/configure-pod-container/security-context/" }
    ]
  },
  {
    id: "kubectl-and-cluster-administration",
    title: "kubectl and Cluster Administration",
    stage: 5,
    order: 3,
    objectives: ["kf-admin"],
    scope: "kcna",
    estMinutes: 30,
    summary: "How kubectl finds and talks to a cluster through kubeconfig, the core verbs, how clusters are built and upgraded with kubeadm and version-skew rules, how the API is versioned, and how CRDs and operators extend it.",
    what: `**kubectl** is a client for the Kubernetes API. Every command becomes one or more HTTPS requests to kube-apiserver; kubectl has no special back door. Anything kubectl does, a CI job, Helm or a controller can do with the same API.

Cluster administration around it covers:

- **kubeconfig** \u2014 the file that tells kubectl which clusters exist, which credentials to use and which pairing (context) is active.
- **Cluster lifecycle** \u2014 creating clusters (for example with **kubeadm**), upgrading them one minor version at a time, and respecting **version skew** rules between components.
- **The API surface** \u2014 API groups and versions, and extending it with **CustomResourceDefinitions (CRDs)** and **operators**.`,
    why: `Almost every KCNA topic is reached through kubectl, so fluency is a multiplier. Equally, misunderstanding kubeconfig is how people run \`kubectl delete\` against production while thinking they are in staging.

Knowing the API's structure (groups, versions, CRDs) explains why \`apiVersion: apps/v1\` is required on a Deployment, why some features say "beta", and how tools like Argo CD or cert-manager add new resource types that kubectl handles as if they were built in.`,
    problem: `An administrator works with several clusters, several identities and many namespaces. Without a structured way to switch between them, commands go to the wrong place. Clusters also cannot be frozen: Kubernetes ships roughly three minor releases a year and each minor version is supported for about a year, so upgrades are routine, and they must not break running components that are temporarily on different versions.`,
    how: `Trace \`kubectl get pods -n shop\`:

- **1. Load kubeconfig.** kubectl reads \`--kubeconfig\` if given, else the \`KUBECONFIG\` environment variable, else \`~/.kube/config\`.
- **2. Pick the context.** \`current-context\` names a **context**, which ties together a **cluster** (API server URL and CA certificate), a **user** (client certificate, token or exec plugin) and optionally a default **namespace**. \`-n shop\` overrides the namespace.
- **3. Discover the API.** kubectl maps \`pods\` to the core group, version \`v1\`, using API discovery (cached locally).
- **4. Send the request.** \`GET /api/v1/namespaces/shop/pods\` over TLS with your credentials.
- **5. Server side.** The API server authenticates, authorizes (RBAC), and for reads returns objects from etcd. For writes, admission runs too.
- **6. Format.** kubectl prints a table, or YAML/JSON with \`-o yaml\` / \`-o json\`.

**API paths** reveal the grouping: core resources live under \`/api/v1\`; everything else under \`/apis/<group>/<version>\`, e.g. \`/apis/apps/v1\` for Deployments. Versions progress **alpha** (\`v1alpha1\`, off by default, may change or vanish), **beta** (\`v1beta1\`, more stable; new beta APIs are off by default) and **stable/GA** (\`v1\`).

**Upgrades with kubeadm**: upgrade the control plane first (\`kubeadm upgrade plan\`, then \`kubeadm upgrade apply\`), then each node in turn (drain, upgrade kubeadm/kubelet, uncordon). Skip no minor versions. Version skew rules allow the kubelet to be older than the API server (up to three minor versions) but **never newer**, and kubectl to be within one minor version of the API server, older or newer.`,
    components: [
      { name: "kubeconfig", description: "YAML file with `clusters`, `users`, `contexts` and `current-context`. Managed with `kubectl config get-contexts`, `current-context`, `use-context` and `view`." },
      { name: "kubectl verbs", description: "Read: `get`, `describe`, `logs`, `explain`, `api-resources`. Write declaratively: `apply -f`. Write imperatively: `create`, `run`, `expose`, `scale`, `set image`, `label`, `delete`. Operate: `rollout`, `drain`, `cordon`, `uncordon`." },
      { name: "kubeadm", description: "Upstream tool that bootstraps a cluster (`kubeadm init`, `kubeadm join`) and upgrades it (`kubeadm upgrade`). It does not provision machines or install a CNI plugin." },
      { name: "API groups and versions", description: "Core group (`v1`: Pods, Services, ConfigMaps) and named groups (`apps/v1`, `batch/v1`, `networking.k8s.io/v1`, `rbac.authorization.k8s.io/v1`)." },
      { name: "CustomResourceDefinition", description: "Registers a new resource type with the API server. Instances (custom resources) are stored in etcd and served like built-in objects, but nothing acts on them until a controller does." },
      { name: "Operator", description: "A custom controller plus CRDs that encodes operational knowledge for one application (e.g. a database): it watches custom resources and reconciles real infrastructure toward them." }
    ],
    misconceptions: [
      { myth: "`kubectl config use-context` changes something in the cluster.", reality: "It only edits your local kubeconfig file. The cluster is unaware of contexts." },
      { myth: "Creating a CRD gives you a working feature.", reality: "A CRD only teaches the API server to store and validate a new type. Behaviour comes from a controller (often an operator) that watches those objects." },
      { myth: "You can upgrade directly from 1.29 to 1.32 if you are careful.", reality: "Control-plane upgrades go one minor version at a time: 1.29 \u2192 1.30 \u2192 1.31 \u2192 1.32." },
      { myth: "A newer kubelet on a node is fine as long as it is close.", reality: "The kubelet must not be newer than kube-apiserver. Upgrade the control plane first, then nodes." }
    ],
    example: {
      title: "Orienting yourself in an unfamiliar cluster",
      description: "A safe, read-only sequence to run before touching anything: confirm where you are, what the server supports, and how a field is defined.",
      language: "bash",
      code: `# Where am I pointed?
kubectl config get-contexts
kubectl config current-context

# Switch, and make "staging" the default namespace for this context
kubectl config use-context staging-cluster
kubectl config set-context --current --namespace=staging

# What does this API server offer?
kubectl version
kubectl api-resources          # every resource type, its short name, group, namespaced?
kubectl api-versions           # every group/version served

# How is a field defined? (docs from the server's own schema)
kubectl explain deployment.spec.strategy

# Custom resources show up like built-ins
kubectl get crds`
    },
    exercise: {
      prompt: `Your kubeconfig has contexts \`dev\` and \`prod\`. A colleague says "I ran \`kubectl delete deploy web\` and it deleted prod's web, but I was sure I was on dev." Give the two commands that would have prevented this, and one habit that makes it less likely.`,
      solution: `- \`kubectl config current-context\` before any destructive command shows which context is active.
- \`kubectl --context dev delete deploy web\` targets a context explicitly for one command, ignoring \`current-context\`.

Habits: keep production credentials in a separate kubeconfig file selected via \`KUBECONFIG\` only when needed, show the current context in your shell prompt, and use \`--dry-run=server\` or \`kubectl diff\` before changes. RBAC that denies delete to day-to-day identities in prod is the cluster-side safety net.`
    },
    faq: [
      { q: "Is kubectl apply the same as kubectl create?", a: "`create` is imperative: it fails if the object exists. `apply` is declarative: it creates or updates the object to match the file and tracks what you previously applied, so it is the right verb for manifests kept in Git." },
      { q: "Do I need kubeadm for the exam?", a: "Know what it is for (bootstrapping and upgrading a conformant cluster) and the upgrade order. Managed services (EKS, GKE, AKS) and local tools (kind, minikube) are other ways to get a cluster." },
      { q: "What is the difference between an operator and a Helm chart?", a: "A Helm chart installs manifests once per install/upgrade. An operator keeps running and continuously reconciles, handling day-2 tasks such as backups, failover or version upgrades of the application it manages." }
    ],
    keyTerms: ["kubeconfig", "context", "API group", "kubeadm", "version skew", "CustomResourceDefinition", "operator", "kubectl explain"],
    deeper: `API deprecation follows a published policy: once an API version is GA, it is not removed within the same major version, and beta versions get a deprecation period of several releases before removal. When an API version is removed (as happened to \`extensions/v1beta1\` Ingress in 1.22), old manifests fail to apply and must be migrated.

Server-side apply (\`kubectl apply --server-side\`) moves field-ownership tracking into the API server via \`managedFields\`, so several actors (you, an HPA, an operator) can own different fields of one object without overwriting each other.`,
    references: [
      { title: "kubectl reference", url: "https://kubernetes.io/docs/reference/kubectl/" },
      { title: "Version Skew Policy", url: "https://kubernetes.io/releases/version-skew-policy/" },
      { title: "Custom Resources", url: "https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/" }
    ]
  },
  {
    id: "troubleshooting-workloads",
    title: "Troubleshooting Workloads",
    stage: 5,
    order: 4,
    objectives: ["co-troubleshooting"],
    scope: "kcna",
    estMinutes: 30,
    summary: "A repeatable method for diagnosing broken Pods: read the status, describe, check events and logs, and map the common states (Pending, ImagePullBackOff, CrashLoopBackOff, OOMKilled, not Ready) to their causes.",
    what: `Troubleshooting in Kubernetes is mostly **reading what the cluster already told you**. Every controller, the scheduler and the kubelet write their decisions into object status and into **Events**. Your job is to know where to look and how to interpret the common failure states.

This lesson is organised as a field guide: one symptom, the place to look, the usual causes.`,
    why: `Most incidents in a Kubernetes environment show up first as "the Pod is not running" or "the Service returns errors". The faster you map a symptom to the right layer \u2014 scheduling, image, process, probe, network \u2014 the less time you spend guessing. KCNA questions about troubleshooting nearly always test exactly this mapping.`,
    problem: `A failure can sit in many places: the scheduler could not place the Pod, the kubelet could not pull the image, the process exits immediately, the kernel killed it for memory, a probe fails, or a Service selector matches nothing. The status column alone (\`Pending\`, \`CrashLoopBackOff\`) is a clue, not a diagnosis.`,
    how: `Work outside-in, from cheapest signal to most detailed:

- **1. \`kubectl get pods -o wide\`** \u2014 status, restarts, READY count, node. Many restarts plus \`CrashLoopBackOff\` points at the process; \`Pending\` points at scheduling or volumes; \`0/1 READY\` but \`Running\` points at a readiness probe.
- **2. \`kubectl describe pod <name>\`** \u2014 container state and **last state** (with exit code and reason such as \`OOMKilled\` or \`Error\`), conditions, and the **Events** section at the bottom.
- **3. \`kubectl get events\`** (optionally \`--sort-by=.metadata.creationTimestamp\`) \u2014 namespace-wide view, useful when the Pod never got created (look at ReplicaSet events too). Events are retained only for a limited time (one hour by default).
- **4. \`kubectl logs <pod>\`** \u2014 application output. Add \`--previous\` to see the crashed instance's logs and \`-c <container>\` for multi-container Pods.
- **5. Check the surroundings** \u2014 Service selector vs Pod labels (\`kubectl get endpointslices\`), referenced ConfigMaps/Secrets/PVCs exist, node health (\`kubectl get nodes\`, \`kubectl describe node\`).

The symptom map:

- **Pending** \u2014 scheduler event \`FailedScheduling\`: insufficient CPU/memory for the requests, nodeSelector/affinity matches no node, untolerated taint, or an unbound PVC.
- **ErrImagePull / ImagePullBackOff** \u2014 wrong image name or tag, private registry without \`imagePullSecrets\`, or registry unreachable. Kubelet retries with increasing back-off.
- **CrashLoopBackOff** \u2014 the container starts and exits repeatedly; kubelet waits longer between restarts. Read \`logs --previous\` and the exit code. Common: bad config, missing env var or file, wrong command, failing liveness probe.
- **OOMKilled** (exit code 137) \u2014 the container exceeded its memory limit; raise the limit or fix the leak.
- **CreateContainerConfigError** \u2014 a referenced ConfigMap or Secret (or key) does not exist.
- **Running but not Ready** \u2014 readiness probe failing; the Pod is removed from Service endpoints.`,
    components: [
      { name: "Pod status and conditions", description: "`phase` (Pending, Running, Succeeded, Failed, Unknown), container states (Waiting, Running, Terminated) with reasons, and conditions such as `PodScheduled` and `Ready`." },
      { name: "Events", description: "Short-lived records emitted by components: scheduler (`FailedScheduling`), kubelet (`Pulling`, `BackOff`, `Unhealthy`), controllers (`FailedCreate`). Shown at the end of `kubectl describe`." },
      { name: "Container logs", description: "stdout/stderr captured by the runtime and served by the kubelet. `--previous` returns the last terminated instance." },
      { name: "Exit codes", description: "`0` success, `1` generic app error, `137` = killed by SIGKILL (often OOMKilled), `143` = SIGTERM (graceful stop)." },
      { name: "Node view", description: "`kubectl describe node` shows conditions (MemoryPressure, DiskPressure, Ready), taints, and allocated requests versus allocatable capacity." }
    ],
    misconceptions: [
      { myth: "CrashLoopBackOff is a Kubernetes bug or a special kind of error.", reality: "It is a waiting state: the container keeps exiting and the kubelet backs off between restarts. The real cause is in the logs of the previous instance or a failing liveness probe." },
      { myth: "A Pending Pod means the image is still downloading.", reality: "Image pulls happen after scheduling, while the Pod already has a node. A Pod stuck in Pending usually has not been scheduled; check for `FailedScheduling` events." },
      { myth: "Scheduling is based on what Pods actually use.", reality: "The scheduler compares **requests** to node allocatable capacity. A node can be nearly idle and still have no room if its requests are fully booked." }
    ],
    example: {
      title: "Diagnosing a CrashLoopBackOff end to end",
      description: "The restart count and back-off point at the process, `describe` gives the exit code, and the previous container's logs give the cause.",
      language: "text",
      code: `$ kubectl get pods
NAME                     READY   STATUS             RESTARTS      AGE
api-6f9c7d8b5d-q2xkp     0/1     CrashLoopBackOff   5 (40s ago)   4m

$ kubectl describe pod api-6f9c7d8b5d-q2xkp
...
    State:          Waiting
      Reason:       CrashLoopBackOff
    Last State:     Terminated
      Reason:       Error
      Exit Code:    1
...
Events:
  Normal   Pulled   3m    kubelet  Container image "shop/api:2.3.0" already present on machine
  Warning  BackOff  20s   kubelet  Back-off restarting failed container api in pod api-6f9c7d8b5d-q2xkp

$ kubectl logs api-6f9c7d8b5d-q2xkp --previous
FATAL: environment variable DATABASE_URL is not set

# Cause: missing configuration. Fix the Deployment's env / envFrom and re-apply.`
    },
    exercise: {
      prompt: `For each symptom, name the first command you would run and the most likely cause:

- a) Pod \`Pending\` for 10 minutes; describe shows \`0/3 nodes are available: 3 Insufficient memory\`.
- b) Pod \`Running\`, READY \`0/1\`, Service returns 503.
- c) Last state \`Terminated\`, reason \`OOMKilled\`.`,
      solution: `- a) Already found via \`kubectl describe pod\`. The memory **request** exceeds free allocatable memory on every node. Lower the request, free capacity, or add nodes (a Cluster Autoscaler would do this automatically).
- b) \`kubectl describe pod\` \u2014 look for \`Unhealthy\` events from a failing **readiness probe**. Not-ready Pods are removed from the Service's endpoints, so the Service has no backends. Check \`kubectl get endpointslices\` to confirm.
- c) \`kubectl describe pod\` confirms exit code 137. The container hit its **memory limit**; raise the limit to match real usage or fix the leak, then check \`kubectl top pod\` if metrics-server is installed.`
    },
    faq: [
      { q: "Why do I get no logs from a crashing container?", a: "The current instance may not have written anything yet. Use `kubectl logs <pod> --previous` to read the instance that crashed. If both are empty, the process may fail before logging: check the command/args and the exit code in `describe`." },
      { q: "Where are events for a Pod that was never created?", a: "On its controller. `kubectl describe replicaset <name>` (or `describe deployment`) shows `FailedCreate` events, for example from a quota or Pod Security Admission rejection." },
      { q: "How long are events kept?", a: "Only briefly \u2014 the API server default is one hour. For history, ship events and logs to an external system." }
    ],
    keyTerms: ["kubectl describe", "Events", "Pending", "ImagePullBackOff", "CrashLoopBackOff", "OOMKilled", "exit code 137", "FailedScheduling"],
    deeper: `Network problems need a different toolkit: test DNS from inside the cluster (\`nslookup my-svc.my-ns.svc.cluster.local\` from a debug Pod), compare a Service's \`selector\` with Pod labels, check that \`targetPort\` matches the container port, and remember that a NetworkPolicy selecting a Pod denies all traffic not explicitly allowed in that direction.

For node-level failures (\`NotReady\`), the usual suspects are the kubelet service, the container runtime, disk pressure or a broken CNI plugin, investigated on the node itself (for example with \`journalctl -u kubelet\`).`,
    references: [
      { title: "Debug Pods", url: "https://kubernetes.io/docs/tasks/debug/debug-application/debug-pods/" },
      { title: "Troubleshooting Applications", url: "https://kubernetes.io/docs/tasks/debug/debug-application/" },
      { title: "Pod Lifecycle", url: "https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/" }
    ]
  },
  // ───────────────────────────── Stage 6 ─────────────────────────────
  {
    id: "cicd-and-gitops",
    title: "CI/CD and GitOps",
    stage: 6,
    order: 1,
    objectives: ["cad-delivery"],
    scope: "kcna",
    estMinutes: 25,
    summary: "Continuous integration builds and tests every change; continuous delivery/deployment gets it to environments. GitOps makes Git the source of truth and lets an in-cluster agent such as Argo CD or Flux pull and reconcile it.",
    what: `**Continuous Integration (CI)** merges small changes frequently and validates each one automatically: build, unit tests, linting, image build, vulnerability scan, push to a registry.

**Continuous Delivery** keeps every validated change in a releasable state, with a final (possibly manual) approval. **Continuous Deployment** removes the manual step: every change that passes the pipeline goes to production.

**GitOps** is a way of doing the deployment half. The desired state of the system lives declaratively in Git, and a software agent running next to the system continuously pulls that state and reconciles reality toward it. The OpenGitOps project (under the CNCF) captures it as four principles:

- **Declarative** \u2014 the system's desired state is expressed declaratively.
- **Versioned and immutable** \u2014 desired state is stored so that it is versioned and retains complete history (Git is the usual choice).
- **Pulled automatically** \u2014 agents pull the desired state from the source.
- **Continuously reconciled** \u2014 agents observe actual state and act to converge it on desired state.`,
    why: `Kubernetes is already a reconciliation engine for objects inside the cluster. GitOps extends the same idea one level up: from "Git says X" to "the cluster has X". You get an audit trail for free (every change is a commit with an author and review), rollback is \`git revert\`, and **drift** \u2014 someone running \`kubectl edit\` by hand \u2014 is detected and corrected.`,
    problem: `A classic push pipeline ends with a CI job running \`kubectl apply\` against the cluster. That works, but:

- the CI system needs **write credentials for every cluster**, a juicy target;
- after the job finishes nobody watches for drift; manual changes silently persist;
- the "real" state is whatever ran last, not something you can read in one place.

GitOps inverts the direction: the cluster pulls, so cluster credentials stay inside the cluster.`,
    how: `Follow one change through a GitOps setup with two repositories, one for application code and one for configuration:

- **1. Developer opens a pull request** in the app repo. CI runs tests and builds an image, tagging it (for example with the commit SHA) and pushing it to the registry.
- **2. Config change.** CI (or an image-automation tool) opens a PR in the config repo updating the image reference in a manifest, Helm values file or Kustomize overlay. Humans review and merge.
- **3. Agent detects the change.** Argo CD or Flux, running in the cluster, polls the repo (or receives a webhook) and sees a new commit.
- **4. Render and compare.** The agent renders manifests (plain YAML, Kustomize or Helm) and diffs them against the live objects.
- **5. Sync.** It applies the difference through the Kubernetes API. Deployments then roll out as usual.
- **6. Keep watching.** If someone changes a live object by hand, the agent reports it as **OutOfSync** and, with automatic self-heal enabled, reverts it to what Git says.

Rollback is a revert commit in the config repo; the agent syncs it like any other change.`,
    components: [
      { name: "CI pipeline", description: "Build, test, scan, package. Runs in tools such as GitHub Actions, GitLab CI, Jenkins or Tekton. Its output is an immutable artifact: a container image." },
      { name: "Container registry", description: "Stores the images CI produces; the deployment references them by tag or digest." },
      { name: "Config repository", description: "Declarative desired state per environment: manifests, Helm values, Kustomize overlays." },
      { name: "Argo CD", description: "CNCF graduated GitOps tool. An `Application` resource points at a repo path and a destination cluster/namespace; a web UI shows sync and health status." },
      { name: "Flux", description: "CNCF graduated GitOps toolkit of controllers: `GitRepository` sources plus `Kustomization` and `HelmRelease` resources that reconcile them." }
    ],
    misconceptions: [
      { myth: "GitOps means storing YAML in Git.", reality: "Storing YAML in Git is version control. GitOps also requires an agent that **pulls automatically** and **continuously reconciles**, correcting drift." },
      { myth: "Continuous Delivery and Continuous Deployment are the same thing.", reality: "Delivery keeps every change deployable but may require a manual release decision. Deployment releases every passing change automatically." },
      { myth: "With GitOps you no longer need CI.", reality: "GitOps handles deploying desired state. You still need CI to test code and build the images that the desired state references." }
    ],
    example: {
      title: "An Argo CD Application with automatic sync",
      description: "This custom resource tells Argo CD to keep the `shop` namespace in sync with the `envs/prod` path of the config repo, prune objects deleted from Git, and undo manual drift.",
      language: "yaml",
      code: `apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: shop-prod
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://git.example.com/platform/shop-config.git
    targetRevision: main
    path: envs/prod
  destination:
    server: https://kubernetes.default.svc
    namespace: shop
  syncPolicy:
    automated:
      prune: true
      selfHeal: true`
    },
    diagram: "gitops-flow",
    exercise: {
      prompt: `An engineer runs \`kubectl scale deploy web --replicas=10\` during an incident in a cluster managed by Argo CD with \`selfHeal: true\`. Git says \`replicas: 3\`. What happens, and what is the GitOps-correct way to scale?`,
      solution: `Argo CD detects that the live Deployment differs from Git (**OutOfSync**) and, because self-heal is on, re-applies \`replicas: 3\` shortly afterwards. The manual change is undone.

The GitOps way is to change \`replicas\` in the config repo and merge it, so the change is reviewed, recorded and reconciled. If load varies, use a HorizontalPodAutoscaler and leave \`replicas\` out of the Git-managed manifest (or tell the tool to ignore that field) so the HPA and GitOps do not fight.`
    },
    faq: [
      { q: "Push or pull \u2014 which is GitOps?", a: "OpenGitOps requires the desired state to be **pulled automatically** by an agent. A pipeline that pushes with `kubectl apply` can deploy from Git, but it is a push-based CD pipeline, not GitOps by that definition." },
      { q: "Argo CD or Flux?", a: "Both are CNCF graduated and implement the same principles. Argo CD is application-centric with a rich UI; Flux is a set of composable controllers driven by CRDs. For KCNA, recognise both as GitOps tools." },
      { q: "Where do Secrets go if everything is in Git?", a: "Never commit plain Secrets. Common patterns are encrypting them before commit (e.g. Sealed Secrets or SOPS) or referencing an external secret store via an operator such as External Secrets." }
    ],
    keyTerms: ["continuous integration", "continuous delivery", "continuous deployment", "GitOps", "OpenGitOps", "drift", "Argo CD", "Flux"],
    deeper: `Large organisations often run one Argo CD or Flux instance per cluster (simple, isolated) or a central one managing many clusters (single pane of glass, but a high-value target). Progressive-delivery tools integrate with GitOps: Argo Rollouts and Flagger replace a Deployment's simple rolling update with metric-driven canary or blue/green steps, still triggered by a Git change.`,
    references: [
      { title: "OpenGitOps principles", url: "https://opengitops.dev/" },
      { title: "Argo CD documentation", url: "https://argo-cd.readthedocs.io/" },
      { title: "Flux documentation", url: "https://fluxcd.io/flux/" }
    ]
  },
  {
    id: "helm-and-kustomize",
    title: "Helm and Kustomize",
    stage: 6,
    order: 2,
    objectives: ["cad-delivery"],
    scope: "kcna",
    estMinutes: 25,
    summary: "Two ways to manage many similar manifests: Helm packages templated charts with releases and rollback; Kustomize layers patches over plain YAML and is built into kubectl.",
    what: `Both tools answer the same question \u2014 **how do I deploy almost the same YAML to dev, staging and prod without copy-pasting it?** \u2014 with opposite philosophies.

- **Helm** is a **package manager**. A **chart** is a directory of Go-templated manifests plus a \`values.yaml\` of defaults. Installing a chart with your values creates a **release**, which Helm tracks with numbered revisions you can upgrade and roll back. Charts are shared through repositories and OCI registries.
- **Kustomize** is a **template-free overlay** tool. You keep a **base** of ordinary, valid YAML and write **overlays** that patch it (change replicas, image tags, add labels, generate ConfigMaps). It is built into kubectl: \`kubectl apply -k <dir>\`.`,
    why: `Real applications ship as dozens of objects (Deployment, Service, ConfigMap, ServiceAccount, RBAC, Ingress...). Hand-maintaining a copy per environment guarantees drift between them. Templating or patching keeps one definition and states only the differences.

Helm also solved distribution: installing a third-party product such as an ingress controller or Prometheus stack is usually \`helm install\` with a few values.`,
    problem: `Think of a cookie recipe. Helm turns the recipe into a **form with blanks** ("{{ sugar }} grams of sugar") and you fill in a values sheet. Kustomize keeps the **original recipe intact** and clips **sticky notes** onto it ("for prod: double the batch").

Forms are flexible but you cannot bake from a blank form \u2014 you must render it first. Sticky notes keep the base readable, but you can only change what a note can express.`,
    how: `**Helm, step by step** (\`helm install web ./chart -f prod-values.yaml\`):

- **1.** Merge values: chart defaults in \`values.yaml\`, then each \`-f\` file, then \`--set\` overrides.
- **2.** Render every file in \`templates/\` with those values (Go templates plus helper functions).
- **3.** Send the rendered objects to the API server.
- **4.** Record the release (name, revision, rendered manifest, values) \u2014 by default in a Secret in the release's namespace.
- **5.** \`helm upgrade\` repeats this as revision 2; \`helm rollback web 1\` re-applies revision 1's stored manifest.

Helm 3 and later talk to the API server directly with your kubeconfig credentials. The old in-cluster **Tiller** component of Helm 2 is gone.

**Kustomize, step by step** (\`kubectl apply -k overlays/prod\`):

- **1.** Read \`overlays/prod/kustomization.yaml\`, which lists \`resources\` (e.g. \`../../base\`).
- **2.** Load the base's plain YAML.
- **3.** Apply transformations: \`namePrefix\`, \`labels\`, \`images\` (tag changes), \`replicas\`, and strategic-merge or JSON patches.
- **4.** Run generators such as \`configMapGenerator\`, which appends a content hash to the name so a config change rolls the Pods.
- **5.** Output the final YAML (view it with \`kubectl kustomize overlays/prod\`) and apply it. There is no release record; the cluster objects are the state.`,
    components: [
      { name: "Chart", description: "`Chart.yaml` (metadata, version), `values.yaml` (defaults), `templates/` (Go-templated manifests), optional dependencies on other charts." },
      { name: "Release", description: "One installed instance of a chart with a name and a revision history. The same chart can be installed many times under different release names." },
      { name: "Repository / OCI registry", description: "Where charts are published: classic HTTP chart repositories (`helm repo add`) or OCI registries (`oci://...`)." },
      { name: "kustomization.yaml", description: "Declares resources, patches, transformers and generators for one directory." },
      { name: "Base and overlays", description: "Base = shared plain manifests. Overlay = an environment-specific directory that references the base and patches it." }
    ],
    misconceptions: [
      { myth: "Helm runs a server component in the cluster.", reality: "Only Helm 2 had Tiller. Helm 3+ is a client that uses your kubeconfig and RBAC permissions." },
      { myth: "Kustomize needs to be installed separately.", reality: "A version of Kustomize is embedded in kubectl (`kubectl apply -k`, `kubectl kustomize`). A standalone binary exists for newer features." },
      { myth: "You must pick one.", reality: "They combine. Teams commonly render a third-party Helm chart and patch the result with Kustomize, and both Argo CD and Flux support either." }
    ],
    example: {
      title: "The same change, both ways",
      description: "Goal: run 5 replicas of version 2.4.1 in prod. With Helm you override values; with Kustomize you patch a base.",
      language: "bash",
      code: `# ---- Helm ----
helm repo add example https://charts.example.com
helm install web example/web --namespace web --create-namespace \\
  --set replicaCount=5
helm list -n web
helm upgrade web example/web -n web -f prod-values.yaml
helm history web -n web
helm rollback web 1 -n web
helm template web example/web -f prod-values.yaml   # render locally, apply nothing

# ---- Kustomize ----
# overlays/prod/kustomization.yaml:
#   resources:
#     - ../../base
#   replicas:
#     - name: web
#       count: 5
#   images:
#     - name: shop/web
#       newTag: "2.4.1"
kubectl kustomize overlays/prod        # preview the rendered YAML
kubectl apply -k overlays/prod`
    },
    exercise: {
      prompt: `You upgraded a Helm release \`api\` from revision 3 to 4 and error rates rose. Write the commands to (a) see the revisions and (b) go back to revision 3. Then explain how you would achieve the same rollback if the app were deployed with Kustomize via GitOps.`,
      solution: `- a) \`helm history api -n <namespace>\`
- b) \`helm rollback api 3 -n <namespace>\` \u2014 this creates a **new** revision 5 whose content equals revision 3.

Kustomize keeps no release history; the history is in Git. Revert the commit that changed the overlay (\`git revert <sha>\`), merge it, and let the GitOps agent sync. (Without GitOps, re-apply the previous overlay with \`kubectl apply -k\`.)`
    },
    faq: [
      { q: "Which should a beginner learn first?", a: "Learn to read and apply Kustomize overlays because it is plain YAML, and learn to install, upgrade and roll back third-party Helm charts because most vendors ship that way. Writing your own complex chart templates can come later." },
      { q: "Is `helm template` the same as `helm install`?", a: "No. `helm template` only renders YAML locally; it does not contact the cluster or create a release." },
      { q: "How do I see what a Kustomize overlay will produce?", a: "`kubectl kustomize <dir>` prints the final YAML. `kubectl diff -k <dir>` compares it with the live cluster." }
    ],
    keyTerms: ["Helm chart", "values.yaml", "release", "helm rollback", "Kustomize", "base and overlay", "patch", "configMapGenerator"],
    deeper: `Helm hooks (annotations such as \`helm.sh/hook: pre-upgrade\`) run Jobs at points in the release lifecycle, e.g. a database migration before an upgrade. Chart dependencies let an umbrella chart pull in sub-charts. Kustomize \`components\` allow reusable optional features (e.g. "enable TLS") that several overlays can opt into.`,
    references: [
      { title: "Helm documentation", url: "https://helm.sh/docs/" },
      { title: "Declarative Management of Kubernetes Objects Using Kustomize", url: "https://kubernetes.io/docs/tasks/manage-kubernetes-objects/kustomization/" },
      { title: "Kustomize", url: "https://kustomize.io/" }
    ]
  },
  {
    id: "rollouts-and-deployment-strategies",
    title: "Rollouts and Deployment Strategies",
    stage: 6,
    order: 3,
    objectives: ["cad-delivery"],
    scope: "kcna",
    estMinutes: 25,
    summary: "How a Deployment replaces Pods (RollingUpdate with maxSurge/maxUnavailable, or Recreate), how to watch and undo a rollout, and how blue/green and canary releases reduce risk.",
    what: `A **rollout** is the process of moving a workload from one version to another. Kubernetes Deployments provide two built-in strategies:

- **RollingUpdate** (default) \u2014 gradually replace old Pods with new ones, keeping the app available.
- **Recreate** \u2014 delete all old Pods, then create new ones. Accepts downtime; used when two versions must never run at once (e.g. incompatible schema or a single-writer volume).

Two higher-level release patterns are built from Kubernetes primitives (or tools on top):

- **Blue/green** \u2014 run the full new version (green) next to the old (blue), test it, then switch all traffic at once.
- **Canary** \u2014 send a small share of real traffic to the new version, watch metrics, and increase gradually.`,
    why: `Most production incidents are triggered by a change. A rollout strategy decides **how many users are exposed to a bad version and for how long**. Rolling updates give zero-downtime deploys for free; canaries cap exposure to a few percent; blue/green makes rollback a single switch.`,
    problem: `Replacing every Pod at once means downtime and, if the new version is broken, a complete outage. Replacing them one at a time is safe but slow. You need knobs for the speed/safety trade-off, a way to tell when a rollout is stuck, and a quick undo.`,
    how: `Trace a RollingUpdate after \`kubectl set image deploy/web web=shop/web:2.0\` with \`replicas: 4\`, \`maxSurge: 1\`, \`maxUnavailable: 0\`:

- **1.** Changing the Pod template creates a **new ReplicaSet** (new \`pod-template-hash\`). The old ReplicaSet still has 4 Pods.
- **2.** \`maxSurge: 1\` allows 5 Pods total, so the controller scales the new ReplicaSet to 1.
- **3.** \`maxUnavailable: 0\` means it must wait until that Pod is **Ready** (readiness probe passing, plus \`minReadySeconds\` if set).
- **4.** Then it scales the old ReplicaSet to 3 and the new one to 2, and repeats until new = 4, old = 0.
- **5.** The old ReplicaSet is kept at 0 replicas as **revision history** (up to \`revisionHistoryLimit\`, default 10).
- **6.** If progress stalls for \`progressDeadlineSeconds\` (default 600), the Deployment's \`Progressing\` condition becomes false with reason \`ProgressDeadlineExceeded\`. Kubernetes does **not** roll back automatically.

\`kubectl rollout undo\` scales the previous ReplicaSet back up in the same rolling way. Both \`maxSurge\` and \`maxUnavailable\` default to **25%**; they accept absolute numbers or percentages, and cannot both be 0.

**Blue/green with plain Kubernetes**: two Deployments with labels \`version: blue\` and \`version: green\`, one Service whose selector includes \`version\`. Switching the Service selector moves all traffic.

**Canary with plain Kubernetes**: two Deployments sharing the label the Service selects on; traffic splits roughly by replica ratio (9 stable + 1 canary \u2248 10%). Precise percentages, header-based routing and automated metric analysis need a Gateway API/ingress implementation that supports weights, a service mesh, or tools such as Argo Rollouts or Flagger.`,
    components: [
      { name: "strategy.type", description: "`RollingUpdate` (default) or `Recreate`." },
      { name: "maxSurge / maxUnavailable", description: "How many Pods above desired may exist during the update, and how many below desired may be unavailable. Default 25% each." },
      { name: "Readiness gate of progress", description: "The rollout advances only as new Pods become Ready, which makes readiness probes part of safe delivery." },
      { name: "kubectl rollout", description: "`status`, `history`, `undo [--to-revision=N]`, `pause`, `resume`, `restart`." },
      { name: "Progressive delivery tools", description: "Argo Rollouts and Flagger automate canary/blue-green steps and roll back based on metrics." }
    ],
    misconceptions: [
      { myth: "Kubernetes automatically rolls back a failed Deployment.", reality: "It marks the rollout as failed (`ProgressDeadlineExceeded`) and stops. Undo is manual (`kubectl rollout undo`) or done by a progressive-delivery tool." },
      { myth: "Changing `replicas` triggers a rollout.", reality: "Only changes to the Pod template (`spec.template`) create a new ReplicaSet and revision. Scaling just resizes the current ReplicaSet." },
      { myth: "A canary means a special Kubernetes object.", reality: "There is no built-in Canary kind. It is a pattern built from Deployments, Services and traffic routing (or CRDs from tools like Argo Rollouts)." }
    ],
    example: {
      title: "A cautious rolling update, then a rollback",
      description: "This Deployment never drops below 4 ready Pods and waits 10 seconds after readiness before counting a Pod as available.",
      language: "yaml",
      code: `apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  replicas: 4
  minReadySeconds: 10
  revisionHistoryLimit: 5
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
        - name: web
          image: shop/web:2.0
          readinessProbe:
            httpGet:
              path: /healthz
              port: 8080
# kubectl rollout status deploy/web
# kubectl rollout history deploy/web
# kubectl rollout undo deploy/web --to-revision=3`
    },
    exercise: {
      prompt: `A Deployment has \`replicas: 10\` and default strategy settings. During a rollout, what is the maximum total number of Pods, and the minimum number that must stay available? Then: the new image has a bug that makes its readiness probe fail. What does the rollout do?`,
      solution: `Defaults are 25% each. \`maxSurge\` 25% of 10 = 2.5, **rounded up** to 3, so up to 13 Pods. \`maxUnavailable\` 25% of 10 = 2.5, **rounded down** to 2, so at least 8 must be available.

With a failing readiness probe the new Pods never become Ready, so the controller cannot remove more old Pods than \`maxUnavailable\` allows. The rollout stalls with most old Pods still serving. After \`progressDeadlineSeconds\` it is reported as failed. Fix with \`kubectl rollout undo deploy/<name>\`. This is why readiness probes protect rollouts.`
    },
    faq: [
      { q: "What does `kubectl rollout restart` do?", a: "It adds a timestamp annotation to the Pod template, which counts as a template change, so all Pods are replaced via a normal rolling update with the same image. Useful to pick up changed ConfigMaps consumed as env vars." },
      { q: "Blue/green or canary?", a: "Blue/green needs double capacity briefly but gives instant, all-at-once switch and rollback. Canary uses less extra capacity and limits blast radius, but needs good metrics and traffic control to be meaningful." },
      { q: "Does a StatefulSet roll out the same way?", a: "Similar idea, different mechanics: StatefulSets update Pods one at a time in reverse ordinal order by default (`RollingUpdate`), or only when Pods are deleted (`OnDelete`)." }
    ],
    keyTerms: ["RollingUpdate", "Recreate", "maxSurge", "maxUnavailable", "revision history", "kubectl rollout undo", "blue/green", "canary"],
    deeper: `Feature flags decouple deploy from release: the code ships dark and is switched on per user group, which complements canaries. Argo Rollouts' \`Rollout\` CRD replaces the Deployment and adds steps such as "set weight 20%, pause, run an analysis querying Prometheus, continue or abort". Flagger works alongside an existing Deployment and drives traffic shifting through a mesh or ingress.`,
    references: [
      { title: "Deployments", url: "https://kubernetes.io/docs/concepts/workloads/controllers/deployment/" },
      { title: "Performing a Rolling Update (tutorial)", url: "https://kubernetes.io/docs/tutorials/kubernetes-basics/update/update-intro/" }
    ]
  },
  {
    id: "debugging-applications",
    title: "Debugging Applications",
    stage: 6,
    order: 4,
    objectives: ["cad-debugging"],
    scope: "kcna",
    estMinutes: 25,
    summary: "Hands-on tools for looking inside running workloads: logs (including --previous), exec, port-forward, and kubectl debug with ephemeral containers, node debugging and Pod copies.",
    what: `Troubleshooting (previous stage) asked **"why isn't it running?"** Debugging asks **"it runs, but behaves wrongly \u2014 what is it actually doing?"** That means getting inside: reading its output, running commands in its environment, sending it requests directly, and attaching tools that the image does not contain.

The toolkit, from least to most invasive:

- \`kubectl logs\` \u2014 read output.
- \`kubectl port-forward\` \u2014 talk to it from your laptop, bypassing Services and Ingress.
- \`kubectl exec\` \u2014 run a command in an existing container.
- \`kubectl debug\` \u2014 add an **ephemeral container** to a running Pod, create a modified copy of a Pod, or open a shell on a node.`,
    why: `Production images are increasingly minimal or **distroless**: no shell, no \`curl\`, no package manager. That is good for security and size, but \`kubectl exec -- sh\` fails. Ephemeral containers solve this by bringing your tools in temporarily without rebuilding or restarting the app.

Knowing which tool isolates which layer also halves debugging time: if \`port-forward\` to the Pod works but the Service URL does not, the bug is in networking, not the app.`,
    problem: `Imagine a scenario: the \`checkout\` service returns HTTP 500 for some requests. Pods are Running and Ready. The image is distroless. Logs say only "upstream error". You need to see the app's view of DNS and the network, and call it directly \u2014 without restarting the Pod, which would destroy the state you are trying to observe.`,
    how: `Work through the scenario with escalating tools:

- **1. Logs.** \`kubectl logs deploy/checkout -c app --since=15m\` shows recent output from one Pod of the Deployment. \`-f\` follows; \`--previous\` shows the last crashed instance; \`-l app=checkout\` reads from several Pods.
- **2. Bypass the network layers.** \`kubectl port-forward pod/checkout-7c9f-abcde 8080:8080\` tunnels through the API server and kubelet to the Pod. \`curl localhost:8080/pay\` now hits the app directly. If it fails here too, the problem is in the app or its dependencies.
- **3. Try exec.** \`kubectl exec -it checkout-7c9f-abcde -c app -- sh\` fails: the image has no shell.
- **4. Attach an ephemeral container.** \`kubectl debug -it checkout-7c9f-abcde --image=busybox:1.36 --target=app\` adds a temporary container to the running Pod. It shares the Pod's network namespace (same IP, same localhost) and, with \`--target\`, the app container's process namespace so you can see its processes. Now \`nslookup payments\` and \`wget -qO- http://payments/health\` show the dependency is unreachable.
- **5. Escalate if needed.** \`kubectl debug checkout-7c9f-abcde -it --copy-to=checkout-debug --image=busybox:1.36 --share-processes\` makes a copy of the Pod with an extra debug container, leaving the original untouched. \`kubectl debug node/worker-2 -it --image=busybox:1.36\` starts a Pod on that node with the node's root filesystem mounted at \`/host\`.

Ephemeral containers (stable since 1.25) cannot be removed or restarted once added, have no ports, probes or resource guarantees, and disappear when the Pod is deleted.`,
    components: [
      { name: "kubectl logs", description: "Reads container stdout/stderr. Key flags: `-c`, `-f`, `--previous`, `--since`, `--tail`, `-l`." },
      { name: "kubectl exec", description: "Runs a process inside an existing container (`-it ... -- sh`). Needs the binary to exist in the image." },
      { name: "kubectl port-forward", description: "Forwards a local port to a Pod (or to a Pod behind a Service or Deployment). For debugging only; not a way to expose apps." },
      { name: "Ephemeral container", description: "A temporary container injected into a running Pod via `kubectl debug`, for tools the app image lacks." },
      { name: "kubectl debug --copy-to / node/", description: "Debug a copy of a Pod (optionally changing image or command) or open a privileged-style session on a node." }
    ],
    misconceptions: [
      { myth: "To debug, add curl to the production image and redeploy.", reality: "That changes what you are debugging and bloats the image. Use an ephemeral container with the tools you need." },
      { myth: "`kubectl port-forward` is a way to expose a service to users.", reality: "It is a temporary tunnel for one client through the API server. Use a Service, Ingress or Gateway to expose apps." },
      { myth: "`kubectl logs` shows logs of a deleted Pod.", reality: "Logs live with the container on the node. Once the Pod is gone, so are its logs unless a log pipeline shipped them elsewhere. `--previous` only covers the prior container instance of a still-existing Pod." }
    ],
    example: {
      title: "Debugging a distroless container",
      description: "Exec fails because there is no shell; an ephemeral busybox container sharing the target's process namespace gives you one.",
      language: "bash",
      code: `$ kubectl exec -it checkout-7c9f-abcde -- sh
error: ... exec: "sh": executable file not found in $PATH

$ kubectl debug -it checkout-7c9f-abcde --image=busybox:1.36 --target=app
Defaulting debug container name to debugger-x7k2p.
/ # ps                       # see the app's processes (shared PID namespace)
/ # nslookup payments        # DNS as the Pod sees it
/ # wget -qO- -T 3 http://payments:8080/health
wget: download timed out     # dependency unreachable -> check its Service / NetworkPolicy

# Copy the Pod to experiment without touching the original
$ kubectl debug checkout-7c9f-abcde -it --copy-to=checkout-debug \\
    --image=busybox:1.36 --share-processes`
    },
    exercise: {
      prompt: `A web app works via \`kubectl port-forward svc/web 8080:80\` but returns 404 through the Ingress. Separately, a Pod restarted twice and its current logs look clean. Which layer does each observation point to, and what command reveals the cause of the restarts?`,
      solution: `- Port-forward to the Service works, so the app and the Service are fine. The 404 comes from the **Ingress layer**: wrong host or path rule, wrong backend service name/port, or a different ingress class. Check \`kubectl describe ingress\`.
- The current instance is healthy; the crash happened in the previous one. \`kubectl logs <pod> --previous\` shows its output, and \`kubectl describe pod\` shows the last state's reason and exit code.`
    },
    faq: [
      { q: "Does kubectl debug restart my Pod?", a: "Adding an ephemeral container does not restart the Pod. `--copy-to` creates a separate new Pod and leaves the original as is." },
      { q: "Why does my ephemeral container not see the app's processes?", a: "By default containers in a Pod have separate PID namespaces. Use `--target=<container>` so the debug container joins that container's process namespace (requires runtime support), or `--share-processes` with `--copy-to`." },
      { q: "Can I use these tools if Pod Security Admission enforces restricted?", a: "Ephemeral containers are also checked against the namespace's policy, so a debug image running as root may be rejected. `kubectl debug` offers `--profile` options (such as `restricted`) to generate a compliant container." }
    ],
    keyTerms: ["kubectl logs --previous", "kubectl exec", "kubectl port-forward", "kubectl debug", "ephemeral container", "distroless image", "process namespace sharing"],
    deeper: `Beyond kubectl, application debugging in production leans on observability: distributed traces show which hop of a request failed, and structured logs with a trace ID let you jump from a trace to the exact log lines. Tools such as Telepresence or mirrord route cluster traffic to a process on your laptop so you can attach a local debugger.`,
    references: [
      { title: "Debug Running Pods", url: "https://kubernetes.io/docs/tasks/debug/debug-application/debug-running-pod/" },
      { title: "Ephemeral Containers", url: "https://kubernetes.io/docs/concepts/workloads/pods/ephemeral-containers/" },
      { title: "kubectl reference", url: "https://kubernetes.io/docs/reference/kubectl/" }
    ]
  },
  // ───────────────────────────── Stage 7 ─────────────────────────────
  {
    id: "cloud-native-principles",
    title: "Cloud Native Principles",
    stage: 7,
    order: 1,
    objectives: ["cna-ecosystem"],
    scope: "kcna",
    estMinutes: 20,
    summary: 'What "cloud native" means according to the CNCF, and the ideas behind it: microservices, containers, declarative APIs, immutable infrastructure, the twelve-factor app and treating servers as cattle rather than pets.',
    what: `The CNCF's definition, paraphrased: cloud native technologies let organisations build and run **scalable** applications in modern, dynamic environments such as public, private and hybrid clouds. **Containers, service meshes, microservices, immutable infrastructure and declarative APIs** exemplify the approach. These techniques enable **loosely coupled** systems that are **resilient, manageable and observable**, and combined with robust **automation** they let engineers make high-impact changes frequently and predictably with minimal toil.

Note what is missing: "cloud native" does not mean "runs in a public cloud". An on-premises Kubernetes cluster running containerised microservices with GitOps is cloud native; a monolith lifted unchanged onto a cloud VM is not.`,
    why: `Every other KCNA topic is an instance of these principles. Deployments embody immutable infrastructure and declarative APIs; Services and DNS embody loose coupling; probes and ReplicaSets embody resilience; Prometheus and OpenTelemetry embody observability. Understanding the principles lets you answer "why would you choose X?" questions rather than memorising feature lists.`,
    problem: `Traditional operations treat servers as **pets**: named, hand-configured, nursed back to health when sick. Over time each one accumulates undocumented changes (configuration drift) and becomes impossible to reproduce. Large monoliths add a second bottleneck: one team's change requires redeploying everything, so releases are rare, big and risky.`,
    how: `Contrast two ways of running the same online shop:

- **Packaging.** Pet style: install packages on long-lived VMs by hand or script. Cloud native: build an **immutable container image** once; the same artifact runs in every environment.
- **Change.** Pet style: SSH in and patch in place. Cloud native: build a new image and **replace** instances (immutable infrastructure). Nothing is modified after deployment.
- **Failure.** Pet style: page a human to fix the server. Cloud native: instances are **cattle** \u2014 identical and disposable \u2014 so a controller deletes and recreates them automatically.
- **Structure.** Pet style: one monolith. Cloud native: **microservices** \u2014 small services owned by small teams, communicating over the network via APIs, deployed and scaled independently.
- **Operation.** Pet style: runbooks and tickets. Cloud native: **declarative APIs** plus **automation** \u2014 you state desired state and controllers converge on it.
- **Visibility.** Pet style: log in and look. Cloud native: built-in **observability** (metrics, logs, traces) collected centrally.

The **twelve-factor app** methodology captures app-level habits that make this work. The ones most relevant to Kubernetes:

- **Config** in the environment, not the code (ConfigMaps, Secrets, env vars).
- **Backing services** (databases, queues) as attached resources addressed by URL.
- **Processes** are stateless; state lives in backing services. This makes horizontal scaling and replacement safe.
- **Disposability**: fast startup and graceful shutdown on SIGTERM.
- **Dev/prod parity**: same image everywhere.
- **Logs** as event streams written to stdout, collected by the platform.`,
    components: [
      { name: "Microservices", description: "Independently deployable services with their own data and lifecycle. Trade-off: network calls, distributed failure and more operational complexity." },
      { name: "Containers", description: "The packaging unit: portable, immutable, fast to start, with isolated dependencies." },
      { name: "Declarative APIs", description: "You describe the end state; controllers handle the steps. Kubernetes is the canonical example." },
      { name: "Immutable infrastructure", description: "Never patch a running instance; replace it with a new one built from a versioned artifact." },
      { name: "Automation and CI/CD", description: "Repeatable pipelines and reconcilers instead of manual steps, enabling frequent, low-risk changes." },
      { name: "Observability", description: "Designing systems so their internal state can be inferred from emitted telemetry." }
    ],
    misconceptions: [
      { myth: "Cloud native means running on AWS, Azure or Google Cloud.", reality: "It describes how applications are built and operated. It applies equally to on-premises, edge and hybrid environments." },
      { myth: "Microservices are always better than a monolith.", reality: "They trade code coupling for distributed-systems complexity. A small team with a simple product may be better off with a well-structured monolith." },
      { myth: "Containerising an app makes it cloud native.", reality: "A stateful, slow-starting app that writes logs to local files and needs manual config inside the container gains little. The design principles matter more than the packaging." }
    ],
    example: {
      title: "Twelve-factor habits expressed in a Pod spec",
      description: "Config comes from the environment, the backing service is a URL, the process is stateless, and a shutdown grace period gives it time to finish requests on SIGTERM.",
      language: "yaml",
      code: `apiVersion: apps/v1
kind: Deployment
metadata:
  name: orders
spec:
  replicas: 3                      # stateless -> scale horizontally
  selector:
    matchLabels: { app: orders }
  template:
    metadata:
      labels: { app: orders }
    spec:
      terminationGracePeriodSeconds: 30   # disposability: graceful shutdown
      containers:
        - name: orders
          image: shop/orders:1.8.2         # same immutable image in every env
          envFrom:
            - configMapRef: { name: orders-config }   # config in the environment
          env:
            - name: DATABASE_URL                       # backing service as a resource
              valueFrom:
                secretKeyRef: { name: orders-db, key: url }
          # logs: the app writes to stdout; the platform collects them`
    },
    exercise: {
      prompt: `A team's app stores uploaded files on the container's local disk and reads its database password from a file baked into the image. Name the twelve-factor principles violated and what to change on Kubernetes.`,
      solution: `- Local file storage violates **stateless processes** (and disposability): the files vanish when the Pod is replaced and are not shared across replicas. Store them in a backing service such as object storage, or at minimum a PersistentVolume.
- A password baked into the image violates **config in the environment** (and is a security problem: everyone with the image has the secret, and changing it requires a rebuild). Provide it via a Secret as an env var or mounted file.`
    },
    faq: [
      { q: "Is Kubernetes required to be cloud native?", a: "No, but it is the most common foundation because it directly implements declarative APIs, self-healing and automated rollouts. Serverless platforms and other orchestrators can also support cloud native designs." },
      { q: "What is the difference between pets and cattle in Kubernetes terms?", a: "Pods managed by a Deployment are cattle: any one can be deleted and replaced. Even StatefulSet Pods, which keep stable names and storage, are recreated automatically rather than hand-repaired." },
      { q: "Do I need to memorise all twelve factors?", a: "Know the idea and the factors that map to Kubernetes features: config, backing services, stateless processes, disposability, dev/prod parity and logs as streams." }
    ],
    keyTerms: ["cloud native", "microservices", "immutable infrastructure", "declarative API", "pets vs cattle", "twelve-factor app", "loose coupling", "resilience"],
    deeper: `Microservices create their own problems: retries amplifying outages, cascading failures, and data consistency across service boundaries. Patterns such as timeouts with budgets, circuit breakers, idempotent APIs, bulkheads and event-driven communication (with eventual consistency) address them, and several are implemented by service meshes rather than in each application.`,
    references: [
      { title: "CNCF Cloud Native Definition", url: "https://github.com/cncf/toc/blob/main/DEFINITION.md" },
      { title: "The Twelve-Factor App", url: "https://12factor.net/" },
      { title: "CNCF Glossary", url: "https://glossary.cncf.io/" }
    ]
  },
  {
    id: "autoscaling-and-serverless",
    title: "Autoscaling and Serverless",
    stage: 7,
    order: 2,
    objectives: ["cna-ecosystem"],
    scope: "kcna",
    estMinutes: 25,
    summary: "The three autoscaling dimensions (more Pods with HPA, bigger Pods with VPA, more nodes with Cluster Autoscaler), event-driven scaling with KEDA, and serverless platforms such as Knative that scale to zero.",
    what: `Autoscaling adjusts capacity to demand automatically. In Kubernetes it happens on three axes:

- **Horizontal Pod Autoscaler (HPA)** \u2014 changes the **number of replicas** of a Deployment, StatefulSet or other scalable resource. Built in (\`autoscaling/v2\`).
- **Vertical Pod Autoscaler (VPA)** \u2014 recommends or changes **CPU/memory requests** of Pods. An add-on, not part of core Kubernetes.
- **Cluster Autoscaler** \u2014 adds **nodes** when Pods are Pending for lack of capacity, and removes underused nodes. Karpenter is an alternative node autoscaler.

**Serverless** takes this to the extreme: developers deploy functions or containers, and the platform handles servers and scaling entirely, often **down to zero** instances when idle, billing per use. On Kubernetes, **Knative** provides serverless containers and **KEDA** provides event-driven scaling (including to zero) for ordinary Deployments.`,
    why: `Static capacity is either wasteful (provisioned for peak) or fragile (provisioned for average). Autoscaling is how the cloud native promise of "elastic" is delivered, and it directly controls cost. It also connects other topics: HPA needs metrics, and Cluster Autoscaler is triggered by the scheduler's \`Pending\` state.`,
    problem: `Picture a ticketing site at 09:59 before a concert sale opens. Traffic will rise 20x in a minute and drop an hour later. Overnight it is nearly idle. Fixed replicas and fixed nodes cannot match that curve, and a human cannot react fast enough.`,
    how: `Walk through the spike with all three autoscalers:

- **1. Metrics.** **metrics-server** collects CPU/memory usage from kubelets and serves it via the Resource Metrics API. (Custom or external metrics need an adapter, e.g. for Prometheus.)
- **2. HPA loop.** Every 15 seconds by default, the HPA controller computes \`desiredReplicas = ceil(currentReplicas \xD7 currentMetric / targetMetric)\`. With 4 replicas at 90% CPU and a target of 60%: ceil(4 \xD7 90/60) = 6. Utilisation is measured **relative to the Pods' CPU requests**, so requests must be set.
- **3. Scheduling.** The 2 new Pods need room. If no node has enough unrequested capacity, they stay **Pending**.
- **4. Cluster Autoscaler** sees unschedulable Pods, simulates whether a new node from a node group would fit them, and asks the cloud provider for one. Minutes later the node joins and the Pods schedule.
- **5. Scale down.** When load drops, HPA reduces replicas (a stabilisation window, 5 minutes by default for scale-down, prevents flapping). Cluster Autoscaler later drains and removes nodes that stay underutilised.
- **6. VPA**, used separately, watches actual usage over time and sets better requests \u2014 typically in recommendation mode, or applied by recreating Pods. Avoid letting HPA and VPA act on the **same CPU/memory metric** for one workload; they fight.

For event-driven work, **KEDA** reads a source such as a queue length or Kafka lag, scales a Deployment between 0 and N (it manages an HPA under the hood for 1\u2192N), and **Knative Serving** routes requests through an activator so a revision can scale to zero and back on the first request (the **cold start**).`,
    components: [
      { name: "HorizontalPodAutoscaler", description: "Built-in API object (`autoscaling/v2`) targeting a scalable resource with min/max replicas and metric targets (resource, Pods, object, external)." },
      { name: "metrics-server", description: "Lightweight cluster add-on supplying CPU/memory for HPA and `kubectl top`. Not a monitoring system; it keeps no history." },
      { name: "Vertical Pod Autoscaler", description: "Add-on that right-sizes container requests based on observed usage." },
      { name: "Cluster Autoscaler / Karpenter", description: "Node-level scaling triggered by unschedulable Pods and underused nodes." },
      { name: "KEDA", description: "Kubernetes Event-Driven Autoscaling: scalers for queues, streams, databases, cron and more; supports scale to zero. CNCF graduated." },
      { name: "Knative", description: "Serverless layer on Kubernetes: Serving (request-driven autoscaling, scale to zero, revisions and traffic splitting) and Eventing." }
    ],
    misconceptions: [
      { myth: "HPA adds nodes when the cluster is full.", reality: "HPA only changes replica counts. If new Pods do not fit, they are Pending until a node autoscaler (or a human) adds capacity." },
      { myth: "HPA works without resource requests.", reality: "CPU utilisation targets are percentages of the request. Without a request the HPA cannot compute utilisation for that metric." },
      { myth: "Serverless means there are no servers.", reality: "Servers still exist; the platform operator manages them, and you are abstracted from provisioning and scaling." },
      { myth: "The standard HPA can scale a Deployment to zero.", reality: "HPA keeps at least `minReplicas` (1 or more by default). Scale-to-zero is provided by KEDA or Knative." }
    ],
    example: {
      title: "An HPA targeting 60% CPU",
      description: "Keeps 2\u201310 replicas of `web` and aims for average CPU usage at 60% of requests. The Deployment's containers must declare CPU requests, and metrics-server must be installed.",
      language: "yaml",
      code: `apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: web
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: web
  minReplicas: 2
  maxReplicas: 10
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 60
# Imperative equivalent:
#   kubectl autoscale deployment web --cpu-percent=60 --min=2 --max=10
# Watch it:
#   kubectl get hpa web --watch`
    },
    exercise: {
      prompt: `An HPA targets 50% CPU, min 2, max 8. Current: 3 replicas averaging 100% of their CPU request. (a) How many replicas will it request? (b) Two of the new Pods are Pending with \`Insufficient cpu\`. Which component fixes that, and how?`,
      solution: `- a) ceil(3 \xD7 100/50) = **6** replicas, which is within the 2\u20138 bounds.
- b) A **node autoscaler** (Cluster Autoscaler or Karpenter). It notices unschedulable Pods, determines that a new node would fit them, and provisions one from the cloud provider. Once the node is Ready the scheduler places the Pods. Without a node autoscaler they stay Pending.`
    },
    faq: [
      { q: "Why is my HPA showing `<unknown>` for targets?", a: "Usually metrics-server is not installed or not working, or the target containers have no CPU requests. `kubectl describe hpa` shows the exact condition." },
      { q: "What is a cold start?", a: "The latency of the first request after scaling from zero: the platform must schedule a Pod, pull the image if needed and start the process. It is the price of paying nothing while idle." },
      { q: "Is FaaS the same as serverless?", a: "Function-as-a-Service is one form of serverless where you deploy individual functions. Serverless containers (e.g. Knative) apply the same operational model to whole container images." }
    ],
    keyTerms: ["HorizontalPodAutoscaler", "Vertical Pod Autoscaler", "Cluster Autoscaler", "metrics-server", "KEDA", "Knative", "scale to zero", "cold start"],
    deeper: `The HPA's \`behavior\` field tunes scaling speed: policies such as "add at most 4 Pods or 100% per 15 seconds" and separate stabilisation windows for scale-up and scale-down. Kubernetes has also added **in-place Pod resource resize**, letting requests and limits change without recreating the Pod, which makes vertical scaling less disruptive; check the feature's status for your cluster version before relying on it.`,
    references: [
      { title: "Horizontal Pod Autoscaling", url: "https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/" },
      { title: "Autoscaling Workloads", url: "https://kubernetes.io/docs/concepts/workloads/autoscaling/" },
      { title: "CNCF Projects", url: "https://www.cncf.io/projects/" }
    ]
  },
  {
    id: "observability-fundamentals",
    title: "Observability Fundamentals",
    stage: 7,
    order: 3,
    objectives: ["cna-observability"],
    scope: "kcna",
    estMinutes: 25,
    summary: "Metrics, logs and traces \u2014 what each signal answers, how OpenTelemetry standardises collecting them, and how SLIs, SLOs and SLAs turn telemetry into reliability targets.",
    what: `**Observability** is the ability to understand a system's internal state from the data it emits, including for failures you did not predict. **Monitoring** is watching known indicators and alerting on them. Monitoring answers "is it broken?"; observability helps answer "why?".

The three main signals:

- **Metrics** \u2014 numeric measurements over time, cheap to store and aggregate: request rate, error count, latency percentiles, CPU usage.
- **Logs** \u2014 timestamped records of discrete events, rich in detail: "payment 8812 declined: card expired".
- **Traces** \u2014 the path of one request across services, made of **spans** (one per operation) sharing a **trace ID**, with timing for each hop.

**OpenTelemetry (OTel)** is the CNCF project that standardises how applications produce and export this telemetry: APIs and SDKs for many languages, automatic instrumentation, a wire protocol (**OTLP**) and the **OpenTelemetry Collector**. It is vendor-neutral: instrument once, send anywhere.`,
    why: `In a monolith you can attach a debugger. In a system of 40 microservices, one user click touches a dozen processes on different nodes that may already have been replaced. Without telemetry collected centrally, a failure is invisible or impossible to locate. Observability is a design requirement of cloud native systems, not an add-on.`,
    problem: `Each signal alone has blind spots:

- Metrics tell you **that** the error rate jumped at 14:02, but not which requests or why.
- Logs have the details, but across 200 Pods you do not know which lines belong to the failing request.
- Traces show **where** the latency is, but sampling means not every request is kept, and they are expensive to store at full volume.

The fix is to correlate: an alert fires on a metric, you open an exemplar trace from that time window, find the slow span, and jump to the logs carrying that trace ID.`,
    how: `Follow telemetry from a checkout request through an OpenTelemetry-based pipeline:

- **1. Instrumentation.** The app uses the OTel SDK (or auto-instrumentation). Incoming HTTP requests start a span; outgoing calls create child spans and inject **trace context** into HTTP headers (W3C Trace Context), so the next service continues the same trace.
- **2. Emit.** The SDK records spans, increments metrics such as \`http.server.request.duration\`, and attaches the trace ID to log records.
- **3. Export.** Data goes over **OTLP** to an **OpenTelemetry Collector**, usually deployed as a DaemonSet (agent per node) and/or a central Deployment (gateway).
- **4. Process.** Collector **pipelines** run receivers \u2192 processors (batching, sampling, adding Kubernetes metadata like Pod and namespace, dropping sensitive attributes) \u2192 exporters.
- **5. Store and query.** Exporters send metrics to e.g. Prometheus, traces to e.g. Jaeger, logs to e.g. Loki or Elasticsearch, or everything to a commercial backend. Switching backends means changing Collector config, not application code.
- **6. Act.** Dashboards and alerts are built on **SLIs** and **SLOs**.

Reliability vocabulary:

- **SLI** (Service Level Indicator) \u2014 a measured quantity, e.g. "fraction of requests served successfully in under 300 ms".
- **SLO** (Service Level Objective) \u2014 the internal target for an SLI over a window, e.g. "99.9% over 30 days". The remaining 0.1% is the **error budget**.
- **SLA** (Service Level Agreement) \u2014 a contract with customers with consequences (credits, penalties) if missed. SLAs are usually looser than SLOs.`,
    components: [
      { name: "Metrics", description: "Aggregatable numbers with labels/attributes. Best for alerting and trends. Low cost per data point; watch label cardinality." },
      { name: "Logs", description: "Event records. In Kubernetes, apps write to stdout/stderr; a node agent (e.g. Fluent Bit, Fluentd, the OTel Collector) ships them to a backend." },
      { name: "Traces and spans", description: "A trace is a tree of spans for one request; context propagation carries the trace ID between services." },
      { name: "OpenTelemetry SDKs and APIs", description: "Language libraries to produce telemetry, plus auto-instrumentation for common frameworks." },
      { name: "OpenTelemetry Collector", description: "Vendor-neutral agent/gateway with receivers, processors and exporters." },
      { name: "SLI / SLO / SLA", description: "Indicator (what you measure), objective (internal target), agreement (external contract)." }
    ],
    misconceptions: [
      { myth: "Observability is just having dashboards.", reality: "Dashboards show questions someone anticipated. Observability means the data is rich and correlated enough to investigate new questions after the fact." },
      { myth: "OpenTelemetry is a monitoring backend that stores and displays data.", reality: "OTel produces, processes and exports telemetry. Storage, querying and visualisation are done by backends such as Prometheus, Jaeger or commercial tools." },
      { myth: "An SLO of 100% is the goal.", reality: "100% is unattainable and freezes change. An SLO below 100% defines an error budget that teams can spend on releases and experiments." }
    ],
    example: {
      title: "A minimal OpenTelemetry Collector pipeline",
      description: "Receives OTLP from applications, batches and enriches it with Kubernetes metadata, then sends traces to a Jaeger backend over OTLP and exposes metrics for Prometheus to scrape. Component names follow the Collector Contrib distribution.",
      language: "yaml",
      code: `receivers:
  otlp:
    protocols:
      grpc: {}
      http: {}
processors:
  k8sattributes: {}      # add pod, namespace, node names
  batch: {}
exporters:
  otlp/jaeger:
    endpoint: jaeger-collector.observability:4317
    tls:
      insecure: true
  prometheus:
    endpoint: 0.0.0.0:8889
service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [k8sattributes, batch]
      exporters: [otlp/jaeger]
    metrics:
      receivers: [otlp]
      processors: [k8sattributes, batch]
      exporters: [prometheus]`
    },
    diagram: "observability-pillars",
    exercise: {
      prompt: `Users report the checkout is "sometimes slow". For each question, say which signal answers it best: (a) Did p99 latency rise, and since when? (b) Which downstream service adds the delay? (c) What exact error did the payment provider return for order 4411?

Then write one SLI and an SLO for checkout.`,
      solution: `- a) **Metrics** \u2014 a latency histogram graphed over time.
- b) **Traces** \u2014 span durations show which hop is slow.
- c) **Logs** \u2014 the detailed event record, found quickly via the trace ID or order ID.

Example SLI: proportion of checkout requests that return a non-5xx response within 500 ms. SLO: 99.5% of checkout requests meet that SLI over a rolling 28 days, giving an error budget of 0.5%.`
    },
    faq: [
      { q: "Are there only three pillars?", a: "Metrics, logs and traces are the classic three. **Profiles** (continuous CPU/memory profiling) are increasingly treated as a fourth signal, and OpenTelemetry has been adding support for them." },
      { q: "Where do Kubernetes Events fit?", a: "They are short-lived cluster events (scheduling, pulls, probe failures). Collectors can ship them to a log backend so they outlive the API server's retention period." },
      { q: "What is sampling and why is it needed?", a: "Keeping only a fraction of traces to control cost. Head sampling decides at the start of a request; tail sampling decides after it completes, so it can keep all errors and slow requests." }
    ],
    keyTerms: ["observability", "metrics", "logs", "traces", "span", "OpenTelemetry", "OTLP", "SLI / SLO / SLA"],
    deeper: `Two practical pitfalls: **cardinality** \u2014 adding a label like user ID to a metric creates a time series per user and can overwhelm a metrics backend; put such detail in logs or traces instead. And **alerting on symptoms, not causes** \u2014 page on SLO burn rate ("we will exhaust the monthly error budget in 6 hours") rather than on every high-CPU node, which reduces alert fatigue.`,
    references: [
      { title: "OpenTelemetry documentation", url: "https://opentelemetry.io/docs/" },
      { title: "Prometheus overview", url: "https://prometheus.io/docs/introduction/overview/" },
      { title: "Kubernetes logging architecture", url: "https://kubernetes.io/docs/concepts/cluster-administration/logging/" }
    ]
  },
  {
    id: "prometheus-and-monitoring",
    title: "Prometheus and Monitoring",
    stage: 7,
    order: 4,
    objectives: ["cna-observability"],
    scope: "kcna",
    estMinutes: 25,
    summary: "How Prometheus collects metrics by scraping (pull model), how exporters and service discovery feed it, the four metric types, basic PromQL, and how Alertmanager and Grafana complete the monitoring stack.",
    what: `**Prometheus** is an open-source monitoring system and time-series database. It was the second project to join the CNCF after Kubernetes and the second to graduate, and it is the de facto standard for metrics in Kubernetes environments.

Its defining choices:

- **Pull model** \u2014 Prometheus scrapes HTTP endpoints (conventionally \`/metrics\`) on a schedule, rather than waiting for apps to push data to it.
- **Dimensional data model** \u2014 every time series is a metric name plus key/value **labels**: \`http_requests_total{method="GET", code="500", pod="api-7c9f"}\`.
- **PromQL** \u2014 a query language for selecting and aggregating those series.
- **Local TSDB** \u2014 a single Prometheus server stores data on its own disk; long-term or global storage is delegated to other systems.`,
    why: `Metrics are the signal you alert on, and Kubernetes components themselves (API server, kubelet, etcd, CoreDNS) expose Prometheus-format metrics. Learning Prometheus vocabulary \u2014 scrape, target, exporter, label, PromQL, Alertmanager \u2014 covers most of what KCNA asks about monitoring.`,
    problem: `In a cluster, monitoring targets come and go every minute as Pods are created and rescheduled. A static list of hosts to monitor would be stale immediately, and asking thousands of short-lived Pods to know where to push data creates its own configuration problem. Prometheus's answer: **service discovery plus pull**. It asks the Kubernetes API what exists, then scrapes it.`,
    how: `Trace a metric from code to a page on someone's phone:

- **1. Expose.** The app uses a Prometheus client library to keep counters in memory and serve them as text on \`/metrics\`. Software you cannot modify (Linux hosts, databases) gets an **exporter**: a sidecar or separate process translating its stats into the format, e.g. **node_exporter** for machine metrics.
- **2. Discover.** Prometheus's Kubernetes service discovery watches the API for Pods, Services, Endpoints/EndpointSlices or Nodes. Relabelling rules choose which ones to scrape and turn their metadata into labels. (The Prometheus Operator lets you declare this with \`ServiceMonitor\` and \`PodMonitor\` custom resources.)
- **3. Scrape.** Every scrape interval (commonly 15\u201360 s) Prometheus GETs each target's \`/metrics\` and appends samples to its TSDB. The synthetic series \`up\` is 1 for a successful scrape and 0 for a failed one.
- **4. Evaluate rules.** **Recording rules** precompute expensive queries; **alerting rules** are PromQL expressions with a \`for\` duration. When an expression stays true that long, the alert fires.
- **5. Alertmanager** receives firing alerts and **deduplicates**, **groups** (one notification for 50 failing Pods), **routes** by labels (team=payments \u2192 that team's channel), applies **silences** and **inhibition**, then notifies via email, chat or paging tools.
- **6. Visualise.** **Grafana** (a separate, non-CNCF open-source project) queries Prometheus with PromQL for dashboards.

Short-lived batch jobs that end before a scrape can push to a **Pushgateway**, which Prometheus then scrapes \u2014 an exception to pull, not the norm.`,
    components: [
      { name: "Prometheus server", description: "Discovers targets, scrapes them, stores samples in its TSDB, evaluates rules and serves PromQL queries." },
      { name: "Exporters", description: "Adapters that expose metrics for third-party systems: node_exporter (hosts), kube-state-metrics (state of Kubernetes objects), database exporters and more." },
      { name: "Metric types", description: "**Counter** (only goes up, resets on restart: requests served), **Gauge** (up and down: memory in use, queue length), **Histogram** (bucketed observations: request durations), **Summary** (client-side quantiles)." },
      { name: "PromQL", description: "Selectors with label matchers, range vectors like `[5m]`, functions like `rate()` and `histogram_quantile()`, and aggregations like `sum by (label)`." },
      { name: "Alertmanager", description: "Handles alerts from Prometheus: dedup, grouping, routing, silences, inhibition, notification." },
      { name: "Grafana", description: "Dashboarding tool commonly paired with Prometheus. Not part of Prometheus and not a CNCF project." }
    ],
    misconceptions: [
      { myth: "Applications push metrics to Prometheus.", reality: "Prometheus pulls (scrapes). Push is only used through the Pushgateway for short-lived jobs, or via other components like an OpenTelemetry Collector that Prometheus scrapes or that uses remote write." },
      { myth: "Prometheus is built for logs and long-term storage.", reality: "It stores numeric time series only, on a local disk with limited retention. Logs go to log systems; long-term/global metric storage uses projects such as Thanos or Cortex via remote write." },
      { myth: "Graphing a counter directly shows the request rate.", reality: "A raw counter is an ever-increasing total. Use `rate(counter[5m])` to get per-second rate; it also handles counter resets." },
      { myth: "metrics-server is a lightweight Prometheus.", reality: "metrics-server only provides current CPU/memory for autoscaling and `kubectl top`. It has no history, no query language and no alerting." }
    ],
    example: {
      title: "Four PromQL queries every learner should be able to read",
      description: "From the raw exposition format to rates, aggregation and percentiles, plus an alerting rule.",
      language: "text",
      code: `# What a target exposes on /metrics
# TYPE http_requests_total counter
http_requests_total{method="GET",code="200"} 10234
http_requests_total{method="GET",code="500"} 17

# 1. Is every target up?            -> 0 means the scrape failed
up{job="api"}

# 2. Requests per second, per status code, over the last 5 minutes
sum by (code) (rate(http_requests_total{job="api"}[5m]))

# 3. Error ratio
sum(rate(http_requests_total{job="api",code=~"5.."}[5m]))
  / sum(rate(http_requests_total{job="api"}[5m]))

# 4. 95th percentile latency from a histogram
histogram_quantile(0.95,
  sum by (le) (rate(http_request_duration_seconds_bucket{job="api"}[5m])))

# Alerting rule (in a rules file)
groups:
  - name: api
    rules:
      - alert: HighErrorRate
        expr: sum(rate(http_requests_total{job="api",code=~"5.."}[5m])) / sum(rate(http_requests_total{job="api"}[5m])) > 0.05
        for: 10m
        labels: { severity: page }`
    },
    exercise: {
      prompt: `Classify each as counter, gauge or histogram: (a) bytes of memory in use, (b) total jobs processed, (c) request durations you want p50/p99 for. Then explain why \`rate()\` should be applied to (b) but not to (a).`,
      solution: `- a) **Gauge** \u2014 it goes up and down.
- b) **Counter** \u2014 it only increases (until the process restarts).
- c) **Histogram** \u2014 buckets of observations, queried with \`histogram_quantile()\`.

\`rate()\` computes the per-second increase of a counter over a window and compensates for resets, turning "total processed" into "processed per second". A gauge's value is already meaningful on its own; to see how it changes use functions like \`deriv()\` or aggregation such as \`avg_over_time()\`, not \`rate()\`.`
    },
    faq: [
      { q: "What is kube-state-metrics and how is it different from metrics-server?", a: "kube-state-metrics exposes the **state of Kubernetes objects** (desired vs available replicas, Pod phase, restarts) for Prometheus to scrape. metrics-server reports **resource usage** (CPU/memory) for autoscaling. Different questions, different tools." },
      { q: "How does Prometheus scale?", a: "A single server scales vertically and you can shard by job. For high availability run two identical servers; for global views and long retention, add Thanos or Cortex-style systems that receive data via remote write or read from object storage." },
      { q: "Do I need to know PromQL in depth for KCNA?", a: "No. Recognise selectors, labels, `rate()` over counters, `sum by`, and what Alertmanager does. Deeper PromQL is for operational roles." }
    ],
    keyTerms: ["Prometheus", "pull model", "scrape", "exporter", "PromQL", "counter vs gauge", "Alertmanager", "Grafana"],
    deeper: `The **Prometheus Operator** (often installed via the kube-prometheus-stack Helm chart) manages Prometheus and Alertmanager with CRDs: \`Prometheus\`, \`Alertmanager\`, \`ServiceMonitor\`, \`PodMonitor\` and \`PrometheusRule\`. Teams then add monitoring for their app by creating a ServiceMonitor next to their Service rather than editing a central config file. Prometheus can also ingest OTLP metrics directly in recent versions, which helps OpenTelemetry-instrumented apps.`,
    references: [
      { title: "Prometheus overview", url: "https://prometheus.io/docs/introduction/overview/" },
      { title: "Querying Prometheus (PromQL basics)", url: "https://prometheus.io/docs/prometheus/latest/querying/basics/" },
      { title: "Alertmanager", url: "https://prometheus.io/docs/alerting/latest/alertmanager/" }
    ]
  },
  {
    id: "service-mesh-and-envoy",
    title: "Service Mesh and Envoy",
    stage: 7,
    order: 5,
    objectives: ["cna-ecosystem"],
    scope: "kcna",
    estMinutes: 25,
    summary: "A service mesh moves service-to-service concerns (mTLS, retries, traffic splitting, telemetry) out of application code into proxies controlled by a central control plane. Covers Envoy, Istio, Linkerd and sidecarless (ambient) designs.",
    what: `A **service mesh** is an infrastructure layer that handles communication **between services** (east-west traffic). It has two parts:

- **Data plane** \u2014 proxies that sit in the path of every request between services and actually move the bytes. Traditionally one **sidecar proxy** per Pod.
- **Control plane** \u2014 a central component that configures all proxies: routing rules, security policy, certificates.

**Envoy** is a high-performance L7 proxy and the data plane of many meshes (Istio among them) and of many gateways. **Istio** and **Linkerd** are the best-known meshes; both are CNCF graduated, as is Envoy. Linkerd uses its own lightweight Rust proxy rather than Envoy.`,
    why: `In a microservice system, every service needs the same networking features: encryption, service identity, retries with timeouts, circuit breaking, gradual traffic shifting, and golden-signal metrics. Implementing them in each language's libraries means inconsistent behaviour and coupling every team to the platform's release cycle. A mesh provides them **uniformly, without code changes**.`,
    problem: `Analogy: in an office without a mailroom, every employee must know how to encrypt letters, verify senders, retry failed deliveries and log what they sent \u2014 and each does it slightly differently. A mesh installs a **mailroom clerk at every desk** (the sidecar). Employees hand over plain letters; the clerks encrypt, verify, retry and keep records, all following rules issued by **head office** (the control plane).

The cost: a clerk at every desk takes space and adds a little delay. That cost motivated sidecarless designs.`,
    how: `Trace a call from \`frontend\` to \`orders\` in a sidecar mesh:

- **1. Injection.** When the namespace is enabled for the mesh, a mutating admission webhook adds a proxy container (and traffic-redirect setup) to each new Pod.
- **2. Interception.** The app calls \`http://orders\` as usual. iptables rules (or a CNI plugin) redirect the outbound connection to the local sidecar.
- **3. Routing.** The sidecar applies rules pushed by the control plane, e.g. 90% to \`orders\` v1 and 10% to v2, a 2-second timeout, up to 3 retries.
- **4. mTLS.** The client sidecar opens a **mutual TLS** connection to the server's sidecar. Both present certificates issued by the mesh's certificate authority that encode **workload identity** (based on the ServiceAccount). Traffic is encrypted and each side knows who the other is.
- **5. Authorization.** The server-side proxy checks policy: is \`frontend\`'s identity allowed to call \`POST /orders\`?
- **6. Delivery and telemetry.** The request reaches the \`orders\` container over localhost. Both proxies record metrics (requests, errors, latency) and can emit trace spans \u2014 giving uniform observability for free, though apps must still forward trace headers for traces to connect.

**Sidecarless / ambient** designs split this up: in Istio's **ambient mode**, a per-node proxy (**ztunnel**) provides mTLS and L4 features for all Pods on the node, and optional **waypoint proxies** (Envoy-based) are deployed only where L7 features are needed. This lowers per-Pod resource cost and avoids restarting Pods to inject sidecars.`,
    components: [
      { name: "Data plane", description: "Proxies on the request path: per-Pod sidecars, or per-node and per-namespace/service proxies in ambient-style designs." },
      { name: "Control plane", description: "Distributes configuration and certificates to proxies (e.g. Istio's `istiod`). Not on the request path." },
      { name: "Envoy", description: "CNCF graduated L4/L7 proxy configured dynamically through its xDS APIs. Used by Istio and by many API gateways and ingress controllers." },
      { name: "Mutual TLS (mTLS)", description: "Both client and server authenticate with certificates, giving encryption in transit plus service identity for authorization." },
      { name: "Traffic management", description: "Retries, timeouts, circuit breaking, weighted splits for canaries, traffic mirroring and fault injection." },
      { name: "Istio / Linkerd", description: "Istio: feature-rich, Envoy-based, sidecar or ambient modes. Linkerd: focused on simplicity, with its own Rust micro-proxy." }
    ],
    misconceptions: [
      { myth: "A service mesh replaces Kubernetes Services and the CNI.", reality: "The mesh builds on them. Pods still get IPs from the CNI plugin, and Services/DNS still name the destinations; the mesh adds L7 behaviour and security on top." },
      { myth: "mTLS in a mesh is the same as a NetworkPolicy.", reality: "NetworkPolicy filters by IP/port/labels at L3/L4 and is enforced by the CNI. Mesh authorization uses cryptographic identity and can match L7 attributes such as HTTP paths. They complement each other." },
      { myth: "Every cluster should run a service mesh.", reality: "A mesh adds components, resource overhead and operational complexity. It pays off when you need uniform mTLS, fine-grained traffic control or consistent telemetry across many services." }
    ],
    example: {
      title: "A 90/10 canary and strict mTLS in Istio",
      description: "Istio custom resources: a VirtualService splits traffic between subsets (defined by a DestinationRule, not shown), and a PeerAuthentication requires mTLS for all workloads in the namespace.",
      language: "yaml",
      code: `apiVersion: networking.istio.io/v1
kind: VirtualService
metadata:
  name: orders
  namespace: shop
spec:
  hosts:
    - orders
  http:
    - route:
        - destination: { host: orders, subset: v1 }
          weight: 90
        - destination: { host: orders, subset: v2 }
          weight: 10
      timeout: 2s
      retries:
        attempts: 3
---
apiVersion: security.istio.io/v1
kind: PeerAuthentication
metadata:
  name: default
  namespace: shop
spec:
  mtls:
    mode: STRICT`
    },
    exercise: {
      prompt: `Your security team requires that all traffic between services is encrypted and that only \`frontend\` may call \`payments\`. A teammate proposes adding TLS libraries to all 30 services and IP allow-lists. Describe how a service mesh would meet both requirements instead, and one cost of doing so.`,
      solution: `- **Encryption**: enable mesh-wide **strict mTLS**. Proxies encrypt every connection automatically; certificates are issued and rotated by the mesh CA \u2014 no app changes.
- **Only frontend \u2192 payments**: write an authorization policy on \`payments\` allowing only the **workload identity** of \`frontend\` (derived from its ServiceAccount). Identities survive Pod rescheduling, unlike IP allow-lists, which break as Pod IPs change.

Costs: extra CPU/memory for proxies (per Pod with sidecars), a small latency increase per hop, and a new control plane to operate and upgrade.`
    },
    faq: [
      { q: "Is Envoy a service mesh?", a: "No. Envoy is a proxy. A mesh is many proxies plus a control plane that configures them. Istio uses Envoy as its data plane." },
      { q: "How does the Gateway API relate to service meshes?", a: "Gateway API was designed for ingress, but its GAMMA initiative extends routes such as `HTTPRoute` to east-west mesh traffic, giving meshes a common, vendor-neutral configuration API." },
      { q: "Do apps need changes to join a mesh?", a: "Usually not for mTLS, retries or metrics. For distributed traces to connect across hops, apps must still propagate trace headers from incoming to outgoing requests." }
    ],
    keyTerms: ["service mesh", "data plane", "control plane", "sidecar proxy", "Envoy", "mTLS", "Istio ambient mode", "Linkerd"],
    deeper: `Envoy is configured through **xDS** discovery APIs (listeners, routes, clusters, endpoints, secrets), which is what lets a control plane update thousands of proxies without restarts. Some CNI-based approaches (for example Cilium's) implement parts of mesh functionality using eBPF in the kernel combined with a per-node Envoy, another variation of the sidecarless idea.`,
    references: [
      { title: "Envoy documentation", url: "https://www.envoyproxy.io/docs" },
      { title: "Istio documentation", url: "https://istio.io/latest/docs/" },
      { title: "Linkerd", url: "https://linkerd.io/" }
    ]
  },
  {
    id: "cncf-community-and-governance",
    title: "CNCF Community and Governance",
    stage: 7,
    order: 6,
    objectives: ["cna-community"],
    scope: "kcna",
    estMinutes: 20,
    summary: "How the cloud native ecosystem is organised: the CNCF under the Linux Foundation, the TOC and project maturity levels, how Kubernetes itself is governed through SIGs and KEPs, the open standards (OCI, CRI, CNI, CSI) that keep it pluggable, and the roles people play.",
    what: `The **Cloud Native Computing Foundation (CNCF)** is a vendor-neutral foundation, part of the **Linux Foundation**, founded in 2015 with Kubernetes (contributed by Google) as its first project. It hosts open-source projects, runs events such as KubeCon + CloudNativeCon, and offers certifications including KCNA, CKA, CKAD and CKS.

Key structures:

- **Governing Board** \u2014 handles budget, marketing and business matters.
- **Technical Oversight Committee (TOC)** \u2014 the technical authority: defines the cloud native vision, accepts projects and votes on maturity changes. It is supported by **Technical Advisory Groups (TAGs)** focused on areas such as security or observability.
- **Projects** \u2014 each has its own maintainers and governance. The CNCF owns trademarks and provides neutral infrastructure; it does not run projects day to day.`,
    why: `KCNA's "Cloud Native Community and Collaboration" competency tests whether you understand how this ecosystem works \u2014 who decides, how mature a project is, and why standards matter. Practically, project maturity is a signal when choosing tools, and knowing how Kubernetes evolves (KEPs, SIGs, release cycle) explains why features move from alpha to GA over several releases.`,
    problem: `Thousands of contributors from competing companies build shared infrastructure. Without neutral governance, one vendor could steer a project for its own benefit, and users could not trust its long-term direction. Without **open standards**, every runtime, network plugin and storage driver would need custom integration with every orchestrator.`,
    how: `**A project's path through the CNCF:**

- **1. Sandbox** \u2014 entry level for early-stage projects. Low bar; experimentation encouraged. Not a statement of production readiness.
- **2. Incubating** \u2014 the project shows production use by multiple adopters, a healthy contributor base and sound governance. Requires TOC due diligence and vote.
- **3. Graduated** \u2014 highest level: broad adoption, committers from multiple organisations, a completed independent security audit, and adoption of the CNCF Code of Conduct. Kubernetes, Prometheus, Envoy, containerd, CoreDNS, etcd, Helm, Argo, Flux, Istio and Linkerd are examples.
- Projects can also be **archived** when no longer active.

**How Kubernetes itself evolves:**

- Work is organised into **Special Interest Groups (SIGs)** owning areas (SIG Network, SIG Storage, SIG Node, SIG Auth...), plus temporary **Working Groups**. A **Steering Committee** oversees project governance.
- Significant changes are proposed as a **Kubernetes Enhancement Proposal (KEP)** in the \`kubernetes/enhancements\` repository, describing motivation, design, test plan and graduation criteria.
- Features progress **alpha \u2192 beta \u2192 stable** across releases, typically behind **feature gates** until GA. Kubernetes ships about **three minor releases per year**.

**Open standards that make it pluggable:**

- **OCI** (Open Container Initiative, a Linux Foundation project) \u2014 image, runtime and distribution specifications.
- **CRI** \u2014 Container Runtime Interface between kubelet and runtimes (containerd, CRI-O).
- **CNI** \u2014 Container Network Interface for network plugins (Calico, Cilium, Flannel).
- **CSI** \u2014 Container Storage Interface for storage drivers.`,
    components: [
      { name: "CNCF / Linux Foundation", description: "Vendor-neutral home for cloud native projects; owns trademarks, funds infrastructure, runs events and certifications." },
      { name: "TOC and TAGs", description: "Technical Oversight Committee decides project acceptance and maturity; Technical Advisory Groups provide domain expertise and guidance." },
      { name: "Maturity levels", description: "Sandbox \u2192 Incubating \u2192 Graduated (and Archived). A signal of adoption and governance, not a guarantee of fit." },
      { name: "SIGs and KEPs", description: "Kubernetes' units of ownership and its design-proposal process for significant changes." },
      { name: "Open standards", description: "OCI, CRI, CNI and CSI decouple Kubernetes from specific runtimes, networks and storage." },
      { name: "Roles", description: "Developers, DevOps engineers, **Site Reliability Engineers** (apply software engineering to operations, own SLOs and error budgets), **platform engineers** (build internal developer platforms as self-service products), security engineers, maintainers and contributors." }
    ],
    misconceptions: [
      { myth: "The CNCF develops Kubernetes and decides its features.", reality: "Features are designed and built by the Kubernetes community through SIGs and KEPs. The CNCF provides neutral governance, funding and infrastructure." },
      { myth: "Sandbox means a project is endorsed for production.", reality: "Sandbox is an early-stage entry point. Maturity grows to Incubating and Graduated as adoption and governance are demonstrated." },
      { myth: "Graduated projects are finished and stop changing.", reality: "Graduation reflects maturity of adoption and governance. Graduated projects continue active development and releases." },
      { myth: "Only employees of big vendors can contribute.", reality: "Anyone can contribute: docs, issue triage, tests, code reviews, SIG meetings. Most SIG meetings are public and recorded." }
    ],
    example: {
      title: "Matching projects to standards and maturity",
      description: "A quick mental map of interfaces and the well-known graduated projects that implement or surround them.",
      language: "text",
      code: `Interface / area    Defined by          Example implementations (CNCF graduated unless noted)
-----------------   -----------------   -----------------------------------------------------
Image & runtime     OCI specs           containerd, CRI-O (both implement CRI as well)
Kubelet -> runtime  CRI (Kubernetes)    containerd, CRI-O
Pod networking      CNI                 Cilium, Calico (non-CNCF), Flannel (non-CNCF)
Storage             CSI                 Cloud provider drivers, Rook-Ceph
Cluster DNS         \u2014                   CoreDNS
Cluster state       \u2014                   etcd
Metrics             \u2014                   Prometheus
Service proxy/mesh  \u2014                   Envoy, Istio, Linkerd
Packaging/GitOps    \u2014                   Helm, Argo, Flux`
    },
    exercise: {
      prompt: `A team wants a new Kubernetes API field. Describe the path from idea to a stable feature, naming the groups and documents involved.`,
      solution: `- Discuss the idea with the owning **SIG** (e.g. SIG Apps for workload APIs) at a SIG meeting or on its channels.
- Write a **KEP** in \`kubernetes/enhancements\` covering motivation, design, alternatives, test plan and graduation criteria; get it reviewed and approved by the SIG (and API reviewers).
- Implement it as **alpha**, usually behind a feature gate disabled by default, in a release.
- After feedback and meeting criteria, promote to **beta**, then **stable (GA)** in later releases, where the feature gate is eventually removed. This usually spans several releases.`
    },
    faq: [
      { q: "How do I check a project's maturity?", a: "Use the CNCF projects page or the CNCF Landscape. Maturity changes over time, so check the current status rather than memorising old lists." },
      { q: "What is the difference between DevOps, SRE and platform engineering?", a: "DevOps is a culture of shared ownership between development and operations. SRE is a concrete practice of running services with software engineering, SLOs and error budgets. Platform engineering builds internal self-service platforms so product teams can ship without becoming infrastructure experts." },
      { q: "Is the Open Container Initiative part of the CNCF?", a: "No. OCI is a separate Linux Foundation project. The CNCF projects (containerd, CRI-O, Kubernetes) implement its specifications." }
    ],
    keyTerms: ["CNCF", "Linux Foundation", "Technical Oversight Committee", "sandbox / incubating / graduated", "SIG", "KEP", "OCI / CRI / CNI / CSI", "platform engineering"],
    deeper: `The **CNCF Landscape** maps thousands of cloud native projects and products, CNCF-hosted or not, by category; the CNCF **Trail Map** historically suggested an adoption order (containers \u2192 CI/CD \u2192 orchestration \u2192 observability \u2192 service mesh...). Kubernetes conformance is a separate programme: vendors run the conformance test suite to become **Certified Kubernetes**, which guarantees the same core APIs behave consistently across distributions.`,
    references: [
      { title: "CNCF projects", url: "https://www.cncf.io/projects/" },
      { title: "CNCF TOC repository", url: "https://github.com/cncf/toc" },
      { title: "Kubernetes community (SIGs)", url: "https://github.com/kubernetes/community" }
    ]
  }
];

// ../../packages/content/src/questions/fundamentals.ts
var R = {
  components: { title: "Kubernetes Components", url: "https://kubernetes.io/docs/concepts/overview/components/" },
  architecture: { title: "Cluster Architecture", url: "https://kubernetes.io/docs/concepts/architecture/" },
  objects: { title: "Objects in Kubernetes", url: "https://kubernetes.io/docs/concepts/overview/working-with-objects/" },
  objectMgmt: {
    title: "Kubernetes Object Management",
    url: "https://kubernetes.io/docs/concepts/overview/working-with-objects/object-management/"
  },
  controller: { title: "Controllers", url: "https://kubernetes.io/docs/concepts/architecture/controller/" },
  cloudController: { title: "Cloud Controller Manager", url: "https://kubernetes.io/docs/concepts/architecture/cloud-controller/" },
  nodes: { title: "Nodes", url: "https://kubernetes.io/docs/concepts/architecture/nodes/" },
  cri: { title: "Container Runtime Interface (CRI)", url: "https://kubernetes.io/docs/concepts/architecture/cri/" },
  admission: {
    title: "Admission Control in Kubernetes",
    url: "https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/"
  },
  pods: { title: "Pods", url: "https://kubernetes.io/docs/concepts/workloads/pods/" },
  initContainers: { title: "Init Containers", url: "https://kubernetes.io/docs/concepts/workloads/pods/init-containers/" },
  sidecars: { title: "Sidecar Containers", url: "https://kubernetes.io/docs/concepts/workloads/pods/sidecar-containers/" },
  deployment: { title: "Deployments", url: "https://kubernetes.io/docs/concepts/workloads/controllers/deployment/" },
  replicaset: { title: "ReplicaSet", url: "https://kubernetes.io/docs/concepts/workloads/controllers/replicaset/" },
  job: { title: "Jobs", url: "https://kubernetes.io/docs/concepts/workloads/controllers/job/" },
  cronjob: { title: "CronJob", url: "https://kubernetes.io/docs/concepts/workloads/controllers/cron-jobs/" },
  daemonset: { title: "DaemonSet", url: "https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/" },
  statefulset: { title: "StatefulSets", url: "https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/" },
  labels: {
    title: "Labels and Selectors",
    url: "https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/"
  },
  namespaces: { title: "Namespaces", url: "https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/" },
  probes: {
    title: "Configure Liveness, Readiness and Startup Probes",
    url: "https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/"
  },
  configmap: { title: "ConfigMaps", url: "https://kubernetes.io/docs/concepts/configuration/configmap/" },
  secret: { title: "Secrets", url: "https://kubernetes.io/docs/concepts/configuration/secret/" },
  resources: {
    title: "Resource Management for Pods and Containers",
    url: "https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/"
  },
  qos: { title: "Pod Quality of Service Classes", url: "https://kubernetes.io/docs/concepts/workloads/pods/pod-qos/" },
  quota: { title: "Resource Quotas", url: "https://kubernetes.io/docs/concepts/policy/resource-quotas/" },
  limitRange: { title: "Limit Ranges", url: "https://kubernetes.io/docs/concepts/policy/limit-range/" },
  scheduler: { title: "Kubernetes Scheduler", url: "https://kubernetes.io/docs/concepts/scheduling-eviction/kube-scheduler/" },
  assignPod: {
    title: "Assigning Pods to Nodes",
    url: "https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/"
  },
  taints: {
    title: "Taints and Tolerations",
    url: "https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/"
  },
  priority: {
    title: "Pod Priority and Preemption",
    url: "https://kubernetes.io/docs/concepts/scheduling-eviction/pod-priority-preemption/"
  },
  kubectl: { title: "Command line tool (kubectl)", url: "https://kubernetes.io/docs/reference/kubectl/" },
  kubeconfig: {
    title: "Organizing Cluster Access Using kubeconfig Files",
    url: "https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/"
  },
  crd: {
    title: "Custom Resources",
    url: "https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/"
  },
  operator: { title: "Operator pattern", url: "https://kubernetes.io/docs/concepts/extend-kubernetes/operator/" },
  skew: { title: "Version Skew Policy", url: "https://kubernetes.io/releases/version-skew-policy/" },
  kubeadmUpgrade: {
    title: "Upgrading kubeadm clusters",
    url: "https://kubernetes.io/docs/tasks/administer-cluster/kubeadm/kubeadm-upgrade/"
  }
};
var questionsFundamentals = [
  // ---------------------------------------------------------------- kf-core
  {
    id: "q-kf-core-001",
    domain: "fundamentals",
    objective: "kf-core",
    lessonId: "yaml-for-kubernetes",
    difficulty: 1,
    type: "single",
    prompt: "You are writing a Deployment manifest from scratch. Which set of top-level fields does it need?",
    choices: [
      "`name`, `image`, `ports`, `replicas`",
      "`kind`, `version`, `labels`, `status`",
      "`apiVersion`, `kind`, `metadata`, `spec`",
      "`apiVersion`, `type`, `metadata`, `data`"
    ],
    answer: [2],
    explanation: "Workload manifests start with `apiVersion` (the API group/version), `kind` (the object type), `metadata` (name, namespace, labels) and `spec` (the desired state). Fields like `image` and `replicas` live inside `spec`, not at the top level.",
    choiceRationale: [
      "These are fields nested inside the spec or the container definition, not top-level fields.",
      "`version` is not a field (it is `apiVersion`), labels belong under `metadata`, and `status` is written by the cluster.",
      "Correct: these four top-level fields describe what the object is, who it is, and what you want.",
      "`data` is used by ConfigMaps and Secrets and `type` by Secrets; a Deployment needs `kind` and `spec`."
    ],
    references: [R.objects],
    tags: ["yaml", "manifests", "api-objects"]
  },
  {
    id: "q-kf-core-002",
    domain: "fundamentals",
    objective: "kf-core",
    lessonId: "yaml-for-kubernetes",
    difficulty: 2,
    type: "single",
    prompt: "After applying a Deployment, an engineer runs `kubectl get deployment web -o yaml` and sees a large top-level section they never wrote. Which section is that, populated by Kubernetes to report the current state?",
    choices: ["`status`", "`spec`", "`metadata.labels`", "`apiVersion`"],
    answer: [0],
    explanation: "The `status` section is written by the control plane and describes the observed state, such as available replicas and conditions. You author `spec` (desired state); controllers continuously work to make `status` match it.",
    choiceRationale: [
      "Correct: `status` reports the observed state and is maintained by controllers, not by the user.",
      "`spec` is the desired state that the user writes in the manifest.",
      "Labels are user-supplied metadata used for selection and grouping.",
      "`apiVersion` is part of the manifest the user writes and identifies the API group and version."
    ],
    references: [R.objects],
    tags: ["yaml", "spec-vs-status", "api-objects"]
  },
  {
    id: "q-kf-core-003",
    domain: "fundamentals",
    objective: "kf-core",
    lessonId: "cluster-architecture",
    difficulty: 1,
    type: "single",
    prompt: "Which component runs on every node and ensures that the containers described in the Pods assigned to that node are running and healthy?",
    choices: ["kube-scheduler", "kube-controller-manager", "etcd", "kubelet"],
    answer: [3],
    explanation: "The kubelet is the node agent. It watches the API server for Pods bound to its node, asks the container runtime to start their containers, runs probes, and reports Pod and node status back.",
    choiceRationale: [
      "The scheduler only chooses a node for a Pod; it does not run containers.",
      "The controller manager runs control loops such as the ReplicaSet controller on the control plane, not on each node.",
      "etcd is the key-value store that holds cluster state; it does not manage containers.",
      "Correct: the kubelet is the per-node agent that runs and monitors Pod containers."
    ],
    references: [R.components],
    tags: ["architecture", "kubelet", "node"]
  },
  {
    id: "q-kf-core-004",
    domain: "fundamentals",
    objective: "kf-core",
    lessonId: "cluster-architecture",
    difficulty: 1,
    type: "multi",
    prompt: "Select TWO components that are part of the Kubernetes control plane.",
    choices: ["kube-apiserver", "kube-proxy", "etcd", "Container runtime (e.g. containerd)"],
    answer: [0, 2],
    explanation: "The control plane consists of kube-apiserver, etcd, kube-scheduler, kube-controller-manager and optionally cloud-controller-manager. kube-proxy and the container runtime are node components that run on every node.",
    choiceRationale: [
      "Correct: the API server is the front end of the control plane.",
      "kube-proxy is a node component that programs Service networking rules on each node.",
      "Correct: etcd is the control plane store holding all cluster data.",
      "The container runtime is a node component used by the kubelet to run containers."
    ],
    references: [R.components, R.architecture],
    tags: ["architecture", "control-plane", "etcd"]
  },
  {
    id: "q-kf-core-005",
    domain: "fundamentals",
    objective: "kf-core",
    lessonId: "api-server-and-etcd",
    difficulty: 1,
    type: "single",
    prompt: "Which component is the only one that reads from and writes to etcd directly?",
    choices: ["kube-scheduler", "kube-apiserver", "kubelet", "kube-controller-manager"],
    answer: [1],
    explanation: "All other components, including the scheduler, controllers and kubelets, interact with cluster state through the kube-apiserver. The API server is the sole client of etcd, which lets it enforce authentication, authorization, admission and validation for every change.",
    choiceRationale: [
      "The scheduler watches and binds Pods through the API server, never via etcd.",
      "Correct: the API server is the single gateway to etcd.",
      "The kubelet reads its Pods and reports status via the API server.",
      "Controllers watch and update objects through the API server, not etcd."
    ],
    references: [R.components],
    tags: ["api-server", "etcd", "control-plane"]
  },
  {
    id: "q-kf-core-006",
    domain: "fundamentals",
    objective: "kf-core",
    lessonId: "api-server-and-etcd",
    difficulty: 2,
    type: "single",
    prompt: "A `kubectl create` request reaches the kube-apiserver. In which order is it processed?",
    choices: [
      "Authorization, authentication, admission control, persisted to etcd",
      "Admission control, authentication, authorization, persisted to etcd",
      "Authentication, authorization, admission control, persisted to etcd",
      "Authentication, admission control, persisted to etcd, authorization"
    ],
    answer: [2],
    explanation: "The API server first establishes who the caller is (authentication), then whether they may perform the action (authorization), then lets admission controllers mutate or validate the object. Only after passing all three is the object persisted to etcd.",
    choiceRationale: [
      "Authorization cannot be decided before the caller is identified.",
      "Admission control runs after the request is authenticated and authorized.",
      "Correct: authn, then authz, then admission, then storage in etcd.",
      "Authorization must happen before the object is persisted, not after."
    ],
    references: [R.admission, R.components],
    tags: ["api-server", "admission", "request-flow"]
  },
  {
    id: "q-kf-core-007",
    domain: "fundamentals",
    objective: "kf-core",
    lessonId: "control-plane-controllers",
    difficulty: 2,
    type: "single",
    prompt: "A team deletes a Pod that belongs to a ReplicaSet, and a replacement Pod object appears within seconds. Which component created the replacement Pod object?",
    choices: [
      "kube-controller-manager",
      "kube-scheduler",
      "The kubelet on the node where the Pod ran",
      "etcd"
    ],
    answer: [0],
    explanation: "The ReplicaSet controller runs inside kube-controller-manager. It notices fewer Pods than desired and creates a new Pod object through the API server; the scheduler then places it and a kubelet starts it.",
    choiceRationale: [
      "Correct: the ReplicaSet controller in kube-controller-manager creates the replacement Pod object.",
      "The scheduler only assigns existing unscheduled Pods to nodes; it never creates Pods.",
      "The kubelet runs Pods bound to its node but does not create Pod objects for ReplicaSets.",
      "etcd only stores data and has no control logic."
    ],
    references: [R.controller, R.replicaset],
    tags: ["controllers", "controller-manager", "replicaset"]
  },
  {
    id: "q-kf-core-008",
    domain: "fundamentals",
    objective: "kf-core",
    lessonId: "control-plane-controllers",
    difficulty: 2,
    type: "single",
    prompt: "Which component links a cluster to a cloud provider API, for example to provision an external load balancer when a Service of type LoadBalancer is created?",
    choices: ["kube-proxy", "cloud-controller-manager", "kube-apiserver", "CoreDNS"],
    answer: [1],
    explanation: "The cloud-controller-manager embeds cloud-specific control loops, such as the service controller that creates cloud load balancers and the node controller that checks cloud instances. It keeps provider code out of the core Kubernetes components.",
    choiceRationale: [
      "kube-proxy programs in-cluster Service rules on nodes but does not call cloud APIs.",
      "Correct: the cloud-controller-manager runs the controllers that talk to the cloud provider.",
      "The API server stores the Service object but does not provision cloud resources.",
      "CoreDNS provides in-cluster DNS names and has no role in load balancer provisioning."
    ],
    references: [R.cloudController],
    tags: ["controllers", "cloud-controller-manager", "control-plane"]
  },
  {
    id: "q-kf-core-009",
    domain: "fundamentals",
    objective: "kf-core",
    lessonId: "node-components",
    difficulty: 1,
    type: "single",
    prompt: "Which node component maintains network rules (for example iptables or IPVS) so that traffic to a Service virtual IP reaches a backing Pod?",
    choices: ["kubelet", "containerd", "CoreDNS", "kube-proxy"],
    answer: [3],
    explanation: "kube-proxy watches Services and EndpointSlices and programs packet-forwarding rules on each node. Some CNI plugins can replace it, but in a standard cluster kube-proxy implements Service virtual IPs.",
    choiceRationale: [
      "The kubelet manages Pods and containers, not Service forwarding rules.",
      "containerd is a container runtime; it does not implement Services.",
      "CoreDNS resolves Service names to IPs but does not forward the traffic.",
      "Correct: kube-proxy programs the per-node rules behind Service virtual IPs."
    ],
    references: [R.components],
    tags: ["node", "kube-proxy", "services"]
  },
  {
    id: "q-kf-core-010",
    domain: "fundamentals",
    objective: "kf-core",
    lessonId: "node-components",
    difficulty: 2,
    type: "multi",
    prompt: "A cluster is being built on Kubernetes 1.31. Select TWO container runtimes the kubelet can use directly through the Container Runtime Interface (CRI).",
    choices: ["dockershim", "containerd", "kube-proxy", "CRI-O"],
    answer: [1, 3],
    explanation: "The kubelet talks to container runtimes over the CRI gRPC API. containerd and CRI-O implement CRI natively. dockershim, the built-in adapter for Docker Engine, was removed in Kubernetes 1.24.",
    choiceRationale: [
      "dockershim was removed from the kubelet in Kubernetes 1.24.",
      "Correct: containerd implements CRI and is a widely used runtime.",
      "kube-proxy handles Service networking and is not a container runtime.",
      "Correct: CRI-O is a CRI runtime built specifically for Kubernetes."
    ],
    references: [R.cri, R.components],
    tags: ["node", "cri", "container-runtime"]
  },
  {
    id: "q-kf-core-011",
    domain: "fundamentals",
    objective: "kf-core",
    lessonId: "node-components",
    difficulty: 2,
    type: "single",
    prompt: "The control plane marks a node `NotReady` (or `Unknown`) after it stops receiving that node's status updates and heartbeats. Which component on the node is responsible for sending them?",
    choices: ["kube-proxy", "kubelet", "The container runtime", "kube-scheduler"],
    answer: [1],
    explanation: "The kubelet registers the node, posts node status, and renews the node's Lease object as a heartbeat. When those updates stop, the node controller in kube-controller-manager marks the node as not ready or unknown.",
    choiceRationale: [
      "kube-proxy programs Service rules and does not report node health.",
      "Correct: the kubelet sends node status updates and Lease heartbeats.",
      "The runtime reports container state to the kubelet, not to the API server.",
      "The scheduler runs on the control plane and only reads node status."
    ],
    references: [R.nodes],
    tags: ["node", "kubelet", "heartbeat"]
  },
  {
    id: "q-kf-core-012",
    domain: "fundamentals",
    objective: "kf-core",
    lessonId: "declarative-reconciliation",
    difficulty: 1,
    type: "single",
    prompt: "What does a Kubernetes controller do in its control loop?",
    choices: [
      "Executes each submitted command once and then exits",
      "Picks a node for each Pod that has not been scheduled",
      "Compares observed state with desired state and acts to close the gap",
      "Converts YAML manifests to JSON before they are stored"
    ],
    answer: [2],
    explanation: "A controller watches the objects it is responsible for, compares their desired state (`spec`) with the actual state, and makes changes until they match. It repeats this continuously, which is what makes Kubernetes self-healing.",
    choiceRationale: [
      "Controllers run continuously rather than executing once and exiting.",
      "Node selection is the scheduler's job, a specific task rather than the general definition of a controller.",
      "Correct: reconciling actual state toward desired state is the core of a control loop.",
      "Format conversion is done by kubectl and the API machinery, not by controllers."
    ],
    references: [R.controller],
    tags: ["reconciliation", "controllers", "desired-state"]
  },
  {
    id: "q-kf-core-013",
    domain: "fundamentals",
    objective: "kf-core",
    lessonId: "declarative-reconciliation",
    difficulty: 2,
    type: "single",
    prompt: "Which of these workflows is declarative object management?",
    choices: [
      "Running `kubectl scale deployment web --replicas=5`",
      "Running `kubectl delete pod web-7d9c-xk2lp`",
      "Running `kubectl run test --image=nginx`",
      "Keeping manifests in Git and running `kubectl apply -f` on the directory"
    ],
    answer: [3],
    explanation: "In declarative management you describe the desired state in files and let `kubectl apply` work out which changes are needed. The other options are imperative commands that tell the cluster to perform a specific action.",
    choiceRationale: [
      "`kubectl scale` is an imperative command that changes one field directly.",
      "Deleting a named Pod is an imperative, one-off action.",
      "`kubectl run` imperatively creates a single Pod.",
      "Correct: versioned manifests plus `kubectl apply` is the declarative workflow."
    ],
    references: [R.objectMgmt],
    tags: ["declarative", "kubectl-apply", "imperative"]
  },
  {
    id: "q-kf-core-014",
    domain: "fundamentals",
    objective: "kf-core",
    lessonId: "declarative-reconciliation",
    difficulty: 3,
    type: "single",
    prompt: "A Deployment specifies 3 replicas. One of its Pods is evicted and deleted. Which sequence restores the replica count?",
    choices: [
      "The kubelet on a healthy node notices the gap and starts an extra container",
      "The ReplicaSet controller creates a new Pod object, the scheduler assigns it a node, and that node's kubelet starts it",
      "The scheduler notices fewer Pods, creates a replacement and places it on a node",
      "The API server recreates the same Pod with the same name on its original node"
    ],
    answer: [1],
    explanation: "Each component reconciles only its own piece. The ReplicaSet controller sees 2 of 3 Pods and creates a Pod object; the scheduler sees an unscheduled Pod and binds it to a node; the kubelet on that node sees a Pod bound to it and starts the containers.",
    choiceRationale: [
      "Kubelets only run Pods already bound to their node; they do not react to replica counts.",
      "Correct: controller creates, scheduler places, kubelet runs, each through the API server.",
      "The scheduler never creates Pods; it only assigns nodes to existing Pods.",
      "The API server has no reconciliation logic and replacement Pods get new generated names."
    ],
    references: [R.controller, R.replicaset],
    tags: ["reconciliation", "self-healing", "controllers"]
  },
  {
    id: "q-kf-core-015",
    domain: "fundamentals",
    objective: "kf-core",
    lessonId: "pods",
    difficulty: 1,
    type: "single",
    prompt: "What is the smallest deployable unit of computing that you create and manage in Kubernetes?",
    choices: ["Container", "Deployment", "Node", "Pod"],
    answer: [3],
    explanation: "Kubernetes schedules and manages Pods, not individual containers. A Pod wraps one or more tightly coupled containers that share networking and storage and are always placed together on one node.",
    choiceRationale: [
      "Containers always run inside a Pod; Kubernetes does not deploy bare containers.",
      "A Deployment is a higher-level controller that manages Pods through ReplicaSets.",
      "A node is a machine that runs Pods, not a deployable unit.",
      "Correct: the Pod is the smallest deployable unit in Kubernetes."
    ],
    references: [R.pods],
    tags: ["pods", "workloads", "basics"]
  },
  {
    id: "q-kf-core-016",
    domain: "fundamentals",
    objective: "kf-core",
    lessonId: "pods",
    difficulty: 3,
    type: "multi",
    prompt: "Select TWO things that containers in the same Pod share by default.",
    choices: [
      "The network namespace, so they share one IP address and port space",
      "A single root filesystem built from one merged image",
      "The process namespace, so each can see the others' processes",
      "Volumes declared in the Pod spec, which each container can mount"
    ],
    answer: [0, 3],
    explanation: "Containers in a Pod share a network namespace, so they reach each other on `localhost` and must not bind the same port. Volumes are declared at Pod level and can be mounted by any of its containers. Each container keeps its own root filesystem from its own image, and process namespace sharing is off unless `shareProcessNamespace: true` is set.",
    choiceRationale: [
      "Correct: all containers in a Pod share one IP and port space.",
      "Each container has its own root filesystem from its own image.",
      "Process namespace sharing is opt-in via `shareProcessNamespace`, not the default.",
      "Correct: Pod-level volumes can be mounted into any of the Pod's containers."
    ],
    references: [R.pods],
    tags: ["pods", "multi-container", "networking"]
  },
  {
    id: "q-kf-core-017",
    domain: "fundamentals",
    objective: "kf-core",
    lessonId: "pods",
    difficulty: 2,
    type: "single",
    prompt: "A Pod defines two regular init containers and one app container. How do they start?",
    choices: [
      "All three containers start at the same time",
      "The init containers run one at a time, each to successful completion, before the app container starts",
      "The app container starts first and the init containers run after it becomes ready",
      "The init containers run in parallel and the app container starts when either finishes"
    ],
    answer: [1],
    explanation: "Regular init containers run sequentially in the order listed, and each must exit successfully before the next starts. Only after all of them complete does the kubelet start the app containers. If an init container fails, it is retried according to the Pod's restart policy.",
    choiceRationale: [
      "Init containers always complete before the app containers start.",
      "Correct: init containers run in order, each to completion, before app containers.",
      "Init containers run before the app containers, not after.",
      "Init containers run sequentially, and all must succeed before the app container starts."
    ],
    references: [R.initContainers],
    tags: ["pods", "init-containers", "lifecycle"]
  },
  {
    id: "q-kf-core-018",
    domain: "fundamentals",
    objective: "kf-core",
    lessonId: "pods",
    difficulty: 3,
    type: "single",
    prompt: "A Job's Pod needs a log-shipping helper that starts before the main container, keeps running alongside it, and does not stop the Job from completing when the main container exits. Which approach fits current Kubernetes?",
    choices: [
      "Run the helper as a DaemonSet on the same nodes",
      "Add the helper as a second regular container after the main one",
      "Attach the helper later as an ephemeral container with `kubectl debug`",
      "Declare the helper as an init container with `restartPolicy: Always`"
    ],
    answer: [3],
    explanation: "Native sidecar containers are init containers with `restartPolicy: Always`. They start before the app containers, keep running for the Pod's lifetime, and are shut down after the main containers finish, so they do not block Job completion. The feature is stable since Kubernetes 1.33.",
    choiceRationale: [
      "A DaemonSet runs a separate Pod per node and is not tied to this Pod's lifecycle.",
      "A regular long-running container would keep the Pod running and block Job completion.",
      "Ephemeral containers are for interactive debugging and are not declared in the Pod spec up front.",
      "Correct: an init container with `restartPolicy: Always` is a native sidecar."
    ],
    references: [R.sidecars],
    tags: ["pods", "sidecar", "init-containers"]
  },
  {
    id: "q-kf-core-019",
    domain: "fundamentals",
    objective: "kf-core",
    lessonId: "replicasets-and-deployments",
    difficulty: 1,
    type: "single",
    prompt: "Which object does a Deployment create and manage directly in order to run its Pods?",
    choices: ["ReplicaSet", "StatefulSet", "Job", "DaemonSet"],
    answer: [0],
    explanation: "A Deployment owns one or more ReplicaSets, and each ReplicaSet owns the Pods. On every Pod template change the Deployment creates a new ReplicaSet and shifts replicas to it, which enables rolling updates and rollbacks.",
    choiceRationale: [
      "Correct: Deployments manage ReplicaSets, which manage Pods.",
      "StatefulSets are a separate workload type for stateful apps.",
      "Jobs run Pods to completion and are not created by Deployments.",
      "DaemonSets are a separate workload type that runs one Pod per node."
    ],
    references: [R.deployment],
    tags: ["deployment", "replicaset", "ownership"]
  },
  {
    id: "q-kf-core-020",
    domain: "fundamentals",
    objective: "kf-core",
    lessonId: "replicasets-and-deployments",
    difficulty: 3,
    type: "single",
    prompt: "An engineer changes a label on one running Pod so it no longer matches its ReplicaSet's selector. What happens?",
    choices: [
      "The ReplicaSet creates a replacement Pod, and the relabeled Pod keeps running without an owner",
      "The ReplicaSet deletes the relabeled Pod immediately",
      "Nothing changes, because ReplicaSets track their Pods by name",
      "The API server rejects the label change on a managed Pod"
    ],
    answer: [0],
    explanation: "ReplicaSets identify their Pods through label selectors. Once the Pod no longer matches, the ReplicaSet releases it and counts one Pod too few, so it creates a replacement. The relabeled Pod keeps running on its own, which is a common way to pull a Pod aside for debugging.",
    choiceRationale: [
      "Correct: the Pod is orphaned but keeps running, and a replacement is created.",
      "The ReplicaSet no longer considers the Pod its own, so it does not delete it.",
      "ReplicaSets select Pods by labels, not by names.",
      "Label changes on Pods are allowed; nothing protects selector labels from edits."
    ],
    references: [R.replicaset, R.labels],
    tags: ["replicaset", "labels", "selectors"]
  },
  {
    id: "q-kf-core-021",
    domain: "fundamentals",
    objective: "kf-core",
    lessonId: "replicasets-and-deployments",
    difficulty: 2,
    type: "single",
    prompt: "A team changes the container image in a Deployment's Pod template and applies it, without setting a strategy. What happens by default?",
    choices: [
      "Running containers are patched in place with the new image",
      "A new ReplicaSet is created and Pods are replaced gradually",
      "All old Pods are deleted before any new Pod is started",
      "Nothing happens until someone runs `kubectl rollout restart`"
    ],
    answer: [1],
    explanation: "The default Deployment strategy is `RollingUpdate`. Changing the Pod template creates a new ReplicaSet, which is scaled up while the old one is scaled down within the `maxSurge` and `maxUnavailable` limits (25% each by default).",
    choiceRationale: [
      "Pod templates are not patched into running Pods; new Pods are created instead.",
      "Correct: RollingUpdate is the default and uses a new ReplicaSet.",
      "This describes the `Recreate` strategy, which must be set explicitly.",
      "Any Pod template change triggers a rollout automatically."
    ],
    references: [R.deployment],
    tags: ["deployment", "rolling-update", "rollout"]
  },
  {
    id: "q-kf-core-022",
    domain: "fundamentals",
    objective: "kf-core",
    lessonId: "namespaces-labels-selectors",
    difficulty: 1,
    type: "single",
    prompt: "How does a Service or a ReplicaSet determine which Pods it applies to?",
    choices: ["By matching Pod names", "By reading Pod annotations", "By label selectors", "By namespace alone"],
    answer: [2],
    explanation: "Labels are key/value pairs on objects, and selectors query them. Services and ReplicaSets use selectors to find their Pods dynamically, so new Pods with matching labels are picked up automatically.",
    choiceRationale: [
      "Pod names are generated and change on every recreation, so they are not used for grouping.",
      "Annotations hold non-identifying metadata and cannot be selected on.",
      "Correct: label selectors are the grouping mechanism used by Services and controllers.",
      "Namespace scopes the search, but labels decide which Pods within it match."
    ],
    references: [R.labels],
    tags: ["labels", "selectors", "services"]
  },
  {
    id: "q-kf-core-023",
    domain: "fundamentals",
    objective: "kf-core",
    lessonId: "jobs-and-cronjobs",
    difficulty: 1,
    type: "single",
    prompt: "Which workload resource runs Pods until a specified number of them complete successfully?",
    choices: ["Deployment", "DaemonSet", "Job", "ReplicaSet"],
    answer: [2],
    explanation: "A Job tracks successful Pod completions and stops once `completions` is reached, retrying failed Pods up to `backoffLimit`. Deployments, ReplicaSets and DaemonSets are for long-running Pods that should be kept alive.",
    choiceRationale: [
      "Deployments keep long-running Pods alive and restart them if they exit.",
      "DaemonSets keep one long-running Pod per node.",
      "Correct: Jobs run Pods to successful completion.",
      "ReplicaSets keep a fixed number of Pods running, not completing."
    ],
    references: [R.job],
    tags: ["jobs", "batch", "workloads"]
  },
  {
    id: "q-kf-core-024",
    domain: "fundamentals",
    objective: "kf-core",
    lessonId: "jobs-and-cronjobs",
    difficulty: 2,
    type: "single",
    prompt: "A CronJob must run a report at 02:00 every day. Which `schedule` value expresses that?",
    choices: ["`0 2 * * *`", "`2 0 * * *`", "`* 2 * * *`", "`0 0 2 * *`"],
    answer: [0],
    explanation: "Cron fields are minute, hour, day of month, month and day of week. `0 2 * * *` means minute 0 of hour 2 on every day. Each run creates a Job, which then creates the Pods.",
    choiceRationale: [
      "Correct: minute 0, hour 2, every day.",
      "This is minute 2 of hour 0, so it runs at 00:02.",
      "This runs every minute between 02:00 and 02:59.",
      "This runs at midnight on the 2nd day of each month."
    ],
    references: [R.cronjob],
    tags: ["cronjobs", "jobs", "scheduling-syntax"]
  },
  {
    id: "q-kf-core-025",
    domain: "fundamentals",
    objective: "kf-core",
    lessonId: "daemonsets-and-statefulsets",
    difficulty: 1,
    type: "single",
    prompt: "A team needs a log collector Pod running on every node, including nodes added later. Which workload resource fits?",
    choices: ["StatefulSet", "Deployment", "DaemonSet", "Job"],
    answer: [2],
    explanation: "A DaemonSet ensures one copy of a Pod runs on each eligible node and automatically adds a Pod when a node joins. It is the standard choice for node agents such as log collectors, monitoring agents and CNI components.",
    choiceRationale: [
      "StatefulSets give Pods stable identities but do not place one per node.",
      "A Deployment runs a replica count and does not guarantee one Pod per node.",
      "Correct: DaemonSets run one Pod per eligible node.",
      "Jobs run Pods to completion rather than keeping agents running."
    ],
    references: [R.daemonset],
    tags: ["daemonset", "workloads", "node-agents"]
  },
  {
    id: "q-kf-core-026",
    domain: "fundamentals",
    objective: "kf-core",
    lessonId: "daemonsets-and-statefulsets",
    difficulty: 2,
    type: "single",
    prompt: "A database cluster needs each replica to keep a stable name (`db-0`, `db-1`, `db-2`) and its own persistent volume, even after being rescheduled. Which workload resource fits?",
    choices: [
      "StatefulSet",
      "Deployment with three replicas",
      "DaemonSet with a node selector",
      "ReplicaSet with a shared volume"
    ],
    answer: [0],
    explanation: "StatefulSets give each Pod a stable ordinal name and, through `volumeClaimTemplates`, its own PersistentVolumeClaim that follows it across rescheduling. Pods are created and scaled in order by default, which suits clustered databases.",
    choiceRationale: [
      "Correct: StatefulSets provide stable identities and per-replica storage.",
      "Deployment Pods get random names and are interchangeable.",
      "DaemonSets place one Pod per node and do not give ordinal identities.",
      "ReplicaSet Pods are interchangeable and a shared volume is not per-replica storage."
    ],
    references: [R.statefulset],
    tags: ["statefulset", "stateful", "storage"]
  },
  {
    id: "q-kf-core-027",
    domain: "fundamentals",
    objective: "kf-core",
    lessonId: "health-probes",
    difficulty: 2,
    type: "single",
    prompt: "A container is alive but cannot serve requests for 30 seconds while it reloads a cache. Which probe should fail during that window so the Pod stops receiving Service traffic without being restarted?",
    choices: ["livenessProbe", "startupProbe", "readinessProbe", "A `postStart` lifecycle hook"],
    answer: [2],
    explanation: "A failing readiness probe marks the Pod not ready, so it is removed from Service endpoints until the probe passes again. The container keeps running. A failing liveness probe would make the kubelet restart the container instead.",
    choiceRationale: [
      "A failing liveness probe restarts the container, which is not wanted here.",
      "Startup probes only apply during initial startup, not to later temporary unavailability.",
      "Correct: readiness controls whether the Pod receives Service traffic.",
      "A postStart hook runs once after the container starts and is not a health check."
    ],
    references: [R.probes],
    tags: ["probes", "readiness", "health"]
  },
  {
    id: "q-kf-core-028",
    domain: "fundamentals",
    objective: "kf-core",
    lessonId: "health-probes",
    difficulty: 3,
    type: "single",
    prompt: "A legacy application needs up to 3 minutes to boot. Its livenessProbe kills the container before it finishes starting, causing a restart loop. What is the most appropriate fix?",
    choices: [
      "Remove the readinessProbe so the Pod is considered ready earlier",
      "Set the Pod's `restartPolicy` to `Never`",
      "Raise the container's memory limit",
      "Add a startupProbe, which holds off liveness and readiness checks until it succeeds"
    ],
    answer: [3],
    explanation: "A startup probe is designed for slow-starting containers. Until it succeeds, the kubelet does not run liveness or readiness probes, so the container gets enough time to boot while keeping a tight liveness check afterwards.",
    choiceRationale: [
      "The readiness probe does not restart containers; the liveness probe is the cause.",
      "Disabling restarts hides the symptom and leaves the app dead after one failure.",
      "Nothing indicates a memory problem; the restarts come from liveness failures.",
      "Correct: a startupProbe protects slow startup from premature liveness kills."
    ],
    references: [R.probes],
    tags: ["probes", "startup", "liveness"]
  },
  {
    id: "q-kf-core-029",
    domain: "fundamentals",
    objective: "kf-core",
    lessonId: "configmaps-and-secrets",
    difficulty: 2,
    type: "multi",
    prompt: "Select TWO accurate statements about Kubernetes Secrets in a cluster with default settings.",
    choices: [
      "Secret values are base64-encoded, which is an encoding and not encryption",
      "Secret values are encrypted in etcd with a key generated at install time",
      "A user allowed to `get` a Secret in a namespace can read its decoded values",
      "Secrets can be mounted only as files and never exposed as environment variables"
    ],
    answer: [0, 2],
    explanation: "Secret data is base64-encoded and stored unencrypted in etcd unless encryption at rest is configured. Anyone with `get` access to the Secret can decode it, so RBAC on Secrets matters. Secrets can be consumed both as mounted files and as environment variables.",
    choiceRationale: [
      "Correct: base64 is reversible encoding, not a security control.",
      "Encryption at rest must be configured explicitly; it is not enabled by default.",
      "Correct: read access to the Secret object exposes its values.",
      "Secrets can also be injected as environment variables."
    ],
    references: [R.secret],
    tags: ["secrets", "security", "configuration"]
  },
  {
    id: "q-kf-core-030",
    domain: "fundamentals",
    objective: "kf-core",
    lessonId: "configmaps-and-secrets",
    difficulty: 3,
    type: "single",
    prompt: "A Pod reads settings from a ConfigMap through environment variables. The team updates the ConfigMap. What happens to the running Pod?",
    choices: [
      "Its environment variables update within about a minute",
      "The kubelet restarts the Pod automatically",
      "The ConfigMap update is rejected while Pods reference it",
      "It keeps the old values until the Pod is recreated"
    ],
    answer: [3],
    explanation: "Environment variables are set when a container starts and are not refreshed. To pick up new values, the Pod must be restarted or replaced, for example with a rollout. ConfigMaps mounted as volumes (without `subPath`) are updated in place eventually.",
    choiceRationale: [
      "Environment variables are fixed at container start; mounted volumes are what update.",
      "Kubernetes does not restart Pods when a referenced ConfigMap changes.",
      "Non-immutable ConfigMaps can be updated freely while in use.",
      "Correct: env values stay the same until the container is recreated."
    ],
    references: [R.configmap],
    tags: ["configmaps", "configuration", "environment"]
  },
  // ---------------------------------------------------------------- kf-admin
  {
    id: "q-kf-admin-001",
    domain: "fundamentals",
    objective: "kf-admin",
    lessonId: "namespaces-labels-selectors",
    difficulty: 1,
    type: "single",
    prompt: "Which of these resources is cluster-scoped rather than namespaced?",
    choices: ["ConfigMap", "Node", "Deployment", "ServiceAccount"],
    answer: [1],
    explanation: "Nodes, PersistentVolumes, Namespaces and ClusterRoles are cluster-scoped and exist outside any namespace. Most workload and configuration objects are namespaced. `kubectl api-resources --namespaced=false` lists the cluster-scoped ones.",
    choiceRationale: [
      "ConfigMaps are namespaced and can only be used by Pods in the same namespace.",
      "Correct: Nodes belong to the whole cluster, not to a namespace.",
      "Deployments are namespaced workload objects.",
      "ServiceAccounts are namespaced identities for Pods."
    ],
    references: [R.namespaces],
    tags: ["namespaces", "cluster-scoped", "api-resources"]
  },
  {
    id: "q-kf-admin-002",
    domain: "fundamentals",
    objective: "kf-admin",
    lessonId: "namespaces-labels-selectors",
    difficulty: 2,
    type: "single",
    prompt: "An engineer runs `kubectl get pods` and sees `No resources found`, although teammates confirm several Pods are running in the `payments` namespace. What is the most likely reason?",
    choices: [
      "Their current context targets a different namespace, such as `default`",
      "`kubectl get pods` only lists Pods created by the current user",
      "Pods in other namespaces stay hidden while RBAC is enabled",
      "The Pods are still `Pending`, and Pending Pods are not listed"
    ],
    answer: [0],
    explanation: "kubectl queries the namespace set in the current context, or `default` if none is set. The engineer should add `-n payments`, use `-A` for all namespaces, or set the namespace on the context with `kubectl config set-context --current --namespace=payments`.",
    choiceRationale: [
      "Correct: kubectl only looks in the context's namespace unless told otherwise.",
      "kubectl lists all Pods in the namespace regardless of who created them.",
      "RBAC would return a Forbidden error, not an empty list.",
      "Pending Pods are listed by `kubectl get pods` with status Pending."
    ],
    references: [R.namespaces, R.kubeconfig],
    tags: ["namespaces", "kubectl", "contexts"]
  },
  {
    id: "q-kf-admin-003",
    domain: "fundamentals",
    objective: "kf-admin",
    lessonId: "namespaces-labels-selectors",
    difficulty: 2,
    type: "multi",
    prompt: "Select TWO true statements about namespaces.",
    choices: [
      "Object names must be unique within a namespace, but can repeat across namespaces",
      "Namespaces block network traffic between Pods in different namespaces by default",
      "A ResourceQuota can cap the total resources consumed within a namespace",
      "Deleting a namespace moves its remaining Pods into the `default` namespace"
    ],
    answer: [0, 2],
    explanation: "Namespaces scope names and are the unit for policies such as ResourceQuota and RBAC Roles. They do not isolate network traffic by themselves; that requires NetworkPolicies. Deleting a namespace deletes every object inside it.",
    choiceRationale: [
      "Correct: `web` can exist in both `dev` and `prod` namespaces.",
      "Pods can reach each other across namespaces unless NetworkPolicies restrict it.",
      "Correct: ResourceQuotas are applied per namespace.",
      "Deleting a namespace deletes all objects in it; nothing is moved."
    ],
    references: [R.namespaces, R.quota],
    tags: ["namespaces", "multi-tenancy", "resourcequota"]
  },
  {
    id: "q-kf-admin-004",
    domain: "fundamentals",
    objective: "kf-admin",
    lessonId: "kubectl-and-cluster-administration",
    difficulty: 1,
    type: "single",
    prompt: "Unless `--kubeconfig` or the `KUBECONFIG` environment variable is set, which file does kubectl read to find clusters, users and contexts?",
    choices: [
      "`/etc/kubernetes/manifests/kube-apiserver.yaml`",
      "`/var/lib/kubelet/config.yaml`",
      "`~/.kube/config`",
      "`/etc/kubernetes/kubelet.conf`"
    ],
    answer: [2],
    explanation: "kubectl loads `$HOME/.kube/config` by default. A kubeconfig file lists clusters (API server endpoints and CA data), users (credentials) and contexts that pair a cluster with a user and an optional default namespace.",
    choiceRationale: [
      "This is a static Pod manifest for the API server on kubeadm control plane nodes.",
      "This is the kubelet's own configuration file on a node.",
      "Correct: `~/.kube/config` is kubectl's default kubeconfig.",
      "This is the kubelet's kubeconfig on kubeadm nodes, not kubectl's default."
    ],
    references: [R.kubeconfig],
    tags: ["kubeconfig", "kubectl", "contexts"]
  },
  {
    id: "q-kf-admin-005",
    domain: "fundamentals",
    objective: "kf-admin",
    lessonId: "kubectl-and-cluster-administration",
    difficulty: 1,
    type: "single",
    prompt: "Your kubeconfig already defines a context named `staging`. Which command makes it the active context?",
    choices: [
      "`kubectl config set-context staging`",
      "`kubectl config get-contexts staging`",
      "`kubectl config set-cluster staging`",
      "`kubectl config use-context staging`"
    ],
    answer: [3],
    explanation: "`kubectl config use-context` sets `current-context` in the kubeconfig, so subsequent commands target that context's cluster, user and namespace. `kubectl config current-context` shows which one is active.",
    choiceRationale: [
      "`set-context` creates or modifies a context entry but does not switch to it.",
      "`get-contexts` only lists contexts.",
      "`set-cluster` defines a cluster entry and does not change the active context.",
      "Correct: `use-context` switches the active context."
    ],
    references: [R.kubeconfig, R.kubectl],
    tags: ["kubeconfig", "contexts", "kubectl"]
  },
  {
    id: "q-kf-admin-006",
    domain: "fundamentals",
    objective: "kf-admin",
    lessonId: "kubectl-and-cluster-administration",
    difficulty: 2,
    type: "single",
    prompt: "A platform team wants a new `Backup` resource type that users can create, list and delete with kubectl just like built-in objects, without changing Kubernetes source code. What should they create?",
    choices: [
      "A ConfigMap with a `kind: Backup` key",
      "A validating admission webhook",
      "A CustomResourceDefinition",
      "A patched build of the kube-apiserver"
    ],
    answer: [2],
    explanation: "A CustomResourceDefinition registers a new resource type with the API server, which then serves it like any built-in kind. A custom controller is usually added to act on those objects; together they form the Operator pattern.",
    choiceRationale: [
      "A ConfigMap stores data but does not create a new API type.",
      "Admission webhooks validate or mutate requests but do not define new resource types.",
      "Correct: CRDs extend the Kubernetes API with new resource types.",
      "Rebuilding the API server is unnecessary; CRDs extend it without code changes."
    ],
    references: [R.crd],
    tags: ["crd", "extensibility", "api"]
  },
  {
    id: "q-kf-admin-007",
    domain: "fundamentals",
    objective: "kf-admin",
    lessonId: "kubectl-and-cluster-administration",
    difficulty: 2,
    type: "single",
    prompt: "Which description best matches the Kubernetes Operator pattern?",
    choices: [
      "A custom controller that uses custom resources to manage an application and automate its operational tasks",
      "A team role that holds cluster-admin rights and runs kubectl on behalf of developers",
      "A kubeadm phase that upgrades control plane components one minor version at a time",
      "A Helm chart that bundles Deployments and Services for a single application"
    ],
    answer: [0],
    explanation: "An operator encodes human operational knowledge (install, backup, upgrade, failover) into a controller. It watches custom resources and reconciles the application to the state they describe, using the same control-loop model as built-in controllers.",
    choiceRationale: [
      "Correct: operators are custom controllers driven by custom resources.",
      "Operators are software, not a human role.",
      "kubeadm upgrade is a cluster lifecycle tool, not the Operator pattern.",
      "A Helm chart packages manifests but has no ongoing control loop."
    ],
    references: [R.operator],
    tags: ["operators", "crd", "controllers"]
  },
  {
    id: "q-kf-admin-008",
    domain: "fundamentals",
    objective: "kf-admin",
    lessonId: "kubectl-and-cluster-administration",
    difficulty: 3,
    type: "single",
    prompt: "All kube-apiserver instances in a cluster run version 1.31. According to the Kubernetes version skew policy, which kubelet version is outside the supported range?",
    choices: ["1.31", "1.30", "1.28", "1.32"],
    answer: [3],
    explanation: "The kubelet must never be newer than the kube-apiserver, and may be up to three minor versions older (since Kubernetes 1.28). With an API server at 1.31, kubelets from 1.28 to 1.31 are supported, and 1.32 is not.",
    choiceRationale: [
      "Matching versions are always supported.",
      "One minor version older is within the allowed skew.",
      "Three minor versions older is the oldest supported kubelet.",
      "Correct: a kubelet newer than the API server is not supported."
    ],
    references: [R.skew],
    tags: ["version-skew", "upgrades", "kubelet"]
  },
  {
    id: "q-kf-admin-009",
    domain: "fundamentals",
    objective: "kf-admin",
    lessonId: "kubectl-and-cluster-administration",
    difficulty: 3,
    type: "single",
    prompt: "A team is upgrading a kubeadm-managed cluster by one minor version. Which order is recommended?",
    choices: [
      "Upgrade the kubelets on worker nodes first, then the control plane",
      "Upgrade the control plane nodes first, then drain, upgrade and uncordon each worker node",
      "Upgrade all nodes at the same time to avoid version skew",
      "Upgrade worker nodes first and finish with etcd once workers are healthy"
    ],
    answer: [1],
    explanation: "The control plane must be upgraded first because kubelets may not be newer than the API server. Worker nodes are then upgraded one at a time: drain the node, upgrade kubeadm and the kubelet, restart the kubelet, and uncordon it.",
    choiceRationale: [
      "Upgrading kubelets first would make them newer than the API server, which is unsupported.",
      "Correct: control plane first, then workers one by one with drain and uncordon.",
      "Upgrading everything at once risks a full outage and is not the documented process.",
      "kubeadm upgrades local etcd with the control plane, before the workers."
    ],
    references: [R.kubeadmUpgrade, R.skew],
    tags: ["kubeadm", "upgrades", "cluster-lifecycle"]
  },
  {
    id: "q-kf-admin-010",
    domain: "fundamentals",
    objective: "kf-admin",
    lessonId: "kubectl-and-cluster-administration",
    difficulty: 1,
    type: "multi",
    prompt: "Select TWO commands that help you discover which resource types the cluster serves and which fields a resource supports.",
    choices: [
      "`kubectl top nodes`",
      "`kubectl api-resources`",
      "`kubectl get events -A`",
      "`kubectl explain deployment.spec.strategy`"
    ],
    answer: [1, 3],
    explanation: "`kubectl api-resources` lists every resource type the API server serves, with short names, API group and whether it is namespaced. `kubectl explain` prints the documented fields of a resource, including nested paths.",
    choiceRationale: [
      "`kubectl top` shows CPU and memory usage from the metrics API.",
      "Correct: it lists all served resource types and their API groups.",
      "Events report what happened to objects, not what resource types exist.",
      "Correct: `kubectl explain` documents fields of a resource."
    ],
    references: [R.kubectl],
    tags: ["kubectl", "api-resources", "discovery"]
  },
  // ---------------------------------------------------------------- kf-scheduling
  {
    id: "q-kf-scheduling-001",
    domain: "fundamentals",
    objective: "kf-scheduling",
    lessonId: "control-plane-controllers",
    difficulty: 1,
    type: "single",
    prompt: "Which component decides which node a newly created Pod should run on?",
    choices: ["kube-controller-manager", "kubelet", "kube-proxy", "kube-scheduler"],
    answer: [3],
    explanation: "kube-scheduler watches for Pods without an assigned node, filters nodes that can run them, scores the remaining ones, and binds the Pod to the best node. The kubelet on that node then starts the Pod.",
    choiceRationale: [
      "The controller manager creates Pods for workloads but does not place them.",
      "The kubelet only runs Pods that are already assigned to its node.",
      "kube-proxy handles Service networking and has no role in placement.",
      "Correct: kube-scheduler assigns Pods to nodes."
    ],
    references: [R.scheduler],
    tags: ["scheduler", "control-plane", "placement"]
  },
  {
    id: "q-kf-scheduling-002",
    domain: "fundamentals",
    objective: "kf-scheduling",
    lessonId: "control-plane-controllers",
    difficulty: 2,
    type: "single",
    prompt: "How does kube-scheduler record its decision once it has chosen a node for a Pod?",
    choices: [
      "It binds the Pod through the API server, which sets the Pod's `spec.nodeName`",
      "It connects to the chosen node and starts the containers itself",
      "It writes the assignment directly into etcd, bypassing the API server",
      "It sends the Pod spec to kube-proxy on the chosen node"
    ],
    answer: [0],
    explanation: "The scheduler creates a Binding through the API server, which sets `spec.nodeName` on the Pod. The kubelet on that node is watching for Pods with its node name and starts the containers.",
    choiceRationale: [
      "Correct: the binding sets `spec.nodeName`, which the kubelet watches for.",
      "The scheduler never starts containers; the kubelet does.",
      "Only the API server talks to etcd directly.",
      "kube-proxy handles Service rules and does not run Pods."
    ],
    references: [R.scheduler, R.components],
    tags: ["scheduler", "binding", "api-server"]
  },
  {
    id: "q-kf-scheduling-003",
    domain: "fundamentals",
    objective: "kf-scheduling",
    lessonId: "resources-requests-limits",
    difficulty: 1,
    type: "single",
    prompt: "What does a container's resource **request** mainly affect?",
    choices: [
      "The hard ceiling the container can never exceed",
      "The order in which container images are pulled",
      "Where the Pod can be scheduled, since nodes must have that much unreserved capacity",
      "How many replicas a Deployment starts with"
    ],
    answer: [2],
    explanation: "The scheduler adds up the requests of all containers in a Pod and only places it on a node whose allocatable capacity minus existing requests can fit it. Limits, not requests, set the ceiling enforced at runtime.",
    choiceRationale: [
      "That describes a limit, not a request.",
      "Requests have no effect on image pull order.",
      "Correct: requests are what the scheduler reserves when placing the Pod.",
      "Replica count is set by `spec.replicas`, not by resource requests."
    ],
    references: [R.resources],
    tags: ["requests", "resources", "scheduling"]
  },
  {
    id: "q-kf-scheduling-004",
    domain: "fundamentals",
    objective: "kf-scheduling",
    lessonId: "resources-requests-limits",
    difficulty: 2,
    type: "single",
    prompt: "A container tries to use more memory than its memory limit. What typically happens?",
    choices: [
      "It is throttled, the same way CPU usage above a limit is",
      "It is terminated with reason `OOMKilled` and restarted according to the restart policy",
      "The Pod is moved to a node with more free memory",
      "The limit is raised automatically to match its usage"
    ],
    answer: [1],
    explanation: "Memory cannot be throttled, so when a container exceeds its memory limit the kernel OOM killer terminates it and Kubernetes reports `OOMKilled`. CPU above the limit is throttled instead. Repeated OOM kills often show up as CrashLoopBackOff.",
    choiceRationale: [
      "Throttling applies to CPU; memory over the limit leads to termination.",
      "Correct: exceeding a memory limit gets the container OOM-killed.",
      "Kubernetes does not migrate running Pods between nodes.",
      "Limits are never adjusted automatically by the kubelet."
    ],
    references: [R.resources],
    tags: ["limits", "oomkilled", "memory"]
  },
  {
    id: "q-kf-scheduling-005",
    domain: "fundamentals",
    objective: "kf-scheduling",
    lessonId: "resources-requests-limits",
    difficulty: 2,
    type: "single",
    prompt: "A Pod has two containers. In both, CPU and memory requests are set and equal to their respective limits. Which QoS class does the Pod get?",
    choices: ["Guaranteed", "Burstable", "BestEffort", "Critical"],
    answer: [0],
    explanation: "A Pod is Guaranteed when every container sets CPU and memory limits and requests that are equal. If some but not all of those conditions hold it is Burstable, and with no requests or limits at all it is BestEffort.",
    choiceRationale: [
      "Correct: equal requests and limits for CPU and memory in every container means Guaranteed.",
      "Burstable applies when requests are set but do not equal limits in every container.",
      "BestEffort applies only when no container has any requests or limits.",
      "There is no QoS class called Critical; criticality is expressed with PriorityClasses."
    ],
    references: [R.qos],
    tags: ["qos", "requests", "limits"]
  },
  {
    id: "q-kf-scheduling-006",
    domain: "fundamentals",
    objective: "kf-scheduling",
    lessonId: "resources-requests-limits",
    difficulty: 2,
    type: "multi",
    prompt: "A cluster admin wants to control resource consumption in the `dev` namespace. Select TWO objects designed for that.",
    choices: ["PriorityClass", "LimitRange", "RuntimeClass", "ResourceQuota"],
    answer: [1, 3],
    explanation: "A ResourceQuota caps the aggregate resources and object counts in a namespace. A LimitRange sets default, minimum and maximum requests and limits for individual containers or Pods in a namespace.",
    choiceRationale: [
      "PriorityClass sets scheduling priority and is cluster-scoped, not a consumption limit.",
      "Correct: LimitRange constrains and defaults per-container resources in a namespace.",
      "RuntimeClass selects a container runtime configuration.",
      "Correct: ResourceQuota caps total consumption in a namespace."
    ],
    references: [R.quota, R.limitRange],
    tags: ["resourcequota", "limitrange", "namespaces"]
  },
  {
    id: "q-kf-scheduling-007",
    domain: "fundamentals",
    objective: "kf-scheduling",
    lessonId: "scheduling-placement",
    difficulty: 1,
    type: "multi",
    prompt: "A Pod must only run on nodes labeled `disktype=ssd`. Select TWO Pod spec fields that can express this requirement.",
    choices: ["`spec.affinity.nodeAffinity`", "`spec.tolerations`", "`spec.nodeSelector`", "`spec.priorityClassName`"],
    answer: [0, 2],
    explanation: "`nodeSelector` is the simplest way to require node labels. Node affinity expresses the same thing with a richer syntax, including operators and preferred (soft) rules.",
    choiceRationale: [
      "Correct: required node affinity can match the `disktype=ssd` label.",
      "Tolerations allow scheduling onto tainted nodes but do not attract Pods to labeled nodes.",
      "Correct: `nodeSelector` restricts the Pod to nodes with matching labels.",
      "Priority affects ordering and preemption, not which nodes are eligible."
    ],
    references: [R.assignPod],
    tags: ["nodeselector", "node-affinity", "labels"]
  },
  {
    id: "q-kf-scheduling-008",
    domain: "fundamentals",
    objective: "kf-scheduling",
    lessonId: "scheduling-placement",
    difficulty: 2,
    type: "single",
    prompt: "A node has the taint `gpu=true:NoSchedule`. Which statement is correct?",
    choices: [
      "Pods with a matching toleration are always scheduled onto that node",
      "Only Pods with a matching toleration can be scheduled there, but the toleration does not force them onto it",
      "Running Pods on the node that lack a toleration are evicted immediately",
      "The taint acts as a node label, so `nodeSelector` can target it"
    ],
    answer: [1],
    explanation: "A taint repels Pods that do not tolerate it. A toleration only permits scheduling onto the tainted node; it does not attract the Pod there. The `NoSchedule` effect affects new scheduling only, while `NoExecute` also evicts running Pods.",
    choiceRationale: [
      "A toleration permits placement but does not require it.",
      "Correct: taints repel and tolerations permit, without attracting.",
      "Eviction of running Pods is the `NoExecute` effect, not `NoSchedule`.",
      "Taints are separate from labels and cannot be matched by `nodeSelector`."
    ],
    references: [R.taints],
    tags: ["taints", "tolerations", "placement"]
  },
  {
    id: "q-kf-scheduling-009",
    domain: "fundamentals",
    objective: "kf-scheduling",
    lessonId: "scheduling-placement",
    difficulty: 3,
    type: "single",
    prompt: "A team wants GPU nodes reserved for GPU workloads, and GPU workloads to run only on GPU nodes. Which combination achieves both?",
    choices: [
      "Add tolerations for the GPU taint to the GPU Pods only",
      "Add a `nodeSelector` for the GPU label to the GPU Pods only",
      "Add pod anti-affinity against GPU Pods to all non-GPU Pods",
      "Taint the GPU nodes, and give GPU Pods both a matching toleration and a node selector or node affinity"
    ],
    answer: [3],
    explanation: "The taint keeps other Pods off the GPU nodes. The toleration lets GPU Pods onto those nodes, and the node selector or affinity makes sure they go only there. Each mechanism alone covers only one of the two goals.",
    choiceRationale: [
      "Without a taint other Pods can still land on GPU nodes, and tolerations do not attract GPU Pods.",
      "This keeps GPU Pods on GPU nodes but does not stop other Pods from using them.",
      "Anti-affinity against Pods is fragile and does not reserve the nodes themselves.",
      "Correct: taint plus toleration reserves the nodes; selector or affinity pins the Pods."
    ],
    references: [R.taints, R.assignPod],
    tags: ["taints", "node-affinity", "dedicated-nodes"]
  },
  {
    id: "q-kf-scheduling-010",
    domain: "fundamentals",
    objective: "kf-scheduling",
    lessonId: "scheduling-placement",
    difficulty: 2,
    type: "single",
    prompt: "A new Pod stays `Pending` and its events show `0/3 nodes are available: 3 Insufficient cpu.` What is the most likely cause?",
    choices: [
      "The container's CPU limit is lower than the application needs",
      "The Pod's CPU request is larger than the unreserved CPU on every node",
      "The container image cannot be pulled from the registry",
      "The liveness probe fails before the container is ready"
    ],
    answer: [1],
    explanation: "The scheduler compares the Pod's requests against each node's allocatable capacity minus the requests of Pods already there. If no node fits, the Pod stays Pending with an `Insufficient cpu` reason. Lowering the request, freeing capacity or adding nodes resolves it.",
    choiceRationale: [
      "A low limit causes throttling at runtime, not a scheduling failure.",
      "Correct: no node has enough unreserved CPU for the Pod's request.",
      "Image pull problems happen after scheduling and show `ImagePullBackOff`.",
      "Probes run only after the Pod is scheduled and started."
    ],
    references: [R.scheduler, R.resources],
    tags: ["pending", "requests", "scheduler"]
  },
  {
    id: "q-kf-scheduling-011",
    domain: "fundamentals",
    objective: "kf-scheduling",
    lessonId: "scheduling-placement",
    difficulty: 3,
    type: "single",
    prompt: "A Deployment's replicas must never run two on the same node, and the rule must be strictly enforced at scheduling time. Which configuration fits?",
    choices: [
      "A `preferredDuringSchedulingIgnoredDuringExecution` pod affinity rule toward its own Pods",
      "A `nodeSelector` with `kubernetes.io/hostname` set to one node name",
      "A `requiredDuringSchedulingIgnoredDuringExecution` pod anti-affinity rule on its own labels with `topologyKey: kubernetes.io/hostname`",
      "A `NoSchedule` taint on every node and a toleration on the Deployment"
    ],
    answer: [2],
    explanation: "Required pod anti-affinity with the hostname topology key forbids placing a replica on a node that already runs a Pod with matching labels. If there are more replicas than eligible nodes, the extras stay Pending rather than doubling up.",
    choiceRationale: [
      "Pod affinity pulls Pods together, and a preferred rule is not strictly enforced.",
      "This pins all replicas onto a single node, the opposite of the goal.",
      "Correct: required anti-affinity per hostname keeps one replica per node.",
      "Taints and tolerations control which Pods may use nodes, not how replicas spread."
    ],
    references: [R.assignPod],
    tags: ["pod-anti-affinity", "high-availability", "placement"]
  },
  {
    id: "q-kf-scheduling-012",
    domain: "fundamentals",
    objective: "kf-scheduling",
    lessonId: "scheduling-placement",
    difficulty: 2,
    type: "single",
    prompt: "A Pod with a high PriorityClass cannot be scheduled because every node is full. What can kube-scheduler do?",
    choices: [
      "Add a new node to the cluster for the Pod",
      "Ignore the Pod's resource requests and place it anyway",
      "Preempt lower-priority Pods on a node to make room for it",
      "Evict any Pod on the node, regardless of its priority"
    ],
    answer: [2],
    explanation: "With priority and preemption, the scheduler can evict lower-priority Pods from a node so the pending higher-priority Pod fits. It never evicts Pods of equal or higher priority for this purpose. Adding nodes is the job of a separate autoscaler.",
    choiceRationale: [
      "The scheduler cannot create nodes; that is the Cluster Autoscaler's role.",
      "The scheduler always respects resource requests when placing Pods.",
      "Correct: preemption removes lower-priority Pods to make room.",
      "Preemption only targets Pods with lower priority than the pending Pod."
    ],
    references: [R.priority],
    tags: ["priority", "preemption", "scheduler"]
  }
];

// ../../packages/content/src/questions/orchestration.ts
var R2 = {
  containers: { title: "Kubernetes docs: Containers", url: "https://kubernetes.io/docs/concepts/containers/" },
  images: { title: "Kubernetes docs: Images", url: "https://kubernetes.io/docs/concepts/containers/images/" },
  cri: { title: "Kubernetes docs: Container Runtime Interface (CRI)", url: "https://kubernetes.io/docs/concepts/architecture/cri/" },
  components: { title: "Kubernetes docs: Kubernetes Components", url: "https://kubernetes.io/docs/concepts/overview/components/" },
  dockershim: { title: "Kubernetes docs: Migrating from dockershim", url: "https://kubernetes.io/docs/tasks/administer-cluster/migrating-from-dockershim/" },
  cgroups: { title: "Kubernetes docs: About cgroup v2", url: "https://kubernetes.io/docs/concepts/architecture/cgroups/" },
  runtimeClass: { title: "Kubernetes docs: Runtime Class", url: "https://kubernetes.io/docs/concepts/containers/runtime-class/" },
  oci: { title: "Open Container Initiative", url: "https://opencontainers.org/" },
  glossary: { title: "CNCF Cloud Native Glossary", url: "https://glossary.cncf.io/" },
  podLifecycle: { title: "Kubernetes docs: Pod Lifecycle", url: "https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/" },
  networking: { title: "Kubernetes docs: Services, Load Balancing, and Networking", url: "https://kubernetes.io/docs/concepts/services-networking/" },
  clusterNetworking: { title: "Kubernetes docs: Cluster Networking", url: "https://kubernetes.io/docs/concepts/cluster-administration/networking/" },
  service: { title: "Kubernetes docs: Service", url: "https://kubernetes.io/docs/concepts/services-networking/service/" },
  dns: { title: "Kubernetes docs: DNS for Services and Pods", url: "https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/" },
  ingress: { title: "Kubernetes docs: Ingress", url: "https://kubernetes.io/docs/concepts/services-networking/ingress/" },
  ingressControllers: { title: "Kubernetes docs: Ingress Controllers", url: "https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/" },
  gateway: { title: "Gateway API", url: "https://gateway-api.sigs.k8s.io/" },
  netpol: { title: "Kubernetes docs: Network Policies", url: "https://kubernetes.io/docs/concepts/services-networking/network-policies/" },
  rbac: { title: "Kubernetes docs: Using RBAC Authorization", url: "https://kubernetes.io/docs/reference/access-authn-authz/rbac/" },
  rbacGood: { title: "Kubernetes docs: Role Based Access Control Good Practices", url: "https://kubernetes.io/docs/concepts/security/rbac-good-practices/" },
  authn: { title: "Kubernetes docs: Authenticating", url: "https://kubernetes.io/docs/reference/access-authn-authz/authentication/" },
  serviceAccounts: { title: "Kubernetes docs: Service Accounts", url: "https://kubernetes.io/docs/concepts/security/service-accounts/" },
  pss: { title: "Kubernetes docs: Pod Security Standards", url: "https://kubernetes.io/docs/concepts/security/pod-security-standards/" },
  psa: { title: "Kubernetes docs: Pod Security Admission", url: "https://kubernetes.io/docs/concepts/security/pod-security-admission/" },
  securityContext: { title: "Kubernetes docs: Configure a Security Context for a Pod or Container", url: "https://kubernetes.io/docs/tasks/configure-pod-container/security-context/" },
  secret: { title: "Kubernetes docs: Secrets", url: "https://kubernetes.io/docs/concepts/configuration/secret/" },
  secretsGood: { title: "Kubernetes docs: Good practices for Kubernetes Secrets", url: "https://kubernetes.io/docs/concepts/security/secrets-good-practices/" },
  encryptAtRest: { title: "Kubernetes docs: Encrypting Confidential Data at Rest", url: "https://kubernetes.io/docs/tasks/administer-cluster/encrypt-data/" },
  debugPods: { title: "Kubernetes docs: Debug Pods", url: "https://kubernetes.io/docs/tasks/debug/debug-application/debug-pods/" },
  debug: { title: "Kubernetes docs: Monitoring, Logging, and Debugging", url: "https://kubernetes.io/docs/tasks/debug/" },
  kubectl: { title: "Kubernetes docs: kubectl reference", url: "https://kubernetes.io/docs/reference/kubectl/" },
  resources: { title: "Kubernetes docs: Resource Management for Pods and Containers", url: "https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/" },
  taints: { title: "Kubernetes docs: Taints and Tolerations", url: "https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/" },
  probes: { title: "Kubernetes docs: Configure Liveness, Readiness and Startup Probes", url: "https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/" },
  volumes: { title: "Kubernetes docs: Volumes", url: "https://kubernetes.io/docs/concepts/storage/volumes/" },
  pv: { title: "Kubernetes docs: Persistent Volumes", url: "https://kubernetes.io/docs/concepts/storage/persistent-volumes/" },
  storageClasses: { title: "Kubernetes docs: Storage Classes", url: "https://kubernetes.io/docs/concepts/storage/storage-classes/" },
  dynamicProvisioning: { title: "Kubernetes docs: Dynamic Volume Provisioning", url: "https://kubernetes.io/docs/concepts/storage/dynamic-provisioning/" }
};
var questionsOrchestration = [
  // ───────────────────────── kf-containerization (fundamentals) ─────────────────────────
  {
    id: "q-kf-containerization-001",
    domain: "fundamentals",
    objective: "kf-containerization",
    lessonId: "linux-essentials",
    difficulty: 1,
    type: "single",
    prompt: "Which Linux kernel feature does a container runtime use to cap how much CPU and memory a container may consume?",
    choices: ["Control groups (cgroups)", "Namespaces", "chroot", "seccomp profiles"],
    answer: [0],
    explanation: "Control groups (cgroups) account for and limit resources such as CPU, memory and process counts. Namespaces control what a process can **see**, while cgroups control how much it can **use**. Kubernetes resource requests and limits are ultimately enforced through cgroups on the node.",
    choiceRationale: [
      "Correct: cgroups are the kernel mechanism that meters and limits CPU, memory and other resources.",
      "Namespaces isolate what a process can see (PIDs, mounts, network), not how much CPU or memory it may use.",
      "chroot only changes the apparent root directory of a process and has no resource accounting.",
      "seccomp filters which system calls a process may make; it does not limit CPU or memory."
    ],
    references: [R2.cgroups, R2.containers],
    tags: ["cgroups", "linux", "resource-limits"]
  },
  {
    id: "q-kf-containerization-002",
    domain: "fundamentals",
    objective: "kf-containerization",
    lessonId: "linux-essentials",
    difficulty: 2,
    type: "single",
    prompt: "Inside a running container, `ps aux` lists only the container's own processes, and the application shows up as PID 1. Which kernel feature produces this view?",
    choices: [
      "Linux capabilities being dropped by the runtime",
      "The pids cgroup controller assigned to the container",
      "A PID namespace created for the container",
      "The overlay filesystem mounted as the container root"
    ],
    answer: [2],
    explanation: "A PID namespace gives a group of processes its own process-ID numbering, so the first process inside it is PID 1 and processes outside are invisible. The pids cgroup controller only limits how many processes can exist; it does not hide anything. Namespaces are about visibility, cgroups about consumption.",
    choiceRationale: [
      "Dropping capabilities restricts privileged operations but does not change which processes are visible.",
      "The pids cgroup caps the number of processes; it does not renumber or hide them.",
      "Correct: a PID namespace isolates the process tree and restarts numbering at 1.",
      "The overlay filesystem shapes the file view, not the process list."
    ],
    references: [R2.glossary, R2.containers],
    tags: ["namespaces", "linux", "isolation"]
  },
  {
    id: "q-kf-containerization-003",
    domain: "fundamentals",
    objective: "kf-containerization",
    lessonId: "linux-essentials",
    difficulty: 2,
    type: "single",
    prompt: "You delete a Pod whose spec does not set `terminationGracePeriodSeconds`. What does the main process in its container receive?",
    choices: [
      "SIGHUP, followed by SIGTERM if the process is still running",
      "SIGKILL immediately, because containers are disposable",
      "SIGINT, followed by SIGQUIT after 10 seconds",
      "SIGTERM, followed by SIGKILL once the 30-second grace period expires"
    ],
    answer: [3],
    explanation: "Kubernetes asks the runtime to send SIGTERM so the application can shut down cleanly (finish requests, flush data). If the process is still running when the grace period ends (30 seconds by default), it is sent SIGKILL. Applications that ignore SIGTERM therefore always take the full grace period to stop.",
    choiceRationale: [
      "SIGHUP is conventionally a reload signal and is not part of Pod termination.",
      "SIGKILL is only the fallback after the grace period, not the first signal.",
      "Neither SIGINT nor SIGQUIT is used, and the default grace period is 30 seconds, not 10.",
      "Correct: graceful SIGTERM first, then SIGKILL after the default 30-second grace period."
    ],
    references: [R2.podLifecycle],
    tags: ["signals", "pod-termination", "linux"]
  },
  {
    id: "q-kf-containerization-004",
    domain: "fundamentals",
    objective: "kf-containerization",
    lessonId: "virtualization-and-containers",
    difficulty: 1,
    type: "single",
    prompt: "What is the most fundamental architectural difference between containers and virtual machines?",
    choices: [
      "Containers share the host kernel, while each VM runs its own guest kernel",
      "Containers need a hypervisor such as KVM, while VMs run directly on the kernel",
      "Containers always provide stronger isolation than VMs",
      "Containers bundle a full guest OS, which is why they start faster"
    ],
    answer: [0],
    explanation: "Containers are isolated processes on a shared host kernel, using namespaces and cgroups. A VM virtualizes hardware through a hypervisor and boots its own kernel. That is why containers start quickly and are lightweight, and also why their isolation boundary is weaker than a VM's.",
    choiceRationale: [
      "Correct: the shared kernel is the defining difference.",
      "This is reversed: VMs rely on a hypervisor, containers do not.",
      "VMs generally offer stronger isolation because they do not share a kernel.",
      "Containers do not ship a guest kernel; they start fast precisely because there is no OS to boot."
    ],
    references: [R2.glossary, R2.containers],
    tags: ["containers", "virtual-machines", "isolation"]
  },
  {
    id: "q-kf-containerization-005",
    domain: "fundamentals",
    objective: "kf-containerization",
    lessonId: "virtualization-and-containers",
    difficulty: 2,
    type: "single",
    prompt: "Why can a Linux container image not run natively on a Windows kernel without some form of Linux VM underneath?",
    choices: [
      "The OCI image format can only be unpacked on Linux file systems",
      "Container processes make system calls directly to the host kernel, so they need a compatible kernel",
      "Windows has no client that can pull images from an OCI registry",
      "Linux images are compressed with an algorithm that Windows cannot decompress"
    ],
    answer: [1],
    explanation: "A container is just a process on the host, so its binaries call the host kernel directly. Linux binaries expect Linux system calls; a Windows kernel does not provide them. Tools that run Linux containers on Windows or macOS do so inside a lightweight Linux VM.",
    choiceRationale: [
      "OCI images are tar archives plus JSON metadata and are not tied to a host file system.",
      "Correct: no guest kernel exists, so the host kernel must match the binaries.",
      "Registry clients exist on every major OS; pulling is not the problem.",
      "Image layers use standard compression such as gzip, which any OS can decompress."
    ],
    references: [R2.containers, R2.oci],
    tags: ["containers", "kernel", "portability"]
  },
  {
    id: "q-kf-containerization-006",
    domain: "fundamentals",
    objective: "kf-containerization",
    lessonId: "virtualization-and-containers",
    difficulty: 3,
    type: "multi",
    prompt: "Which statements about container isolation are accurate? (Select TWO.)",
    choices: [
      "A kernel vulnerability can potentially affect every container on the same host",
      "Each container runs its own separate kernel instance",
      "Sandboxed runtimes such as gVisor or Kata Containers add an extra isolation layer between workloads and the host kernel",
      "A container can never be granted more privileges than an ordinary host process",
      "Namespaces protect a container from noisy neighbors exhausting CPU and memory"
    ],
    answer: [0, 2],
    explanation: "Because all containers on a node share one kernel, a kernel exploit can break out of the namespace boundary. Sandboxed runtimes, selectable in Kubernetes via RuntimeClass, add a user-space kernel (gVisor) or a lightweight VM (Kata) to strengthen that boundary. Resource fairness comes from cgroups, not namespaces.",
    choiceRationale: [
      "Correct: the shared kernel is a common attack surface for all containers on the host.",
      "Containers do not have their own kernel; that is what distinguishes them from VMs.",
      "Correct: gVisor and Kata Containers exist precisely to harden this boundary.",
      "Privileged containers and added capabilities can grant near-host-level power.",
      "Resource limits come from cgroups; namespaces only isolate visibility."
    ],
    references: [R2.runtimeClass, R2.glossary],
    tags: ["isolation", "security", "runtimeclass"]
  },
  {
    id: "q-kf-containerization-007",
    domain: "fundamentals",
    objective: "kf-containerization",
    lessonId: "container-images-and-oci",
    difficulty: 1,
    type: "single",
    prompt: "In a reference such as `nginx@sha256:4c0f...`, what does the digest after the `@` represent?",
    choices: [
      "A mutable label such as v1.2 that can be re-pointed to a newer image",
      "The total compressed size of the image layers",
      "A cryptographic signature proving who built the image",
      "A content-addressable hash that identifies the exact image content"
    ],
    answer: [3],
    explanation: "A digest is a hash of the image manifest, so it always resolves to exactly the same content. Tags are human-friendly pointers that can be moved to different images over time. Pinning by digest gives reproducible deployments; signatures are a separate concern handled by tools such as Sigstore.",
    choiceRationale: [
      "That describes a tag, which is mutable; a digest is immutable.",
      "Size is recorded in the manifest, but the digest is not a size.",
      "A digest proves integrity of the content, not the identity of the builder.",
      "Correct: the digest is a content hash, so the same digest always means the same image."
    ],
    references: [R2.images, R2.oci],
    tags: ["images", "digests", "oci"]
  },
  {
    id: "q-kf-containerization-008",
    domain: "fundamentals",
    objective: "kf-containerization",
    lessonId: "container-images-and-oci",
    difficulty: 2,
    type: "single",
    prompt: `A Dockerfile is ordered like this:

\`\`\`text
FROM node:20-slim
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
CMD ["node", "server.js"]
\`\`\`

Why copy the dependency files and run \`npm ci\` before copying the rest of the source?`,
    choices: [
      "So that source-code edits do not invalidate the cached dependency-install layer",
      "Because COPY instructions must always precede RUN instructions",
      "Because it makes the final image contain fewer files",
      "Because the OCI image spec requires dependencies in the lowest layer"
    ],
    answer: [0],
    explanation: "Each instruction creates a layer, and a build cache entry is reused only if that instruction and everything before it are unchanged. Dependency manifests change rarely, so `npm ci` stays cached while frequent source edits only rebuild the final `COPY . .` layer. The resulting image has the same files either way; the gain is build speed.",
    choiceRationale: [
      "Correct: ordering from least to most frequently changed maximizes cache reuse.",
      "Dockerfiles have no such rule; RUN and COPY may appear in any order.",
      "Both orderings end up with the same files in the image.",
      "The OCI image spec does not dictate what content goes in which layer."
    ],
    references: [R2.images, R2.oci],
    tags: ["dockerfile", "layers", "build-cache"]
  },
  {
    id: "q-kf-containerization-009",
    domain: "fundamentals",
    objective: "kf-containerization",
    lessonId: "container-images-and-oci",
    difficulty: 1,
    type: "single",
    prompt: "Which three specifications does the Open Container Initiative (OCI) maintain?",
    choices: [
      "Build, Ship, and Run specifications",
      "Container Runtime, Network, and Storage interfaces",
      "Runtime, Image, and Distribution specifications",
      "Image, Scheduling, and Registry specifications"
    ],
    answer: [2],
    explanation: "The OCI Runtime Spec defines how to run an unpacked container bundle, the Image Spec defines the image format, and the Distribution Spec defines the registry API for pushing and pulling. These standards let images built by one tool run on any compliant runtime. CRI, CNI and CSI are Kubernetes interfaces, not OCI specs.",
    choiceRationale: [
      '"Build, ship, run" is a marketing slogan, not a set of OCI specs.',
      "CRI, CNI and CSI are Kubernetes plugin interfaces, not OCI specifications.",
      "Correct: Runtime, Image and Distribution are the three OCI specs.",
      "Scheduling is an orchestrator concern and is not standardized by OCI."
    ],
    references: [R2.oci],
    tags: ["oci", "standards", "images"]
  },
  {
    id: "q-kf-containerization-010",
    domain: "fundamentals",
    objective: "kf-containerization",
    lessonId: "container-images-and-oci",
    difficulty: 2,
    type: "single",
    prompt: "A container uses `image: registry.example.com/shop/api:latest` and does not set `imagePullPolicy`. Which pull policy does Kubernetes apply?",
    choices: ["Always", "IfNotPresent", "Never", "OnFailure"],
    answer: [0],
    explanation: "When the tag is `:latest` or no tag is given, Kubernetes defaults `imagePullPolicy` to `Always`. For any other tag the default is `IfNotPresent`. Because `latest` is mutable, pinning a specific tag or digest is the recommended practice for production.",
    choiceRationale: [
      "Correct: a latest (or missing) tag defaults to Always.",
      "IfNotPresent is the default only for tags other than latest.",
      "Never is only used when explicitly set and requires the image to be pre-loaded on the node.",
      "OnFailure is a Pod restartPolicy value, not an image pull policy."
    ],
    references: [R2.images],
    tags: ["images", "imagepullpolicy", "tags"]
  },
  {
    id: "q-kf-containerization-011",
    domain: "fundamentals",
    objective: "kf-containerization",
    lessonId: "container-images-and-oci",
    difficulty: 3,
    type: "single",
    prompt: "An application writes `/var/cache/report.tmp` inside its container (no volume mounted there). The container then crashes and the kubelet restarts it in the same Pod. What happens to the file?",
    choices: [
      "It survives, because writes go into the image's top read-only layer",
      "It is pushed to the registry as a new layer on the next pull",
      "It survives until the node reboots, because overlay data lives in RAM",
      "It is gone, because the new container starts with a fresh writable layer"
    ],
    answer: [3],
    explanation: "Image layers are read-only; each container gets its own thin writable layer on top. When the kubelet restarts a crashed container, it creates a new container from the image with a new, empty writable layer. Data that must survive restarts belongs in a volume such as emptyDir or a PersistentVolume.",
    choiceRationale: [
      "Image layers are read-only; writes go to a per-container writable layer.",
      "Nothing running in a container is automatically pushed to a registry.",
      "The writable layer is normally on disk, and it is discarded with the old container regardless.",
      "Correct: the restarted container gets a fresh writable layer, so the file is lost."
    ],
    references: [R2.images, R2.volumes],
    tags: ["layers", "ephemeral-storage", "images"]
  },
  {
    id: "q-kf-containerization-012",
    domain: "fundamentals",
    objective: "kf-containerization",
    lessonId: "node-components",
    difficulty: 1,
    type: "single",
    prompt: "What is the Container Runtime Interface (CRI)?",
    choices: [
      "The plugin API the kubelet uses to talk to container runtimes such as containerd and CRI-O",
      "The plugin API that assigns IP addresses to Pods",
      "The protocol registries use to serve OCI images",
      "The plugin API used to attach and mount storage volumes"
    ],
    answer: [0],
    explanation: "CRI is a gRPC API between the kubelet and the container runtime. It lets Kubernetes work with any compliant runtime without runtime-specific code in the kubelet. Networking is handled by CNI and storage by CSI.",
    choiceRationale: [
      "Correct: CRI decouples the kubelet from specific runtimes.",
      "That is the Container Network Interface (CNI).",
      "That is the OCI Distribution Specification.",
      "That is the Container Storage Interface (CSI)."
    ],
    references: [R2.cri, R2.components],
    tags: ["cri", "kubelet", "runtimes"]
  },
  {
    id: "q-kf-containerization-013",
    domain: "fundamentals",
    objective: "kf-containerization",
    lessonId: "node-components",
    difficulty: 2,
    type: "single",
    prompt: "Which statement accurately describes container runtimes after dockershim was removed in Kubernetes 1.24?",
    choices: [
      "Images produced by `docker build` must be rebuilt before Kubernetes can run them",
      "The kubelet now starts container processes itself without any runtime",
      "Nodes use a CRI-compatible runtime such as containerd or CRI-O, and Docker-built images still run",
      "Docker Engine is still built into the kubelet but disabled by default"
    ],
    answer: [2],
    explanation: "Dockershim was the in-tree adapter that let the kubelet drive Docker Engine; it was removed in 1.24. Nodes now use a runtime that implements CRI directly, typically containerd or CRI-O. Images built with Docker are standard OCI images, so they run unchanged.",
    choiceRationale: [
      "Docker builds OCI-compatible images, which containerd and CRI-O run without changes.",
      "The kubelet always delegates to a container runtime through CRI.",
      "Correct: a CRI runtime is required, and existing images keep working.",
      "The dockershim code was removed from the kubelet entirely, not merely disabled."
    ],
    references: [R2.dockershim, R2.cri],
    tags: ["dockershim", "containerd", "cri-o"]
  },
  {
    id: "q-kf-containerization-014",
    domain: "fundamentals",
    objective: "kf-containerization",
    lessonId: "node-components",
    difficulty: 2,
    type: "multi",
    prompt: "Which of these implement the CRI and can be used directly by the kubelet as the node's container runtime? (Select TWO.)",
    choices: ["containerd", "runc", "CRI-O", "kube-proxy", "Podman"],
    answer: [0, 2],
    explanation: "containerd and CRI-O are high-level runtimes that implement the CRI gRPC API. They in turn call a low-level OCI runtime such as runc to actually create the container processes. kube-proxy handles Service networking, and Podman is a standalone container tool rather than a CRI endpoint.",
    choiceRationale: [
      "Correct: containerd ships a CRI plugin and is the most common runtime.",
      "runc is a low-level OCI runtime invoked by containerd or CRI-O, not a CRI server.",
      "Correct: CRI-O was built specifically to implement CRI for Kubernetes.",
      "kube-proxy programs Service networking rules and does not run containers.",
      "Podman is a daemonless container CLI and does not serve the CRI API to the kubelet."
    ],
    references: [R2.cri, R2.components],
    tags: ["cri", "containerd", "cri-o"]
  },
  // ───────────────────────── co-networking ─────────────────────────
  {
    id: "q-co-networking-001",
    domain: "orchestration",
    objective: "co-networking",
    lessonId: "networking-fundamentals",
    difficulty: 1,
    type: "single",
    prompt: "Which transport protocol and port do ordinary DNS queries typically use?",
    choices: ["TCP port 80", "UDP port 123", "TCP port 443", "UDP port 53"],
    answer: [3],
    explanation: "Standard DNS queries go over UDP port 53, falling back to TCP port 53 for large responses and zone transfers. In Kubernetes, the cluster DNS Service (CoreDNS) listens on port 53 for both protocols. Port 123 is NTP, and 80/443 are HTTP/HTTPS.",
    choiceRationale: [
      "TCP 80 is plain HTTP.",
      "UDP 123 is NTP, used for time synchronization.",
      "TCP 443 is HTTPS.",
      "Correct: DNS uses port 53, primarily over UDP."
    ],
    references: [R2.dns],
    tags: ["dns", "ports", "networking-basics"]
  },
  {
    id: "q-co-networking-002",
    domain: "orchestration",
    objective: "co-networking",
    lessonId: "networking-fundamentals",
    difficulty: 2,
    type: "single",
    prompt: "A Pod with IP `10.244.2.15` calls a public API. The API's access log shows the request arriving from the node's address, not the Pod IP. Which technique most likely explains this?",
    choices: [
      "Source NAT (masquerading) rewrote the source address to the node's IP",
      "The cluster DNS server rewrote the destination hostname",
      "A Layer 7 proxy terminated TLS and re-encrypted the request",
      "ARP replaced the Pod's MAC address with the default gateway's"
    ],
    answer: [0],
    explanation: "Pod IPs usually come from a private range that is not routable on the internet. For egress, the CNI plugin or node commonly applies source NAT (masquerade), so replies return to the node and are translated back to the Pod. Inside the cluster, by contrast, Pods talk to each other without NAT.",
    choiceRationale: [
      "Correct: SNAT/masquerading replaces the private source IP with the node's IP.",
      "DNS resolves names; it does not alter packet source addresses.",
      "No L7 proxy is implied, and TLS termination would not explain a node source IP by itself.",
      "ARP works on the local link and does not change the IP address seen by a remote server."
    ],
    references: [R2.clusterNetworking],
    tags: ["nat", "egress", "networking-basics"]
  },
  {
    id: "q-co-networking-003",
    domain: "orchestration",
    objective: "co-networking",
    lessonId: "pod-networking-and-cni",
    difficulty: 1,
    type: "single",
    prompt: "Which statement reflects the Kubernetes network model?",
    choices: [
      "Pods on different nodes must use NodePort Services to reach each other",
      "Every Pod gets its own IP address and can reach every other Pod without NAT",
      "Each container in a Pod receives a different IP address",
      "Pod IPs are allocated by kube-proxy from the Service CIDR"
    ],
    answer: [1],
    explanation: "Kubernetes requires a flat network: each Pod has a unique cluster-wide IP and can talk to any other Pod directly, across nodes, without NAT. Containers in the same Pod share that IP and reach each other on localhost. A CNI plugin implements this model and assigns Pod IPs.",
    choiceRationale: [
      "Pods reach each other directly by Pod IP; Services are for stable access, not a requirement.",
      "Correct: one IP per Pod and NAT-free Pod-to-Pod communication.",
      "Containers in one Pod share a network namespace and therefore one IP.",
      "Pod IPs come from the CNI plugin's Pod CIDR; kube-proxy handles Service IPs."
    ],
    references: [R2.clusterNetworking, R2.networking],
    tags: ["network-model", "pods", "cni"]
  },
  {
    id: "q-co-networking-004",
    domain: "orchestration",
    objective: "co-networking",
    lessonId: "pod-networking-and-cni",
    difficulty: 2,
    type: "single",
    prompt: `A freshly bootstrapped cluster shows this:

\`\`\`text
$ kubectl get nodes
NAME       STATUS     ROLES           AGE   VERSION
cp-1       NotReady   control-plane   6m    v1.31.2
worker-1   NotReady   <none>          4m    v1.31.2

$ kubectl describe node worker-1 | grep -i network
  Ready  False  ...  KubeletNotReady  container runtime network not ready: NetworkReady=false reason:NetworkPluginNotReady message:Network plugin returns error: cni plugin not initialized
\`\`\`

What is the most likely cause?`,
    choices: [
      "No Ingress controller has been deployed yet",
      "kube-proxy is running in IPVS mode instead of iptables mode",
      "No CNI plugin (for example Calico, Cilium, or Flannel) has been installed",
      "The cluster has no Service of type LoadBalancer"
    ],
    answer: [2],
    explanation: "Kubernetes does not ship a Pod network implementation; a CNI plugin must be installed after bootstrapping. Until one is present, the kubelet reports the network as not ready and nodes stay NotReady. Installing a CNI plugin such as Calico, Cilium or Flannel resolves it.",
    choiceRationale: [
      "Ingress controllers handle HTTP routing and do not affect node readiness.",
      "The kube-proxy mode affects Service routing, not whether the Pod network is initialized.",
      "Correct: the message explicitly says the CNI plugin is not initialized.",
      "LoadBalancer Services are optional and unrelated to node readiness."
    ],
    references: [R2.clusterNetworking],
    tags: ["cni", "troubleshooting", "node-notready"]
  },
  {
    id: "q-co-networking-005",
    domain: "orchestration",
    objective: "co-networking",
    lessonId: "services",
    difficulty: 1,
    type: "single",
    prompt: "If a Service manifest omits `spec.type`, which type does Kubernetes create?",
    choices: ["NodePort", "LoadBalancer", "ClusterIP", "ExternalName"],
    answer: [2],
    explanation: "ClusterIP is the default Service type. It gives the Service a stable virtual IP reachable only from inside the cluster. NodePort, LoadBalancer and ExternalName must be requested explicitly.",
    choiceRationale: [
      "NodePort must be set explicitly; it builds on top of a ClusterIP.",
      "LoadBalancer must be set explicitly and needs a cloud or bare-metal load balancer implementation.",
      "Correct: ClusterIP is the default.",
      "ExternalName must be set explicitly and maps the Service to a DNS name."
    ],
    references: [R2.service],
    tags: ["services", "clusterip", "defaults"]
  },
  {
    id: "q-co-networking-006",
    domain: "orchestration",
    objective: "co-networking",
    lessonId: "services",
    difficulty: 2,
    type: "single",
    prompt: `Requests to the \`web\` Service time out. You collect:

\`\`\`text
$ kubectl describe svc web
Name:              web
Namespace:         shop
Selector:          app=web
Type:              ClusterIP
IP:                10.96.41.7
Port:              http  80/TCP
TargetPort:        8080/TCP
Endpoints:         <none>

$ kubectl get pods -n shop --show-labels
NAME                   READY   STATUS    RESTARTS   AGE   LABELS
web-5d8f7c9b6-k2m4x    1/1     Running   0          20m   app=web-frontend,pod-template-hash=5d8f7c9b6
web-5d8f7c9b6-p9t7q    1/1     Running   0          20m   app=web-frontend,pod-template-hash=5d8f7c9b6
\`\`\`

What is the cause?`,
    choices: [
      "kube-proxy must be restarted after a Service is created",
      "ClusterIP Services only get endpoints once an Ingress points at them",
      "The targetPort must equal the Service port for endpoints to appear",
      "The Service selector does not match the labels on the Pods"
    ],
    answer: [3],
    explanation: "A Service only gets endpoints for ready Pods whose labels match its selector. Here the selector is `app=web` but the Pods carry `app=web-frontend`, so the EndpointSlice is empty. Fixing either the selector or the Pod template labels makes the endpoints appear.",
    choiceRationale: [
      "kube-proxy watches the API continuously; no restart is needed.",
      "Endpoints are populated from the selector, independent of any Ingress.",
      "port and targetPort may differ; that is the point of having both fields.",
      "Correct: `app=web` does not match `app=web-frontend`, so there are no endpoints."
    ],
    references: [R2.service, R2.debug],
    tags: ["services", "selectors", "troubleshooting"]
  },
  {
    id: "q-co-networking-007",
    domain: "orchestration",
    objective: "co-networking",
    lessonId: "services",
    difficulty: 2,
    type: "single",
    prompt: "A StatefulSet uses a Service with `clusterIP: None`. What does a DNS lookup of that Service name return from inside the cluster?",
    choices: [
      "A single virtual IP that kube-proxy load-balances",
      "The IP addresses of the ready Pods selected by the Service",
      "The IP addresses of the nodes where the Pods run",
      "A CNAME pointing to an external load balancer"
    ],
    answer: [1],
    explanation: "Setting `clusterIP: None` creates a headless Service: no virtual IP is allocated and kube-proxy does not handle it. Cluster DNS instead returns A/AAAA records for the selected ready Pods. StatefulSets rely on this to give each Pod a stable DNS name.",
    choiceRationale: [
      "A headless Service has no virtual IP by definition.",
      "Correct: DNS returns the individual Pod IPs.",
      "Node IPs are only relevant for NodePort access, not headless DNS.",
      "CNAME records are returned for ExternalName Services, not headless ones."
    ],
    references: [R2.service, R2.dns],
    tags: ["services", "headless", "dns"]
  },
  {
    id: "q-co-networking-008",
    domain: "orchestration",
    objective: "co-networking",
    lessonId: "services",
    difficulty: 3,
    type: "multi",
    prompt: "Which statements about kube-proxy are accurate? (Select TWO.)",
    choices: [
      "It programs packet-forwarding rules on each node (for example iptables, IPVS, or nftables) so Service IPs reach backend Pods",
      "It assigns IP addresses to Pods when they start",
      "It watches Services and EndpointSlices through the API server",
      "It answers DNS queries that resolve Service names to IPs",
      "It runs only on control-plane nodes"
    ],
    answer: [0, 2],
    explanation: "kube-proxy runs on every node (typically as a DaemonSet), watches Services and EndpointSlices, and translates them into local forwarding rules. Pod IP assignment is the CNI plugin's job, and name resolution is handled by CoreDNS. Some CNI plugins can replace kube-proxy entirely, but its role stays the same conceptually.",
    choiceRationale: [
      "Correct: kube-proxy implements Service virtual IPs via node-level rules.",
      "Pod IPs are assigned by the CNI plugin.",
      "Correct: it reacts to Service and EndpointSlice changes from the API server.",
      "DNS is served by CoreDNS, not kube-proxy.",
      "kube-proxy runs on every node that hosts Pods, not just the control plane."
    ],
    references: [R2.service, R2.components],
    tags: ["kube-proxy", "services", "endpointslices"]
  },
  {
    id: "q-co-networking-009",
    domain: "orchestration",
    objective: "co-networking",
    lessonId: "dns-and-coredns",
    difficulty: 1,
    type: "single",
    prompt: "With the default cluster domain, what is the fully qualified DNS name of a Service named `orders` in namespace `shop`?",
    choices: [
      "shop.orders.svc.cluster.local",
      "orders.svc.shop.cluster.local",
      "orders.shop.svc.cluster.local",
      "orders.shop.pod.cluster.local"
    ],
    answer: [2],
    explanation: "Service DNS names follow `<service>.<namespace>.svc.<cluster-domain>`, and the default cluster domain is `cluster.local`. CoreDNS serves these records automatically. Shorter forms such as `orders` or `orders.shop` work thanks to the Pod's DNS search list.",
    choiceRationale: [
      "The Service name comes first and the namespace second, not the reverse.",
      "The `svc` label follows the namespace, not the Service name.",
      "Correct: service, namespace, `svc`, then the cluster domain.",
      "The `pod` subdomain is used for Pod records, not Service records."
    ],
    references: [R2.dns],
    tags: ["dns", "coredns", "services"]
  },
  {
    id: "q-co-networking-010",
    domain: "orchestration",
    objective: "co-networking",
    lessonId: "dns-and-coredns",
    difficulty: 2,
    type: "single",
    prompt: "A Pod in namespace `billing` fails to reach `http://orders`, but `http://orders.shop` works. The `orders` Service lives in namespace `shop`. Why?",
    choices: [
      "CoreDNS is not running in the billing namespace",
      "A short name is resolved using the Pod's own namespace first, so `orders` is looked up in billing",
      "Services can only be reached from Pods in the same namespace",
      "The orders Service must be type NodePort to be reachable from other namespaces"
    ],
    answer: [1],
    explanation: "A Pod's `/etc/resolv.conf` contains search domains starting with `<its-namespace>.svc.cluster.local`. The bare name `orders` therefore expands to `orders.billing.svc.cluster.local`, which does not exist. Adding the namespace (`orders.shop`) or using the full name resolves the right Service.",
    choiceRationale: [
      "CoreDNS runs once for the cluster (in kube-system) and serves every namespace.",
      "Correct: the DNS search path prefers the client Pod's own namespace.",
      "Cross-namespace Service access works by default unless a NetworkPolicy blocks it.",
      "ClusterIP Services are reachable from any namespace; NodePort is about external access."
    ],
    references: [R2.dns],
    tags: ["dns", "namespaces", "troubleshooting"]
  },
  {
    id: "q-co-networking-011",
    domain: "orchestration",
    objective: "co-networking",
    lessonId: "ingress-and-gateway-api",
    difficulty: 2,
    type: "single",
    prompt: `You applied an Ingress twelve minutes ago, but no traffic reaches the backend:

\`\`\`text
$ kubectl get ingress -n shop
NAME   CLASS    HOSTS              ADDRESS   PORTS   AGE
shop   <none>   shop.example.com             80      12m
\`\`\`

What is the most likely reason?`,
    choices: [
      "Ingress objects only route to NodePort Services",
      "The Ingress must be created in the kube-system namespace",
      "Ingress requires a NetworkPolicy allowing port 80 first",
      "No Ingress controller is running to implement the Ingress"
    ],
    answer: [3],
    explanation: "An Ingress is only a set of routing rules; an Ingress controller (for example ingress-nginx, Traefik, or a cloud controller) must watch it and configure a proxy. Without a controller, nothing populates the ADDRESS column and no traffic is routed. Kubernetes does not ship a controller by default.",
    choiceRationale: [
      "Ingress backends are commonly ClusterIP Services.",
      "Ingresses live in the same namespace as the Services they route to.",
      "Without NetworkPolicies, all traffic is already allowed.",
      "Correct: the empty ADDRESS and no CLASS point to a missing controller."
    ],
    references: [R2.ingress, R2.ingressControllers],
    tags: ["ingress", "ingress-controller", "troubleshooting"]
  },
  {
    id: "q-co-networking-012",
    domain: "orchestration",
    objective: "co-networking",
    lessonId: "ingress-and-gateway-api",
    difficulty: 3,
    type: "single",
    prompt: "In the Gateway API role model, which resource does a cluster operator create to define listeners (ports, protocols, TLS) that application teams then attach their HTTPRoutes to?",
    choices: ["GatewayClass", "Gateway", "HTTPRoute", "IngressClass"],
    answer: [1],
    explanation: "Gateway API splits responsibilities: the infrastructure provider defines a GatewayClass, the cluster operator creates a Gateway with listeners, and application developers create Routes such as HTTPRoute that attach to that Gateway. This role separation is a key improvement over the single Ingress object.",
    choiceRationale: [
      "GatewayClass names the controller implementation; it does not define listeners.",
      "Correct: the Gateway declares listeners that Routes attach to.",
      "HTTPRoute holds the app team's routing rules and attaches to a Gateway.",
      "IngressClass belongs to the Ingress API, not Gateway API."
    ],
    references: [R2.gateway],
    tags: ["gateway-api", "httproute", "roles"]
  },
  {
    id: "q-co-networking-013",
    domain: "orchestration",
    objective: "co-networking",
    lessonId: "network-policies",
    difficulty: 1,
    type: "single",
    prompt: "If no NetworkPolicy selects a Pod, what traffic is that Pod allowed to send and receive?",
    choices: [
      "All ingress and egress traffic is allowed",
      "All traffic is denied until a policy explicitly allows it",
      "Only traffic from Pods in the same namespace is allowed",
      "Only egress traffic is allowed; ingress is denied"
    ],
    answer: [0],
    explanation: 'Pods are non-isolated by default: everything is allowed in both directions. A Pod becomes isolated for ingress or egress only when a NetworkPolicy selects it for that direction. That is why a "default deny" policy is a common first step.',
    choiceRationale: [
      "Correct: with no selecting policy, Pods accept and send all traffic.",
      "Default deny only applies after you create such a policy.",
      "There is no implicit namespace boundary for network traffic.",
      "Neither direction is restricted by default."
    ],
    references: [R2.netpol],
    tags: ["network-policies", "defaults", "isolation"]
  },
  {
    id: "q-co-networking-014",
    domain: "orchestration",
    objective: "co-networking",
    lessonId: "network-policies",
    difficulty: 3,
    type: "single",
    prompt: `A cluster uses a CNI plugin that enforces NetworkPolicy. You apply:

\`\`\`yaml
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: lockdown
  namespace: payments
spec:
  podSelector: {}
  policyTypes:
  - Ingress
\`\`\`

What is the effect?`,
    choices: [
      "All traffic into and out of every Pod in payments is denied",
      "Nothing changes, because the policy contains no ingress rules",
      "All incoming traffic to every Pod in payments is denied; outgoing traffic is unaffected",
      "Only Pods without any labels in payments are isolated"
    ],
    answer: [2],
    explanation: "An empty `podSelector` selects every Pod in the namespace, and listing `Ingress` in `policyTypes` with no ingress rules means nothing is allowed in. Egress is not listed, so outbound traffic is unchanged. This is the standard default-deny-ingress pattern.",
    choiceRationale: [
      "Egress is only restricted if `Egress` appears in policyTypes.",
      "An isolating policy with no allow rules denies everything for that direction.",
      "Correct: default-deny ingress for all Pods in the namespace.",
      "`podSelector: {}` matches all Pods, labeled or not."
    ],
    references: [R2.netpol],
    tags: ["network-policies", "default-deny", "yaml"]
  },
  // ───────────────────────── co-security ─────────────────────────
  {
    id: "q-co-security-001",
    domain: "orchestration",
    objective: "co-security",
    lessonId: "authentication-authorization-rbac",
    difficulty: 1,
    type: "single",
    prompt: "What is the key difference between a Role and a ClusterRole?",
    choices: [
      "A Role is for human users, while a ClusterRole is for ServiceAccounts",
      "A Role grants permissions within one namespace; a ClusterRole is not namespaced and can cover cluster-scoped resources",
      "A ClusterRole can only be bound with a ClusterRoleBinding",
      "A Role can contain deny rules, while a ClusterRole cannot"
    ],
    answer: [1],
    explanation: "A Role lives in a namespace and grants access only there. A ClusterRole is cluster-wide and can grant access to cluster-scoped resources such as nodes, or be reused across namespaces. A ClusterRole can be bound with a RoleBinding to grant its permissions in a single namespace.",
    choiceRationale: [
      "Both kinds can be bound to users, groups or ServiceAccounts.",
      "Correct: scope is the difference.",
      "A RoleBinding may reference a ClusterRole to grant it within one namespace.",
      "RBAC has no deny rules at all; permissions are purely additive."
    ],
    references: [R2.rbac],
    tags: ["rbac", "role", "clusterrole"]
  },
  {
    id: "q-co-security-002",
    domain: "orchestration",
    objective: "co-security",
    lessonId: "authentication-authorization-rbac",
    difficulty: 2,
    type: "single",
    prompt: "A user can delete Secrets in namespace `prod` through a RoleBinding to the `edit` ClusterRole. Security asks you to block that one action while keeping their other permissions. How do you achieve this with RBAC?",
    choices: [
      "Add a second Role containing a `deny` verb for secrets",
      "Create a NetworkPolicy that blocks the user from the API server",
      "Set `automountServiceAccountToken: false` in the namespace",
      "Replace the binding with a narrower Role that omits delete on secrets, since RBAC permissions are only additive"
    ],
    answer: [3],
    explanation: "RBAC rules can only grant permissions; there is no deny. To remove a permission, you must remove or narrow the binding that grants it, for example by binding a custom Role that lists only the needed verbs. Least privilege therefore starts with granting little, not subtracting later.",
    choiceRationale: [
      "RBAC has no deny verb; such a rule would grant nothing and remove nothing.",
      "NetworkPolicies control Pod traffic, not user API requests.",
      "That setting affects token mounting in Pods, not a human user's permissions.",
      "Correct: because RBAC is additive, you must narrow what is granted."
    ],
    references: [R2.rbac, R2.rbacGood],
    tags: ["rbac", "least-privilege", "additive"]
  },
  {
    id: "q-co-security-003",
    domain: "orchestration",
    objective: "co-security",
    lessonId: "authentication-authorization-rbac",
    difficulty: 2,
    type: "single",
    prompt: `The ServiceAccount \`deployer\` in namespace \`ci\` has a RoleBinding (in \`ci\`) to a Role \`pod-reader\` that allows get and list on pods. Yet:

\`\`\`text
$ kubectl auth can-i list pods --as=system:serviceaccount:ci:deployer -n staging
no
\`\`\`

Why?`,
    choices: [
      "ServiceAccounts can never list Pods; only users can",
      "The `pod-reader` Role must use the verb `watch` instead of `list`",
      "A RoleBinding only grants access in its own namespace, so nothing grants access in staging",
      "The `--as` flag ignores RoleBindings and only checks ClusterRoleBindings"
    ],
    answer: [2],
    explanation: "Roles and RoleBindings are namespaced; a binding in `ci` grants permissions only in `ci`. To allow the account in `staging`, create a RoleBinding in `staging` (pointing to a Role there or to a ClusterRole). `kubectl auth can-i` with `--as` is a convenient way to verify this.",
    choiceRationale: [
      "ServiceAccounts can be granted any permission through bindings.",
      "list is the correct verb for listing; watch is a separate verb.",
      "Correct: the grant exists only in the ci namespace.",
      "Impersonation evaluates all bindings, namespaced and cluster-wide."
    ],
    references: [R2.rbac, R2.kubectl],
    tags: ["rbac", "serviceaccounts", "namespaces"]
  },
  {
    id: "q-co-security-004",
    domain: "orchestration",
    objective: "co-security",
    lessonId: "authentication-authorization-rbac",
    difficulty: 1,
    type: "single",
    prompt: "How does an application running in a Pod normally authenticate to the Kubernetes API server?",
    choices: [
      "With a ServiceAccount token that the kubelet projects into the Pod",
      "With the node's administrator kubeconfig copied into the container",
      "With a username and password stored in the container image",
      "With the kubelet's client certificate shared through the Pod network"
    ],
    answer: [0],
    explanation: "Every Pod runs as a ServiceAccount (`default` if none is set), and a short-lived token for it is mounted into the Pod. The API server authenticates the token and RBAC then authorizes what that ServiceAccount may do. Embedding credentials in images or reusing node credentials would break least privilege.",
    choiceRationale: [
      "Correct: Pods authenticate as their ServiceAccount via a projected token.",
      "Copying admin credentials into a container would be a serious security flaw.",
      "Credentials baked into images are insecure and not how Kubernetes works.",
      "The kubelet's credentials belong to the node identity and are not shared with Pods."
    ],
    references: [R2.serviceAccounts, R2.authn],
    tags: ["serviceaccounts", "authentication", "tokens"]
  },
  {
    id: "q-co-security-005",
    domain: "orchestration",
    objective: "co-security",
    lessonId: "authentication-authorization-rbac",
    difficulty: 3,
    type: "multi",
    prompt: "Which statements about Kubernetes identities are accurate? (Select TWO.)",
    choices: [
      "Authorization runs before authentication for every API request",
      "There is no User object; normal users are identified by external means such as client certificates or OIDC tokens",
      "Every RoleBinding must reference a ClusterRole",
      "ServiceAccounts are namespaced objects created and managed through the Kubernetes API",
      "Tokens issued to Pods through the TokenRequest API never expire"
    ],
    answer: [1, 3],
    explanation: "Kubernetes does not store human users; it trusts identities asserted by authenticators such as X.509 certificates or OIDC. ServiceAccounts, in contrast, are real namespaced API objects intended for workloads. Requests flow through authentication, then authorization, then admission control.",
    choiceRationale: [
      "The order is authentication first, then authorization.",
      "Correct: users come from external identity sources, not a Kubernetes object.",
      "A RoleBinding may reference either a Role or a ClusterRole.",
      "Correct: ServiceAccounts are namespaced API resources.",
      "TokenRequest tokens are time-bound and bound to the Pod, so they expire."
    ],
    references: [R2.authn, R2.serviceAccounts],
    tags: ["authentication", "serviceaccounts", "users"]
  },
  {
    id: "q-co-security-006",
    domain: "orchestration",
    objective: "co-security",
    lessonId: "pod-security-and-least-privilege",
    difficulty: 1,
    type: "single",
    prompt: "PodSecurityPolicy was removed in Kubernetes 1.25. What is the built-in replacement?",
    choices: [
      "NetworkPolicy objects applied per namespace",
      "A ClusterRole named `psp` bound to every ServiceAccount",
      "Pod Security Admission, which enforces the Pod Security Standards per namespace",
      "SecurityContextConstraints objects"
    ],
    answer: [2],
    explanation: "Pod Security Admission is a built-in admission controller that applies the Pod Security Standards (Privileged, Baseline, Restricted) based on namespace labels. It is simpler than PodSecurityPolicy and has no per-Pod policy objects. Teams needing finer rules add policy engines such as Kyverno or OPA Gatekeeper.",
    choiceRationale: [
      "NetworkPolicies control traffic, not Pod security settings.",
      "No such built-in ClusterRole exists; RBAC was only how PSPs were authorized.",
      "Correct: Pod Security Admission is the in-tree successor.",
      "SecurityContextConstraints are an OpenShift feature, not upstream Kubernetes."
    ],
    references: [R2.psa, R2.pss],
    tags: ["pod-security-admission", "psp", "admission"]
  },
  {
    id: "q-co-security-007",
    domain: "orchestration",
    objective: "co-security",
    lessonId: "pod-security-and-least-privilege",
    difficulty: 1,
    type: "single",
    prompt: "What are the three policy levels defined by the Pod Security Standards?",
    choices: [
      "Privileged, Baseline, and Restricted",
      "Enforce, Audit, and Warn",
      "Low, Medium, and High",
      "Open, Default, and Locked"
    ],
    answer: [0],
    explanation: "Privileged is unrestricted, Baseline blocks known privilege escalations, and Restricted applies current hardening best practices. Enforce, Audit and Warn are the Pod Security Admission **modes** that decide what happens when a Pod violates a level. Mixing up levels and modes is a common mistake.",
    choiceRationale: [
      "Correct: Privileged, Baseline, Restricted.",
      "These are the admission modes, not the policy levels.",
      "These are not names used by the Pod Security Standards.",
      "These are not names used by the Pod Security Standards."
    ],
    references: [R2.pss, R2.psa],
    tags: ["pod-security-standards", "levels", "admission"]
  },
  {
    id: "q-co-security-008",
    domain: "orchestration",
    objective: "co-security",
    lessonId: "pod-security-and-least-privilege",
    difficulty: 2,
    type: "single",
    prompt: `The namespace is labeled \`pod-security.kubernetes.io/enforce: restricted\`. Creating a Pod fails:

\`\`\`text
Error from server (Forbidden): error when creating "web.yaml": pods "web" is forbidden:
violates PodSecurity "restricted:latest": allowPrivilegeEscalation != false
(container "web" must set securityContext.allowPrivilegeEscalation=false),
runAsNonRoot != true (pod or container "web" must set securityContext.runAsNonRoot=true)
\`\`\`

Which change addresses these violations?`,
    choices: [
      "Set `privileged: true` so the admission controller trusts the container",
      "Bind the Pod's ServiceAccount to the `cluster-admin` ClusterRole",
      "Create a PodSecurityPolicy that allows the Pod",
      "Set `allowPrivilegeEscalation: false` and `runAsNonRoot: true` in the securityContext"
    ],
    answer: [3],
    explanation: "Pod Security Admission checks the Pod spec itself, so the fix is to harden the securityContext as the message describes. The image must also actually run as a non-root user for `runAsNonRoot` to succeed at runtime. RBAC permissions do not exempt a Pod from Pod Security Standards.",
    choiceRationale: [
      "Privileged containers are forbidden by both Baseline and Restricted.",
      "RBAC controls API access; it does not change how Pod specs are evaluated.",
      "PodSecurityPolicy was removed in 1.25 and no longer exists.",
      "Correct: these two settings satisfy exactly the reported violations."
    ],
    references: [R2.pss, R2.securityContext],
    tags: ["pod-security-admission", "securitycontext", "troubleshooting"]
  },
  {
    id: "q-co-security-009",
    domain: "orchestration",
    objective: "co-security",
    lessonId: "pod-security-and-least-privilege",
    difficulty: 2,
    type: "multi",
    prompt: "Which Pod spec settings move a workload toward least privilege? (Select TWO.)",
    choices: [
      "`readOnlyRootFilesystem: true` in the container securityContext",
      "`privileged: true` in the container securityContext",
      '`capabilities: { drop: ["ALL"] }` in the container securityContext',
      "`hostNetwork: true` in the Pod spec",
      "`runAsUser: 0` in the Pod securityContext"
    ],
    answer: [0, 2],
    explanation: "A read-only root filesystem stops attackers from modifying binaries or dropping tools, and dropping all capabilities removes kernel privileges the app rarely needs. Privileged mode, host networking and running as UID 0 all expand what a compromised container can do. Add back only the specific capabilities an app genuinely requires.",
    choiceRationale: [
      "Correct: prevents writes to the container's root filesystem.",
      "Privileged mode grants almost full access to the host.",
      "Correct: removes all Linux capabilities by default.",
      "Host networking exposes the node's network stack to the Pod.",
      "UID 0 is root, which increases the impact of a compromise."
    ],
    references: [R2.securityContext, R2.pss],
    tags: ["securitycontext", "least-privilege", "capabilities"]
  },
  {
    id: "q-co-security-010",
    domain: "orchestration",
    objective: "co-security",
    lessonId: "configmaps-and-secrets",
    difficulty: 2,
    type: "multi",
    prompt: "By default, Secret values are only base64-encoded in the API and are stored unencrypted in etcd. Which measures actually improve their protection? (Select TWO.)",
    choices: [
      "Base64-encode each value a second time before creating the Secret",
      "Enable encryption at rest for Secrets on the API server",
      "Move the values into a ConfigMap so they are hidden from `kubectl get`",
      "Restrict get, list, and watch on Secrets with least-privilege RBAC"
    ],
    answer: [1, 3],
    explanation: "Base64 is an encoding, not encryption, so anyone who can read the object or etcd can recover the values. Encryption at rest protects etcd data and backups, and tight RBAC limits who can read Secrets via the API. External secret stores are a further option for sensitive environments.",
    choiceRationale: [
      "Double encoding is still trivially reversible and adds no security.",
      "Correct: encryption at rest protects Secret data stored in etcd.",
      "ConfigMaps are intended for non-sensitive data and are fully visible.",
      "Correct: RBAC controls who can read Secrets through the API."
    ],
    references: [R2.secretsGood, R2.encryptAtRest],
    tags: ["secrets", "encryption-at-rest", "rbac"]
  },
  {
    id: "q-co-security-011",
    domain: "orchestration",
    objective: "co-security",
    lessonId: "configmaps-and-secrets",
    difficulty: 1,
    type: "single",
    prompt: `A developer commits this Secret manifest to a shared Git repository, saying it is safe because the value is "encoded":

\`\`\`yaml
apiVersion: v1
kind: Secret
metadata:
  name: db-creds
type: Opaque
data:
  password: czNjcjN0IQ==
\`\`\`

What is the problem?`,
    choices: [
      "None; base64 values can only be decoded by the API server",
      "The manifest is invalid because `data` values must be plaintext",
      "None; Kubernetes rotates the value automatically when it is applied",
      "Anyone with repository access can decode it with `base64 -d`, so it is effectively plaintext"
    ],
    answer: [3],
    explanation: "Base64 is a reversible encoding meant for transporting bytes, not for confidentiality. Committing this file exposes the password to everyone with repo access, including history forever. Use tools that encrypt secrets for Git or sync from an external secret manager instead.",
    choiceRationale: [
      "Any base64 tool decodes the value; no key is involved.",
      "`data` must be base64-encoded; plaintext belongs in `stringData`.",
      "Kubernetes never rotates Secret values on its own.",
      "Correct: base64 offers no confidentiality."
    ],
    references: [R2.secret, R2.secretsGood],
    tags: ["secrets", "base64", "gitops"]
  },
  {
    id: "q-co-security-012",
    domain: "orchestration",
    objective: "co-security",
    lessonId: "configmaps-and-secrets",
    difficulty: 3,
    type: "single",
    prompt: "A user has no `get` or `list` permission on Secrets in namespace `app`, but can create Pods there. Can they read the Secrets in `app`?",
    choices: [
      "No; RBAC on the secrets resource blocks every access path",
      "Yes; they can create a Pod that mounts the Secret and read it from inside the container",
      "Only if the Secret has type `kubernetes.io/basic-auth`",
      "Only if encryption at rest is disabled on the API server"
    ],
    answer: [1],
    explanation: "The ability to create Pods in a namespace implies indirect access to its Secrets, because a Pod can reference any Secret in its namespace as a volume or environment variable. Kubernetes security guidance calls this out explicitly. Treat Pod-creation rights as sensitive and isolate secrets by namespace.",
    choiceRationale: [
      "RBAC on secrets does not stop a Pod from mounting them.",
      "Correct: creating a Pod that consumes the Secret exposes its value.",
      "The Secret type does not affect whether a Pod can mount it.",
      "Encryption at rest protects etcd storage, not access through Pods."
    ],
    references: [R2.secretsGood, R2.rbacGood],
    tags: ["secrets", "rbac", "privilege-escalation"]
  },
  // ───────────────────────── co-troubleshooting ─────────────────────────
  {
    id: "q-co-troubleshooting-001",
    domain: "orchestration",
    objective: "co-troubleshooting",
    lessonId: "troubleshooting-workloads",
    difficulty: 1,
    type: "single",
    prompt: "A Pod has been in `Pending` for several minutes. Which command is the best first step to find out why?",
    choices: [
      "`kubectl logs <pod>`",
      "`kubectl exec -it <pod> -- sh`",
      "`kubectl describe pod <pod>` and read the Events section",
      "`kubectl rollout undo deployment/<name>`"
    ],
    answer: [2],
    explanation: "A Pending Pod usually has not been scheduled or its containers have not started, so there are no logs and nothing to exec into. `kubectl describe pod` shows events such as FailedScheduling with the exact reason. Gather evidence before taking corrective actions like rollbacks.",
    choiceRationale: [
      "No container is running yet, so there are no logs to read.",
      "You cannot exec into a container that has not started.",
      "Correct: events explain scheduling and startup problems.",
      "Rolling back without evidence may not address the cause at all."
    ],
    references: [R2.debugPods],
    tags: ["pending", "kubectl-describe", "events"]
  },
  {
    id: "q-co-troubleshooting-002",
    domain: "orchestration",
    objective: "co-troubleshooting",
    lessonId: "troubleshooting-workloads",
    difficulty: 1,
    type: "single",
    prompt: `A new release will not start:

\`\`\`text
$ kubectl get pods
NAME                  READY   STATUS             RESTARTS   AGE
api-6f9c8d7b5-q2xkz   0/1     ImagePullBackOff   0          4m

$ kubectl describe pod api-6f9c8d7b5-q2xkz | tail -3
  Warning  Failed   2m   kubelet  Failed to pull image "registry.example.com/api:v2.4.l": not found
  Warning  Failed   2m   kubelet  Error: ErrImagePull
  Normal   BackOff  1m   kubelet  Back-off pulling image "registry.example.com/api:v2.4.l"
\`\`\`

What is the most likely cause?`,
    choices: [
      "The image reference is wrong: the tag `v2.4.l` does not exist in the registry",
      "The container exceeded its memory limit during startup",
      "The liveness probe is failing and the kubelet keeps restarting it",
      "No node has enough free CPU to run the Pod"
    ],
    answer: [0],
    explanation: 'ImagePullBackOff means the kubelet repeatedly failed to pull the image and is backing off between attempts. The event says "not found", and the tag `v2.4.l` looks like a typo for `v2.4.1`. Other common causes are a missing registry credential (imagePullSecrets) or an unreachable registry.',
    choiceRationale: [
      "Correct: the registry reports that this image reference does not exist.",
      "Memory problems show up as OOMKilled after the container has started.",
      "Probes run only after the container starts, which it never did.",
      "CPU shortages leave a Pod Pending with a FailedScheduling event."
    ],
    references: [R2.debugPods, R2.images],
    tags: ["imagepullbackoff", "images", "events"]
  },
  {
    id: "q-co-troubleshooting-003",
    domain: "orchestration",
    objective: "co-troubleshooting",
    lessonId: "troubleshooting-workloads",
    difficulty: 2,
    type: "single",
    prompt: "Pod `api-7d9c-xk2lp` is in `CrashLoopBackOff`. The current container instance exits too quickly to show useful output. Which command shows the logs of the instance that just crashed?",
    choices: [
      "`kubectl get pod api-7d9c-xk2lp -o wide`",
      "`kubectl top pod api-7d9c-xk2lp`",
      "`kubectl rollout status deployment/api`",
      "`kubectl logs api-7d9c-xk2lp --previous`"
    ],
    answer: [3],
    explanation: "CrashLoopBackOff means the container keeps exiting and the kubelet waits longer between restarts. `kubectl logs --previous` (or `-p`) prints the output of the last terminated instance, which usually contains the startup error. Pair it with `kubectl describe pod` to see the exit code.",
    choiceRationale: [
      "This shows node and IP placement, not application output.",
      "This shows resource usage and requires metrics-server; it has no logs.",
      "This reports rollout progress, not why a container crashed.",
      "Correct: `--previous` returns logs from the prior container instance."
    ],
    references: [R2.debugPods, R2.kubectl],
    tags: ["crashloopbackoff", "kubectl-logs", "debugging"]
  },
  {
    id: "q-co-troubleshooting-004",
    domain: "orchestration",
    objective: "co-troubleshooting",
    lessonId: "troubleshooting-workloads",
    difficulty: 2,
    type: "single",
    prompt: `A worker Pod keeps restarting. Part of \`kubectl describe pod\`:

\`\`\`text
    State:          Running
      Started:      Tue, 10 Nov 2026 09:14:02 +0000
    Last State:     Terminated
      Reason:       OOMKilled
      Exit Code:    137
    Restart Count:  6
    Limits:
      memory:  256Mi
\`\`\`

What is happening?`,
    choices: [
      "The image cannot be pulled, so the kubelet retries it",
      "The container exceeded its 256Mi memory limit and was killed",
      "The readiness probe failed, so the kubelet restarted the container",
      "The node ran out of disk space and evicted the Pod"
    ],
    answer: [1],
    explanation: "OOMKilled with exit code 137 (128 + SIGKILL) means the kernel killed the process for exceeding its memory cgroup limit. Fix it by raising the limit to match real usage or by reducing the application's memory consumption. Evictions and image problems look different in describe output.",
    choiceRationale: [
      "Pull failures show ErrImagePull or ImagePullBackOff, not a terminated container.",
      "Correct: OOMKilled means the memory limit was exceeded.",
      "Failing readiness probes never restart containers.",
      "A disk-pressure eviction marks the Pod as Failed with reason Evicted, not OOMKilled."
    ],
    references: [R2.resources, R2.debugPods],
    tags: ["oomkilled", "resource-limits", "restarts"]
  },
  {
    id: "q-co-troubleshooting-005",
    domain: "orchestration",
    objective: "co-troubleshooting",
    lessonId: "troubleshooting-workloads",
    difficulty: 3,
    type: "single",
    prompt: `A Pod stays Pending:

\`\`\`text
Events:
  Type     Reason            Age   From               Message
  Warning  FailedScheduling  45s   default-scheduler  0/3 nodes are available: 1 node(s) had untolerated taint {node-role.kubernetes.io/control-plane: }, 2 Insufficient memory.
\`\`\`

Which action is the most appropriate fix?`,
    choices: [
      "Increase the container's memory limit",
      "Restart the kubelet on both worker nodes",
      "Lower the Pod's memory request or add nodes with more allocatable memory",
      "Remove the taint from both worker nodes"
    ],
    answer: [2],
    explanation: "The scheduler places Pods based on **requests**: both workers lack enough unreserved memory for this Pod's request, and the control-plane node is excluded by its taint. Reducing the request to a realistic value or adding capacity lets the Pod fit. Workloads normally should not be forced onto control-plane nodes.",
    choiceRationale: [
      "A higher limit does not help scheduling; it would not reduce the request.",
      "Restarting the kubelet does not free memory reserved by other Pods' requests.",
      "Correct: scheduling depends on requests fitting allocatable memory.",
      "The workers are rejected for insufficient memory, not because of taints."
    ],
    references: [R2.resources, R2.taints],
    tags: ["pending", "scheduling", "resource-requests"]
  },
  {
    id: "q-co-troubleshooting-006",
    domain: "orchestration",
    objective: "co-troubleshooting",
    lessonId: "health-probes",
    difficulty: 2,
    type: "single",
    prompt: "A container's readiness probe starts failing while its liveness probe keeps passing. What happens?",
    choices: [
      "The kubelet restarts the container",
      "The Pod is removed from Service endpoints, but the container keeps running",
      "The Pod is evicted and rescheduled on another node",
      "The owning Deployment automatically rolls back"
    ],
    answer: [1],
    explanation: "Readiness controls whether a Pod receives traffic: a failing readiness probe marks it not ready and removes it from Service endpoints. Only a failing liveness probe causes a restart. This lets an overloaded or warming-up Pod stop taking traffic without being killed.",
    choiceRationale: [
      "Restarts are triggered by liveness failures, not readiness failures.",
      "Correct: readiness only gates traffic.",
      "Probes never move Pods to other nodes.",
      "Deployments do not roll back automatically on probe failures."
    ],
    references: [R2.probes, R2.podLifecycle],
    tags: ["readiness-probe", "services", "probes"]
  },
  {
    id: "q-co-troubleshooting-007",
    domain: "orchestration",
    objective: "co-troubleshooting",
    lessonId: "health-probes",
    difficulty: 3,
    type: "single",
    prompt: `A Java service needs about 90 seconds to start. Its Pod never becomes ready and keeps restarting:

\`\`\`text
Events:
  Warning  Unhealthy  20s  kubelet  Liveness probe failed: Get "http://10.244.1.17:8080/healthz": dial tcp 10.244.1.17:8080: connect: connection refused
  Normal   Killing    20s  kubelet  Container app failed liveness probe, will be restarted
\`\`\`

What is the best fix?`,
    choices: [
      "Remove the readiness probe so traffic arrives sooner",
      "Set `restartPolicy: Never` in the Deployment's Pod template",
      "Increase the Deployment's replica count",
      "Add a startupProbe so liveness checks only begin after the app has started"
    ],
    answer: [3],
    explanation: "The liveness probe kills the container before it finishes starting, so it never gets the chance to become healthy. A startupProbe disables liveness and readiness checks until it succeeds, giving slow starters time without weakening ongoing liveness checks. A longer `initialDelaySeconds` also works but is less precise.",
    choiceRationale: [
      "Readiness is not what kills the container; liveness is.",
      "Deployments only allow `restartPolicy: Always`, and that would not fix the probe anyway.",
      "More replicas would all fail the same way.",
      "Correct: a startupProbe protects slow-starting containers from liveness kills."
    ],
    references: [R2.probes],
    tags: ["startup-probe", "liveness-probe", "restarts"]
  },
  {
    id: "q-co-troubleshooting-008",
    domain: "orchestration",
    objective: "co-troubleshooting",
    lessonId: "health-probes",
    difficulty: 1,
    type: "multi",
    prompt: "Which of the following are valid probe handler types in a Kubernetes container spec? (Select TWO.)",
    choices: ["httpGet", "icmpPing", "tcpSocket", "dnsLookup"],
    answer: [0, 2],
    explanation: "Kubernetes probes support `exec`, `httpGet`, `tcpSocket` and `grpc` handlers. An HTTP status of 200\u2013399 or a successful TCP connection counts as success. There is no built-in ICMP or DNS probe type.",
    choiceRationale: [
      "Correct: httpGet checks an HTTP endpoint.",
      "Kubernetes has no ICMP ping probe.",
      "Correct: tcpSocket checks that a port accepts connections.",
      "There is no DNS lookup probe handler."
    ],
    references: [R2.probes],
    tags: ["probes", "httpget", "tcpsocket"]
  },
  // ───────────────────────── co-storage ─────────────────────────
  {
    id: "q-co-storage-001",
    domain: "orchestration",
    objective: "co-storage",
    lessonId: "volumes",
    difficulty: 2,
    type: "single",
    prompt: "How long does the data in an `emptyDir` volume last?",
    choices: [
      "Until any container in the Pod restarts",
      "As long as the Pod exists on its node; it survives container restarts but is deleted with the Pod",
      "Until the PersistentVolumeClaim that backs it is deleted",
      "Indefinitely, because the data is stored in etcd"
    ],
    answer: [1],
    explanation: "An emptyDir is created when a Pod is assigned to a node and is removed when that Pod is removed. Container crashes and restarts do not clear it. It is useful for scratch space and for sharing files between containers, but not for durable data.",
    choiceRationale: [
      "emptyDir is tied to the Pod, so it outlives container restarts.",
      "Correct: Pod lifetime, not container lifetime.",
      "emptyDir is not backed by a PVC.",
      "Volume data is never stored in etcd."
    ],
    references: [R2.volumes],
    tags: ["emptydir", "volumes", "ephemeral"]
  },
  {
    id: "q-co-storage-002",
    domain: "orchestration",
    objective: "co-storage",
    lessonId: "volumes",
    difficulty: 2,
    type: "single",
    prompt: "Why is a `hostPath` volume generally discouraged for application workloads?",
    choices: [
      "It stores files in etcd and bloats the cluster database",
      "It only supports the ReadWriteMany access mode",
      "It requires installing a dedicated CSI driver",
      "It exposes the node's filesystem to the Pod and ties the data to a single node"
    ],
    answer: [3],
    explanation: "hostPath mounts a path from the node into the Pod, which can let a compromised container read or alter host files. The data also stays on that one node, so a rescheduled Pod will not find it. It is mainly for node-level system agents; the Baseline Pod Security Standard forbids it.",
    choiceRationale: [
      "hostPath data lives on the node's disk, not in etcd.",
      "Access modes apply to PersistentVolumes; hostPath has no such restriction.",
      "hostPath is built in and needs no CSI driver.",
      "Correct: security exposure and node affinity of data are the core problems."
    ],
    references: [R2.volumes, R2.pss],
    tags: ["hostpath", "volumes", "security"]
  },
  {
    id: "q-co-storage-003",
    domain: "orchestration",
    objective: "co-storage",
    lessonId: "volumes",
    difficulty: 1,
    type: "single",
    prompt: "A Pod has an app container that writes log files and a sidecar container that ships them. What is the simplest way for both containers to see the same files?",
    choices: [
      "Mount the same emptyDir volume into both containers",
      "Create a separate PersistentVolumeClaim for each container",
      "Have the app write to a ConfigMap that the sidecar reads",
      "Do nothing, because containers in a Pod share one root filesystem"
    ],
    answer: [0],
    explanation: "Containers in a Pod share network and volumes, but each has its own root filesystem. Declaring one emptyDir volume and mounting it into both containers gives them a shared directory for the Pod's lifetime. ConfigMaps are read-only configuration, not a data exchange channel.",
    choiceRationale: [
      "Correct: a shared emptyDir is the standard pattern.",
      "Two separate claims would give each container different storage.",
      "ConfigMaps are mounted read-only and are not meant for runtime data.",
      "Each container has its own root filesystem built from its own image."
    ],
    references: [R2.volumes],
    tags: ["emptydir", "sidecar", "volumes"]
  },
  {
    id: "q-co-storage-004",
    domain: "orchestration",
    objective: "co-storage",
    lessonId: "persistent-volumes-and-csi",
    difficulty: 1,
    type: "single",
    prompt: "What is the relationship between a PersistentVolume (PV) and a PersistentVolumeClaim (PVC)?",
    choices: [
      "A PV is a request for storage and a PVC is the actual disk",
      "They are two names for the same object in different API versions",
      "A PV represents actual storage in the cluster, and a PVC is a namespaced request that binds to a suitable PV",
      "A PVC is created by the kubelet when a Pod starts, and a PV is created by the user"
    ],
    answer: [2],
    explanation: "A PV is a cluster-scoped resource representing a piece of storage, provisioned by an admin or dynamically. A PVC is a namespaced request for a size and access mode; Kubernetes binds it to a matching PV. Pods reference the PVC, which keeps them independent of storage details.",
    choiceRationale: [
      "This reverses the roles of the two objects.",
      "They are distinct kinds with different purposes.",
      "Correct: PV is the supply, PVC is the demand.",
      "Users (or StatefulSet templates) create PVCs; the kubelet does not."
    ],
    references: [R2.pv],
    tags: ["pv", "pvc", "binding"]
  },
  {
    id: "q-co-storage-005",
    domain: "orchestration",
    objective: "co-storage",
    lessonId: "persistent-volumes-and-csi",
    difficulty: 2,
    type: "single",
    prompt: "What enables a PersistentVolume to be created automatically when a user creates a PVC?",
    choices: [
      "An administrator pre-creating a PV for every possible claim",
      "A StorageClass whose provisioner creates a matching PV on demand",
      "A hostPath volume declared in the Pod spec",
      "A ConfigMap that lists the available disks"
    ],
    answer: [1],
    explanation: "Dynamic provisioning uses a StorageClass: when a PVC references it (or the default class applies), the class's provisioner, usually a CSI driver, creates the backing volume and its PV. This removes the need for admins to pre-create volumes. Pre-created PVs are static provisioning.",
    choiceRationale: [
      "That is static provisioning, the opposite of automatic creation.",
      "Correct: StorageClasses drive dynamic provisioning.",
      "hostPath bypasses the PV/PVC system entirely.",
      "ConfigMaps hold configuration and have no role in provisioning."
    ],
    references: [R2.dynamicProvisioning, R2.storageClasses],
    tags: ["storageclass", "dynamic-provisioning", "pvc"]
  },
  {
    id: "q-co-storage-006",
    domain: "orchestration",
    objective: "co-storage",
    lessonId: "persistent-volumes-and-csi",
    difficulty: 2,
    type: "single",
    prompt: `A database Pod stays Pending. You check its claim:

\`\`\`text
$ kubectl get pvc data -n db
NAME   STATUS    VOLUME   CAPACITY   ACCESS MODES   STORAGECLASS   AGE
data   Pending                                      fast-ssd       5m

$ kubectl describe pvc data -n db | tail -2
  Warning  ProvisioningFailed  12s (x21 over 5m)  persistentvolume-controller  storageclass.storage.k8s.io "fast-ssd" not found
\`\`\`

What should you do?`,
    choices: [
      "Increase the requested capacity so a larger disk is chosen",
      "Change the access mode to ReadWriteMany",
      "Create the `fast-ssd` StorageClass or point the PVC at an existing one",
      "Delete the Pod so the scheduler retries on another node"
    ],
    answer: [2],
    explanation: "The PVC names a StorageClass that does not exist, so nothing can provision a volume and the claim stays Pending. The Pod then cannot be scheduled because its claim is unbound. Fix the class name (`kubectl get storageclass` lists what exists) or create the class.",
    choiceRationale: [
      "Capacity is irrelevant when there is no provisioner to fulfil any request.",
      "Access mode is not the reported problem and many backends do not support RWX.",
      "Correct: the error says the StorageClass is missing.",
      "Rescheduling the Pod does not create the missing StorageClass."
    ],
    references: [R2.storageClasses, R2.pv],
    tags: ["pvc", "storageclass", "troubleshooting"]
  },
  {
    id: "q-co-storage-007",
    domain: "orchestration",
    objective: "co-storage",
    lessonId: "persistent-volumes-and-csi",
    difficulty: 3,
    type: "single",
    prompt: "What does the `ReadWriteOnce` access mode on a PersistentVolume guarantee?",
    choices: [
      "Exactly one Pod in the whole cluster can mount the volume",
      "The volume can be written once and then becomes read-only",
      "Many nodes can mount it read-write, but only one at a time",
      "The volume can be mounted read-write by a single node, and Pods on that node can share it"
    ],
    answer: [3],
    explanation: "ReadWriteOnce restricts read-write mounting to one **node**, not one Pod, so several Pods on that node can use it together. If you need a single-Pod guarantee, use `ReadWriteOncePod`. Multi-node read-write access requires `ReadWriteMany` and a backend that supports it.",
    choiceRationale: [
      "That describes ReadWriteOncePod, not ReadWriteOnce.",
      "Access modes say nothing about write-once semantics.",
      "Multi-node access is ReadWriteMany or ReadOnlyMany.",
      "Correct: the limit is per node, not per Pod."
    ],
    references: [R2.pv],
    tags: ["access-modes", "pv", "readwriteonce"]
  },
  {
    id: "q-co-storage-008",
    domain: "orchestration",
    objective: "co-storage",
    lessonId: "persistent-volumes-and-csi",
    difficulty: 3,
    type: "multi",
    prompt: "Which statements about Kubernetes persistent storage are accurate? (Select TWO.)",
    choices: [
      "With reclaimPolicy `Retain`, a released PV is immediately bound to the next pending PVC",
      "With reclaimPolicy `Delete`, deleting the PVC also deletes the dynamically provisioned PV and its backing storage",
      "StorageClasses are namespaced, so each namespace needs its own",
      "In-tree volume plugins are the recommended way to add new storage backends",
      "CSI lets storage vendors ship drivers independently of the Kubernetes core code"
    ],
    answer: [1, 4],
    explanation: "Dynamically provisioned volumes default to the Delete reclaim policy, so removing the claim removes the storage. Retain keeps the PV and its data in a Released state until an admin cleans it up manually. CSI is the standard plugin interface; in-tree plugins have largely been migrated to CSI drivers.",
    choiceRationale: [
      "A Retained PV stays Released and must be reclaimed manually before reuse.",
      "Correct: Delete removes both the PV and the underlying volume.",
      "StorageClasses are cluster-scoped.",
      "New backends are added as CSI drivers; in-tree plugins are being phased out.",
      "Correct: CSI decouples storage drivers from the Kubernetes release cycle."
    ],
    references: [R2.pv, R2.volumes],
    tags: ["reclaim-policy", "csi", "storageclass"]
  }
];

// ../../packages/content/src/questions/delivery-architecture.ts
var R3 = {
  gitops: { title: "OpenGitOps principles", url: "https://opengitops.dev/" },
  argo: { title: "Argo CD documentation", url: "https://argo-cd.readthedocs.io/" },
  flux: { title: "Flux documentation", url: "https://fluxcd.io/flux/" },
  helm: { title: "Helm documentation", url: "https://helm.sh/docs/" },
  kustomize: { title: "Kustomize", url: "https://kustomize.io/" },
  kustomizeTask: {
    title: "Declarative management of Kubernetes objects using Kustomize",
    url: "https://kubernetes.io/docs/tasks/manage-kubernetes-objects/kustomization/"
  },
  deployment: { title: "Kubernetes Deployments", url: "https://kubernetes.io/docs/concepts/workloads/controllers/deployment/" },
  debug: { title: "Kubernetes: Monitoring, logging, and debugging", url: "https://kubernetes.io/docs/tasks/debug/" },
  ephemeral: { title: "Ephemeral containers", url: "https://kubernetes.io/docs/concepts/workloads/pods/ephemeral-containers/" },
  kubectl: { title: "kubectl reference", url: "https://kubernetes.io/docs/reference/kubectl/" },
  service: { title: "Kubernetes Service", url: "https://kubernetes.io/docs/concepts/services-networking/service/" },
  otel: { title: "OpenTelemetry documentation", url: "https://opentelemetry.io/docs/" },
  sre: { title: "Google SRE book: Service Level Objectives", url: "https://sre.google/sre-book/service-level-objectives/" },
  glossary: { title: "CNCF Cloud Native Glossary", url: "https://glossary.cncf.io/" },
  prom: { title: "Prometheus overview", url: "https://prometheus.io/docs/introduction/overview/" },
  pushing: { title: "Prometheus: When to use the Pushgateway", url: "https://prometheus.io/docs/practices/pushing/" },
  promql: { title: "Querying Prometheus", url: "https://prometheus.io/docs/prometheus/latest/querying/basics/" },
  twelve: { title: "The Twelve-Factor App", url: "https://12factor.net/" },
  hpa: { title: "Horizontal Pod Autoscaling", url: "https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/" },
  keda: { title: "KEDA", url: "https://keda.sh/" },
  envoy: { title: "Envoy documentation", url: "https://www.envoyproxy.io/docs" },
  istio: { title: "Istio documentation", url: "https://istio.io/latest/docs/" },
  linkerd: { title: "Linkerd", url: "https://linkerd.io/" },
  raft: { title: "The Raft consensus algorithm", url: "https://raft.github.io/" },
  etcd: { title: "etcd documentation", url: "https://etcd.io/docs/" },
  cncfProjects: { title: "CNCF projects", url: "https://www.cncf.io/projects/" },
  toc: { title: "CNCF Technical Oversight Committee", url: "https://github.com/cncf/toc" },
  keps: { title: "Kubernetes Enhancement Proposals", url: "https://github.com/kubernetes/enhancements" },
  community: { title: "Kubernetes community (SIGs)", url: "https://github.com/kubernetes/community" },
  components: { title: "Kubernetes components", url: "https://kubernetes.io/docs/concepts/overview/components/" }
};
var questionsDeliveryArchitecture = [
  // ---------------------------------------------------------------- cad-delivery: cicd-and-gitops
  {
    id: "q-cad-delivery-001",
    domain: "delivery",
    objective: "cad-delivery",
    lessonId: "cicd-and-gitops",
    difficulty: 1,
    type: "single",
    prompt: "Which description best matches the core idea of GitOps?",
    choices: [
      "A CI pipeline runs `kubectl apply` against production with admin credentials after every merge.",
      "Operators log in to nodes and edit manifests directly whenever an incident occurs.",
      "Git holds the desired state, and an agent in the cluster pulls it and reconciles the cluster to match.",
      "The running cluster state is exported into Git every night as a backup."
    ],
    answer: [2],
    explanation: "GitOps treats a Git repository as the source of truth for declarative desired state. A software agent (such as Argo CD or Flux) pulls that state and continuously reconciles the cluster toward it, so changes happen through commits rather than ad-hoc commands.",
    choiceRationale: [
      "This is push-based CD from a CI system; it uses Git as a trigger but not as a continuously reconciled source of truth.",
      "Manual edits on nodes are the opposite of GitOps and create untracked drift.",
      "Correct: declared state lives in Git and an in-cluster agent pulls and reconciles it.",
      "Exporting live state into Git makes Git a backup, not the source of desired state."
    ],
    references: [R3.gitops, R3.argo],
    tags: ["gitops", "cd", "reconciliation"]
  },
  {
    id: "q-cad-delivery-002",
    domain: "delivery",
    objective: "cad-delivery",
    lessonId: "cicd-and-gitops",
    difficulty: 2,
    type: "multi",
    prompt: "Which of the following are principles defined by OpenGitOps? **Select TWO.**",
    choices: [
      "Pushed to the cluster by the CI pipeline",
      "Declarative",
      "Hotfixed in place with `kubectl edit`",
      "Continuously reconciled"
    ],
    answer: [1, 3],
    explanation: "OpenGitOps defines four principles: declarative, versioned and immutable, pulled automatically, and continuously reconciled. Desired state is pulled by agents rather than pushed by CI, and out-of-band edits are treated as drift to be corrected.",
    choiceRationale: [
      "OpenGitOps says state is pulled automatically by agents, not pushed by CI.",
      "Correct: the system desired state must be expressed declaratively.",
      "Manual in-place edits are drift, which GitOps agents detect and correct.",
      "Correct: agents continuously observe actual state and work to match desired state."
    ],
    references: [R3.gitops],
    tags: ["gitops", "opengitops", "principles"]
  },
  {
    id: "q-cad-delivery-003",
    domain: "delivery",
    objective: "cad-delivery",
    lessonId: "cicd-and-gitops",
    difficulty: 2,
    type: "single",
    prompt: "A Deployment is managed by an Argo CD Application with automated sync and self-heal enabled. Git declares `replicas: 3`. An engineer runs `kubectl scale deployment api --replicas=6`. What happens next?",
    choices: [
      "The new value stays, and Argo CD commits `replicas: 6` back to the Git repository.",
      "Argo CD detects the drift and restores the Deployment to the 3 replicas declared in Git.",
      "The API server rejects the command because the object is managed by Argo CD.",
      "Argo CD deletes the Deployment and recreates it, causing a brief full outage."
    ],
    answer: [1],
    explanation: "Argo CD compares live state against Git. With self-heal enabled, it treats the manual change as drift and syncs the object back to the declared value. The durable way to change replicas is a commit to Git.",
    choiceRationale: [
      "GitOps agents reconcile the cluster toward Git; they do not write live changes back into the repository.",
      "Correct: self-heal reverts out-of-band changes to match the Git-declared state.",
      "The API server accepts the change if RBAC allows it; Argo CD reacts afterwards.",
      "Argo CD patches the object back to the desired state rather than deleting and recreating it."
    ],
    references: [R3.argo, R3.gitops],
    tags: ["gitops", "argo-cd", "drift"]
  },
  {
    id: "q-cad-delivery-004",
    domain: "delivery",
    objective: "cad-delivery",
    lessonId: "cicd-and-gitops",
    difficulty: 1,
    type: "single",
    prompt: "What is the main focus of continuous integration (CI)?",
    choices: [
      "Automatically promoting every artifact to production without any review.",
      "Reconciling cluster state against manifests stored in a Git repository.",
      "Scheduling Pods onto nodes that have enough free capacity.",
      "Merging code changes frequently and automatically building and testing each change."
    ],
    answer: [3],
    explanation: "CI is about integrating changes into a shared branch often, with every change automatically built and tested so problems surface early. Continuous delivery or deployment then takes the resulting artifacts and releases them to environments.",
    choiceRationale: [
      "Releasing every change to production automatically describes continuous deployment, not CI.",
      "Reconciling a cluster against Git describes GitOps-style delivery.",
      "Placing Pods on nodes is the job of the kube-scheduler.",
      "Correct: frequent merges with automated build and test are the essence of CI."
    ],
    references: [R3.glossary],
    tags: ["ci", "cicd"]
  },
  {
    id: "q-cad-delivery-005",
    domain: "delivery",
    objective: "cad-delivery",
    lessonId: "cicd-and-gitops",
    difficulty: 2,
    type: "single",
    prompt: "Why is pull-based GitOps often considered to have a smaller attack surface than a CI system that pushes deployments into the cluster?",
    choices: [
      "Cluster credentials stay inside the cluster instead of being stored in the external CI system.",
      "The GitOps agent automatically encrypts every Secret stored in etcd.",
      "Pull-based agents bypass RBAC, so fewer permissions need to be configured.",
      "Git signs every container image while the agent pulls manifests."
    ],
    answer: [0],
    explanation: "With push-based CD, the CI system needs credentials that can modify the cluster, which makes it a high-value target. In pull-based GitOps the agent runs inside the cluster and only needs read access to the repository, so cluster-admin-level credentials never leave the cluster.",
    choiceRationale: [
      "Correct: the agent runs in-cluster, so the CI system does not need cluster write credentials.",
      "GitOps agents do not change how Secrets are stored in etcd; encryption at rest is configured separately.",
      "GitOps agents act through the API server and are subject to RBAC like any other client.",
      "Git does not sign images; image signing is done with separate supply-chain tools."
    ],
    references: [R3.gitops, R3.flux],
    tags: ["gitops", "security", "pull-model"]
  },
  {
    id: "q-cad-delivery-006",
    domain: "delivery",
    objective: "cad-delivery",
    lessonId: "cicd-and-gitops",
    difficulty: 2,
    type: "single",
    prompt: "Which statement about Argo CD and Flux is accurate?",
    choices: [
      "Flux is a CI server that builds images, while Argo CD only deploys them.",
      "Argo CD only supports Helm charts, while Flux only supports plain YAML.",
      "Both run as controllers in the cluster and reconcile declared state from sources such as Git.",
      "Both push manifests from developer laptops to the cluster on every commit."
    ],
    answer: [2],
    explanation: "Argo CD and Flux are both CNCF graduated GitOps tools. Each runs inside the cluster, watches sources such as Git repositories, and reconciles Kubernetes resources to match, with support for plain manifests, Kustomize, and Helm.",
    choiceRationale: [
      "Neither tool is a CI server; image builds happen in a separate CI pipeline.",
      "Both tools support Helm, Kustomize, and plain manifests.",
      "Correct: both are in-cluster GitOps controllers that pull and reconcile desired state.",
      "Both follow a pull model from the cluster side, not a push from developer machines."
    ],
    references: [R3.argo, R3.flux],
    tags: ["gitops", "argo-cd", "flux"]
  },
  // ---------------------------------------------------------------- cad-delivery: helm-and-kustomize
  {
    id: "q-cad-delivery-007",
    domain: "delivery",
    objective: "cad-delivery",
    lessonId: "helm-and-kustomize",
    difficulty: 1,
    type: "single",
    prompt: "In Helm terminology, what is a **release**?",
    choices: [
      "A packaged set of templates and default values that describes an application.",
      "A remote location where packaged charts are stored and shared.",
      "The `values.yaml` file a user passes to override chart defaults.",
      "A specific installed instance of a chart in a cluster, with a name and revision history."
    ],
    answer: [3],
    explanation: "A chart is the package; a release is one installation of that chart in a cluster. The same chart can be installed several times as different releases, and each upgrade or rollback adds a new revision to that release.",
    choiceRationale: [
      "That describes a chart, the package itself.",
      "That describes a chart repository.",
      "A values file customizes an install but is not the release itself.",
      "Correct: a release is a named, versioned installation of a chart."
    ],
    references: [R3.helm],
    tags: ["helm", "release", "chart"]
  },
  {
    id: "q-cad-delivery-008",
    domain: "delivery",
    objective: "cad-delivery",
    lessonId: "helm-and-kustomize",
    difficulty: 2,
    type: "single",
    prompt: "How does Kustomize produce environment-specific manifests?",
    choices: [
      "It layers overlays and patches onto a base of plain YAML without a templating language.",
      "It renders Go templates using values files, similar to a Helm chart.",
      "It stores each rendered version as a release record for later rollback.",
      "It downloads packaged charts from an OCI registry and installs them."
    ],
    answer: [0],
    explanation: "Kustomize is template-free: you keep valid Kubernetes YAML in a base and describe per-environment changes as overlays and patches in a `kustomization.yaml`. Helm, by contrast, renders templates with values and tracks releases.",
    choiceRationale: [
      "Correct: Kustomize customizes plain YAML through bases, overlays, and patches.",
      "Go templates with values files are how Helm works, not Kustomize.",
      "Release records and rollback history are a Helm feature.",
      "Pulling and installing packaged charts is Helm behavior."
    ],
    references: [R3.kustomize, R3.kustomizeTask],
    tags: ["kustomize", "overlays", "helm"]
  },
  {
    id: "q-cad-delivery-009",
    domain: "delivery",
    objective: "cad-delivery",
    lessonId: "helm-and-kustomize",
    difficulty: 1,
    type: "single",
    prompt: "A directory `overlays/prod` contains a `kustomization.yaml`. Which command applies it using the Kustomize support built into kubectl?",
    choices: [
      "`helm install prod overlays/prod`",
      "`kubectl create -f overlays/prod/values.yaml`",
      "`kubectl apply -k overlays/prod`",
      "`kubectl kustomize apply overlays/prod`"
    ],
    answer: [2],
    explanation: "kubectl has had Kustomize built in since v1.14. The `-k` flag tells `kubectl apply` to build the kustomization in the given directory and apply the result.",
    choiceRationale: [
      "Helm installs charts, and this directory is a kustomization, not a chart.",
      "Kustomize does not use a `values.yaml`, and `-f` would skip the kustomization build.",
      "Correct: `kubectl apply -k <dir>` builds and applies a kustomization.",
      "`kubectl kustomize` only renders output; it has no `apply` subcommand."
    ],
    references: [R3.kustomizeTask],
    tags: ["kustomize", "kubectl"]
  },
  {
    id: "q-cad-delivery-010",
    domain: "delivery",
    objective: "cad-delivery",
    lessonId: "helm-and-kustomize",
    difficulty: 1,
    type: "single",
    prompt: "`helm history shop` shows revisions 1, 2, and 3. Revision 3 broke the app and revision 2 was healthy. Which command returns the release to the healthy configuration?",
    choices: [
      "`helm rollback shop 3`",
      "`helm rollback shop 2`",
      "`helm history shop 2`",
      "`helm uninstall shop`"
    ],
    answer: [1],
    explanation: "`helm rollback <release> <revision>` re-applies the manifests from an earlier revision. The rollback itself is recorded as a new revision (4), so history is preserved.",
    choiceRationale: [
      "Revision 3 is the broken one; rolling back to it changes nothing useful.",
      "Correct: this restores the configuration from healthy revision 2.",
      "`helm history` only lists revisions; it does not change the release.",
      "Uninstalling removes the application entirely instead of restoring it."
    ],
    references: [R3.helm],
    tags: ["helm", "rollback"]
  },
  {
    id: "q-cad-delivery-011",
    domain: "delivery",
    objective: "cad-delivery",
    lessonId: "helm-and-kustomize",
    difficulty: 3,
    type: "single",
    prompt: "In Helm 3, where is release information (such as revision history) stored by default?",
    choices: [
      "In the Tiller server running in the `kube-system` namespace.",
      "In Secrets in the namespace where the release is installed.",
      "In the chart repository `index.yaml` file.",
      "In a local file on the machine that ran `helm install`."
    ],
    answer: [1],
    explanation: "Helm 3 removed the in-cluster Tiller component. Release state is stored as Secrets in the release namespace by default, which is why any user with the right RBAC permissions can run `helm history` or `helm rollback` from their own machine.",
    choiceRationale: [
      "Tiller existed in Helm 2 and was removed in Helm 3.",
      "Correct: Helm 3 stores release records as Secrets in the release namespace by default.",
      "The repository index lists available charts, not installed releases.",
      "Storing state on one laptop would prevent teammates from managing the release."
    ],
    references: [R3.helm],
    tags: ["helm", "helm3", "release"]
  },
  // ---------------------------------------------------------------- cad-delivery: rollouts-and-deployment-strategies
  {
    id: "q-cad-delivery-012",
    domain: "delivery",
    objective: "cad-delivery",
    lessonId: "rollouts-and-deployment-strategies",
    difficulty: 3,
    type: "single",
    prompt: "A Deployment has `replicas: 10` and uses the default RollingUpdate settings (`maxSurge: 25%`, `maxUnavailable: 25%`). During a rollout, what is the maximum total number of Pods that can exist at once?",
    choices: ["10", "12", "13", "15"],
    answer: [2],
    explanation: "`maxSurge` is calculated from the desired replicas and rounded up: 25% of 10 is 2.5, which becomes 3. So up to 10 + 3 = 13 Pods may exist. `maxUnavailable` rounds down, so at least 8 Pods stay available.",
    choiceRationale: [
      "A surge above the desired count is allowed, so the total can exceed 10.",
      "This assumes 2.5 rounds down, but maxSurge rounds up.",
      "Correct: 25% of 10 rounds up to 3 extra Pods, giving 13.",
      "This adds maxSurge and maxUnavailable together, which is not how the limit works."
    ],
    references: [R3.deployment],
    tags: ["rolling-update", "maxsurge", "deployment"]
  },
  {
    id: "q-cad-delivery-013",
    domain: "delivery",
    objective: "cad-delivery",
    lessonId: "rollouts-and-deployment-strategies",
    difficulty: 1,
    type: "single",
    prompt: "Which strategy keeps two complete environments running and switches all traffic from the old one to the new one in a single step?",
    choices: ["Blue/green", "Canary", "Rolling update", "Recreate"],
    answer: [0],
    explanation: "Blue/green runs the current (blue) and new (green) versions side by side at full size, then flips traffic at once, for example by changing a Service selector. Rolling back is just flipping traffic back.",
    choiceRationale: [
      "Correct: two full environments with an all-at-once traffic switch is blue/green.",
      "Canary sends a small share of traffic to the new version and grows it gradually.",
      "A rolling update replaces Pods incrementally rather than switching between two full environments.",
      "Recreate stops the old version before starting the new one, so there is no parallel environment."
    ],
    references: [R3.deployment],
    tags: ["blue-green", "deployment-strategies"]
  },
  {
    id: "q-cad-delivery-014",
    domain: "delivery",
    objective: "cad-delivery",
    lessonId: "rollouts-and-deployment-strategies",
    difficulty: 2,
    type: "single",
    prompt: "A team wants to send about 5% of users to v2, watch error rates, and only then increase the share. Which deployment strategy fits?",
    choices: ["Recreate", "Blue/green", "Rolling update with `maxSurge: 1`", "Canary"],
    answer: [3],
    explanation: "A canary release exposes a small, controlled share of traffic to the new version and expands it as metrics stay healthy. Precise percentage-based splits usually need a service mesh, Gateway API, or a progressive delivery tool rather than a plain Deployment.",
    choiceRationale: [
      "Recreate replaces all Pods at once and cannot target a percentage of users.",
      "Blue/green switches all traffic at once instead of a small share first.",
      "A rolling update replaces Pods progressively but does not control traffic percentages or pause for metric checks.",
      "Correct: canary releases start with a small traffic share and expand based on observed health."
    ],
    references: [R3.deployment, R3.glossary],
    tags: ["canary", "deployment-strategies", "progressive-delivery"]
  },
  {
    id: "q-cad-delivery-015",
    domain: "delivery",
    objective: "cad-delivery",
    lessonId: "rollouts-and-deployment-strategies",
    difficulty: 2,
    type: "single",
    prompt: "Which change to a Deployment creates a new ReplicaSet and a new rollout revision?",
    choices: [
      "Changing `spec.replicas` from 3 to 5.",
      "Changing the container image in the Pod template.",
      "Adding a label to the Deployment object metadata.",
      "Running `kubectl rollout status` on the Deployment."
    ],
    answer: [1],
    explanation: "A rollout is triggered only when the Pod template (`spec.template`) changes, such as a new image, env var, or template label. Scaling only changes the replica count of the current ReplicaSet and does not create a revision.",
    choiceRationale: [
      "Scaling adjusts the existing ReplicaSet and does not create a new revision.",
      "Correct: changing the Pod template, such as the image, starts a new rollout.",
      "Labels on the Deployment itself are outside the Pod template and do not trigger a rollout.",
      "`rollout status` only reports progress; it does not modify anything."
    ],
    references: [R3.deployment],
    tags: ["rollout", "replicaset", "deployment"]
  },
  {
    id: "q-cad-delivery-016",
    domain: "delivery",
    objective: "cad-delivery",
    lessonId: "rollouts-and-deployment-strategies",
    difficulty: 2,
    type: "multi",
    prompt: "Which statements about the Deployment `Recreate` strategy are true? **Select TWO.**",
    choices: [
      "All existing Pods are terminated before new Pods are created.",
      "Traffic shifts gradually by percentage between the old and new versions.",
      "It requires an Ingress controller in order to work.",
      "Old and new versions never serve traffic at the same time."
    ],
    answer: [0, 3],
    explanation: "`Recreate` kills all old Pods first and then creates the new ones. This causes downtime but guarantees two versions never run side by side, which helps when versions cannot coexist (for example, incompatible schema changes).",
    choiceRationale: [
      "Correct: Recreate removes every old Pod before starting new ones.",
      "Gradual percentage-based shifting describes a canary release.",
      "Recreate is a native Deployment strategy and needs no Ingress controller.",
      "Correct: because old Pods are gone first, versions never overlap."
    ],
    references: [R3.deployment],
    tags: ["recreate", "deployment-strategies"]
  },
  // ---------------------------------------------------------------- cad-debugging: debugging-applications
  {
    id: "q-cad-debugging-001",
    domain: "delivery",
    objective: "cad-debugging",
    lessonId: "debugging-applications",
    difficulty: 1,
    type: "single",
    prompt: "Pod `web-7d9c-xk2lp` shows `RESTARTS 4`. You want to read the output of the container instance that crashed, not the one currently running. Which command do you use?",
    choices: [
      "`kubectl logs web-7d9c-xk2lp -f`",
      "`kubectl get pod web-7d9c-xk2lp -o wide`",
      "`kubectl logs web-7d9c-xk2lp --previous`",
      "`kubectl top pod web-7d9c-xk2lp`"
    ],
    answer: [2],
    explanation: "After a restart, `kubectl logs` shows the current container instance. `--previous` (or `-p`) returns logs from the prior terminated instance, which usually contains the crash reason.",
    choiceRationale: [
      "`-f` streams logs from the current instance, not the crashed one.",
      "`get -o wide` shows node and IP details, not container output.",
      "Correct: `--previous` returns logs from the last terminated container.",
      "`kubectl top` shows current CPU and memory usage, not logs."
    ],
    references: [R3.debug, R3.kubectl],
    tags: ["kubectl-logs", "crashloopbackoff", "debugging"]
  },
  {
    id: "q-cad-debugging-002",
    domain: "delivery",
    objective: "cad-debugging",
    lessonId: "debugging-applications",
    difficulty: 2,
    type: "single",
    prompt: "Container `app` in Pod `api-5f6b-q8x2z` uses a distroless image with no shell. You need to run network tools next to it without restarting the Pod. Which command fits?",
    choices: [
      "`kubectl exec -it api-5f6b-q8x2z -- sh`",
      "`kubectl attach -it api-5f6b-q8x2z`",
      "`kubectl port-forward api-5f6b-q8x2z 8080:80`",
      "`kubectl debug -it api-5f6b-q8x2z --image=busybox --target=app`"
    ],
    answer: [3],
    explanation: "`kubectl debug` adds an ephemeral container with its own image (and tools) to a running Pod. `--target` shares the process namespace of the named container so you can inspect its processes, and the Pod is not restarted.",
    choiceRationale: [
      "`exec` runs inside the existing container, which has no shell to start.",
      "`attach` connects to the main process stdio and brings no extra tools.",
      "Port-forwarding reaches the app from your machine but gives no tools inside the Pod.",
      "Correct: an ephemeral debug container brings its own tools into the running Pod."
    ],
    references: [R3.ephemeral, R3.debug],
    tags: ["kubectl-debug", "ephemeral-containers", "distroless"]
  },
  {
    id: "q-cad-debugging-003",
    domain: "delivery",
    objective: "cad-debugging",
    lessonId: "debugging-applications",
    difficulty: 2,
    type: "single",
    prompt: "What does `kubectl port-forward svc/api 8080:80` do?",
    choices: [
      "Publishes the Service on port 8080 of every node so external clients can reach it.",
      "Forwards `localhost:8080` on your machine to port 80 of a Pod selected by `svc/api`.",
      "Changes the Service port from 80 to 8080 for all clients in the cluster.",
      "Forwards port 8080 in the Pod to port 80 on your local machine."
    ],
    answer: [1],
    explanation: "The port pair is `LOCAL:REMOTE`. When the target is a Service, kubectl picks one backing Pod and tunnels your local port to it through the API server. Nothing changes in the cluster, and there is no load balancing across Pods.",
    choiceRationale: [
      "Exposing a port on every node is what a NodePort Service does.",
      "Correct: the local port 8080 is tunneled to port 80 on one Pod behind the Service.",
      "port-forward is a temporary tunnel and does not modify the Service.",
      "The order is reversed: the first number is local and the second is remote."
    ],
    references: [R3.kubectl, R3.debug],
    tags: ["port-forward", "kubectl", "debugging"]
  },
  {
    id: "q-cad-debugging-004",
    domain: "delivery",
    objective: "cad-debugging",
    lessonId: "debugging-applications",
    difficulty: 3,
    type: "multi",
    prompt: "Which statements about ephemeral containers are true? **Select TWO.**",
    choices: [
      "Once added to a Pod, an ephemeral container cannot be removed from that Pod.",
      "They support liveness and readiness probes like regular containers.",
      "They can be added to an already running Pod without restarting it.",
      "They are declared in a Deployment Pod template so they start with every replica."
    ],
    answer: [0, 2],
    explanation: "Ephemeral containers are added to an existing Pod through a special subresource, typically with `kubectl debug`. They are meant for interactive troubleshooting, so they lack ports, probes, and resource guarantees, and they stay in the Pod spec until the Pod is deleted.",
    choiceRationale: [
      "Correct: ephemeral containers cannot be removed; they go away when the Pod is deleted.",
      "Probes are not allowed on ephemeral containers.",
      "Correct: they are injected into a running Pod without restarting it.",
      "They cannot be defined in Pod templates; they are added to individual running Pods."
    ],
    references: [R3.ephemeral],
    tags: ["ephemeral-containers", "kubectl-debug"]
  },
  {
    id: "q-cad-debugging-005",
    domain: "delivery",
    objective: "cad-debugging",
    lessonId: "debugging-applications",
    difficulty: 3,
    type: "single",
    prompt: "A container exits within a second of starting, so `kubectl exec` never succeeds. You want to inspect its filesystem and try the startup command by hand. Which approach is most practical?",
    choices: [
      "Use `kubectl debug --copy-to` to create a copy of the Pod with the container command replaced by a shell.",
      "Run `kubectl exec` in a tight loop until it connects between restarts.",
      "Use `kubectl port-forward` to the Pod and browse its files over HTTP.",
      "Set `restartPolicy: Always` so the container stays up long enough to exec."
    ],
    answer: [0],
    explanation: "`kubectl debug <pod> --copy-to=<new-name>` creates a copy of the Pod, and you can override the container command (for example to `sh`) so it stays running. The original Pod is untouched while you explore the copy.",
    choiceRationale: [
      "Correct: a debug copy with an overridden command keeps the container alive for inspection.",
      "Racing restarts is unreliable, and backoff delays make the window even smaller.",
      "port-forward tunnels network traffic; it does not expose the container filesystem.",
      "Pods from a Deployment already use `Always`, which restarts the container but cannot keep it running."
    ],
    references: [R3.debug, R3.kubectl],
    tags: ["kubectl-debug", "crashloopbackoff", "debugging"]
  },
  {
    id: "q-cad-debugging-006",
    domain: "delivery",
    objective: "cad-debugging",
    lessonId: "debugging-applications",
    difficulty: 1,
    type: "single",
    prompt: "Which command shows a Pod's recent Events, such as failed image pulls or failed probes, alongside its status?",
    choices: [
      "`kubectl logs web-7d9c-xk2lp`",
      "`kubectl get pod web-7d9c-xk2lp`",
      "`kubectl exec web-7d9c-xk2lp -- env`",
      "`kubectl describe pod web-7d9c-xk2lp`"
    ],
    answer: [3],
    explanation: "`kubectl describe pod` combines the Pod spec and status with related Events at the bottom. Events record what the scheduler and kubelet did, such as image pull errors, probe failures, and scheduling problems.",
    choiceRationale: [
      "Logs show application output, not Kubernetes Events.",
      "`get` shows a one-line status summary without the Events list.",
      "`exec env` prints environment variables inside the container.",
      "Correct: `describe` includes the Events related to the Pod."
    ],
    references: [R3.debug],
    tags: ["kubectl-describe", "events", "debugging"]
  },
  {
    id: "q-cad-debugging-007",
    domain: "delivery",
    objective: "cad-debugging",
    lessonId: "debugging-applications",
    difficulty: 2,
    type: "single",
    prompt: "Requests through Service `api` time out. The backing Pods are all `Running` and `1/1` Ready, and `kubectl port-forward` to a Pod works. `kubectl get endpointslices -l kubernetes.io/service-name=api` lists no endpoints. What is the most likely cause?",
    choices: [
      "The Service selector does not match the labels on the Pods.",
      "The Pods do not define a liveness probe.",
      "The container image uses the `latest` tag.",
      "The namespace has a ResourceQuota applied."
    ],
    answer: [0],
    explanation: "EndpointSlices for a Service are populated with Ready Pods whose labels match the Service selector. Since the Pods are Ready and reachable directly, an empty endpoint list points to a selector and label mismatch.",
    choiceRationale: [
      "Correct: with Ready Pods but no endpoints, the selector is not matching any Pod.",
      "Liveness probes affect restarts, not Service endpoint membership.",
      "The image tag does not influence which Pods a Service selects.",
      "A ResourceQuota limits resource creation but does not remove endpoints."
    ],
    references: [R3.service, R3.debug],
    tags: ["services", "endpointslices", "selectors"]
  },
  {
    id: "q-cad-debugging-008",
    domain: "delivery",
    objective: "cad-debugging",
    lessonId: "debugging-applications",
    difficulty: 3,
    type: "single",
    prompt: "What does `kubectl debug node/worker-1 -it --image=busybox` do?",
    choices: [
      "Creates a Pod on `worker-1` that runs in host namespaces with the node root filesystem mounted at `/host`.",
      "Opens an SSH session to `worker-1` using the kubelet credentials.",
      "Cordons and drains `worker-1` so it can be repaired safely.",
      "Adds an ephemeral container to every Pod currently running on `worker-1`."
    ],
    answer: [0],
    explanation: "Node debugging creates a new Pod scheduled on the target node that shares host namespaces and mounts the node filesystem at `/host`. It is a way to inspect a node without direct SSH access; remember to delete the debug Pod afterwards.",
    choiceRationale: [
      "Correct: kubectl creates a debugging Pod on that node with the host filesystem at `/host`.",
      "kubectl does not use SSH; it works through the API server.",
      "Cordon and drain are separate commands (`kubectl cordon`, `kubectl drain`).",
      "Node debugging creates one new Pod and does not alter existing Pods."
    ],
    references: [R3.debug, R3.kubectl],
    tags: ["kubectl-debug", "nodes", "debugging"]
  },
  // ---------------------------------------------------------------- cna-observability: observability-fundamentals
  {
    id: "q-cna-observability-001",
    domain: "architecture",
    objective: "cna-observability",
    lessonId: "observability-fundamentals",
    difficulty: 1,
    type: "single",
    prompt: "A checkout request passes through six microservices and is slow. Which telemetry signal best shows how much time each service spent on that single request?",
    choices: ["Metrics", "Logs", "Kubernetes Events", "Distributed traces"],
    answer: [3],
    explanation: "A distributed trace follows one request across services as a tree of spans, each with its own timing. Metrics show aggregate trends and logs show discrete events, but neither naturally connects one request end to end.",
    choiceRationale: [
      "Metrics are aggregated numbers over time and do not follow individual requests.",
      "Logs record events per service but do not link them into a timed request path by themselves.",
      "Kubernetes Events describe cluster object changes, not application request latency.",
      "Correct: traces break one request into timed spans across every service it touched."
    ],
    references: [R3.otel, R3.glossary],
    tags: ["tracing", "observability", "signals"]
  },
  {
    id: "q-cna-observability-002",
    domain: "architecture",
    objective: "cna-observability",
    lessonId: "observability-fundamentals",
    difficulty: 2,
    type: "single",
    prompt: "A team sets an internal goal that 99.9% of HTTP requests over 30 days must return a non-5xx response. No customer contract or penalty is attached. What is this goal called?",
    choices: ["SLO", "SLI", "SLA", "Error budget"],
    answer: [0],
    explanation: "The SLI is the measurement (the share of non-5xx responses). The SLO is the target set for that measurement, here 99.9% over 30 days. An SLA is an external agreement with consequences, and the error budget is the 0.1% of allowed failure.",
    choiceRationale: [
      "Correct: an internal target for a service level indicator is an SLO.",
      "The SLI is the measured ratio itself, not the target.",
      "An SLA is a contract with customers, usually with penalties.",
      "The error budget is the allowed failure (0.1%) derived from the SLO."
    ],
    references: [R3.sre],
    tags: ["slo", "sli", "sla"]
  },
  {
    id: "q-cna-observability-003",
    domain: "architecture",
    objective: "cna-observability",
    lessonId: "observability-fundamentals",
    difficulty: 2,
    type: "single",
    prompt: "What is OpenTelemetry?",
    choices: [
      "A time-series database that stores metrics and evaluates alerting rules.",
      "A vendor-neutral set of APIs, SDKs, and a Collector for producing and exporting traces, metrics, and logs.",
      "A dashboard tool that visualizes data from many backends.",
      "A node agent that only ships container log files to a central store."
    ],
    answer: [1],
    explanation: "OpenTelemetry standardizes how telemetry is generated, collected, and exported. It is not a storage backend; you send its data to backends such as Prometheus, Jaeger, or a commercial tool.",
    choiceRationale: [
      "That describes Prometheus; OpenTelemetry does not store data.",
      "Correct: OpenTelemetry provides instrumentation APIs, SDKs, and the Collector.",
      "Dashboards are the role of tools such as Grafana.",
      "OpenTelemetry covers traces, metrics, and logs, not only log shipping."
    ],
    references: [R3.otel],
    tags: ["opentelemetry", "instrumentation"]
  },
  {
    id: "q-cna-observability-004",
    domain: "architecture",
    objective: "cna-observability",
    lessonId: "observability-fundamentals",
    difficulty: 2,
    type: "multi",
    prompt: "Which are component types in an OpenTelemetry Collector pipeline? **Select TWO.**",
    choices: ["Receivers", "Silences", "Exporters", "Recording rules"],
    answer: [0, 2],
    explanation: "A Collector pipeline receives telemetry through receivers, optionally transforms it with processors, and sends it on through exporters. Silences belong to Alertmanager and recording rules belong to Prometheus.",
    choiceRationale: [
      "Correct: receivers accept telemetry into the Collector.",
      "Silences are an Alertmanager feature for muting alerts.",
      "Correct: exporters send telemetry to one or more backends.",
      "Recording rules are a Prometheus feature for precomputing queries."
    ],
    references: [R3.otel],
    tags: ["opentelemetry", "collector"]
  },
  // ---------------------------------------------------------------- cna-observability: prometheus-and-monitoring
  {
    id: "q-cna-observability-005",
    domain: "architecture",
    objective: "cna-observability",
    lessonId: "prometheus-and-monitoring",
    difficulty: 1,
    type: "single",
    prompt: "How does Prometheus collect metrics by default?",
    choices: [
      "Applications push metrics to Prometheus through a message queue.",
      "Node agents tail log files and convert each line into a metric.",
      "Prometheus periodically scrapes HTTP endpoints, such as `/metrics`, exposed by targets.",
      "The kubelet streams metrics into etcd, where Prometheus reads them."
    ],
    answer: [2],
    explanation: "Prometheus is pull-based: it discovers targets and scrapes their metrics endpoints on a schedule. Targets that do not expose metrics natively are covered by exporters, such as node_exporter for host metrics.",
    choiceRationale: [
      "Push is not the default model; Prometheus pulls from targets.",
      "Prometheus does not derive metrics from log lines.",
      "Correct: Prometheus scrapes HTTP metrics endpoints at regular intervals.",
      "etcd stores cluster state, not monitoring time series."
    ],
    references: [R3.prom],
    tags: ["prometheus", "pull-model", "scraping"]
  },
  {
    id: "q-cna-observability-006",
    domain: "architecture",
    objective: "cna-observability",
    lessonId: "prometheus-and-monitoring",
    difficulty: 2,
    type: "single",
    prompt: "A nightly batch job runs for 20 seconds and exits before Prometheus would scrape it. Which component lets the job publish its final metrics?",
    choices: ["Alertmanager", "Pushgateway", "node_exporter", "Grafana"],
    answer: [1],
    explanation: "Short-lived batch jobs may finish before a scrape happens. They can push their metrics to the Pushgateway, which keeps them and exposes them for Prometheus to scrape. It is intended for this narrow case, not as a general push pipeline.",
    choiceRationale: [
      "Alertmanager routes and deduplicates alerts; it does not hold metrics.",
      "Correct: the Pushgateway holds metrics from short-lived jobs for Prometheus to scrape.",
      "node_exporter exposes host metrics such as CPU and disk, not job results.",
      "Grafana visualizes data but does not collect it from jobs."
    ],
    references: [R3.pushing, R3.prom],
    tags: ["prometheus", "pushgateway", "batch-jobs"]
  },
  {
    id: "q-cna-observability-007",
    domain: "architecture",
    objective: "cna-observability",
    lessonId: "prometheus-and-monitoring",
    difficulty: 3,
    type: "single",
    prompt: "`http_requests_total` is a Prometheus counter. Which PromQL expression returns the per-second request rate averaged over the last 5 minutes?",
    choices: [
      "`http_requests_total[5m]`",
      "`sum(http_requests_total)`",
      "`avg_over_time(http_requests_total[5m])`",
      "`rate(http_requests_total[5m])`"
    ],
    answer: [3],
    explanation: "Counters only increase (except on reset), so their raw value is rarely useful. `rate()` takes a range vector and calculates the per-second increase, handling counter resets automatically.",
    choiceRationale: [
      "This returns raw samples in a range vector, not a rate.",
      "Summing a counter gives a running total, not requests per second.",
      "Averaging cumulative counter values does not produce a per-second rate.",
      "Correct: `rate()` computes the per-second increase over the 5-minute window."
    ],
    references: [R3.promql],
    tags: ["prometheus", "promql", "counter"]
  },
  // ---------------------------------------------------------------- cna-ecosystem: cloud-native-principles
  {
    id: "q-cna-ecosystem-001",
    domain: "architecture",
    objective: "cna-ecosystem",
    lessonId: "cloud-native-principles",
    difficulty: 1,
    type: "single",
    prompt: 'In the "pets vs cattle" analogy, which practice treats servers as cattle?',
    choices: [
      "Instances are interchangeable and are replaced from a template when they fail.",
      "Each server has a unique name and is repaired by hand when it breaks.",
      "Servers are kept in separate data centers to avoid shared failures.",
      "Workloads are pinned to specific bare-metal machines for stability."
    ],
    answer: [0],
    explanation: "Cattle are identical and disposable: when one fails, you replace it rather than nurse it back to health. Kubernetes applies this to Pods, which controllers recreate from a template instead of repairing.",
    choiceRationale: [
      "Correct: disposable, replaceable instances built from a template are cattle.",
      "Uniquely named, hand-repaired servers are pets.",
      "Spreading across data centers is about failure domains, not the pets vs cattle model.",
      "Pinning workloads to specific machines treats those machines as pets."
    ],
    references: [R3.glossary],
    tags: ["cloud-native", "immutable-infrastructure", "pets-vs-cattle"]
  },
  {
    id: "q-cna-ecosystem-002",
    domain: "architecture",
    objective: "cna-ecosystem",
    lessonId: "cloud-native-principles",
    difficulty: 2,
    type: "single",
    prompt: "A team builds a separate container image for dev, staging, and prod because each image has its database URL baked in. Which change best follows cloud-native and 12-factor practice?",
    choices: [
      "Keep separate images but tag them clearly with the environment name.",
      "Write the URL into the container filesystem after startup with a script.",
      "Build one immutable image and inject environment-specific config at deploy time, for example from a ConfigMap.",
      "Store the URL in the source code with an `if` statement per environment."
    ],
    answer: [2],
    explanation: "The 12-factor app stores config in the environment, separate from code. Building one artifact and promoting it unchanged through environments means production runs exactly what was tested, while ConfigMaps or Secrets provide per-environment values.",
    choiceRationale: [
      "Clear tags do not fix the core problem: each environment runs a different artifact.",
      "Writing config into the container at runtime is fragile and lost on restart.",
      "Correct: one immutable image plus deploy-time configuration separates config from code.",
      "Environment branches in code still couple config to the build."
    ],
    references: [R3.twelve],
    tags: ["12-factor", "configuration", "immutable-infrastructure"]
  },
  // ---------------------------------------------------------------- cna-ecosystem: autoscaling-and-serverless
  {
    id: "q-cna-ecosystem-003",
    domain: "architecture",
    objective: "cna-ecosystem",
    lessonId: "autoscaling-and-serverless",
    difficulty: 2,
    type: "single",
    prompt: "A worker Deployment should scale with the length of a message queue, including down to zero replicas when the queue is empty. Which project is designed for this?",
    choices: ["Vertical Pod Autoscaler", "KEDA", "Cluster Autoscaler", "kube-proxy"],
    answer: [1],
    explanation: "KEDA (Kubernetes Event-Driven Autoscaling) scales workloads based on external event sources such as queues and streams, and can scale to zero. It works alongside the HPA by feeding it external metrics.",
    choiceRationale: [
      "VPA changes CPU and memory requests of Pods, not replica count.",
      "Correct: KEDA scales on event sources and supports scaling to zero.",
      "Cluster Autoscaler changes the number of nodes, not Pod replicas.",
      "kube-proxy programs Service networking and does no scaling."
    ],
    references: [R3.keda, R3.hpa],
    tags: ["keda", "autoscaling", "event-driven"]
  },
  {
    id: "q-cna-ecosystem-004",
    domain: "architecture",
    objective: "cna-ecosystem",
    lessonId: "autoscaling-and-serverless",
    difficulty: 1,
    type: "single",
    prompt: "The HPA raised a Deployment to 20 replicas, but 6 new Pods are stuck `Pending` because no node has enough CPU. Which component can add nodes to the cluster?",
    choices: ["Cluster Autoscaler", "Horizontal Pod Autoscaler", "Vertical Pod Autoscaler", "kube-scheduler"],
    answer: [0],
    explanation: "The Cluster Autoscaler watches for Pods that cannot be scheduled due to insufficient resources and asks the cloud provider for more nodes. It also removes underused nodes. HPA and VPA operate on Pods, not nodes.",
    choiceRationale: [
      "Correct: Cluster Autoscaler adds nodes when Pods cannot be scheduled for lack of capacity.",
      "HPA already did its job by adding replicas; it cannot create nodes.",
      "VPA adjusts Pod resource requests, not node count.",
      "The scheduler places Pods on existing nodes but cannot create new ones."
    ],
    references: [R3.hpa, R3.components],
    tags: ["cluster-autoscaler", "autoscaling", "pending"]
  },
  {
    id: "q-cna-ecosystem-005",
    domain: "architecture",
    objective: "cna-ecosystem",
    lessonId: "autoscaling-and-serverless",
    difficulty: 3,
    type: "single",
    prompt: "An HPA targets 70% average CPU utilization. metrics-server is running, but the HPA shows the current value as `<unknown>`. The containers have no `resources.requests.cpu`. Why?",
    choices: [
      "The HPA can only scale on memory, never on CPU.",
      "The HPA works only when the Deployment uses the Recreate strategy.",
      "The HPA supports StatefulSets but not Deployments.",
      "Utilization is a percentage of the CPU request, so without requests there is nothing to compare against."
    ],
    answer: [3],
    explanation: "For resource utilization targets, the HPA divides current usage by the container request. If requests are missing, utilization cannot be computed and the HPA does not act. Setting CPU requests fixes this.",
    choiceRationale: [
      "CPU is the most common HPA metric; memory is optional.",
      "The rollout strategy has no effect on HPA metric calculation.",
      "The HPA works with Deployments, StatefulSets, and other scalable resources.",
      "Correct: utilization is measured relative to requests, which are missing here."
    ],
    references: [R3.hpa],
    tags: ["hpa", "autoscaling", "requests"]
  },
  // ---------------------------------------------------------------- cna-ecosystem: service-mesh-and-envoy
  {
    id: "q-cna-ecosystem-006",
    domain: "architecture",
    objective: "cna-ecosystem",
    lessonId: "service-mesh-and-envoy",
    difficulty: 1,
    type: "single",
    prompt: "In a sidecar-based service mesh, what does the proxy next to each application container do?",
    choices: [
      "It replaces kube-proxy and programs iptables for every Service on the node.",
      "It schedules the application Pod onto a suitable node.",
      "It stores the application configuration and secrets for the Pod.",
      "It intercepts the Pod's traffic to add features such as mTLS, retries, and telemetry without app code changes."
    ],
    answer: [3],
    explanation: "The sidecar proxy sits in the data path for the Pod's inbound and outbound traffic. A control plane configures all proxies, providing encryption, traffic policies, and consistent metrics without modifying application code.",
    choiceRationale: [
      "Service meshes run alongside kube-proxy; they do not replace Service routing on the node.",
      "Scheduling is done by the kube-scheduler.",
      "Configuration and secrets come from ConfigMaps and Secrets, not the proxy.",
      "Correct: the sidecar handles network concerns such as mTLS, retries, and telemetry transparently."
    ],
    references: [R3.istio, R3.linkerd],
    tags: ["service-mesh", "sidecar", "mtls"]
  },
  {
    id: "q-cna-ecosystem-007",
    domain: "architecture",
    objective: "cna-ecosystem",
    lessonId: "service-mesh-and-envoy",
    difficulty: 3,
    type: "multi",
    prompt: "Which statements about service mesh implementations are accurate? **Select TWO.**",
    choices: [
      "Linkerd uses Envoy as its data-plane proxy.",
      "Istio uses Envoy as its data-plane proxy.",
      "Istio ambient mode can secure traffic without injecting a sidecar into each Pod.",
      "Enabling mTLS in a mesh requires changing the TLS code in each application."
    ],
    answer: [1, 2],
    explanation: "Istio is built on Envoy, and its ambient mode moves L4 security into a per-node proxy (ztunnel) with optional waypoint proxies for L7, removing per-Pod sidecars. Linkerd uses its own lightweight Rust proxy rather than Envoy.",
    choiceRationale: [
      "Linkerd uses its own purpose-built proxy written in Rust, not Envoy.",
      "Correct: Envoy is the data-plane proxy in Istio.",
      "Correct: ambient mode provides mesh features without per-Pod sidecars.",
      "The mesh proxies handle mTLS transparently, so applications need no TLS changes."
    ],
    references: [R3.istio, R3.envoy, R3.linkerd],
    tags: ["istio", "envoy", "linkerd"]
  },
  // ---------------------------------------------------------------- cna-ecosystem: distributed-systems-basics
  {
    id: "q-cna-ecosystem-008",
    domain: "architecture",
    objective: "cna-ecosystem",
    lessonId: "distributed-systems-basics",
    difficulty: 2,
    type: "single",
    prompt: "An etcd cluster has 5 members using Raft consensus. How many members can fail while the cluster still accepts writes?",
    choices: ["1", "2", "3", "4"],
    answer: [1],
    explanation: "Raft needs a majority (quorum) of members to commit writes. With 5 members, quorum is 3, so 2 members can fail. This is why etcd clusters use odd sizes: 4 members also tolerate only 1 failure.",
    choiceRationale: [
      "One failure is the tolerance of a 3-member cluster.",
      "Correct: quorum for 5 members is 3, so 2 can be lost.",
      "Losing 3 of 5 leaves 2, which is not a majority.",
      "A single remaining member cannot form a majority of 5."
    ],
    references: [R3.raft, R3.etcd],
    tags: ["raft", "quorum", "etcd"]
  },
  {
    id: "q-cna-ecosystem-009",
    domain: "architecture",
    objective: "cna-ecosystem",
    lessonId: "distributed-systems-basics",
    difficulty: 1,
    type: "single",
    prompt: 'A client sends "set replicas to 5", times out without a reply, and sends the same request again. Applying it twice has the same result as applying it once. What is this property called?',
    choices: ["Eventual consistency", "Atomicity", "Idempotency", "Partition tolerance"],
    answer: [2],
    explanation: 'An idempotent operation produces the same result no matter how many times it is applied. Declarative "set to X" operations are idempotent, which makes retries safe, unlike "add 1 replica", which is not.',
    choiceRationale: [
      "Eventual consistency means replicas converge over time; it says nothing about repeated requests.",
      "Atomicity means an operation happens fully or not at all, not that repeats are harmless.",
      "Correct: repeating an idempotent request does not change the outcome.",
      "Partition tolerance is about continuing to operate when the network splits."
    ],
    references: [R3.glossary],
    tags: ["idempotency", "distributed-systems", "retries"]
  },
  // ---------------------------------------------------------------- cna-community: cncf-community-and-governance
  {
    id: "q-cna-community-001",
    domain: "architecture",
    objective: "cna-community",
    lessonId: "cncf-community-and-governance",
    difficulty: 1,
    type: "single",
    prompt: "What is the order of CNCF project maturity levels, from earliest to most mature?",
    choices: [
      "Incubating, Sandbox, Graduated",
      "Sandbox, Graduated, Incubating",
      "Graduated, Incubating, Sandbox",
      "Sandbox, Incubating, Graduated"
    ],
    answer: [3],
    explanation: "New CNCF projects usually enter at Sandbox, move to Incubating as adoption and governance mature, and reach Graduated once they show broad production use, a healthy contributor base, and a security audit.",
    choiceRationale: [
      "Sandbox is the entry level, so it comes before Incubating.",
      "Graduated is the final level and cannot come before Incubating.",
      "This is the reverse order.",
      "Correct: Sandbox, then Incubating, then Graduated."
    ],
    references: [R3.cncfProjects, R3.toc],
    tags: ["cncf", "maturity-levels"]
  },
  {
    id: "q-cna-community-002",
    domain: "architecture",
    objective: "cna-community",
    lessonId: "cncf-community-and-governance",
    difficulty: 2,
    type: "single",
    prompt: "What is a Kubernetes Enhancement Proposal (KEP) used for?",
    choices: [
      "Documenting the motivation, design, and graduation criteria of a significant change to Kubernetes.",
      "Reporting a bug in a specific Kubernetes release.",
      "Requesting that a project be accepted into the CNCF Sandbox.",
      "Applying for a seat on the Kubernetes Steering Committee."
    ],
    answer: [0],
    explanation: "KEPs describe significant features or process changes, including motivation, design, and alpha/beta/GA criteria. Each KEP is owned by a SIG and tracked in the kubernetes/enhancements repository.",
    choiceRationale: [
      "Correct: KEPs capture the design and lifecycle of significant enhancements.",
      "Bugs are reported as GitHub issues, not KEPs.",
      "Sandbox applications go to the CNCF TOC process, not the KEP process.",
      "Steering Committee seats are filled by community elections."
    ],
    references: [R3.keps, R3.community],
    tags: ["kep", "kubernetes", "governance"]
  },
  {
    id: "q-cna-community-003",
    domain: "architecture",
    objective: "cna-community",
    lessonId: "cncf-community-and-governance",
    difficulty: 2,
    type: "multi",
    prompt: "Which statements about CNCF governance are true? **Select TWO.**",
    choices: [
      "Graduated projects are maintained mainly by CNCF staff engineers.",
      "The CNCF is part of the Linux Foundation.",
      "The Technical Oversight Committee (TOC) votes on accepting projects and moving them between maturity levels.",
      "A project backed by a large vendor can enter directly at Graduated."
    ],
    answer: [1, 2],
    explanation: "The CNCF is a foundation under the Linux Foundation, and its TOC provides technical leadership, including decisions on project acceptance and maturity changes. Projects are maintained by their own contributor communities, and graduation is based on criteria, not sponsorship.",
    choiceRationale: [
      "Projects are maintained by their own community maintainers, often from many companies.",
      "Correct: the CNCF operates under the Linux Foundation.",
      "Correct: the TOC votes on project acceptance and maturity level changes.",
      "Graduation requires meeting defined criteria regardless of who backs the project."
    ],
    references: [R3.toc, R3.cncfProjects],
    tags: ["cncf", "toc", "governance"]
  },
  {
    id: "q-cna-community-004",
    domain: "architecture",
    objective: "cna-community",
    lessonId: "cncf-community-and-governance",
    difficulty: 3,
    type: "single",
    prompt: "A cluster switches its container runtime from containerd to CRI-O without any change to kubelet code. Which open standard makes this possible?",
    choices: [
      "CRI (Container Runtime Interface)",
      "OCI (Open Container Initiative) image specification",
      "CNI (Container Network Interface)",
      "CSI (Container Storage Interface)"
    ],
    answer: [0],
    explanation: "The kubelet talks to any runtime through the CRI gRPC API, so CRI-compatible runtimes such as containerd and CRI-O are interchangeable. OCI standardizes image and runtime formats underneath, while CNI and CSI cover networking and storage plugins.",
    choiceRationale: [
      "Correct: CRI is the interface between the kubelet and the container runtime.",
      "OCI defines image and low-level runtime formats, not how the kubelet calls a runtime.",
      "CNI standardizes Pod networking plugins.",
      "CSI standardizes storage drivers."
    ],
    references: [R3.components, R3.glossary],
    tags: ["cri", "open-standards", "container-runtime"]
  },
  {
    id: "q-cna-community-005",
    domain: "architecture",
    objective: "cna-community",
    lessonId: "cncf-community-and-governance",
    difficulty: 1,
    type: "single",
    prompt: "A new open source project has just been accepted into the CNCF. At which maturity level does a project normally enter?",
    choices: ["Graduated", "Incubating", "Sandbox", "Archived"],
    answer: [2],
    explanation: "Sandbox is the entry point for early-stage projects. Projects then move to Incubating and Graduated as they show adoption, a healthy contributor base and good governance. Archived is for projects that are no longer active.",
    choiceRationale: [
      "Graduated is the highest maturity level, reached only after meeting adoption and governance criteria.",
      "Incubating is the middle level; projects usually reach it after time in Sandbox.",
      "Correct: Sandbox is the entry level for new CNCF projects.",
      "Archived is for retired or inactive projects, not new ones."
    ],
    references: [R3.cncfProjects, R3.toc],
    tags: ["cncf", "maturity", "sandbox"]
  },
  {
    id: "q-cna-community-006",
    domain: "architecture",
    objective: "cna-community",
    lessonId: "cncf-community-and-governance",
    difficulty: 2,
    type: "single",
    prompt: "You want to propose a significant new feature for Kubernetes itself. What is the established process for designing and tracking such a change?",
    choices: [
      "Open a support ticket with the CNCF",
      "Write a Kubernetes Enhancement Proposal (KEP) with the owning SIG",
      "Submit the code directly to a cloud provider for inclusion in their distribution",
      "Ask the Technical Oversight Committee to vote on the pull request"
    ],
    answer: [1],
    explanation: "Significant Kubernetes changes go through a Kubernetes Enhancement Proposal (KEP), sponsored and reviewed by the Special Interest Group (SIG) that owns the area. KEPs track design, graduation stages (alpha, beta, stable) and release milestones.",
    choiceRationale: [
      "The CNCF does not triage Kubernetes feature requests through support tickets.",
      "Correct: KEPs are the design and tracking process, owned by the relevant SIG.",
      "Vendors ship distributions, but upstream features are designed in the open project.",
      "The TOC governs CNCF projects at a high level; it does not vote on individual Kubernetes pull requests."
    ],
    references: [{ title: "Kubernetes Enhancement Proposals", url: "https://github.com/kubernetes/enhancements" }, { title: "Kubernetes community and SIGs", url: "https://github.com/kubernetes/community" }],
    tags: ["kep", "sig", "community"]
  },
  {
    id: "q-cna-community-007",
    domain: "architecture",
    objective: "cna-community",
    lessonId: "cncf-community-and-governance",
    difficulty: 2,
    type: "single",
    prompt: "Which statement best describes a Kubernetes Special Interest Group (SIG)?",
    choices: [
      "A paid support tier offered by the Linux Foundation",
      "A vendor certification program for Kubernetes distributions",
      "An open community group that owns a specific area of the project, such as networking or storage",
      "A private committee that sets the price of CNCF certifications"
    ],
    answer: [2],
    explanation: "SIGs are open groups that own parts of Kubernetes (for example SIG Network, SIG Storage, SIG Node). Anyone can join their meetings and mailing lists; they review code, own KEPs and maintain their subprojects.",
    choiceRationale: [
      "SIGs are community groups, not commercial support offerings.",
      "Distribution conformance is a separate program (Certified Kubernetes), not a SIG.",
      "Correct: each SIG owns a specific area of the project and is open to anyone.",
      "SIGs are public and technical; they have nothing to do with certification pricing."
    ],
    references: [{ title: "Kubernetes community and SIGs", url: "https://github.com/kubernetes/community" }],
    tags: ["sig", "community", "governance"]
  },
  {
    id: "q-cna-community-008",
    domain: "architecture",
    objective: "cna-community",
    lessonId: "cncf-community-and-governance",
    difficulty: 2,
    type: "multi",
    prompt: "Which TWO interfaces are open standards that let Kubernetes use pluggable implementations? (Select TWO.)",
    choices: ["CNI for Pod networking", "kubeconfig for authentication", "CSI for storage drivers", "YAML for API objects"],
    answer: [0, 2],
    explanation: "The Container Network Interface (CNI) and Container Storage Interface (CSI) are open specifications that let different vendors plug networking and storage into Kubernetes without changing core code. Together with CRI and OCI they are the key cloud-native standards.",
    choiceRationale: [
      "Correct: CNI lets plugins such as Calico or Cilium provide Pod networking.",
      "kubeconfig is a client configuration file format, not a plugin interface.",
      "Correct: CSI lets storage vendors provide volume drivers out of tree.",
      "YAML is a serialization format, not a pluggability standard."
    ],
    references: [R3.glossary, { title: "Kubernetes storage: CSI", url: "https://kubernetes.io/docs/concepts/storage/volumes/" }],
    tags: ["cni", "csi", "open-standards"]
  },
  {
    id: "q-cna-observability-008",
    domain: "architecture",
    objective: "cna-observability",
    lessonId: "prometheus-and-monitoring",
    difficulty: 2,
    type: "single",
    prompt: "Prometheus fires an alert rule. Which component deduplicates, groups and routes that alert to a chat channel or pager?",
    choices: ["Grafana", "Alertmanager", "The Pushgateway", "kube-state-metrics"],
    answer: [1],
    explanation: "Prometheus evaluates alerting rules and sends firing alerts to Alertmanager, which handles deduplication, grouping, silencing, inhibition and routing to receivers such as email, chat or paging systems.",
    choiceRationale: [
      "Grafana visualizes data; it is not the component Prometheus sends alerts to.",
      "Correct: Alertmanager groups, deduplicates and routes alerts.",
      "The Pushgateway accepts metrics pushed by short-lived jobs; it does not route alerts.",
      "kube-state-metrics exposes metrics about Kubernetes objects; it does not handle alerts."
    ],
    references: [R3.prom, { title: "Prometheus Alertmanager", url: "https://prometheus.io/docs/alerting/latest/alertmanager/" }],
    tags: ["prometheus", "alertmanager", "alerting"]
  },
  {
    id: "q-cna-observability-009",
    domain: "architecture",
    objective: "cna-observability",
    lessonId: "observability-fundamentals",
    difficulty: 2,
    type: "single",
    prompt: "Users report that checkout is slow, but only sometimes. The request passes through five microservices. Which signal is designed to show where the time is spent across those services for a single request?",
    choices: ["A counter metric of total requests", "Distributed traces with spans per service", "Node CPU utilisation graphs", "Kubernetes Events"],
    answer: [1],
    explanation: "A distributed trace follows one request through every service, with a span per hop that records timing. That makes it the right tool to find which service adds latency; metrics show that latency is high, and logs explain what a single component did.",
    choiceRationale: [
      "A request counter tells you volume, not where time is spent within one request.",
      "Correct: traces break a single request into timed spans across services.",
      "Node CPU graphs are infrastructure metrics and cannot attribute latency to a service hop.",
      "Kubernetes Events describe object lifecycle changes, not request latency."
    ],
    references: [R3.otel],
    tags: ["tracing", "latency", "opentelemetry"]
  }
];

// ../../packages/content/src/flashcards.ts
var flashcards = [
  // Stage 0 — Foundations
  {
    id: "fc-001",
    lessonId: "linux-essentials",
    objective: "kf-containerization",
    front: "Which Linux kernel feature gives a container its own view of processes, network interfaces and mounts?",
    back: "**Namespaces.** Each namespace type (PID, network, mount, UTS, IPC, user, cgroup) isolates one kind of system resource view."
  },
  {
    id: "fc-002",
    lessonId: "linux-essentials",
    objective: "kf-containerization",
    front: "What do **cgroups** (control groups) do for containers?",
    back: "They limit and account for the CPU, memory and I/O used by a group of processes. Kubernetes resource limits are enforced through cgroups on the node."
  },
  {
    id: "fc-003",
    lessonId: "linux-essentials",
    objective: "kf-containerization",
    front: "Which signal does a container's main process receive first when Kubernetes terminates a Pod?",
    back: "`SIGTERM`. If the process is still running after the grace period (30 seconds by default), it receives `SIGKILL`."
  },
  {
    id: "fc-004",
    lessonId: "networking-fundamentals",
    objective: "co-networking",
    front: "What job does DNS do, and which component does it in a Kubernetes cluster?",
    back: "DNS translates names into IP addresses. In Kubernetes, CoreDNS resolves Service names to their cluster IPs."
  },
  {
    id: "fc-005",
    lessonId: "networking-fundamentals",
    objective: "co-networking",
    front: "TCP vs UDP in one sentence each.",
    back: "TCP is connection-oriented and delivers bytes reliably and in order. UDP is connectionless and gives no delivery or ordering guarantee, trading reliability for low overhead."
  },
  {
    id: "fc-006",
    lessonId: "networking-fundamentals",
    objective: "co-networking",
    front: "What is NAT, and where does Kubernetes use it?",
    back: "Network Address Translation rewrites a packet's source or destination address. kube-proxy uses destination NAT to send traffic for a Service's virtual IP to a real Pod IP."
  },
  {
    id: "fc-007",
    lessonId: "virtualization-and-containers",
    objective: "kf-containerization",
    front: "What is the key isolation difference between a VM and a container?",
    back: "A VM runs its own guest kernel on a hypervisor. Containers share the host kernel and are isolated with namespaces and cgroups."
  },
  {
    id: "fc-008",
    lessonId: "virtualization-and-containers",
    objective: "kf-containerization",
    front: "Why does a container usually start in well under a second while a VM takes much longer?",
    back: "Starting a container is starting an isolated process on an already-running kernel. A VM has to boot a whole operating system first."
  },
  {
    id: "fc-009",
    lessonId: "container-images-and-oci",
    objective: "kf-containerization",
    front: "Name the three OCI specifications.",
    back: "The **runtime spec** (how to run a container), the **image spec** (image format) and the **distribution spec** (how registries serve images)."
  },
  {
    id: "fc-010",
    lessonId: "container-images-and-oci",
    objective: "kf-containerization",
    front: "Image tag vs image digest",
    back: "A tag such as `nginx:1.27` is a movable label that can be re-pointed. A digest such as `nginx@sha256:...` is a content hash, so it always refers to exactly the same image."
  },
  {
    id: "fc-011",
    lessonId: "container-images-and-oci",
    objective: "kf-containerization",
    front: "What is an image layer?",
    back: "A read-only filesystem diff, typically produced by a Dockerfile instruction that changes files. Layers are cached and shared between images, and a running container adds one thin writable layer on top."
  },
  {
    id: "fc-012",
    lessonId: "yaml-for-kubernetes",
    objective: "kf-core",
    front: "Which four top-level fields does almost every Kubernetes manifest you write contain?",
    back: "`apiVersion`, `kind`, `metadata` and `spec`. The `status` field is filled in by the system, not by you."
  },
  {
    id: "fc-013",
    lessonId: "yaml-for-kubernetes",
    objective: "kf-core",
    front: "`spec` vs `status` in a Kubernetes object",
    back: "`spec` is the desired state you declare. `status` is the observed state that controllers and the kubelet report back."
  },
  {
    id: "fc-014",
    lessonId: "distributed-systems-basics",
    objective: "cna-ecosystem",
    front: "Which consensus algorithm does etcd use?",
    back: "**Raft.** A write is committed only when a majority (quorum) of members has accepted it."
  },
  {
    id: "fc-015",
    lessonId: "distributed-systems-basics",
    objective: "cna-ecosystem",
    front: "Why do etcd clusters use 3 or 5 members rather than 4?",
    back: "Quorum is a majority, floor(n/2)+1. Three members tolerate one failure and four still only tolerate one, so the even member adds cost without adding fault tolerance. Five tolerate two."
  },
  // Stage 1 — Architecture
  {
    id: "fc-016",
    lessonId: "cluster-architecture",
    objective: "kf-core",
    front: "List the control plane components.",
    back: "kube-apiserver, etcd, kube-scheduler and kube-controller-manager, plus cloud-controller-manager when running on a cloud provider."
  },
  {
    id: "fc-017",
    lessonId: "cluster-architecture",
    objective: "kf-core",
    front: "Which components run on every worker node?",
    back: "The kubelet, a container runtime such as containerd or CRI-O, and usually kube-proxy (some CNI plugins replace it)."
  },
  {
    id: "fc-018",
    lessonId: "cluster-architecture",
    objective: "kf-core",
    front: "Which single component do all other components and clients talk to?",
    back: "The **kube-apiserver**. The scheduler, controllers, kubelets and kubectl all go through it; only the API server talks to etcd."
  },
  {
    id: "fc-019",
    lessonId: "api-server-and-etcd",
    objective: "kf-core",
    front: "In what order does the API server process a write request?",
    back: "Authentication, then authorization, then admission control (mutating, then validating), and finally the object is persisted to etcd."
  },
  {
    id: "fc-020",
    lessonId: "api-server-and-etcd",
    objective: "kf-core",
    front: "What is etcd's role in a cluster?",
    back: "It is the consistent, distributed key-value store that holds all cluster state and API objects. Losing etcd without a backup means losing the cluster's state."
  },
  {
    id: "fc-021",
    lessonId: "api-server-and-etcd",
    objective: "kf-core",
    front: "Mutating vs validating admission",
    back: "Mutating admission may change the incoming object (for example, inject defaults). Validating admission can only accept or reject it, and runs after mutation."
  },
  {
    id: "fc-022",
    lessonId: "control-plane-controllers",
    objective: "kf-scheduling",
    front: "What exactly does kube-scheduler do?",
    back: "It picks a node for each Pod that has no node assigned and records that choice by binding the Pod. It does not start containers; the kubelet on the chosen node does."
  },
  {
    id: "fc-023",
    lessonId: "control-plane-controllers",
    objective: "kf-core",
    front: "What is kube-controller-manager?",
    back: "A single binary that runs the built-in controllers, such as the Deployment, ReplicaSet, Node, Job and EndpointSlice controllers."
  },
  {
    id: "fc-024",
    lessonId: "control-plane-controllers",
    objective: "kf-core",
    front: "What does the cloud-controller-manager handle?",
    back: "Cloud-specific control logic: node lifecycle checks against the cloud, routes, and provisioning cloud load balancers for `type: LoadBalancer` Services."
  },
  {
    id: "fc-025",
    lessonId: "node-components",
    objective: "kf-core",
    front: "What does the kubelet do?",
    back: "It is the agent on every node. It makes sure the containers in Pods assigned to its node are running and healthy, runs probes, and reports Pod and node status to the API server."
  },
  {
    id: "fc-026",
    lessonId: "node-components",
    objective: "kf-containerization",
    front: "CRI",
    back: "The **Container Runtime Interface**, a gRPC API between the kubelet and the container runtime. containerd and CRI-O implement it."
  },
  {
    id: "fc-027",
    lessonId: "node-components",
    objective: "kf-containerization",
    front: "In which Kubernetes version was dockershim removed, and do Docker-built images still run?",
    back: "Kubernetes 1.24. Images built with Docker are standard OCI images, so they still run on containerd or CRI-O."
  },
  {
    id: "fc-028",
    lessonId: "declarative-reconciliation",
    objective: "kf-core",
    front: "What is a control loop (reconciliation loop)?",
    back: "A controller repeatedly observes the actual state, compares it with the desired state and acts to close the gap. It never finishes; it keeps converging."
  },
  {
    id: "fc-029",
    lessonId: "declarative-reconciliation",
    objective: "kf-core",
    front: "Imperative vs declarative management",
    back: "Imperative: you issue commands such as `kubectl create` or `kubectl scale`. Declarative: you keep the desired state in files and run `kubectl apply`, and Kubernetes works out the changes."
  },
  {
    id: "fc-030",
    lessonId: "declarative-reconciliation",
    objective: "kf-core",
    front: "You delete a Pod that belongs to a ReplicaSet with `replicas: 3`. What happens?",
    back: "The ReplicaSet controller sees only 2 matching Pods and creates a replacement to get back to 3."
  },
  // Stage 2 — Workloads
  {
    id: "fc-031",
    lessonId: "pods",
    objective: "kf-core",
    front: "What is a Pod?",
    back: "The smallest deployable unit in Kubernetes: one or more containers that are scheduled together, share one network namespace (one IP) and can share volumes."
  },
  {
    id: "fc-032",
    lessonId: "pods",
    objective: "kf-core",
    front: "Init containers",
    back: "Containers that run one after another, each to completion, before the app containers start. They are used for setup steps such as waiting for a dependency."
  },
  {
    id: "fc-033",
    lessonId: "pods",
    objective: "kf-core",
    front: "How is a native sidecar container declared?",
    back: "As an init container with `restartPolicy: Always`. It starts before the app containers and keeps running alongside them. The feature is stable as of Kubernetes 1.33."
  },
  {
    id: "fc-034",
    lessonId: "replicasets-and-deployments",
    objective: "kf-core",
    front: "What does a Deployment manage directly?",
    back: "ReplicaSets. The ReplicaSets in turn manage Pods: Deployment \u2192 ReplicaSet \u2192 Pods."
  },
  {
    id: "fc-035",
    lessonId: "replicasets-and-deployments",
    objective: "kf-core",
    front: "Which Deployment change creates a new ReplicaSet?",
    back: "A change to the Pod template (`spec.template`), such as a new image. Changing only `replicas` scales the existing ReplicaSet."
  },
  {
    id: "fc-036",
    lessonId: "replicasets-and-deployments",
    objective: "kf-core",
    front: "How does a ReplicaSet decide which Pods belong to it?",
    back: "Through its label selector. Pods it adopts or creates also carry an `ownerReferences` entry pointing to it."
  },
  {
    id: "fc-037",
    lessonId: "namespaces-labels-selectors",
    objective: "kf-core",
    front: "Labels vs annotations",
    back: "Labels are identifying key/value pairs that selectors can match. Annotations hold non-identifying metadata for tools and people, and cannot be used in selectors."
  },
  {
    id: "fc-038",
    lessonId: "namespaces-labels-selectors",
    objective: "kf-admin",
    front: "Name some resources that are NOT namespaced.",
    back: "Nodes, PersistentVolumes, StorageClasses, ClusterRoles, ClusterRoleBindings and Namespaces themselves. `kubectl api-resources --namespaced=false` lists them all."
  },
  {
    id: "fc-039",
    lessonId: "jobs-and-cronjobs",
    objective: "kf-core",
    front: "Job vs Deployment",
    back: "A Job runs Pods until a set number complete successfully, then stops. A Deployment keeps long-running Pods alive indefinitely."
  },
  {
    id: "fc-040",
    lessonId: "jobs-and-cronjobs",
    objective: "kf-core",
    front: "What does a CronJob create?",
    back: "A new **Job** on each run of its cron-format `schedule`. The Job then creates the Pods."
  },
  {
    id: "fc-041",
    lessonId: "daemonsets-and-statefulsets",
    objective: "kf-core",
    front: "DaemonSet",
    back: "Runs one copy of a Pod on every eligible node, adding Pods as nodes join. It is typical for log collectors, node monitoring agents and CNI agents."
  },
  {
    id: "fc-042",
    lessonId: "daemonsets-and-statefulsets",
    objective: "kf-core",
    front: "What does a StatefulSet guarantee that a Deployment does not?",
    back: "Stable, ordinal Pod names (`db-0`, `db-1`), stable per-Pod storage from `volumeClaimTemplates`, and ordered creation, scaling and updates by default."
  },
  {
    id: "fc-043",
    lessonId: "daemonsets-and-statefulsets",
    objective: "kf-core",
    front: "Which kind of Service gives each StatefulSet Pod its own DNS name?",
    back: "A **headless Service** (`clusterIP: None`) named in the StatefulSet's `serviceName`."
  },
  {
    id: "fc-044",
    lessonId: "resources-requests-limits",
    objective: "kf-scheduling",
    front: "Resource request vs limit",
    back: "The scheduler places Pods using **requests** (reserved capacity). **Limits** are the runtime caps enforced on the node."
  },
  {
    id: "fc-045",
    lessonId: "resources-requests-limits",
    objective: "kf-scheduling",
    front: "What happens when a container exceeds its memory limit, and when it exceeds its CPU limit?",
    back: "Exceeding the memory limit gets the container killed (`OOMKilled`). Exceeding the CPU limit only gets it throttled."
  },
  {
    id: "fc-046",
    lessonId: "resources-requests-limits",
    objective: "kf-scheduling",
    front: "Name the three Pod QoS classes.",
    back: "**Guaranteed** (every container sets CPU and memory requests equal to limits), **Burstable** (some requests or limits set) and **BestEffort** (none set). BestEffort Pods are evicted first under node pressure."
  },
  {
    id: "fc-047",
    lessonId: "health-probes",
    objective: "kf-core",
    front: "What does the kubelet do when a liveness probe keeps failing?",
    back: "It restarts the container (subject to the Pod's `restartPolicy`)."
  },
  {
    id: "fc-048",
    lessonId: "health-probes",
    objective: "co-troubleshooting",
    front: "What happens when a readiness probe fails?",
    back: "The Pod is marked not ready and removed from Service endpoints, so it stops receiving traffic. The container is **not** restarted."
  },
  {
    id: "fc-049",
    lessonId: "health-probes",
    objective: "kf-core",
    front: "Why use a startup probe?",
    back: "For slow-starting apps. Liveness and readiness checks are held off until the startup probe succeeds, so the container is not killed while it is still booting."
  },
  {
    id: "fc-050",
    lessonId: "scheduling-placement",
    objective: "kf-scheduling",
    front: "What are the two phases the scheduler uses to choose a node?",
    back: "**Filtering** removes nodes that cannot run the Pod. **Scoring** ranks the remaining nodes, and the highest score wins."
  },
  {
    id: "fc-051",
    lessonId: "scheduling-placement",
    objective: "kf-scheduling",
    front: "Taints vs tolerations",
    back: "A taint on a node repels Pods. A toleration on a Pod lets it be scheduled onto a matching taint but does not attract it there; use node affinity for that."
  },
  {
    id: "fc-052",
    lessonId: "scheduling-placement",
    objective: "kf-scheduling",
    front: "nodeSelector vs node affinity",
    back: "`nodeSelector` requires exact label matches. Node affinity supports operators such as `In` and `NotIn`, and both required and preferred rules."
  },
  // Stage 3 — Networking
  {
    id: "fc-053",
    lessonId: "pod-networking-and-cni",
    objective: "co-networking",
    front: "State the core rule of the Kubernetes network model.",
    back: "Every Pod gets its own IP address, and all Pods can reach all other Pods across nodes without NAT."
  },
  {
    id: "fc-054",
    lessonId: "pod-networking-and-cni",
    objective: "co-networking",
    front: "CNI",
    back: "The **Container Network Interface**: a specification and set of plugins that attach Pods to the network and assign their IPs. Kubernetes does not implement Pod networking itself."
  },
  {
    id: "fc-055",
    lessonId: "pod-networking-and-cni",
    objective: "co-networking",
    front: "Name three CNI plugins.",
    back: "Calico, Cilium (built on eBPF) and Flannel."
  },
  {
    id: "fc-056",
    lessonId: "services",
    objective: "co-networking",
    front: "What is the default Service type?",
    back: "**ClusterIP**: a stable virtual IP that can only be reached from inside the cluster."
  },
  {
    id: "fc-057",
    lessonId: "services",
    objective: "co-networking",
    front: "What is the default NodePort range?",
    back: "30000\u201332767. A NodePort Service opens the same port on every node."
  },
  {
    id: "fc-058",
    lessonId: "services",
    objective: "co-networking",
    front: "Headless Service",
    back: "A Service with `clusterIP: None`. It has no virtual IP; DNS returns the IPs of the ready Pods directly."
  },
  {
    id: "fc-059",
    lessonId: "dns-and-coredns",
    objective: "co-networking",
    front: "What is the fully qualified DNS name of Service `api` in namespace `shop`?",
    back: "`api.shop.svc.cluster.local`, assuming the default cluster domain `cluster.local`. From inside `shop`, plain `api` also works."
  },
  {
    id: "fc-060",
    lessonId: "dns-and-coredns",
    objective: "co-networking",
    front: "CoreDNS",
    back: "The default cluster DNS server, normally run as a Deployment in `kube-system`. It is a graduated CNCF project."
  },
  {
    id: "fc-061",
    lessonId: "ingress-and-gateway-api",
    objective: "co-networking",
    front: "You create an Ingress object but nothing routes. What is most likely missing?",
    back: "An **Ingress controller**, such as ingress-nginx or Traefik. The Ingress resource is only configuration; a controller has to act on it."
  },
  {
    id: "fc-062",
    lessonId: "ingress-and-gateway-api",
    objective: "co-networking",
    front: "Which Gateway API resources map to which roles?",
    back: "**GatewayClass**: infrastructure provider. **Gateway**: cluster operator. **HTTPRoute** (and other Routes): application developer."
  },
  {
    id: "fc-063",
    lessonId: "ingress-and-gateway-api",
    objective: "co-networking",
    front: "What is the status of the Ingress API?",
    back: "It is stable but frozen, so it receives no new features. New traffic-routing features go into Gateway API, which reached GA (v1.0) in October 2023."
  },
  {
    id: "fc-064",
    lessonId: "network-policies",
    objective: "co-networking",
    front: "With no NetworkPolicies in a namespace, what traffic is allowed?",
    back: "All of it. Pods are non-isolated by default."
  },
  {
    id: "fc-065",
    lessonId: "network-policies",
    objective: "co-networking",
    front: "Which component actually enforces NetworkPolicies?",
    back: "The CNI plugin. If the plugin does not support NetworkPolicy, policies are accepted by the API but have no effect."
  },
  {
    id: "fc-066",
    lessonId: "network-policies",
    objective: "co-security",
    front: "A Pod is selected by a NetworkPolicy with `policyTypes: [Ingress]`. What happens to ingress traffic?",
    back: "The Pod becomes isolated for ingress: only traffic matched by an allow rule in some policy is accepted. Policies only add allows; there are no deny rules."
  },
  // Stage 4 — Configuration & Storage
  {
    id: "fc-067",
    lessonId: "configmaps-and-secrets",
    objective: "kf-core",
    front: "ConfigMap",
    back: "An API object holding non-confidential key/value configuration. It lets you change configuration without rebuilding the image."
  },
  {
    id: "fc-068",
    lessonId: "configmaps-and-secrets",
    objective: "co-security",
    front: "Are Secrets encrypted by default?",
    back: "No. Secret values are only base64-encoded and are stored unencrypted in etcd unless encryption at rest is configured. Restrict access to them with RBAC."
  },
  {
    id: "fc-069",
    lessonId: "configmaps-and-secrets",
    objective: "kf-core",
    front: "You update a ConfigMap. Which consumers see the change without a restart?",
    back: "Files from a mounted ConfigMap volume update eventually (except `subPath` mounts). Environment variables do not change until the container restarts."
  },
  {
    id: "fc-070",
    lessonId: "volumes",
    objective: "co-storage",
    front: "How long does an `emptyDir` volume live?",
    back: "It is created when the Pod is assigned to a node and deleted when the Pod is removed. It survives container restarts within the Pod."
  },
  {
    id: "fc-071",
    lessonId: "volumes",
    objective: "co-storage",
    front: "Why is `hostPath` considered risky?",
    back: "It mounts the node's own filesystem into the Pod. That can expose sensitive host files, and the data stays on one specific node."
  },
  {
    id: "fc-072",
    lessonId: "volumes",
    objective: "co-storage",
    front: "Ephemeral vs persistent volumes",
    back: "Ephemeral volumes (emptyDir, configMap, secret) live and die with the Pod. Persistent volumes (PVs claimed through PVCs) keep their data after the Pod is gone."
  },
  {
    id: "fc-073",
    lessonId: "persistent-volumes-and-csi",
    objective: "co-storage",
    front: "PersistentVolume vs PersistentVolumeClaim",
    back: "A PV is a piece of storage in the cluster (cluster-scoped). A PVC is a namespaced request for storage that binds to a matching PV."
  },
  {
    id: "fc-074",
    lessonId: "persistent-volumes-and-csi",
    objective: "co-storage",
    front: "What does a StorageClass enable?",
    back: "**Dynamic provisioning.** A PVC that names a StorageClass makes its provisioner create a matching PV on demand."
  },
  {
    id: "fc-075",
    lessonId: "persistent-volumes-and-csi",
    objective: "co-storage",
    front: "List the four PV access modes.",
    back: "ReadWriteOnce (RWO, one node), ReadOnlyMany (ROX), ReadWriteMany (RWX) and ReadWriteOncePod (RWOP, a single Pod)."
  },
  {
    id: "fc-076",
    lessonId: "persistent-volumes-and-csi",
    objective: "co-storage",
    front: "CSI",
    back: "The **Container Storage Interface**: a standard that lets storage vendors ship drivers outside the Kubernetes codebase."
  },
  // Stage 5 — Security & Operations
  {
    id: "fc-077",
    lessonId: "authentication-authorization-rbac",
    objective: "co-security",
    front: "Role vs ClusterRole",
    back: "A Role grants permissions inside one namespace. A ClusterRole is cluster-scoped and can cover cluster-scoped resources, or be reused across namespaces through RoleBindings."
  },
  {
    id: "fc-078",
    lessonId: "authentication-authorization-rbac",
    objective: "co-security",
    front: "Does Kubernetes store user accounts as API objects?",
    back: "No. Human users are authenticated externally (client certificates, OIDC and so on). ServiceAccounts are the API objects that represent workload identities."
  },
  {
    id: "fc-079",
    lessonId: "authentication-authorization-rbac",
    objective: "co-security",
    front: "Can an RBAC rule deny an action?",
    back: "No. RBAC is purely additive: permissions are unions of allow rules, and anything not allowed is denied."
  },
  {
    id: "fc-080",
    lessonId: "pod-security-and-least-privilege",
    objective: "co-security",
    front: "What replaced PodSecurityPolicy, and when was PSP removed?",
    back: "**Pod Security Admission**, a built-in admission controller that enforces the Pod Security Standards. PSP was removed in Kubernetes 1.25."
  },
  {
    id: "fc-081",
    lessonId: "pod-security-and-least-privilege",
    objective: "co-security",
    front: "Name the three Pod Security Standards levels.",
    back: "**Privileged** (unrestricted), **Baseline** (blocks known privilege escalations) and **Restricted** (follows hardening best practices)."
  },
  {
    id: "fc-082",
    lessonId: "pod-security-and-least-privilege",
    objective: "co-security",
    front: "What does `runAsNonRoot: true` in a securityContext do?",
    back: "The kubelet refuses to start the container if it would run as UID 0 (root)."
  },
  {
    id: "fc-083",
    lessonId: "kubectl-and-cluster-administration",
    objective: "kf-admin",
    front: "What is a kubeconfig context?",
    back: "A named combination of cluster, user and default namespace. `kubectl config use-context <name>` switches between them."
  },
  {
    id: "fc-084",
    lessonId: "kubectl-and-cluster-administration",
    objective: "kf-admin",
    front: "CRD vs operator",
    back: "A CustomResourceDefinition adds a new resource type to the API. An operator is a custom controller that reconciles those custom resources, encoding the operational knowledge for an application."
  },
  {
    id: "fc-085",
    lessonId: "kubectl-and-cluster-administration",
    objective: "kf-admin",
    front: "What is kubeadm for?",
    back: "Bootstrapping and upgrading clusters: `kubeadm init` sets up a control plane, and `kubeadm join` adds nodes."
  },
  {
    id: "fc-086",
    lessonId: "troubleshooting-workloads",
    objective: "co-troubleshooting",
    front: "A Pod is stuck in `Pending`. What are the usual causes?",
    back: "It cannot be scheduled. Common reasons are insufficient CPU or memory, unmatched nodeSelector or affinity rules, untolerated taints, or an unbound PVC. Look at the Events section of `kubectl describe pod`."
  },
  {
    id: "fc-087",
    lessonId: "troubleshooting-workloads",
    objective: "co-troubleshooting",
    front: "`ImagePullBackOff`: what are the usual causes?",
    back: "A wrong image name or tag, missing registry credentials (imagePullSecrets) or an unreachable registry. The kubelet keeps retrying with growing delays."
  },
  {
    id: "fc-088",
    lessonId: "troubleshooting-workloads",
    objective: "co-troubleshooting",
    front: "`CrashLoopBackOff`: what does it mean, and what should you check first?",
    back: "The container keeps exiting and the kubelet waits longer before each restart. Check `kubectl logs <pod> --previous` and the exit code in `kubectl describe pod`."
  },
  // Stage 6 — Application Delivery
  {
    id: "fc-089",
    lessonId: "cicd-and-gitops",
    objective: "cad-delivery",
    front: "What are the four OpenGitOps principles?",
    back: "Declarative, Versioned and Immutable, Pulled Automatically, and Continuously Reconciled."
  },
  {
    id: "fc-090",
    lessonId: "cicd-and-gitops",
    objective: "cad-delivery",
    front: "Push-based vs pull-based deployment",
    back: "Push: a CI pipeline holding cluster credentials runs the deployment. Pull (GitOps): an agent inside the cluster, such as Argo CD or Flux, pulls from Git and reconciles."
  },
  {
    id: "fc-091",
    lessonId: "cicd-and-gitops",
    objective: "cad-delivery",
    front: "CI vs CD",
    back: "Continuous Integration builds and tests every change merged into a shared branch. Continuous Delivery/Deployment automatically gets the tested artifact released to environments."
  },
  {
    id: "fc-092",
    lessonId: "helm-and-kustomize",
    objective: "cad-delivery",
    front: "Helm chart vs Helm release",
    back: "A chart is a package of templated Kubernetes manifests plus default `values.yaml`. A release is one installed instance of a chart in a cluster."
  },
  {
    id: "fc-093",
    lessonId: "helm-and-kustomize",
    objective: "cad-delivery",
    front: "How does Kustomize differ from Helm?",
    back: "Kustomize uses no templates. It patches plain YAML bases with overlays, and it is built into kubectl (`kubectl apply -k`)."
  },
  {
    id: "fc-094",
    lessonId: "rollouts-and-deployment-strategies",
    objective: "cad-delivery",
    front: "Which two strategies does a Deployment support natively?",
    back: "**RollingUpdate** (the default) and **Recreate**, which deletes all old Pods before creating new ones. `kubectl rollout undo` rolls back to the previous revision."
  },
  {
    id: "fc-095",
    lessonId: "rollouts-and-deployment-strategies",
    objective: "cad-delivery",
    front: "What are the default `maxSurge` and `maxUnavailable` values?",
    back: "25% each. maxSurge is how many extra Pods may exist during the update; maxUnavailable is how many may be unavailable."
  },
  {
    id: "fc-096",
    lessonId: "rollouts-and-deployment-strategies",
    objective: "cad-delivery",
    front: "Canary vs blue/green",
    back: "Canary sends a small, gradually growing share of traffic to the new version. Blue/green runs two full environments and switches all traffic at once."
  },
  {
    id: "fc-097",
    lessonId: "debugging-applications",
    objective: "cad-debugging",
    front: "What does `kubectl logs <pod> --previous` show?",
    back: "The logs of the previous, terminated instance of the container, which you need after a crash and restart."
  },
  {
    id: "fc-098",
    lessonId: "debugging-applications",
    objective: "cad-debugging",
    front: "Ephemeral containers",
    back: "Temporary containers that `kubectl debug` adds to a running Pod for troubleshooting. They are useful when the image is distroless and has no shell."
  },
  // Stage 7 — Cloud Native Architecture
  {
    id: "fc-099",
    lessonId: "cloud-native-principles",
    objective: "cna-ecosystem",
    front: "Immutable infrastructure",
    back: "Servers and containers are never patched in place. To change something you build a new version and replace the old one."
  },
  {
    id: "fc-100",
    lessonId: "cloud-native-principles",
    objective: "cna-ecosystem",
    front: "Pets vs cattle",
    back: "Pets are unique, hand-tended servers that are nursed back to health. Cattle are identical and disposable, so a broken one is simply replaced. Cloud native treats infrastructure as cattle."
  },
  {
    id: "fc-101",
    lessonId: "cloud-native-principles",
    objective: "cna-ecosystem",
    front: "Where does a twelve-factor app keep its configuration?",
    back: "In the environment, kept separate from the code, so the same build can run in every environment."
  },
  {
    id: "fc-102",
    lessonId: "autoscaling-and-serverless",
    objective: "cna-ecosystem",
    front: "HPA vs VPA vs Cluster Autoscaler",
    back: "HPA changes the **number of Pods**. VPA changes a Pod's **CPU/memory requests**. Cluster Autoscaler changes the **number of nodes**."
  },
  {
    id: "fc-103",
    lessonId: "autoscaling-and-serverless",
    objective: "cna-ecosystem",
    front: "KEDA",
    back: "Kubernetes Event-driven Autoscaling: it scales workloads based on event sources such as queue length, and can scale to zero. It is a graduated CNCF project."
  },
  {
    id: "fc-104",
    lessonId: "observability-fundamentals",
    objective: "cna-observability",
    front: "SLI vs SLO vs SLA",
    back: "An SLI is a measured indicator (for example, the success rate). An SLO is the internal target for it (99.9%). An SLA is a contract with customers that carries consequences if it is missed."
  },
  {
    id: "fc-105",
    lessonId: "observability-fundamentals",
    objective: "cna-observability",
    front: "What is OpenTelemetry?",
    back: "A vendor-neutral CNCF standard of APIs, SDKs and the Collector for producing and exporting traces, metrics and logs. It is not a storage backend."
  },
  {
    id: "fc-106",
    lessonId: "prometheus-and-monitoring",
    objective: "cna-observability",
    front: "How does Prometheus collect metrics?",
    back: "By **pulling**: it periodically scrapes HTTP endpoints (usually `/metrics`) on targets and stores the samples as time series."
  },
  {
    id: "fc-107",
    lessonId: "prometheus-and-monitoring",
    objective: "cna-observability",
    front: "What does Alertmanager do?",
    back: "It receives alerts fired by Prometheus, then deduplicates, groups and silences them and routes them to receivers such as email, Slack or a pager."
  },
  {
    id: "fc-108",
    lessonId: "service-mesh-and-envoy",
    objective: "cna-ecosystem",
    front: "What does a service mesh add to service-to-service traffic?",
    back: "Mutual TLS, retries and timeouts, traffic splitting and per-request telemetry, without changing application code. It is implemented by proxies (sidecar or node-level) under a control plane."
  },
  {
    id: "fc-109",
    lessonId: "cncf-community-and-governance",
    objective: "cna-community",
    front: "What are the CNCF project maturity levels, in order?",
    back: "Sandbox, then Incubating, then Graduated. The Technical Oversight Committee (TOC) votes on moves between levels."
  },
  {
    id: "fc-110",
    lessonId: "cncf-community-and-governance",
    objective: "cna-community",
    front: "KEP",
    back: "A **Kubernetes Enhancement Proposal**: the design document and tracking process for significant Kubernetes changes, owned by a SIG."
  }
];

// ../../packages/content/src/glossary.ts
var glossary = [
  {
    term: "Admission controller",
    objective: "co-security",
    lessonId: "api-server-and-etcd",
    definition: "Code in the API server that intercepts requests after authentication and authorization but before the object is persisted. Mutating admission can modify objects; validating admission can only accept or reject them.",
    related: ["kube-apiserver", "Pod Security Admission", "OPA (Open Policy Agent)", "Kyverno"]
  },
  {
    term: "Alertmanager",
    objective: "cna-observability",
    lessonId: "prometheus-and-monitoring",
    definition: "The Prometheus component that receives alerts, deduplicates, groups and silences them, and routes notifications to receivers such as email, chat or paging systems.",
    related: ["Prometheus", "PromQL"]
  },
  {
    term: "Annotation",
    objective: "kf-core",
    lessonId: "namespaces-labels-selectors",
    definition: "Non-identifying key/value metadata attached to an object, used by tools and humans (build info, controller hints). Annotations cannot be used in selectors.",
    related: ["Label"]
  },
  {
    term: "Argo CD",
    objective: "cad-delivery",
    lessonId: "cicd-and-gitops",
    definition: "A declarative GitOps continuous delivery tool for Kubernetes, part of the graduated CNCF Argo project. It runs in the cluster, compares live state with Git and syncs differences.",
    related: ["GitOps", "Flux", "Helm", "Kustomize"]
  },
  {
    term: "Backstage",
    objective: "cna-community",
    lessonId: "cncf-community-and-governance",
    definition: "A CNCF framework for building internal developer portals: a software catalog, templates and documentation in one place. A common building block for platform engineering teams.",
    related: ["Crossplane"]
  },
  {
    term: "Blue/green deployment",
    objective: "cad-delivery",
    lessonId: "rollouts-and-deployment-strategies",
    definition: "A release strategy that runs the old (blue) and new (green) versions side by side as complete environments and switches all traffic at once, allowing instant rollback by switching back.",
    related: ["Canary deployment", "Deployment"]
  },
  {
    term: "Calico",
    objective: "co-networking",
    lessonId: "pod-networking-and-cni",
    definition: "A widely used CNI plugin providing Pod networking and NetworkPolicy enforcement. It is an open-source project led by Tigera, not a CNCF-hosted project.",
    related: ["CNI (Container Network Interface)", "Cilium", "NetworkPolicy"]
  },
  {
    term: "Canary deployment",
    objective: "cad-delivery",
    lessonId: "rollouts-and-deployment-strategies",
    definition: "A release strategy that sends a small, gradually increasing share of traffic to a new version while metrics are watched, and aborts if errors rise.",
    related: ["Blue/green deployment", "Service mesh"]
  },
  {
    term: "cgroups",
    objective: "kf-containerization",
    lessonId: "linux-essentials",
    definition: "Linux control groups: a kernel feature that limits and accounts for CPU, memory and I/O used by a set of processes. Container runtimes use cgroups to enforce Kubernetes resource limits.",
    related: ["Container", "Requests and limits"]
  },
  {
    term: "Cilium",
    objective: "co-networking",
    lessonId: "pod-networking-and-cni",
    definition: "A graduated CNCF project providing eBPF-based networking, NetworkPolicy, observability and load balancing for Kubernetes. It can replace kube-proxy.",
    related: ["CNI (Container Network Interface)", "Calico", "kube-proxy"]
  },
  {
    term: "cloud-controller-manager",
    objective: "kf-core",
    lessonId: "control-plane-controllers",
    definition: "Control plane component that runs cloud-provider-specific controllers: node lifecycle checks, routes, and provisioning cloud load balancers for LoadBalancer Services.",
    related: ["kube-controller-manager", "LoadBalancer Service", "Control plane"]
  },
  {
    term: "Cluster Autoscaler",
    objective: "cna-ecosystem",
    lessonId: "autoscaling-and-serverless",
    definition: "A component that adds nodes when Pods are Pending for lack of capacity and removes underused nodes. It scales the infrastructure, not the Pods.",
    related: ["Horizontal Pod Autoscaler (HPA)", "Vertical Pod Autoscaler (VPA)"]
  },
  {
    term: "ClusterIP",
    objective: "co-networking",
    lessonId: "services",
    definition: "The default Service type: a stable virtual IP reachable only from inside the cluster, load-balancing to the Service's ready Pods.",
    related: ["Service", "NodePort", "Headless Service"]
  },
  {
    term: "ClusterRole",
    objective: "co-security",
    lessonId: "authentication-authorization-rbac",
    definition: "A cluster-scoped set of RBAC permissions. It can grant access to cluster-scoped resources (such as nodes) or be bound per namespace with a RoleBinding to reuse common rules.",
    related: ["Role", "RoleBinding", "RBAC (Role-Based Access Control)"]
  },
  {
    term: "CNI (Container Network Interface)",
    objective: "co-networking",
    lessonId: "pod-networking-and-cni",
    definition: "A CNCF specification and plugin model for configuring container network interfaces. The kubelet's runtime calls a CNI plugin to give each Pod its IP and connectivity.",
    related: ["Calico", "Cilium", "NetworkPolicy"]
  },
  {
    term: "ConfigMap",
    objective: "kf-core",
    lessonId: "configmaps-and-secrets",
    definition: "An API object storing non-confidential configuration as key/value pairs, consumed as environment variables, command arguments or mounted files.",
    related: ["Secret"]
  },
  {
    term: "Container",
    objective: "kf-containerization",
    lessonId: "virtualization-and-containers",
    definition: "A process (or group of processes) running from an image, isolated with kernel namespaces and constrained with cgroups, sharing the host kernel.",
    related: ["Container image", "cgroups", "Container runtime"]
  },
  {
    term: "Container image",
    objective: "kf-containerization",
    lessonId: "container-images-and-oci",
    definition: "An immutable, layered package of a filesystem plus metadata (entrypoint, environment) used to start containers. Referenced by tag or by content digest.",
    related: ["OCI (Open Container Initiative)", "Harbor", "Container"]
  },
  {
    term: "Container runtime",
    objective: "kf-containerization",
    lessonId: "node-components",
    definition: "Software on each node that pulls images and runs containers. Kubernetes talks to it through the CRI; containerd and CRI-O are the common choices.",
    related: ["CRI (Container Runtime Interface)", "containerd", "CRI-O", "kubelet"]
  },
  {
    term: "containerd",
    objective: "kf-containerization",
    lessonId: "node-components",
    definition: "A graduated CNCF container runtime that implements the CRI. It manages image pulls, storage and container execution (via an OCI runtime such as runc).",
    related: ["Container runtime", "CRI-O", "CRI (Container Runtime Interface)"]
  },
  {
    term: "Control plane",
    objective: "kf-core",
    lessonId: "cluster-architecture",
    definition: "The components that manage cluster state and make global decisions: kube-apiserver, etcd, kube-scheduler, kube-controller-manager and optionally cloud-controller-manager.",
    related: ["kube-apiserver", "etcd", "kube-scheduler", "kube-controller-manager", "Node"]
  },
  {
    term: "Controller",
    objective: "kf-core",
    lessonId: "declarative-reconciliation",
    definition: "A control loop that watches objects through the API server and acts to move actual state toward the desired state declared in their spec.",
    related: ["kube-controller-manager", "Operator", "Declarative configuration"]
  },
  {
    term: "CoreDNS",
    objective: "co-networking",
    lessonId: "dns-and-coredns",
    definition: "A graduated CNCF DNS server and the default cluster DNS in Kubernetes. It resolves Service and Pod names such as `web.default.svc.cluster.local`.",
    related: ["Service", "Headless Service"]
  },
  {
    term: "CRD (CustomResourceDefinition)",
    objective: "kf-admin",
    lessonId: "kubectl-and-cluster-administration",
    definition: "An API object that registers a new resource type with the API server, so custom objects can be created and stored like built-in ones.",
    related: ["Operator", "Controller"]
  },
  {
    term: "CRI (Container Runtime Interface)",
    objective: "kf-containerization",
    lessonId: "node-components",
    definition: "The gRPC API between the kubelet and the container runtime. It decouples Kubernetes from any single runtime; dockershim was removed in 1.24.",
    related: ["containerd", "CRI-O", "kubelet", "Container runtime"]
  },
  {
    term: "CRI-O",
    objective: "kf-containerization",
    lessonId: "node-components",
    definition: "A lightweight, graduated CNCF container runtime built specifically to implement the Kubernetes CRI using OCI runtimes.",
    related: ["containerd", "CRI (Container Runtime Interface)"]
  },
  {
    term: "CronJob",
    objective: "kf-core",
    lessonId: "jobs-and-cronjobs",
    definition: "A workload that creates Jobs on a recurring cron-format schedule, such as nightly backups or reports.",
    related: ["Job"]
  },
  {
    term: "Crossplane",
    objective: "cna-ecosystem",
    lessonId: "cloud-native-principles",
    definition: "A CNCF project that extends Kubernetes with CRDs to provision and compose cloud infrastructure (databases, buckets, clusters) declaratively.",
    related: ["CRD (CustomResourceDefinition)", "Backstage", "Operator"]
  },
  {
    term: "CSI (Container Storage Interface)",
    objective: "co-storage",
    lessonId: "persistent-volumes-and-csi",
    definition: "A standard interface that lets storage vendors write volume drivers outside the Kubernetes codebase, used for provisioning, attaching and mounting volumes.",
    related: ["PersistentVolume (PV)", "StorageClass", "Rook", "Longhorn"]
  },
  {
    term: "DaemonSet",
    objective: "kf-core",
    lessonId: "daemonsets-and-statefulsets",
    definition: "A workload that runs one Pod on every eligible node, adding Pods as nodes join. Used for node-level agents such as log collectors and CNI agents.",
    related: ["Deployment", "StatefulSet", "Taint"]
  },
  {
    term: "Declarative configuration",
    objective: "kf-core",
    lessonId: "declarative-reconciliation",
    definition: "Describing the desired end state in files (applied with `kubectl apply`) and letting controllers work out the steps, instead of issuing imperative commands.",
    related: ["Controller", "GitOps"]
  },
  {
    term: "Deployment",
    objective: "kf-core",
    lessonId: "replicasets-and-deployments",
    definition: "A workload for stateless apps that manages ReplicaSets to provide declarative updates, rolling updates and rollbacks.",
    related: ["ReplicaSet", "Pod", "StatefulSet", "DaemonSet"]
  },
  {
    term: "EndpointSlice",
    objective: "co-networking",
    lessonId: "services",
    definition: "An API object listing the network endpoints (Pod IPs and ports) behind a Service. It replaced the older Endpoints API for scalability.",
    related: ["Service", "kube-proxy"]
  },
  {
    term: "Envoy",
    objective: "cna-ecosystem",
    lessonId: "service-mesh-and-envoy",
    definition: "A graduated CNCF high-performance L4/L7 proxy, used as the data plane for Istio and in many API gateways and Gateway API implementations.",
    related: ["Istio", "Service mesh", "Gateway API"]
  },
  {
    term: "Ephemeral container",
    objective: "cad-debugging",
    lessonId: "debugging-applications",
    definition: "A temporary container added to a running Pod with `kubectl debug` for troubleshooting. It is never restarted and has no ports or probes.",
    related: ["Pod", "kubectl"]
  },
  {
    term: "etcd",
    objective: "kf-core",
    lessonId: "api-server-and-etcd",
    definition: "A graduated CNCF consistent, distributed key-value store using Raft. It is the source of truth for all Kubernetes cluster state; only the API server talks to it.",
    related: ["kube-apiserver", "Control plane"]
  },
  {
    term: "Falco",
    objective: "co-security",
    lessonId: "pod-security-and-least-privilege",
    definition: "A graduated CNCF runtime security tool that watches system calls and Kubernetes events and alerts on suspicious behavior, such as a shell spawned in a container.",
    related: ["OPA (Open Policy Agent)", "Kyverno"]
  },
  {
    term: "Fluentd",
    objective: "cna-observability",
    lessonId: "observability-fundamentals",
    definition: "A graduated CNCF log collector and processor that unifies log collection and forwards logs to many backends. Fluent Bit is its lightweight sibling.",
    related: ["Prometheus", "Jaeger", "OpenTelemetry"]
  },
  {
    term: "Flux",
    objective: "cad-delivery",
    lessonId: "cicd-and-gitops",
    definition: "A graduated CNCF GitOps toolkit that keeps clusters in sync with Git repositories, Helm repositories and OCI artifacts.",
    related: ["GitOps", "Argo CD", "Helm"]
  },
  {
    term: "Gateway API",
    objective: "co-networking",
    lessonId: "ingress-and-gateway-api",
    definition: "The role-oriented successor to Ingress (GA in v1.0, October 2023), using GatewayClass, Gateway and Route resources such as HTTPRoute.",
    related: ["Ingress", "Envoy", "Service"]
  },
  {
    term: "GitOps",
    objective: "cad-delivery",
    lessonId: "cicd-and-gitops",
    definition: "Operating systems from desired state that is declarative, versioned and immutable (in Git), pulled automatically and continuously reconciled by in-cluster agents.",
    related: ["Argo CD", "Flux", "Declarative configuration"]
  },
  {
    term: "Grafana",
    objective: "cna-observability",
    lessonId: "prometheus-and-monitoring",
    definition: "An open-source dashboarding and visualization tool frequently paired with Prometheus. It is a Grafana Labs project, not a CNCF project.",
    related: ["Prometheus", "PromQL"]
  },
  {
    term: "Harbor",
    objective: "kf-containerization",
    lessonId: "container-images-and-oci",
    definition: "A graduated CNCF container registry adding access control, vulnerability scanning, image signing support and replication.",
    related: ["Container image", "OCI (Open Container Initiative)"]
  },
  {
    term: "Headless Service",
    objective: "co-networking",
    lessonId: "services",
    definition: "A Service with `clusterIP: None`. It has no virtual IP; DNS returns individual Pod IPs, which gives StatefulSet Pods stable per-Pod DNS names.",
    related: ["Service", "StatefulSet", "CoreDNS"]
  },
  {
    term: "Helm",
    objective: "cad-delivery",
    lessonId: "helm-and-kustomize",
    definition: "A graduated CNCF package manager for Kubernetes. Charts are templated manifests with default values; each installation is a versioned release that can be upgraded or rolled back.",
    related: ["Kustomize", "Argo CD", "Flux"]
  },
  {
    term: "Horizontal Pod Autoscaler (HPA)",
    objective: "cna-ecosystem",
    lessonId: "autoscaling-and-serverless",
    definition: "A built-in controller that changes a workload's replica count based on observed metrics such as CPU utilization relative to requests.",
    related: ["Vertical Pod Autoscaler (VPA)", "Cluster Autoscaler", "KEDA"]
  },
  {
    term: "Immutable infrastructure",
    objective: "cna-ecosystem",
    lessonId: "cloud-native-principles",
    definition: "Infrastructure that is never modified after deployment. Changes are made by building a new image or instance and replacing the old one.",
    related: ["Container image", "Declarative configuration"]
  },
  {
    term: "Ingress",
    objective: "co-networking",
    lessonId: "ingress-and-gateway-api",
    definition: "An API object defining HTTP(S) host and path routing to Services. It needs an Ingress controller to work, and the API is stable but frozen in favor of Gateway API.",
    related: ["Gateway API", "Service"]
  },
  {
    term: "Init container",
    objective: "kf-core",
    lessonId: "pods",
    definition: "A container in a Pod that runs to completion before app containers start. Multiple init containers run sequentially.",
    related: ["Pod", "Sidecar container"]
  },
  {
    term: "Istio",
    objective: "cna-ecosystem",
    lessonId: "service-mesh-and-envoy",
    definition: "A graduated CNCF service mesh using Envoy proxies (as sidecars or in sidecarless ambient mode) for mTLS, traffic management and telemetry.",
    related: ["Service mesh", "Envoy", "Linkerd", "mTLS (mutual TLS)"]
  },
  {
    term: "Jaeger",
    objective: "cna-observability",
    lessonId: "observability-fundamentals",
    definition: "A graduated CNCF distributed tracing platform for collecting, storing and visualizing traces across microservices.",
    related: ["OpenTelemetry", "Prometheus", "Fluentd"]
  },
  {
    term: "Job",
    objective: "kf-core",
    lessonId: "jobs-and-cronjobs",
    definition: "A workload that runs Pods until a specified number complete successfully, retrying failures up to a back-off limit.",
    related: ["CronJob", "Deployment"]
  },
  {
    term: "KEDA",
    objective: "cna-ecosystem",
    lessonId: "autoscaling-and-serverless",
    definition: "Kubernetes Event-driven Autoscaling: a graduated CNCF project that scales workloads on event sources (queues, streams) and supports scale to zero.",
    related: ["Horizontal Pod Autoscaler (HPA)", "Knative", "Serverless"]
  },
  {
    term: "KEP (Kubernetes Enhancement Proposal)",
    objective: "cna-community",
    lessonId: "cncf-community-and-governance",
    definition: "The design and tracking document for a significant Kubernetes change, owned by a SIG and moving features through alpha, beta and stable.",
    related: ["SIG (Special Interest Group)"]
  },
  {
    term: "Knative",
    objective: "cna-ecosystem",
    lessonId: "autoscaling-and-serverless",
    definition: "A CNCF platform on Kubernetes for serverless workloads: request-driven autoscaling including scale to zero (Serving) and event delivery (Eventing).",
    related: ["Serverless", "KEDA"]
  },
  {
    term: "kube-apiserver",
    objective: "kf-core",
    lessonId: "api-server-and-etcd",
    definition: "The front end of the control plane. It exposes the Kubernetes REST API, runs authentication, authorization and admission, and is the only component that talks to etcd.",
    related: ["etcd", "Admission controller", "Control plane"]
  },
  {
    term: "kube-controller-manager",
    objective: "kf-core",
    lessonId: "control-plane-controllers",
    definition: "Control plane binary that runs the built-in controllers, including Deployment, ReplicaSet, Node, Job and EndpointSlice controllers.",
    related: ["Controller", "cloud-controller-manager"]
  },
  {
    term: "kube-proxy",
    objective: "co-networking",
    lessonId: "services",
    definition: "A node agent that programs packet-forwarding rules (iptables, IPVS or nftables) so traffic to a Service's virtual IP reaches backend Pods. Some CNIs replace it.",
    related: ["Service", "EndpointSlice", "Cilium"]
  },
  {
    term: "kube-scheduler",
    objective: "kf-scheduling",
    lessonId: "control-plane-controllers",
    definition: "Control plane component that assigns unscheduled Pods to nodes by filtering infeasible nodes and scoring the rest. It does not start containers.",
    related: ["Taint", "Toleration", "Requests and limits"]
  },
  {
    term: "kubeconfig",
    objective: "kf-admin",
    lessonId: "kubectl-and-cluster-administration",
    definition: "A file (default `~/.kube/config`) holding clusters, users and contexts that kubectl uses to connect and authenticate.",
    related: ["kubectl"]
  },
  {
    term: "kubectl",
    objective: "kf-admin",
    lessonId: "kubectl-and-cluster-administration",
    definition: "The Kubernetes command-line client. It sends requests to the API server: `get`, `describe`, `apply`, `logs`, `exec` and more.",
    related: ["kubeconfig", "kube-apiserver"]
  },
  {
    term: "kubelet",
    objective: "kf-core",
    lessonId: "node-components",
    definition: "The agent on every node that ensures containers in the Pods assigned to it are running, executes probes and reports Pod and node status.",
    related: ["Container runtime", "CRI (Container Runtime Interface)", "Node"]
  },
  {
    term: "Kustomize",
    objective: "cad-delivery",
    lessonId: "helm-and-kustomize",
    definition: "A template-free configuration tool that customizes plain YAML bases with overlays and patches. It is built into kubectl via `kubectl apply -k`.",
    related: ["Helm"]
  },
  {
    term: "Kyverno",
    objective: "co-security",
    lessonId: "pod-security-and-least-privilege",
    definition: "A CNCF policy engine for Kubernetes whose policies are written as Kubernetes YAML. It can validate, mutate and generate resources through admission control.",
    related: ["OPA (Open Policy Agent)", "Admission controller"]
  },
  {
    term: "Label",
    objective: "kf-core",
    lessonId: "namespaces-labels-selectors",
    definition: "An identifying key/value pair on an object. Selectors match labels to group objects, for example to connect Services and ReplicaSets to Pods.",
    related: ["Annotation", "Service", "ReplicaSet"]
  },
  {
    term: "Linkerd",
    objective: "cna-ecosystem",
    lessonId: "service-mesh-and-envoy",
    definition: "A graduated CNCF service mesh focused on simplicity, using its own lightweight Rust proxy (not Envoy) to provide mTLS, retries and golden metrics.",
    related: ["Service mesh", "Istio", "mTLS (mutual TLS)"]
  },
  {
    term: "Liveness probe",
    objective: "kf-core",
    lessonId: "health-probes",
    definition: "A periodic check of whether a container is still healthy. If it keeps failing, the kubelet restarts the container.",
    related: ["Readiness probe", "Startup probe"]
  },
  {
    term: "LoadBalancer Service",
    objective: "co-networking",
    lessonId: "services",
    definition: "A Service type that asks the cloud provider (or an add-on) for an external load balancer, built on top of NodePort and ClusterIP.",
    related: ["Service", "NodePort", "cloud-controller-manager"]
  },
  {
    term: "Longhorn",
    objective: "co-storage",
    lessonId: "persistent-volumes-and-csi",
    definition: "A CNCF distributed block storage system for Kubernetes, providing replicated persistent volumes through a CSI driver.",
    related: ["Rook", "CSI (Container Storage Interface)"]
  },
  {
    term: "Microservices",
    objective: "cna-ecosystem",
    lessonId: "cloud-native-principles",
    definition: "An architecture that splits an application into small, independently deployable services communicating over the network, each owned by a small team.",
    related: ["Service mesh", "Twelve-factor app"]
  },
  {
    term: "mTLS (mutual TLS)",
    objective: "co-security",
    lessonId: "service-mesh-and-envoy",
    definition: "TLS in which both client and server present certificates, giving encrypted traffic plus verified identity on both sides. Service meshes automate it.",
    related: ["Service mesh", "Istio", "Linkerd"]
  },
  {
    term: "Namespace",
    objective: "kf-admin",
    lessonId: "namespaces-labels-selectors",
    definition: "A virtual partition of a cluster that scopes names, RBAC Roles, ResourceQuotas and policies. Not every resource is namespaced, for example Nodes and PVs.",
    related: ["Role", "NetworkPolicy"]
  },
  {
    term: "NetworkPolicy",
    objective: "co-networking",
    lessonId: "network-policies",
    definition: "A namespaced object that restricts ingress and egress traffic for selected Pods. Allow-list only, and enforced by the CNI plugin.",
    related: ["CNI (Container Network Interface)", "Calico", "Cilium"]
  },
  {
    term: "Node",
    objective: "kf-core",
    lessonId: "cluster-architecture",
    definition: "A worker machine (VM or physical) running the kubelet, a container runtime and usually kube-proxy, on which Pods are scheduled.",
    related: ["kubelet", "Control plane"]
  },
  {
    term: "NodePort",
    objective: "co-networking",
    lessonId: "services",
    definition: "A Service type that opens the same port (default range 30000\u201332767) on every node and forwards it to the Service.",
    related: ["ClusterIP", "LoadBalancer Service", "Service"]
  },
  {
    term: "OCI (Open Container Initiative)",
    objective: "kf-containerization",
    lessonId: "container-images-and-oci",
    definition: "A Linux Foundation project defining open standards for containers: the runtime, image and distribution specifications.",
    related: ["Container image", "CRI (Container Runtime Interface)"]
  },
  {
    term: "OPA (Open Policy Agent)",
    objective: "co-security",
    lessonId: "pod-security-and-least-privilege",
    definition: "A graduated CNCF general-purpose policy engine using the Rego language. It is used in Kubernetes admission via Gatekeeper.",
    related: ["Kyverno", "Admission controller"]
  },
  {
    term: "OpenTelemetry",
    objective: "cna-observability",
    lessonId: "observability-fundamentals",
    definition: "A CNCF project providing vendor-neutral APIs, SDKs and the Collector to generate and export traces, metrics and logs. It does not store data itself.",
    related: ["Jaeger", "Prometheus", "Fluentd"]
  },
  {
    term: "Operator",
    objective: "kf-admin",
    lessonId: "kubectl-and-cluster-administration",
    definition: "A custom controller plus CRDs that encodes operational knowledge (install, upgrade, backup, failover) for a specific application.",
    related: ["CRD (CustomResourceDefinition)", "Controller"]
  },
  {
    term: "PersistentVolume (PV)",
    objective: "co-storage",
    lessonId: "persistent-volumes-and-csi",
    definition: "A cluster-scoped piece of storage, provisioned statically or dynamically, whose lifecycle is independent of any Pod.",
    related: ["PersistentVolumeClaim (PVC)", "StorageClass", "CSI (Container Storage Interface)"]
  },
  {
    term: "PersistentVolumeClaim (PVC)",
    objective: "co-storage",
    lessonId: "persistent-volumes-and-csi",
    definition: "A namespaced request for storage (size, access mode, StorageClass) that binds to a PV. Pods reference the PVC, not the PV.",
    related: ["PersistentVolume (PV)", "StorageClass"]
  },
  {
    term: "Pod",
    objective: "kf-core",
    lessonId: "pods",
    definition: "The smallest deployable unit: one or more containers scheduled together on one node, sharing a network namespace (one IP) and optionally volumes.",
    related: ["Deployment", "Init container", "Sidecar container"]
  },
  {
    term: "Pod Security Admission",
    objective: "co-security",
    lessonId: "pod-security-and-least-privilege",
    definition: "The built-in admission controller that enforces Pod Security Standards per namespace through labels in enforce, audit or warn mode. It replaced PodSecurityPolicy, removed in 1.25.",
    related: ["Pod Security Standards", "Admission controller"]
  },
  {
    term: "Pod Security Standards",
    objective: "co-security",
    lessonId: "pod-security-and-least-privilege",
    definition: "Three policy levels for Pod security settings: Privileged (unrestricted), Baseline (blocks known escalations) and Restricted (hardened).",
    related: ["Pod Security Admission"]
  },
  {
    term: "Prometheus",
    objective: "cna-observability",
    lessonId: "prometheus-and-monitoring",
    definition: "A graduated CNCF monitoring system and time-series database that pulls (scrapes) metrics from HTTP endpoints and evaluates alerting rules.",
    related: ["PromQL", "Alertmanager", "Grafana"]
  },
  {
    term: "PromQL",
    objective: "cna-observability",
    lessonId: "prometheus-and-monitoring",
    definition: "The Prometheus query language for selecting and aggregating time series, for example `rate(http_requests_total[5m])`.",
    related: ["Prometheus", "Grafana"]
  },
  {
    term: "RBAC (Role-Based Access Control)",
    objective: "co-security",
    lessonId: "authentication-authorization-rbac",
    definition: "The Kubernetes authorization mode that grants verbs on resources through Roles and ClusterRoles bound to users, groups or ServiceAccounts. Permissions are additive only.",
    related: ["Role", "ClusterRole", "RoleBinding", "ServiceAccount"]
  },
  {
    term: "Readiness probe",
    objective: "co-troubleshooting",
    lessonId: "health-probes",
    definition: "A check of whether a container can serve traffic. Failing removes the Pod from Service endpoints without restarting it.",
    related: ["Liveness probe", "Startup probe", "Service"]
  },
  {
    term: "ReplicaSet",
    objective: "kf-core",
    lessonId: "replicasets-and-deployments",
    definition: "A controller that keeps a specified number of Pods matching its selector running. Usually managed by a Deployment rather than created directly.",
    related: ["Deployment", "Pod", "Label"]
  },
  {
    term: "Requests and limits",
    objective: "kf-scheduling",
    lessonId: "resources-requests-limits",
    definition: "Per-container CPU and memory settings. Requests drive scheduling and QoS class; limits cap usage (CPU throttled, memory OOMKilled).",
    related: ["kube-scheduler", "cgroups"]
  },
  {
    term: "Role",
    objective: "co-security",
    lessonId: "authentication-authorization-rbac",
    definition: "A namespaced set of RBAC rules (API groups, resources, verbs) granted to subjects through a RoleBinding.",
    related: ["ClusterRole", "RoleBinding", "RBAC (Role-Based Access Control)"]
  },
  {
    term: "RoleBinding",
    objective: "co-security",
    lessonId: "authentication-authorization-rbac",
    definition: "Grants a Role or ClusterRole to users, groups or ServiceAccounts within one namespace.",
    related: ["Role", "ClusterRole", "ServiceAccount"]
  },
  {
    term: "Rook",
    objective: "co-storage",
    lessonId: "persistent-volumes-and-csi",
    definition: "A graduated CNCF storage operator that runs Ceph on Kubernetes, providing block, file and object storage.",
    related: ["Longhorn", "Operator", "CSI (Container Storage Interface)"]
  },
  {
    term: "Secret",
    objective: "co-security",
    lessonId: "configmaps-and-secrets",
    definition: "An object for small sensitive data such as passwords and tokens. Values are base64-encoded, not encrypted, by default; enable encryption at rest and limit RBAC access.",
    related: ["ConfigMap", "RBAC (Role-Based Access Control)"]
  },
  {
    term: "Serverless",
    objective: "cna-ecosystem",
    lessonId: "autoscaling-and-serverless",
    definition: "A model where developers deploy functions or containers without managing servers, and the platform scales them on demand, often to zero.",
    related: ["Knative", "KEDA"]
  },
  {
    term: "Service",
    objective: "co-networking",
    lessonId: "services",
    definition: "A stable network endpoint (name and virtual IP) for a set of Pods selected by labels. Types are ClusterIP (default), NodePort, LoadBalancer and ExternalName.",
    related: ["ClusterIP", "NodePort", "LoadBalancer Service", "EndpointSlice", "kube-proxy"]
  },
  {
    term: "Service mesh",
    objective: "cna-ecosystem",
    lessonId: "service-mesh-and-envoy",
    definition: "An infrastructure layer of proxies (sidecar or node-level) plus a control plane that adds mTLS, traffic control and telemetry to service-to-service calls without code changes.",
    related: ["Istio", "Linkerd", "Envoy", "mTLS (mutual TLS)"]
  },
  {
    term: "ServiceAccount",
    objective: "co-security",
    lessonId: "authentication-authorization-rbac",
    definition: "A namespaced identity for processes running in Pods, used to authenticate to the API server and bound to permissions through RBAC.",
    related: ["RBAC (Role-Based Access Control)", "RoleBinding"]
  },
  {
    term: "Sidecar container",
    objective: "kf-core",
    lessonId: "pods",
    definition: "A helper container running alongside the main app in the same Pod (proxy, log shipper). Natively declared as an init container with `restartPolicy: Always`, stable in 1.33.",
    related: ["Pod", "Init container", "Service mesh"]
  },
  {
    term: "SIG (Special Interest Group)",
    objective: "cna-community",
    lessonId: "cncf-community-and-governance",
    definition: "A Kubernetes community group owning one area (for example SIG Network, SIG Storage), with open meetings, code ownership and KEP review.",
    related: ["KEP (Kubernetes Enhancement Proposal)"]
  },
  {
    term: "SLA",
    objective: "cna-observability",
    lessonId: "observability-fundamentals",
    definition: "Service Level Agreement: a contract with customers about service levels, with consequences such as credits if it is missed.",
    related: ["SLO", "SLI"]
  },
  {
    term: "SLI",
    objective: "cna-observability",
    lessonId: "observability-fundamentals",
    definition: "Service Level Indicator: a measured metric of service quality, such as the proportion of successful requests or p99 latency.",
    related: ["SLO", "SLA"]
  },
  {
    term: "SLO",
    objective: "cna-observability",
    lessonId: "observability-fundamentals",
    definition: "Service Level Objective: an internal target value for an SLI over a time window, such as 99.9% success over 30 days.",
    related: ["SLI", "SLA"]
  },
  {
    term: "Startup probe",
    objective: "kf-core",
    lessonId: "health-probes",
    definition: "A probe that holds off liveness and readiness checks until it succeeds, protecting slow-starting containers from premature restarts.",
    related: ["Liveness probe", "Readiness probe"]
  },
  {
    term: "StatefulSet",
    objective: "kf-core",
    lessonId: "daemonsets-and-statefulsets",
    definition: "A workload for stateful apps that gives Pods stable ordinal names, stable per-Pod storage via volumeClaimTemplates and ordered rollout.",
    related: ["Headless Service", "PersistentVolumeClaim (PVC)", "Deployment"]
  },
  {
    term: "StorageClass",
    objective: "co-storage",
    lessonId: "persistent-volumes-and-csi",
    definition: "A cluster-scoped object naming a provisioner and parameters, enabling dynamic provisioning of PVs when a PVC requests it.",
    related: ["PersistentVolumeClaim (PVC)", "PersistentVolume (PV)", "CSI (Container Storage Interface)"]
  },
  {
    term: "Taint",
    objective: "kf-scheduling",
    lessonId: "scheduling-placement",
    definition: "A key/value/effect marker on a node (NoSchedule, PreferNoSchedule, NoExecute) that repels Pods that do not tolerate it.",
    related: ["Toleration", "kube-scheduler"]
  },
  {
    term: "Toleration",
    objective: "kf-scheduling",
    lessonId: "scheduling-placement",
    definition: "A Pod setting that allows scheduling onto nodes with matching taints. It permits but does not attract; use affinity to steer Pods.",
    related: ["Taint", "kube-scheduler"]
  },
  {
    term: "Twelve-factor app",
    objective: "cna-ecosystem",
    lessonId: "cloud-native-principles",
    definition: "A methodology for building portable, scalable services, including config in the environment, stateless processes, disposability and dev/prod parity.",
    related: ["Microservices", "Immutable infrastructure"]
  },
  {
    term: "Vertical Pod Autoscaler (VPA)",
    objective: "cna-ecosystem",
    lessonId: "autoscaling-and-serverless",
    definition: "An add-on that recommends or automatically adjusts container CPU and memory requests based on observed usage.",
    related: ["Horizontal Pod Autoscaler (HPA)", "Cluster Autoscaler", "Requests and limits"]
  }
];

// ../../packages/content/src/comparisons.ts
var comparisons = [
  {
    id: "cmp-pod-vs-deployment",
    a: "Pod",
    b: "Deployment",
    objective: "kf-core",
    lessonId: "replicasets-and-deployments",
    rows: [
      { aspect: "What it is", a: "The smallest runnable unit: one or more containers sharing an IP", b: "A controller object that manages ReplicaSets, which manage Pods" },
      { aspect: "Self-healing", a: "None: a deleted or evicted bare Pod is gone for good", b: "Replaces failed or deleted Pods to keep the replica count" },
      { aspect: "Scaling", a: "One instance; you would create more by hand", b: "Change `replicas` or use `kubectl scale`" },
      { aspect: "Updates", a: "Most spec fields are immutable; you delete and recreate the Pod", b: "Rolling updates and `kubectl rollout undo` rollbacks" },
      { aspect: "Typical use", a: "One-off debugging, or as the template inside controllers", b: "Long-running stateless applications" }
    ],
    rule: "Run applications as Deployments and treat Pods as disposable instances that a controller creates for you.",
    examTrap: "`kubectl run` creates a single bare Pod, not a Deployment, so nothing recreates it after deletion."
  },
  {
    id: "cmp-replicaset-vs-deployment",
    a: "ReplicaSet",
    b: "Deployment",
    objective: "kf-core",
    lessonId: "replicasets-and-deployments",
    rows: [
      { aspect: "Job", a: "Keeps N Pods matching a selector running", b: "Manages ReplicaSets to roll out new Pod templates" },
      { aspect: "Rolling updates", a: "No: editing its template does not replace existing Pods", b: "Yes: it creates a new ReplicaSet and shifts Pods over gradually" },
      { aspect: "Rollback history", a: "None", b: "Old ReplicaSets are kept as revisions (`revisionHistoryLimit`)" },
      { aspect: "Created by", a: "Usually a Deployment, rarely by hand", b: "You" },
      { aspect: "Naming", a: "`<deployment>-<pod-template-hash>`", b: "The name you choose" }
    ],
    rule: "Deployments own ReplicaSets and ReplicaSets own Pods; you manage the Deployment and let it manage the rest.",
    examTrap: "Scaling a Deployment does not create a new ReplicaSet; only a change to the Pod template (`spec.template`) does."
  },
  {
    id: "cmp-deployment-vs-statefulset",
    a: "Deployment",
    b: "StatefulSet",
    objective: "kf-core",
    lessonId: "daemonsets-and-statefulsets",
    rows: [
      { aspect: "Pod identity", a: "Random suffixes (`web-7d9c-xk2lp`); Pods are interchangeable", b: "Stable ordinals (`db-0`, `db-1`) that persist across rescheduling" },
      { aspect: "Storage", a: "Pods normally share one PVC or use none", b: "One PVC per Pod from `volumeClaimTemplates`, which stays attached to that identity" },
      { aspect: "Ordering", a: "Pods are created and deleted in parallel", b: "Ordered creation, scaling and updates by default" },
      { aspect: "Network identity", a: "Reached through a normal Service VIP", b: "Per-Pod DNS names through a headless Service" },
      { aspect: "Typical use", a: "Stateless web or API servers", b: "Databases, Kafka, etcd, and other clustered stateful systems" }
    ],
    rule: "If replicas are interchangeable use a Deployment; if each replica needs its own identity or data, use a StatefulSet.",
    examTrap: "Deleting or scaling down a StatefulSet does not delete its PVCs by default, so the data survives."
  },
  {
    id: "cmp-deployment-vs-daemonset",
    a: "Deployment",
    b: "DaemonSet",
    objective: "kf-core",
    lessonId: "daemonsets-and-statefulsets",
    rows: [
      { aspect: "Replica count", a: "Set by `replicas` (or an HPA)", b: "One per eligible node; there is no `replicas` field" },
      { aspect: "Placement", a: "The scheduler spreads Pods wherever they fit", b: "Pinned per node; new nodes automatically get a Pod" },
      { aspect: "Scales with", a: "Load", b: "Cluster size" },
      { aspect: "Typical use", a: "Application services", b: "Node agents: log collectors, monitoring exporters, CNI agents" },
      { aspect: "Control-plane nodes", a: "Not targeted", b: "Covered only if the Pods tolerate the control-plane taint" }
    ],
    rule: "Choose a DaemonSet when you need one Pod per node, and a Deployment when you need N Pods anywhere.",
    examTrap: "A DaemonSet cannot be scaled with `kubectl scale`; to change where it runs, use node selectors, affinity or tolerations."
  },
  {
    id: "cmp-service-vs-ingress",
    a: "Service",
    b: "Ingress",
    objective: "co-networking",
    lessonId: "ingress-and-gateway-api",
    rows: [
      { aspect: "OSI layer", a: "L4 (TCP/UDP/SCTP)", b: "L7 (HTTP/HTTPS)" },
      { aspect: "Routing", a: "To Pods selected by labels", b: "By host and path to Services" },
      { aspect: "TLS termination", a: "No", b: "Yes, using a TLS Secret" },
      { aspect: "Needs an extra component", a: "No: kube-proxy or the CNI implements it", b: "Yes: an Ingress controller must be installed" },
      { aspect: "External exposure", a: "Through NodePort or LoadBalancer types", b: "Many HTTP apps share one entry point" },
      { aspect: "Backends", a: "Pods", b: "Services, never Pods directly" }
    ],
    rule: "A Service gives Pods a stable address, and an Ingress routes external HTTP traffic to Services.",
    examTrap: "An Ingress with no Ingress controller is accepted by the API but routes nothing."
  },
  {
    id: "cmp-ingress-vs-gateway-api",
    a: "Ingress",
    b: "Gateway API",
    objective: "co-networking",
    lessonId: "ingress-and-gateway-api",
    rows: [
      { aspect: "Status", a: "Stable (`networking.k8s.io/v1`) but frozen: no new features", b: "GA since v1.0 (October 2023) and actively developed" },
      { aspect: "Resource model", a: "One Ingress object", b: "GatewayClass, Gateway and Routes (HTTPRoute, GRPCRoute, ...)" },
      { aspect: "Role separation", a: "None: one object mixes infrastructure and app routing", b: "Infra provider, cluster operator and app developer each own their own resources" },
      { aspect: "Advanced features", a: "Mostly through controller-specific annotations", b: "Header matching, traffic splitting and more, defined in the spec" },
      { aspect: "Protocols", a: "HTTP/HTTPS", b: "HTTP and gRPC, plus TCP, UDP and TLS route resources (some still experimental)" }
    ],
    rule: "Ingress still works; Gateway API is where new routing features land.",
    examTrap: "Ingress is frozen, not deprecated or removed, and Gateway API is an official Kubernetes SIG Network project rather than a vendor product."
  },
  {
    id: "cmp-configmap-vs-secret",
    a: "ConfigMap",
    b: "Secret",
    objective: "co-security",
    lessonId: "configmaps-and-secrets",
    rows: [
      { aspect: "Intended data", a: "Non-confidential configuration", b: "Passwords, tokens, keys, certificates" },
      { aspect: "Encoding", a: "Plain text", b: "Base64 in the API, which is encoding and not encryption" },
      { aspect: "Encryption at rest", a: "No", b: "Only when encryption at rest is configured on the API server" },
      { aspect: "Consumption", a: "Env vars, args or mounted files", b: "Env vars or mounted files, plus `imagePullSecrets`" },
      { aspect: "Size limit", a: "1 MiB", b: "1 MiB" }
    ],
    rule: "Use a Secret for anything you would not paste into a public chat, and still protect it with RBAC and encryption at rest.",
    examTrap: "base64 is not encryption: anyone who can read the Secret can decode it."
  },
  {
    id: "cmp-pv-vs-pvc",
    a: "PersistentVolume (PV)",
    b: "PersistentVolumeClaim (PVC)",
    objective: "co-storage",
    lessonId: "persistent-volumes-and-csi",
    rows: [
      { aspect: "Role", a: "The actual piece of storage", b: "A request for storage" },
      { aspect: "Scope", a: "Cluster-scoped", b: "Namespaced" },
      { aspect: "Created by", a: "An admin (static) or a StorageClass provisioner (dynamic)", b: "An application developer" },
      { aspect: "Referenced by Pods", a: "Never directly", b: "Yes, through `persistentVolumeClaim.claimName`" },
      { aspect: "Lifecycle", a: "Its reclaim policy (Retain/Delete) decides what happens after release", b: "Binds one-to-one with a PV; deleting it releases the PV" }
    ],
    rule: "Developers claim storage with PVCs; PVs (often created dynamically through a StorageClass) satisfy those claims.",
    examTrap: "Pods mount PVCs, not PVs, and dynamically provisioned PVs default to the `Delete` reclaim policy, so their data goes when the PVC is deleted."
  },
  {
    id: "cmp-metrics-logs-traces",
    a: "Metrics",
    b: "Logs",
    c: "Traces",
    objective: "cna-observability",
    lessonId: "observability-fundamentals",
    rows: [
      { aspect: "Shape", a: "Numeric time series with labels", b: "Timestamped event records (text or structured)", c: "Trees of spans following one request across services" },
      { aspect: "Answers", a: "Is something wrong, and how much?", b: "What exactly happened here?", c: "Where in the call chain is the time or error?" },
      { aspect: "Cost profile", a: "Cheap and compact; aggregates well", b: "Large volume; costly to store and index", c: "Often sampled to control volume" },
      { aspect: "Typical tools", a: "Prometheus, Grafana", b: "Fluentd/Fluent Bit, Loki, Elasticsearch", c: "Jaeger, plus OpenTelemetry for instrumentation" },
      { aspect: "Typical use", a: "Dashboards, alerting, SLIs", b: "Debugging individual errors and auditing", c: "Latency analysis in microservices" }
    ],
    rule: "Metrics tell you something is wrong, traces tell you where, and logs tell you why.",
    examTrap: "OpenTelemetry covers all three signals for instrumentation and export, but it is not a storage or visualization backend."
  },
  {
    id: "cmp-cicd-vs-gitops",
    a: "Traditional CI/CD (push)",
    b: "GitOps (pull)",
    objective: "cad-delivery",
    lessonId: "cicd-and-gitops",
    rows: [
      { aspect: "Who applies changes", a: "The pipeline runs `kubectl` or `helm` against the cluster", b: "An in-cluster agent (Argo CD, Flux) pulls and applies" },
      { aspect: "Cluster credentials", a: "Stored in the CI system", b: "Stay inside the cluster" },
      { aspect: "Source of truth", a: "Whatever the last pipeline run applied", b: "The desired state in Git" },
      { aspect: "Drift handling", a: "Undetected until the next deploy", b: "Detected and reconciled continuously" },
      { aspect: "Rollback", a: "Rerun an older pipeline", b: "`git revert`; the agent converges" }
    ],
    rule: "GitOps keeps CI for building and testing, but replaces push-style deployment with an agent that continuously pulls desired state from Git.",
    examTrap: "GitOps does not replace CI: images are still built and tested in CI, and GitOps changes only how deployment happens."
  },
  {
    id: "cmp-probes",
    a: "Liveness probe",
    b: "Readiness probe",
    c: "Startup probe",
    objective: "kf-core",
    lessonId: "health-probes",
    rows: [
      { aspect: "Question asked", a: "Is the container still healthy?", b: "Can it serve traffic right now?", c: "Has it finished starting?" },
      { aspect: "On failure", a: "The kubelet restarts the container", b: "The Pod is removed from Service endpoints; no restart", c: "After `failureThreshold` failures the container is restarted" },
      { aspect: "When it runs", a: "For the container's whole life, after startup succeeds", b: "For the container's whole life, after startup succeeds", c: "Only until it first succeeds" },
      { aspect: "Typical use", a: "Recovering from deadlocks or hung processes", b: "Warm-up, dependency outages, temporary overload", c: "Slow-booting apps such as legacy JVM apps" },
      { aspect: "Risk if misused", a: "Restart loops if it checks external dependencies", b: "No traffic if it is too strict", c: "Slow failure detection if thresholds are too long" }
    ],
    rule: "Liveness restarts, readiness routes, and startup protects slow boots.",
    examTrap: "A failing readiness probe never restarts the container, so it alone cannot cause CrashLoopBackOff."
  },
  {
    id: "cmp-role-vs-clusterrole",
    a: "Role",
    b: "ClusterRole",
    objective: "co-security",
    lessonId: "authentication-authorization-rbac",
    rows: [
      { aspect: "Scope of the object", a: "Namespaced", b: "Cluster-scoped" },
      { aspect: "Can grant on cluster-scoped resources (nodes, PVs)", a: "No", b: "Yes, when bound with a ClusterRoleBinding" },
      { aspect: "Bound with", a: "A RoleBinding in the same namespace", b: "A ClusterRoleBinding (cluster-wide) or a RoleBinding (one namespace)" },
      { aspect: "Reuse", a: "Must be duplicated in each namespace", b: "Defined once and bound wherever needed" },
      { aspect: "Built-in examples", a: "None of note", b: "`cluster-admin`, `admin`, `edit`, `view`" }
    ],
    rule: "The binding decides where permissions apply; the role kind decides what the permissions can cover.",
    examTrap: "A ClusterRole bound with a RoleBinding only grants access inside that RoleBinding's namespace."
  }
];

// ../../packages/content/src/labs.ts
var KIND = { title: "kind quick start", url: "https://kind.sigs.k8s.io/docs/user/quick-start/" };
var KUBECTL = { title: "kubectl reference", url: "https://kubernetes.io/docs/reference/kubectl/" };
var KIND_PREREQS = [
  "Docker (or Podman) running locally",
  "kind v0.24+ installed (https://kind.sigs.k8s.io/)",
  "kubectl within one minor version of the cluster"
];
var CREATE_CLUSTER = "kind create cluster --name kcna";
var DELETE_CLUSTER = "kind delete cluster --name kcna";
var CLUSTER_TASK = {
  title: "Start (or reuse) the lab cluster",
  instructions: 'Create a single-node kind cluster called `kcna`. If it already exists from a previous lab, `kind create` will fail with "node(s) already exist" \u2014 just switch to its context instead.',
  commands: [CREATE_CLUSTER, "kubectl config use-context kind-kcna", "kubectl get nodes"],
  expected: `NAME                 STATUS   ROLES           AGE   VERSION
kcna-control-plane   Ready    control-plane   40s   v1.3x.x`,
  hint: "If the node shows `NotReady`, wait 20\u201330 seconds: the CNI (kindnet) is still starting."
};
var labs = [
  // ───────────────────────────── FULL LABS ─────────────────────────────
  {
    id: "lab-kind-cluster-explore",
    title: "Create a kind cluster and explore its components",
    objectives: ["kf-core", "kf-admin"],
    scope: "kcna",
    status: "full",
    environment: "kind",
    estMinutes: 30,
    objective: "Stand up a local Kubernetes cluster with kind and identify every control-plane and node component you will be asked about on the exam: kube-apiserver, etcd, kube-scheduler, kube-controller-manager, kubelet, kube-proxy, CoreDNS and the container runtime.",
    prerequisites: KIND_PREREQS,
    architecture: 'kind ("Kubernetes in Docker") runs each Kubernetes **node as a Docker container**. Inside the `kcna-control-plane` container, systemd runs **containerd** and the **kubelet**; the kubelet starts the control-plane components as **static Pods** from manifests in `/etc/kubernetes/manifests`. kube-proxy and the kindnet CNI agent run as DaemonSets, CoreDNS as a Deployment.\n\n```\nhost \u2500\u2500 docker \u2500\u2500 kcna-control-plane (container)\n                   \u251C\u2500 containerd + kubelet (systemd)\n                   \u2514\u2500 Pods: kube-apiserver, etcd, scheduler, controller-manager,\n                            kube-proxy, kindnet, coredns, local-path-provisioner\n```',
    tasks: [
      {
        title: "Create the cluster",
        instructions: "Create a cluster named `kcna`. kind writes a kubeconfig entry and switches your current context to `kind-kcna`.",
        commands: [CREATE_CLUSTER, "kubectl config current-context", "kubectl cluster-info"],
        expected: `Creating cluster "kcna" ...
...
Set kubectl context to "kind-kcna"
...
kind-kcna
Kubernetes control plane is running at https://127.0.0.1:<port>
CoreDNS is running at https://127.0.0.1:<port>/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy`,
        hint: "If image download is slow, the first run can take a few minutes. Subsequent clusters reuse the cached `kindest/node` image."
      },
      {
        title: "Look at the node \u2014 from Kubernetes and from Docker",
        instructions: "List nodes with extra columns, then confirm the node is really a Docker container. Note the container runtime column.",
        commands: ["kubectl get nodes -o wide", "docker ps --filter name=kcna"],
        expected: `NAME                 STATUS   ROLES           AGE   VERSION   INTERNAL-IP   EXTERNAL-IP   OS-IMAGE   KERNEL-VERSION   CONTAINER-RUNTIME
kcna-control-plane   Ready    control-plane   2m    v1.3x.x   172.18.0.2    <none>        Debian ... ...              containerd://2.x.x`,
        hint: "`CONTAINER-RUNTIME` shows containerd: Kubernetes talks to it through the CRI. Docker is only used by kind to host the node, not by the kubelet."
      },
      {
        title: "Find the control-plane components",
        instructions: "List the Pods in `kube-system` with the node they run on. Identify which are static Pods (their names end with the node name).",
        commands: ["kubectl get pods -n kube-system -o wide"],
        expected: `coredns-...                                 1/1   Running
etcd-kcna-control-plane                     1/1   Running
kindnet-...                                 1/1   Running
kube-apiserver-kcna-control-plane           1/1   Running
kube-controller-manager-kcna-control-plane  1/1   Running
kube-proxy-...                              1/1   Running
kube-scheduler-kcna-control-plane           1/1   Running`,
        hint: "Static Pods are managed by the kubelet directly from files, so their names get the node name as suffix."
      },
      {
        title: "Peek inside the node",
        instructions: "Open the static Pod manifest directory and list running containers with `crictl`, the CRI command-line client shipped in the kind node image.",
        commands: [
          "docker exec kcna-control-plane ls /etc/kubernetes/manifests",
          "docker exec kcna-control-plane crictl ps"
        ],
        expected: `etcd.yaml
kube-apiserver.yaml
kube-controller-manager.yaml
kube-scheduler.yaml`,
        hint: "Editing a file in `/etc/kubernetes/manifests` makes the kubelet recreate that component \u2014 this is how kubeadm-style clusters run the control plane."
      },
      {
        title: "Discover the API",
        instructions: "List the resource types the API server knows, separate namespaced and cluster-scoped ones, and use `kubectl explain` to read field docs offline.",
        commands: [
          "kubectl api-resources | head -20",
          "kubectl api-resources --namespaced=false",
          "kubectl explain pod.spec.containers.image",
          "kubectl get --raw='/readyz?verbose' | tail -3"
        ],
        expected: `NAME          SHORTNAMES   APIVERSION   NAMESPACED   KIND
bindings                   v1           true         Binding
componentstatuses   cs     v1           false        ComponentStatus
configmaps          cm     v1           true         ConfigMap
...
readyz check passed`,
        hint: "The SHORTNAMES column is where aliases like `po`, `svc`, `deploy` come from."
      },
      {
        title: "Namespaces and the default context",
        instructions: "List namespaces and check which namespace your context uses by default.",
        commands: ["kubectl get namespaces", "kubectl config get-contexts"],
        expected: `NAME                 STATUS   AGE
default              Active   5m
kube-node-lease      Active   5m
kube-public          Active   5m
kube-system          Active   5m
local-path-storage   Active   5m`,
        hint: "An empty NAMESPACE column in `get-contexts` means `default`."
      }
    ],
    validation: [
      { description: "Node is Ready", command: `kubectl get nodes -o jsonpath='{.items[0].status.conditions[?(@.type=="Ready")].status}'`, expected: "True" },
      { description: "API server is healthy", command: "kubectl get --raw='/readyz'", expected: "ok" },
      { description: "CoreDNS is running", command: "kubectl get deployment coredns -n kube-system", expected: "READY 2/2" }
    ],
    troubleshooting: [
      { symptom: 'kind create cluster fails with "Cannot connect to the Docker daemon"', fix: "Start Docker (or Docker Desktop) and make sure your user can run `docker ps` without sudo." },
      { symptom: 'ERROR: failed to create cluster: node(s) already exist for a cluster with the name "kcna"', fix: "Reuse it (`kubectl config use-context kind-kcna`) or delete it first with `kind delete cluster --name kcna`." },
      { symptom: 'kubectl: "The connection to the server localhost:8080 was refused"', fix: "Your kubeconfig has no current context. Run `kubectl config use-context kind-kcna` or `kind export kubeconfig --name kcna`." }
    ],
    cleanup: [DELETE_CLUSTER],
    references: [KIND, { title: "Kubernetes Components", url: "https://kubernetes.io/docs/concepts/overview/components/" }, KUBECTL]
  },
  {
    id: "lab-pods-deployments",
    title: "Pods and Deployments: deploy, scale, self-heal",
    objectives: ["kf-core"],
    scope: "kcna",
    status: "full",
    environment: "kind",
    estMinutes: 35,
    objective: "See the difference between a bare Pod and a Deployment-managed Pod, scale a Deployment, and watch the ReplicaSet controller replace a deleted Pod \u2014 reconciliation in action.",
    prerequisites: [...KIND_PREREQS, "Completed lab-kind-cluster-explore (or equivalent kubectl basics)"],
    architecture: "A **Deployment** owns a **ReplicaSet**, which owns **Pods**. Each controller compares desired state (`spec.replicas`) to actual state and acts on the difference. A bare Pod has no controller \u2014 when it is deleted, nothing recreates it.\n\n```\nDeployment web \u2500\u2500owns\u2500\u2500> ReplicaSet web-<hash> \u2500\u2500owns\u2500\u2500> Pod web-<hash>-<id> (x N)\n```",
    tasks: [
      CLUSTER_TASK,
      {
        title: "Run a bare Pod and delete it",
        instructions: "`kubectl run` creates a single Pod with no controller. Delete it and confirm nothing brings it back.",
        commands: [
          "kubectl run solo --image=nginx:1.27",
          "kubectl get pod solo -o wide",
          "kubectl delete pod solo",
          "kubectl get pods"
        ],
        expected: `pod/solo created
...
pod "solo" deleted
No resources found in default namespace.`,
        hint: "Wait until `solo` is `Running` before deleting so you see the whole lifecycle."
      },
      {
        title: "Create a Deployment",
        instructions: "Create a Deployment with 3 replicas and look at all three layers of objects it creates.",
        commands: [
          "kubectl create deployment web --image=nginx:1.27 --replicas=3",
          "kubectl rollout status deployment/web",
          "kubectl get deployments,replicasets,pods -l app=web"
        ],
        expected: `NAME                  READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/web   3/3     3            3           20s

NAME                             DESIRED   CURRENT   READY   AGE
replicaset.apps/web-<hash>       3         3         3       20s

NAME                  READY   STATUS    RESTARTS   AGE
pod/web-<hash>-xxxxx  1/1     Running   0          20s
...`,
        hint: "`kubectl create deployment` labels everything `app=web` automatically, which is why `-l app=web` works."
      },
      {
        title: "Inspect ownership",
        instructions: "Each Pod records its owner in `metadata.ownerReferences`. Print the owner kind and name of every web Pod.",
        commands: [
          "kubectl get pods -l app=web -o custom-columns=NAME:.metadata.name,OWNER_KIND:.metadata.ownerReferences[0].kind,OWNER:.metadata.ownerReferences[0].name"
        ],
        expected: `NAME                OWNER_KIND   OWNER
web-<hash>-xxxxx    ReplicaSet   web-<hash>
...`
      },
      {
        title: "Scale up and down",
        instructions: "Scale to 5 replicas, then back to 2. Watch which Pods are removed.",
        commands: [
          "kubectl scale deployment web --replicas=5",
          "kubectl get pods -l app=web",
          "kubectl scale deployment web --replicas=2",
          "kubectl get pods -l app=web"
        ],
        expected: `deployment.apps/web scaled
... 5 Pods Running ...
deployment.apps/web scaled
... 2 Pods Running (others Terminating briefly) ...`,
        hint: "Scaling only changes the replica count, so no new ReplicaSet is created \u2014 the pod-template-hash stays the same."
      },
      {
        title: "Self-healing",
        instructions: "Start a watch in a second terminal, then delete one Pod in the first. The ReplicaSet notices actual (1) \u2260 desired (2) and creates a replacement within seconds.",
        commands: [
          "kubectl get pods -l app=web -w",
          "kubectl delete pod $(kubectl get pods -l app=web -o jsonpath='{.items[0].metadata.name}')"
        ],
        expected: `web-<hash>-aaaaa   1/1   Terminating         0   3m
web-<hash>-ccccc   0/1   Pending             0   0s
web-<hash>-ccccc   0/1   ContainerCreating   0   0s
web-<hash>-ccccc   1/1   Running             0   2s`,
        hint: "Stop the watch with Ctrl+C. The replacement has a new name and IP \u2014 that is why clients should use a Service, not Pod IPs."
      },
      {
        title: "From imperative to declarative",
        instructions: "Generate the YAML that `kubectl create` would send, without creating anything, then apply an edited version declaratively.",
        commands: [
          "kubectl create deployment api --image=nginx:1.27-alpine --replicas=2 --dry-run=client -o yaml > api.yaml",
          "cat api.yaml",
          "kubectl apply -f api.yaml",
          "kubectl get deployment api"
        ],
        expected: `deployment.apps/api created
NAME   READY   UP-TO-DATE   AVAILABLE   AGE
api    2/2     2            2           10s`,
        hint: "Edit `replicas` in `api.yaml` and run `kubectl apply -f api.yaml` again \u2014 apply computes the difference and patches only what changed."
      }
    ],
    validation: [
      { description: "web has 2 ready replicas", command: "kubectl get deployment web -o jsonpath='{.status.readyReplicas}'", expected: "2" },
      { description: "api has 2 ready replicas", command: "kubectl get deployment api -o jsonpath='{.status.readyReplicas}'", expected: "2" },
      { description: "Bare Pod is gone for good", command: "kubectl get pod solo", expected: 'Error from server (NotFound): pods "solo" not found' }
    ],
    troubleshooting: [
      { symptom: "Pods stuck in ContainerCreating for a long time", fix: "The node is pulling the image. Check `kubectl describe pod <name>` events; on slow networks wait, or pre-load the image with `kind load docker-image nginx:1.27 --name kcna` after `docker pull nginx:1.27`." },
      { symptom: 'error: failed to create deployment: deployments.apps "web" already exists', fix: "You ran the lab before. Delete it with `kubectl delete deployment web` or continue with the existing one." },
      { symptom: 'Deleting a Pod "does nothing" \u2014 it comes back', fix: "That is the point: delete or scale the **Deployment** to remove Pods permanently." }
    ],
    cleanup: ["kubectl delete deployment web api", "rm -f api.yaml", DELETE_CLUSTER],
    references: [
      { title: "Deployments", url: "https://kubernetes.io/docs/concepts/workloads/controllers/deployment/" },
      { title: "Pods", url: "https://kubernetes.io/docs/concepts/workloads/pods/" },
      KIND
    ]
  },
  {
    id: "lab-services-dns",
    title: "Services and DNS",
    objectives: ["co-networking"],
    scope: "kcna",
    status: "full",
    environment: "kind",
    estMinutes: 35,
    objective: "Give a set of Pods a stable virtual IP and DNS name with a ClusterIP Service, resolve it from another Pod, watch endpoints follow scaling, and understand how NodePort behaves on kind.",
    prerequisites: [...KIND_PREREQS, "Completed lab-pods-deployments"],
    architecture: "A **Service** selects Pods by label; the EndpointSlice controller keeps the list of ready Pod IPs; **kube-proxy** on each node programs rules so traffic to the ClusterIP is spread across those IPs. **CoreDNS** answers `<service>.<namespace>.svc.cluster.local` with the ClusterIP.\n\n```\nclient Pod \u2500\u2500DNS\u2500\u2500> CoreDNS: web.default.svc.cluster.local = 10.96.x.x\nclient Pod \u2500\u2500TCP 10.96.x.x:80\u2500\u2500> kube-proxy rules \u2500\u2500> one of the web Pod IPs:80\n```",
    tasks: [
      CLUSTER_TASK,
      {
        title: "Deploy backends",
        instructions: "Create a 2-replica nginx Deployment and note the Pod IPs.",
        commands: [
          "kubectl create deployment web --image=nginx:1.27 --replicas=2",
          "kubectl rollout status deployment/web",
          "kubectl get pods -l app=web -o wide"
        ],
        expected: `NAME               READY   STATUS    RESTARTS   AGE   IP           NODE
web-<hash>-xxxxx   1/1     Running   0          15s   10.244.0.5   kcna-control-plane
web-<hash>-yyyyy   1/1     Running   0          15s   10.244.0.6   kcna-control-plane`
      },
      {
        title: "Create a ClusterIP Service",
        instructions: "Expose the Deployment on port 80 and confirm that the Service found both Pods.",
        commands: [
          "kubectl expose deployment web --port=80",
          "kubectl get service web",
          "kubectl get endpointslices -l kubernetes.io/service-name=web"
        ],
        expected: `NAME   TYPE        CLUSTER-IP     EXTERNAL-IP   PORT(S)   AGE
web    ClusterIP   10.96.x.x      <none>        80/TCP    5s

NAME        ADDRESSTYPE   PORTS   ENDPOINTS               AGE
web-xxxxx   IPv4          80      10.244.0.5,10.244.0.6   5s`,
        hint: "No `--type` means ClusterIP, the default."
      },
      {
        title: "Resolve and call the Service from a Pod",
        instructions: "Start a throwaway busybox Pod, look at its DNS config, resolve the Service name and fetch the nginx page. `--rm` deletes the Pod when the command ends.",
        commands: [
          "kubectl run dns-test --rm -it --restart=Never --image=busybox:1.36 -- sh -c 'cat /etc/resolv.conf; nslookup web.default.svc.cluster.local; wget -qO- http://web | head -4'"
        ],
        expected: `search default.svc.cluster.local svc.cluster.local cluster.local
nameserver 10.96.0.10
...
Name:	web.default.svc.cluster.local
Address: 10.96.x.x
<!DOCTYPE html>
<html>
<head>
<title>Welcome to nginx!</title>`,
        hint: "The short name `web` works because of the `search` list in resolv.conf. From another namespace you would need `web.default`."
      },
      {
        title: "Endpoints follow the Pods",
        instructions: "Scale to 4 and check the EndpointSlice again, then scale to 0 and check once more.",
        commands: [
          "kubectl scale deployment web --replicas=4",
          "kubectl rollout status deployment/web",
          "kubectl get endpointslices -l kubernetes.io/service-name=web",
          "kubectl scale deployment web --replicas=0",
          "kubectl get endpointslices -l kubernetes.io/service-name=web",
          "kubectl scale deployment web --replicas=2"
        ],
        expected: `web-xxxxx   IPv4   80   10.244.0.5,10.244.0.6,10.244.0.7 + 1 more...
...
web-xxxxx   IPv4   <unset>   <unset>   ...`,
        hint: "With zero endpoints the Service still exists and keeps its ClusterIP \u2014 but connections to it fail."
      },
      {
        title: "NodePort on kind",
        instructions: "Create a second Service of type NodePort. On kind, nodes are Docker containers, so the NodePort is opened **inside the node container**. On Linux the node IP (Docker bridge) is reachable from the host; on macOS/Windows it is not, and `kubectl port-forward` is the portable way in. (To publish NodePorts on localhost, kind needs `extraPortMappings` in a cluster config at creation time.)",
        commands: [
          "kubectl expose deployment web --name=web-np --type=NodePort --port=80",
          "NODE_PORT=$(kubectl get service web-np -o jsonpath='{.spec.ports[0].nodePort}'); echo $NODE_PORT",
          `NODE_IP=$(kubectl get node kcna-control-plane -o jsonpath='{.status.addresses[?(@.type=="InternalIP")].address}'); echo $NODE_IP`,
          "curl -s http://$NODE_IP:$NODE_PORT | head -4   # Linux hosts only",
          "kubectl port-forward service/web 8080:80   # any OS; then in another terminal: curl -s localhost:8080 | head -4"
        ],
        expected: `3xxxx
172.18.0.2
<!DOCTYPE html>
<html>
<head>
<title>Welcome to nginx!</title>`,
        hint: "NodePorts are allocated from 30000\u201332767 by default. Stop port-forward with Ctrl+C."
      }
    ],
    validation: [
      { description: "Service web is ClusterIP", command: "kubectl get service web -o jsonpath='{.spec.type}'", expected: "ClusterIP" },
      { description: "Service web has 2 endpoints", command: `kubectl get endpointslices -l kubernetes.io/service-name=web -o jsonpath='{range .items[*].endpoints[*]}{.addresses[0]}{"\\n"}{end}'`, expected: "two Pod IPs, one per line" },
      { description: "DNS resolves the Service", command: "kubectl run dns-check --rm -it --restart=Never --image=busybox:1.36 -- nslookup web.default.svc.cluster.local", expected: "Address: 10.96.x.x (the ClusterIP)" }
    ],
    troubleshooting: [
      { symptom: `nslookup prints "server can't find web.default.svc.cluster.local"`, fix: "Check CoreDNS is running: `kubectl get pods -n kube-system -l k8s-app=kube-dns`. Check the Service exists in `default` and you typed the namespace correctly." },
      { symptom: 'wget: "Connection refused" or hangs', fix: "Look at endpoints: if empty, the selector does not match (or Pods are not Ready); if present, check the `targetPort` matches the container port." },
      { symptom: 'error: pod "dns-test" already exists', fix: "A previous run was interrupted. `kubectl delete pod dns-test` and run again." },
      { symptom: "curl to NODE_IP:NODE_PORT times out on macOS/Windows", fix: "Expected: the Docker network is inside a VM. Use `kubectl port-forward`, or recreate the cluster with `extraPortMappings`." }
    ],
    cleanup: ["kubectl delete service web web-np", "kubectl delete deployment web", DELETE_CLUSTER],
    references: [
      { title: "Service", url: "https://kubernetes.io/docs/concepts/services-networking/service/" },
      { title: "DNS for Services and Pods", url: "https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/" },
      KIND
    ]
  },
  {
    id: "lab-configmaps-secrets",
    title: "ConfigMaps and Secrets as env vars and files",
    objectives: ["kf-core", "co-security"],
    scope: "kcna",
    status: "full",
    environment: "kind",
    estMinutes: 30,
    objective: "Externalize configuration: create a ConfigMap and a Secret, inject them into a Pod as environment variables and as mounted files, and observe which form picks up later changes.",
    prerequisites: [...KIND_PREREQS, "Completed lab-pods-deployments"],
    architecture: "ConfigMaps and Secrets are namespaced API objects stored in etcd. The **kubelet** reads them when it starts a container: env vars are resolved **once at container start**; mounted volumes are files the kubelet keeps in sync (eventually) with the object.",
    tasks: [
      CLUSTER_TASK,
      {
        title: "Create a ConfigMap and a Secret",
        instructions: "Create both imperatively from literals and inspect them.",
        commands: [
          "kubectl create configmap app-config --from-literal=APP_COLOR=blue --from-literal=APP_MODE=demo",
          "kubectl create secret generic app-secret --from-literal=DB_PASSWORD='s3cr3t-pass'",
          "kubectl get configmap app-config -o yaml",
          "kubectl get secret app-secret -o yaml"
        ],
        expected: `data:
  APP_COLOR: blue
  APP_MODE: demo
...
data:
  DB_PASSWORD: czNjcjN0LXBhc3M=
type: Opaque`,
        hint: "The Secret value is base64, not encrypted. Decode it with `base64 -d`."
      },
      {
        title: "Decode the Secret",
        instructions: "Prove that anyone with `get secrets` permission can read the value.",
        commands: ["kubectl get secret app-secret -o jsonpath='{.data.DB_PASSWORD}' | base64 -d; echo"],
        expected: `s3cr3t-pass`
      },
      {
        title: "Consume them in a Pod",
        instructions: "Apply a Pod that loads every ConfigMap key with `envFrom`, a single Secret key with `secretKeyRef`, and also mounts the ConfigMap as files under `/etc/config`.",
        commands: [
          `kubectl apply -f - <<'EOF'
apiVersion: v1
kind: Pod
metadata:
  name: cfg-demo
spec:
  containers:
  - name: app
    image: busybox:1.36
    command: ["sh", "-c", "sleep 3600"]
    envFrom:
    - configMapRef:
        name: app-config
    env:
    - name: DB_PASSWORD
      valueFrom:
        secretKeyRef:
          name: app-secret
          key: DB_PASSWORD
    volumeMounts:
    - name: config
      mountPath: /etc/config
      readOnly: true
  volumes:
  - name: config
    configMap:
      name: app-config
EOF`,
          "kubectl wait --for=condition=Ready pod/cfg-demo --timeout=60s"
        ],
        expected: `pod/cfg-demo created
pod/cfg-demo condition met`
      },
      {
        title: "Check what the container sees",
        instructions: "Print the env vars and the mounted files.",
        commands: [
          `kubectl exec cfg-demo -- sh -c 'env | grep -E "APP_|DB_"'`,
          "kubectl exec cfg-demo -- ls /etc/config",
          "kubectl exec cfg-demo -- cat /etc/config/APP_COLOR"
        ],
        expected: `APP_COLOR=blue
APP_MODE=demo
DB_PASSWORD=s3cr3t-pass
APP_COLOR
APP_MODE
blue`,
        hint: "Each ConfigMap key becomes one file named after the key."
      },
      {
        title: "Change the ConfigMap",
        instructions: "Update `APP_COLOR` to `green` declaratively (generate YAML and pipe it to apply). After a short delay (typically under a minute or two) the **file** updates, but the **env var** keeps the old value until the container restarts.",
        commands: [
          "kubectl create configmap app-config --from-literal=APP_COLOR=green --from-literal=APP_MODE=demo --dry-run=client -o yaml | kubectl apply -f -",
          "kubectl exec cfg-demo -- cat /etc/config/APP_COLOR",
          "kubectl exec cfg-demo -- printenv APP_COLOR"
        ],
        expected: `configmap/app-config configured
green      # (file \u2014 may take a little while; re-run until it changes)
blue       # (env var \u2014 unchanged)`,
        hint: "A `Warning: resource configmaps/app-config is missing the kubectl.kubernetes.io/last-applied-configuration annotation` is expected the first time you `apply` an object created with `create`."
      }
    ],
    validation: [
      { description: "Env var injected from ConfigMap", command: "kubectl exec cfg-demo -- printenv APP_MODE", expected: "demo" },
      { description: "Secret injected as env var", command: "kubectl exec cfg-demo -- printenv DB_PASSWORD", expected: "s3cr3t-pass" },
      { description: "Mounted file reflects the update", command: "kubectl exec cfg-demo -- cat /etc/config/APP_COLOR", expected: "green" }
    ],
    troubleshooting: [
      { symptom: "Pod shows CreateContainerConfigError", fix: "A referenced ConfigMap/Secret or key does not exist in the Pod's namespace. `kubectl describe pod cfg-demo` names it; create it and the kubelet retries automatically." },
      { symptom: "The mounted file never changes", fix: "Wait a bit longer (kubelet sync period plus cache TTL). Note that volumes mounted with `subPath` never receive updates." },
      { symptom: "error: no such key in the base64 output / garbled value", fix: "Use the jsonpath `{.data.DB_PASSWORD}` exactly and pipe through `base64 -d`; `--from-literal` values with shell special characters need single quotes." }
    ],
    cleanup: ["kubectl delete pod cfg-demo", "kubectl delete configmap app-config", "kubectl delete secret app-secret", DELETE_CLUSTER],
    references: [
      { title: "ConfigMaps", url: "https://kubernetes.io/docs/concepts/configuration/configmap/" },
      { title: "Secrets", url: "https://kubernetes.io/docs/concepts/configuration/secret/" }
    ]
  },
  {
    id: "lab-rolling-update-rollback",
    title: "Rolling updates, rollout history and rollback",
    objectives: ["cad-delivery", "kf-core"],
    scope: "kcna",
    status: "full",
    environment: "kind",
    estMinutes: 35,
    objective: "Ship a new image with zero downtime, record why each revision exists, push a broken release and see how the rolling update limits the damage, then roll back.",
    prerequisites: [...KIND_PREREQS, "Completed lab-pods-deployments"],
    architecture: "Changing a Deployment's Pod template creates a **new ReplicaSet**. The Deployment controller scales the new one up and the old one down in steps bounded by `maxSurge` (extra Pods allowed) and `maxUnavailable` (Pods allowed to be missing). Old ReplicaSets are kept at 0 replicas as **revision history** \u2014 that is what makes `rollout undo` instant.",
    tasks: [
      CLUSTER_TASK,
      {
        title: "Deploy version 1",
        instructions: "Create a 4-replica Deployment and record a change cause.",
        commands: [
          "kubectl create deployment web --image=nginx:1.27 --replicas=4",
          "kubectl rollout status deployment/web",
          'kubectl annotate deployment web kubernetes.io/change-cause="initial release nginx:1.27"'
        ],
        expected: `deployment.apps/web created
deployment "web" successfully rolled out
deployment.apps/web annotated`,
        hint: "`kubectl create deployment` names the container after the image \u2014 here `nginx`. You need that name for `set image`."
      },
      {
        title: "Roll out version 2",
        instructions: "Switch to the alpine variant, watch the rollout, and update the change cause.",
        commands: [
          "kubectl set image deployment/web nginx=nginx:1.27-alpine",
          "kubectl rollout status deployment/web",
          'kubectl annotate deployment web kubernetes.io/change-cause="switch to nginx:1.27-alpine" --overwrite',
          "kubectl get replicasets -l app=web"
        ],
        expected: `deployment.apps/web image updated
Waiting for deployment "web" rollout to finish: 2 out of 4 new replicas have been updated...
...
deployment "web" successfully rolled out
NAME             DESIRED   CURRENT   READY   AGE
web-<hash-1>     0         0         0       3m
web-<hash-2>     4         4         4       30s`,
        hint: "The old ReplicaSet is scaled to 0, not deleted."
      },
      {
        title: "Read the history",
        instructions: "List revisions and inspect the template of one of them.",
        commands: ["kubectl rollout history deployment/web", "kubectl rollout history deployment/web --revision=1"],
        expected: `REVISION  CHANGE-CAUSE
1         initial release nginx:1.27
2         switch to nginx:1.27-alpine
...
    Image:	nginx:1.27`
      },
      {
        title: "Ship a broken release",
        instructions: "Deploy a tag that does not exist. `rollout status` with a timeout fails; the Pods show why. Notice that most old Pods keep running \u2014 `maxUnavailable` (25% of 4 = 1) caps how many can be taken down.",
        commands: [
          "kubectl set image deployment/web nginx=nginx:does-not-exist",
          "kubectl rollout status deployment/web --timeout=60s",
          "kubectl get pods -l app=web"
        ],
        expected: `error: timed out waiting for the condition
NAME               READY   STATUS             RESTARTS   AGE
web-<hash-2>-aaa   1/1     Running            0          4m
web-<hash-2>-bbb   1/1     Running            0          4m
web-<hash-2>-ccc   1/1     Running            0          4m
web-<hash-3>-xxx   0/1     ImagePullBackOff   0          60s
web-<hash-3>-yyy   0/1     ErrImagePull       0          60s`,
        hint: "Without a timeout, `rollout status` waits until `progressDeadlineSeconds` (default 600s) marks the rollout as failed."
      },
      {
        title: "Roll back",
        instructions: "Undo to the previous revision, then jump explicitly to revision 1.",
        commands: [
          "kubectl rollout undo deployment/web",
          "kubectl rollout status deployment/web",
          "kubectl get deployment web -o jsonpath='{.spec.template.spec.containers[0].image}'; echo",
          "kubectl rollout undo deployment/web --to-revision=1",
          "kubectl rollout status deployment/web",
          "kubectl rollout history deployment/web"
        ],
        expected: `deployment.apps/web rolled back
deployment "web" successfully rolled out
nginx:1.27-alpine
deployment.apps/web rolled back
...
REVISION  CHANGE-CAUSE
3         ...
4         switch to nginx:1.27-alpine
5         initial release nginx:1.27`,
        hint: "A rollback re-uses an old template, which then gets a **new** revision number \u2014 the old number disappears from the list."
      },
      {
        title: "Tune the strategy",
        instructions: "Make rollouts never drop below the desired count by setting `maxUnavailable: 0` and `maxSurge: 1`, then trigger a restart rollout.",
        commands: [
          `kubectl patch deployment web -p '{"spec":{"strategy":{"rollingUpdate":{"maxSurge":1,"maxUnavailable":0}}}}'`,
          "kubectl rollout restart deployment/web",
          "kubectl rollout status deployment/web"
        ],
        expected: `deployment.apps/web patched
deployment.apps/web restarted
deployment "web" successfully rolled out`,
        hint: "`rollout restart` changes a template annotation (`kubectl.kubernetes.io/restartedAt`), forcing new Pods with the same image."
      }
    ],
    validation: [
      { description: "Deployment is back on a working image", command: "kubectl get deployment web -o jsonpath='{.spec.template.spec.containers[0].image}'", expected: "nginx:1.27" },
      { description: "All replicas ready", command: "kubectl get deployment web -o jsonpath='{.status.readyReplicas}'", expected: "4" },
      { description: "Strategy tuned", command: "kubectl get deployment web -o jsonpath='{.spec.strategy.rollingUpdate.maxUnavailable}'", expected: "0" }
    ],
    troubleshooting: [
      { symptom: 'error: unable to find container named "web"', fix: "The container is named after the image (`nginx`). Check with `kubectl get deployment web -o jsonpath='{.spec.template.spec.containers[*].name}'`." },
      { symptom: "CHANGE-CAUSE shows <none>", fix: "Annotate the Deployment with `kubernetes.io/change-cause` after each change (the old `--record` flag is deprecated)." },
      { symptom: 'rollout undo says "skipped rollback (current template already matches revision N)"', fix: "You are already on that template. Check `kubectl rollout history` and pick a different `--to-revision`." }
    ],
    cleanup: ["kubectl delete deployment web", DELETE_CLUSTER],
    references: [
      { title: "Deployments \u2014 rolling back", url: "https://kubernetes.io/docs/concepts/workloads/controllers/deployment/" },
      { title: "Performing a Rolling Update (tutorial)", url: "https://kubernetes.io/docs/tutorials/kubernetes-basics/update/update-intro/" }
    ]
  },
  {
    id: "lab-troubleshoot-broken-workloads",
    title: "Troubleshoot broken workloads",
    objectives: ["co-troubleshooting", "cad-debugging"],
    scope: "kcna",
    status: "full",
    environment: "kind",
    estMinutes: 40,
    objective: "Apply three intentionally broken workloads and diagnose each with the standard loop: `get` (what state?) \u2192 `describe` (which events?) \u2192 `logs` (what did the app say?) \u2192 fix the spec.",
    prerequisites: [...KIND_PREREQS, "Completed lab-pods-deployments"],
    architecture: "Each failure stops at a different component: **ImagePullBackOff** \u2014 the kubelet/runtime cannot pull the image; **CrashLoopBackOff** \u2014 the container starts and its process exits; **Pending** \u2014 the scheduler finds no node that fits. Knowing which component is stuck tells you where to look.",
    tasks: [
      CLUSTER_TASK,
      {
        title: "Apply the broken workloads",
        instructions: "Create a namespace and apply all three manifests.",
        commands: [
          "kubectl create namespace broken",
          `kubectl apply -n broken -f - <<'EOF'
apiVersion: apps/v1
kind: Deployment
metadata:
  name: bad-image
spec:
  replicas: 1
  selector:
    matchLabels:
      app: bad-image
  template:
    metadata:
      labels:
        app: bad-image
    spec:
      containers:
      - name: nginx
        image: nginx:1.27-doesnotexist
EOF`,
          `kubectl apply -n broken -f - <<'EOF'
apiVersion: apps/v1
kind: Deployment
metadata:
  name: crasher
spec:
  replicas: 1
  selector:
    matchLabels:
      app: crasher
  template:
    metadata:
      labels:
        app: crasher
    spec:
      containers:
      - name: app
        image: busybox:1.36
        command: ["sh", "-c", "echo starting; test -n \\"$DB_HOST\\" || { echo 'FATAL: DB_HOST not set'; exit 1; }; echo connected to $DB_HOST; sleep 3600"]
EOF`,
          `kubectl apply -n broken -f - <<'EOF'
apiVersion: v1
kind: Pod
metadata:
  name: too-big
spec:
  containers:
  - name: app
    image: nginx:1.27
    resources:
      requests:
        cpu: "64"
        memory: 1Gi
EOF`,
          "kubectl get pods -n broken"
        ],
        expected: `NAME                         READY   STATUS             RESTARTS      AGE
bad-image-<hash>-xxxxx       0/1     ImagePullBackOff   0             45s
crasher-<hash>-yyyyy         0/1     CrashLoopBackOff   2 (20s ago)   45s
too-big                      0/1     Pending            0             45s`,
        hint: "Statuses change over the first minute (ErrImagePull \u2192 ImagePullBackOff, Error \u2192 CrashLoopBackOff). Re-run `get pods` until they settle."
      },
      {
        title: "Diagnose ImagePullBackOff",
        instructions: "Read the kubelet events for the bad-image Pod. Then fix the image tag on the Deployment.",
        commands: [
          "kubectl describe pod -n broken -l app=bad-image | tail -8",
          "kubectl set image deployment/bad-image -n broken nginx=nginx:1.27",
          "kubectl rollout status deployment/bad-image -n broken"
        ],
        expected: `Warning  Failed     ...  kubelet  Failed to pull image "nginx:1.27-doesnotexist": ... not found
Warning  Failed     ...  kubelet  Error: ErrImagePull
Normal   BackOff    ...  kubelet  Back-off pulling image "nginx:1.27-doesnotexist"
...
deployment "bad-image" successfully rolled out`,
        hint: "`not found` = wrong tag/name; `unauthorized` / `denied` = credentials (imagePullSecrets)."
      },
      {
        title: "Diagnose CrashLoopBackOff",
        instructions: "Check the last termination state and the logs of the previous instance, then fix the Deployment by adding the missing env var.",
        commands: [
          'kubectl describe pod -n broken -l app=crasher | grep -A5 "Last State"',
          "kubectl logs -n broken deployment/crasher --previous",
          "kubectl set env deployment/crasher -n broken DB_HOST=db.example.internal",
          "kubectl rollout status deployment/crasher -n broken",
          "kubectl logs -n broken deployment/crasher"
        ],
        expected: `    Last State:     Terminated
      Reason:       Error
      Exit Code:    1
...
starting
FATAL: DB_HOST not set
...
deployment "crasher" successfully rolled out
starting
connected to db.example.internal`,
        hint: "`kubectl logs deployment/<name>` picks one of its Pods for you. `kubectl set env` changes the Pod template, so it triggers a normal rolling update."
      },
      {
        title: "Diagnose Pending",
        instructions: "The Pod requests 64 CPUs \u2014 more than the node has. Read the scheduler event, compare with the node's allocatable CPU, then recreate the Pod with a sane request (most Pod spec fields, including resources, cannot be edited in place).",
        commands: [
          "kubectl describe pod too-big -n broken | tail -4",
          "kubectl get node kcna-control-plane -o jsonpath='{.status.allocatable.cpu}'; echo",
          "kubectl delete pod too-big -n broken",
          `kubectl apply -n broken -f - <<'EOF'
apiVersion: v1
kind: Pod
metadata:
  name: too-big
spec:
  containers:
  - name: app
    image: nginx:1.27
    resources:
      requests:
        cpu: 100m
        memory: 64Mi
EOF`,
          "kubectl get pod too-big -n broken"
        ],
        expected: `Warning  FailedScheduling  ...  default-scheduler  0/1 nodes are available: 1 Insufficient cpu. preemption: 0/1 nodes are available: 1 No preemption victims found for incoming pod.
8
pod "too-big" deleted
pod/too-big created
NAME      READY   STATUS    RESTARTS   AGE
too-big   1/1     Running   0          5s`,
        hint: "Your allocatable CPU equals the number of CPUs Docker gives the kind node, so the number will differ."
      },
      {
        title: "Use events as a timeline",
        instructions: "List everything that happened in the namespace, oldest first.",
        commands: ["kubectl get events -n broken --sort-by=.metadata.creationTimestamp"],
        expected: `LAST SEEN   TYPE      REASON             OBJECT                      MESSAGE
...         Warning   FailedScheduling   pod/too-big                 0/1 nodes are available: 1 Insufficient cpu...
...         Warning   Failed             pod/bad-image-...           Failed to pull image "nginx:1.27-doesnotexist"...
...         Warning   BackOff            pod/crasher-...             Back-off restarting failed container app ...`,
        hint: "Events are kept for a limited time (1 hour by default) \u2014 capture them early when investigating."
      }
    ],
    validation: [
      { description: "All workloads healthy", command: "kubectl get pods -n broken", expected: "every Pod 1/1 Running" },
      { description: "bad-image uses a real tag", command: "kubectl get deployment bad-image -n broken -o jsonpath='{.spec.template.spec.containers[0].image}'", expected: "nginx:1.27" },
      { description: "crasher has DB_HOST set", command: "kubectl get deployment crasher -n broken -o jsonpath='{.spec.template.spec.containers[0].env[0].name}'", expected: "DB_HOST" }
    ],
    troubleshooting: [
      { symptom: "too-big is Running right away", fix: 'Your Docker host exposes 64+ CPUs to the node. Raise the request (e.g. `cpu: "512"`) to force the Pending state.' },
      { symptom: 'kubectl logs --previous: "previous terminated container not found"', fix: "The container has not restarted yet. Wait for `RESTARTS` \u2265 1 and try again." },
      { symptom: 'The Pod "too-big" is invalid: spec: Forbidden: pod updates may not change fields other than ...', fix: "Pod resources are (mostly) immutable. Delete and recreate the Pod \u2014 or better, run it from a Deployment so you can change the template." }
    ],
    cleanup: ["kubectl delete namespace broken", DELETE_CLUSTER],
    references: [
      { title: "Debug Pods", url: "https://kubernetes.io/docs/tasks/debug/debug-application/debug-pods/" },
      { title: "Debug Running Pods", url: "https://kubernetes.io/docs/tasks/debug/debug-application/debug-running-pod/" },
      KUBECTL
    ]
  },
  // ──────────────────────────── DESIGN LABS ────────────────────────────
  {
    id: "lab-storage-pvc",
    title: "Persistent storage with PVCs on kind",
    objectives: ["co-storage"],
    scope: "kcna",
    status: "design",
    environment: "kind",
    estMinutes: 30,
    objective: "Use kind's built-in local-path provisioner to dynamically provision a volume through a PVC, write data, delete the Pod, and prove the data survives.",
    prerequisites: [...KIND_PREREQS, "Completed lab-pods-deployments"],
    architecture: "kind ships a default StorageClass `standard` backed by `rancher.io/local-path`, with `volumeBindingMode: WaitForFirstConsumer` \u2014 the PV is created only when a Pod using the claim is scheduled. Data lives in a directory on the node container.",
    tasks: [
      CLUSTER_TASK,
      {
        title: "Inspect the StorageClass",
        instructions: "Find the default class, its provisioner and binding mode.",
        commands: ["kubectl get storageclass", "kubectl get pods -n local-path-storage"],
        expected: `NAME                 PROVISIONER             RECLAIMPOLICY   VOLUMEBINDINGMODE      ...
standard (default)   rancher.io/local-path   Delete          WaitForFirstConsumer   ...`
      },
      {
        title: "Create a claim",
        instructions: "Create a 1Gi RWO claim. It stays `Pending` until a Pod uses it \u2014 that is expected here.",
        commands: [
          `kubectl apply -f - <<'EOF'
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: data
spec:
  accessModes: ["ReadWriteOnce"]
  resources:
    requests:
      storage: 1Gi
EOF`,
          "kubectl get pvc data",
          "kubectl describe pvc data | tail -2"
        ],
        expected: `data   Pending   ...   standard
... WaitForFirstConsumer  waiting for first consumer to be created before binding`
      },
      {
        title: "Mount it and write data",
        instructions: "Run a Pod that mounts the claim; the PV is provisioned and bound.",
        commands: [
          `kubectl apply -f - <<'EOF'
apiVersion: v1
kind: Pod
metadata:
  name: writer
spec:
  containers:
  - name: app
    image: busybox:1.36
    command: ["sh", "-c", "date >> /data/log.txt; sleep 3600"]
    volumeMounts:
    - name: data
      mountPath: /data
  volumes:
  - name: data
    persistentVolumeClaim:
      claimName: data
EOF`,
          "kubectl wait --for=condition=Ready pod/writer --timeout=90s",
          "kubectl get pvc,pv"
        ],
        expected: `persistentvolumeclaim/data   Bound   pvc-...   1Gi   RWO   standard
persistentvolume/pvc-...     1Gi     RWO   Delete   Bound   default/data   standard`
      },
      {
        title: "Prove persistence",
        instructions: "Delete the Pod, recreate it with the same manifest (re-run the previous apply), and read the file \u2014 it now has two lines.",
        commands: ["kubectl delete pod writer", "kubectl exec writer -- cat /data/log.txt   # after re-applying the writer Pod"],
        expected: `Thu Nov 12 10:00:01 UTC 2026
Thu Nov 12 10:02:37 UTC 2026`
      }
    ],
    validation: [
      { description: "Claim is bound", command: "kubectl get pvc data -o jsonpath='{.status.phase}'", expected: "Bound" },
      { description: "Data survived Pod recreation", command: "kubectl exec writer -- wc -l /data/log.txt", expected: "2 /data/log.txt" }
    ],
    troubleshooting: [
      { symptom: "PVC Pending even after the Pod exists", fix: "`kubectl describe pvc data` and check the local-path-provisioner Pod logs in `local-path-storage`." },
      { symptom: "Deleting the PVC also deleted the data", fix: "Expected with `reclaimPolicy: Delete`. Use a class with `Retain` for data you must keep." }
    ],
    cleanup: ["kubectl delete pod writer", "kubectl delete pvc data", DELETE_CLUSTER],
    references: [
      { title: "Persistent Volumes", url: "https://kubernetes.io/docs/concepts/storage/persistent-volumes/" },
      { title: "Storage Classes", url: "https://kubernetes.io/docs/concepts/storage/storage-classes/" }
    ]
  },
  {
    id: "lab-rbac-serviceaccounts",
    title: "RBAC and ServiceAccounts with kubectl auth can-i",
    objectives: ["co-security"],
    scope: "kcna",
    status: "design",
    environment: "kind",
    estMinutes: 25,
    objective: "Create a ServiceAccount with least-privilege read access to Deployments in one namespace, and verify permissions with `kubectl auth can-i` and impersonation.",
    prerequisites: [...KIND_PREREQS],
    architecture: "Subjects (users, groups, ServiceAccounts) get permissions only through bindings. **Role/RoleBinding** are namespaced; **ClusterRole/ClusterRoleBinding** are cluster-wide. RBAC is additive \u2014 there are no deny rules.",
    tasks: [
      CLUSTER_TASK,
      {
        title: "Create the identity and the role",
        instructions: "Namespace, ServiceAccount, read-only Role for Deployments, and a RoleBinding.",
        commands: [
          "kubectl create namespace dev",
          "kubectl create serviceaccount ci -n dev",
          "kubectl create role deploy-reader --verb=get,list,watch --resource=deployments -n dev",
          "kubectl create rolebinding ci-deploy-reader --role=deploy-reader --serviceaccount=dev:ci -n dev"
        ]
      },
      {
        title: "Check permissions",
        instructions: "Impersonate the ServiceAccount and ask the API server what it may do.",
        commands: [
          "kubectl auth can-i list deployments -n dev --as=system:serviceaccount:dev:ci",
          "kubectl auth can-i delete deployments -n dev --as=system:serviceaccount:dev:ci",
          "kubectl auth can-i list deployments -n default --as=system:serviceaccount:dev:ci",
          "kubectl auth can-i --list -n dev --as=system:serviceaccount:dev:ci"
        ],
        expected: `yes
no
no`,
        hint: "You can impersonate because the kind admin user is cluster-admin."
      },
      {
        title: "Reuse a ClusterRole in one namespace",
        instructions: "Bind the built-in `view` ClusterRole with a RoleBinding \u2014 the rules apply only inside `dev`.",
        commands: [
          "kubectl create rolebinding ci-view --clusterrole=view --serviceaccount=dev:ci -n dev",
          "kubectl auth can-i list pods -n dev --as=system:serviceaccount:dev:ci",
          "kubectl auth can-i list pods -n kube-system --as=system:serviceaccount:dev:ci"
        ],
        expected: `yes
no`
      }
    ],
    validation: [
      { description: "SA can read Deployments in dev", command: "kubectl auth can-i get deployments -n dev --as=system:serviceaccount:dev:ci", expected: "yes" },
      { description: "SA cannot delete", command: "kubectl auth can-i delete deployments -n dev --as=system:serviceaccount:dev:ci", expected: "no" }
    ],
    troubleshooting: [
      { symptom: 'can-i says "no" although you created the binding', fix: "Check the namespace of the RoleBinding and the exact subject string `system:serviceaccount:<ns>:<name>`." }
    ],
    cleanup: ["kubectl delete namespace dev", DELETE_CLUSTER],
    references: [
      { title: "Using RBAC Authorization", url: "https://kubernetes.io/docs/reference/access-authn-authz/rbac/" },
      { title: "RBAC good practices", url: "https://kubernetes.io/docs/concepts/security/rbac-good-practices/" }
    ]
  },
  {
    id: "lab-network-policies",
    title: "NetworkPolicies: default deny and allow-lists",
    objectives: ["co-networking", "co-security"],
    scope: "kcna",
    status: "design",
    environment: "kind",
    estMinutes: 35,
    objective: "Show that Pod-to-Pod traffic is open by default, apply a default-deny ingress policy, then allow only labelled clients.",
    prerequisites: [...KIND_PREREQS, "Completed lab-services-dns"],
    architecture: "NetworkPolicies are enforced by the **CNI plugin**, not by the API server. Recent kind releases ship kindnet with NetworkPolicy support \u2014 **verify** with the default-deny test below. If traffic is not blocked, recreate the cluster with `networking.disableDefaultCNI: true` in a kind config and install a policy-capable CNI such as Calico or Cilium following its kind guide.",
    tasks: [
      CLUSTER_TASK,
      {
        title: "Baseline: everything can talk",
        instructions: "Deploy a server and confirm an unlabelled client can reach it.",
        commands: [
          "kubectl create deployment web --image=nginx:1.27",
          "kubectl expose deployment web --port=80",
          "kubectl rollout status deployment/web",
          "kubectl run client --rm -it --restart=Never --image=busybox:1.36 -- wget -qO- -T 3 http://web | head -4"
        ],
        expected: `<title>Welcome to nginx!</title>`
      },
      {
        title: "Default deny ingress",
        instructions: "Select all Pods in the namespace for Ingress with no allow rules.",
        commands: [
          `kubectl apply -f - <<'EOF'
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: default-deny-ingress
spec:
  podSelector: {}
  policyTypes:
  - Ingress
EOF`,
          "kubectl run client --rm -it --restart=Never --image=busybox:1.36 -- wget -qO- -T 3 http://web"
        ],
        expected: `wget: download timed out`,
        hint: "If the page still loads, your CNI is not enforcing policies \u2014 see the architecture note."
      },
      {
        title: "Allow labelled clients",
        instructions: "Allow ingress to `app=web` only from Pods labelled `access=web`.",
        commands: [
          `kubectl apply -f - <<'EOF'
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: web-allow-clients
spec:
  podSelector:
    matchLabels:
      app: web
  policyTypes:
  - Ingress
  ingress:
  - from:
    - podSelector:
        matchLabels:
          access: web
    ports:
    - protocol: TCP
      port: 80
EOF`,
          "kubectl run client --rm -it --restart=Never --labels=access=web --image=busybox:1.36 -- wget -qO- -T 3 http://web | head -4"
        ],
        expected: `<title>Welcome to nginx!</title>`
      }
    ],
    validation: [
      { description: "Unlabelled client is blocked", command: "kubectl run v1 --rm -it --restart=Never --image=busybox:1.36 -- wget -qO- -T 3 http://web", expected: "download timed out" },
      { description: "Labelled client is allowed", command: "kubectl run v2 --rm -it --restart=Never --labels=access=web --image=busybox:1.36 -- wget -qO- -T 3 http://web", expected: "nginx welcome page HTML" }
    ],
    troubleshooting: [
      { symptom: "Policies have no effect", fix: "The CNI does not enforce NetworkPolicy. Upgrade kind or use Calico/Cilium with `disableDefaultCNI: true`." },
      { symptom: "DNS lookups fail after adding egress policies", fix: "An egress default-deny also blocks DNS. Allow UDP/TCP 53 to the CoreDNS Pods in `kube-system`." }
    ],
    cleanup: ["kubectl delete networkpolicy default-deny-ingress web-allow-clients", "kubectl delete service,deployment web", DELETE_CLUSTER],
    references: [
      { title: "Network Policies", url: "https://kubernetes.io/docs/concepts/services-networking/network-policies/" },
      KIND
    ]
  },
  {
    id: "lab-helm-basics",
    title: "Helm: install, upgrade, rollback",
    objectives: ["cad-delivery"],
    scope: "kcna",
    status: "design",
    environment: "kind",
    estMinutes: 30,
    objective: "Package an app as a Helm chart, install it as a release, upgrade it with new values, and roll back \u2014 without needing any external chart repository.",
    prerequisites: [...KIND_PREREQS, "Helm v3 installed (https://helm.sh/docs/intro/install/)"],
    architecture: "A **chart** is a package of templates plus `values.yaml`. Installing it creates a **release**; every install/upgrade/rollback creates a new **revision**, stored as a Secret in the release namespace. Helm renders templates client-side and sends plain manifests to the API server.",
    tasks: [
      CLUSTER_TASK,
      {
        title: "Scaffold and render a chart",
        instructions: "`helm create` generates a working nginx chart. Render it locally to see the YAML it produces.",
        commands: ["helm create demo", "helm template demo ./demo | head -40", "helm lint ./demo"],
        expected: `==> Linting ./demo
1 chart(s) linted, 0 chart(s) failed`
      },
      {
        title: "Install and upgrade",
        instructions: "Install, then upgrade to 3 replicas via `--set`.",
        commands: [
          "helm install demo ./demo",
          "kubectl get deployment demo",
          "helm upgrade demo ./demo --set replicaCount=3",
          "helm history demo"
        ],
        expected: `REVISION  UPDATED  STATUS      CHART        APP VERSION  DESCRIPTION
1         ...      superseded  demo-0.1.0   1.16.0       Install complete
2         ...      deployed    demo-0.1.0   1.16.0       Upgrade complete`
      },
      {
        title: "Roll back",
        instructions: "Return to revision 1 and confirm replicas.",
        commands: ["helm rollback demo 1", "helm history demo", "kubectl get deployment demo"],
        expected: `Rollback was a success! Happy Helming!
...
3         ...      deployed    demo-0.1.0   1.16.0       Rollback to 1`
      }
    ],
    validation: [
      { description: "Release deployed", command: "helm status demo", expected: "STATUS: deployed" },
      { description: "Back at 1 replica", command: "kubectl get deployment demo -o jsonpath='{.spec.replicas}'", expected: "1" }
    ],
    troubleshooting: [
      { symptom: "Error: INSTALLATION FAILED: cannot re-use a name that is still in use", fix: "A release `demo` already exists. Use `helm upgrade --install demo ./demo` or uninstall it first." }
    ],
    cleanup: ["helm uninstall demo", "rm -rf demo", DELETE_CLUSTER],
    references: [
      { title: "Helm docs", url: "https://helm.sh/docs/" },
      { title: "Helm quickstart", url: "https://helm.sh/docs/intro/quickstart/" }
    ]
  },
  {
    id: "lab-jobs-cronjobs",
    title: "Jobs and CronJobs",
    objectives: ["kf-core"],
    scope: "kcna",
    status: "design",
    environment: "kind",
    estMinutes: 25,
    objective: "Run finite work to completion with a Job, schedule recurring work with a CronJob, and trigger a CronJob manually.",
    prerequisites: [...KIND_PREREQS],
    architecture: "A **Job** creates Pods until the requested number of completions succeed, retrying failures up to `backoffLimit` (default 6). A **CronJob** creates a Job on each schedule tick. Job Pods use `restartPolicy: OnFailure` or `Never` \u2014 never `Always`.",
    tasks: [
      CLUSTER_TASK,
      {
        title: "Run a Job",
        instructions: "Create a Job, wait for completion and read its output.",
        commands: [
          "kubectl create job hello --image=busybox:1.36 -- sh -c 'echo working; sleep 5; echo done'",
          "kubectl wait --for=condition=complete job/hello --timeout=90s",
          "kubectl get job hello",
          "kubectl logs job/hello"
        ],
        expected: `NAME    STATUS     COMPLETIONS   DURATION   AGE
hello   Complete   1/1           8s         15s
working
done`
      },
      {
        title: "Schedule a CronJob",
        instructions: "Run every minute; watch Jobs appear. Then trigger one immediately from the CronJob template.",
        commands: [
          "kubectl create cronjob tick --image=busybox:1.36 --schedule='*/1 * * * *' -- date",
          "kubectl get cronjob tick",
          "kubectl get jobs -w",
          "kubectl create job tick-manual --from=cronjob/tick"
        ],
        expected: `NAME   SCHEDULE      TIMEZONE   SUSPEND   ACTIVE   LAST SCHEDULE   AGE
tick   */1 * * * *   <none>     False     0        <none>          5s`,
        hint: "By default only the last 3 successful and 1 failed Jobs are kept (`successfulJobsHistoryLimit` / `failedJobsHistoryLimit`)."
      }
    ],
    validation: [
      { description: "Job completed", command: "kubectl get job hello -o jsonpath='{.status.succeeded}'", expected: "1" },
      { description: "CronJob has run", command: "kubectl get cronjob tick -o jsonpath='{.status.lastScheduleTime}'", expected: "a timestamp" }
    ],
    troubleshooting: [
      { symptom: "Job never completes and keeps creating Pods", fix: "The command exits non-zero. Check `kubectl logs` of a failed Pod; the Job gives up after `backoffLimit` retries." }
    ],
    cleanup: ["kubectl delete cronjob tick", "kubectl delete job hello tick-manual", DELETE_CLUSTER],
    references: [
      { title: "Jobs", url: "https://kubernetes.io/docs/concepts/workloads/controllers/job/" },
      { title: "CronJob", url: "https://kubernetes.io/docs/concepts/workloads/controllers/cron-jobs/" }
    ]
  },
  {
    id: "lab-probes-resources-qos",
    title: "Probes, resource requests/limits and QoS classes",
    objectives: ["kf-scheduling", "co-troubleshooting"],
    scope: "kcna",
    status: "design",
    environment: "kind",
    estMinutes: 35,
    objective: "Watch a liveness probe restart a container, see a readiness probe remove a Pod from a Service, and observe how requests/limits decide a Pod's QoS class.",
    prerequisites: [...KIND_PREREQS, "Completed lab-services-dns"],
    architecture: "The **kubelet** runs probes. Liveness failure \u2192 container restart; readiness failure \u2192 removed from endpoints; startup probe \u2192 delays the others. QoS: **Guaranteed** (requests = limits for CPU and memory in every container), **Burstable** (some requests/limits), **BestEffort** (none) \u2014 BestEffort Pods are evicted first under node pressure.",
    tasks: [
      CLUSTER_TASK,
      {
        title: "Liveness probe restarts",
        instructions: "The container deletes its health file after 30s; the exec probe starts failing and the kubelet restarts it.",
        commands: [
          `kubectl apply -f - <<'EOF'
apiVersion: v1
kind: Pod
metadata:
  name: liveness-demo
spec:
  containers:
  - name: app
    image: busybox:1.36
    command: ["sh", "-c", "touch /tmp/healthy; sleep 30; rm -f /tmp/healthy; sleep 600"]
    livenessProbe:
      exec:
        command: ["cat", "/tmp/healthy"]
      initialDelaySeconds: 5
      periodSeconds: 5
EOF`,
          "kubectl get pod liveness-demo -w",
          'kubectl describe pod liveness-demo | grep -E "Unhealthy|Killing"'
        ],
        expected: `liveness-demo   1/1   Running   1 (2s ago)   75s
... Liveness probe failed: cat: can't open '/tmp/healthy': No such file or directory
... Container app failed liveness probe, will be restarted`
      },
      {
        title: "QoS classes",
        instructions: "Create three Pods with different resource settings and read their QoS class.",
        commands: [
          "kubectl run besteffort --image=nginx:1.27",
          `kubectl apply -f - <<'EOF'
apiVersion: v1
kind: Pod
metadata:
  name: guaranteed
spec:
  containers:
  - name: app
    image: nginx:1.27
    resources:
      requests: {cpu: 100m, memory: 64Mi}
      limits: {cpu: 100m, memory: 64Mi}
EOF`,
          `kubectl apply -f - <<'EOF'
apiVersion: v1
kind: Pod
metadata:
  name: burstable
spec:
  containers:
  - name: app
    image: nginx:1.27
    resources:
      requests: {cpu: 50m, memory: 32Mi}
      limits: {memory: 128Mi}
EOF`,
          "kubectl get pods besteffort guaranteed burstable -o custom-columns=NAME:.metadata.name,QOS:.status.qosClass"
        ],
        expected: `NAME         QOS
besteffort   BestEffort
guaranteed   Guaranteed
burstable    Burstable`
      }
    ],
    validation: [
      { description: "Liveness Pod has restarted", command: "kubectl get pod liveness-demo -o jsonpath='{.status.containerStatuses[0].restartCount}'", expected: ">= 1" },
      { description: "Guaranteed QoS assigned", command: "kubectl get pod guaranteed -o jsonpath='{.status.qosClass}'", expected: "Guaranteed" }
    ],
    troubleshooting: [
      { symptom: "Restarts never happen", fix: "Wait at least 30s + 3 failed probes (failureThreshold 3 \xD7 periodSeconds 5)." }
    ],
    cleanup: ["kubectl delete pod liveness-demo besteffort guaranteed burstable", DELETE_CLUSTER],
    references: [
      { title: "Configure Liveness, Readiness and Startup Probes", url: "https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/" },
      { title: "Pod Quality of Service Classes", url: "https://kubernetes.io/docs/concepts/workloads/pods/pod-qos/" }
    ]
  },
  {
    id: "lab-hpa-metrics-server",
    title: "Horizontal Pod Autoscaling with metrics-server",
    objectives: ["cna-ecosystem", "kf-scheduling"],
    scope: "kcna",
    status: "design",
    environment: "kind",
    estMinutes: 35,
    objective: "Install metrics-server, create an HPA targeting CPU utilization, generate load and watch replicas scale out and back in.",
    prerequisites: [...KIND_PREREQS, "Completed lab-services-dns"],
    architecture: "metrics-server scrapes kubelet resource metrics and serves the `metrics.k8s.io` API (used by `kubectl top` and the HPA). The HPA controller compares observed CPU usage to **requests** and adjusts `replicas`. kind kubelets use self-signed serving certs, so metrics-server needs `--kubelet-insecure-tls` (lab only).",
    tasks: [
      CLUSTER_TASK,
      {
        title: "Install metrics-server",
        instructions: "Apply the release manifest and add the insecure-TLS flag for kind.",
        commands: [
          "kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml",
          `kubectl patch deployment metrics-server -n kube-system --type=json -p '[{"op":"add","path":"/spec/template/spec/containers/0/args/-","value":"--kubelet-insecure-tls"}]'`,
          "kubectl rollout status deployment/metrics-server -n kube-system",
          "kubectl top nodes"
        ],
        expected: `NAME                 CPU(cores)   CPU(%)   MEMORY(bytes)   MEMORY(%)
kcna-control-plane   150m         1%       700Mi           9%`,
        hint: '`kubectl top` may say "metrics not available yet" for the first minute.'
      },
      {
        title: "Deploy and autoscale",
        instructions: "Create a Deployment with a small CPU request and an `autoscaling/v2` HPA targeting 50% CPU.",
        commands: [
          "kubectl create deployment web --image=nginx:1.27",
          "kubectl set resources deployment web --requests=cpu=50m",
          "kubectl expose deployment web --port=80",
          `kubectl apply -f - <<'EOF'
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: web
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: web
  minReplicas: 1
  maxReplicas: 5
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 50
EOF`,
          "kubectl get hpa web"
        ]
      },
      {
        title: "Generate load",
        instructions: "Run a busy client and watch the HPA. Delete the client and watch it scale down (after the default 5-minute stabilization window).",
        commands: [
          "kubectl run load --image=busybox:1.36 --restart=Never -- sh -c 'while true; do wget -q -O- http://web >/dev/null; done'",
          "kubectl get hpa web -w",
          "kubectl delete pod load"
        ],
        expected: `NAME   REFERENCE        TARGETS         MINPODS   MAXPODS   REPLICAS
web    Deployment/web   cpu: 180%/50%   1         5         4`
      }
    ],
    validation: [
      { description: "HPA scaled out under load", command: "kubectl get hpa web -o jsonpath='{.status.currentReplicas}'", expected: "> 1 while load runs" }
    ],
    troubleshooting: [
      { symptom: "TARGETS shows <unknown>/50%", fix: "metrics-server is not ready, or the Deployment has no CPU **request** \u2014 utilization is a percentage of the request." }
    ],
    cleanup: ["kubectl delete hpa web", "kubectl delete service,deployment web", "kubectl delete pod load --ignore-not-found", DELETE_CLUSTER],
    references: [
      { title: "Horizontal Pod Autoscaling", url: "https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/" },
      { title: "HPA walkthrough", url: "https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale-walkthrough/" }
    ]
  },
  {
    id: "lab-prometheus-stack",
    title: "Monitoring with kube-prometheus-stack",
    objectives: ["cna-observability"],
    scope: "beyond",
    status: "design",
    environment: "kind",
    estMinutes: 45,
    objective: "Install Prometheus, Alertmanager and Grafana with the community Helm chart, run a few PromQL queries and open a prebuilt dashboard. KCNA only expects you to understand the concepts (pull model, exporters, PromQL, Alertmanager) \u2014 operating the stack is beyond the exam.",
    prerequisites: [...KIND_PREREQS, "Helm v3 installed", "At least 4 GB RAM available to Docker"],
    architecture: "The chart installs the **Prometheus Operator**, which manages Prometheus and Alertmanager via CRDs (`ServiceMonitor`, `PrometheusRule`), plus **node-exporter** (DaemonSet), **kube-state-metrics** and **Grafana**. Prometheus **pulls** (scrapes) `/metrics` endpoints on an interval.",
    tasks: [
      CLUSTER_TASK,
      {
        title: "Install the chart",
        instructions: "Add the repository and install into a `monitoring` namespace.",
        commands: [
          "helm repo add prometheus-community https://prometheus-community.github.io/helm-charts",
          "helm repo update",
          "helm install kps prometheus-community/kube-prometheus-stack -n monitoring --create-namespace",
          "kubectl get pods -n monitoring",
          "kubectl get svc -n monitoring"
        ],
        hint: "Service names are derived from the release name; read them from `kubectl get svc -n monitoring` before port-forwarding."
      },
      {
        title: "Query Prometheus",
        instructions: "Port-forward to the Prometheus Service, open http://localhost:9090 and try `up`, then `sum by (namespace) (kube_pod_info)`.",
        commands: ["kubectl port-forward -n monitoring svc/kps-kube-prometheus-stack-prometheus 9090:9090"]
      },
      {
        title: "Open Grafana",
        instructions: 'Read the generated admin password, port-forward and browse the "Kubernetes / Compute Resources" dashboards.',
        commands: [
          "kubectl get secret kps-grafana -n monitoring -o jsonpath='{.data.admin-password}' | base64 -d; echo",
          "kubectl port-forward -n monitoring svc/kps-grafana 3000:80"
        ]
      }
    ],
    validation: [
      { description: "Prometheus Pod running", command: "kubectl get pods -n monitoring -l app.kubernetes.io/name=prometheus", expected: "2/2 Running" }
    ],
    troubleshooting: [
      { symptom: "Pods Pending or OOMKilled", fix: "Give Docker more memory; the full stack needs a few GB." },
      { symptom: "Some control-plane targets are down (etcd, scheduler, controller-manager)", fix: "Expected on kind: those components bind to localhost on the node. Ignore for this lab." }
    ],
    cleanup: ["helm uninstall kps -n monitoring", "kubectl delete namespace monitoring", DELETE_CLUSTER],
    references: [
      { title: "Prometheus overview", url: "https://prometheus.io/docs/introduction/overview/" },
      { title: "Helm docs", url: "https://helm.sh/docs/" }
    ]
  },
  {
    id: "lab-gitops-argocd",
    title: "GitOps with Argo CD on kind",
    objectives: ["cad-delivery"],
    scope: "beyond",
    status: "design",
    environment: "kind",
    estMinutes: 45,
    objective: "Install Argo CD, point an Application at a public Git repository, and watch the controller sync and self-heal. KCNA asks for GitOps principles and tool recognition; running Argo CD is beyond the exam.",
    prerequisites: [...KIND_PREREQS],
    architecture: "Argo CD runs **inside** the cluster and **pulls** desired state from Git. An `Application` CR maps a repo path to a destination namespace. With automated sync + self-heal, manual drift in the cluster is reverted to what Git says.",
    tasks: [
      CLUSTER_TASK,
      {
        title: "Install Argo CD",
        instructions: "Apply the upstream install manifest and wait for the server.",
        commands: [
          "kubectl create namespace argocd",
          "kubectl apply -n argocd --server-side -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml",
          "kubectl rollout status deployment/argocd-server -n argocd",
          "kubectl get secret argocd-initial-admin-secret -n argocd -o jsonpath='{.data.password}' | base64 -d; echo",
          "kubectl port-forward svc/argocd-server -n argocd 8080:443"
        ],
        hint: "Log in at https://localhost:8080 as `admin` (accept the self-signed certificate)."
      },
      {
        title: "Create an Application",
        instructions: "Sync the public guestbook example with automated sync and self-heal.",
        commands: [
          `kubectl apply -f - <<'EOF'
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: guestbook
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/argoproj/argocd-example-apps.git
    targetRevision: HEAD
    path: guestbook
  destination:
    server: https://kubernetes.default.svc
    namespace: guestbook
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
    - CreateNamespace=true
EOF`,
          "kubectl get applications -n argocd"
        ],
        expected: `NAME        SYNC STATUS   HEALTH STATUS
guestbook   Synced        Healthy`
      },
      {
        title: "Watch self-heal",
        instructions: "Scale the Deployment by hand; Argo CD reverts it to the replica count in Git.",
        commands: ["kubectl scale deployment guestbook-ui -n guestbook --replicas=3", "kubectl get deployment guestbook-ui -n guestbook -w"]
      }
    ],
    validation: [
      { description: "Application synced", command: "kubectl get application guestbook -n argocd -o jsonpath='{.status.sync.status}'", expected: "Synced" }
    ],
    troubleshooting: [
      { symptom: 'CRD apply error "metadata.annotations: Too long"', fix: "Use server-side apply (`--server-side`) as shown; client-side apply stores the whole object in an annotation." }
    ],
    cleanup: ["kubectl delete application guestbook -n argocd", "kubectl delete namespace argocd guestbook", DELETE_CLUSTER],
    references: [
      { title: "Argo CD documentation", url: "https://argo-cd.readthedocs.io/" },
      { title: "OpenGitOps / CNCF projects", url: "https://www.cncf.io/projects/" }
    ]
  }
];

// ../../packages/content/src/practice/terminal.ts
var terminalChallenges = [
  {
    id: "term-explore-cluster",
    title: "First look at a new cluster",
    objective: "kf-core",
    lessonId: "cluster-architecture",
    difficulty: 1,
    scenario: "You just received a kubeconfig for a small training cluster (one control-plane node, two workers). Before deploying anything, get oriented: which nodes exist, which namespaces exist, and what is already running.",
    steps: [
      {
        task: "List the nodes in the cluster and check that they are all `Ready`.",
        expect: [{ verb: "get", resource: "nodes" }],
        output: `NAME                 STATUS   ROLES           AGE   VERSION
kcna-control-plane   Ready    control-plane   12d   v1.31.2
kcna-worker          Ready    <none>          12d   v1.31.2
kcna-worker2         Ready    <none>          12d   v1.31.2`,
        hint: "Nodes are a cluster-scoped resource: kubectl get nodes",
        explanation: "Nodes are cluster-scoped, so no namespace is involved. `ROLES` is derived from the `node-role.kubernetes.io/...` labels; worker nodes usually show `<none>`. `Ready` means the kubelet is reporting healthy status to the API server."
      },
      {
        task: "List the namespaces in the cluster.",
        expect: [{ verb: "get", resource: "namespaces" }],
        output: `NAME                 STATUS   AGE
default              Active   12d
kube-node-lease      Active   12d
kube-public          Active   12d
kube-system          Active   12d
local-path-storage   Active   12d
shop                 Active   3d`,
        hint: "Namespaces are also cluster-scoped. The short name is ns.",
        explanation: "Every cluster starts with `default`, `kube-system`, `kube-public` and `kube-node-lease`. `kube-node-lease` holds the Lease objects nodes use as heartbeats. Namespaces themselves are not namespaced."
      },
      {
        task: "List Pods across **all** namespaces to see what is already running.",
        expect: [{ verb: "get", resource: "pods", flags: { "all-namespaces": "" } }],
        output: `NAMESPACE            NAME                                         READY   STATUS    RESTARTS   AGE
kube-system          coredns-7db6d8ff4d-4kz9p                     1/1     Running   0          12d
kube-system          coredns-7db6d8ff4d-qv7mt                     1/1     Running   0          12d
kube-system          etcd-kcna-control-plane                      1/1     Running   0          12d
kube-system          kindnet-6wq2d                                1/1     Running   0          12d
kube-system          kindnet-b8x4n                                1/1     Running   0          12d
kube-system          kindnet-lm2rc                                1/1     Running   0          12d
kube-system          kube-apiserver-kcna-control-plane            1/1     Running   0          12d
kube-system          kube-controller-manager-kcna-control-plane   1/1     Running   0          12d
kube-system          kube-proxy-5hzcj                             1/1     Running   0          12d
kube-system          kube-proxy-9tfqw                             1/1     Running   0          12d
kube-system          kube-proxy-xr7dk                             1/1     Running   0          12d
kube-system          kube-scheduler-kcna-control-plane            1/1     Running   0          12d
local-path-storage   local-path-provisioner-6f8956fb48-zw5vh      1/1     Running   0          12d
shop                 cart-5d7c9b6f4-hm2xq                         1/1     Running   0          3d`,
        hint: "Use -A (or --all-namespaces) with kubectl get pods.",
        explanation: "Without `-A` kubectl only shows the current namespace (usually `default`). The control-plane components (`kube-apiserver`, `etcd`, `kube-scheduler`, `kube-controller-manager`) run here as static Pods on the control-plane node. `kube-proxy` and the CNI agent (`kindnet`) run once per node via DaemonSets."
      },
      {
        task: "Show the Pods in `kube-system` with extra columns so you can see **which node** each one runs on.",
        expect: [{ verb: "get", resource: "pods", namespace: "kube-system", flags: { output: "wide" } }],
        output: `NAME                                         READY   STATUS    RESTARTS   AGE   IP           NODE                 NOMINATED NODE   READINESS GATES
coredns-7db6d8ff4d-4kz9p                     1/1     Running   0          12d   10.244.0.3   kcna-control-plane   <none>           <none>
coredns-7db6d8ff4d-qv7mt                     1/1     Running   0          12d   10.244.0.2   kcna-control-plane   <none>           <none>
etcd-kcna-control-plane                      1/1     Running   0          12d   172.18.0.4   kcna-control-plane   <none>           <none>
kindnet-6wq2d                                1/1     Running   0          12d   172.18.0.4   kcna-control-plane   <none>           <none>
kindnet-b8x4n                                1/1     Running   0          12d   172.18.0.2   kcna-worker          <none>           <none>
kindnet-lm2rc                                1/1     Running   0          12d   172.18.0.3   kcna-worker2         <none>           <none>
kube-apiserver-kcna-control-plane            1/1     Running   0          12d   172.18.0.4   kcna-control-plane   <none>           <none>
kube-controller-manager-kcna-control-plane   1/1     Running   0          12d   172.18.0.4   kcna-control-plane   <none>           <none>
kube-proxy-5hzcj                             1/1     Running   0          12d   172.18.0.4   kcna-control-plane   <none>           <none>
kube-proxy-9tfqw                             1/1     Running   0          12d   172.18.0.2   kcna-worker          <none>           <none>
kube-proxy-xr7dk                             1/1     Running   0          12d   172.18.0.3   kcna-worker2         <none>           <none>
kube-scheduler-kcna-control-plane            1/1     Running   0          12d   172.18.0.4   kcna-control-plane   <none>           <none>`,
        hint: "Combine -n kube-system with -o wide.",
        explanation: "`-o wide` adds the Pod IP and node. Notice that `kube-proxy` and `kindnet` use the **node IP** (they run with `hostNetwork: true`), while CoreDNS gets an address from the Pod CIDR (`10.244.x.x`)."
      }
    ]
  },
  {
    id: "term-scale-deployment",
    title: "Inspect and scale a Deployment",
    objective: "kf-core",
    lessonId: "replicasets-and-deployments",
    difficulty: 1,
    scenario: "A Deployment called `web` runs the storefront in the `default` namespace. Traffic is about to spike for a sale. Inspect it, then scale it from 3 to 5 replicas and confirm the new Pods.",
    steps: [
      {
        task: "List the Deployments in the current namespace.",
        expect: [{ verb: "get", resource: "deployments" }],
        output: `NAME   READY   UP-TO-DATE   AVAILABLE   AGE
web    3/3     3            3            2d`,
        hint: "kubectl get deployments (short name: deploy)",
        explanation: "`READY 3/3` = ready replicas / desired replicas. `UP-TO-DATE` counts replicas matching the current Pod template; `AVAILABLE` counts replicas that have been ready for at least `minReadySeconds`."
      },
      {
        task: "Describe the `web` Deployment to see its selector, strategy and Pod template.",
        expect: [{ verb: "describe", resource: "deployments", name: "web" }],
        output: `Name:                   web
Namespace:              default
CreationTimestamp:      Mon, 09 Nov 2026 10:14:02 +0000
Labels:                 app=web
Selector:               app=web
Replicas:               3 desired | 3 updated | 3 total | 3 available | 0 unavailable
StrategyType:           RollingUpdate
MinReadySeconds:        0
RollingUpdateStrategy:  25% max unavailable, 25% max surge
Pod Template:
  Labels:  app=web
  Containers:
   nginx:
    Image:        nginx:1.27
    Port:         80/TCP
    Host Port:    0/TCP
    Environment:  <none>
    Mounts:       <none>
  Volumes:        <none>
Conditions:
  Type           Status  Reason
  ----           ------  ------
  Available      True    MinimumReplicasAvailable
  Progressing    True    NewReplicaSetAvailable
OldReplicaSets:  <none>
NewReplicaSet:   web-6c9f8d7b54 (3/3 replicas created)
Events:          <none>`,
        hint: "kubectl describe deployment web",
        explanation: "The Deployment does not own Pods directly: it owns the ReplicaSet `web-6c9f8d7b54`, which owns the Pods. The default strategy is `RollingUpdate` with 25% max unavailable / 25% max surge."
      },
      {
        task: "Scale `web` to **5** replicas.",
        expect: [{ verb: "scale", resource: "deployments", name: "web", flags: { replicas: "5" } }],
        output: `deployment.apps/web scaled`,
        hint: "kubectl scale deployment web --replicas=5",
        explanation: "`kubectl scale` updates `spec.replicas`. The Deployment controller passes the new count to its ReplicaSet, and the ReplicaSet controller creates two more Pods. Note: if this Deployment is managed by GitOps or an HPA, an imperative scale will be overwritten."
      },
      {
        task: "List only the Pods that belong to `web` using its label selector.",
        expect: [{ verb: "get", resource: "pods", flags: { selector: "app=web" } }],
        output: `NAME                   READY   STATUS    RESTARTS   AGE
web-6c9f8d7b54-2kxbz   1/1     Running   0          2d
web-6c9f8d7b54-8hq4n   1/1     Running   0          2d
web-6c9f8d7b54-tm7vd   1/1     Running   0          2d
web-6c9f8d7b54-pz5wr   1/1     Running   0          9s
web-6c9f8d7b54-r4lcj   1/1     Running   0          9s`,
        hint: "Use -l app=web (the selector shown by describe).",
        explanation: "Pod names are `<replicaset-name>-<random suffix>`, and the ReplicaSet name is `<deployment>-<pod-template-hash>`. The two new Pods share the same template hash because only the replica count changed, not the template."
      }
    ]
  },
  {
    id: "term-crashloop",
    title: "Diagnose a CrashLoopBackOff",
    objective: "co-troubleshooting",
    lessonId: "troubleshooting-workloads",
    difficulty: 2,
    scenario: "After a config change, users report the `api` service is down. The Deployment `api` in namespace `default` was updated ten minutes ago. Find out why its Pod keeps restarting.",
    steps: [
      {
        task: "List the Pods and spot the unhealthy one.",
        expect: [{ verb: "get", resource: "pods" }],
        output: `NAME                   READY   STATUS             RESTARTS      AGE
api-5f7b8c9d6-x2kqp    0/1     CrashLoopBackOff   6 (42s ago)   9m48s
web-6c9f8d7b54-2kxbz   1/1     Running            0             2d`,
        hint: "kubectl get pods",
        explanation: "`CrashLoopBackOff` is not a crash reason \u2014 it means the container keeps exiting and the kubelet is waiting an increasing back-off delay (up to 5 minutes) before restarting it again."
      },
      {
        task: "Describe the failing Pod `api-5f7b8c9d6-x2kqp` and look at the container state and events.",
        expect: [{ verb: "describe", resource: "pods", name: "api-5f7b8c9d6-x2kqp" }],
        output: `Name:             api-5f7b8c9d6-x2kqp
Namespace:        default
Node:             kcna-worker2/172.18.0.3
Status:           Running
IP:               10.244.2.17
Controlled By:    ReplicaSet/api-5f7b8c9d6
Containers:
  api:
    Image:          busybox:1.36
    Command:
      sh
      -c
      test -n "$DATABASE_URL" || { echo "FATAL: DATABASE_URL is not set"; exit 1; }; sleep 3600
    State:          Waiting
      Reason:       CrashLoopBackOff
    Last State:     Terminated
      Reason:       Error
      Exit Code:    1
      Started:      Thu, 12 Nov 2026 09:31:05 +0000
      Finished:     Thu, 12 Nov 2026 09:31:05 +0000
    Ready:          False
    Restart Count:  6
Events:
  Type     Reason     Age                    From               Message
  ----     ------     ----                   ----               -------
  Normal   Scheduled  9m48s                  default-scheduler  Successfully assigned default/api-5f7b8c9d6-x2kqp to kcna-worker2
  Normal   Pulled     3m12s (x7 over 9m47s)  kubelet            Container image "busybox:1.36" already present on machine
  Normal   Created    3m12s (x7 over 9m47s)  kubelet            Created container api
  Normal   Started    3m12s (x7 over 9m47s)  kubelet            Started container api
  Warning  BackOff    42s (x41 over 9m45s)   kubelet            Back-off restarting failed container api in pod api-5f7b8c9d6-x2kqp_default(3b1f...)`,
        hint: "kubectl describe pod <name>",
        explanation: "The image pulled and the container started, so this is not an image or scheduling problem. `Last State: Terminated, Exit Code: 1` says the **process itself** exited with an error right after starting. The next stop is the logs of that previous run."
      },
      {
        task: "Show the logs of the **previous** (crashed) container instance.",
        expect: [{ verb: "logs", name: "api-5f7b8c9d6-x2kqp", flags: { previous: "" } }],
        output: `FATAL: DATABASE_URL is not set`,
        hint: "kubectl logs <pod> --previous (or -p)",
        explanation: "Plain `kubectl logs` shows the current container instance, which may have just restarted and printed nothing yet. `--previous` shows the output of the last terminated instance \u2014 usually where the real error is. Here the app requires `DATABASE_URL`, which the recent change removed from the Pod template."
      },
      {
        task: "Confirm the cause: print the Deployment `api` as YAML and check its container `env`.",
        expect: [{ verb: "get", resource: "deployments", name: "api", flags: { output: "yaml" } }],
        output: `apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: api
  template:
    metadata:
      labels:
        app: api
    spec:
      containers:
      - name: api
        image: busybox:1.36
        command: ["sh", "-c", "test -n \\"$DATABASE_URL\\" || { echo \\"FATAL: DATABASE_URL is not set\\"; exit 1; }; sleep 3600"]
        env:
        - name: LOG_LEVEL
          value: debug`,
        hint: "kubectl get deployment api -o yaml",
        explanation: "Only `LOG_LEVEL` is set; `DATABASE_URL` is missing. Fix it in the Deployment (not the Pod \u2014 the ReplicaSet would just recreate the broken Pod), e.g. add the env var back or roll back with `kubectl rollout undo deployment/api`."
      }
    ]
  },
  {
    id: "term-expose-service",
    title: "Expose a Deployment and check its endpoints",
    objective: "co-networking",
    lessonId: "services",
    difficulty: 2,
    scenario: "The `web` Deployment (3 nginx replicas, label `app=web`, container port 80) is running but nothing can reach it by a stable name. Create a ClusterIP Service for it and verify that the Service actually found the Pods.",
    steps: [
      {
        task: "Expose the `web` Deployment as a Service on port **80**.",
        expect: [{ verb: "expose", resource: "deployments", name: "web", flags: { port: "80" } }],
        output: `service/web exposed`,
        hint: "kubectl expose deployment web --port=80",
        explanation: "`kubectl expose` copies the Deployment's selector (`app=web`) into a new Service. With no `--type`, the Service is `ClusterIP`. If `--target-port` is omitted it defaults to the same value as `--port`."
      },
      {
        task: "Show the new Service `web`.",
        expect: [{ verb: "get", resource: "services", name: "web" }],
        output: `NAME   TYPE        CLUSTER-IP     EXTERNAL-IP   PORT(S)   AGE
web    ClusterIP   10.96.142.37   <none>        80/TCP    6s`,
        hint: "kubectl get service web (short name: svc)",
        explanation: "The ClusterIP `10.96.142.37` is virtual: no interface owns it. kube-proxy programs rules on every node so traffic to it is load-balanced to the backing Pods. Inside the cluster the Service is also reachable as `web.default.svc.cluster.local`."
      },
      {
        task: "Check which Pod IPs the Service routes to.",
        expect: [
          { verb: "get", resource: "endpoints", name: "web" },
          { verb: "get", resource: "endpointslices", flags: { selector: "kubernetes.io/service-name=web" } },
          { verb: "describe", resource: "services", name: "web" }
        ],
        output: `NAME   ENDPOINTS                                      AGE
web    10.244.1.12:80,10.244.1.13:80,10.244.2.9:80   6s`,
        hint: "kubectl get endpoints web \u2014 or the EndpointSlices labelled kubernetes.io/service-name=web",
        explanation: "Three addresses = three ready Pods matched by the selector. An **empty** endpoints list is the classic sign of a selector/label mismatch or Pods that are not Ready. Modern clusters store this data in EndpointSlices; the legacy Endpoints API is still served for compatibility."
      },
      {
        task: "Verify the Pod IPs match: list the `app=web` Pods with wide output.",
        expect: [{ verb: "get", resource: "pods", flags: { selector: "app=web", output: "wide" } }],
        output: `NAME                   READY   STATUS    RESTARTS   AGE   IP            NODE           NOMINATED NODE   READINESS GATES
web-6c9f8d7b54-2kxbz   1/1     Running   0          2d    10.244.1.12   kcna-worker    <none>           <none>
web-6c9f8d7b54-8hq4n   1/1     Running   0          2d    10.244.1.13   kcna-worker    <none>           <none>
web-6c9f8d7b54-tm7vd   1/1     Running   0          2d    10.244.2.9    kcna-worker2   <none>           <none>`,
        hint: "kubectl get pods -l app=web -o wide",
        explanation: "The Pod IPs match the endpoints exactly. The Service is a stable front; Pods can come and go and the endpoints list is updated automatically by the EndpointSlice controller."
      }
    ]
  },
  {
    id: "term-rollout-rollback",
    title: "Rolling update and rollback",
    objective: "cad-delivery",
    lessonId: "rollouts-and-deployment-strategies",
    difficulty: 2,
    scenario: "The `web` Deployment runs `nginx:1.27` in container `nginx`. Ship `nginx:1.27-alpine`, watch the rollout, then practise rolling back as if the new version misbehaved.",
    steps: [
      {
        task: "Update the image of container `nginx` in Deployment `web` to `nginx:1.27-alpine`.",
        expect: [{ verb: "set", subcommand: "image", resource: "deployments", name: "web" }],
        output: `deployment.apps/web image updated`,
        hint: "kubectl set image deployment/web nginx=nginx:1.27-alpine",
        explanation: "Changing the Pod template creates a **new ReplicaSet** with a new pod-template-hash. The Deployment then scales the new ReplicaSet up and the old one down, respecting `maxSurge` and `maxUnavailable`."
      },
      {
        task: "Watch the rollout until it completes.",
        expect: [{ verb: "rollout", subcommand: "status", resource: "deployments", name: "web" }],
        output: `Waiting for deployment "web" rollout to finish: 1 out of 3 new replicas have been updated...
Waiting for deployment "web" rollout to finish: 2 out of 3 new replicas have been updated...
Waiting for deployment "web" rollout to finish: 1 old replicas are pending termination...
deployment "web" successfully rolled out`,
        hint: "kubectl rollout status deployment/web",
        explanation: "`rollout status` blocks until the rollout finishes or fails, and exits non-zero on failure \u2014 which is why CI/CD pipelines use it as a gate after deploying."
      },
      {
        task: "Show the revision history of `web`.",
        expect: [{ verb: "rollout", subcommand: "history", resource: "deployments", name: "web" }],
        output: `deployment.apps/web
REVISION  CHANGE-CAUSE
1         <none>
2         <none>`,
        hint: "kubectl rollout history deployment/web",
        explanation: "Each revision corresponds to a ReplicaSet the Deployment keeps around (up to `revisionHistoryLimit`, default 10). `CHANGE-CAUSE` is read from the `kubernetes.io/change-cause` annotation, which you can set yourself with `kubectl annotate`."
      },
      {
        task: "Roll `web` back to the previous revision.",
        expect: [
          { verb: "rollout", subcommand: "undo", resource: "deployments", name: "web" },
          { verb: "rollout", subcommand: "undo", resource: "deployments", name: "web", flags: { "to-revision": "1" } }
        ],
        output: `deployment.apps/web rolled back`,
        hint: "kubectl rollout undo deployment/web (optionally --to-revision=1)",
        explanation: "A rollback is just another rolling update: the old ReplicaSet's template is copied back and scaled up. The history now shows revisions 2 and 3 \u2014 revision 1 is renumbered to 3 because it became current again."
      }
    ]
  },
  {
    id: "term-labels-selectors",
    title: "Find things with labels and selectors",
    objective: "kf-core",
    lessonId: "namespaces-labels-selectors",
    difficulty: 1,
    scenario: "The `shop` namespace contains Pods for several tiers of an online shop. You need to find the frontend Pods, tag one for debugging, and see how a Service picks its Pods.",
    steps: [
      {
        task: "List all Pods in namespace `shop` together with their labels.",
        expect: [{ verb: "get", resource: "pods", namespace: "shop", flags: { "show-labels": "" } }],
        output: `NAME                        READY   STATUS    RESTARTS   AGE   LABELS
cart-5d7c9b6f4-hm2xq        1/1     Running   0          3d    app=cart,pod-template-hash=5d7c9b6f4,tier=backend
catalog-7b9d5c8f6-9wq2m     1/1     Running   0          3d    app=catalog,pod-template-hash=7b9d5c8f6,tier=backend
frontend-6d8f7c5b9-k4z7t    1/1     Running   0          3d    app=frontend,pod-template-hash=6d8f7c5b9,tier=frontend
frontend-6d8f7c5b9-v2hxn    1/1     Running   0          3d    app=frontend,pod-template-hash=6d8f7c5b9,tier=frontend
redis-0                     1/1     Running   0          3d    app=redis,apps.kubernetes.io/pod-index=0,controller-revision-hash=redis-7c8d9f6b5,statefulset.kubernetes.io/pod-name=redis-0,tier=cache`,
        hint: "kubectl get pods -n shop --show-labels",
        explanation: "Labels are key/value pairs used for **selection**. Some are added automatically by controllers, such as `pod-template-hash` (Deployments) and `statefulset.kubernetes.io/pod-name` (StatefulSets)."
      },
      {
        task: "List only the Pods in `shop` with label `tier=frontend`.",
        expect: [{ verb: "get", resource: "pods", namespace: "shop", flags: { selector: "tier=frontend" } }],
        output: `NAME                       READY   STATUS    RESTARTS   AGE
frontend-6d8f7c5b9-k4z7t   1/1     Running   0          3d
frontend-6d8f7c5b9-v2hxn   1/1     Running   0          3d`,
        hint: "kubectl get pods -n shop -l tier=frontend",
        explanation: "This is the same equality-based selection that Services, ReplicaSets and NetworkPolicies use internally. Set-based selectors also exist, e.g. `-l 'tier in (frontend,cache)'`."
      },
      {
        task: "Add the label `debug=true` to Pod `frontend-6d8f7c5b9-k4z7t` in `shop`.",
        expect: [{ verb: "label", resource: "pods", name: "frontend-6d8f7c5b9-k4z7t", namespace: "shop" }],
        output: `pod/frontend-6d8f7c5b9-k4z7t labeled`,
        hint: "kubectl label pod frontend-6d8f7c5b9-k4z7t debug=true -n shop",
        explanation: "Adding a label does not affect the Pod's owner as long as the selector labels (`app=frontend`) are unchanged. Removing or changing a selector label would orphan the Pod \u2014 the ReplicaSet would create a replacement."
      },
      {
        task: "Show the Services in `shop` with wide output to see which selector each one uses.",
        expect: [{ verb: "get", resource: "services", namespace: "shop", flags: { output: "wide" } }],
        output: `NAME       TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)    AGE   SELECTOR
cart       ClusterIP   10.96.88.140    <none>        8080/TCP   3d    app=cart
catalog    ClusterIP   10.96.201.6     <none>        8080/TCP   3d    app=catalog
frontend   ClusterIP   10.96.17.233    <none>        80/TCP     3d    app=frontend
redis      ClusterIP   None            <none>        6379/TCP   3d    app=redis`,
        hint: "kubectl get services -n shop -o wide",
        explanation: "The `SELECTOR` column is exactly what each Service matches against Pod labels. `redis` has `CLUSTER-IP None`: it is a **headless** Service, commonly paired with a StatefulSet so each Pod gets a stable DNS name."
      }
    ]
  },
  {
    id: "term-config-secrets",
    title: "Inspect ConfigMaps and Secrets",
    objective: "co-security",
    lessonId: "configmaps-and-secrets",
    difficulty: 2,
    scenario: "The `cart` service in namespace `shop` reads settings from ConfigMap `cart-config` and credentials from Secret `cart-db`. A teammate asks what values the app actually receives.",
    steps: [
      {
        task: "List the ConfigMaps in namespace `shop`.",
        expect: [{ verb: "get", resource: "configmaps", namespace: "shop" }],
        output: `NAME               DATA   AGE
cart-config        3      3d
kube-root-ca.crt   1      3d`,
        hint: "kubectl get configmaps -n shop (short name: cm)",
        explanation: "`DATA` is the number of keys. `kube-root-ca.crt` is published automatically into every namespace so Pods can verify the API server's certificate."
      },
      {
        task: "Show the keys and values of ConfigMap `cart-config`.",
        expect: [
          { verb: "describe", resource: "configmaps", name: "cart-config", namespace: "shop" },
          { verb: "get", resource: "configmaps", name: "cart-config", namespace: "shop", flags: { output: "yaml" } }
        ],
        output: `Name:         cart-config
Namespace:    shop
Labels:       app=cart
Annotations:  <none>

Data
====
CACHE_TTL_SECONDS:
----
300
CURRENCY:
----
EUR
LOG_LEVEL:
----
info

BinaryData
====

Events:  <none>`,
        hint: "kubectl describe configmap cart-config -n shop (or get ... -o yaml)",
        explanation: "ConfigMap values are plain text and fully visible. They are meant for non-sensitive configuration only."
      },
      {
        task: "Describe Secret `cart-db` in `shop`.",
        expect: [{ verb: "describe", resource: "secrets", name: "cart-db", namespace: "shop" }],
        output: `Name:         cart-db
Namespace:    shop
Labels:       app=cart
Annotations:  <none>

Type:  Opaque

Data
====
password:  15 bytes
username:  8 bytes`,
        hint: "kubectl describe secret cart-db -n shop",
        explanation: "`describe` hides Secret values and only shows sizes. That is a convenience for screen-sharing, **not** a security boundary."
      },
      {
        task: "Print Secret `cart-db` as YAML to see how the data is stored.",
        expect: [{ verb: "get", resource: "secrets", name: "cart-db", namespace: "shop", flags: { output: "yaml" } }],
        output: `apiVersion: v1
data:
  password: czNjcjN0LXBhc3N3MHJk
  username: Y2FydF9hcHA=
kind: Secret
metadata:
  labels:
    app: cart
  name: cart-db
  namespace: shop
type: Opaque`,
        hint: "kubectl get secret cart-db -n shop -o yaml",
        explanation: "Values are **base64-encoded, not encrypted**: `echo Y2FydF9hcHA= | base64 -d` prints `cart_app`. Anyone allowed to `get` Secrets can read them, so restrict Secret access with RBAC and enable encryption at rest for etcd."
      }
    ]
  }
];

// ../../packages/content/src/practice/yaml.ts
var yamlChallenges = [
  {
    id: "yaml-selector-mismatch",
    title: "Fix a Deployment whose selector matches nothing",
    objective: "kf-core",
    lessonId: "replicasets-and-deployments",
    kind: "fix",
    difficulty: 1,
    instructions: "The API server rejects this Deployment with `selector does not match template labels`. Make the Pod template labels and the selector agree. Keep the selector as `app: web` and the replica count at 3.",
    starter: `apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  replicas: 3
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: frontend
    spec:
      containers:
      - name: nginx
        image: nginx:1.27
        ports:
        - containerPort: 80
`,
    checks: [
      { path: "kind", op: "equals", value: "Deployment", message: "kind must stay Deployment." },
      { path: "spec.selector.matchLabels.app", op: "equals", value: "web", message: "Keep the selector as app: web." },
      { path: "spec.template.metadata.labels.app", op: "equals", value: "web", message: "The Pod template must carry the label app: web so the selector can find its Pods." },
      { op: "selectorMatchesTemplate", message: "Every key/value in spec.selector.matchLabels must also appear in spec.template.metadata.labels." },
      { path: "spec.replicas", op: "equals", value: 3, message: "replicas should stay at 3." }
    ],
    solution: `apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  replicas: 3
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
      - name: nginx
        image: nginx:1.27
        ports:
        - containerPort: 80
`,
    explanation: 'A Deployment finds "its" Pods only through `spec.selector`. For `apps/v1` the selector is required, immutable after creation, and must match the template labels \u2014 otherwise the controller would create Pods it could never count, and keep creating more. The template may carry **extra** labels; it just must include every selector label.'
  },
  {
    id: "yaml-missing-image",
    title: "Add the missing container image",
    objective: "kf-containerization",
    lessonId: "pods",
    kind: "fix",
    difficulty: 1,
    instructions: "This Pod is rejected with `spec.containers[0].image: Required value`. Add the image `busybox:1.36` to the container. Use a pinned tag, not `latest`.",
    starter: `apiVersion: v1
kind: Pod
metadata:
  name: sleeper
  labels:
    app: sleeper
spec:
  containers:
  - name: main
    command: ["sh", "-c", "echo started; sleep 3600"]
`,
    checks: [
      { path: "kind", op: "equals", value: "Pod", message: "kind must stay Pod." },
      { path: "spec.containers[0].name", op: "equals", value: "main", message: "Keep the container name main." },
      { path: "spec.containers[0].image", op: "exists", message: "The container has no image field \u2014 every container needs an image." },
      { path: "spec.containers[0].image", op: "equals", value: "busybox:1.36", message: "Use exactly busybox:1.36 (a pinned tag, not latest or an untagged name)." }
    ],
    solution: `apiVersion: v1
kind: Pod
metadata:
  name: sleeper
  labels:
    app: sleeper
spec:
  containers:
  - name: main
    image: busybox:1.36
    command: ["sh", "-c", "echo started; sleep 3600"]
`,
    explanation: "`image` is the one required field of a container besides `name`. Pinning a tag (or better, a digest like `busybox@sha256:...`) makes deployments reproducible; an untagged image means `:latest`, which also changes the default `imagePullPolicy` to `Always`."
  },
  {
    id: "yaml-resources",
    title: "Set resource requests and limits",
    objective: "kf-scheduling",
    lessonId: "resources-requests-limits",
    kind: "complete",
    difficulty: 2,
    instructions: "Give the `api` container these resources:\n\n- requests: `cpu: 250m`, `memory: 128Mi`\n- limits: `memory: 256Mi`\n\nDo not set a CPU limit (CPU over-use is throttled, not killed, so many teams omit it).",
    starter: `apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
spec:
  replicas: 2
  selector:
    matchLabels:
      app: api
  template:
    metadata:
      labels:
        app: api
    spec:
      containers:
      - name: api
        image: nginx:1.27
        resources: {}
`,
    checks: [
      { path: "spec.template.spec.containers[0].resources.requests.cpu", op: "equals", value: "250m", message: "requests.cpu should be 250m (a quarter of a CPU core)." },
      { path: "spec.template.spec.containers[0].resources.requests.memory", op: "equals", value: "128Mi", message: "requests.memory should be 128Mi." },
      { path: "spec.template.spec.containers[0].resources.limits.memory", op: "equals", value: "256Mi", message: "limits.memory should be 256Mi \u2014 exceeding it gets the container OOMKilled." },
      { path: "spec.template.spec.containers[0].resources.limits.cpu", op: "absent", message: "The task asks for no CPU limit." },
      { op: "selectorMatchesTemplate", message: "Do not break the selector: template labels must still include app: api." }
    ],
    solution: `apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
spec:
  replicas: 2
  selector:
    matchLabels:
      app: api
  template:
    metadata:
      labels:
        app: api
    spec:
      containers:
      - name: api
        image: nginx:1.27
        resources:
          requests:
            cpu: 250m
            memory: 128Mi
          limits:
            memory: 256Mi
`,
    explanation: "**Requests** are what the scheduler reserves when choosing a node; **limits** are enforced at runtime by the kubelet and kernel cgroups. Memory over the limit \u2192 OOMKilled; CPU over a limit \u2192 throttled. Because requests are set but do not equal limits, this Pod gets the **Burstable** QoS class."
  },
  {
    id: "yaml-readiness-probe",
    title: "Add a readiness probe",
    objective: "co-troubleshooting",
    lessonId: "health-probes",
    kind: "complete",
    difficulty: 2,
    instructions: "The app listens on port 8080 and returns 200 on `/ready` only after it has loaded its cache. Add a **readiness** probe to the container: HTTP GET `/ready` on port `8080`, checked every `5` seconds, with an initial delay of `3` seconds.",
    starter: `apiVersion: apps/v1
kind: Deployment
metadata:
  name: catalog
spec:
  replicas: 2
  selector:
    matchLabels:
      app: catalog
  template:
    metadata:
      labels:
        app: catalog
    spec:
      containers:
      - name: catalog
        image: registry.example.com/shop/catalog:2.4.1
        ports:
        - containerPort: 8080
`,
    checks: [
      { path: "spec.template.spec.containers[0].readinessProbe", op: "exists", message: "Add a readinessProbe to the container (not a livenessProbe)." },
      { path: "spec.template.spec.containers[0].readinessProbe.httpGet.path", op: "equals", value: "/ready", message: "The probe should use httpGet with path /ready." },
      { path: "spec.template.spec.containers[0].readinessProbe.httpGet.port", op: "equals", value: 8080, message: "The probe should hit port 8080, where the app listens." },
      { path: "spec.template.spec.containers[0].readinessProbe.periodSeconds", op: "equals", value: 5, message: "periodSeconds should be 5." },
      { path: "spec.template.spec.containers[0].readinessProbe.initialDelaySeconds", op: "equals", value: 3, message: "initialDelaySeconds should be 3." }
    ],
    solution: `apiVersion: apps/v1
kind: Deployment
metadata:
  name: catalog
spec:
  replicas: 2
  selector:
    matchLabels:
      app: catalog
  template:
    metadata:
      labels:
        app: catalog
    spec:
      containers:
      - name: catalog
        image: registry.example.com/shop/catalog:2.4.1
        ports:
        - containerPort: 8080
        readinessProbe:
          httpGet:
            path: /ready
            port: 8080
          initialDelaySeconds: 3
          periodSeconds: 5
`,
    explanation: 'A failing **readiness** probe removes the Pod from Service endpoints but does **not** restart it \u2014 exactly right for "still warming up". A failing **liveness** probe restarts the container, which would be wrong here and could cause a restart loop while the cache loads. For very slow starts, a `startupProbe` holds off the other probes.'
  },
  {
    id: "yaml-service-targetport",
    title: "Fix a Service that points at the wrong port",
    objective: "co-networking",
    lessonId: "services",
    kind: "fix",
    difficulty: 2,
    instructions: 'The `api` Pods (label `app: api`) run a container that listens on **8080**. Clients should keep calling the Service on port **80**. Requests currently fail with "connection refused". Fix the Service.',
    starter: `apiVersion: v1
kind: Service
metadata:
  name: api
spec:
  selector:
    app: api
  ports:
  - name: http
    port: 80
    targetPort: 80
`,
    checks: [
      { path: "kind", op: "equals", value: "Service", message: "kind must stay Service." },
      { path: "spec.selector.app", op: "equals", value: "api", message: "The selector must stay app: api." },
      { path: "spec.ports[0].port", op: "equals", value: 80, message: "Clients call port 80 \u2014 keep spec.ports[0].port at 80." },
      { path: "spec.ports[0].targetPort", op: "equals", value: 8080, message: "targetPort is the port on the Pod. The container listens on 8080, so targetPort must be 8080." }
    ],
    solution: `apiVersion: v1
kind: Service
metadata:
  name: api
spec:
  selector:
    app: api
  ports:
  - name: http
    port: 80
    targetPort: 8080
`,
    explanation: '`port` is what clients connect to on the Service\'s ClusterIP; `targetPort` is where traffic is forwarded on each Pod. Endpoints still exist here (the selector is fine), so the symptom is "connection refused" rather than "no endpoints". `targetPort` can also be a **named** container port (e.g. `http`), which survives port changes in the Pod spec.'
  },
  {
    id: "yaml-pvc",
    title: "Write a PersistentVolumeClaim",
    objective: "co-storage",
    lessonId: "persistent-volumes-and-csi",
    kind: "complete",
    difficulty: 2,
    instructions: "Complete the claim so a single-node database can mount it read-write: access mode `ReadWriteOnce`, `5Gi` of storage, StorageClass `standard`.",
    starter: `apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: db-data
spec:
  resources:
    requests: {}
`,
    checks: [
      { path: "kind", op: "equals", value: "PersistentVolumeClaim", message: "kind must be PersistentVolumeClaim." },
      { path: "spec.accessModes[0]", op: "equals", value: "ReadWriteOnce", message: "spec.accessModes is a list; its first entry should be ReadWriteOnce." },
      { path: "spec.resources.requests.storage", op: "equals", value: "5Gi", message: "Request 5Gi under spec.resources.requests.storage." },
      { path: "spec.storageClassName", op: "equals", value: "standard", message: "Set spec.storageClassName: standard so the right provisioner handles the claim." }
    ],
    solution: `apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: db-data
spec:
  accessModes:
  - ReadWriteOnce
  storageClassName: standard
  resources:
    requests:
      storage: 5Gi
`,
    explanation: "A PVC is a **request** for storage; the StorageClass's provisioner creates a matching PersistentVolume (dynamic provisioning) and binds it. `ReadWriteOnce` means mountable read-write by one **node** at a time (`ReadWriteOncePod` restricts it to a single Pod). Without a matching class or PV, the claim stays `Pending`."
  },
  {
    id: "yaml-envfrom-configmap",
    title: "Load all keys of a ConfigMap as environment variables",
    objective: "kf-core",
    lessonId: "configmaps-and-secrets",
    kind: "fix",
    difficulty: 2,
    instructions: "The author tried to import every key of ConfigMap `app-config` as environment variables, but used a field that does not exist. Fix the `envFrom` entry so it references the ConfigMap correctly.",
    starter: `apiVersion: v1
kind: Pod
metadata:
  name: shop-ui
spec:
  containers:
  - name: ui
    image: nginx:1.27
    envFrom:
    - configMap:
        name: app-config
`,
    checks: [
      { path: "spec.containers[0].envFrom[0].configMap", op: "absent", message: "envFrom entries do not have a configMap field \u2014 that name belongs to volumes." },
      { path: "spec.containers[0].envFrom[0].configMapRef.name", op: "equals", value: "app-config", message: "Use envFrom[0].configMapRef.name: app-config." },
      { path: "spec.containers[0].image", op: "equals", value: "nginx:1.27", message: "Keep the image nginx:1.27." }
    ],
    solution: `apiVersion: v1
kind: Pod
metadata:
  name: shop-ui
spec:
  containers:
  - name: ui
    image: nginx:1.27
    envFrom:
    - configMapRef:
        name: app-config
`,
    explanation: "In `envFrom` you use `configMapRef` / `secretRef`; in `env[].valueFrom` you use `configMapKeyRef` / `secretKeyRef`; in `volumes` you use `configMap` / `secret`. Environment variables are read once at container start \u2014 editing the ConfigMap later does not change them until the Pod restarts (mounted volumes, by contrast, are refreshed eventually)."
  },
  {
    id: "yaml-networkpolicy",
    title: "Allow only the API to reach the database",
    objective: "co-security",
    lessonId: "network-policies",
    kind: "complete",
    difficulty: 3,
    instructions: "Complete the NetworkPolicy so that Pods labelled `app: db` accept **ingress** only from Pods labelled `app: api` in the same namespace, on TCP port `5432`.",
    starter: `apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: db-allow-api
spec:
  podSelector: {}
  policyTypes:
  - Ingress
  ingress: []
`,
    checks: [
      { path: "kind", op: "equals", value: "NetworkPolicy", message: "kind must be NetworkPolicy." },
      { path: "spec.podSelector.matchLabels.app", op: "equals", value: "db", message: "spec.podSelector selects the Pods the policy protects \u2014 it should match app: db, not every Pod ({})." },
      { path: "spec.policyTypes[0]", op: "equals", value: "Ingress", message: "policyTypes should contain Ingress." },
      { path: "spec.ingress[0].from[0].podSelector.matchLabels.app", op: "equals", value: "api", message: "The allowed source is ingress[0].from[0].podSelector with app: api." },
      { path: "spec.ingress[0].ports[0].port", op: "equals", value: 5432, message: "Restrict the rule to port 5432 via ingress[0].ports[0].port." },
      { path: "spec.ingress[0].ports[0].protocol", op: "oneOf", value: ["TCP"], message: "Use protocol TCP for PostgreSQL." }
    ],
    solution: `apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: db-allow-api
spec:
  podSelector:
    matchLabels:
      app: db
  policyTypes:
  - Ingress
  ingress:
  - from:
    - podSelector:
        matchLabels:
          app: api
    ports:
    - protocol: TCP
      port: 5432
`,
    explanation: 'Once any policy selects a Pod for Ingress, that Pod becomes **default-deny** for ingress except what some policy allows. A `podSelector` inside `from` (without a `namespaceSelector`) means "Pods in this policy\'s namespace". NetworkPolicy is only enforced if the CNI plugin supports it (e.g. Calico, Cilium) \u2014 otherwise it is silently ignored.'
  }
];

// ../../packages/content/src/practice/troubleshooting.ts
var K8S_DEBUG_PODS = { title: "Debug Pods (Kubernetes docs)", url: "https://kubernetes.io/docs/tasks/debug/debug-application/debug-pods/" };
var K8S_DEBUG = { title: "Monitoring, Logging, and Debugging (Kubernetes docs)", url: "https://kubernetes.io/docs/tasks/debug/" };
var troubleshootingScenarios = [
  {
    id: "ts-crashloopbackoff",
    title: "The worker that keeps dying",
    objective: "co-troubleshooting",
    lessonId: "troubleshooting-workloads",
    difficulty: 1,
    symptom: "A new `report-worker` Deployment was rolled out 15 minutes ago. Its Pod never becomes ready and the restart counter keeps climbing.",
    evidence: [
      {
        command: "kubectl get pods -l app=report-worker",
        output: `NAME                             READY   STATUS             RESTARTS      AGE
report-worker-7c6d9b8f5d-qk2pl   0/1     CrashLoopBackOff   7 (2m ago)    15m`
      }
    ],
    stages: [
      {
        phase: "hypothesis",
        question: "What does `CrashLoopBackOff` tell you about where the problem is?",
        options: [
          { text: "The container starts, then its process exits; the kubelet is backing off between restarts.", correct: true, feedback: "Right. The image was pulled and the Pod was scheduled \u2014 the failure is in what happens after the process starts." },
          { text: "The scheduler cannot find a node for the Pod.", correct: false, feedback: "A scheduling failure shows `Pending` with a `FailedScheduling` event; this Pod has already restarted 7 times on a node." },
          { text: "The node cannot download the container image.", correct: false, feedback: "That would be `ErrImagePull` / `ImagePullBackOff`. A container must have an image before it can crash." }
        ]
      },
      {
        phase: "investigation",
        question: "Which command is most likely to show the actual error message from the crashed process?",
        options: [
          { text: "kubectl logs report-worker-7c6d9b8f5d-qk2pl --previous", correct: true, feedback: "Yes. `--previous` returns output from the last terminated instance, which is where the crash message lives." },
          { text: "kubectl get nodes", correct: false, feedback: "Node health is not the issue \u2014 the Pod is running on a node and restarting there." },
          { text: "kubectl get svc", correct: false, feedback: "Services route traffic to Pods; they cannot make a container exit." }
        ],
        reveal: {
          command: "kubectl logs report-worker-7c6d9b8f5d-qk2pl --previous",
          output: `2026-11-12T09:14:03Z INFO  starting report-worker v3.2.0
2026-11-12T09:14:03Z ERROR open /etc/report/templates.yaml: no such file or directory
2026-11-12T09:14:03Z FATAL cannot load templates, exiting`
        }
      },
      {
        phase: "evidence",
        question: "The log says `/etc/report/templates.yaml` does not exist. What is the most useful next piece of evidence?",
        options: [
          { text: "The Pod spec's volumes and volumeMounts (e.g. kubectl describe pod or get deploy -o yaml).", correct: true, feedback: "Correct. A missing config file inside a container usually means a volume was not mounted, or mounted at a different path." },
          { text: "The node's CPU usage via kubectl top nodes.", correct: false, feedback: "Resource pressure does not delete files from a container's filesystem." },
          { text: "The cluster's CoreDNS logs.", correct: false, feedback: "DNS is not involved in reading a local file path." }
        ],
        reveal: {
          command: "kubectl describe pod report-worker-7c6d9b8f5d-qk2pl | grep -A3 Mounts",
          output: `    Mounts:
      /etc/reports from templates (ro)
      /var/run/secrets/kubernetes.io/serviceaccount from kube-api-access-8vwpz (ro)`
        }
      },
      {
        phase: "solution",
        question: "The ConfigMap is mounted at `/etc/reports`, but the app reads `/etc/report`. What is the correct fix?",
        options: [
          { text: "Fix the mountPath in the Deployment's Pod template to /etc/report and let it roll out.", correct: true, feedback: "Yes. Change desired state in the Deployment; the controller replaces the Pods with the corrected template." },
          { text: "kubectl exec into the Pod and create the file by hand.", correct: false, feedback: "The container is restarting, and any manual change is lost on the next restart or reschedule. Fix the spec instead." },
          { text: "Delete the Pod so it restarts cleanly.", correct: false, feedback: "The ReplicaSet recreates it from the same broken template, so it crashes the same way." }
        ]
      }
    ],
    takeaway: "`CrashLoopBackOff` is a symptom, not a cause. Go straight to `kubectl logs --previous` and the `Last State` / `Exit Code` in `kubectl describe pod`, then fix the **template** in the owning controller.",
    references: [K8S_DEBUG_PODS, { title: "Pod lifecycle", url: "https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/" }]
  },
  {
    id: "ts-imagepullbackoff",
    title: "The image that never arrives",
    objective: "co-troubleshooting",
    lessonId: "troubleshooting-workloads",
    difficulty: 1,
    symptom: "A developer bumped the `checkout` image in CI. The new Pod has been stuck for 10 minutes; the old Pods are still serving.",
    evidence: [
      {
        command: "kubectl get pods -l app=checkout",
        output: `NAME                        READY   STATUS             RESTARTS   AGE
checkout-58d9f7c6b4-7hjwt   1/1     Running            0          3d
checkout-58d9f7c6b4-n2c8x   1/1     Running            0          3d
checkout-6b7f9d8c5-x9vmq    0/1     ImagePullBackOff   0          10m`
      }
    ],
    stages: [
      {
        phase: "hypothesis",
        question: "Which explanations fit `ImagePullBackOff`?",
        options: [
          { text: "The image reference is wrong, the tag does not exist, or the registry needs credentials the node does not have.", correct: true, feedback: "Right \u2014 the kubelet asked the runtime to pull the image and the pull failed repeatedly." },
          { text: "The application inside the image crashes on startup.", correct: false, feedback: "The container never started; an app crash would be `CrashLoopBackOff`." },
          { text: "The Pod is waiting for a node with enough memory.", correct: false, feedback: "Scheduling problems show `Pending`. This Pod is already assigned to a node, which is trying to pull." }
        ]
      },
      {
        phase: "investigation",
        question: "Where will you find the exact pull error?",
        options: [
          { text: "The Events section of kubectl describe pod checkout-6b7f9d8c5-x9vmq", correct: true, feedback: "Yes. The kubelet records `Failed to pull image` events with the registry's error message." },
          { text: "kubectl logs checkout-6b7f9d8c5-x9vmq", correct: false, feedback: "There are no logs \u2014 the container never ran. kubectl will say the container is waiting to start." },
          { text: "kubectl get endpoints checkout", correct: false, feedback: "Endpoints tell you which Pods receive traffic, not why an image pull failed." }
        ],
        reveal: {
          command: "kubectl describe pod checkout-6b7f9d8c5-x9vmq | tail -6",
          output: `Events:
  Type     Reason   Age                  From     Message
  ----     ------   ----                 ----     -------
  Warning  Failed   9m (x4 over 10m)     kubelet  Failed to pull image "registry.example.com/shop/checkout:1.9.0-rc": rpc error: code = NotFound desc = failed to pull and unpack image "registry.example.com/shop/checkout:1.9.0-rc": registry.example.com/shop/checkout:1.9.0-rc: not found
  Warning  Failed   9m (x4 over 10m)     kubelet  Error: ErrImagePull
  Normal   BackOff  30s (x42 over 10m)   kubelet  Back-off pulling image "registry.example.com/shop/checkout:1.9.0-rc"`
        }
      },
      {
        phase: "evidence",
        question: "What does `not found` (rather than `unauthorized` or `403`) point to?",
        options: [
          { text: "The tag 1.9.0-rc does not exist in that repository.", correct: true, feedback: "Correct. The registry answered; it just has no such manifest. An auth problem would say unauthorized/denied." },
          { text: "The node has no network connectivity.", correct: false, feedback: "With no connectivity you would see a timeout or DNS error, not a `NotFound` answer from the registry." },
          { text: "An imagePullSecret is missing.", correct: false, feedback: "Missing credentials typically produce `unauthorized` or `authentication required`." }
        ],
        reveal: {
          command: "kubectl get deploy checkout -o jsonpath='{.spec.template.spec.containers[0].image}'",
          output: `registry.example.com/shop/checkout:1.9.0-rc`
        }
      },
      {
        phase: "solution",
        question: "CI actually published `1.9.0`. What do you do?",
        options: [
          { text: "Correct the image tag in the Deployment (or its source in Git) to 1.9.0.", correct: true, feedback: "Yes. The rollout continues with the corrected template and the stuck Pod is replaced." },
          { text: "Add imagePullPolicy: Never.", correct: false, feedback: "That forbids pulling entirely; the image is not on the node, so it would fail with `ErrImageNeverPull`." },
          { text: "Scale the Deployment to 0 and back.", correct: false, feedback: "The template still references the wrong tag, so the new Pods fail the same way." }
        ]
      }
    ],
    takeaway: "For image problems, read the kubelet events: `not found` = wrong name/tag, `unauthorized` = credentials (`imagePullSecrets`), timeouts = network/registry reachability. Note the rolling update kept the old Pods serving \u2014 that is `maxUnavailable` protecting you.",
    references: [K8S_DEBUG_PODS, { title: "Images", url: "https://kubernetes.io/docs/concepts/containers/images/" }]
  },
  {
    id: "ts-pending-pod",
    title: "The Pod nobody will host",
    objective: "kf-scheduling",
    lessonId: "scheduling-placement",
    difficulty: 2,
    symptom: "A data team deployed a `trainer` Pod requesting a lot of memory. It has been `Pending` for 20 minutes and nothing is in its logs.",
    evidence: [
      {
        command: "kubectl get pod trainer -o wide",
        output: `NAME      READY   STATUS    RESTARTS   AGE   IP       NODE     NOMINATED NODE   READINESS GATES
trainer   0/1     Pending   0          20m   <none>   <none>   <none>           <none>`
      }
    ],
    stages: [
      {
        phase: "hypothesis",
        question: "`Pending` with no node assigned. Which component has not done its job yet?",
        options: [
          { text: "kube-scheduler \u2014 it has not found a node that passes all filters.", correct: true, feedback: "Right. NODE is `<none>`, so the Pod was never bound to a node." },
          { text: "The kubelet \u2014 it failed to start the container.", correct: false, feedback: "The kubelet only acts after the Pod is bound to its node. No node is assigned here." },
          { text: "kube-proxy \u2014 it has not created Service rules.", correct: false, feedback: "kube-proxy handles Service traffic and has nothing to do with placing Pods." }
        ]
      },
      {
        phase: "investigation",
        question: "How do you get the scheduler's reason?",
        options: [
          { text: "kubectl describe pod trainer and read the FailedScheduling event.", correct: true, feedback: "Yes. The scheduler explains per-node why each was rejected." },
          { text: "kubectl logs trainer", correct: false, feedback: "No container has run, so there are no logs." },
          { text: "kubectl rollout status pod/trainer", correct: false, feedback: "`rollout` works on Deployments, DaemonSets and StatefulSets, not bare Pods." }
        ],
        reveal: {
          command: "kubectl describe pod trainer | tail -4",
          output: `Events:
  Type     Reason            Age                 From               Message
  ----     ------            ----                ----               -------
  Warning  FailedScheduling  2m (x5 over 20m)    default-scheduler  0/3 nodes are available: 1 node(s) had untolerated taint {node-role.kubernetes.io/control-plane: }, 2 Insufficient memory. preemption: 0/3 nodes are available: 1 Preemption is not helpful for scheduling, 2 No preemption victims found for incoming pod.`
        }
      },
      {
        phase: "evidence",
        question: "How do you read `1 node(s) had untolerated taint ... , 2 Insufficient memory`?",
        options: [
          { text: "The control-plane node is tainted against workloads, and both workers lack enough unreserved memory for the Pod's request.", correct: true, feedback: "Correct. Every node is ruled out, each for a stated reason." },
          { text: "The Pod is using more memory than its limit.", correct: false, feedback: "Scheduling compares **requests** to node allocatable capacity. The Pod is not running, so it is using nothing." },
          { text: "Two nodes are NotReady.", correct: false, feedback: "NotReady nodes would show a `not-ready` taint/condition message. These are Ready but full." }
        ],
        reveal: {
          command: 'kubectl describe node kcna-worker | grep -A6 "Allocated resources"',
          output: `Allocated resources:
  (Total limits may be over 100 percent, i.e., overcommitted.)
  Resource           Requests      Limits
  --------           --------      ------
  cpu                850m (21%)    1 (25%)
  memory             5800Mi (74%)  6Gi (78%)`
        }
      },
      {
        phase: "solution",
        question: "The Pod requests `memory: 12Gi` and each worker has about 7.6Gi allocatable. What is a correct fix?",
        options: [
          { text: "Lower the request to what the job really needs, or add a node large enough (e.g. via Cluster Autoscaler).", correct: true, feedback: "Yes. Either shrink the request to fit, or add capacity. Both make a node pass the filter." },
          { text: "Add a toleration for the control-plane taint.", correct: false, feedback: "The control-plane node is not big enough either, and running heavy workloads there risks the control plane." },
          { text: "Remove the memory limit.", correct: false, feedback: "The scheduler filters on **requests**, not limits. The 12Gi request still cannot fit anywhere." }
        ]
      }
    ],
    takeaway: "`Pending` + no node = scheduling. `kubectl describe pod` gives the `FailedScheduling` reason per node: insufficient resources (requests vs allocatable), taints without tolerations, nodeSelector/affinity mismatches, or unbound PVCs.",
    references: [
      { title: "Scheduling, Preemption and Eviction", url: "https://kubernetes.io/docs/concepts/scheduling-eviction/" },
      { title: "Taints and Tolerations", url: "https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/" }
    ]
  },
  {
    id: "ts-service-no-endpoints",
    title: "The Service that routes to nowhere",
    objective: "co-networking",
    lessonId: "services",
    difficulty: 2,
    symptom: 'The `orders` Pods are all `Running` and `1/1` Ready, but other services get "connection refused" or timeouts when calling `http://orders`.',
    evidence: [
      {
        command: "kubectl get svc orders",
        output: `NAME     TYPE        CLUSTER-IP     EXTERNAL-IP   PORT(S)   AGE
orders   ClusterIP   10.96.73.204   <none>        80/TCP    1h`
      },
      {
        command: "kubectl get pods -l app=orders",
        output: `NAME                      READY   STATUS    RESTARTS   AGE
orders-7f8c9d6b5f-6tq2m   1/1     Running   0          1h
orders-7f8c9d6b5f-zx4wd   1/1     Running   0          1h`
      }
    ],
    stages: [
      {
        phase: "hypothesis",
        question: "Pods are healthy and the Service exists. What should you suspect first?",
        options: [
          { text: "The Service is not connected to the Pods \u2014 its selector or port does not match them.", correct: true, feedback: "Right. A Service only forwards to Pods its selector matches, on its targetPort." },
          { text: "The ClusterIP range is exhausted.", correct: false, feedback: "The Service already has a ClusterIP, so allocation succeeded." },
          { text: "The container image is wrong.", correct: false, feedback: "The Pods are Running and Ready, so the image is fine." }
        ]
      },
      {
        phase: "investigation",
        question: "Which command shows whether the Service has backends?",
        options: [
          { text: "kubectl get endpoints orders (or the EndpointSlices for the Service)", correct: true, feedback: "Yes. The endpoint list is exactly where the Service would send traffic." },
          { text: "kubectl get nodes -o wide", correct: false, feedback: "Node addresses do not tell you whether the Service matched any Pods." },
          { text: "kubectl logs deploy/orders", correct: false, feedback: "The app logs will be quiet \u2014 the requests never reach it." }
        ],
        reveal: {
          command: "kubectl get endpoints orders",
          output: `NAME     ENDPOINTS   AGE
orders   <none>      1h`
        }
      },
      {
        phase: "evidence",
        question: "Endpoints are `<none>`. What do you compare next?",
        options: [
          { text: "The Service's selector against the Pods' labels.", correct: true, feedback: "Correct. No ready Pod matched the selector, so nothing was added to the endpoints." },
          { text: "The Service's creation time against the Pods'.", correct: false, feedback: "Order does not matter \u2014 the EndpointSlice controller continuously reconciles matches." },
          { text: "The node's kernel version.", correct: false, feedback: "Matching is done in the control plane via labels, not on nodes." }
        ],
        reveal: {
          command: "kubectl get svc orders -o jsonpath='{.spec.selector}'; echo; kubectl get pods -l app=orders --show-labels",
          output: `{"app":"order"}
NAME                      READY   STATUS    RESTARTS   AGE   LABELS
orders-7f8c9d6b5f-6tq2m   1/1     Running   0          1h    app=orders,pod-template-hash=7f8c9d6b5f
orders-7f8c9d6b5f-zx4wd   1/1     Running   0          1h    app=orders,pod-template-hash=7f8c9d6b5f`
        }
      },
      {
        phase: "solution",
        question: "The Service selects `app=order`; the Pods are labelled `app=orders`. Best fix?",
        options: [
          { text: "Correct the Service selector to app: orders.", correct: true, feedback: "Yes. Endpoints populate within seconds and traffic flows." },
          { text: "Relabel the running Pods with kubectl label.", correct: false, feedback: "New Pods from the Deployment would still lack the label. Fix the selector (or the template) at the source." },
          { text: "Change the Service type to NodePort.", correct: false, feedback: "NodePort uses the same selector \u2014 it would have no endpoints either." }
        ]
      }
    ],
    takeaway: 'When a Service "does nothing", check endpoints first. `<none>` means selector/label mismatch or no Ready Pods; endpoints present but connection refused usually means a wrong `targetPort`.',
    references: [
      { title: "Debug Services", url: "https://kubernetes.io/docs/tasks/debug/debug-application/debug-service/" },
      { title: "Service", url: "https://kubernetes.io/docs/concepts/services-networking/service/" }
    ]
  },
  {
    id: "ts-missing-configmap",
    title: "The config that was never created",
    objective: "co-troubleshooting",
    lessonId: "configmaps-and-secrets",
    difficulty: 2,
    symptom: "A `notifier` Deployment was applied to a fresh `staging` namespace. Its Pod never starts and shows an unusual status.",
    evidence: [
      {
        command: "kubectl get pods -n staging",
        output: `NAME                        READY   STATUS                       RESTARTS   AGE
notifier-6d5b8c7f9c-4wq8z   0/1     CreateContainerConfigError   0          4m`
      }
    ],
    stages: [
      {
        phase: "hypothesis",
        question: "What does `CreateContainerConfigError` suggest?",
        options: [
          { text: "The kubelet cannot build the container's configuration \u2014 often a referenced ConfigMap or Secret (or key) is missing.", correct: true, feedback: "Right. The image is fine, but the kubelet cannot assemble env vars or files the container needs." },
          { text: "The image has an invalid entrypoint.", correct: false, feedback: "A bad entrypoint fails when the container starts (`RunContainerError` or `CrashLoopBackOff`), not while building config." },
          { text: "The scheduler rejected the Pod.", correct: false, feedback: "The Pod has a status from the kubelet, so it was already scheduled." }
        ]
      },
      {
        phase: "investigation",
        question: "Where do you look?",
        options: [
          { text: "kubectl describe pod notifier-6d5b8c7f9c-4wq8z -n staging (Events)", correct: true, feedback: "Yes. The kubelet names the missing object in the event." },
          { text: "kubectl logs notifier-6d5b8c7f9c-4wq8z -n staging --previous", correct: false, feedback: "The container was never created, so there is no previous instance with logs." },
          { text: "kubectl get events -n kube-system", correct: false, feedback: "The relevant events are in the Pod's own namespace, `staging`." }
        ],
        reveal: {
          command: "kubectl describe pod notifier-6d5b8c7f9c-4wq8z -n staging | tail -2",
          output: `  Warning  Failed     12s (x20 over 4m)  kubelet            Error: configmap "notifier-config" not found`
        }
      },
      {
        phase: "evidence",
        question: "How do you confirm the ConfigMap is really missing in this namespace?",
        options: [
          { text: "kubectl get configmaps -n staging", correct: true, feedback: "Correct. ConfigMaps are namespaced \u2014 a Pod can only reference ones in its own namespace." },
          { text: "kubectl get configmaps -n default", correct: false, feedback: "Even if it exists in `default`, a Pod in `staging` cannot use it." },
          { text: "kubectl get nodes", correct: false, feedback: "ConfigMaps are API objects stored in etcd, not on nodes." }
        ],
        reveal: {
          command: "kubectl get configmaps -n staging",
          output: `NAME               DATA   AGE
kube-root-ca.crt   1      6m`
        }
      },
      {
        phase: "solution",
        question: "What is the right fix?",
        options: [
          { text: "Create notifier-config in staging (ideally from the same source as other environments). The kubelet retries and the container starts.", correct: true, feedback: "Yes. No Pod restart is needed; the kubelet keeps retrying until the reference resolves." },
          { text: "Mark the reference optional: true and move on.", correct: false, feedback: "That hides the problem \u2014 the app would start without its config and probably fail later in a less obvious way." },
          { text: "Copy the ConfigMap into kube-system.", correct: false, feedback: "Wrong namespace. References never cross namespaces." }
        ]
      }
    ],
    takeaway: "`CreateContainerConfigError` = a missing ConfigMap/Secret, or a missing **key** in one. Check the event, then check the object exists in the **same namespace**. Order your applies (or use Helm/Kustomize/GitOps) so config lands before workloads.",
    references: [K8S_DEBUG_PODS, { title: "ConfigMaps", url: "https://kubernetes.io/docs/concepts/configuration/configmap/" }]
  },
  {
    id: "ts-pvc-pending",
    title: "The claim nobody answers",
    objective: "co-storage",
    lessonId: "persistent-volumes-and-csi",
    difficulty: 3,
    symptom: "A `postgres` StatefulSet was copied from a cloud cluster into an on-prem cluster. Its Pod is `Pending` and so is its PersistentVolumeClaim.",
    evidence: [
      {
        command: "kubectl get pvc",
        output: `NAME              STATUS    VOLUME   CAPACITY   ACCESS MODES   STORAGECLASS   VOLUMEATTRIBUTESCLASS   AGE
data-postgres-0   Pending                                      fast-ssd       <unset>                 8m`
      }
    ],
    stages: [
      {
        phase: "hypothesis",
        question: "Why might a PVC stay `Pending`?",
        options: [
          { text: "No PV matches it and no provisioner is creating one \u2014 e.g. the StorageClass does not exist here.", correct: true, feedback: "Right. A PVC binds to an existing matching PV or one created by its StorageClass's provisioner." },
          { text: "The Pod using it is in CrashLoopBackOff.", correct: false, feedback: "Cause and effect are reversed: the Pod is Pending *because* its claim is unbound." },
          { text: "etcd is out of disk space.", correct: false, feedback: "Then you could not create the PVC at all; the API write succeeded." }
        ]
      },
      {
        phase: "investigation",
        question: "What do you run to see why it is not binding?",
        options: [
          { text: "kubectl describe pvc data-postgres-0", correct: true, feedback: "Yes. The PV controller and provisioners post events on the claim." },
          { text: "kubectl logs postgres-0", correct: false, feedback: "The Pod has not started \u2014 no logs exist." },
          { text: "kubectl get pv -A", correct: false, feedback: "PersistentVolumes are cluster-scoped; `-A` is meaningless for them, and the list alone does not say why binding failed." }
        ],
        reveal: {
          command: "kubectl describe pvc data-postgres-0 | tail -3",
          output: `  Type     Reason              Age                 From                         Message
  ----     ------              ----                ----                         -------
  Warning  ProvisioningFailed  12s (x34 over 8m)   persistentvolume-controller  storageclass.storage.k8s.io "fast-ssd" not found`
        }
      },
      {
        phase: "evidence",
        question: "Which StorageClasses does this cluster actually offer?",
        options: [
          { text: "kubectl get storageclass", correct: true, feedback: "Correct. StorageClasses are cluster-scoped; the `(default)` marker shows the default class." },
          { text: "kubectl get csidrivers -n default", correct: false, feedback: "CSIDrivers are cluster-scoped and list drivers, not the classes you can request." },
          { text: "kubectl describe node", correct: false, feedback: "Nodes do not list StorageClasses." }
        ],
        reveal: {
          command: "kubectl get storageclass",
          output: `NAME                 PROVISIONER             RECLAIMPOLICY   VOLUMEBINDINGMODE      ALLOWVOLUMEEXPANSION   AGE
standard (default)   rancher.io/local-path   Delete          WaitForFirstConsumer   false                  40d`
        }
      },
      {
        phase: "solution",
        question: "What is the right fix?",
        options: [
          { text: "Use storageClassName: standard (or create an equivalent fast-ssd class) in the StatefulSet's volumeClaimTemplates, then recreate the PVC.", correct: true, feedback: "Yes. Most PVC spec fields are immutable, so delete the Pending claim and let the StatefulSet recreate it from the fixed template." },
          { text: "Edit the PVC to add more storage.", correct: false, feedback: "The size is not the problem; there is no provisioner for the requested class." },
          { text: "Change the access mode to ReadWriteMany.", correct: false, feedback: "RWX is even harder to satisfy, and the class still would not exist." }
        ]
      }
    ],
    takeaway: "StorageClass names are cluster-specific. `kubectl describe pvc` tells you whether the class is missing, no PV matches (size/access mode/class), or binding is waiting for a consumer (`WaitForFirstConsumer` is normal until a Pod uses the claim).",
    references: [
      { title: "Persistent Volumes", url: "https://kubernetes.io/docs/concepts/storage/persistent-volumes/" },
      { title: "Storage Classes", url: "https://kubernetes.io/docs/concepts/storage/storage-classes/" }
    ]
  },
  {
    id: "ts-readiness-failing",
    title: "Running, but not Ready",
    objective: "co-troubleshooting",
    lessonId: "health-probes",
    difficulty: 2,
    symptom: "After a release, the `search` Service intermittently returns 503 from the Ingress. The Pods show `Running` with zero restarts.",
    evidence: [
      {
        command: "kubectl get pods -l app=search",
        output: `NAME                      READY   STATUS    RESTARTS   AGE
search-5b9c8d7f6c-2rlkp   0/1     Running   0          12m
search-5b9c8d7f6c-mf8tz   0/1     Running   0          12m`
      }
    ],
    stages: [
      {
        phase: "hypothesis",
        question: "`Running` but `0/1` Ready, no restarts. What is going on?",
        options: [
          { text: "The readiness probe is failing; the containers run but are not considered ready to receive traffic.", correct: true, feedback: "Right. Readiness failures do not restart containers \u2014 liveness failures do." },
          { text: "The liveness probe is failing.", correct: false, feedback: "A failing liveness probe causes restarts; RESTARTS is 0." },
          { text: "The Pods are still being scheduled.", correct: false, feedback: "They are Running on nodes, so scheduling is done." }
        ]
      },
      {
        phase: "investigation",
        question: "What does this mean for the Service?",
        options: [
          { text: "Not-ready Pods are excluded from the Service's ready endpoints, so there is nothing healthy to route to.", correct: true, feedback: "Correct \u2014 that is why the Ingress returns 503." },
          { text: "The Service load-balances to them anyway.", correct: false, feedback: "Readiness exists precisely to keep not-ready Pods out of rotation." },
          { text: "The Service is deleted automatically.", correct: false, feedback: "The Service stays; only its endpoint list changes." }
        ],
        reveal: {
          command: "kubectl get endpoints search",
          output: `NAME     ENDPOINTS   AGE
search   <none>      30d`
        }
      },
      {
        phase: "evidence",
        question: "How do you see why the probe fails?",
        options: [
          { text: "kubectl describe pod search-5b9c8d7f6c-2rlkp \u2014 look for Unhealthy events and the probe config.", correct: true, feedback: "Yes. The kubelet logs each probe failure as an `Unhealthy` event with the reason." },
          { text: "kubectl get svc search -o yaml", correct: false, feedback: "The Service does not define or report probe results." },
          { text: "kubectl top pods", correct: false, feedback: "Resource usage does not say what the probe returned." }
        ],
        reveal: {
          command: 'kubectl describe pod search-5b9c8d7f6c-2rlkp | grep -E "Readiness|Unhealthy"',
          output: `    Readiness:      http-get http://:8080/healthz delay=0s timeout=1s period=10s #success=1 #failure=3
  Warning  Unhealthy  8s (x70 over 12m)  kubelet  Readiness probe failed: HTTP probe failed with statuscode: 404`
        }
      },
      {
        phase: "solution",
        question: "The release notes say the health endpoint moved to `/ready`. Fix?",
        options: [
          { text: "Update readinessProbe.httpGet.path to /ready in the Deployment.", correct: true, feedback: "Yes. New Pods pass readiness, join the endpoints, and the rollout completes." },
          { text: "Remove the readiness probe.", correct: false, feedback: "That would send traffic to Pods before they are truly ready and hide future problems." },
          { text: "Increase failureThreshold to 100.", correct: false, feedback: "A 404 never turns into a 200 by waiting; the probe still fails, just more slowly." }
        ]
      }
    ],
    takeaway: "`0/1 Running` with no restarts = readiness failing. The Pod is alive but out of the Service's endpoints. Read the `Unhealthy` events, and keep probe paths in sync with the app.",
    references: [
      { title: "Configure Liveness, Readiness and Startup Probes", url: "https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/" },
      K8S_DEBUG
    ]
  },
  {
    id: "ts-oomkilled",
    title: "Killed without a stack trace",
    objective: "kf-scheduling",
    lessonId: "resources-requests-limits",
    difficulty: 2,
    symptom: "The `image-resizer` Pod restarts every few minutes under load. Its logs end abruptly with no error message.",
    evidence: [
      {
        command: "kubectl get pods -l app=image-resizer",
        output: `NAME                             READY   STATUS      RESTARTS      AGE
image-resizer-7d4c9f8b6d-gq5xk   0/1     OOMKilled   4 (30s ago)   22m`
      }
    ],
    stages: [
      {
        phase: "hypothesis",
        question: "What does `OOMKilled` mean?",
        options: [
          { text: "The container used more memory than its limit and the kernel's OOM killer terminated it.", correct: true, feedback: "Right. The process gets SIGKILL \u2014 no chance to log an error, hence the abrupt logs." },
          { text: "The node ran out of disk space.", correct: false, feedback: "Disk pressure leads to eviction (`Evicted`), not OOMKilled." },
          { text: "The image is too large to pull.", correct: false, feedback: "Image size affects pull time, not runtime memory kills." }
        ]
      },
      {
        phase: "investigation",
        question: "Where do you confirm it and see the configured limit?",
        options: [
          { text: "kubectl describe pod \u2014 Last State: Terminated, Reason: OOMKilled, Exit Code: 137, plus the Limits section.", correct: true, feedback: "Yes. Exit code 137 = 128 + 9 (SIGKILL)." },
          { text: "kubectl get events -n kube-system", correct: false, feedback: "The relevant state is on the Pod in its own namespace." },
          { text: "kubectl logs --previous", correct: false, feedback: "Useful context, but the logs just stop \u2014 they cannot show the kill reason or the limit." }
        ],
        reveal: {
          command: 'kubectl describe pod image-resizer-7d4c9f8b6d-gq5xk | grep -A12 "Last State"',
          output: `    Last State:     Terminated
      Reason:       OOMKilled
      Exit Code:    137
      Started:      Thu, 12 Nov 2026 10:02:11 +0000
      Finished:     Thu, 12 Nov 2026 10:05:47 +0000
    Ready:          False
    Restart Count:  4
    Limits:
      memory:  256Mi
    Requests:
      cpu:     100m
      memory:  128Mi`
        }
      },
      {
        phase: "evidence",
        question: "How do you check how much memory the app actually needs under load?",
        options: [
          { text: "kubectl top pod (requires metrics-server) while it handles load, or your Prometheus memory metrics.", correct: true, feedback: "Correct. Measure real usage before choosing a new limit." },
          { text: "kubectl get pod -o wide", correct: false, feedback: "That shows IP and node, not memory usage." },
          { text: "kubectl describe node and read the node's total memory.", correct: false, feedback: "Node capacity does not tell you what this container uses." }
        ],
        reveal: {
          command: "kubectl top pod -l app=image-resizer",
          output: `NAME                             CPU(cores)   MEMORY(bytes)
image-resizer-7d4c9f8b6d-gq5xk   410m         249Mi`
        }
      },
      {
        phase: "solution",
        question: "Typical peak is ~400Mi when resizing large images. Best fix?",
        options: [
          { text: "Raise the memory limit (e.g. 512Mi) and the request to a realistic baseline in the Deployment; investigate leaks if usage keeps growing.", correct: true, feedback: "Yes. Right-size requests/limits from measurements so the scheduler reserves enough and the kernel does not kill normal peaks." },
          { text: "Raise the CPU limit.", correct: false, feedback: "CPU limits cause throttling, not OOM kills. Memory is the constrained resource." },
          { text: "Set restartPolicy: Never.", correct: false, feedback: "Deployments only allow `Always`, and refusing to restart would not stop the kill anyway." }
        ]
      }
    ],
    takeaway: "OOMKilled / exit 137 = memory limit exceeded. Memory is **incompressible** (kill), CPU is **compressible** (throttle). Size limits from measured peaks, and remember requests drive scheduling while limits drive enforcement.",
    references: [
      { title: "Resource Management for Pods and Containers", url: "https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/" },
      K8S_DEBUG_PODS
    ]
  },
  {
    id: "ts-hpa-not-scaling",
    title: "The autoscaler that never scales",
    objective: "cna-ecosystem",
    lessonId: "autoscaling-and-serverless",
    difficulty: 2,
    symptom: "A HorizontalPodAutoscaler targets 60% CPU for the `api` Deployment. A load test drives traffic up, response times climb, but the Deployment stays at 2 replicas.",
    evidence: [
      {
        command: "kubectl get hpa api",
        output: `NAME   REFERENCE        TARGETS              MINPODS   MAXPODS   REPLICAS   AGE
api    Deployment/api   cpu: <unknown>/60%   2         10        2          20m`
      }
    ],
    stages: [
      {
        phase: "hypothesis",
        question: "The TARGETS column shows `<unknown>`. What does that suggest?",
        options: [
          { text: "The HPA cannot read current CPU usage, so it cannot compute a desired replica count.", correct: true, feedback: "Right. Without a current value the HPA has nothing to compare against the 60% target." },
          { text: "The Deployment has reached maxReplicas.", correct: false, feedback: "maxReplicas is 10 and there are only 2 replicas, so the ceiling is not the problem." },
          { text: "The scheduler has no room for new Pods.", correct: false, feedback: "That would show as Pending Pods after the HPA scales up. Here the HPA never asks for more replicas." }
        ]
      },
      {
        phase: "investigation",
        question: "Where does the HPA get CPU usage from for a `cpu` resource target?",
        options: [
          { text: "The resource metrics API (metrics.k8s.io), usually served by metrics-server.", correct: true, feedback: "Correct. Resource-based HPA reads the metrics API, which metrics-server normally provides." },
          { text: "Directly from the container runtime on each node.", correct: false, feedback: "The HPA controller talks to aggregated metrics APIs, not to runtimes." },
          { text: "From the Deployment status field.", correct: false, feedback: "Deployment status has replica counts, not CPU usage." }
        ],
        reveal: {
          command: "kubectl top pods -l app=api",
          output: "error: Metrics API not available"
        }
      },
      {
        phase: "evidence",
        question: "The metrics API is unavailable. What else must be true for a CPU-utilisation target to work, even once metrics exist?",
        options: [
          { text: "The containers must declare CPU requests, because utilisation is measured as a percentage of the request.", correct: true, feedback: 'Exactly. With no CPU request there is no denominator for "60%".' },
          { text: "The Pods must run as root.", correct: false, feedback: "Security context has nothing to do with metrics collection." },
          { text: "The Service must be of type LoadBalancer.", correct: false, feedback: "Service type does not affect how the HPA measures CPU." }
        ],
        reveal: {
          command: "kubectl get deploy api -o jsonpath='{.spec.template.spec.containers[0].resources}'",
          output: '{"requests":{"cpu":"200m","memory":"128Mi"}}'
        }
      },
      {
        phase: "solution",
        question: "CPU requests are set. What fixes the problem?",
        options: [
          { text: "Install (or repair) metrics-server so the resource metrics API is served; the HPA then sees usage and scales.", correct: true, feedback: "Yes. Once `kubectl top pods` works, the TARGETS column shows a real value and the HPA reacts." },
          { text: "Raise maxReplicas to 50.", correct: false, feedback: "The HPA is not hitting its ceiling; it simply has no data." },
          { text: "Delete the HPA and scale manually forever.", correct: false, feedback: "That works around the symptom but abandons autoscaling instead of fixing the missing metrics pipeline." }
        ]
      }
    ],
    takeaway: "Resource-based autoscaling needs two things: a working metrics pipeline (metrics-server or another provider of metrics.k8s.io) and resource requests on the containers. `<unknown>` in `kubectl get hpa` is the classic sign of the first one missing.",
    references: [{ title: "Horizontal Pod Autoscaling", url: "https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/" }]
  },
  {
    id: "ts-latency-observability",
    title: "Checkout is slow \u2014 find the culprit",
    objective: "cna-observability",
    lessonId: "observability-fundamentals",
    difficulty: 2,
    symptom: "An SLO alert fires: 99th percentile checkout latency is 2.8s against a 500ms objective. All Pods are Running and Ready, and nothing has restarted.",
    evidence: [
      {
        command: "kubectl get pods -n shop",
        output: `NAME                        READY   STATUS    RESTARTS   AGE
checkout-6d8f7c9b4-2xk8q    1/1     Running   0          3d
payments-5b9c6d7f8-p7wqz    1/1     Running   0          3d
inventory-7f6b5c4d9-lm2rt   1/1     Running   0          2h`
      }
    ],
    stages: [
      {
        phase: "hypothesis",
        question: "Pods look healthy. What is the best first hypothesis?",
        options: [
          { text: "One of the services in the request path is slow; the problem is latency, not availability.", correct: true, feedback: "Right. Ready Pods only prove health checks pass; they say nothing about how fast requests are served." },
          { text: "The cluster DNS is down.", correct: false, feedback: "A DNS outage would cause errors and failed lookups across many services, not slow-but-successful checkouts." },
          { text: "The Pods are being OOMKilled.", correct: false, feedback: "OOMKills would show as restarts; there are none." }
        ]
      },
      {
        phase: "investigation",
        question: "Which signal tells you where the 2.8 seconds is spent inside one slow checkout request?",
        options: [
          { text: "A distributed trace of a slow request, broken into spans per service.", correct: true, feedback: "Yes. Traces attribute time to each hop, which metrics and logs alone cannot do for a single request." },
          { text: "The total request counter for checkout.", correct: false, feedback: "A counter shows volume, not where latency comes from." },
          { text: "kubectl get events -n shop", correct: false, feedback: "Events describe object lifecycle changes such as scheduling, not request timing." }
        ],
        reveal: {
          command: "trace 4f9a\u2026 (from the tracing backend)",
          output: `checkout  POST /checkout          2.81s
\u251C\u2500 payments  POST /authorize       0.12s
\u2514\u2500 inventory GET /reserve          2.61s
   \u2514\u2500 inventory \u2192 postgres query   2.58s`
        }
      },
      {
        phase: "evidence",
        question: "The trace points at inventory\u2019s database query. What evidence explains why it started now?",
        options: [
          { text: "Inventory\u2019s logs and metrics around its deployment 2 hours ago (e.g. slow-query logs, query latency histograms).", correct: true, feedback: "Good: the inventory Pod is only 2h old, which lines up with a recent change. Logs give the detail behind the slow span." },
          { text: "The node\u2019s kernel version.", correct: false, feedback: "Nothing points at the node; only one service\u2019s queries are slow." },
          { text: "The payments service\u2019s logs.", correct: false, feedback: "Payments took only 0.12s in the trace." }
        ],
        reveal: {
          command: "kubectl logs deploy/inventory -n shop | grep -i slow | tail -2",
          output: `WARN slow query 2571ms: SELECT * FROM stock WHERE sku = $1 (seq scan on stock)
WARN slow query 2602ms: SELECT * FROM stock WHERE sku = $1 (seq scan on stock)`
        }
      },
      {
        phase: "solution",
        question: "What is the most appropriate fix?",
        options: [
          { text: "Roll back the inventory release (or restore the dropped index it introduced), then verify latency recovers against the SLO.", correct: true, feedback: "Yes. Fix the cause the evidence points to, and confirm with the same metric that alerted." },
          { text: "Scale checkout to 20 replicas.", correct: false, feedback: "More checkout Pods will not make inventory\u2019s database query faster." },
          { text: "Raise the SLO target to 3 seconds.", correct: false, feedback: "That hides the regression instead of fixing it." }
        ]
      }
    ],
    takeaway: "Use the three signals together: metrics (and SLO alerts) tell you something is wrong, traces tell you where, and logs tell you why. Healthy, Ready Pods do not mean a fast service.",
    references: [{ title: "OpenTelemetry documentation", url: "https://opentelemetry.io/docs/" }, { title: "Prometheus overview", url: "https://prometheus.io/docs/introduction/overview/" }]
  }
];

// ../../packages/content/src/index.ts
var lessons = [...lessonsA, ...lessonsB, ...lessonsC].sort(
  (a, b) => a.stage - b.stage || a.order - b.order
);
var questions = [
  ...questionsFundamentals,
  ...questionsOrchestration,
  ...questionsDeliveryArchitecture
];
var lessonIndex = new Map(lessons.map((l) => [l.id, l]));
var questionIndex = new Map(questions.map((q) => [q.id, q]));
var lessonById = (id) => lessonIndex.get(id);
var questionById = (id) => questionIndex.get(id);

// ../../packages/engine/src/corpus.ts
var lessonHref = (id, anchor) => `#/lessons/${id}${anchor ? `?s=${anchor}` : ""}`;
function lessonDocs(l) {
  const base = { lessonId: l.id, objective: l.objectives[0], refs: l.references };
  const docs = [
    { ...base, id: `lesson:${l.id}`, kind: "lesson", title: l.title, text: `${l.summary}
${l.what}
${l.keyTerms.join(", ")}`, href: lessonHref(l.id) },
    { ...base, id: `lesson:${l.id}:why`, kind: "section", title: `${l.title} \u2014 why it exists`, text: `${l.why}
${l.problem}`, href: lessonHref(l.id, "why") },
    { ...base, id: `lesson:${l.id}:how`, kind: "section", title: `${l.title} \u2014 how it works`, text: l.how, href: lessonHref(l.id, "how") },
    {
      ...base,
      id: `lesson:${l.id}:components`,
      kind: "section",
      title: `${l.title} \u2014 components`,
      text: l.components.map((c) => `${c.name}: ${c.description}`).join("\n"),
      href: lessonHref(l.id, "components")
    },
    {
      ...base,
      id: `lesson:${l.id}:misconceptions`,
      kind: "section",
      title: `${l.title} \u2014 common misconceptions`,
      text: l.misconceptions.map((m) => `Myth: ${m.myth}
Reality: ${m.reality}`).join("\n"),
      href: lessonHref(l.id, "misconceptions")
    },
    {
      ...base,
      id: `lesson:${l.id}:example`,
      kind: "section",
      title: `${l.title} \u2014 example: ${l.example.title}`,
      text: `${l.example.description}
${l.example.code ?? ""}`,
      href: lessonHref(l.id, "example")
    }
  ];
  if (l.deeper)
    docs.push({ ...base, id: `lesson:${l.id}:deeper`, kind: "section", title: `${l.title} \u2014 beyond the exam`, text: l.deeper, href: lessonHref(l.id, "deeper") });
  l.faq.forEach(
    (f, i) => docs.push({ ...base, id: `lesson:${l.id}:faq:${i}`, kind: "faq", title: f.q, text: f.a, href: lessonHref(l.id, "faq") })
  );
  return docs;
}
function buildCorpus(opts = {}) {
  const docs = lessons.flatMap(lessonDocs);
  for (const g of glossary)
    docs.push({
      id: `glossary:${g.term}`,
      kind: "glossary",
      title: g.term,
      text: g.definition + (g.related?.length ? `
Related: ${g.related.join(", ")}` : ""),
      href: `#/glossary?q=${encodeURIComponent(g.term)}`,
      lessonId: g.lessonId,
      objective: g.objective
    });
  for (const c of comparisons)
    docs.push({
      id: `comparison:${c.id}`,
      kind: "comparison",
      title: [c.a, c.b, c.c].filter(Boolean).join(" vs "),
      text: `${c.rule}
${c.rows.map((r) => `${r.aspect}: ${c.a}: ${r.a}; ${c.b}: ${r.b}${c.c ? `; ${c.c}: ${r.c}` : ""}`).join("\n")}
Exam trap: ${c.examTrap}`,
      href: `#/compare?id=${c.id}`,
      lessonId: c.lessonId,
      objective: c.objective
    });
  for (const lab of labs)
    docs.push({
      id: `lab:${lab.id}`,
      kind: "lab",
      title: `Lab: ${lab.title}`,
      text: `${lab.objective}
${lab.tasks.map((t) => t.title).join("\n")}
${lab.troubleshooting.map((t) => `${t.symptom}: ${t.fix}`).join("\n")}`,
      href: `#/labs/${lab.id}`,
      objective: lab.objectives[0],
      refs: lab.references
    });
  for (const f of flashcards)
    docs.push({ id: `flashcard:${f.id}`, kind: "flashcard", title: f.front, text: f.back, href: `#/lessons/${f.lessonId}`, lessonId: f.lessonId, objective: f.objective });
  if (opts.includeQuestions)
    for (const q of questions)
      docs.push({
        id: `question:${q.id}`,
        kind: "question",
        title: q.prompt.slice(0, 120),
        text: q.explanation,
        href: `#/lessons/${q.lessonId}`,
        lessonId: q.lessonId,
        objective: q.objective,
        refs: q.references
      });
  return docs;
}
var cached;
function contentIndex() {
  return cached ??= new SearchIndex(buildCorpus());
}

// ../../packages/engine/src/kubectl.ts
var RESOURCE_ALIASES = {};
var KINDS = [
  ["pods", ["pod", "po"]],
  ["deployments", ["deployment", "deploy"]],
  ["replicasets", ["replicaset", "rs"]],
  ["services", ["service", "svc"]],
  ["nodes", ["node", "no"]],
  ["namespaces", ["namespace", "ns"]],
  ["configmaps", ["configmap", "cm"]],
  ["secrets", ["secret"]],
  ["events", ["event", "ev"]],
  ["persistentvolumeclaims", ["persistentvolumeclaim", "pvc"]],
  ["persistentvolumes", ["persistentvolume", "pv"]],
  ["storageclasses", ["storageclass", "sc"]],
  ["ingresses", ["ingress", "ing"]],
  ["networkpolicies", ["networkpolicy", "netpol"]],
  ["serviceaccounts", ["serviceaccount", "sa"]],
  ["roles", ["role"]],
  ["rolebindings", ["rolebinding"]],
  ["clusterroles", ["clusterrole"]],
  ["clusterrolebindings", ["clusterrolebinding"]],
  ["jobs", ["job"]],
  ["cronjobs", ["cronjob", "cj"]],
  ["daemonsets", ["daemonset", "ds"]],
  ["statefulsets", ["statefulset", "sts"]],
  ["endpoints", ["endpoint", "ep"]],
  ["endpointslices", ["endpointslice"]],
  ["horizontalpodautoscalers", ["horizontalpodautoscaler", "hpa"]],
  ["all", []]
];
for (const [canon, aliases] of KINDS) {
  RESOURCE_ALIASES[canon] = canon;
  for (const a of aliases) RESOURCE_ALIASES[a] = canon;
}

// ../../packages/engine/src/yamlcheck.ts
var import_yaml2 = __toESM(require_dist(), 1);
var isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
function getPath(root, path) {
  let cur = root;
  for (const part of path.split(".")) {
    const m = part.match(/^([^[\]]*)((?:\[\d+\])*)$/);
    if (!m) return void 0;
    if (m[1]) {
      if (!isObj(cur)) return void 0;
      cur = cur[m[1]];
    }
    for (const idx of m[2].match(/\d+/g) ?? []) {
      if (!Array.isArray(cur)) return void 0;
      cur = cur[Number(idx)];
    }
  }
  return cur;
}
var KNOWN_KINDS = {
  Pod: ["v1"],
  Service: ["v1"],
  ConfigMap: ["v1"],
  Secret: ["v1"],
  Namespace: ["v1"],
  ServiceAccount: ["v1"],
  PersistentVolume: ["v1"],
  PersistentVolumeClaim: ["v1"],
  Deployment: ["apps/v1"],
  ReplicaSet: ["apps/v1"],
  StatefulSet: ["apps/v1"],
  DaemonSet: ["apps/v1"],
  Job: ["batch/v1"],
  CronJob: ["batch/v1"],
  Ingress: ["networking.k8s.io/v1"],
  NetworkPolicy: ["networking.k8s.io/v1"],
  Role: ["rbac.authorization.k8s.io/v1"],
  RoleBinding: ["rbac.authorization.k8s.io/v1"],
  ClusterRole: ["rbac.authorization.k8s.io/v1"],
  ClusterRoleBinding: ["rbac.authorization.k8s.io/v1"],
  StorageClass: ["storage.k8s.io/v1"],
  HorizontalPodAutoscaler: ["autoscaling/v2"]
};
var WORKLOADS_WITH_TEMPLATE = /* @__PURE__ */ new Set(["Deployment", "ReplicaSet", "StatefulSet", "DaemonSet", "Job"]);
function podSpecOf(doc) {
  const kind = doc.kind;
  if (kind === "Pod") return { spec: getPath(doc, "spec"), base: "spec" };
  if (kind === "CronJob") return { spec: getPath(doc, "spec.jobTemplate.spec.template.spec"), base: "spec.jobTemplate.spec.template.spec" };
  if (WORKLOADS_WITH_TEMPLATE.has(kind)) return { spec: getPath(doc, "spec.template.spec"), base: "spec.template.spec" };
  return { spec: void 0, base: "" };
}
var QUANTITY = /^\d+(\.\d+)?(m|Ki|Mi|Gi|Ti|Pi|Ei|k|M|G|T|P|E)?$/;
var DNS1123 = /^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$/;
function lintManifest(doc) {
  const f = [];
  const kind = doc.kind;
  if (typeof doc.apiVersion !== "string") f.push({ level: "error", message: "Missing apiVersion.", path: "apiVersion" });
  if (typeof kind !== "string") {
    f.push({ level: "error", message: "Missing kind.", path: "kind" });
    return f;
  }
  const known = KNOWN_KINDS[kind];
  if (known && typeof doc.apiVersion === "string" && !known.includes(doc.apiVersion))
    f.push({ level: "error", message: `${kind} uses apiVersion ${known.join(" or ")}, not "${doc.apiVersion}".`, path: "apiVersion" });
  if (!known) f.push({ level: "info", message: `Kind "${kind}" is not in the trainer's built-in list; only generic checks applied.` });
  const name = getPath(doc, "metadata.name");
  if (typeof name !== "string") f.push({ level: "error", message: "metadata.name is required.", path: "metadata.name" });
  else if (!DNS1123.test(name)) f.push({ level: "error", message: `metadata.name "${name}" must be lowercase alphanumerics, "-" or ".".`, path: "metadata.name" });
  if (WORKLOADS_WITH_TEMPLATE.has(kind) && kind !== "Job") {
    const sel = getPath(doc, "spec.selector.matchLabels");
    const labels = getPath(doc, "spec.template.metadata.labels");
    if (!isObj(sel)) f.push({ level: "error", message: `${kind} needs spec.selector.matchLabels.`, path: "spec.selector.matchLabels" });
    else if (!isObj(labels) || Object.entries(sel).some(([k, v]) => labels[k] !== v))
      f.push({ level: "error", message: "spec.selector.matchLabels must match spec.template.metadata.labels \u2014 otherwise the API server rejects the object.", path: "spec.selector" });
  }
  const { spec, base } = podSpecOf(doc);
  if (base) {
    const containers = spec?.containers;
    if (!Array.isArray(containers) || !containers.length) f.push({ level: "error", message: "A Pod template needs at least one container.", path: `${base}.containers` });
    else
      containers.forEach((c, i) => {
        const p = `${base}.containers[${i}]`;
        if (!isObj(c)) return;
        if (typeof c.name !== "string") f.push({ level: "error", message: "Every container needs a name.", path: `${p}.name` });
        if (typeof c.image !== "string" || !c.image) f.push({ level: "error", message: "Every container needs an image.", path: `${p}.image` });
        else if (!c.image.includes(":") && !c.image.includes("@"))
          f.push({ level: "warning", message: `Image "${c.image}" has no tag, so it resolves to :latest \u2014 pin a version for reproducible rollouts.`, path: `${p}.image` });
        else if (c.image.endsWith(":latest")) f.push({ level: "warning", message: "Avoid the :latest tag in manifests; pin a version.", path: `${p}.image` });
        const res = c.resources;
        if (!isObj(res)) f.push({ level: "info", message: `Container "${String(c.name)}" sets no resource requests/limits (BestEffort QoS).`, path: `${p}.resources` });
        else
          for (const section of ["requests", "limits"]) {
            const r = res[section];
            if (isObj(r)) {
              for (const [k, v] of Object.entries(r))
                if (!QUANTITY.test(String(v))) f.push({ level: "error", message: `${section}.${k} "${String(v)}" is not a valid quantity (e.g. 250m, 128Mi).`, path: `${p}.resources.${section}.${k}` });
            }
          }
        if (Array.isArray(c.ports))
          c.ports.forEach((port, j) => {
            if (isObj(port) && typeof port.containerPort !== "number")
              f.push({ level: "error", message: "containerPort must be a number.", path: `${p}.ports[${j}].containerPort` });
          });
        for (const probe of ["livenessProbe", "readinessProbe", "startupProbe"])
          if (isObj(c[probe]) && !["httpGet", "tcpSocket", "exec", "grpc"].some((h) => isObj(c[probe][h])))
            f.push({ level: "error", message: `${probe} needs a handler: httpGet, tcpSocket, exec or grpc.`, path: `${p}.${probe}` });
      });
    if (spec && isObj(spec.securityContext) === false && kind === "Pod")
      f.push({ level: "info", message: "Consider a securityContext (runAsNonRoot, readOnlyRootFilesystem) for least privilege." });
  }
  if (kind === "Service") {
    const ports = getPath(doc, "spec.ports");
    if (!Array.isArray(ports) || !ports.length) f.push({ level: "error", message: "A Service needs spec.ports.", path: "spec.ports" });
    if (!isObj(getPath(doc, "spec.selector")) && getPath(doc, "spec.type") !== "ExternalName")
      f.push({ level: "warning", message: "Service has no selector, so Kubernetes will not create endpoints for it automatically.", path: "spec.selector" });
    const type = getPath(doc, "spec.type");
    if (type !== void 0 && !["ClusterIP", "NodePort", "LoadBalancer", "ExternalName"].includes(String(type)))
      f.push({ level: "error", message: `Unknown Service type "${String(type)}".`, path: "spec.type" });
  }
  if (kind === "Secret" && isObj(doc.data))
    f.push({ level: "info", message: "Secret data is only base64-encoded. Enable encryption at rest and restrict access with RBAC." });
  if (kind === "PersistentVolumeClaim") {
    const modes = getPath(doc, "spec.accessModes");
    if (!Array.isArray(modes) || !modes.length) f.push({ level: "error", message: "A PVC needs spec.accessModes.", path: "spec.accessModes" });
    else
      for (const m of modes)
        if (!["ReadWriteOnce", "ReadOnlyMany", "ReadWriteMany", "ReadWriteOncePod"].includes(String(m)))
          f.push({ level: "error", message: `Unknown access mode "${String(m)}".`, path: "spec.accessModes" });
    if (getPath(doc, "spec.resources.requests.storage") === void 0)
      f.push({ level: "error", message: "A PVC needs spec.resources.requests.storage.", path: "spec.resources.requests.storage" });
  }
  return f;
}
function parseManifests(text) {
  const docs = (0, import_yaml2.parseAllDocuments)(text);
  const documents = [];
  for (const d of Array.isArray(docs) ? docs : [docs]) {
    if (d.errors.length) {
      const e = d.errors[0];
      const line = e.linePos?.[0]?.line;
      return { parsed: false, documents: [], findings: [], error: `YAML syntax error${line ? ` on line ${line}` : ""}: ${e.message.split("\n")[0]}` };
    }
    const js = d.toJS();
    if (js === null || js === void 0) continue;
    if (!isObj(js)) return { parsed: false, documents: [], findings: [], error: "Each YAML document must be a mapping (key: value), not a list or scalar." };
    documents.push(js);
  }
  const findings = documents.flatMap((d) => lintManifest(d));
  return { parsed: true, documents, findings };
}

// ../../packages/engine/src/tutor.ts
var TUTOR_MODES = ["explain", "socratic", "exam-coach", "troubleshoot", "yaml-review", "revision"];
var TUTOR_LIMITS = {
  maxMessages: 12,
  maxUserChars: 2e3,
  maxAssistantChars: 4e3,
  maxYamlChars: 6e3,
  maxPerformanceChars: 1500,
  maxLabErrorChars: 2e3,
  maxPageChars: 80,
  retrievalDocs: 4,
  snippetChars: 600
};
var isObj2 = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
var ID = /^[a-z0-9:-]{1,80}$/;
function validateTutorRequest(body) {
  if (!isObj2(body)) return { ok: false, error: "Body must be a JSON object." };
  const mode = body.mode ?? "explain";
  if (typeof mode !== "string" || !TUTOR_MODES.includes(mode)) return { ok: false, error: "Unknown tutor mode." };
  const level = body.level ?? "beginner";
  if (level !== "beginner" && level !== "technical") return { ok: false, error: "level must be beginner or technical." };
  if (!Array.isArray(body.messages) || body.messages.length === 0) return { ok: false, error: "messages must be a non-empty array." };
  const L = TUTOR_LIMITS;
  const messages = [];
  for (const m of body.messages.slice(-L.maxMessages)) {
    if (!isObj2(m) || m.role !== "user" && m.role !== "assistant" || typeof m.content !== "string")
      return { ok: false, error: "Each message needs role (user|assistant) and string content." };
    const max = m.role === "user" ? L.maxUserChars : L.maxAssistantChars;
    if (m.role === "user" && m.content.length > max) return { ok: false, error: `Messages are limited to ${max} characters.` };
    const content = m.content.slice(0, max).trim();
    if (!content) return { ok: false, error: "Messages must not be empty." };
    messages.push({ role: m.role, content });
  }
  if (messages[0].role !== "user") messages.shift();
  if (!messages.length || messages[messages.length - 1].role !== "user") return { ok: false, error: "The last message must come from the user." };
  const ctx = {};
  const c = body.context;
  if (c !== void 0) {
    if (!isObj2(c)) return { ok: false, error: "context must be an object." };
    if (c.lessonId !== void 0) {
      if (typeof c.lessonId !== "string" || !ID.test(c.lessonId) || !lessonById(c.lessonId)) return { ok: false, error: "Unknown lessonId." };
      ctx.lessonId = c.lessonId;
    }
    if (c.questionId !== void 0) {
      if (typeof c.questionId !== "string" || !questionById(c.questionId)) return { ok: false, error: "Unknown questionId." };
      ctx.questionId = c.questionId;
      if (c.selected !== void 0) {
        const q = questionById(c.questionId);
        if (!Array.isArray(c.selected) || c.selected.length > q.choices.length || !c.selected.every((i) => Number.isInteger(i) && i >= 0 && i < q.choices.length))
          return { ok: false, error: "selected must be valid choice indices." };
        ctx.selected = c.selected;
      }
    }
    if (c.yaml !== void 0) {
      if (typeof c.yaml !== "string" || c.yaml.length > L.maxYamlChars) return { ok: false, error: `YAML is limited to ${L.maxYamlChars} characters.` };
      ctx.yaml = c.yaml;
    }
    if (c.performance !== void 0) {
      if (typeof c.performance !== "string") return { ok: false, error: "performance must be a string." };
      ctx.performance = c.performance.slice(0, L.maxPerformanceChars);
    }
    if (c.page !== void 0) {
      if (typeof c.page !== "string" || c.page.length > L.maxPageChars) return { ok: false, error: "page is invalid." };
      ctx.page = c.page;
    }
    if (c.labError !== void 0) {
      if (typeof c.labError !== "string") return { ok: false, error: "labError must be a string." };
      ctx.labError = c.labError.slice(0, L.maxLabErrorChars);
    }
  }
  return { ok: true, value: { mode, level, messages, context: ctx } };
}
var MODE_INSTRUCTIONS = {
  explain: "MODE: Explain. Teach the concept clearly: start with a one-sentence answer, then how it works, then a concrete example (YAML or kubectl if useful). End with one short question that checks understanding.",
  socratic: "MODE: Socratic. Do NOT give the full answer. Ask one or two guiding questions at a time that lead the learner to reason it out, building on what they said. Confirm or gently correct their reasoning. Reveal the answer only if they explicitly ask for it.",
  "exam-coach": 'MODE: Exam coach. Focus strictly on what the KCNA exam expects. Name the tested concept, the common misconception or trap, and why each wrong option is wrong. Keep it brief and exam-oriented; label anything deeper as "beyond KCNA".',
  troubleshoot: "MODE: Troubleshooting. Work through Symptom \u2192 Hypothesis \u2192 Investigation \u2192 Evidence \u2192 Solution. Ask what the learner observes and suggest the next kubectl command to gather evidence. Do not reveal the final fix until the evidence supports it or the learner asks for it.",
  "yaml-review": "MODE: YAML review. Explain what the manifest does, field by field where it matters, then list problems. Treat the deterministic validator findings below as facts. Never invent fields; if unsure whether a field exists, say so.",
  revision: "MODE: Revision coach. Use the learner's performance summary to explain WHY specific topics are recommended, then run a short focused revision: a key-idea recap and 2-3 quick practice questions (answers hidden until the learner replies)."
};
var SYSTEM_RULES = `You are the KCNA Tutor inside the KCNA Interactive Learning Lab, helping a learner prepare for the CNCF Kubernetes and Cloud Native Associate exam.
Rules:
- Ground answers in the REFERENCE MATERIAL supplied with the question; cite it inline as [1], [2]. If the material does not cover something, say so and answer cautiously from general Kubernetes knowledge, marking it "(general knowledge \u2014 verify in the docs)".
- Never invent kubectl commands, flags, API fields or documentation links. Only mention URLs that appear in the reference material.
- Prefer the reference material over your own memory whenever they differ.
- Be precise about these frequently confused facts:
  * When a container crashes, the kubelet restarts that container in place inside the same Pod (same Pod name and IP; RESTARTS increases; repeated crashes show CrashLoopBackOff). Files in the container's writable layer are lost on restart; only volumes persist. A controller creates a replacement Pod only when the Pod object is deleted or evicted, or its node is lost.
  * Roll back a Deployment with \`kubectl rollout undo deployment/<name>\`; deleting a Deployment deletes its Pods.
  * Secrets are base64-encoded, not encrypted, by default.
  * The scheduler only assigns Pods to nodes; the kubelet starts containers.
- When something goes beyond the KCNA exam, label it "(beyond KCNA)".
- If an AUTHORITATIVE ANSWER is provided, it is correct. Never contradict it; explain it.
- Say when you are uncertain. Keep answers focused: usually under 200 words. Use short paragraphs, bullet lists and fenced code blocks.
- Stay on Kubernetes, cloud-native and KCNA study topics; politely decline unrelated requests.`;
function systemPrompt(mode, level) {
  const lvl = level === "beginner" ? "LEVEL: Beginner \u2014 use plain language and an everyday analogy before technical detail." : "LEVEL: Technical \u2014 use precise terminology and mention the relevant API objects and fields.";
  return `${SYSTEM_RULES}

${MODE_INSTRUCTIONS[mode]}
${lvl}`;
}
var QUERY_EXPANSIONS = [
  [/\bcrash(es|ed|ing)?\b|\bdies?\b|\bkeeps? (dying|failing)\b/i, "container restart restartPolicy CrashLoopBackOff exits back-off kubelet"],
  [/\broll ?back|\brevert|\bundo\b/i, "rollout undo revision history ReplicaSet"],
  [/\bexpose|\breach(able)?\b|\baccess (my|the) app/i, "Service ClusterIP NodePort LoadBalancer Ingress"],
  [/\bpersist|\bkeep (my |the )?data|\blose data|\bdata loss/i, "PersistentVolume PersistentVolumeClaim volume storage"],
  [/\bpermission|\bforbidden|\bnot allowed|\bwho can\b/i, "RBAC Role RoleBinding ServiceAccount authorization"],
  [/\bslow|\blatency/i, "latency metrics traces observability"],
  [/\bstuck\b|\bpending\b|\bwon'?t (start|schedule)/i, "Pending scheduling FailedScheduling events describe"],
  [/\bscale|\bmore (copies|replicas)|\bautoscal/i, "replicas scale HorizontalPodAutoscaler"],
  [/\bpassword|\bcredential|\bapi key/i, "Secret ConfigMap"],
  [/\bhealth ?check|\bnot ready\b/i, "readiness liveness probe"]
];
function expandQuery(q) {
  const extra = QUERY_EXPANSIONS.filter(([re]) => re.test(q)).map(([, t]) => t);
  return extra.length ? `${q} ${extra.join(" ")}` : q;
}
function retrievalQuery(req) {
  const users = req.messages.filter((m) => m.role === "user");
  const last = users[users.length - 1]?.content ?? "";
  const prev = users.length > 1 ? users[users.length - 2].content : "";
  const lesson = req.context.lessonId ? lessonById(req.context.lessonId)?.title ?? "" : "";
  const q = req.context.questionId ? questionById(req.context.questionId)?.prompt ?? "" : "";
  return [expandQuery(last), last.length < 80 ? prev : "", lesson, q.slice(0, 200)].filter(Boolean).join(" ");
}
function retrieve(index, req) {
  return index.search(retrievalQuery(req), { limit: TUTOR_LIMITS.retrievalDocs, boostLesson: req.context.lessonId });
}
var letter = (i) => String.fromCharCode(65 + i);
function contextBlock(req, hits) {
  const parts = [];
  const sources = [];
  const seen = /* @__PURE__ */ new Set();
  hits.forEach((h, i) => {
    const snippet = h.doc.text.replace(/\s+/g, " ").slice(0, TUTOR_LIMITS.snippetChars);
    parts.push(`[${i + 1}] ${h.doc.title}
${snippet}`);
    sources.push({ title: h.doc.title, href: h.doc.href });
    for (const r of h.doc.refs ?? [])
      if (!seen.has(r.url) && sources.length < 10) {
        sources.push({ title: r.title, href: r.url, url: r.url });
        seen.add(r.url);
      }
  });
  const ctx = req.context;
  const extra = [];
  if (ctx.lessonId) {
    const l = lessonById(ctx.lessonId);
    extra.push(`CURRENT LESSON: ${l.title} (scope: ${l.scope}). Summary: ${l.summary}`);
  }
  if (ctx.page) {
    const [kind, id] = ctx.page.split(":");
    const item = kind === "terminal" ? terminalChallenges.find((t) => t.id === id)?.title : kind === "yaml" ? yamlChallenges.find((t) => t.id === id)?.title : kind === "troubleshoot" ? troubleshootingScenarios.find((t) => t.id === id)?.title : kind === "lab" ? labs.find((t) => t.id === id)?.title : id;
    extra.push(`LEARNER IS VIEWING: ${kind}${item ? ` \u2014 ${item}` : ""}`);
  }
  if (ctx.questionId) {
    const q = questionById(ctx.questionId);
    const choices = q.choices.map((c, i) => `${letter(i)}. ${c}`).join("\n");
    const sel = ctx.selected?.length ? ctx.selected.map(letter).join(", ") : "nothing";
    extra.push(
      `PRACTICE QUESTION (unofficial, original):
${q.prompt}
${choices}
Learner selected: ${sel}
AUTHORITATIVE ANSWER: ${q.answer.map(letter).join(", ")}
Official explanation: ${q.explanation}
Per-option notes:
${q.choiceRationale.map((r, i) => `${letter(i)}: ${r}`).join("\n")}`
    );
  }
  if (ctx.yaml) {
    const report = parseManifests(ctx.yaml);
    const findings = report.parsed ? report.findings.map((f) => `- ${f.level.toUpperCase()}: ${f.message}${f.path ? ` (${f.path})` : ""}`).join("\n") || "- No issues found by the validator." : `- ${report.error}`;
    extra.push(`MANIFEST:
\`\`\`yaml
${ctx.yaml}
\`\`\`
DETERMINISTIC VALIDATOR FINDINGS:
${findings}`);
  }
  if (ctx.labError) extra.push(`LAB ERROR OUTPUT FROM THE LEARNER:
\`\`\`
${ctx.labError}
\`\`\``);
  if (ctx.performance) extra.push(`LEARNER PERFORMANCE SUMMARY (from local progress):
${ctx.performance}`);
  const text = [parts.length ? `REFERENCE MATERIAL:
${parts.join("\n\n")}` : "REFERENCE MATERIAL: none matched.", ...extra].join("\n\n");
  return { text, sources };
}
function buildChat(req, hits) {
  const { text, sources } = contextBlock(req, hits);
  const history = req.messages.slice(0, -1);
  const last = req.messages[req.messages.length - 1];
  return {
    messages: [
      { role: "system", content: systemPrompt(req.mode, req.level) },
      ...history,
      { role: "user", content: `${text}

---
LEARNER: ${last.content}` }
    ],
    sources
  };
}
function cleanModelOutput(s) {
  return s.replace(/<think>[\s\S]*?<\/think>/g, "").replace(/^\s*<think>[\s\S]*$/, "").trimStart();
}

// ../../packages/engine/src/factguard.ts
var RULES = [
  {
    id: "container-restart-data",
    pattern: /\bno data loss\b|data[^.]{0,50}\b(preserved|safe|kept|survives?)\b[^.]{0,60}\b(restart|crash|recreat|replac)|\b(restart|crash|recreat|replac)\w*[^.]{0,60}\bdata[^.]{0,40}\b(preserved|safe|kept)\b/i,
    correction: "When a container restarts, anything written to its own filesystem (writable layer) is lost. Only data in volumes (emptyDir survives container restarts; PersistentVolumes survive Pod replacement) is kept.",
    lessonId: "volumes",
    unless: /\b(volume|pvc|persistentvolume|statefulset)/i
  },
  {
    id: "crash-means-new-pod",
    pattern: /\bcrash\w*[^.]{0,100}\b(creates? a (brand )?new pod|replaced entirely|is replaced by a new pod|not restarted)/i,
    correction: "A crashing container is restarted in place by the kubelet, inside the same Pod (same name and IP; the RESTARTS count increases; repeated crashes show CrashLoopBackOff). A controller creates a new Pod only when the Pod object is deleted or evicted, or its node is lost.",
    lessonId: "pods"
  },
  {
    id: "rollback-by-delete",
    pattern: /\bdelet\w* (the |a |your )?deployment[^.]{0,80}\broll ?back|\broll ?back[^.]{0,80}\bdelet\w* (the |a |your )?deployment/i,
    correction: "Roll back a Deployment with `kubectl rollout undo deployment/<name>` (optionally `--to-revision=N`). Deleting a Deployment deletes its ReplicaSets and Pods.",
    lessonId: "rollouts-and-deployment-strategies"
  },
  {
    id: "secrets-encrypted",
    pattern: /\bsecrets? (are|is) (automatically |always )?encrypted( at rest)? by default/i,
    correction: "Secret values are only base64-encoded by default. Encryption at rest must be configured for etcd, and access should be restricted with RBAC.",
    lessonId: "configmaps-and-secrets"
  },
  {
    id: "scheduler-starts-containers",
    pattern: /\bscheduler (starts|runs|launches|creates|pulls)\b[^.]{0,30}\b(containers?|images?)/i,
    correction: "The kube-scheduler only chooses a node and binds the Pod to it. The kubelet on that node starts the containers through the container runtime.",
    lessonId: "control-plane-controllers"
  },
  {
    id: "kubectl-run-deployment",
    pattern: /\bkubectl run\b[^.]{0,60}\bcreates? (a |an )?deployment/i,
    correction: "`kubectl run` creates a single Pod. Use `kubectl create deployment` (or a manifest) to create a Deployment.",
    lessonId: "kubectl-and-cluster-administration"
  },
  {
    id: "docker-required",
    pattern: /\b(kubernetes|kubelet) (requires|needs|uses) docker( engine)? (as|for) (its |the )?(container )?runtime/i,
    correction: "Kubernetes uses CRI-compatible runtimes such as containerd or CRI-O. Docker Engine support via dockershim was removed in Kubernetes 1.24. Images built with Docker still work, because they are OCI images.",
    lessonId: "node-components"
  },
  {
    id: "psp-current",
    pattern: /\b(use|enable|configure|create) (a )?PodSecurityPolic(y|ies)\b/i,
    correction: "PodSecurityPolicy was removed in Kubernetes 1.25. Use Pod Security Admission (Pod Security Standards: privileged, baseline, restricted) or a policy engine such as Kyverno or OPA Gatekeeper.",
    lessonId: "pod-security-and-least-privilege"
  }
];
var NEGATION = /\b(not|n't|never|avoid|instead of|rather than|misconception|myth|wrong|incorrect)\b/i;
function sentenceAround(text, index) {
  const start = Math.max(text.lastIndexOf(".", index), text.lastIndexOf("\n", index)) + 1;
  const endDot = text.indexOf(".", index);
  const endNl = text.indexOf("\n", index);
  const end = [endDot, endNl].filter((x) => x >= 0).reduce((a, b) => Math.min(a, b), text.length);
  return text.slice(start, end);
}
function factCheck(text) {
  const notes = [];
  for (const r of RULES) {
    const m = r.pattern.exec(text);
    if (!m) continue;
    const sentence = sentenceAround(text, m.index);
    if (NEGATION.test(sentence) || r.unless?.test(sentence)) continue;
    notes.push({ id: r.id, correction: r.correction, lessonId: r.lessonId });
  }
  return notes;
}

// src/limits.ts
var RateLimiter = class {
  constructor(max, windowMs) {
    this.max = max;
    this.windowMs = windowMs;
  }
  max;
  windowMs;
  hits = /* @__PURE__ */ new Map();
  /** Returns seconds to wait, or 0 if allowed (and records the hit). */
  check(key, now = Date.now()) {
    const list = (this.hits.get(key) ?? []).filter((t) => now - t < this.windowMs);
    if (list.length >= this.max) {
      this.hits.set(key, list);
      return Math.ceil((this.windowMs - (now - list[0])) / 1e3);
    }
    list.push(now);
    this.hits.set(key, list);
    if (this.hits.size > 1e4) this.prune(now);
    return 0;
  }
  prune(now) {
    for (const [k, v] of this.hits) if (!v.some((t) => now - t < this.windowMs)) this.hits.delete(k);
  }
};
var Gate = class {
  constructor(concurrency, maxQueue) {
    this.concurrency = concurrency;
    this.maxQueue = maxQueue;
  }
  concurrency;
  maxQueue;
  active = 0;
  waiters = [];
  get queued() {
    return this.waiters.length;
  }
  /** Resolves with a release function, or null if the queue is full. */
  async acquire(signal) {
    if (this.active < this.concurrency) {
      this.active++;
      return this.releaser();
    }
    if (this.waiters.length >= this.maxQueue) return null;
    await new Promise((resolve2, reject) => {
      const w = () => resolve2();
      this.waiters.push(w);
      signal?.addEventListener("abort", () => {
        this.waiters = this.waiters.filter((x) => x !== w);
        reject(new Error("aborted"));
      });
    });
    this.active++;
    return this.releaser();
  }
  releaser() {
    let done = false;
    return () => {
      if (done) return;
      done = true;
      this.active--;
      this.waiters.shift()?.();
    };
  }
};

// src/providers.ts
var ProviderError = class extends Error {
  constructor(code, message) {
    super(message);
    this.code = code;
  }
  code;
};
var DisabledProvider = class {
  name = "none";
  model = "none";
  async state() {
    return "disabled";
  }
  // eslint-disable-next-line require-yield
  async *stream() {
    throw new ProviderError("unavailable", "The AI tutor is disabled on this deployment.");
  }
};
var OpenAICompatibleProvider = class {
  constructor(o) {
    this.o = o;
    this.name = o.name;
    this.model = o.model;
  }
  o;
  name;
  model;
  month = "";
  used = 0;
  capReached() {
    const m = (/* @__PURE__ */ new Date()).toISOString().slice(0, 7);
    if (m !== this.month) {
      this.month = m;
      this.used = 0;
    }
    return !!this.o.monthlyRequestCap && this.used >= this.o.monthlyRequestCap;
  }
  async state() {
    if (this.capReached()) return "quota-exhausted";
    if (!this.o.healthUrl) return "ready";
    try {
      const r = await fetch(this.o.healthUrl, { signal: AbortSignal.timeout(2e3) });
      if (r.ok) return "ready";
      return r.status === 503 ? "loading" : "unavailable";
    } catch {
      return "unavailable";
    }
  }
  async *stream(p) {
    if (this.capReached()) throw new ProviderError("quota", "Monthly AI request budget for this deployment is used up.");
    this.used++;
    let res;
    try {
      res = await fetch(`${this.o.baseUrl}/chat/completions`, {
        method: "POST",
        signal: p.signal,
        headers: {
          "content-type": "application/json",
          ...this.o.apiKey ? { authorization: `Bearer ${this.o.apiKey}` } : {}
        },
        body: JSON.stringify({
          model: this.model,
          messages: p.messages,
          max_tokens: p.maxTokens,
          temperature: p.temperature,
          stream: true,
          ...this.o.extraBody
        })
      });
    } catch (e) {
      if (p.signal.aborted) throw new ProviderError("timeout", "The model took too long to respond.");
      throw new ProviderError("unavailable", `Model backend unreachable (${e.name}).`);
    }
    if (res.status === 402 || res.status === 429) throw new ProviderError("quota", "The model provider reports that the free quota is exhausted or rate-limited.");
    if (res.status === 503) throw new ProviderError("unavailable", "The model is still loading. Try again in a minute.");
    if (!res.ok || !res.body) throw new ProviderError("upstream", `Model backend returned HTTP ${res.status}.`);
    const reader = res.body.getReader();
    const dec = new TextDecoder();
    let buf = "";
    try {
      for (; ; ) {
        const { value, done } = await reader.read();
        if (done) break;
        buf += dec.decode(value, { stream: true });
        let nl;
        while ((nl = buf.indexOf("\n")) >= 0) {
          const line = buf.slice(0, nl).trim();
          buf = buf.slice(nl + 1);
          if (!line.startsWith("data:")) continue;
          const data = line.slice(5).trim();
          if (data === "[DONE]") return;
          try {
            const j = JSON.parse(data);
            const t = j.choices?.[0]?.delta?.content;
            if (t) yield t;
          } catch {
          }
        }
      }
    } catch (e) {
      if (p.signal.aborted) throw new ProviderError("timeout", "The model took too long to respond.");
      throw e;
    }
  }
};
function providerFromEnv(env = process.env) {
  const kind = env.TUTOR_PROVIDER ?? "llamacpp";
  if (kind === "none") return new DisabledProvider();
  if (kind === "hf-router") {
    const token = env.HF_TOKEN;
    if (!token) return new DisabledProvider();
    return new OpenAICompatibleProvider({
      name: "hf-router",
      baseUrl: "https://router.huggingface.co/v1",
      model: env.HF_ROUTER_MODEL ?? "Qwen/Qwen3-4B-Instruct-2507",
      apiKey: token,
      monthlyRequestCap: Number(env.HF_ROUTER_MONTHLY_REQUEST_CAP ?? 300)
    });
  }
  const base = env.LLAMA_URL ?? "http://127.0.0.1:8081";
  return new OpenAICompatibleProvider({
    name: "llamacpp",
    baseUrl: `${base}/v1`,
    healthUrl: `${base}/health`,
    model: env.TUTOR_MODEL ?? "local",
    extraBody: { chat_template_kwargs: { enable_thinking: false }, cache_prompt: true }
  });
}

// src/server.ts
function configFromEnv(env = process.env) {
  return {
    port: Number(env.PORT ?? 7860),
    staticDir: env.STATIC_DIR,
    allowedOrigins: (env.ALLOWED_ORIGINS ?? "https://mhhamdan.github.io").split(",").map((s) => s.trim()).filter(Boolean),
    provider: providerFromEnv(env),
    rateLimit: { max: Number(env.RATE_LIMIT_MAX ?? 20), windowMs: Number(env.RATE_LIMIT_WINDOW_MS ?? 10 * 6e4) },
    concurrency: Number(env.TUTOR_CONCURRENCY ?? 1),
    maxQueue: Number(env.TUTOR_MAX_QUEUE ?? 4),
    maxTokens: Number(env.TUTOR_MAX_TOKENS ?? 450),
    timeoutMs: Number(env.TUTOR_TIMEOUT_MS ?? 18e4)
  };
}
var MIME = {
  ".html": "text/html; charset=utf-8",
  ".js": "text/javascript; charset=utf-8",
  ".css": "text/css; charset=utf-8",
  ".json": "application/json; charset=utf-8",
  ".svg": "image/svg+xml",
  ".png": "image/png",
  ".ico": "image/x-icon",
  ".webmanifest": "application/manifest+json",
  ".woff2": "font/woff2",
  ".txt": "text/plain; charset=utf-8"
};
var SECURITY_HEADERS = {
  "x-content-type-options": "nosniff",
  "referrer-policy": "strict-origin-when-cross-origin",
  // The Space page on huggingface.co embeds the app in an iframe.
  "content-security-policy": "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; connect-src 'self'; font-src 'self' data:; object-src 'none'; base-uri 'self'; frame-ancestors 'self' https://huggingface.co https://*.hf.space"
};
var MAX_BODY = 32 * 1024;
function clientKey(req) {
  const xff = req.headers["x-forwarded-for"];
  const ip = (Array.isArray(xff) ? xff[0] : xff)?.split(",")[0].trim();
  return ip || req.socket.remoteAddress || "unknown";
}
function json(res, status, body, headers = {}) {
  res.writeHead(status, { "content-type": "application/json; charset=utf-8", "cache-control": "no-store", ...headers });
  res.end(JSON.stringify(body));
}
async function readBody(req) {
  let size = 0;
  const chunks = [];
  for await (const c of req) {
    size += c.length;
    if (size > MAX_BODY) throw new Error("too-large");
    chunks.push(c);
  }
  return Buffer.concat(chunks).toString("utf8");
}
function createApp(cfg2) {
  const limiter = new RateLimiter(cfg2.rateLimit.max, cfg2.rateLimit.windowMs);
  const gate = new Gate(cfg2.concurrency, cfg2.maxQueue);
  const index = contentIndex();
  const staticRoot = cfg2.staticDir ? resolve(cfg2.staticDir) : void 0;
  function cors(req) {
    const origin = req.headers.origin;
    if (!origin) return {};
    const host = req.headers["x-forwarded-host"] ?? req.headers.host;
    try {
      if (new URL(origin).host === host) return {};
    } catch {
      return null;
    }
    if (!cfg2.allowedOrigins.includes(origin)) return null;
    return { "access-control-allow-origin": origin, vary: "Origin", "access-control-allow-headers": "content-type", "access-control-allow-methods": "GET, POST, OPTIONS", "access-control-max-age": "600" };
  }
  async function health(res, h) {
    const state = await cfg2.provider.state();
    json(res, 200, {
      status: "ok",
      tutor: { provider: cfg2.provider.name, model: cfg2.provider.model, state, queued: gate.queued },
      limits: { ...TUTOR_LIMITS, requestsPerWindow: cfg2.rateLimit.max, windowMinutes: cfg2.rateLimit.windowMs / 6e4 },
      corpusDocs: index.size
    }, h);
  }
  async function chat(req, res, h) {
    if (!String(req.headers["content-type"] ?? "").includes("application/json")) return json(res, 415, { error: "bad-request", message: "Use application/json." }, h);
    const wait = limiter.check(clientKey(req));
    if (wait) return json(res, 429, { error: "rate-limited", message: `Tutor request limit reached. Try again in ${wait}s.`, retryAfter: wait }, { ...h, "retry-after": String(wait) });
    let body;
    try {
      body = JSON.parse(await readBody(req));
    } catch (e) {
      return json(res, e.message === "too-large" ? 413 : 400, { error: "bad-request", message: "Invalid or oversized JSON body." }, h);
    }
    const v = validateTutorRequest(body);
    if (!v.ok) return json(res, 400, { error: "bad-request", message: v.error }, h);
    const state = await cfg2.provider.state();
    if (state !== "ready") {
      const code = state === "quota-exhausted" ? "quota" : state === "disabled" ? "disabled" : state === "loading" ? "loading" : "unavailable";
      return json(res, 503, { error: code, message: `AI tutor is ${state.replace("-", " ")}.` }, h);
    }
    const ac = new AbortController();
    const timer = setTimeout(() => ac.abort(), cfg2.timeoutMs);
    res.on("close", () => ac.abort());
    let release;
    try {
      release = await gate.acquire(ac.signal);
    } catch {
      clearTimeout(timer);
      return;
    }
    if (!release) {
      clearTimeout(timer);
      return json(res, 503, { error: "busy", message: "The tutor is busy answering other learners. Try again shortly." }, h);
    }
    const hits = retrieve(index, v.value);
    const { messages, sources } = buildChat(v.value, hits);
    res.writeHead(200, { ...h, "content-type": "text/event-stream; charset=utf-8", "cache-control": "no-store", "x-accel-buffering": "no", connection: "keep-alive" });
    const send = (event, data) => res.write(`event: ${event}
data: ${JSON.stringify(data)}

`);
    send("meta", { sources, model: cfg2.provider.model, provider: cfg2.provider.name });
    const started = Date.now();
    let out = "";
    let sentLen = 0;
    try {
      for await (const tok of cfg2.provider.stream({ messages, maxTokens: cfg2.maxTokens, temperature: 0.3, signal: ac.signal })) {
        out += tok;
        const clean = cleanModelOutput(out);
        if (out.includes("<think>") && !out.includes("</think>")) continue;
        if (clean.length > sentLen) {
          send("token", { t: clean.slice(sentLen) });
          sentLen = clean.length;
        }
      }
      const notes = factCheck(cleanModelOutput(out));
      if (notes.length) send("notes", { notes });
      send("done", { ms: Date.now() - started });
      log(`tutor ok mode=${v.value.mode} turns=${v.value.messages.length} chars=${sentLen} notes=${notes.length} ms=${Date.now() - started}`);
    } catch (e) {
      const pe = e instanceof ProviderError ? e : new ProviderError("upstream", "Unexpected model error.");
      send("error", { code: pe.code, message: pe.message });
      log(`tutor err code=${pe.code} ms=${Date.now() - started}`);
    } finally {
      clearTimeout(timer);
      release();
      res.end();
    }
  }
  function serveStatic(req, res) {
    if (!staticRoot) return json(res, 404, { error: "not-found" });
    const url = new URL(req.url ?? "/", "http://x");
    let rel = decodeURIComponent(url.pathname);
    if (rel.endsWith("/")) rel += "index.html";
    const file = normalize(join(staticRoot, rel));
    if (!file.startsWith(staticRoot)) return json(res, 403, { error: "forbidden" });
    const target = existsSync(file) && statSync(file).isFile() ? file : join(staticRoot, "index.html");
    const isAsset = target.includes(`${staticRoot}/assets/`);
    res.writeHead(200, {
      ...SECURITY_HEADERS,
      "content-type": MIME[extname(target)] ?? "application/octet-stream",
      "cache-control": isAsset ? "public, max-age=31536000, immutable" : "no-cache"
    });
    if (req.method === "HEAD") return res.end();
    createReadStream(target).pipe(res);
  }
  return createServer(async (req, res) => {
    const path = (req.url ?? "/").split("?")[0];
    try {
      if (path.startsWith("/api/")) {
        const h = cors(req);
        if (h === null) return json(res, 403, { error: "forbidden-origin" });
        if (req.method === "OPTIONS") {
          res.writeHead(204, h);
          return res.end();
        }
        if (path === "/api/health" && req.method === "GET") return await health(res, h);
        if (path === "/api/tutor/chat" && req.method === "POST") return await chat(req, res, h);
        return json(res, 404, { error: "not-found" }, h);
      }
      if (req.method !== "GET" && req.method !== "HEAD") return json(res, 405, { error: "method-not-allowed" });
      return serveStatic(req, res);
    } catch (e) {
      log(`error ${e.message}`);
      if (!res.headersSent) json(res, 500, { error: "internal" });
      else res.end();
    }
  });
}
function log(msg) {
  if (process.env.NODE_ENV !== "test") console.log(`${(/* @__PURE__ */ new Date()).toISOString()} ${msg}`);
}

// src/main.ts
var cfg = configFromEnv();
createApp(cfg).listen(cfg.port, "0.0.0.0", () => {
  console.log(
    `KCNA API listening on :${cfg.port} provider=${cfg.provider.name} model=${cfg.provider.model} static=${cfg.staticDir ?? "(none)"} origins=${cfg.allowedOrigins.join(",")}`
  );
});