{"id":18510781,"url":"https://github.com/envato/knuckle_cluster","last_synced_at":"2025-08-01T03:35:47.768Z","repository":{"id":52258772,"uuid":"90819881","full_name":"envato/knuckle_cluster","owner":"envato","description":"Gem to interrogate and connect to ECS clusters, Spot fleets and Autoscaling groups","archived":false,"fork":false,"pushed_at":"2024-01-25T02:04:33.000Z","size":149,"stargazers_count":10,"open_issues_count":2,"forks_count":1,"subscribers_count":42,"default_branch":"master","last_synced_at":"2024-04-26T01:21:34.701Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Ruby","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/envato.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","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-10T04:11:07.000Z","updated_at":"2023-04-11T13:32:43.000Z","dependencies_parsed_at":"2024-01-25T02:46:46.808Z","dependency_job_id":"4f853b00-3b96-4498-80f8-3d5064b45c56","html_url":"https://github.com/envato/knuckle_cluster","commit_stats":{"total_commits":84,"total_committers":6,"mean_commits":14.0,"dds":"0.40476190476190477","last_synced_commit":"d230c2540155b61df3ff69a16e1a45f79ae081fc"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/envato%2Fknuckle_cluster","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/envato%2Fknuckle_cluster/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/envato%2Fknuckle_cluster/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/envato%2Fknuckle_cluster/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/envato","download_url":"https://codeload.github.com/envato/knuckle_cluster/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247953107,"owners_count":21023947,"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":[],"created_at":"2024-11-06T15:25:07.051Z","updated_at":"2025-04-09T04:33:23.817Z","avatar_url":"https://github.com/envato.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# KnuckleCluster\n\nHave you ever wanted to shuck away the hard, rough exterior of an ECS cluster and get to the soft, chewy innards? Sounds like you need KnuckleCluster!\nThis tool provides scripts, invoked via cli or rakefile, to list, connect to and/or run commands on ecs agents and containers via ssh.  This makes it very easy to interrogate ECS agents and containers without having to go digging for IP addresses and things.\nPrimarily created as a tool to connect to instances in an ECS cluster and see what is running on them, it has evolved slightly to include the ability to list instances in spot requests and auto-scaling groups.\n\n## Features\n* See what agents in your ECS cluster are doing\n* Easily connect to running agents\n* Easily connect and get a console inside running containers\n* Create shortcuts to oft-used commands and run them easily\n* Optionally integrates with [aws-vault](https://github.com/99designs/aws-vault) for AWS authentication\n\n## Development Status\nIs being used in production for various projects and is considered stable. Any new features/bug fixes etc are most welcome!\n\n## Installation\n\nKnuckleCluster can be used in two ways:\n1.  As a system-wide executable with a config file (preferred)\n1.  As a rake task in your project\n\nInstall the executable with:\n\n    $ gem install knuckle_cluster\n\nOR\n\nAdd this line to your application's Gemfile:\n\n```ruby\nsource 'https://rubygems.envato.com/' do\n  gem 'knuckle_cluster'\nend\n```\n\nAnd then execute:\n\n    $ bundle\n\n\n## Usage\n\nKnuckle Cluster can be used either as a part of an application via a rakefile, or at a system level.\n\nYou'll need to execute knuckle_cluster with appropriate AWS permissions on the cluster in question, stored in your ENV. I like to use `aws-vault` to handle this for me.\n\n### System usage\n\nCreate a file: `~/.ssh/knuckle_cluster`.  This is the config file that will be used to make connections from the command line.  It is a yaml file.  The connection name is the key, and all parameters are below it. EG:\n```\nplatform:\n  cluster_name: platform-ecs-cluster-ABC123\n  region: us-east-1\n  bastion: platform_bastion\n  rsa_key_location: ~/.ssh/platform_rsa_key\n  ssh_username: ubuntu\n  sudo: true\n  aws_vault_profile: platform_super_user\n  shortcuts:\n    console:\n      container: web\n      command: bundle exec rails console\n    db:\n      container: worker\n      command: script/db_console\n  tunnels:\n    db:\n      local_port: 54321\n      remote_host: postgres-db.yourcompany.com\n      remote_port: 5432\n  hide:\n    container: some_container_regex_i_dont_care_about\n    task: some_task_regex_i_dont_care_about\n```\n\nSee [Options for Knuckle Cluster](#options-for-knuckle-cluster) below for a list of what each option does.\n\nCommand line options:\n\n```\nknuckle_cluster list - list all available clusters\nknuckle_cluster CLUSTER_PROFILE agents - list all agents and select one to start a shell\nknuckle_cluster CLUSTER_PROFILE containers - list all containers and select one to start a shell\nknuckle_cluster CLUSTER_PROFILE logs CONTAINER_NAME - tail the logs for a container\nknuckle_cluster CLUSTER_PROFILE CONTAINER_NAME [OPTIONAL COMMANDS] - connect to a container and start a shell or run a command\nknuckle_cluster CLUSTER_PROFILE SHORTCUT_NAME - run a shortcut defined in your knuckle_cluster configuration\nknuckle_cluster CLUSTER_PROFILE tunnel TUNNEL_NAME - open a tunnel defined in your knuckle_cluster configuration\nknuckle_cluster CLUSTER_PROFILE scp source destination - copied a file via scp to or from a container or agent. Use container:\u003clocation\u003e or agent:\u003clocation\u003e\n```\n\n### Rakefile usage\n\nIt takes one argument at minimum: `cluster_name` .  A region is likely also required as it will default to `us-east-1`.\nEg:\n```\nkc = KnuckleCluster.new(\n  cluster_name: 'platform-ecs-cluster-ABC123',\n  region: 'us-east-1',\n  bastion: 'platform_bastion',\n  rsa_key_location: \"~/.ssh/platform_rsa_key\",\n  ssh_username: \"ubuntu\",\n  sudo: true\n)\ntask :agents do\n  kc.connect_to_agents\nend\n\ntask :containers do\n  kc.connect_to_containers\nend\n```\n\ninvoke with `rake agents` or `rake containers`\n\n\nOnce you have an instance of KnuckleCluster, you can now do things!\n```\n$ knuckle_cluster super_platform containers\n```\nWhich will give you the output and run bash for you on the actual docker container:\n```\nListing Containers\nTASK              | AGENT               | INDEX | CONTAINER\n------------------|---------------------|-------|--------------------\ntask-one          | i-123abc123abc123ab | 1     | t1-container-one\ntask-two          | i-123abc123abc123ab | 2     | t2-container-one\n                  |                     | 3     | t2-container-two\ntask-three        | i-456def456def456de | 4     | t3-container-one\n                  |                     | 5     | t3-container-two\n                  |                     | 6     | t3-container-three\n\nEnter the INDEX number and press ENTER to connect:\n```\n\nSame with connecting directly to agents\n```\n$ knuckle_cluster super_platform agents\n```\n```\nListing Agents\nINDEX | INSTANCE_ID         | TASK       | CONTAINER\n------|---------------------|------------|--------------------\n1     | i-123abc123abc123ab | task-one   | t1-container-one\n      |                     | task-two   | t2-container-one\n      |                     |            | t2-container-two\n2     | i-456def456def456de | task-three | t3-container-one\n      |                     |            | t3-container-two\n      |                     |            | t3-container-three\n\nEnter the INDEX number and press ENTER to connect:\n```\n\nBoth `connect_to_containers` and `connect_to_agents` can have the following optional arguments:\n\nArgument | Description\n-------- | -----------\ncommand | Runs a command on the specified container/agent. When connecting to containers, this defaults to `bash`\nauto | Automatically connects to the first container/agent it can find. Handy when used in conjunction with `command`.\n\n\n\nEg: To connect to a container, echo something and then immediately disconnect you could use:\n```\nkc.connect_to_containers(auto: true, command: \"echo I love KnuckleCluster!\")\n```\n\n\n## Options for Knuckle Cluster\nPossible options are below. If left blank, they will be ignored and defaults used where available.:\n\nArgument | Description\n-------- | -----------\ncluster_name | The name of the cluster (not the ARN). eg 'my-super-cluster'. One of `cluster_name`,`spot_request_id` or `asg_name` is required.\nspot_request_id | The spot request ID you are connecting to. eg 'sfr-abcdef'. One of `cluster_name`,`spot_request_id` or `asg_name` is required.\nasg_name | The auto-scaling group name you are connecting to. eg 'very-scaly-group'. One of `cluster_name`,`spot_request_id` or `asg_name` is required.\nregion | The AWS region you would like to use. Defaults to `us-east-1`\nbastion | if you have a bastion to proxy to your ecs cluster via ssh, put the name of it here as defined in your `~/.ssh/config` file.  Alternatively, this can be a collection of keys for `username`, `host`, and `rsa_key_location`\nrsa_key_location | The RSA key needed to connect to an ecs agent eg `~/.ssh/id_rsa`.\nssh_username | The username to conncet. Will default to `ec2-user`\nsudo | true or false - will sudo the `docker` command on the target machine. Usually not needed unless the user is not a part of the `docker` group.\naws_vault_profile | If you use the `aws-vault` tool to manage your AWS credentials, you can specify a profile here that will be automatically used to connect to this cluster.\nprofile | Another profile to inherit settings from. Settings from lower profiles can be overridden in higher ones.\nhide | allows you to specify a regex for either `task` or `container` to omit these from being shown\n\n## Known Issues\n\n### Aliases in the config file\n\nCurrently, aliases cannot be used in the config file. If you have aliases in your config, you might see the following error.\n\n```\nERROR: There was a problem loading your configuration: Alias parsing was not enabled. To enable it, pass `aliases: true` to `Psych::load` or `Psych::safe_load`.\n```\n\nThis is an issue with Psych changing the default behaviour around expanding aliases in Ruby 3. See [this issue](https://github.com/envato/knuckle_cluster/issues/32) for a workaround.\n\n## Spot Fleets\nIf you wish to see what instances are running within a spot fleet, KnuckleCluster can do that too!.  In your config, use `spot_request_id` instead of `cluster_name`.  Note that the `containers` command will not work when invoking (use `agents` instead).\n\n## AutoScaling Groups\nIf you wish to see what instances are running within an ASG, KnuckleCluster can do that too!.  In your config, use `asg_name` instead of `cluster_name`.  Note that the `containers` command will not work when invoking (use `agents` instead).\n\n## SCP\nYou can use Knuckle Cluster to copy files in and out of agents or containers.  Note that this will only work where one of the source or destination is your local machine, copying between containers is not yet supported.  Use a syntax similar to existing `scp` syntax when specifying a source or destination, but use the keyword `container` or `agent` for the remote. When using one of these keywords, you will be prompted as to which agent/container you wish to use.\n```\n#Copy some_file.txt into a container at /app/some_file.txt\nknuckle_cluster super_platform scp ./some_file.txt container:/app/some_file.txt\n\n#Copy /app/some_file.txt from a remote container to ./some_file.txt on your local machine\nknuckle_cluster super_platform scp container:/app/some_file.txt ./some_file.txt\n\n#Copy some_file.txt into an agent at ~/some_file.txt\nknuckle_cluster super_platform scp ./some_file.txt agent:~/some_file.txt\n\n#Copy /app/some_file.txt from a remote container to ./some_file.txt on your local machine\nknuckle_cluster super_platform scp agent:~/some_file.txt ./some_file.txt\n```\n\n## Maintainer\n[Envato](https://github.com/envato)\n\n## Contributors\n- [Peter Hofmann](https://github.com/envatopoho)\n- [Giancarlo Salamanca](https://github.com/salamagd)\n- [Jiexin Huang](https://github.com/jiexinhuang)\n\n## License\n\n`KnuckleCluster` uses MIT license. See\n[`LICENSE.txt`](https://github.com/envato/knuckle_cluster/blob/master/LICENSE.txt) for\ndetails.\n\n## Code of conduct\n\nWe welcome contribution from everyone. Read more about it in\n[`CODE_OF_CONDUCT.md`](https://github.com/envato/knuckle_cluster/blob/master/CODE_OF_CONDUCT.md)\n\n## Contributing\n\nFor bug fixes, documentation changes, and small features:\n\n1. Fork it ( https://github.com/[my-github-username]/knuckle_cluster/fork )\n2. Create your feature branch (git checkout -b my-new-feature)\n3. Commit your changes (git commit -am 'Add some feature')\n4. Push to the branch (git push origin my-new-feature)\n5. Create a new Pull Request\n\nFor larger new features: Do everything as above, but first also make contact with the project maintainers to be sure your change fits with the project direction and you won't be wasting effort going in the wrong direction.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fenvato%2Fknuckle_cluster","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fenvato%2Fknuckle_cluster","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fenvato%2Fknuckle_cluster/lists"}