{"id":22454632,"url":"https://github.com/ngine-io/cs","last_synced_at":"2025-05-16T09:03:59.447Z","repository":{"id":55476360,"uuid":"21390959","full_name":"ngine-io/cs","owner":"ngine-io","description":"A simple, yet powerful CloudStack API client for python and the command-line.","archived":false,"fork":false,"pushed_at":"2025-01-19T06:58:20.000Z","size":288,"stargazers_count":87,"open_issues_count":0,"forks_count":39,"subscribers_count":20,"default_branch":"master","last_synced_at":"2025-04-12T04:49:12.598Z","etag":null,"topics":["cloudstack","cloudstack-api","cloudstack-cli"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ngine-io.png","metadata":{"files":{"readme":"README.rst","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},"funding":{"github":["resmo"],"custom":["paypal.me/resmo"]}},"created_at":"2014-07-01T14:35:46.000Z","updated_at":"2025-04-07T12:01:24.000Z","dependencies_parsed_at":"2022-08-15T01:10:48.842Z","dependency_job_id":"1f639857-bde9-4fe6-9ce6-7a40b2a769ce","html_url":"https://github.com/ngine-io/cs","commit_stats":{"total_commits":189,"total_committers":21,"mean_commits":9.0,"dds":0.6613756613756614,"last_synced_commit":"229e0c166d77da24d3608aa2b0abc92a87ee69cb"},"previous_names":["ngine-io/cs","exoscale/cs"],"tags_count":62,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ngine-io%2Fcs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ngine-io%2Fcs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ngine-io%2Fcs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ngine-io%2Fcs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ngine-io","download_url":"https://codeload.github.com/ngine-io/cs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254501556,"owners_count":22081528,"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":["cloudstack","cloudstack-api","cloudstack-cli"],"created_at":"2024-12-06T07:08:47.534Z","updated_at":"2025-05-16T09:03:59.417Z","avatar_url":"https://github.com/ngine-io.png","language":"Python","funding_links":["https://github.com/sponsors/resmo","paypal.me/resmo"],"categories":["Libraries"],"sub_categories":["Vagrant"],"readme":".. image:: https://github.com/ngine-io/cs/actions/workflows/main.yml/badge.svg\n   :alt: CI\n   :target: https://github.com/ngine-io/cs/actions/workflows/main.yml\n.. image:: https://img.shields.io/pypi/pyversions/cs.svg\n   :alt: Python versions\n   :target: https://pypi.org/project/cs/\n\n.. image:: https://img.shields.io/pypi/dw/cs.svg\n   :alt: Downloads / Week\n   :target: https://pypi.org/project/cs/\n\n.. image:: https://img.shields.io/pypi/l/cs.svg\n   :alt: License\n   :target: https://pypi.org/project/cs/\n\nCS - Python CloudStack API client \n=================================\n\nA simple, yet powerful CloudStack API client for python and the command-line.\n\n* Async support.\n* All present and future CloudStack API calls and parameters are supported.\n* Syntax highlight in the command-line client if Pygments is installed.\n* BSD license.\n\nInstallation\n------------\n\n::\n\n    pip install cs\n\n    # with the colored output\n    pip install cs[highlight]\n\n    # with the async support\n    pip install cs[async]\n\n    # with both\n    pip install cs[async,highlight]\n\nUsage\n-----\n\nIn Python:\n\n.. code-block:: python\n\n    from cs import CloudStack\n\n    cs = CloudStack(endpoint='https://cloudstack.example.com/client/api',\n                    key='cloudstack api key',\n                    secret='cloudstack api secret')\n\n    vms = cs.listVirtualMachines()\n\n    cs.createSecurityGroup(name='web', description='HTTP traffic')\n\nFrom the command-line, this requires some configuration:\n\n.. code-block:: console\n\n    cat $HOME/.cloudstack.ini\n\n.. code-block:: ini\n\n    [cloudstack]\n    endpoint = https://cloudstack.example.com/client/api\n    key = cloudstack api key\n    secret = cloudstack api secret\n    # Optional ca authority certificate\n    verify = /path/to/certs/ca.crt\n    # Optional client PEM certificate\n    cert = /path/to/client.pem\n    # If you need to pass the certificate and key as separate files\n    cert_key = /path/to/client_key.pem\n\nThen:\n\n.. code-block:: console\n\n    $ cs listVirtualMachines\n\n.. code-block:: json\n\n    {\n      \"count\": 1,\n      \"virtualmachine\": [\n        {\n          \"account\": \"...\",\n          ...\n        }\n      ]\n    }\n\n.. code-block:: console\n\n    $ cs authorizeSecurityGroupIngress \\\n        cidrlist=\"0.0.0.0/0\" endport=443 startport=443 \\\n        securitygroupname=\"blah blah\" protocol=tcp\n\nThe command-line client polls when async results are returned. To disable\npolling, use the ``--async`` flag.\n\nTo find the list CloudStack API calls go to\nhttp://cloudstack.apache.org/api.html\n\nConfiguration\n-------------\n\nConfiguration is read from several locations, in the following order:\n\n* The ``CLOUDSTACK_ENDPOINT``, ``CLOUDSTACK_KEY``, ``CLOUDSTACK_SECRET`` and\n  ``CLOUDSTACK_METHOD`` environment variables,\n* A ``CLOUDSTACK_CONFIG`` environment variable pointing to an ``.ini`` file,\n* A ``CLOUDSTACK_VERIFY`` (optional) environment variable pointing to a CA authority cert file,\n* A ``CLOUDSTACK_CERT`` (optional) environment variable pointing to a client PEM cert file,\n* A ``CLOUDSTACK_CERT_KEY`` (optional) environment variable pointing to a client PEM certificate key file,\n* A ``cloudstack.ini`` file in the current working directory,\n* A ``.cloudstack.ini`` file in the home directory.\n\nTo use that configuration scheme from your Python code:\n\n.. code-block:: python\n\n    from cs import CloudStack, read_config\n\n    cs = CloudStack(**read_config())\n\nNote that ``read_config()`` can raise ``SystemExit`` if no configuration is\nfound.\n\n``CLOUDSTACK_METHOD`` or the ``method`` entry in the configuration file can be\nused to change the HTTP verb used to make CloudStack requests. By default,\nrequests are made with the GET method but CloudStack supports POST requests.\nPOST can be useful to overcome some length limits in the CloudStack API.\n\n``CLOUDSTACK_TIMEOUT`` or the ``timeout`` entry in the configuration file can\nbe used to change the HTTP timeout when making CloudStack requests (in\nseconds). The default value is 10.\n\n``CLOUDSTACK_RETRY`` or the ``retry`` entry in the configuration file\n(integer) can be used to retry ``list`` and ``queryAsync`` requests on\nfailure. The default value is 0, meaning no retry.\n\n``CLOUDSTACK_JOB_TIMEOUT`` or the `job_timeout`` entry in the configuration file\n(float) can be used to set how long an async call is retried assuming ``fetch_result`` is set to true). The default value is ``None``, it waits forever.\n\n``CLOUDSTACK_POLL_INTERVAL`` or the ``poll_interval`` entry in the configuration file (number of seconds, float) can be used to set how frequently polling an async job result is done. The default value is 2.\n\n``CLOUDSTACK_EXPIRATION`` or the ``expiration`` entry in the configuration file\n(integer) can be used to set how long a signature is valid. By default, it picks\n10 minutes but may be deactivated using any negative value, e.g. -1.\n\n``CLOUDSTACK_DANGEROUS_NO_TLS_VERIFY`` or the ``dangerous_no_tls_verify`` entry\nin the configuration file (boolean) can be used to deactivate the TLS verification\nmade when using the HTTPS protocol.\n\nMultiple credentials can be set in ``.cloudstack.ini``. This allows selecting\nthe credentials or endpoint to use with a command-line flag.\n\n.. code-block:: ini\n\n    [cloudstack]\n    endpoint = https://some-host/api/v1\n    key = api key\n    secret = api secret\n\n    [region-example]\n    endpoint = https://cloudstack.example.com/client/api\n    key = api key\n    secret = api secret\n\nUsage::\n\n    $ cs listVirtualMachines --region=region-example\n\nOptionally ``CLOUDSTACK_REGION`` can be used to overwrite the default region ``cloudstack``.\n\nFor the power users that don't want to put any secrets on disk,\n``CLOUDSTACK_OVERRIDES`` let you pick which key will be set from the\nenvironment even if present in the ini file.\n\n\nPagination\n----------\n\nCloudStack paginates requests. ``cs`` is able to abstract away the pagination\nlogic to allow fetching large result sets in one go. This is done with the\n``fetch_list`` parameter::\n\n    $ cs listVirtualMachines fetch_list=true\n\nOr in Python::\n\n    cs.listVirtualMachines(fetch_list=True)\n\nTracing HTTP requests\n---------------------\n\nOnce in a while, it could be useful to understand, see what HTTP calls are made\nunder the hood. The ``trace`` flag (or ``CLOUDSTACK_TRACE``) does just that::\n\n   $ cs --trace listVirtualMachines\n\n   $ cs -t listZones\n\nAsync client\n------------\n\n``cs`` provides the ``AIOCloudStack`` class for async/await calls in Python\n3.5+.\n\n.. code-block:: python\n\n    import asyncio\n    from cs import AIOCloudStack, read_config\n\n    cs = AIOCloudStack(**read_config())\n\n    async def main():\n       vms = await cs.listVirtualMachines(fetch_list=True)\n       print(vms)\n\n    asyncio.run(main())\n\nAsync deployment of multiple VMs\n________________________________\n\n.. code-block:: python\n\n    import asyncio\n    from cs import AIOCloudStack, read_config\n\n    cs = AIOCloudStack(**read_config())\n\n    machine = {\"zoneid\": ..., \"serviceofferingid\": ..., \"templateid\": ...}\n\n    async def main():\n       tasks = asyncio.gather(*(cs.deployVirtualMachine(name=f\"vm-{i}\",\n                                                        **machine,\n                                                        fetch_result=True)\n                                for i in range(5)))\n\n       results = await tasks\n\n       # Destroy all of them, but skip waiting on the job results\n       await asyncio.gather(*(cs.destroyVirtualMachine(id=result['virtualmachine']['id'])\n                              for result in results))\n\n    asyncio.run(main())\n\nRelease Procedure\n-----------------\n\n.. code-block:: shell-session\n\n    mktmpenv -p /usr/bin/python3\n    pip install -U twine wheel build\n    cd ./cs\n    rm -rf build dist\n    python -m build\n    twine upload dist/*\n\nLinks\n-----\n\n* CloudStack API: http://cloudstack.apache.org/api.html\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fngine-io%2Fcs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fngine-io%2Fcs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fngine-io%2Fcs/lists"}