Skip to content

feat: add snapshot parameter to auto-create ENV #1026

Description

@mbevc1

Summary

Add a flag to kosli snapshot <type> that creates the target environment on the
fly if it does not already exist, instead of failing. This lets users report a
snapshot in a single command rather than requiring a prior kosli create environment.
Optional flags allow the auto-created environment's description and scaling
behavior to be configured inline.

Motivation

Today, reporting a snapshot to an environment that hasn't been created yet fails,
because kosli snapshot assumes the environment already exists. This forces a
two-step setup:

kosli create environment prod --type docker --description "..."
kosli snapshot docker prod --api-token <token> --org <org>

This is extra friction during onboarding - workflows that report snapshots must special-case the "first run" where the environment doesn't exist yet, or run a separate create step guarded by error handling. There is also a scaling scanario where we want to define mapping and start reporting.

Proposed solution

Add a boolean flag to the kosli snapshot command group, plus optional
pass-through flags for environment configuration:

kosli snapshot docker prod \
  --auto-environment \
  --environment-description "Production docker host" \
  --include-scaling \
  --api-token <token> \
  --org <org>

The flag is --auto-environment (short -a), with --auto-env accepted as an
alias.

Behavior:

  • If the environment named prod does not exist, create it before reporting the
    snapshot.
  • Infer --type from the snapshot subcommand (snapshot dockerdocker,
    snapshot k8sk8s, etc.), so the type never has to be restated.
  • If the environment already exists, --auto-environment is a no-op and the
    snapshot is reported as normal (idempotent).

Optional flags (only take effect when an environment is actually created):

  • --environment-description <string> — description for the new environment.
    Defaults to something like "Auto-created by kosli snapshot" if omitted.
  • --include-scaling / --exclude-scaling — control whether scaling events
    (changes in the number of running instances) produce new snapshots, mirroring
    the existing flags on kosli create environment. If neither is passed, the
    environment inherits the platform default (scaling events excluded).

Edge cases / considerations

  • Optional flags without --auto-environment — if the user passes
    --environment-description or the scaling flags but the environment already
    exists (or --auto-environment isn't set), decide between: silently
    ignoring them, warning, or erroring. Recommend a warning so a stale
    description flag doesn't fail an otherwise-valid snapshot.
  • Logical environments cannot receive snapshots, so auto-create should only
    ever create a physical environment of the subcommand's type. A snapshot
    targeting an existing logical env should still error clearly.
  • Type mismatch — if the environment already exists with a different type
    than the subcommand, fail with a clear message rather than silently reporting.
  • Conflicting scaling flags — passing both --include-scaling and
    --exclude-scaling should error, consistent with kosli create environment.
  • Short flag -a — confirm -a isn't already bound on any kosli snapshot
    subcommand before reserving it globally across the group.

Acceptance criteria

  • kosli snapshot <type> <name> --auto-environment (or -a) creates
    <name> with the inferred type when it doesn't exist, then reports the
    snapshot.
  • --auto-env works as an alias for --auto-environment.
  • The flag is idempotent when the environment already exists.
  • Type is inferred from the subcommand; no separate --type required.
  • --environment-description sets the description on the auto-created env;
    a sensible default is used when omitted.
  • --include-scaling / --exclude-scaling set scaling behavior on the
    auto-created env and error when used together.
  • Optional flags are ignored-with-warning when no environment is created.
  • Clear error on type mismatch or when targeting a logical environment.
  • Flag added consistently across all kosli snapshot <type> subcommands.
  • Docs updated for kosli snapshot and the getting-started/CI tutorials.

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions