{"id":16264994,"url":"https://github.com/ninesstack/sidecar-executor","last_synced_at":"2025-03-19T23:30:28.457Z","repository":{"id":39853279,"uuid":"75077265","full_name":"NinesStack/sidecar-executor","owner":"NinesStack","description":"Run Docker containers on Mesos with Sidecar service discovery!","archived":false,"fork":false,"pushed_at":"2022-10-05T18:28:37.000Z","size":4933,"stargazers_count":21,"open_issues_count":3,"forks_count":8,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-03-17T11:50:37.109Z","etag":null,"topics":["docker","docker-container","golang","mesos","sidecar"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NinesStack.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}},"created_at":"2016-11-29T12:01:15.000Z","updated_at":"2023-05-24T00:53:33.000Z","dependencies_parsed_at":"2022-08-27T17:20:54.515Z","dependency_job_id":null,"html_url":"https://github.com/NinesStack/sidecar-executor","commit_stats":null,"previous_names":["nitro/sidecar-executor"],"tags_count":46,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NinesStack%2Fsidecar-executor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NinesStack%2Fsidecar-executor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NinesStack%2Fsidecar-executor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NinesStack%2Fsidecar-executor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NinesStack","download_url":"https://codeload.github.com/NinesStack/sidecar-executor/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244524380,"owners_count":20466416,"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":["docker","docker-container","golang","mesos","sidecar"],"created_at":"2024-10-10T17:05:08.283Z","updated_at":"2025-03-19T23:30:27.940Z","avatar_url":"https://github.com/NinesStack.png","language":"Go","readme":"Sidecar Executor\n===============\n\nRun Docker containers on Mesos with\n[Sidecar](https://github.com/newrelic/sidecar) service discovery! We're running\nit with HubSpot's [Singularity](https://github.com/HubSpot/Singularity)\nscheduler.\n\nThis is a Mesos executor that integrates with the service discovery platform\n[Sidecar](https://github.com/newrelic/sidecar) to more tightly tie Sidecar into\nthe Mesos ecosystem. The main advantage is that the executor leverages the\nservice health checking that Sidecar already provides in order to fail Mesos\ntasks quickly when they have gone off the rails.\n\nWith Sidecar and Sidecar Executor you get service health checking unified with\nservice Discovery, regardless of which Mesos scheduler you are running. The\nsystem is completely scheduler agnostic to the extent possible.\n\nNote that _unlike_ Sidecar, Sidecar Executor assumes that tasks are to be run\nas Docker containers. You may of course still integrate non-Dockerized services\nwith Sidecar as normal.\n\nSubset of Features\n------------------\n\nThis executor does not attempt to support every single option that Docker can\nsupport for running containers. It supports the core feature set that most\npeople actually use. If you are looking for something that it doesn't currently\nprovide, pull requests or feature requests are welcome.\n\n### Currently supported:\n * Environment variables\n * Docker labels\n * Exposed port and port mappings\n * Volume binds from the host\n * Network mode setting\n * Capability Add\n * Capability Drop\n * Resolve environment variables stored in [Vault](https://www.vaultproject.io)\n * Enforce CPU and Memory limits via Docker cgroups\n\nThis set of features probably supports most of the production containers out\nthere.\n\n\nDebugability\n------------\n\nThis executor tries to expose as much information as possible to help with the\npainful task of debugging a Mesos task failure. It logs each of the actions\nthat it takes and why. And, on startup it logs both the current environment\nvariables which the executor will run with, the settings for the executor, and\nthe Docker environment that will be supplied to the container. This can be\ncritical in understanding how a task failed.\n\nWhen a task fails or is killed, the executor will fetch the last logs that were\nsent to the container, and copy them to its own stdout and stderr. This means\nthat in most cases the Mesos logs will now contain the failure messages and\nthere is usually no need to dig further into logging frameworks to find out\nwhat happened.\n\nAdditionally since each instance of the executor manages a single container,\nthe process name of the executor that shows up in `ps` output contains both\nthe ID of the Docker container and the Docker image name that was used to\nstart it.\n\nRunning the Executor\n--------------------\n\nA separate copy of the executor is started for each task. The binary is small\nand only uses a few MB of memory so this is fairly cheap.\n\nBut, since the executor will always be running as long as your task, it will\nhave the file open and you won't be ablet to replace it (e.g. to upgrade) while\nthe task is running. It's thus recommended that you run the `executor.sh`\nscript as the actual executor defined in each of your tasks. That will in turn\ncopy the binary from a location of your choosing to the task's sandbox and then\nexecute it from there. This means that the copy of the executor used to start\nthe task will remain in the sandbox directory for the life of the task and\nsolves the problem nicely.\n\nTo upgrade the executor you can then simply replace the binary in the defined\nlocation on your systems and any new tasks will start under the new copy while\nolder tasks remain running under their respective version. By default the\nshell script assumes the path will be `/opt/mesos/sidecar-executor`.\n\nConfiguration\n-------------\n\nEach task can be run with its own executor configuration. This is helpful when\nin situations such as needing to delay health checking for apps that are slow\nto start, allowing for longer grace periods or a larger failure count before\nshooting a container. You may configure the executor via environment variables\nin the Mesos task. These will then be present for the executor at the time that\nit runs. Note that these are separate from the environment variables used in\nthe Docker container. Currently the settings available are:\n\nSetting                 | Default\n------------------------|----------------------------\nKillTaskTimeout         | 5 (seconds)\nHttpTimeout             | 2s\nSidecarRetryCount       | 5\nSidecarRetryDelay       | 3s\nSidecarUrl              | http://localhost:7777/state.json\nSidecarBackoff          | 1m\nSidecarPollInterval     | 30s\nSidecarMaxFails         | 3\nSidecarDrainingDuration | 10s\nSeedSidecar             | false\nDockerRepository        | https://index.docker.io/v1/\nLogsSince               | 3m\nForceCpuLimit           | false\nForceMemoryLimit        | false\nUseCpuShares            | false\nDebug                   | false\nMesosMasterPort         | 5050\nRelaySyslog             | false\nRelaySyslogStartupOnly  | false\nRelaySyslogStartupTime  | 1m\nSyslogAddr              | 127.0.0.1:514\nContainerLogsStdout     | false\nSendDockerLabels        | []\nLogHostname             | System Hostname\n\nAll of the environment variables are of the form `EXECUTOR_SIDECAR_RETRY_DELAY`\nwhere all of the CamelCased words are split apart, and each setting is prefixed\nwith `EXECUTOR_`.\n\n * **KillTaskTimeout**: This is the amount of time to wait before we hard kill\n   the container. Initially we send a SIGTERM and after this timeout we follow\n   up with a SIGKILL. If your process has a clean shutdown procedure and takes\n   awhile, you may want to back this off to let it complete shutdown before\n   being hard killed by the kernel. **Note** that unlike the other settings,\n   this, for internal library reasons, is an integer in seconds and not a Go\n   time spec.\n\n * **HttpTimeout**: The timeout when talking to Sidecar. The default should be\n   far longer than needed unless you really have something wrong.\n\n * **SidecarRetryCount**: This is the number of times we'll retry calling to\n   Sidecar when health checking.\n\n * **SidecarRetryDelay**: The amount of time to wait between retries when\n   contacting Sidecar.\n\n * **SidecarUrl**: The URL to use to contact Sidecar. The default will usually\n   be the right setting.\n\n * **SidecarBackoff**: How long to wait before we start health checking to Sidecar.\n   You want this value to be longer than the time it takes your process to start\n   up and start responding as healthy on the health check endpoint.\n\n * **SidecarPollInterval**: The interval between asking Sidecar how healthy we\n   are.\n\n * **SidecarMaxFails**: How many failed checks to Sidecar before we shut down\n   the container? Note that this is not just _contacting_ Sidecar. This is how\n   many _affirmed_ unhealthy checks we need to receive, each spaced apart by\n   `SidecarPollInterval`.\n\n * **SidecarDrainingDuration**: How much time to wait before killing the container\n   after instructing Sidecar to set the current service's status to `DRAINING`.\n   Setting this to `0` will prevent the executor from telling Sidecar to trigger\n   the `DRAINING` state and it will kill the container as soon as possible.\n\n * **SeedSidecar**: Should we query the Mesos master for the list of workers\n   and then provide those in the `SIDECAR_SEEDS` environment variables?\n\n * **DockerRepository**: This is used to match the credentials that we'll store\n   from the Docker config. This will follow the same matching order as\n   [described here](https://godoc.org/github.com/fsouza/go-dockerclient#NewAuthConfigurationsFromDockerCfg).\n   The executor expects to use only one set of credentials for each job.\n\n * **LogsSince**: When the container exits or is killed, the executor will copy\n   logs from the Docker container output to its own stdout and stderr so that\n   they show up in the Mesos logs. `LogsSince` is how far back in time we\n   reach to get these logs.\n\n * **ForceCpuLimit**: Should we enforce the CPU limits in the request using\n   cgroups (via Docker)?\n\n * **ForceMemoryLimit**: Should we enforce the memory limits in the request using\n   cgroups (via Docker)?\n\n * **UseCpuShares**: By default we use the Linux Completely Fair Scheduler\n   settings to control CPU limiting. This doesn't work well for certain\n   workloads. Should we instead use the older CPU Shares relative workload\n   limiting mechanism? Note that you should understand the difference before\n   turning this on. \n\n * **Debug**: Should we turn on debug logging (verbose!) for this executor?\n\n * **MesosMasterPort**: The port on which the Mesos Master node listens on.\n\n * **RelaySyslog**: Should we relay container logs to syslog? This is a bare UDP\n   implementation suitable for loggers that don't care about syslog protocol.\n   Logs will be sent in JSON format, using Logrus.\n\n * **RelaySyslogStartupOnly**: Should we relay container logs to syslog only\n   for the startup duration? This is helpful for apps that do their own\n   syslogging but are not able to log during their startup process. The length\n   of time to relay logs is controlled by `RelaySyslogStartupTime`.\n\n * **RelaySyslogStartupTime**: By itself this configuration item does nothing.\n   It controls the value for how long to log for when `RelaySyslogStartupOnly`\n   is set.\n\n * **SyslogAddr**: If `RelaySyslog` is true, we'll use this as the remote address\n   for syslog logging.\n\n * **ContainerLogsStdout**: Should we copy the container logs to stdout? The\n   effect of doing this is that container logs (both stdout and stderr) will end\n   up in the Mesos sandbox logs. Be careful here since the Mesos logs are *not*\n   rotated by the Mesos worker. Requires that `RelaySyslog` be true. Note that\n   if you don't want syslog but you do want this option, there is not *much* harm\n   in turning on `RelaySyslog` since the UDP packets will just drop. **Note**:\n   This only works with Docker log drivers `json-file` and `journald` because it\n   uses the native Docker logging functionality to collect the logs.\n\n * **SendDockerLabels**: If `RelaySyslog` is true, should we augment JSON logs\n   with some fields defined in Docker labels? This is a comma-separated list\n   of labels. They will be sent with the field name being the Docker label name.\n\n * **LogHostname**: When relaying logs, we will add this as the `Hostname`\n   field. Defaults to the OS hostname and can be overridden with `LOG_HOSTNAME`\n   in the environment.\n\nSpecial AWS Role Configuration\n------------------------------\n\nIn addition to all the executor level settings above, you may also pass the\nfollowing env vars into the executor to enable the executor to maintain AWS\ncreds with a specific role via Vault:\n\n * `EXECUTOR_AWS_ROLE` - specifies the AWS role (pre-existing in IAM/Vault) to\n   request. By itself this will give you the default TTL for the policy\n\n * `EXECUTOR_AWS_ROLE_TTL` - This will allow you extend the requested time, up to\n   the max allowed by Vault for the policy. The value is a string, specified\n   in [Go Duration format](https://golang.org/pkg/time/#ParseDuration). E.g.\n   \"1m40s\" for 1 minute and 40 seconds.\n\nVault Configuration\n-------------------\n\nBecause the executor uses the Vault library, it lets the Vault client configure\nitself from its own environment settings. You can look these up in the Vault\n[source](https://github.com/hashicorp/vault/blob/master/api/client.go#L28) if\nyou'd like to see them all. The executor adds a couple of others to better\ncontrol the Vault integration. You should specify at least the following:\n\n * `VAULT_ADDR` - URL of the Vault server.\n * `VAULT_MAX_RETRIES` - API retries before Vault fails.\n * `VAULT_TOKEN` - Optional if specified in a file or using userpass.\n * `VAULT_TOKEN_FILE` - Where to cache Vault tokens between calls to the\n   executor on the same host.\n * `VAULT_TTL` - The TTL in seconds of the Vault Token we'll have issued note\n   that the grace period is one hour so shorter than 1 hour is not possible.\n\n**WARNING** If you are using Vault, you _really_ want to have the executor\ncache tokens to a `VAULT_TOKEN_FILE`. If not you can build up quite a lot of\ntokens in Vault, and that doesn't work well. Especially in a fast job failure\nscenario where executors running on multiple machines might be generating\ntokens constantly.\n\n\n\nConfiguring Docker Connectivity\n-------------------------------\n\nSidecar Executor supports all the normal environment variables for configuring\nyour connection to the Docker daemon. It will look for `DOCKER_HOST`, etc in\nthe runtime environment and configure connectivity accordingly.\n\nContributing\n------------\n\nContributions are more than welcome. Bug reports with specific reproduction\nsteps are great. If you have a code contribution you'd like to make, open a\npull request with suggested code.\n\nPull requests should:\n\n * Clearly state their intent in the title\n * Have a description that explains the need for the changes\n * Include tests!\n * Not break the public API\n\nPing us to let us know you're working on something interesting by opening a GitHub Issue on the project.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fninesstack%2Fsidecar-executor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fninesstack%2Fsidecar-executor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fninesstack%2Fsidecar-executor/lists"}