devlift-cli 0.1.0__py3-none-any.whl

devlift_cli/ops/eks.py

@@ -0,0 +1,877 @@
+"""`devlift eks create`: register a service and park its first configuration.
+
+Mirrors the web's "Create & Add" followed by the Settings tab's Save, which is
+also what the MCP's create_service_and_save_draft does:
+
+    1. POST /services/create-service              the service (name, type, product, group)
+    2. POST /service-configs                      a baseline row for ONE placement: cluster
+                                                  context, ALB selection, namespace — none of
+                                                  the user's settings, on purpose (see below)
+    3. POST /transaction/service-settings/{code}  the settings as a DRAFT queue row
+
+Nothing is submitted, approved or deployed here; those are the review lane's
+verbs. The settings deliberately do NOT go into step 2: the draft in step 3 is
+diffed against the live row, and a live row that already held the values would
+diff to nothing and queue no review.
+
+Values: the user supplies what no template can know (repository, branches,
+language, version); the rest starts from the platform's per-language template
+(the same one the MCP applies) and `--set key=value` overrides any field.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+from devlift_cli.api import catalog, infra_list, services as services_api
+from devlift_cli.context import Invocation
+from devlift_cli.errors import EXIT_CONFLICT, EXIT_NOT_FOUND, CliError, InputError
+from devlift_cli.ops.placement import resolve_placement
+from devlift_cli.render import output
+from devlift_cli.render.output import kv_table, rows_table
+from devlift_cli.resolve import allowlist
+from devlift_cli.resolve.names import Resolver
+
+SERVICE_TYPES = {"api": "API", "worker": "BACKGROUND_SERVICE", "background": "BACKGROUND_SERVICE"}
+
+# ── the settings a service has (form field id → where it lives in `config`) ──
+# The dashboard's Settings form, the chatbot form and the language template all
+# name these the same way; only the autoscaling trio is nested in the stored
+# config (config.hpa.enabled / min_replicas / max_replicas).
+_STRING_FIELDS = (
+    "port", "health", "service_path", "build_path", "dockerfile_path", "go_config_path",
+    "xms", "xmx", "alb_schema", "compute", "auth_mode",
+    "cpu_requested", "cpu_limit", "memory_requested", "memory_limit",
+    "replica_count", "min_replicas", "max_replicas",
+)
+_BOOL_FIELDS = (
+    "generate_dockerfile", "go_use_aws_secrets", "hpa_enabled",
+    "create_ecr", "create_secrets", "create_ssm", "create_argo",
+)
+_LIST_FIELDS = ("other_paths", "custom_iam_policies")
+_PAIR_FIELDS = ("build_args",)
+SETTABLE_FIELDS = _STRING_FIELDS + _BOOL_FIELDS + _LIST_FIELDS + _PAIR_FIELDS
+
+_CHOICES = {
+    "alb_schema": ("internal", "internet-facing"),
+    "compute": ("on-demand", "spot"),
+    "auth_mode": ("pod_identity", "irsa"),
+}
+_IAM_POLICIES = ("s3", "sqs", "dynamodb", "ses")
+_JAVA = ("Java Gradle", "Java Maven")
+
+# When a setting applies at all — the conditional rules of the platform's EKS
+# form (eks_service_form.json), which the web's Settings tab mirrors: JVM heap
+# only for Java, Go config only for Go, build path for compiled languages,
+# Dockerfile path only when the Dockerfile is not generated, ALB schema and
+# the two HTTP paths only for an API (a worker has no load balancer), min/max
+# replicas only with autoscaling, a fixed replica count only without it.
+# `required` = must have a value once it applies.
+_APPLIES = {
+    "xms":                {"language": _JAVA},
+    "xmx":                {"language": _JAVA},
+    "go_config_path":     {"language": ("Go",)},
+    "go_use_aws_secrets": {"language": ("Go",)},
+    "build_path":         {"language": _JAVA + ("Go",)},
+    "dockerfile_path":    {"generate_dockerfile": False},
+    "alb_schema":         {"service_type": "API", "required": True},
+    "health":             {"service_type": "API", "required": True},
+    "service_path":       {"service_type": "API", "required": True},
+    "min_replicas":       {"hpa_enabled": True, "required": True},
+    "max_replicas":       {"hpa_enabled": True, "required": True},
+    "replica_count":      {"hpa_enabled": False, "required": True},
+}
+_ALWAYS_REQUIRED = ("port", "cpu_requested", "cpu_limit", "memory_requested", "memory_limit", "compute", "generate_dockerfile", "hpa_enabled")
+
+
+def applies(key: str, *, language: str, service_type: str, settings: dict) -> tuple[bool, str]:
+    """(does this setting apply, why not)."""
+    rule = _APPLIES.get(key)
+    if not rule:
+        return True, ""
+    if "language" in rule and language not in rule["language"]:
+        return False, f"only applies to {' / '.join(rule['language'])} services, and this one is {language}"
+    if "service_type" in rule and service_type != rule["service_type"]:
+        return False, "only applies to an API service; a worker has no load balancer or HTTP path"
+    if "generate_dockerfile" in rule and bool(settings.get("generate_dockerfile")) != rule["generate_dockerfile"]:
+        return False, "only applies when the Dockerfile is not generated (generate_dockerfile=false)"
+    if "hpa_enabled" in rule and bool(settings.get("hpa_enabled")) != rule["hpa_enabled"]:
+        return False, ("only applies with autoscaling on (hpa_enabled=true)" if rule["hpa_enabled"]
+                       else "does not apply with autoscaling on; the HPA decides the count")
+    return True, ""
+
+
+def _number(key: str, value, lo: float, hi: float) -> float:
+    try:
+        n = float(value)
+    except (TypeError, ValueError):
+        raise InputError(f"{LABELS.get(key, key)} must be a number, got '{value}'.")
+    if not lo <= n <= hi:
+        raise InputError(f"{LABELS.get(key, key)} must be between {lo:g} and {hi:g}.")
+    return n
+
+
+def validate_settings(settings: dict) -> None:
+    """The form's own validation rules, applied before anything is written."""
+    s = settings
+    if "port" in s and not re.match(r"^[0-9]{1,5}$", str(s["port"])):
+        raise InputError("Port must be a number of up to five digits, e.g. 8080.")
+    cpu_req = _number("cpu_requested", s["cpu_requested"], 0, 4) if s.get("cpu_requested") else None
+    cpu_lim = _number("cpu_limit", s["cpu_limit"], 0, 4) if s.get("cpu_limit") else None
+    if cpu_req is not None and cpu_lim is not None and cpu_lim < cpu_req:
+        raise InputError("CPU limit cannot be less than CPU request.")
+    mem_req = _number("memory_requested", s["memory_requested"], 0, 8) if s.get("memory_requested") else None
+    mem_lim = _number("memory_limit", s["memory_limit"], 0, 8) if s.get("memory_limit") else None
+    if mem_req is not None and mem_lim is not None and mem_lim < mem_req:
+        raise InputError("Memory limit cannot be less than memory request.")
+    for key in ("min_replicas", "max_replicas", "replica_count"):
+        if s.get(key):
+            _number(key, s[key], 1, 100)
+    if s.get("min_replicas") and s.get("max_replicas") and float(s["max_replicas"]) <= float(s["min_replicas"]):
+        raise InputError("Max replicas must be greater than min replicas.")
+    for key in ("health", "service_path"):
+        if s.get(key) and not str(s[key]).startswith("/"):
+            raise InputError(f"{LABELS[key]} must start with '/'.")
+    for key in ("xms", "xmx"):
+        if s.get(key) and not re.match(r"^[0-9]+[mMgG]?$", str(s[key])):
+            raise InputError(f"{LABELS[key]} must be a heap size like 512m or 1g.")
+    bad = [p for p in s.get("custom_iam_policies") or [] if p not in _IAM_POLICIES]
+    if bad:
+        raise InputError(f"Unknown IAM policy {', '.join(bad)}.", hint="One of: " + ", ".join(_IAM_POLICIES))
+    for arg in s.get("build_args") or []:
+        if not re.match(r"^[A-Z][A-Z0-9_]*$", str(arg.get("name", ""))):
+            raise InputError(f"Build arg name '{arg.get('name')}' must be uppercase, e.g. APP_ENV.")
+_HPA_KEYS = {"hpa_enabled": "enabled", "min_replicas": "min_replicas", "max_replicas": "max_replicas"}
+# Template keys that are not settings at all (the manifests carry them, nobody
+# is asked for them) — same exclusion the MCP applies.
+_NOT_SETTINGS = {"namespace", "ebs_enabled", "ebs.volume", "ebs.size", "ebs.type",
+                 "secrets_enabled", "secret_keys", "ci_provider"}
+_TEMPLATE_ALIASES = {"hpa.enabled": "hpa_enabled", "hpa.min_replicas": "min_replicas", "hpa.max_replicas": "max_replicas"}
+
+LABELS = {
+    "port": "Port", "health": "Health check path", "service_path": "Service path",
+    "build_path": "Build path", "dockerfile_path": "Dockerfile path", "generate_dockerfile": "Generate Dockerfile",
+    "go_config_path": "Go config path", "go_use_aws_secrets": "Go: AWS Secrets Manager",
+    "xms": "JVM initial heap (-Xms)", "xmx": "JVM max heap (-Xmx)", "build_args": "Build args",
+    "cpu_requested": "CPU request (cores)", "cpu_limit": "CPU limit (cores)",
+    "memory_requested": "Memory request (GiB)", "memory_limit": "Memory limit (GiB)",
+    "hpa_enabled": "Autoscaling", "min_replicas": "Min replicas", "max_replicas": "Max replicas",
+    "replica_count": "Replicas", "alb_schema": "ALB schema", "compute": "Compute",
+    "custom_iam_policies": "IAM policies", "create_ecr": "Create ECR repo", "create_secrets": "Create secret",
+    "create_ssm": "Create SSM parameters", "create_argo": "Create Argo CD app", "auth_mode": "IAM auth mode",
+    "other_paths": "Extra trigger paths",
+}
+
+
+def normalise_service_name(name: str) -> str:
+    """The name the platform deploys under: lowercase, hyphens, `-service` suffix.
+    Same rule as the manifest generator, so paths derived here match."""
+    n = name.strip().lower().replace(" ", "-").replace("_", "-")
+    return n if n.endswith("-service") else f"{n}-service"
+
+
+def validate_service_name(raw: str) -> str | None:
+    name = raw.strip()
+    if not name:
+        return "required."
+    if len(name) > 255:
+        return "must be 255 characters or fewer."
+    if not re.match(r"^[a-z][a-z0-9-]{1,254}$", name):
+        return "use lowercase letters, numbers and hyphens, starting with a letter, e.g. user-service."
+    return None
+
+
+# ── --set parsing ────────────────────────────────────────────────────────────
+
+def _split_pairs(pairs: list[str]) -> list[str]:
+    """Several settings in one `--set`, separated by `;` or a newline.
+
+    Comma cannot be that separator: it already separates the values INSIDE
+    one setting (`custom_iam_policies=s3,sqs`), so `a=1,b=2` would have to
+    guess which it meant. A semicolon never appears in these values, so
+    `--set "cpu_limit=0.5;port=9090"` is unambiguous, and repeating `--set`
+    keeps working exactly as before.
+    """
+    out: list[str] = []
+    for raw in pairs:
+        out += [part.strip() for part in raw.replace("\n", ";").split(";") if part.strip()]
+    return out
+
+
+def parse_set(pairs: list[str]) -> dict:
+    """`--set key=value` flags into typed values, validated against the field list."""
+    out: dict = {}
+    for raw in _split_pairs(pairs):
+        if "=" not in raw:
+            raise InputError(f"--set expects key=value, got '{raw}'.")
+        key, value = raw.split("=", 1)
+        key, value = key.strip(), value.strip()
+        if key not in SETTABLE_FIELDS:
+            raise InputError(f"Unknown setting '{key}'.", hint="Settable: " + ", ".join(SETTABLE_FIELDS))
+        if key in _BOOL_FIELDS:
+            if value.lower() not in ("true", "false", "yes", "no"):
+                raise InputError(f"--set {key} must be true or false.")
+            out[key] = value.lower() in ("true", "yes")
+        elif key in _LIST_FIELDS:
+            out[key] = [v.strip() for v in value.split(",") if v.strip()]
+        elif key in _PAIR_FIELDS:
+            items = []
+            for part in (p.strip() for p in value.split(",") if p.strip()):
+                if "=" not in part:
+                    raise InputError(f"--set {key} takes NAME=VALUE pairs separated by commas, got '{part}'.")
+                n, v = part.split("=", 1)
+                items.append({"name": n.strip(), "value": v.strip()})
+            out[key] = items
+        else:
+            if key in _CHOICES and value not in _CHOICES[key]:
+                raise InputError(f"--set {key} must be one of {', '.join(_CHOICES[key])}.")
+            out[key] = value
+    return out
+
+
+# ── template → settings ──────────────────────────────────────────────────────
+
+def settings_from_template(block: dict | None, service_name: str) -> dict:
+    """Flat settings (form field ids) from a language template block.
+
+    `null` = no reliable default, leave unset so it gets asked. Empty string or
+    list = deliberately unset (the MCP's `template_skips`). Placeholders take
+    the normalised service name."""
+    settings: dict = {}
+    deployed = normalise_service_name(service_name)
+    for key, value in (block or {}).items():
+        if key in _NOT_SETTINGS or value is None:
+            continue
+        key = _TEMPLATE_ALIASES.get(key, key)
+        if value == "":
+            continue
+        if isinstance(value, bool):
+            settings[key] = value
+        elif isinstance(value, list):
+            settings[key] = value
+        elif isinstance(value, (int, float)):
+            settings[key] = str(value)
+        else:
+            text = str(value).replace("{service_name}", deployed).replace("{service_path}", f"/{deployed}")
+            settings[key] = text
+    return settings
+
+
+def _missing(settings: dict, *, language: str, service_type: str) -> list[str]:
+    need = list(_ALWAYS_REQUIRED) + [
+        k for k, rule in _APPLIES.items()
+        if rule.get("required") and applies(k, language=language, service_type=service_type, settings=settings)[0]
+    ]
+    return [k for k in need if settings.get(k) in (None, "")]
+
+
+def _to_config(settings: dict, *, service_name: str, service_type: str, language_ref_code: str,
+               repository: str, branches: list[str]) -> dict:
+    """The `config` block of the draft, in the shape the Settings tab sends."""
+    config: dict = {
+        "repository": repository,
+        "branches": branches,
+        "language_ref_code": language_ref_code,
+        "namespace": normalise_service_name(service_name),
+        "alb_selection": "no_alb" if service_type == "BACKGROUND_SERVICE" else "existing_alb",
+    }
+    hpa: dict = {"enabled": bool(settings.get("hpa_enabled"))}
+    for key, value in settings.items():
+        if key in _HPA_KEYS:
+            if key != "hpa_enabled" and hpa["enabled"]:
+                hpa[_HPA_KEYS[key]] = str(value)
+            continue
+        config[key] = value
+    config["hpa"] = hpa
+    if hpa["enabled"]:
+        config.pop("replica_count", None)
+    for key in _LIST_FIELDS + _PAIR_FIELDS:
+        config.setdefault(key, [])
+    return config
+
+
+# ── cluster / language lookups ───────────────────────────────────────────────
+
+def _cluster_context(locator: dict) -> dict:
+    """The cluster fields the web copies from the canvas node onto the baseline
+    row. Locators mix snake_case and camelCase; read both. vpc_id is left out
+    on purpose — the web's create dialog never carries it."""
+    def pick(*keys):
+        for k in keys:
+            v = locator.get(k)
+            if v not in (None, "", [], {}):
+                return v
+        return None
+    context = {
+        "cluster_name": pick("cluster_name", "clusterName"),
+        "cluster_arn": pick("cluster_arn", "clusterArn"),
+        "region": pick("cloudRegion", "region", "cloud_region"),
+        "cloud_region_id": pick("cloudRegionId", "cloud_region_id"),
+        "subnet_ids": pick("subnetIds", "subnet_ids"),
+    }
+    return {k: v for k, v in context.items() if v is not None}
+
+
+def resolve_cluster(inv: Invocation, *, application_code: str, environment: str, geo_loc_mst_code: str, wanted: str | None) -> dict:
+    """The registered EKS cluster this service runs on. Product-scoped clusters
+    win; tenant-level ones (no product) are the fallback — the same rule the
+    dashboard picker and the MCP apply. The list route already hides
+    unregistered clusters."""
+    rows = infra_list.list_infrastructures(
+        inv.api, infra_type=services_api.EKS_INFRA_TYPE, environment=environment, geo_loc_mst_code=geo_loc_mst_code,
+    )
+    scoped = [r for r in rows if r.get("applications_mst_code") == application_code]
+    shared = [r for r in rows if not r.get("applications_mst_code")]
+    candidates = scoped or shared
+    if wanted:
+        w = wanted.strip().lower()
+        hit = [r for r in rows if w in (str(r.get("code", "")).lower(), str(r.get("name", "")).lower(), str(r.get("cluster_name", "")).lower())]
+        if not hit:
+            names = ", ".join(f"{r.get('cluster_name') or r.get('name')} ({r['code']})" for r in rows) or "none"
+            raise CliError(f"Cluster '{wanted}' is not available for {environment} / {geo_loc_mst_code}. Available: {names}.", EXIT_NOT_FOUND)
+        return hit[0]
+    if not candidates:
+        raise CliError(
+            f"No registered EKS cluster for this product in {environment} / {geo_loc_mst_code}.",
+            EXIT_NOT_FOUND, hint="Ask the DevOps team to register one, or pick another environment/region.",
+        )
+    if len(candidates) == 1:
+        return candidates[0]
+    labels = [f"{r.get('cluster_name') or r.get('name')} ({r['code']})" for r in candidates]
+    choice = inv.ask("Cluster", choices=labels, flag="--cluster")
+    return candidates[labels.index(choice)]
+
+
+def resolve_language(inv: Invocation, language: str | None, version: str | None) -> tuple[str, str, str]:
+    """(language label, version, language_ref_code) from the grouped list."""
+    groups = services_api.language_versions_grouped(inv.api)
+    labels = [g["language_name"] for g in groups]
+    if language is None:
+        language = inv.ask("Language", choices=labels, flag="--language")
+    want = language.strip().lower()
+    group = next((g for g in groups if g["language_name"].lower() == want), None)
+    if group is None:
+        prefix = [g for g in groups if g["language_name"].lower().startswith(want)]
+        if len(prefix) == 1:
+            group = prefix[0]
+        else:
+            raise InputError(f"Unknown language '{language}'.", hint="One of: " + ", ".join(labels))
+    versions = group.get("versions") or []
+    if not versions:
+        raise CliError(f"No versions are configured for {group['language_name']}.", EXIT_NOT_FOUND)
+    if version is None:
+        version = versions[0]["version"] if len(versions) == 1 else inv.ask(
+            f"{group['language_name']} version", choices=[v["version"] for v in versions], flag="--version",
+        )
+    v = version.strip().lower()
+    row = next((x for x in versions if v in (str(x.get("version", "")).lower(), str(x.get("code", "")).lower())), None)
+    if row is None:
+        raise InputError(f"{group['language_name']} has no version '{version}'.", hint="One of: " + ", ".join(x["version"] for x in versions))
+    return group["language_name"], row["version"], row["code"]
+
+
+def resolve_repository(inv: Invocation, wanted: str | None) -> tuple[str, str]:
+    """(owner/name, default branch) from the repositories the GitHub App can
+    see. A bare name matches when it is unique; anything else is asked or
+    refused with the list to run."""
+    repos = catalog.list_repositories(inv.api)
+    if not repos:
+        raise CliError("The DevLift GitHub App sees no repositories for this tenant.", EXIT_NOT_FOUND,
+                       hint="Install or link the GitHub App from the dashboard first.")
+    names = [r["full_name"] for r in repos]
+    if wanted is None:
+        wanted = inv.ask("Repository", choices=names if len(names) <= 12 else None, flag="--repository")
+    w = wanted.strip().lower()
+    hit = [r for r in repos if r["full_name"].lower() == w] or [r for r in repos if str(r.get("name", "")).lower() == w]
+    if len(hit) != 1:
+        raise CliError(
+            f"Repository '{wanted}' is not one the DevLift GitHub App can see." if not hit
+            else f"Repository '{wanted}' matches several: " + ", ".join(r["full_name"] for r in hit) + ".",
+            EXIT_NOT_FOUND if not hit else 3,
+            hint="`devlift repositories list` shows the accepted owner/name values.",
+        )
+    return hit[0]["full_name"], hit[0].get("default_branch") or "main"
+
+
+def resolve_branches(inv: Invocation, repository: str, wanted: list[str], default_branch: str) -> list[str]:
+    """The branches that trigger a build, each checked to exist on the
+    repository. The branch is the user's decision: asked on a terminal (the
+    repository's default branch offered as the default answer), required
+    under --no-input."""
+    existing = [b["name"] for b in catalog.list_branches(inv.api, repository)]
+    if not wanted:
+        if not inv.interactive:
+            raise InputError(
+                "Branch is required.",
+                hint=f"Pass --branch (repeatable). `devlift repositories branches {repository}` lists them; the default branch is {default_branch}.",
+            )
+        if existing and len(existing) <= 12:
+            output.err_console.print(f"[bold]Branches on {repository}[/bold]: " + ", ".join(existing))
+        raw = inv.ask("Branches that trigger a build (comma-separated)", default=default_branch, flag="--branch")
+        wanted = [b.strip() for b in raw.split(",") if b.strip()]
+    unknown = [b for b in wanted if existing and b not in existing]
+    if unknown:
+        shown = ", ".join(existing[:8]) + (" …" if len(existing) > 8 else "")
+        raise InputError(
+            f"Branch {', '.join(repr(b) for b in unknown)} does not exist on {repository}.",
+            hint=f"`devlift repositories branches {repository}` lists them (for example: {shown}).",
+        )
+    return wanted
+
+
+# ── the sequence ─────────────────────────────────────────────────────────────
+
+@dataclass
+class EksCreateResult:
+    service_name: str
+    service_code: str
+    service_config_code: str
+    environment: str
+    region: str
+    cluster: str
+    queue_code: str | None
+    queue_status: str | None
+    config: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        return {
+            "service": self.service_name,
+            "service_code": self.service_code,
+            "service_config_code": self.service_config_code,
+            "environment": self.environment,
+            "region": self.region,
+            "cluster": self.cluster,
+            "queue_code": self.queue_code,
+            "queue_status": self.queue_status,
+            "config": self.config,
+        }
+
+
+def create_eks_service(
+    inv: Invocation,
+    res: Resolver,
+    *,
+    name: str | None,
+    app: str | None,
+    env: str | None,
+    region: str | None,
+    resource_group: str | None,
+    service_type: str | None,
+    repository: str | None,
+    branches: list[str],
+    language: str | None,
+    version: str | None,
+    cluster: str | None,
+    overrides: dict,
+    public: bool = False,
+) -> EksCreateResult:
+    # 1. what it is, where it lives
+    if name is None:
+        name = inv.ask("Service name", flag="--name")
+    problem = validate_service_name(name)
+    if problem:
+        raise InputError(f"Service name {problem}")
+    name = name.strip()
+
+    if service_type is None:
+        service_type = inv.ask("Service type", choices=["api", "worker"], default="api", flag="--type")
+    stype = SERVICE_TYPES.get(service_type.strip().lower())
+    if not stype:
+        raise InputError("--type must be api or worker.")
+
+    placement = resolve_placement(inv, res, app, env, region, service=allowlist.SERVICE_EKS)
+
+    groups = [g for g in res.resource_groups() if g.get("applications_mst_code") == placement.application_code]
+    if resource_group is None:
+        if len(groups) == 1:
+            group = groups[0]
+        elif groups:
+            pick = inv.ask("Resource group", choices=[g["name"] for g in groups], flag="--resource-group")
+            group = next(g for g in groups if g["name"] == pick)
+        else:
+            raise CliError(f"'{placement.application_name}' has no resource groups; create one in the dashboard first.", EXIT_NOT_FOUND)
+    else:
+        group = res.resource_group(resource_group, placement.application_code)
+
+    existing = [s for s in catalog.list_services(inv.api, application_code=placement.application_code)
+                if str(s.get("service_name", "")).strip().lower() == name.lower()]
+    if existing:
+        raise CliError(
+            f"A service named '{name}' already exists in {placement.application_name} ({existing[0].get('service_code')}).",
+            EXIT_CONFLICT, hint=f"`devlift services describe {name}`. Adding a configuration for another environment is not available yet.",
+        )
+
+    chosen = resolve_cluster(inv, application_code=placement.application_code, environment=placement.environment,
+                             geo_loc_mst_code=placement.geo_loc_mst_code, wanted=cluster)
+    cluster_locator = chosen.get("locator") or {}
+    cluster_label = cluster_locator.get("cluster_name") or chosen.get("cluster_name") or chosen.get("name") or chosen["code"]
+
+    # 2. what only the user knows — checked against the same lists the web's
+    #    dropdowns show (`devlift repositories list` / `repositories branches`)
+    repository, default_branch = resolve_repository(inv, repository)
+    branches = resolve_branches(inv, repository, branches, default_branch)
+    lang_label, lang_version, language_ref_code = resolve_language(inv, language, version)
+
+    # 3. the rest: template, then overrides
+    templates = services_api.eks_language_templates(inv.api)
+    block = next((b for k, b in templates.items() if k.lower() == lang_label.lower()), None)
+    if block is None:
+        output.warn(f"No template for {lang_label}; every setting must come from --set.")
+    settings = settings_from_template(block, name)
+    settings.update(overrides)
+    # A setting the user named that cannot apply to THIS service is a mistake
+    # to report, not to drop silently: `--set xms=1g` on a Go service.
+    for key in overrides:
+        ok, why = applies(key, language=lang_label, service_type=stype, settings=settings)
+        if not ok:
+            raise InputError(f"{LABELS.get(key, key)} ({key}) {why}.")
+    # Template values that do not apply here just fall away — the template is
+    # per language, but the service type and the autoscaling choice are not.
+    settings = {k: v for k, v in settings.items()
+                if applies(k, language=lang_label, service_type=stype, settings=settings)[0]}
+    for key in _missing(settings, language=lang_label, service_type=stype):
+        if key in ("port", "health", "service_path") and inv.interactive:
+            settings[key] = inv.ask(LABELS.get(key, key), flag=f"--set {key}=…")
+        else:
+            raise InputError(f"{LABELS.get(key, key)} is not set and the {lang_label} template has no default for it.",
+                             hint=f"Pass --set {key}=<value>.")
+    validate_settings(settings)
+
+    config = _to_config(settings, service_name=name, service_type=stype, language_ref_code=language_ref_code,
+                        repository=repository, branches=branches)
+
+    # 4. show, confirm
+    if inv.show_summary:
+        output.err_console.print(kv_table([
+            ("Service", name),
+            ("Type", "API" if stype == "API" else "Worker (no load balancer)"),
+            ("Application", placement.application_name),
+            ("Resource group", group["name"]),
+            ("Environment", placement.environment),
+            ("Region", placement.region_name),
+            ("Cluster", cluster_label),
+            ("Repository", repository),
+            ("Branches", ", ".join(branches)),
+            ("Language", f"{lang_label} {lang_version}"),
+        ], title="Create service"))
+        shown = [(LABELS.get(k, k), _show(v), "you" if k in overrides else lang_label + " template")
+                 for k, v in settings.items()]
+        output.err_console.print(rows_table(["Setting", "Value", "From"], shown, title="Configuration"))
+    inv.confirm(f"Create '{name}' and save this configuration as a draft for review?")
+
+    # 5. the three calls
+    created = services_api.create_service(
+        inv.api, application_code=placement.application_code, resource_group_code=group["code"],
+        service_name=name, service_type=stype, is_public_facing=public,
+    )
+    service_code = created.get("service_code")
+    if not service_code:
+        raise CliError("DevLift created the service but returned no code.")
+    output.info(f"Created service {name} ({service_code}).")
+
+    baseline = {
+        "alb_selection": config["alb_selection"],
+        "namespace": config["namespace"],
+        **_cluster_context(cluster_locator),
+    }
+    cfg = services_api.create_service_config(
+        inv.api, services_mst_code=service_code, environment=placement.environment,
+        geo_loc_mst_code=placement.geo_loc_mst_code, infrastructure_mst_code=chosen["code"], config=baseline,
+    )
+    service_config_code = cfg.get("code")
+    if not service_config_code:
+        raise CliError("DevLift created the configuration row but returned no code.")
+    output.info(f"Configuration row {service_config_code} created for {placement.environment} / {placement.region_name}.")
+
+    snapshot = {
+        "config": config,
+        "language_name": lang_label,
+        "language_version": lang_version,
+        "services_mst_code": service_code,
+        "service_name": name,
+        "service_type": stype,
+        "geo_loc_mst_code": placement.geo_loc_mst_code,
+        "environment": placement.environment,
+        "infrastructuretype_ref_code": services_api.EKS_INFRA_TYPE,
+        "infrastructure_mst_code": chosen["code"],
+        "product_name": placement.application_name,
+        "applications_mst_code": placement.application_code,
+    }
+    ingress = (cfg.get("config") or {}).get("ingress_group_order")
+    if ingress is not None:
+        snapshot["ingress_group_order"] = ingress
+    draft = services_api.save_settings_draft(inv.api, service_config_code=service_config_code, config_snapshot=snapshot)
+    approval = draft.get("approval") or {}
+    queue_code, queue_status = approval.get("code"), approval.get("status")
+    output.info(f"Configuration saved as draft {queue_code or ''} ({queue_status or 'draft'}). Nothing is deployed until it is submitted, approved and deployed.")
+
+    return EksCreateResult(
+        service_name=name, service_code=service_code, service_config_code=service_config_code,
+        environment=placement.environment, region=placement.region_name, cluster=cluster_label,
+        queue_code=queue_code, queue_status=queue_status, config=config,
+    )
+
+
+# ── editing an existing service ──────────────────────────────────────────────
+#
+# The Settings tab's model, and the MCP's edit path: the form is hydrated from
+# the LIVE row, then the caller's OPEN DRAFT (if any) is laid over it, the user
+# changes fields, and Save parks the full result as a settings draft — reusing
+# the open draft's queue code so a second edit updates the same request rather
+# than tripping the one-live-request lane. A request under review (submitted
+# or approved, whoever's) blocks editing: the values are being decided on.
+
+def settings_from_config(config: dict) -> dict:
+    """A stored `config` block → the flat settings keys the form and --set use."""
+    cfg = config or {}
+    out: dict = {}
+    for key in _STRING_FIELDS:
+        if key in ("min_replicas", "max_replicas"):
+            continue
+        v = cfg.get(key)
+        if v not in (None, "", [], {}):
+            out[key] = str(v) if not isinstance(v, str) else v
+    for key in _BOOL_FIELDS:
+        if key == "hpa_enabled":
+            continue
+        v = cfg.get(key)
+        if v is not None:
+            out[key] = bool(v) if not isinstance(v, str) else v.lower() == "true"
+    for key in _LIST_FIELDS + _PAIR_FIELDS:
+        v = cfg.get(key)
+        if isinstance(v, list):
+            out[key] = v
+    hpa = cfg.get("hpa") if isinstance(cfg.get("hpa"), dict) else None
+    if hpa is not None:
+        out["hpa_enabled"] = bool(hpa.get("enabled"))
+        if out["hpa_enabled"]:
+            for k in ("min_replicas", "max_replicas"):
+                if hpa.get(k) not in (None, ""):
+                    out[k] = str(hpa[k])
+    elif "replica_count" in out:
+        out["hpa_enabled"] = False
+    return out
+
+
+def language_label(name: str | None, code: str | None) -> str | None:
+    """The label the grouped list uses: 'Java Maven' / 'Java Gradle' by code,
+    otherwise the first word of the name ('Python 3.12' → 'Python')."""
+    if code and code.upper().startswith("JAVA-MAVEN"):
+        return "Java Maven"
+    if code and code.upper().startswith("JAVA"):
+        return "Java Gradle"
+    return (name or "").split()[0] if name else None
+
+
+@dataclass
+class Effective:
+    """A service configuration as the Settings tab would show it."""
+    target: object                       # ops.kong.GatewayTarget
+    service: dict                        # the services list row
+    live: dict                           # GET /service-configs/by-code/{code}
+    config: dict                         # live config with the open draft laid over it
+    draft: dict | None                   # the caller's open settings draft, if any
+    pending_keys: set                    # keys where the draft differs from live
+    language_ref_code: str | None
+    language_label: str | None
+    language_version: str | None
+    settings: dict                       # flat form keys
+
+
+def load_effective(inv: Invocation, res: Resolver, service: str, env: str | None, region: str | None, *, for_edit: bool) -> Effective:
+    from devlift_cli.api import approvals as approvals_api
+    from devlift_cli.ops.kong import resolve_target
+
+    target = resolve_target(inv, res, service, env, region)
+    service_row = res.service(service)
+    live = services_api.get_service_config(inv.api, target.config_code)
+    live_config = dict(live.get("config") or {})
+
+    rows = [r for r in approvals_api.list_requests(inv.api, resource_code=target.config_code) if r.get("case_ref_code") == "update_service"]
+    under_review = [r for r in rows if r.get("status") in ("submit", "approved")]
+    if for_edit and under_review:
+        r = under_review[0]
+        raise CliError(
+            f"{target.service_name} has a {r['status']} settings request ({r['code']}, by "
+            f"{r.get('requested_by_name') or r.get('requested_by')}) — its values are being decided on and cannot be edited now.",
+            EXIT_CONFLICT, hint="Wait for it to deploy, or withdraw / revoke it first.",
+        )
+    draft = next((r for r in rows if r.get("status") == "draft" and (r.get("you") or {}).get("mine")), None)
+    shown_draft = draft or next((r for r in under_review), None)
+    overlay = ((shown_draft or {}).get("config_snapshot") or {}).get("config") or {}
+    config = {**live_config, **overlay}
+    pending = {k for k, v in overlay.items() if live_config.get(k) != v}
+
+    language_ref_code = config.get("language_ref_code") or live.get("language_ref_code")
+    label = version = None
+    if language_ref_code:
+        try:
+            lv = services_api.language_version(inv.api, language_ref_code)
+            label, version = language_label(lv.get("name"), lv.get("code")), lv.get("version")
+        except CliError:
+            label = language_label(None, language_ref_code)
+    return Effective(target, service_row, live, config, draft if for_edit else shown_draft, pending,
+                     language_ref_code, label, version, settings_from_config(config))
+
+
+@dataclass
+class EditResult:
+    service_name: str
+    config_code: str
+    environment: str | None
+    changed: bool
+    changes: list[tuple[str, object, object]]
+    queue_code: str | None = None
+    queue_status: str | None = None
+
+    def to_dict(self) -> dict:
+        return {
+            "service": self.service_name, "service_config_code": self.config_code, "environment": self.environment,
+            "changed": self.changed, "changes": {f: {"from": a, "to": b} for f, a, b in self.changes},
+            "queue_code": self.queue_code, "queue_status": self.queue_status,
+        }
+
+
+def edit_eks_service(
+    inv: Invocation, res: Resolver, service: str, *, env: str | None, region: str | None,
+    overrides: dict, repository: str | None, branches: list[str], language: str | None, version: str | None,
+) -> EditResult:
+    eff = load_effective(inv, res, service, env, region, for_edit=True)
+    target = eff.target
+    stype = (eff.service.get("service_type") or "API").upper()
+    before = dict(eff.settings)
+
+    # what only the user knows, when they change it
+    repo_before = eff.config.get("repository")
+    branches_before = list(eff.config.get("branches") or eff.config.get("selected_branches") or [])
+    lang_code, lang_label, lang_version = eff.language_ref_code, eff.language_label, eff.language_version
+    repo_after, default_branch = (resolve_repository(inv, repository) if repository else (repo_before, None))
+    if branches or (repository and repo_after != repo_before):
+        if not repo_after:
+            raise InputError("This configuration has no repository yet; pass --repository too.")
+        branches_after = resolve_branches(inv, repo_after, branches or branches_before, default_branch or "main")
+    else:
+        branches_after = branches_before
+    if language or version:
+        lang_label, lang_version, lang_code = resolve_language(inv, language or lang_label, version)
+    if not lang_label:
+        raise InputError(f"{target.service_name} has no language set yet.", hint="Pass --language and --version.")
+
+    settings = dict(before)
+    settings.update(overrides)
+    for key in overrides:
+        ok, why = applies(key, language=lang_label, service_type=stype, settings=settings)
+        if not ok:
+            raise InputError(f"{LABELS.get(key, key)} ({key}) {why}.")
+    settings = {k: v for k, v in settings.items() if applies(k, language=lang_label, service_type=stype, settings=settings)[0]}
+    missing = _missing(settings, language=lang_label, service_type=stype)
+    if missing:
+        raise InputError(
+            "Not set: " + ", ".join(LABELS.get(k, k) for k in missing) + ".",
+            hint="Pass them with --set key=value: " + " ".join(f"--set {k}=…" for k in missing),
+        )
+    validate_settings(settings)
+
+    changes: list[tuple[str, object, object]] = []
+    for key in sorted(set(before) | set(settings)):
+        if _comparable(before.get(key)) != _comparable(settings.get(key)):
+            changes.append((key, before.get(key), settings.get(key)))
+    if repo_after != repo_before:
+        changes.append(("repository", repo_before, repo_after))
+    if branches_after != branches_before:
+        changes.append(("branches", branches_before, branches_after))
+    if lang_code != eff.language_ref_code:
+        changes.append(("language", f"{eff.language_label or '–'} {eff.language_version or ''}".strip(), f"{lang_label} {lang_version}"))
+    if not changes:
+        output.info(f"{target.service_name} already has those values. Nothing to change.")
+        return EditResult(target.service_name, target.config_code, target.environment, False, [])
+
+    if inv.show_summary:
+        output.err_console.print(rows_table(
+            ["Setting", "Current", "New"],
+            [(LABELS.get(f, f), _show(a), _show(b)) for f, a, b in changes],
+            title=f"Edit {target.service_name} ({target.environment} / {target.region_name})"
+                  + (f" — updates your draft {eff.draft['code']}" if eff.draft else ""),
+        ))
+    inv.confirm("Save these changes as a draft for review?")
+
+    config = _to_config(settings, service_name=target.service_name, service_type=stype, language_ref_code=lang_code or "",
+                        repository=repo_after or "", branches=branches_after)
+    live = eff.live
+    snapshot = {
+        "config": config,
+        "language_name": lang_label,
+        "language_version": lang_version,
+        "services_mst_code": live.get("services_mst_code") or eff.service.get("service_code"),
+        "service_name": target.service_name,
+        "service_type": stype,
+        "geo_loc_mst_code": live.get("geo_loc_mst_code"),
+        "environment": live.get("environment"),
+        "infrastructuretype_ref_code": live.get("infrastructuretype_ref_code") or services_api.EKS_INFRA_TYPE,
+        "infrastructure_mst_code": live.get("infrastructure_mst_code"),
+        "product_name": eff.service.get("application_name"),
+        "applications_mst_code": eff.service.get("application_code"),
+    }
+    ingress = (live.get("config") or {}).get("ingress_group_order")
+    if ingress is not None:
+        snapshot["ingress_group_order"] = ingress
+    draft = services_api.save_settings_draft(
+        inv.api, service_config_code=target.config_code, config_snapshot=snapshot,
+        queue_code=(eff.draft or {}).get("code"),
+    )
+    approval = draft.get("approval") or {}
+    output.info(f"Saved as draft {approval.get('code') or ''} ({approval.get('status') or 'draft'}). "
+                f"Submit it with `devlift request submit {target.service_name}`.")
+    return EditResult(target.service_name, target.config_code, target.environment, True, changes,
+                      queue_code=approval.get("code"), queue_status=approval.get("status"))
+
+
+def _comparable(value):
+    if isinstance(value, list):
+        return [str(v) for v in value]
+    if isinstance(value, bool) or value is None:
+        return value
+    return str(value)
+
+
+def describe_settings() -> list[dict]:
+    """One row per --set key: what it is and when it applies (for `eks settings`)."""
+    rows = []
+    for key in SETTABLE_FIELDS:
+        rule = _APPLIES.get(key, {})
+        if "language" in rule:
+            when = "language " + " / ".join(rule["language"])
+        elif "service_type" in rule:
+            when = "API services only"
+        elif "generate_dockerfile" in rule:
+            when = "generate_dockerfile=false"
+        elif "hpa_enabled" in rule:
+            when = "hpa_enabled=true" if rule["hpa_enabled"] else "hpa_enabled=false"
+        else:
+            when = "always"
+        if key in _BOOL_FIELDS:
+            kind = "true | false"
+        elif key in _CHOICES:
+            kind = " | ".join(_CHOICES[key])
+        elif key == "custom_iam_policies":
+            kind = "comma-separated: " + ", ".join(_IAM_POLICIES)
+        elif key in _LIST_FIELDS:
+            kind = "comma-separated list"
+        elif key in _PAIR_FIELDS:
+            kind = "NAME=VALUE pairs, comma-separated"
+        else:
+            kind = "text"
+        rows.append({"key": key, "label": LABELS.get(key, key), "values": kind, "applies": when,
+                     "required": key in _ALWAYS_REQUIRED or bool(rule.get("required"))})
+    return rows
+
+
+def _show(value) -> str:
+    if isinstance(value, bool):
+        return "yes" if value else "no"
+    if isinstance(value, list):
+        if value and isinstance(value[0], dict):
+            return ", ".join(f"{d.get('name')}={d.get('value')}" for d in value)
+        return ", ".join(str(v) for v in value) if value else "–"
+    return "–" if value in (None, "") else str(value)