{"id":13586239,"url":"https://github.com/opsani/skopos-plugin-swarm-exec","last_synced_at":"2026-01-17T08:51:26.477Z","repository":{"id":117653408,"uuid":"90004155","full_name":"opsani/skopos-plugin-swarm-exec","owner":"opsani","description":"A tool for executing commands in service containers deployed on Docker swarm and a Skopos plugin for doing the same","archived":false,"fork":false,"pushed_at":"2017-05-17T16:23:10.000Z","size":18,"stargazers_count":11,"open_issues_count":0,"forks_count":2,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-02-14T21:25:04.058Z","etag":null,"topics":["container-management","docker","docker-swarm","open-source","orchestration","skopos-plugin","tools"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/opsani.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-05-02T07:27:03.000Z","updated_at":"2024-08-01T16:32:14.472Z","dependencies_parsed_at":null,"dependency_job_id":"35005882-eeba-4205-aa5e-4f02701ee654","html_url":"https://github.com/opsani/skopos-plugin-swarm-exec","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opsani%2Fskopos-plugin-swarm-exec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opsani%2Fskopos-plugin-swarm-exec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opsani%2Fskopos-plugin-swarm-exec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opsani%2Fskopos-plugin-swarm-exec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/opsani","download_url":"https://codeload.github.com/opsani/skopos-plugin-swarm-exec/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223285197,"owners_count":17119858,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["container-management","docker","docker-swarm","open-source","orchestration","skopos-plugin","tools"],"created_at":"2024-08-01T15:05:25.259Z","updated_at":"2026-01-17T08:51:26.458Z","avatar_url":"https://github.com/opsani.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# skopos-plugin-swarm-exec\n\n[![Join the chat at https://gitter.im/datagridsys/skopos](https://badges.gitter.im/datagridsys/skopos.svg)](https://gitter.im/datagridsys/skopos?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n\nA tool for executing commands in service containers deployed on Docker swarm - equivalent to:\n\n`docker service exec \u003ctask_id\u003e \u003ccommand\u003e \u003cargs\u003e`\n\nIt also provides a Skopos plugin for doing the same in the [Skopos Continuous Deployment System](http://datagridsys.com).\n\n## Background\n\nDocker Swarm does not yet provide a way to execute commands inside a service\ntask from the manager node (CLI or API). This project provides an easy-to-use\nmechanism for doing just that: executing a command in the container of a service task.\n\nThink of it as a `docker service exec` that applies to a specific task of a service.\n\nWhile this project is intended for use with the [Skopos Continuous Deployment System](http://datagridsys.com),\nit can be used as a standalone tool to provide the same capability during the deployment process (see [FAQ](http://datagridsys.com/skopos-faq/)).\n\nThe need for this project is expected to go away when the\n[Support for executing into a task #1895](https://github.com/docker/swarmkit/issues/1895)\nissue is resolved in the Docker swarm project and the same capability becomes available\ndirectly in the Docker swarm API and command-line client. \n\nThe exec capability, together with `docker service logs` (already included in Docker 17.05.0-ce as non-experimental), a `docker service signal`, as well as pause/resume, will provide closure of the container operation functions between plain Docker containers and services that run containers on a swarm cluster.\n\n## Standalone Use\n\nOn the swarm manager node, run the following command:\n\n```\ndocker run -v /var/run/docker.sock:/var/run/docker.sock\n    datagridsys/skopos-plugin-swarm-exec \\\n    task-exec \u003ctaskID\u003e \u003ccommand\u003e [\u003carguments\u003e...]\n```\n\nwhere:\n\n* `\u003ctaskID\u003e` is the task ID of the task in which you want to execute a command (see task IDs with `docker service ps \u003cservice_name\u003e`)\n* `\u003ccommand\u003e` command to execute (e.g. `curl`)\n* `\u003carguments\u003e...` zero or more arguments to pass to the command (e.g., `http://example.com/file`)\n\n\u003eNote: it is possible to use the `swarm-exec` script directly, if python3 and\nthe docker Python SDK are installed, and the `lib` directory is included in the\nPython module path. The container packaging is easier to use in most cases.\n\n\n## Use With Skopos\n\n### Setup\n\nCopy the `plugin` directory to the host on which you run Skopos, e.g., into `~/skopos/`.\nStart Skopos using the following command, on the Swarm manager node:\n\n```\ndocker run -d -p 8090:80 --restart=unless-stopped --name skopos \\\n    -v ~/skopos/plugin:/skopos/user/bin          \\\n    -v /var/run/docker.sock:/var/run/docker.sock \\\n    datagridsys/skopos\n```\n\nNote that this will map the `plugin` directory into the Skopos container, providing\nthe `swarm-exec` plugin as a user-defined plugin in Skopos.\n\n\u003eAlternate method: re-package Skopos into a new container, starting from\nthe original `datagridsys/skopos` container and placing the `swarm-exec` file\ndirectly into the `/skopos/plugins/` directory. There is no need to use the `lib`\ndirectory, as Skopos already has the required libraries. This method eliminates the\nneed to use host directory mapping and may be more appropriate for production clusters.\n\n### Model Steps\n\nTo add command execution into each instance of the newly deployed/upgraded\ncomponent, add the `lifecycle` section to the component's model section, with\none or more `call` sub-sections:\n\n```\n...\ncomponents:\n  mycomponent:\n    image: myrepo/myimage:1.2.3\n    ...\n    lifecycle:\n      quality_probe:\n        steps:\n          - call:\n              label: \"execute a command\" # text to show in plan view\n              plugin: swarm-exec\n              action: inst_exec\n              arguments:\n                selector: new \t\t    # required, don't change\n                command: \"sleep 3\"      # command to execute, single string\n...\n```\n\nFor a fully functioning example app, see the [example](example/) directory. Feel\nfree to modify the command in the `back` component and experiment with various\ncommands and arguments:\n\n* `true` - should succeed\n* `false` - should fail (exit code 1)\n* `foobarnone` - should fail as a non-existing command (exit code 126)\n* `sleep 5` - should succeed, with a visible 5 second delay during the exec step\n* `sleep 60` - should fail, as the exec timeout is set to 30 seconds\n\nTo load and run a deployment of the example app, use the following command\n(assuming Skopos is on port 8090 and you are running on the same host):\n\n`sks-ctl --bind localhost:8090 run --replace-all --env env.yaml model.yaml`\n\n\u003eOnce loaded with the above command, it is possible to experiment by simply\nchanging the model using the built-in YAML editor.\n\n\n### Supported Actions and Arguments\n\nThe **swarm-exec** plugin supports only one action, `inst_exec` and the following arguments for it:\n\n* `command` - (required) command to execute, string\n* `timeout` - (optional) how long to wait for command to complete, in seconds. Default: 300 seconds (5 minutes)\n* `image` - (optional) alternate container image to use for invoking the container command. Default: `datagridsys/skopos-plugin-swarm-exec:latest`\n\n## Limitations\n\n* requires Docker Swarm, 17.03 or later, and must execute on a swarm manager node\n* commands must be strings (lists don't work)\n* only the exit code is returned, currently there is no way to see the output from the command\n\n## Tips\n\n1. To verify the plugin is working, try using `'true'` and `'false'` as commands (make sure those are in quotes to avoid parsing them as booleans)\n1. If the exit code is `126`, this usually means the command's executable was not found.\n\n## How It Works (Internals)\n\nStarting from a task ID and a command to execute, here are the steps that are taken:\n\n1. Obtain the node ID on which the target task is running, as well as the container ID\nof the task on that node\n1. Create a temporary service, using the same container image, and a scheduling constraint\nthat places the task of the temporary service on the same node where the target task is\n1. Execute the equivalent of a `docker exec` command using the node-local Docker engine API\n1. Upon completion of the command, terminate the temporary service, propagating the exit code of the executed command\n1. Upon termination of the temporary service, extract the exit code and return it\n\n## License\n\nThis is an open source project. See the [LICENSE](LICENSE) file.\n\n## Contributing\n\nIf you want to propose an improvement, issues and pull requests are always welcome!\n\nYou can reach the project maintainers on [Gitter](https://gitter.im/datagridsys/skopos).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopsani%2Fskopos-plugin-swarm-exec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopsani%2Fskopos-plugin-swarm-exec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopsani%2Fskopos-plugin-swarm-exec/lists"}