Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion internal/verda-cli/cmd/serverless/CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ This rule applies equally to Claude, Codex, Cursor, or a human editing the packa
- `verda container` → `/container-deployments` (continuous endpoints, supports spot)
- `verda batchjob` → `/job-deployments` (one-shot jobs, deadline-based, **no spot**)
- There is **no** `verda serverless` parent command — the two trees were promoted to root for shorter invocations. They still share this Go package because they share wizard step factories, validators, and the API cache.
- Verbs (both trees): `create`, `update`, `list` (alias `ls`), `describe` (aliases `get`, `show`), `delete` (aliases `rm`, `del`), `pause`, `resume`, `purge-queue`. Container also has `restart`, `scale` and `replicas`.
- Verbs (both trees): `create`, `update`, `list` (alias `ls`), `describe` (aliases `get`, `show`), `delete` (aliases `rm`, `del`), `pause`, `resume`, `purge-queue`. Container also has `restart`, `scale`, `replicas`, and the `env`, `secret`, `file-secret` and `registry-creds` subtrees.
- Files:
- `container.go`, `batchjob.go` — Top-level command builders. `NewCmdContainer` and `NewCmdBatchjob` are exported and called directly from `cmd/cmd.go`. Both are GA: registered unconditionally, visible, no `cmdutil.TagAnnotation`. `visibility_test.go` and `cmd/cmd_test.go` guard this (the former `VERDA_BATCHJOB_ENABLED` gate and `(beta)` tag are gone).
- `container_create.go` — `containerCreateOptions`, flags, `request()`, validate(), wizard entry point.
Expand All @@ -36,6 +36,7 @@ This rule applies equally to Claude, Codex, Cursor, or a human editing the packa
- `container_scale.go` — `container scale`: flags → `scaling.Change`, confirm, PATCH, optional `--wait`.
- `container_scale_wizard.go` — `buildScaleFlow`: setting multi-select, then one step per setting.
- `container_replicas.go` — `container replicas`: `GetDeploymentReplicas` + table / structured output.
- `container_env.go` — `container env list|set|unset`: resolves the deployment's inner container (`containerNameOf`) and reads the grouped env GET (`fetchEnvVars`). See "Env endpoints key on the inner container" below.
- `container_delete.go` — `DeleteDeployment(timeoutMs)` + destructive confirm.
- `container_actions.go` — Data-driven action factory `newContainerActionCmd` (pause/resume/restart/purge-queue).
- `batchjob_create.go` — `batchjobCreateOptions` (simpler: no spot, deadline required).
Expand Down Expand Up @@ -147,6 +148,7 @@ Describe cards (`renderContainerDeploymentCard`, `renderJobDeploymentCard`) prin
- **Scaling preset + legacy rows on describe.** When a deployment was created via the web UI with a custom queue-load (say 10), our CLI shows `custom (10)` rather than a named preset. Don't try to round-trip it back to a named preset — exact threshold wins.
- **`ContainerDeployment.Status` is NOT in the `GetDeployments` list response.** The list endpoint returns `ContainerDeployment` without status. We call `GetDeploymentStatus(name)` per-row in `describe`, but NOT in `list` (would N+1). If the web UI grows a bulk status endpoint, wire it in.
- **Env-var name validation:** `^[A-Z_][A-Z0-9_]*$`. Lowercase or leading-digit names are rejected client-side in both `parseEnvFlag` and `promptEnvVar`. This is stricter than POSIX (which allows lowercase) but matches Verda's conventions.
- **Env endpoints key on the inner container, not the deployment.** `POST/PATCH/DELETE /container-deployments/{name}/environment-variables` take `container_name` = `Containers[0].Name`, which the API assigns as `<deployment>-0` on create (we never send a container name). Passing the deployment name returns `not_found` ("A container with the name 'x' does not exist in the deployment 'x'"). All three env commands resolve it via `containerNameOf` (one extra GET), so `list` reads the same container `set` and `unset` write to. The GET response is also grouped per container (`[{container_name, env[]}]`); SDK `GetEnvironmentVariables` decodes it flat and yields one blank entry per container, so `fetchEnvVars` reads the grouped shape via `client.NewRequest`/`Do` and `envVarsOf` picks the container's group. Drop `fetchEnvVars` once the SDK returns groups. Multi-container deployments: the CLI always targets `Containers[0]`; `env list` warns when the deployment has more than one container (never key the choice on env-GET group order: the groups can come back reordered or miss a container with no vars). Both found live on prod 2026-11-18.
- **Secret mount path must be absolute.** `parseSecretMountFlag` and `promptSecretMount` both check `strings.HasPrefix(path, "/")`. No trailing-slash normalization is applied.
- **Update commands use fetch-then-merge-then-PATCH.** GET current state, overlay only `cmd.Flags().Changed()` flags, send one PATCH. nil/omitted fields in the request mean "don't change". Container update needs two GETs (deployment + scaling) because `ContainerDeployment` doesn't include scaling; job update needs one (scaling is inline).
- **Env merge on update is type-partitioned.** `--env` replaces ALL plain vars and carries all secret vars unchanged; `--env-secret` replaces ALL secret vars and carries all plain vars unchanged. Both flags set → full replacement. Neither → no env field in PATCH.
Expand Down
14 changes: 14 additions & 0 deletions internal/verda-cli/cmd/serverless/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -205,6 +205,20 @@ Env names must match `^[A-Z_][A-Z0-9_]*$` (uppercase alphanumerics + underscore,

The describe card shows env names only. `-o json|yaml` and `--agent` print plain values verbatim, as the API returns them. Put sensitive values in secrets (`--env-secret`): output shows only the secret name.

### Managing env on a running deployment

`verda container env` changes variables in place, without a redeploy. Every subcommand takes the **deployment name**; the CLI resolves the container inside it.

```bash
verda container env list my-endpoint
verda container env set my-endpoint --env HF_HOME=/data/.huggingface --env-secret API_KEY=my-secret
verda container env unset --deployment my-endpoint HF_HOME MODEL_NAME
```

`set` adds variables that do not exist yet and updates the ones that do. `unset` asks for confirmation (`--yes` to skip; required in agent mode). Without a name on a terminal, `list` and `set` open a deployment picker; `unset` uses `--deployment`.

`verda container env list|set|unset` operate on the deployment's first container (the CLI creates exactly one, named `<deployment>-0` by the API). On a deployment with several containers, `env list` shows the first and prints a warning.

## See also

- `CLAUDE.md` in this directory — domain knowledge + gotchas for future Claude sessions
Expand Down
105 changes: 97 additions & 8 deletions internal/verda-cli/cmd/serverless/container_env.go
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,8 @@ package serverless
import (
"context"
"fmt"
"net/http"
"net/url"
"strings"
"text/tabwriter"

Expand All @@ -28,6 +30,76 @@ import (

const envValueMasked = "***"

// containerNameOf: the env endpoints key `container_name` on the container
// inside the deployment (the API names it "<deployment>-0"), not on the
// deployment; sending the deployment name returns not_found. Multi-container
// deployments always target Containers[0]; count is the deployment's size.
func containerNameOf(ctx context.Context, client *verda.Client, deployment string) (name string, count int, err error) {
d, err := client.ContainerDeployments.GetDeploymentByName(ctx, deployment)
if err != nil {
return "", 0, err
}
if len(d.Containers) == 0 {
return "", 0, fmt.Errorf("deployment %q has no containers", deployment)
}
return d.Containers[0].Name, len(d.Containers), nil
}

// envVarGroup is one element of the GET environment-variables response,
// which is grouped per container (GetDeploymentEnvVariablesPublicApiResponseDto).
type envVarGroup struct {
ContainerName string `json:"container_name"`
Env []verda.ContainerEnvVar `json:"env"`
}

// fetchEnvVars reads the grouped response directly. SDK v1.9.0's
// GetEnvironmentVariables decodes it as a flat []ContainerEnvVar, which
// yields one blank entry per container; drop this once the SDK returns groups.
func fetchEnvVars(ctx context.Context, client *verda.Client, deployment string) ([]envVarGroup, error) {
req, err := client.NewRequest(ctx, http.MethodGet, "/container-deployments/"+url.PathEscape(deployment)+"/environment-variables", nil)
if err != nil {
return nil, err
}
var groups []envVarGroup
if _, err := client.Do(req, &groups); err != nil {
return nil, err
}
return groups, nil
}

// envTarget: the container every env command keys on and its current
// variables. list, set and unset all resolve it the same way so they never
// disagree on which container a multi-container deployment means.
type envTarget struct {
Container string
Containers int
Vars []verda.ContainerEnvVar
}

func loadEnvTarget(ctx context.Context, client *verda.Client, deployment string) (*envTarget, error) {
cn, count, err := containerNameOf(ctx, client, deployment)
if err != nil {
return nil, err
}
groups, err := fetchEnvVars(ctx, client, deployment)
if err != nil {
return nil, err
}
return &envTarget{Container: cn, Containers: count, Vars: envVarsOf(groups, cn)}, nil
}

// envVarsOf: the variables of container. The deployment GET and the env GET
// are separate reads, so the container may be missing from the groups (no
// vars yet, or a lagging read): that is empty, not an error.
func envVarsOf(groups []envVarGroup, container string) []verda.ContainerEnvVar {
for i := range groups {
if groups[i].ContainerName == container {
return groups[i].Env
}
}
return nil
}

func newCmdContainerEnv(f cmdutil.Factory, ioStreams cmdutil.IOStreams) *cobra.Command {
cmd := &cobra.Command{
Use: "env",
Expand All @@ -53,7 +125,11 @@ func newCmdEnvList(f cmdutil.Factory, ioStreams cmdutil.IOStreams) *cobra.Comman
Use: "list <deployment>",
Aliases: []string{"ls"},
Short: "List environment variables",
Args: cobra.MaximumNArgs(1),
Example: cmdutil.Examples(`
# List variables on a deployment (secret-backed values are masked)
verda container env list my-endpoint
`),
Args: cobra.MaximumNArgs(1),
RunE: func(cmd *cobra.Command, args []string) error {
name, err := resolveContainerName(cmd, f, ioStreams, args)
if err != nil {
Expand All @@ -70,12 +146,16 @@ func newCmdEnvList(f cmdutil.Factory, ioStreams cmdutil.IOStreams) *cobra.Comman
ctx, cancel := context.WithTimeout(cmd.Context(), f.Options().Timeout)
defer cancel()

vars, err := cmdutil.WithSpinner(ctx, f.Status(), "Fetching environment variables...", func(ctx context.Context) ([]verda.ContainerEnvVar, error) {
return client.ContainerDeployments.GetEnvironmentVariables(ctx, name)
target, err := cmdutil.WithSpinner(ctx, f.Status(), "Fetching environment variables...", func(ctx context.Context) (*envTarget, error) {
return loadEnvTarget(ctx, client, name)
})
if err != nil {
return err
}
if target.Containers > 1 {
_, _ = fmt.Fprintf(ioStreams.ErrOut, "Warning: deployment has %d containers; showing %q\n", target.Containers, target.Container)
}
vars := target.Vars

if wrote, werr := cmdutil.WriteStructured(ioStreams.Out, f.OutputFormat(), vars); wrote {
return werr
Expand Down Expand Up @@ -156,12 +236,13 @@ func newCmdEnvSet(f cmdutil.Factory, ioStreams cmdutil.IOStreams) *cobra.Command
ctx, cancel := context.WithTimeout(cmd.Context(), f.Options().Timeout)
defer cancel()

current, err := cmdutil.WithSpinner(ctx, f.Status(), "Fetching current variables...", func(ctx context.Context) ([]verda.ContainerEnvVar, error) {
return client.ContainerDeployments.GetEnvironmentVariables(ctx, name)
target, err := cmdutil.WithSpinner(ctx, f.Status(), "Fetching current variables...", func(ctx context.Context) (*envTarget, error) {
return loadEnvTarget(ctx, client, name)
})
if err != nil {
return err
}
containerName, current := target.Container, target.Vars

existing := make(map[string]bool, len(current))
for _, v := range current {
Expand All @@ -178,7 +259,7 @@ func newCmdEnvSet(f cmdutil.Factory, ioStreams cmdutil.IOStreams) *cobra.Command
}

if len(toAdd) > 0 {
req := &verda.ContainerEnvVarsRequest{ContainerName: name, Env: toAdd}
req := &verda.ContainerEnvVarsRequest{ContainerName: containerName, Env: toAdd}
cmdutil.DebugJSON(ioStreams.ErrOut, f.Debug(), "Add env vars:", req)
if err := cmdutil.RunWithSpinner(ctx, f.Status(), "Adding environment variables...", func(ctx context.Context) error {
return client.ContainerDeployments.AddEnvironmentVariables(ctx, name, req)
Expand All @@ -187,7 +268,7 @@ func newCmdEnvSet(f cmdutil.Factory, ioStreams cmdutil.IOStreams) *cobra.Command
}
}
if len(toUpdate) > 0 {
req := &verda.ContainerEnvVarsRequest{ContainerName: name, Env: toUpdate}
req := &verda.ContainerEnvVarsRequest{ContainerName: containerName, Env: toUpdate}
cmdutil.DebugJSON(ioStreams.ErrOut, f.Debug(), "Update env vars:", req)
if err := cmdutil.RunWithSpinner(ctx, f.Status(), "Updating environment variables...", func(ctx context.Context) error {
return client.ContainerDeployments.UpdateEnvironmentVariables(ctx, name, req)
Expand Down Expand Up @@ -266,8 +347,16 @@ func newCmdEnvUnset(f cmdutil.Factory, ioStreams cmdutil.IOStreams) *cobra.Comma
ctx, cancel := context.WithTimeout(cmd.Context(), f.Options().Timeout)
defer cancel()

containerName, err := cmdutil.WithSpinner(ctx, f.Status(), "Loading deployment...", func(ctx context.Context) (string, error) {
cn, _, err := containerNameOf(ctx, client, deployment)
return cn, err
})
if err != nil {
return err
}

req := &verda.DeleteContainerEnvVarsRequest{
ContainerName: deployment,
ContainerName: containerName,
Env: args,
}
cmdutil.DebugJSON(ioStreams.ErrOut, f.Debug(), "Delete env vars:", req)
Expand Down
Loading