docker-stack 2.3.0__py3-none-any.whl → 2.3.2__py3-none-any.whl

docker_stack/cli.py

@@ -8,7 +8,7 @@ import shutil
 import sys
 import textwrap
 from pathlib import Path
-from typing import Dict, List, Optional, Tuple
+from typing import Dict, List, Optional, Set, Tuple
 import os
 import yaml
 import json
@@ -703,6 +703,143 @@ def load_env_file(env_file: str, base_env: Optional[Dict[str, str]] = None, max_
     return _resolve_env_entries(entries, env_file, base_env=base_env, max_cycles=max_cycles)
 
 
+
+
+_ENV_REF_PATTERN = re.compile(r"\$\{([^}:\s]+)(?::-(.*?))?\}|\$([a-zA-Z_][a-zA-Z0-9_]*)")
+_ESCAPED_DOLLAR = "$_ESCAPED_DOLLAR_"
+
+
+def _escape_dollars(text: str) -> str:
+    """Marks text as a literal payload for the manager, which collapses `$$`."""
+    return text.replace("$", "$$")
+
+
+def _substitute_selected_vars(text: str, names: Set[str], replacements: Dict[str, str]) -> str:
+    """Expands only `names`, leaving every other `${VAR}` for the manager."""
+    if not names:
+        return text
+    guarded = text.replace("$$", _ESCAPED_DOLLAR)
+
+    def replace(match: "re.Match[str]") -> str:
+        var = match.group(1) if match.group(1) is not None else match.group(3)
+        if var not in names:
+            return match.group(0)
+        value = os.environ.get(var)
+        if value in (None, "") and match.group(2) is not None:
+            value = match.group(2)
+        if value in (None, ""):
+            return match.group(0)
+        for old, new in replacements.items():
+            value = value.replace(old, new)
+        return value
+
+    return _ENV_REF_PATTERN.sub(replace, guarded).replace(_ESCAPED_DOLLAR, "$$")
+
+
+def _substitute_selected_in_yaml_tree(value, names: Set[str], replacements: Dict[str, str]):
+    if isinstance(value, str):
+        return _substitute_selected_vars(value, names, replacements)
+    if isinstance(value, dict):
+        return {
+            _substitute_selected_in_yaml_tree(key, names, replacements): _substitute_selected_in_yaml_tree(item, names, replacements)
+            for key, item in value.items()
+        }
+    if isinstance(value, list):
+        return [_substitute_selected_in_yaml_tree(item, names, replacements) for item in value]
+    return value
+
+
+def _mark_inline_secret_content_literal(compose_data) -> None:
+    """Protects inlined secret payloads from the manager's interpolation.
+
+    `x-content` is a payload, not a template: the file it came from was already
+    rendered locally when it was declared as `x-template-file`, and a `file:` or
+    `environment:` secret is verbatim by definition. Without this a `$` inside a
+    secret is read as a variable reference and the secret is silently corrupted
+    or the deploy fails on a variable the payload never meant to name.
+    """
+    if not isinstance(compose_data, dict):
+        return
+    secrets = compose_data.get("secrets")
+    if not isinstance(secrets, dict):
+        return
+    for details in secrets.values():
+        if isinstance(details, dict) and isinstance(details.get("x-content"), str):
+            details["x-content"] = _escape_dollars(details["x-content"])
+
+
+def _render_manager_compose(compose_data, secret_env_vars: Set[str], replacements: Dict[str, str]) -> str:
+    """Renders the compose a manager-backed deploy sends.
+
+    The manager owns interpolation: it receives the authored compose and the
+    `.env` holding the values, and it substitutes in the parsed document. So
+    variables are left standing here rather than rendered twice, which is what
+    the `$` doubling in `replacements` exists to undo. Only the variables the
+    manager cannot see are resolved locally - a secret sourced from the
+    environment is deliberately kept out of `.env` so its value is not stored
+    with the stack.
+
+    References are still checked here so a missing variable is reported against
+    the authored file, with its line and surrounding context, instead of coming
+    back as a deploy failure.
+    """
+    _mark_inline_secret_content_literal(compose_data)
+    missing: List[str] = []
+    _substitute_in_yaml_tree(compose_data, replacements, missing)
+    if missing:
+        _report_missing_variables(compose_data, replacements, missing)
+    return yaml.dump(_substitute_selected_in_yaml_tree(compose_data, secret_env_vars, replacements), sort_keys=False)
+
+
+def _substitute_in_yaml_tree(value, replacements: Dict[str, str], missing: List[str]):
+    """Expands `${VAR}` inside the scalars of a parsed compose document.
+
+    Substituting in the serialized text instead would let a variable's value
+    change the structure of the document. `KEY: ${JSON}` holding `{"a":"b"}`
+    reparses as a nested mapping, which the manager rejects as a non-scalar
+    environment value, and a value containing `: ` makes the document fail to
+    parse at all. Walking the tree keeps every substituted value a scalar,
+    whatever characters it contains.
+    """
+    if isinstance(value, str):
+        try:
+            return envsubst(value, replacements=replacements, on_error="throw")
+        except SubstitutionError as error:
+            missing.extend(result.variable_name for result in error.results if result.has_error)
+            return value
+    if isinstance(value, dict):
+        return {
+            _substitute_in_yaml_tree(key, replacements, missing): _substitute_in_yaml_tree(item, replacements, missing)
+            for key, item in value.items()
+        }
+    if isinstance(value, list):
+        return [_substitute_in_yaml_tree(item, replacements, missing) for item in value]
+    return value
+
+
+def _render_compose_substitutions(compose_data, replacements: Dict[str, str]) -> str:
+    missing: List[str] = []
+    substituted = _substitute_in_yaml_tree(compose_data, replacements, missing)
+    if missing:
+        _report_missing_variables(compose_data, replacements, missing)
+    return yaml.dump(substituted, sort_keys=False)
+
+
+def _report_missing_variables(compose_data, replacements: Dict[str, str], missing: List[str]) -> None:
+    """Reports unresolved variables against the whole document.
+
+    Substitution happens scalar by scalar, which has no line numbers to report.
+    Re-running over the serialized document restores the line and context in the
+    error, and exits the same way it always has.
+    """
+    document = yaml.dump(compose_data, sort_keys=False)
+    envsubst(document, replacements=replacements)
+    raise SubstitutionError(
+        [LineCheckResult(line_no=1, line_content="", variable_name=name, start_index=0) for name in missing],
+        document,
+    )
+
+
 class Docker:
     def __init__(self, registries: List[str] = []):
         self.stack = DockerStack(self)
@@ -791,7 +928,27 @@ class DockerStack:
     def _relative_source_name(path: Path, base_dir: Path) -> str:
         return os.path.relpath(path, base_dir).replace(os.sep, "/")
 
-    def _build_env_xfile(self, sources: List[str], excluded_names: set) -> Optional[Dict[str, str]]:
+    @staticmethod
+    def _config_environment_vars(compose_data: dict) -> set:
+        """Variables named by `configs.<name>.environment`.
+
+        These are not `${VAR}` references, so scanning the compose text does not
+        find them, yet the manager resolves them from the stack `.env` like any
+        other variable. Secrets are deliberately absent: their value is inlined
+        locally so it is never stored alongside the stack.
+        """
+        config_env_vars = set()
+        configs = compose_data.get("configs", {})
+        if not isinstance(configs, dict):
+            return config_env_vars
+        for details in configs.values():
+            if isinstance(details, dict) and "environment" in details:
+                env_name = str(details["environment"]).strip()
+                if env_name:
+                    config_env_vars.add(env_name)
+        return config_env_vars
+
+    def _build_env_xfile(self, sources: List[str], excluded_names: set, extra_names: Optional[Set[str]] = None) -> Optional[Dict[str, str]]:
         seen = set()
         lines = []
         for source in sources:
@@ -805,6 +962,14 @@ class DockerStack:
                     continue
                 seen.add(name)
                 lines.append(f"{name}={value}")
+        for name in sorted(extra_names or ()):
+            if name in seen or name in excluded_names:
+                continue
+            value = os.environ.get(name)
+            if value in (None, ""):
+                continue
+            seen.add(name)
+            lines.append(f"{name}={value}")
         if not lines:
             return None
         content = ("\n".join(lines) + "\n").encode("utf-8")
@@ -912,12 +1077,19 @@ class DockerStack:
 
         # Define the replacements for '$' to '$$' for env variables in compose files
         replacements_map = {"$": "$$"}
-        clean_content = envsubst(yaml.dump(compose_data, sort_keys=False), replacements=replacements_map)
+        if manager_deploy:
+            clean_content = _render_manager_compose(compose_data, secret_env_vars, replacements_map)
+        else:
+            clean_content = _render_compose_substitutions(compose_data, replacements_map)
         enriched_data = yaml.safe_load(clean_content) or {}
         x_files = [
             {"path": "compose.yml", "content": self._b64_content(template_bytes)},
         ]
-        env_xfile = self._build_env_xfile(env_sources, secret_env_vars)
+        env_xfile = self._build_env_xfile(
+            env_sources,
+            secret_env_vars,
+            extra_names=self._config_environment_vars(compose_data) if manager_deploy else None,
+        )
         if env_xfile:
             x_files.append(env_xfile)
         x_files.extend(source_x_files)
@@ -2099,14 +2271,14 @@ def _run(args: List[str] = None):
 
     checkout_parser = subparsers.add_parser("checkout", help="Deploy specific version of the stack")
     checkout_parser.add_argument("stack_name", help="Name of the stack")
-    checkout_parser.add_argument("version", help="Stack version to cat")
+    checkout_parser.add_argument("version", help="Stack version to deploy")
     _add_namespace_argument(checkout_parser)
 
     # version_parser = subparsers.add_parser("version",help="Deploy specific version of the stack")
     # version_parser.add_argument("stack_name", help="Name of the stack")
     # version_parser.add_argument("version","versions", help="Stack version to cat")
 
-    version_parser = subparsers.add_parser("version", aliases=["versions"], help="Deploy specific version of the stack")
+    version_parser = subparsers.add_parser("version", aliases=["versions"], help="List recorded versions of the stack")
     version_parser.add_argument("stack_name", help="Name of the stack")
     _add_namespace_argument(version_parser)
 

docker_stack/helpers.py

@@ -1,4 +1,4 @@
-import random
+import secrets as _secrets
 import string
 import sys
 from typing import Callable, Dict, List, Optional, Union
@@ -23,13 +23,17 @@ def generate_secret(
 
     Returns:
         A randomly generated secret string.
+
+    Note:
+        Uses the ``secrets`` module rather than ``random``, since these values
+        are used as passwords, API keys and tokens.
     """
     if length is None:
-        length = random.randint(12, 20)
+        length = 12 + _secrets.randbelow(9)  # 12..20 inclusive
 
     # Always start with a letter (uppercase or lowercase)
     first_char_pool = string.ascii_lowercase + string.ascii_uppercase
-    first_char = random.choice(first_char_pool)
+    first_char = _secrets.choice(first_char_pool)
 
     # Prepare the character pool for the rest of the secret
     characters = string.ascii_lowercase
@@ -47,7 +51,7 @@ def generate_secret(
         raise ValueError("No character types selected for secret generation.")
 
     # Generate the rest of the string
-    secret = [first_char] + [random.choice(characters) for _ in range(length - 1)]
+    secret = [first_char] + [_secrets.choice(characters) for _ in range(length - 1)]
 
     return "".join(secret)
 

docker_stack-2.3.2.dist-info/METADATA

@@ -0,0 +1,392 @@
+Metadata-Version: 2.4
+Name: docker-stack
+Version: 2.3.2
+Summary: CLI for deploying and managing Docker stacks.
+Home-page: https://github.com/mesudip/docker-stack
+Author: Sudip Bhattarai
+Author-email: sudip@bhattarai.me
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: PyYAML
+Provides-Extra: dev
+Requires-Dist: pytest<9,>=8; extra == "dev"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# Docker Stack CLI Utility
+
+A command-line tool for advanced Docker Swarm stack deployments on plain Docker daemons. `docker-stack` extends vanilla `docker stack deploy` with generated secrets, templated configs, versioned stack state, safer rollbacks, and better day-to-day stack workflows.
+
+## Installation
+
+Install or upgrade `docker-stack` with:
+
+```bash
+pip install docker-stack --upgrade --break-system-packages
+```
+
+## Quick Start
+
+### Plain Docker Daemon
+
+If you already have a Docker Swarm daemon or Docker context, you can use the advanced stack features directly against it.
+
+Typical daemon-only workflow:
+
+```bash
+docker-stack deploy my-stack docker-compose.yml
+docker-stack ls
+docker-stack ls -n team-a
+docker-stack ls -A
+docker-stack versions my-stack
+docker-stack cat my-stack
+docker-stack checkout my-stack v2
+docker-stack node ls
+```
+
+What this gives you on a raw Docker daemon:
+
+-   richer secret and config handling in Compose
+-   generated secrets without external scripts
+-   template expansion from env vars and files
+-   versioned stack config history
+-   stack version inspection and checkout
+-   raw daemon compatibility without extra infrastructure
+
+### GitHub Actions
+
+#### 1. Normal Docker daemon
+
+Use this when the runner already has Docker access through the default Docker context or `DOCKER_HOST`.
+
+```yaml
+steps:
+  - uses: actions/checkout@v4
+  - uses: actions/setup-python@v6
+    with:
+      python-version: '3.x'
+  - run: python3 -m pip install --upgrade docker-stack
+  - run: docker-stack deploy my-stack docker-compose.yml
+```
+
+Use this option when CI can connect directly to the target Docker daemon.
+
+#### 2. Docker-Manager
+
+Use the bundled action when deploying through
+[Docker-Manager](https://github.com/mesudip/docker-enterprise). The manager
+repository contains the server source, installation instructions, and deployment
+documentation.
+
+For a full compose deployment directly from CI, use the action to configure
+Docker-Manager authentication and then run the normal `docker-stack deploy`
+command:
+
+```yaml
+permissions:
+  contents: read
+  id-token: write
+
+steps:
+  - uses: actions/checkout@v4
+  - uses: mesudip/docker-stack@v2
+    with:
+      manager: https://manager.example.com:2378
+  - run: docker-stack deploy --namespace team-a --with-registry-auth my-stack docker-compose.yml
+```
+
+You can also deploy the full compose file through action inputs:
+
+```yaml
+permissions:
+  contents: read
+  id-token: write
+
+steps:
+  - uses: actions/checkout@v4
+  - uses: mesudip/docker-stack@v2
+    with:
+      manager: https://manager.example.com:2378
+      stack: my-stack
+      compose-file: docker-compose.yml
+      namespace: team-a
+      with-registry-auth: "true"
+```
+
+To release new service images without submitting the compose file again:
+
+```yaml
+permissions:
+  contents: read
+  id-token: write
+
+steps:
+  - uses: actions/checkout@v4
+  - uses: mesudip/docker-stack@v2
+    with:
+      manager: https://manager.example.com:2378
+      stack: my-stack
+      namespace: team-a
+      with-registry-auth: "true"
+      images: |
+        api=ghcr.io/acme/api:${{ github.sha }}
+        worker=ghcr.io/acme/worker:${{ github.sha }}
+```
+
+Use a full compose deployment when the workflow owns the complete stack
+definition. Use an image-only deployment when the stack is already managed and
+the workflow only needs to release new images. Both forms support namespaces;
+the namespace defaults to `default` when omitted.
+
+### Authenticated Docker-Manager shell
+
+Open an isolated Bash or Zsh session for a manager context:
+
+```bash
+docker-stack shell office
+```
+
+If `office` does not exist yet, the CLI asks for its Docker-Manager URL, creates
+the context, authenticates, and opens the shell. You can also provide everything
+non-interactively with `docker-stack shell --context office <manager-url>`.
+
+Stack commands use the `default` namespace unless `-n/--namespace` is supplied.
+Listings print the selected namespace; `docker-stack ls -A` (or
+`--all-namespaces`) lists every visible namespace.
+
+The prompt displays `(docker:office@cluster)`, keeps the selected manager context active,
+and refreshes authentication when needed. The session supports `docker` and
+`docker compose`; legacy `docker-compose` is not supported. If authentication
+expires, run `docker-stack login` again.
+
+Container listing is cluster-aware and includes the owning Swarm node. Select a
+node when working with daemon-local resources such as volumes and images:
+
+```bash
+docker ps
+docker-stack node current
+docker-stack node use worker-02
+docker volume ls
+docker image ls
+docker-stack node use cluster
+```
+
+Node selection is stored only in the managed shell's isolated Docker
+configuration and appears in the prompt as `(docker:office@worker-02)`.
+Selected-node requests remain subject to the manager's Docker permissions;
+image management is root-only because the manager does not define delegated
+image permissions.
+
+Cluster-aware output is enabled after the manager has observed compatible
+agents on every discovered node. The manager remembers that capability until it
+restarts, so a temporary agent outage does not make the CLI revert to a legacy
+feature decision. A partial cluster listing prints the available containers,
+reports each failed node on stderr with its incident id, and exits non-zero.
+
+`docker ps --quiet` and `docker ps --format ...` use Docker's native formatter
+and therefore do not add the `NODE` column. Explicit Docker overrides such as
+`--context`, `--host`/`-H`, and `--config` bypass managed cluster formatting and
+are sent unchanged to the Docker CLI.
+
+## What It Adds
+
+Beyond `docker stack deploy`, against a plain Docker daemon:
+
+- **Generated secrets** — no external scripts; see [Object Versioning and Reuse](#object-versioning-and-reuse) for the once-only semantics.
+- **Inline and templated configs/secrets** — content in the compose file, or expanded from environment variables and files.
+- **Automatic versioning** — configs and secrets are content-hashed and versioned, so edits do not require hand-written `_v2` names.
+- **Version inspection and checkout** — `versions`, `cat`, and `checkout` restore a complete recorded stack version, including its configs.
+- **Cluster-aware inspection** — stack and node output that reports the owning Swarm node.
+
+### Concurrent deploys (Docker-Manager)
+
+Docker-Manager runs one apply per stack at a time. When `docker-stack deploy`
+or `docker-stack checkout` finds another run in progress (a UI deploy, a CI
+image bump, another operator), it waits and prints who started it:
+
+```
+[manager] waiting: a deploy started by alice 42s ago is still running (waiting up to 300s, set DOCKER_MANAGER_DEPLOY_WAIT_SECS to change)
+[manager] press Enter twice to force your deploy (aborts that run; changes it already made to the daemon stay), Ctrl+C to quit
+```
+
+- It retries every 5 seconds until the stack is free or `DOCKER_MANAGER_DEPLOY_WAIT_SECS` runs out (default: the deploy timeout; `0` fails immediately). CI runs wait the same way, without the prompt.
+- At a terminal, pressing Enter twice within 3 seconds asks the manager to abort the running deployment and deploys as soon as the stack is released. This needs stack deploy permission and is offered once per run. The aborted run stops orchestrating, but daemon requests it already made still complete; your deploy then applies over that state.
+- Ctrl+C exits without touching the other run.
+
+## Compose Extensions
+
+`docker-stack` reads extra keys under top-level `configs:` and `secrets:` and
+resolves them into real Docker objects before calling `docker stack deploy`.
+Standard Compose keys (`file:`, `external:`, `name:`) continue to work.
+
+| Key | Configs | Secrets | Content comes from |
+| --- | --- | --- | --- |
+| `file:` | yes | yes | the file, verbatim (standard Compose) |
+| `x-content` | yes | yes | a literal string in the compose file |
+| `x-template` | yes | yes | a literal string, with `${VAR}` expanded |
+| `x-template-file` | yes | yes | a file, with `${VAR}` expanded |
+| `environment` | no | yes | the named environment variable |
+| `x-generate` | no | yes | a value generated by `docker-stack` |
+
+Exactly one content key per object.
+
+### `x-content` — inline content
+
+```yaml
+secrets:
+  my_inline_secret:
+    x-content: "This is my secret content defined inline."
+
+configs:
+  my_inline_config:
+    x-content: |
+      key=value
+      another_key=another_value
+```
+
+### `x-template` and `x-template-file` — environment substitution
+
+`${VAR}` references are expanded from the deploying shell's environment.
+
+```yaml
+secrets:
+  my_templated_secret:
+    x-template: "${API_KEY_NAME}:${MY_API_KEY}"
+
+configs:
+  my_config_from_template_file:
+    x-template-file: "./templates/my_config.tpl"
+```
+
+### `environment` — content from a variable
+
+```yaml
+secrets:
+  api_token:
+    environment: API_TOKEN
+configs:
+  app_conf:
+    environment: APP_CONF_VALUE
+```
+
+If the variable is unset or empty, the deploy fails before any Docker object is
+created.
+
+Configs are supported on Docker-Manager deploys, where the value travels in the
+stack `.env` and the manager resolves it. A raw daemon deploy supports secrets
+only. The two are handled differently on purpose: a secret's value is inlined
+locally so it is never written to the `.env` that is stored with the stack.
+
+### `x-generate` — generated secrets
+
+Secrets only. Configs must use `x-content`, `x-template`, or `x-template-file`.
+
+```yaml
+secrets:
+  # default options, random length 12-20
+  simple:
+    x-generate: true
+
+  # fixed length, default character classes
+  fixed_length:
+    x-generate: 30
+
+  # explicit character classes
+  api_token:
+    x-generate:
+      length: 40
+      numbers: true    # digits 0-9              (default true)
+      special: true    # punctuation             (default true)
+      uppercase: true  # A-Z                     (default true)
+```
+
+Lowercase letters are always included and the value always starts with a
+letter.
+
+`special: true` leaves out `$`, `'`, `"` and `\`, so generated values are safe
+to paste into a shell or a YAML file. Use `special: false` when the application
+rejects punctuation, or for values that go in URLs or HTTP headers:
+
+```yaml
+secrets:
+  bearer_token:
+    x-generate:
+      length: 64
+      numbers: true
+      special: false
+      uppercase: true
+```
+
+## Versioning and Reuse
+
+Docker configs and secrets cannot be changed in place. `docker-stack` handles
+that for you: when a config's content changes, it creates a new version and
+points your services at it. You never have to add `_v2` to names yourself.
+
+**Generated secrets are created once.** Redeploying does not change them, so
+anything holding a generated value keeps working. The value survives
+redeploys, restarts and unrelated changes to the stack.
+
+### Stored source metadata
+
+Versioned stack configs include a top-level `x-files` list holding
+base64-encoded source material for recovery and auditing: the original compose
+file as `compose.yml`, a generated `.env` containing referenced non-secret
+environment values, and any config files referenced by `configs.*.file` or
+`configs.*.x-template-file`.
+
+Secret source files, and the variables named by `secrets.*.environment`, are
+deliberately **not** stored in `x-files`.
+
+### Rotating a generated secret
+
+There is no rotate flag. Remove the secret's newest version, then deploy again
+to get a fresh value:
+
+```bash
+docker secret rm <name>_v<N>
+docker-stack deploy --show-generated my-stack docker-compose.yml
+```
+
+`--show-generated` prints the new value. Update anything still holding the old
+one.
+
+### Secrets you created yourself
+
+If a secret already exists because you ran `docker secret create`, pointing
+`x-generate` at it does **not** take it over. The deploy generates a new value
+instead, and anything holding the old one stops working.
+
+Either leave it as `external: true`, or move to `x-generate` deliberately:
+deploy once with `--show-generated`, then update your clients. After that it
+behaves like any other generated secret.
+
+## Known Limitations
+
+Docker limits config content to 500 KB. Stack history includes encoded source
+files, so stacks with large compose or config files can exceed that limit.
+
+## Development
+
+Install runtime and test dependencies with either:
+
+```bash
+python3 -m pip install -r requirements-dev.txt
+```
+
+or:
+
+```bash
+python3 -m pip install -e '.[dev]'
+```

{docker_stack-2.3.0.dist-info → docker_stack-2.3.2.dist-info}/RECORD

@@ -1,12 +1,12 @@
 docker_stack/__init__.py,sha256=qgHdW8ZDBlyk6FzIf8Mld_cJD1SjOfqo2dELg4pK668,880
-docker_stack/cli.py,sha256=rEIjauHe9Cz0k-2j6guaeThQR2aaVrFeEW16qG1y8QI,100468
+docker_stack/cli.py,sha256=4l08fHaQurX0A3cRcoNx2oBlx4YFRSeuL_AV9y4SzGk,108003
 docker_stack/command_runner.py,sha256=mNaUAVKtrJbji_5ARVPLKhc92avqllNKrVQj1A6S0dA,1252
 docker_stack/compose.py,sha256=_fAVesjyW5ecid46sYYhcu02yF1vqknDSCFYflJPDOE,534
 docker_stack/conflict_prompt.py,sha256=1pmsyJZyZbzKYAtLJ8kYNVSC0LJb6fsu8Qz2zWvyqBE,4911
 docker_stack/docker_objects.py,sha256=U6szytv5gKrmBYKqThSeMMXdiJ2u4STIQLkeqQ-Fn4Q,12103
 docker_stack/envsubst.py,sha256=gdEUpsjWJeNbbahySk56vUdQh1nns85o3LbU6SUBo3I,8337
 docker_stack/envsubst_merge.py,sha256=TwOu8BducG0rWnSreJGwesNi-VghCetljcf-aWceE8M,4971
-docker_stack/helpers.py,sha256=nJHaIS1vtFyPYclXVl3-Qd-1h55jnSy1LwdATDrF4hk,5953
+docker_stack/helpers.py,sha256=ppN3VBf-OYGoXhIpJrNzyAFrAJVJR5N-oNQvpeJdg-g,6136
 docker_stack/login.py,sha256=jnrmrDh79Brlzj89YdZ1sGpg-ex16yb3ZN47eFpcW5g,41754
 docker_stack/manager_api.py,sha256=9AnVzsbYDllo1NeQM5vq7zTlQfPXXEYX24vXeuQCj74,44403
 docker_stack/markers.py,sha256=gqStnr0tNWZ1kzqvREc2jVQVQrevheShgJtL5QzSx4g,2388
@@ -14,8 +14,8 @@ docker_stack/merge_conf.py,sha256=Pmsabcgf3SDyaWvf2OLsBPodzEqsvOIjj9xzn_qWXH0,19
 docker_stack/registry.py,sha256=sWC1J9JDIrcYyhei1POYCZHJ0xUCKC2pveisSHMgYsQ,9036
 docker_stack/shell_auth.py,sha256=UUu9y4wMFKfc_j86yGcasvS_TLZ2uV4kv0T4XKTMQBQ,33424
 docker_stack/url_parser.py,sha256=Sk8GQE0nEiwCkijp1OltP2AfgtKEmM2hybcH_rBhfiI,6824
-docker_stack-2.3.0.dist-info/METADATA,sha256=AOgiK8qI7kxr18yUxvOqEDrbOhpLMR_vRCi9zhuKCcU,15013
-docker_stack-2.3.0.dist-info/WHEEL,sha256=SmOxYU7pzNKBqASvQJ7DjX3XGUF92lrGhMb3R6_iiqI,91
-docker_stack-2.3.0.dist-info/entry_points.txt,sha256=mpe2RwIguARsosXIUBQEN2pKU53URqZCh2S4ATwDFL4,55
-docker_stack-2.3.0.dist-info/top_level.txt,sha256=zT6TPL54cLrt9LO_MNkhEpGGOmsoe2HV6Na5Ohy3_2c,13
-docker_stack-2.3.0.dist-info/RECORD,,
+docker_stack-2.3.2.dist-info/METADATA,sha256=igRt3mHXB_3EXVvAnsjTneG3N37_jTqSvtTsKDYEM5U,13121
+docker_stack-2.3.2.dist-info/WHEEL,sha256=SmOxYU7pzNKBqASvQJ7DjX3XGUF92lrGhMb3R6_iiqI,91
+docker_stack-2.3.2.dist-info/entry_points.txt,sha256=mpe2RwIguARsosXIUBQEN2pKU53URqZCh2S4ATwDFL4,55
+docker_stack-2.3.2.dist-info/top_level.txt,sha256=zT6TPL54cLrt9LO_MNkhEpGGOmsoe2HV6Na5Ohy3_2c,13
+docker_stack-2.3.2.dist-info/RECORD,,

docker_stack-2.3.0.dist-info/METADATA

@@ -1,411 +0,0 @@
-Metadata-Version: 2.4
-Name: docker-stack
-Version: 2.3.0
-Summary: CLI for deploying and managing Docker stacks.
-Home-page: https://github.com/mesudip/docker-stack
-Author: Sudip Bhattarai
-Author-email: sudip@bhattarai.me
-Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-Requires-Dist: PyYAML
-Provides-Extra: dev
-Requires-Dist: pytest<9,>=8; extra == "dev"
-Dynamic: author
-Dynamic: author-email
-Dynamic: classifier
-Dynamic: description
-Dynamic: description-content-type
-Dynamic: home-page
-Dynamic: provides-extra
-Dynamic: requires-dist
-Dynamic: requires-python
-Dynamic: summary
-
-# Docker Stack CLI Utility
-
-A command-line tool for advanced Docker Swarm stack deployments on plain Docker daemons. `docker-stack` extends vanilla `docker stack deploy` with generated secrets, templated configs, versioned stack state, safer rollbacks, and better day-to-day stack workflows.
-
-## Installation
-
-Install or upgrade `docker-stack` with:
-
-```bash
-pip install docker-stack --upgrade --break-system-packages
-```
-
-## Quick Start
-
-### Plain Docker Daemon
-
-If you already have a Docker Swarm daemon or Docker context, you can use the advanced stack features directly against it.
-
-Typical daemon-only workflow:
-
-```bash
-docker-stack deploy my-stack docker-compose.yml
-docker-stack ls
-docker-stack ls -n team-a
-docker-stack ls -A
-docker-stack versions my-stack
-docker-stack cat my-stack
-docker-stack checkout my-stack v2
-docker-stack node ls
-```
-
-What this gives you on a raw Docker daemon:
-
--   richer secret and config handling in Compose
--   generated secrets without external scripts
--   template expansion from env vars and files
--   versioned stack config history
--   stack version inspection and checkout
--   raw daemon compatibility without extra infrastructure
-
-### GitHub Actions
-
-#### 1. Normal Docker daemon
-
-Use this when the runner already has Docker access through the default Docker context or `DOCKER_HOST`.
-
-```yaml
-steps:
-  - uses: actions/checkout@v4
-  - uses: actions/setup-python@v6
-    with:
-      python-version: '3.x'
-  - run: python3 -m pip install --upgrade docker-stack
-  - run: docker-stack deploy my-stack docker-compose.yml
-```
-
-Use this option when CI can connect directly to the target Docker daemon.
-
-#### 2. Docker-Manager
-
-Use the bundled action when deploying through
-[Docker-Manager](https://github.com/mesudip/docker-enterprise). The manager
-repository contains the server source, installation instructions, and deployment
-documentation.
-
-For a full compose deployment directly from CI, use the action to configure
-Docker-Manager authentication and then run the normal `docker-stack deploy`
-command:
-
-```yaml
-permissions:
-  contents: read
-  id-token: write
-
-steps:
-  - uses: actions/checkout@v4
-  - uses: mesudip/docker-stack@v2
-    with:
-      manager: https://manager.example.com:2378
-  - run: docker-stack deploy --namespace team-a --with-registry-auth my-stack docker-compose.yml
-```
-
-You can also deploy the full compose file through action inputs:
-
-```yaml
-permissions:
-  contents: read
-  id-token: write
-
-steps:
-  - uses: actions/checkout@v4
-  - uses: mesudip/docker-stack@v2
-    with:
-      manager: https://manager.example.com:2378
-      stack: my-stack
-      compose-file: docker-compose.yml
-      namespace: team-a
-      with-registry-auth: "true"
-```
-
-To release new service images without submitting the compose file again:
-
-```yaml
-permissions:
-  contents: read
-  id-token: write
-
-steps:
-  - uses: actions/checkout@v4
-  - uses: mesudip/docker-stack@v2
-    with:
-      manager: https://manager.example.com:2378
-      stack: my-stack
-      namespace: team-a
-      with-registry-auth: "true"
-      images: |
-        api=ghcr.io/acme/api:${{ github.sha }}
-        worker=ghcr.io/acme/worker:${{ github.sha }}
-```
-
-Use a full compose deployment when the workflow owns the complete stack
-definition. Use an image-only deployment when the stack is already managed and
-the workflow only needs to release new images. Both forms support namespaces;
-the namespace defaults to `default` when omitted.
-
-### Authenticated Docker-Manager shell
-
-Open an isolated Bash or Zsh session for a manager context:
-
-```bash
-docker-stack shell office
-```
-
-If `office` does not exist yet, the CLI asks for its Docker-Manager URL, creates
-the context, authenticates, and opens the shell. You can also provide everything
-non-interactively with `docker-stack shell --context office <manager-url>`.
-
-Stack commands use the `default` namespace unless `-n/--namespace` is supplied.
-Listings print the selected namespace; `docker-stack ls -A` (or
-`--all-namespaces`) lists every visible namespace.
-
-The prompt displays `(docker:office@cluster)`, keeps the selected manager context active,
-and refreshes authentication when needed. The session supports `docker` and
-`docker compose`; legacy `docker-compose` is not supported. If authentication
-expires, run `docker-stack login` again.
-
-Container listing is cluster-aware and includes the owning Swarm node. Select a
-node when working with daemon-local resources such as volumes and images:
-
-```bash
-docker ps
-docker-stack node current
-docker-stack node use worker-02
-docker volume ls
-docker image ls
-docker-stack node use cluster
-```
-
-Node selection is stored only in the managed shell's isolated Docker
-configuration and appears in the prompt as `(docker:office@worker-02)`.
-Selected-node requests remain subject to the manager's Docker permissions;
-image management is root-only because the manager does not define delegated
-image permissions.
-
-Cluster-aware output is enabled after the manager has observed compatible
-agents on every discovered node. The manager remembers that capability until it
-restarts, so a temporary agent outage does not make the CLI revert to a legacy
-feature decision. A partial cluster listing prints the available containers,
-reports each failed node on stderr with its incident id, and exits non-zero.
-
-`docker ps --quiet` and `docker ps --format ...` use Docker's native formatter
-and therefore do not add the `NODE` column. Explicit Docker overrides such as
-`--context`, `--host`/`-H`, and `--config` bypass managed cluster formatting and
-are sent unchanged to the Docker CLI.
-
-## Core Capabilities
-
--   **Advanced Deployments on Plain Docker Daemons:**
-    `docker-stack` works directly against a raw Docker daemon and adds capabilities that standard `docker stack deploy` does not provide out of the box:
-    - generated secrets
-    - inline configs and secrets
-    - template rendering from environment variables and files
-    - versioned config and secret history
-    - version lookup, checkout, and rollback-oriented workflows
-    - more ergonomic stack and node inspection output
-
--   **Docker Stack Versioning and Config Backup for Rollback:**
-    The utility automatically versions your Docker configs and secrets, allowing for easy tracking of changes and seamless rollbacks to previous states. This provides a safety net for your deployments, ensuring you can always revert to a stable configuration.
-
--   **Waiting for another deploy of the same stack (Docker-Manager):**
-    Docker-Manager runs one apply per stack at a time. When `docker-stack deploy` or `docker-stack checkout` finds another run in progress (a UI deploy, a CI image bump, another operator), it waits and prints who started it:
-
-    ```
-    [manager] waiting: a deploy started by alice 42s ago is still running (waiting up to 300s, set DOCKER_MANAGER_DEPLOY_WAIT_SECS to change)
-    [manager] press Enter twice to force your deploy (aborts that run; changes it already made to the daemon stay), Ctrl+C to quit
-    ```
-
-    - It retries every 5 seconds until the stack is free or `DOCKER_MANAGER_DEPLOY_WAIT_SECS` runs out (default: the deploy timeout; `0` fails immediately). CI runs wait the same way, without the prompt.
-    - At a terminal, pressing Enter twice within 3 seconds asks the manager to abort the running deployment and deploys as soon as the stack is released. This needs stack deploy permission and is offered once per run. The aborted run stops orchestrating, but daemon requests it already made still complete; your deploy then applies over that state.
-    - Ctrl+C exits without touching the other run.
-
-## Why Use It?
-
-Vanilla Docker Stack deployments can sometimes lack the flexibility needed for dynamic environments or robust secret management. This utility bridges those gaps by:
-
--   **Automating Secret Management:** No more manual secret generation or complex external scripts.
--   **Simplifying Configuration:** Define configs and secrets directly in your compose files or use templates.
--   **Enhancing Security:** Generate strong, random secrets on the fly.
--   **Enabling Rollbacks:** Versioning ensures you can always revert to a known good state.
--   **Improving Raw Daemon Workflows:** Works directly with a plain Docker Swarm daemon.
-
-## Advanced Compose Features
-
--   **Docker Config and Secret Management with Extended Options:**
-    This utility significantly extends Docker's native config and secret management by introducing `x-` prefixed directives in your `docker-compose.yml` files. These directives allow for dynamic content generation, templating, and file inclusion, making your deployments more flexible and secure.
-
-    ### `x-content`: Inline Content for Configs and Secrets
-    Allows you to define the content of a Docker config or secret directly within your `docker-compose.yml`.
-
-    ```yaml
-    secrets:
-      my_inline_secret:
-        x-content: "This is my secret content defined inline."
-
-    configs:
-      my_inline_config:
-        x-content: |
-          key=value
-          another_key=another_value
-    ```
-
-    ### `x-template`: Environment Variable Templating
-    Enables the use of environment variables within your config or secret content, which are substituted at deployment time.
-
-    ```yaml
-    secrets:
-      my_templated_secret:
-        x-template: "I can create composite secret with template. ${API_KEY_NAME}:${MY_API_KEY}"
-    ```
-
-    ### `x-template-file`: External Template Files
-    Reference an external file whose content will be treated as a template and processed with environment variables.
-
-    ```yaml
-    configs:
-      my_config_from_template_file:
-        x-template-file: "./templates/my_config.tpl"
-    ```
-    *(Content of `./templates/my_config.tpl` might be: `DB_HOST=${DATABASE_HOST}`)*
-
-    ### `environment`: Secret Content from Environment Variables
-    Secrets can read their content from an environment variable at deploy time.
-
-    ```yaml
-    secrets:
-      api_token:
-        environment: API_TOKEN
-    ```
-
-    If the variable is unset or empty, deployment fails before Docker objects are created.
-
-    ### Stored Source Metadata
-    Versioned stack configs include a top-level `x-files` list with base64-encoded source material for recovery and auditing. This includes the original compose file as `compose.yml`, a generated `.env` containing referenced non-secret environment values, and config files referenced by `configs.*.file` or `configs.*.x-template-file`. Secret source files and variables used by `secrets.*.environment` are not stored in `x-files`.
-
-    ### `x-generate`: Dynamic Secret Generation (Secrets Only)
-    This powerful feature allows you to automatically generate random secrets based on specified criteria, eliminating the need to manually create and manage them. This is particularly useful for passwords, API keys, and other sensitive data.
-
-    Supported `x-generate` forms:
-
-    -   `true`
-        Generate a secret with default options.
-    -   integer
-        Generate a secret with the requested length.
-    -   object
-        Generate a secret with explicit generation flags.
-
-    Supported object flags:
-
-    -   `length`
-        Exact secret length.
-    -   `numbers`
-        Include digits `0-9`.
-    -   `special`
-        Include special characters.
-    -   `uppercase`
-        Include uppercase letters `A-Z`.
-
-    Behavior notes:
-
-    -   Generated values are created at deploy time.
-    -   Generated secrets are versioned like other managed secrets.
-    -   Newly generated values can be shown after deploy when `--show-generated` is enabled.
-    -   `x-generate` is for secrets only; configs should use `x-content`, `x-template`, or `x-template-file`.
-
-    -   **Simple Generation (12-20 characters, default options):**
-        ```yaml
-        secrets:
-          my_simple_generated_secret:
-            x-generate: true
-        ```
-
-    -   **Specify Length:**
-        ```yaml
-        secrets:
-          my_fixed_length_secret:
-            x-generate: 30 # Generates a 30-character secret
-        ```
-
-    -   **Custom Generation Options:**
-        You can provide a dictionary to fine-tune the generation process:
-        -   `length`: (integer, default: 12-20 random) Exact length of the secret.
-        -   `numbers`: (boolean, default: `true`) Include numbers (0-9).
-        -   `special`: (boolean, default: `true`) Include special characters (!@#$%^&*...).
-        -   `uppercase`: (boolean, default: `true`) Include uppercase letters (A-Z).
-
-        ```yaml
-        secrets:
-          my_complex_generated_secret:
-            x-generate:
-              length: 25
-              numbers: false
-              special: true
-              uppercase: true
-          my_alphanumeric_secret:
-            x-generate:
-              length: 15
-              numbers: true
-              special: false
-              uppercase: false
-        ```
-
-    -   **Database Password Style Secret:**
-        Generates a strong password with uppercase letters, lowercase letters, numbers, and special characters.
-        ```yaml
-        secrets:
-          db_password:
-            x-generate:
-              length: 32
-              numbers: true
-              special: false
-              uppercase: true
-        ```
-
-    -   **Application Token Without Special Characters:**
-        Useful when the target application rejects punctuation in credentials or tokens.
-        ```yaml
-        secrets:
-          app_token:
-            x-generate:
-              length: 40
-              numbers: true
-              special: false
-              uppercase: true
-        ```
-
-    -   **Lowercase Alphanumeric Secret:**
-        Useful for systems that want URL-safe or copy-friendly generated values.
-        ```yaml
-        secrets:
-          compact_secret:
-            x-generate:
-              length: 24
-              numbers: true
-              special: false
-              uppercase: false
-        ```
-
-## Known Limitations
-
-Docker limits config content to 500 KB. Stack history includes encoded source
-files, so stacks with large compose or config files can exceed that limit.
-
-## Development
-
-Install runtime and test dependencies with either:
-
-```bash
-python3 -m pip install -r requirements-dev.txt
-```
-
-or:
-
-```bash
-python3 -m pip install -e '.[dev]'
-```