# Spare Cores Runner
Spare Cores Runner is a command-line tool and Python API designed to simplify the process of provisioning
and managing cloud instances across various cloud providers.
It leverages Pulumi to handle infrastructure-as-code and automate the creation, and destruction of
compute instances in your preferred cloud environment.
Spare Cores Runner (`sc-runner` from now on) is used by [Spare Cores Inspector](https://github.com/SpareCores/sc-inspector)
to start up basic cloud instances with the required minimum configuration and environment to start the machine with a custom
`cloud-init` script, but it can be used to just start an instance with a given SSH key, so it's available for basic
uses.
## Supported Cloud Providers and their Credentials
`sc-runner` uses the Spare Cores database to pre-fill the available configuration options, like what regions and instance
types are available for a given cloud provider.
To use a given cloud provider, you have to provide credentials for them, either by running it in an environment,
where the underlying library can pick them up, or by specifying them through environment variables or by command line options.
For more details, see the supported vendor's Pulumi integration:
* [AWS](https://www.pulumi.com/registry/packages/aws/installation-configuration/)
* [Azure](https://www.pulumi.com/registry/packages/azure-native/installation-configuration/)
* [GCP](https://www.pulumi.com/registry/packages/gcp/installation-configuration/), [GOOGLE_CREDENTIALS](https://www.pulumi.com/registry/packages/gcp/service-account/)
* [Hetzner Cloud](https://www.pulumi.com/registry/packages/hcloud/)
* [UpCloud](https://github.com/UpCloudLtd/pulumi-upcloud)
## Pulumi
As `sc-runner` uses Pulumi under the hood to manage the cloud providers, it'll need to have a Pulumi project.
You can configure Pulumi project-related settings either by specifying them using command line arguments, shown below:
```shell
sc-runner create --help
Usage: sc-runner create [OPTIONS] COMMAND [ARGS]...
Options:
--project-name TEXT Pulumi project name [default: runner]
--work-dir TEXT Pulumi work dir [default: /data/workdir]
--pulumi-home TEXT Pulumi home [default: /root/.pulumi]
--pulumi-backend-url TEXT Pulumi backend URL [default: file:///data/backend]
--stack-name TEXT Pulumi stack name, defaults to
{vendor}.{region}.{zone}.{instance_id} or similar
--help Show this message and exit.
Commands:
aws
azure
gcp
hcloud
upcloud
```
Or by setting the following environment variables:
* PULUMI_PROJECT_NAME
* PULUMI_WORK_DIR
* PULUMI_HOMEPULUMI_BACKEND_URL
`sc-runner` should create the project on the first invocation, in which it'll create multiple stacks for each
`vendor.region.zone.instance_id` tuple. This is to allow concurrent creation of the instances, supporting our
Spare Cores Inspector use case, where we start a given instance type once for collection data from them.
## Usage
### CLI examples
#### Create instances
Create and destroy a default `t3.micro` instance in the default VPC/subnet in AWS:
```shell
sc-runner create aws
sc-runner destroy aws
```
Create an Azure instance with a public key:
```shell
sc-runner create azure --instance Standard_DS1_v2 --public-key $(cat .ssh/id_ed25519.pub)
```
Create an AWS instance with public IP and an already stored SSH key named `spare_cores`:
```shell
sc-runner create aws --region us-west-2 --instance t4g.large --instance-opts '{"associate_public_ip_address": true,"key_name":"spare-cores"}' --public-key ""
```
#### Destroy instances
```shell
sc-runner destroy azure --instance Standard_DS1_v2
sc-runner destroy aws --region us-west-2 --instance t4g.large
```
You can also user `destroy-stack` instead of `destroy`, which does a `pulumi refresh` first, synchronizing the underlying
cloud-reality with Pulumi's internal backend and destroys only what's really there (so it won't fail on already deleted
resources).
##### Cancelling Pulumi Locks
Sometimes Pulumi might leave a lock file in its state store, preventing further operations. With this command you can
cancel those:
```shell
sc-runner cancel aws --region us-west-2 --instance t4g.large
```
### Docker
`sc-runner` is available through a Docker image as well, which you can use with the following command:
```shell
docker run --rm -ti ghcr.io/sparecores/sc-runner:main --help
```
You'll have to set up the same environment variables or configure the cloud credentials for Pulumi.
Raw data
{
"_id": null,
"home_page": null,
"name": "sparecores-runner",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "Spare Cores team <pkg@sparecores.com>",
"keywords": "cloud, compute",
"author": "Attila Nagy, Gergely Daroczi, Balazs Hodobay",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/a9/06/ec7596a54638d5872248e2e7d20aec3b3307216730d764c3fe84981cfdbd/sparecores_runner-0.0.30.tar.gz",
"platform": null,
"description": "# Spare Cores Runner\n\nSpare Cores Runner is a command-line tool and Python API designed to simplify the process of provisioning \nand managing cloud instances across various cloud providers.\nIt leverages Pulumi to handle infrastructure-as-code and automate the creation, and destruction of \ncompute instances in your preferred cloud environment.\n\nSpare Cores Runner (`sc-runner` from now on) is used by [Spare Cores Inspector](https://github.com/SpareCores/sc-inspector)\nto start up basic cloud instances with the required minimum configuration and environment to start the machine with a custom\n`cloud-init` script, but it can be used to just start an instance with a given SSH key, so it's available for basic\nuses.\n\n## Supported Cloud Providers and their Credentials\n\n`sc-runner` uses the Spare Cores database to pre-fill the available configuration options, like what regions and instance\ntypes are available for a given cloud provider.\nTo use a given cloud provider, you have to provide credentials for them, either by running it in an environment,\nwhere the underlying library can pick them up, or by specifying them through environment variables or by command line options.\n\nFor more details, see the supported vendor's Pulumi integration:\n\n* [AWS](https://www.pulumi.com/registry/packages/aws/installation-configuration/)\n* [Azure](https://www.pulumi.com/registry/packages/azure-native/installation-configuration/)\n* [GCP](https://www.pulumi.com/registry/packages/gcp/installation-configuration/), [GOOGLE_CREDENTIALS](https://www.pulumi.com/registry/packages/gcp/service-account/)\n* [Hetzner Cloud](https://www.pulumi.com/registry/packages/hcloud/)\n* [UpCloud](https://github.com/UpCloudLtd/pulumi-upcloud)\n\n## Pulumi\n\nAs `sc-runner` uses Pulumi under the hood to manage the cloud providers, it'll need to have a Pulumi project.\nYou can configure Pulumi project-related settings either by specifying them using command line arguments, shown below:\n\n```shell\nsc-runner create --help\nUsage: sc-runner create [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n --project-name TEXT Pulumi project name [default: runner]\n --work-dir TEXT Pulumi work dir [default: /data/workdir]\n --pulumi-home TEXT Pulumi home [default: /root/.pulumi]\n --pulumi-backend-url TEXT Pulumi backend URL [default: file:///data/backend]\n --stack-name TEXT Pulumi stack name, defaults to\n {vendor}.{region}.{zone}.{instance_id} or similar\n --help Show this message and exit.\n\nCommands:\n aws\n azure\n gcp\n hcloud\n upcloud\n```\n\nOr by setting the following environment variables:\n\n* PULUMI_PROJECT_NAME\n* PULUMI_WORK_DIR\n* PULUMI_HOMEPULUMI_BACKEND_URL\n\n`sc-runner` should create the project on the first invocation, in which it'll create multiple stacks for each \n`vendor.region.zone.instance_id` tuple. This is to allow concurrent creation of the instances, supporting our\nSpare Cores Inspector use case, where we start a given instance type once for collection data from them.\n\n## Usage\n### CLI examples\n\n#### Create instances\n\nCreate and destroy a default `t3.micro` instance in the default VPC/subnet in AWS:\n```shell\nsc-runner create aws\nsc-runner destroy aws\n```\n\nCreate an Azure instance with a public key:\n```shell\nsc-runner create azure --instance Standard_DS1_v2 --public-key $(cat .ssh/id_ed25519.pub)\n```\n\nCreate an AWS instance with public IP and an already stored SSH key named `spare_cores`:\n```shell\nsc-runner create aws --region us-west-2 --instance t4g.large --instance-opts '{\"associate_public_ip_address\": true,\"key_name\":\"spare-cores\"}' --public-key \"\"\n```\n\n#### Destroy instances\n\n```shell\nsc-runner destroy azure --instance Standard_DS1_v2\nsc-runner destroy aws --region us-west-2 --instance t4g.large\n```\n\nYou can also user `destroy-stack` instead of `destroy`, which does a `pulumi refresh` first, synchronizing the underlying\ncloud-reality with Pulumi's internal backend and destroys only what's really there (so it won't fail on already deleted\nresources).\n\n##### Cancelling Pulumi Locks\n\nSometimes Pulumi might leave a lock file in its state store, preventing further operations. With this command you can\ncancel those:\n\n```shell\nsc-runner cancel aws --region us-west-2 --instance t4g.large\n```\n\n### Docker\n\n`sc-runner` is available through a Docker image as well, which you can use with the following command:\n```shell\ndocker run --rm -ti ghcr.io/sparecores/sc-runner:main --help\n```\n\nYou'll have to set up the same environment variables or configure the cloud credentials for Pulumi.\n",
"bugtrack_url": null,
"license": null,
"summary": "Start cloud instances.",
"version": "0.0.30",
"project_urls": {
"documentation": "https://sparecores.github.io/sc-runner/",
"homepage": "https://sparecores.com",
"issues": "https://github.com/SpareCores/sc-runner/issues",
"repository": "https://github.com/SpareCores/sc-runner"
},
"split_keywords": [
"cloud",
" compute"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a212f56be4ccb259dfaa6967122b010ed38f4851d609de020910c31c6ee65b2e",
"md5": "21026b0a943633a8cafe176d13290e91",
"sha256": "a290b010512018075d0f5858e588a4bc65385a6d46c986ec85f25aff5389a461"
},
"downloads": -1,
"filename": "sparecores_runner-0.0.30-py3-none-any.whl",
"has_sig": false,
"md5_digest": "21026b0a943633a8cafe176d13290e91",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 22373,
"upload_time": "2024-12-18T22:06:36",
"upload_time_iso_8601": "2024-12-18T22:06:36.798248Z",
"url": "https://files.pythonhosted.org/packages/a2/12/f56be4ccb259dfaa6967122b010ed38f4851d609de020910c31c6ee65b2e/sparecores_runner-0.0.30-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a906ec7596a54638d5872248e2e7d20aec3b3307216730d764c3fe84981cfdbd",
"md5": "2397c8244aa0b7ba5aa7cb9654952e33",
"sha256": "fc229b52806ce660b179b112ff0f3937581477078717dae8ff8230e7431b1e71"
},
"downloads": -1,
"filename": "sparecores_runner-0.0.30.tar.gz",
"has_sig": false,
"md5_digest": "2397c8244aa0b7ba5aa7cb9654952e33",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 19765,
"upload_time": "2024-12-18T22:06:39",
"upload_time_iso_8601": "2024-12-18T22:06:39.912367Z",
"url": "https://files.pythonhosted.org/packages/a9/06/ec7596a54638d5872248e2e7d20aec3b3307216730d764c3fe84981cfdbd/sparecores_runner-0.0.30.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-18 22:06:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "SpareCores",
"github_project": "sc-runner",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "sparecores-runner"
}
JSON
