{
    "info": {
        "author": "Oleg Avdeev",
        "author_email": "feedback@instaguide.io",
        "bugtrack_url": null,
        "classifiers": [
            "Development Status :: 4 - Beta",
            "Intended Audience :: Developers",
            "License :: OSI Approved :: MIT License",
            "Programming Language :: Python :: 3",
            "Topic :: Utilities"
        ],
        "description": "# GetBox\n\n#### \"playground\" instance manager\n\nIn a nutshell:\n* One-click launch ec2 spot instances and attach EBS volumes to them\n\n* Instances and volumes will be properly tagged with your team and **your** name.\n\n## Installation:\n\n### From pypi\n\n```bash\npip3 install getbox\n```\n\n### Manual\n\nThe only dependency is `boto3`, you probably already have it. If not you can install it using `pip install boto3` . After that do:\n\n```bash\npython3 getbox install\n```\n\nThat will install the binary to `/usr/local/bin` and will try to install bash completions as well.\n\n### Authentication\n\nIt assumes you have ssh key pair used to access EC2 instances in your ssh agent.\n\nYou'll need AWS creds. If you have used awscli on your machine before, you should be good. If not, install awscli and run `aws configure`.\n\n### Permissions\n\n`getbox` requires a few permissions to launch and terminate instances.\n\nExample IAM policy:\n\n```json\n{\n    \"Version\": \"2012-10-17\",\n    \"Statement\": [\n       {\n            \"Effect\": \"Allow\",\n            \"Action\": [\n                \"ec2:AttachVolume\",\n                \"ec2:CancelSpotInstanceRequests\",\n                \"ec2:CreateTags\",\n                \"ec2:DeleteVolume\",\n                \"ec2:DescribeInstances\",\n                \"ec2:DescribeKeyPairs\",\n                \"ec2:DescribeSpotInstanceRequests\",\n                \"ec2:DescribeSubnets\",\n                \"ec2:DescribeVolumes\",\n                \"ec2:ModifyInstanceAttribute\",\n                \"ec2:RequestSpotInstances\",\n                \"ec2:RunInstances\",\n                \"ec2:TerminateInstances\"\n            ],\n            \"Resource\": [\n                \"*\"\n            ]\n        }\n    ]\n}\n```\n\n## Magic\n\nLaziest way ever to get an instance in one command:\n\n```console\n$ getbox get\n<..a minute later..>\n[ubuntu@ip-172-18-142-171 ~]$\n```\n\nYou get an ubuntu 17.04 linux box in `us-west-2`. It will have a 100GB EBS drive mounted at `/mnt`.\n\nBy default, EBS drive will be deleted when instance is terminated. You can change that behavior using `getbox keep` command or you can combine that `getbox get r3.4xlarge keep`. Remember that your spot instance can be terminated by Amazon at any time.\n\n## Usage:\n\nSince it will tag instances will your unix user name, don't run it as root or in a container.\n\n```\n                      Usage: getbox <cmd> [parameters]\nget          Get an ec2 instance and ssh into it.                          getbox get r3.8xlarge\n             ...optionally, pass EBS volume id to attach.                  getbox get vol-321\n             ...or both                                                    getbox get r3.8xlarge vol-321\n             ...you can also name it                                       getbox get r3.8xlarge --name mytestbox\n             ...or specify EBS volume size                                 getbox get r3.8xlarge 200GB\nlist         List your instances and volumes                               getbox list\nkill         Kill an instance or (unattached) volume                       getbox kill 123\n                                                                           getbox kill vol-456\nssh          Log into the instance (uses utility1 key)                     getbox ssh 123\nkeep         Disable delete-on-termination on an attached EBS volume       getbox keep vol-123\nunkeep       Enable delete-on-termination on an attached EBS volume        getbox unkeep vol-123\ninstall      Install getbox to /usr/local/bin and add bash autocomplete    getbox install\n```\n\n\n\n`getbox ssh <instance-id>` is a bit magic; if used from interactive console, it will just log you in. But if it detects that its output was redirected, it will return user@host string. That allows you to use custom ssh flags or rsync/scp like this: `rsync -av . $(getbox ssh):`\n\nAlso, when starting an instance with an existing EBS drive using `getbox get vol-123141` if you don't specify instance type explicitly, `getbox` will automatically choose the instance type that was last used with that EBS volume.\n\n\n## Instances with ephemeral drives\n\nEphemeral drives often provide much better performance in terms of iops and latency than EBS. With `getbox`, you have two options: either mount ephemeral drives as a separate \"scratch\" volume, or automatically mirror data both to EBS and ephemeral drives, so it survives instance termination.\n\n##### 1. Use ephemeral drives as a scratch store\n![Ephemeral drives as scratch](getbox_scratch.png)\n\nEBS will be mounted at `/mnt` and ephemeral drives will be mounted as one RAID-0 lvm voume under `/scratch`.  You will lose everything under `/scratch` when instance gets terminated.\n\n##### 2. Use ephemeral drives as a mirror\n![Ephemeral drives as mirror](getbox_mirror.png)\n\nIn this mode, toggled by `--mirror` flag, `getbox` creates a RAID volume so that all writes go **both** to ephemeral drives as well as EBS volume. It is set up so that reads only go to the ephemeral drive when possible, so you get random read performance closest to that of the ephemeral drive and write performance of the slowest of two, and you don't lose the data when instance terminates.\n\nYou get both the (read) performance and persistence!\n\nThere are a couple caveats:\n\n* You cannot choose EBS volume size in this mode; it will be automatically choosen to match ephemeral storage, that depends on the instance type.\n* Currently you can only reuse mirrored EBS volume with the same instance type (since ephemeral drives size has to match EBS size).  `getbox` remembers what instance type was used, so you can just run `getbox get <volume-id>` and it will start an instance of the same type and will reassemble RAID array.\n* When first launching the instance in this mode, it will require 10-50 minutes to resync the RAID array; you can use the instance during resync, but read performance will be that of EBS. You can check status of resync by using `mdadm --detail /dev/md0`.\n* Remember that you still need to do `getbox keep` to keep the EBS drive around when instance terminates.\n\n\n## Configuration\n\nYou can customize some of `getbox` default parameters using JSON config file in your home dir named `.getbox`.\n\n| Name          | Description   | Default |\n| ------------- |---------------|--------|\n| `extra_tags`    | Tags to assign to ec2 instance and EBS drive | |\n| `owner_tag_name` | `getbox` also tags your instances with your username, this is the name of the tag | `\"owner\"` |\n| `ssh_user` | Linux username used to ssh into instances      |    `\"ubuntu\"` |\n| `ssh_key_name` | Name of ssh keypair to use when creating an instance      |    `\"utility1\"` |\n| `ssh_wait_timeout_seconds` | Timeout when trying to connect to a newly created instance      |    `600` |\n| `ssh_flags` | Flags to use with ssh command for `getbox ssh`      |    `\"-A\"` |\n| `root_size_gb` | Default size of the root EBS drive (GiB)      |    `30` |\n| `ami_id` | EC2 AMI id to use      |    `\"ami-790ec601\"` |\n| `cuda_ami_id` | EC2 AMI id to use with GPU-enabled instances (can be null, then `ami_id` is used)      |    `\"ami-a1e534d9\"` |\n| `iam_role_arn` | EC2 IAM role arn to use for instance profile      |     |\n| `security_groups` | A list of security group ids to use      |    |\n| `subnets` | A list of subnets to use      |   |\n| `spot_price` | Spot price | `\"3.00\"`\n| `extra_init_commands` | A list of additional commands to execute on instance initialization |  |",
        "description_content_type": "text/markdown",
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/oavdeev/getbox",
        "keywords": "ec2 aws spot ssh",
        "license": "MIT license",
        "maintainer": "",
        "maintainer_email": "",
        "name": "getbox",
        "package_url": "https://pypi.org/project/getbox/",
        "platform": "",
        "project_url": "https://pypi.org/project/getbox/",
        "project_urls": {
            "Homepage": "https://github.com/oavdeev/getbox"
        },
        "release_url": "https://pypi.org/project/getbox/0.8.0/",
        "requires_dist": null,
        "requires_python": "",
        "summary": "Spot instance managing tool for AWS EC2",
        "version": "0.8.0"
    },
    "last_serial": 4937485,
    "releases": {
        "0.7.4": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "cb473c12066a4053d8438e6768cab97a",
                    "sha256": "d2d782f1bf2b34071d817227e48bb56d780296888f4d049700969b4fa80543b5"
                },
                "downloads": -1,
                "filename": "getbox-0.7.4.tar.gz",
                "has_sig": false,
                "md5_digest": "cb473c12066a4053d8438e6768cab97a",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 16814,
                "upload_time": "2018-08-03T02:28:01",
                "url": "https://files.pythonhosted.org/packages/2a/3a/59199e934656cc0f1ad78a16e367cb2c30b1605d1bcdd3f6d2384d331227/getbox-0.7.4.tar.gz"
            }
        ],
        "0.7.5": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "0a957ae42756c8dfc68e10382019909c",
                    "sha256": "02fc76ad302ffe6ede995ef5d6b6362011b336f281fee37246cafa145dfc588f"
                },
                "downloads": -1,
                "filename": "getbox-0.7.5.tar.gz",
                "has_sig": false,
                "md5_digest": "0a957ae42756c8dfc68e10382019909c",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 16893,
                "upload_time": "2018-08-03T02:29:52",
                "url": "https://files.pythonhosted.org/packages/f2/bd/778a0445c9c0d84ef1e2e4e547d364988690d1eec16d6516916a1e753355/getbox-0.7.5.tar.gz"
            }
        ],
        "0.7.6": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "bacbd8140d21d296641567febac50b3f",
                    "sha256": "af80c69ebf0f65fd3aa8f70d32c82c227ddd591a77a29ecf04e80e28a5eeaa31"
                },
                "downloads": -1,
                "filename": "getbox-0.7.6.tar.gz",
                "has_sig": false,
                "md5_digest": "bacbd8140d21d296641567febac50b3f",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 16924,
                "upload_time": "2018-08-03T03:00:38",
                "url": "https://files.pythonhosted.org/packages/d2/a6/4aa0b3867a256c30c6b340a63fe7d624a1e9df7f262246c8dc381dde5874/getbox-0.7.6.tar.gz"
            }
        ],
        "0.7.7": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "360e829b0388e57f982f96f2dadf9929",
                    "sha256": "5a26c9d130a458cca41415796ed0963c464d4adde8f0475b83d06ff33a70a2b5"
                },
                "downloads": -1,
                "filename": "getbox-0.7.7.tar.gz",
                "has_sig": false,
                "md5_digest": "360e829b0388e57f982f96f2dadf9929",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 17591,
                "upload_time": "2019-01-13T23:03:00",
                "url": "https://files.pythonhosted.org/packages/de/fc/4d4e69403eae5641217a4f0dd48b5b4c67e200b834f596ae0e87a1517533/getbox-0.7.7.tar.gz"
            }
        ],
        "0.8.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "82cd071354b78325adf05d88a862dcb7",
                    "sha256": "3a81bd6a9d5ce1ae3698026519bca9f6fca70460a7bd6687a0975043bdefd4b2"
                },
                "downloads": -1,
                "filename": "getbox-0.8.0.tar.gz",
                "has_sig": false,
                "md5_digest": "82cd071354b78325adf05d88a862dcb7",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 18110,
                "upload_time": "2019-03-14T03:02:31",
                "url": "https://files.pythonhosted.org/packages/cd/a1/a31991143b2e6494d259062becf2065b7973922b56b307a0631c5ad20b0a/getbox-0.8.0.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "82cd071354b78325adf05d88a862dcb7",
                "sha256": "3a81bd6a9d5ce1ae3698026519bca9f6fca70460a7bd6687a0975043bdefd4b2"
            },
            "downloads": -1,
            "filename": "getbox-0.8.0.tar.gz",
            "has_sig": false,
            "md5_digest": "82cd071354b78325adf05d88a862dcb7",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 18110,
            "upload_time": "2019-03-14T03:02:31",
            "url": "https://files.pythonhosted.org/packages/cd/a1/a31991143b2e6494d259062becf2065b7973922b56b307a0631c5ad20b0a/getbox-0.8.0.tar.gz"
        }
    ]
}