cURL-like tool to access OpenStack APIs with keystone auth


License
Apache-2.0
Install
pip install oscurl==1.1.1

Documentation

oscurl

oscurl is a tool to access OpenStack APIs as raw. You can specify method, URL path and body of HTTP requests freely. It's useful to test, check or confirm OpenStack APIs.

Features

  • cURL-like access to OpenStack APIs
  • Handle Keystone authentication and insert X-Auth-Token header; You do not need to handle Keystone authentication manually
  • Construct URL based on OpenStack service endpoints (relative mode)
  • Support multiple output formats: raw, YAML, JSON, header only and body only
  • Show request header and body
  • Keystone v3 and v2 support
  • Microversioning header support. 'latest' is used by default.
  • Support multiple ways to specify keystone credentials:
    • Legacy way to use OS_* environment variables
    • os-client-config via OS_CLOUD environment variable
  • JSON input for POST and PUT requests

Installation

oscurl is available at PyPI (the Python Packaging Index). To install oscurl, just run:

$ pip install oscurl

Usage

  1. Set environment variables as same as you use nova command:

    $ source credential_file
    

    or if you have os-client-config configuration like /etc/openstack/clouds.yaml:

    $ export OS_CLOUD=<env-name>
    
  2. Run oscurl:

    $ oscurl -p /servers
    HTTP/1.1 200 OK
    X-Compute-Request-Id: req-e5d6537e-9db8-48a2-abfb-f3a63f17add5
    Content-Type: application/json
    Content-Length: 15
    Date: Sun, 22 Jun 2014 12:20:46 GMT
    
    {"servers": []}
    
  3. oscurl --help shows the options. oscurl --full-help shows the options from os-client-config too.

Environment Variables

The following environment variables can be used to change the default behavior.

  • OSCURL_SERVICE: the default service type. Service types registered in Keystone service catalog like like compute, volume, identity, image and network
  • OSCURL_FORMAT: the default format used to display API responses
  • OSCURL_METHOD: the default method to be used

Examples

  • Get server list from Nova:

    $ oscurl -p /servers
    
  • Get flavor list from Nova:

    $ oscurl -p /flavors
    
  • Get image list from Glance:

    $ oscurl -s image -p /images
    
  • Get volume list from Cinder:

    $ oscurl -s volume -p /volumes
    
  • Get network list from Neutron:

    $ oscurl -s network -p /v2.0/networks
    
  • Create a new instance by passing the input as JSON file:

    $ oscurl -m POST -p /servers -i create_instance_body.json
    

    or:

    $ oscurl -m POST -p /servers -i - < create_instance_body.json
    

    The content of create_instance_body.json is like below:

    {
        "server": {
            "name": "server-test-1",
            "imageRef": "19befdd4-248b-4b8d-b586-8a91a8bf8623",
            "flavorRef": "1",
            "max_count": 1,
            "min_count": 1,
            "networks": [
                {
                    "uuid": "6a2c033b-3f50-4f43-97fa-2517ccdc28d9"
                }
            ],
            "security_groups": [
                {
                    "name": "default"
                }
            ]
        }
    }
    
  • Show an instance information:

    $ oscurl -p /servers/fdec5b9e-9b6a-4eb4-8684-6c75cd275559
    
  • Delete an instance:

    $ oscurl -p /servers/fdec5b9e-9b6a-4eb4-8684-6c75cd275559 -m DELETE
    

Output mode

--show-mode controls what are shown.

  • ALL shows request and response including both headers and body.
  • RESP shows response headers and body. Request headers and body are not shown.
  • BODY shows response body only. Useful if you pass output to another program like jq.

Output Format

--format controls the output format of response body.

  • RAW: Show response body as-is (Default):

    $ oscurl -p /servers -r RESP
    HTTP/1.1 200 OK
    Content-Length: 296
    Content-Type: application/json
    Openstack-Api-Version: compute 2.42
    X-Openstack-Nova-Api-Version: 2.42
    Vary: OpenStack-API-Version, X-OpenStack-Nova-API-Version
    X-Compute-Request-Id: req-565bb028-c144-40cc-8fb5-52f1c5ff3b58
    Date: Fri, 24 Mar 2017 09:07:08 GMT
    Connection: keep-alive
    
    {"servers": [{"id": "2820fcfc-3cd2-4a40-8c01-3c9544cfbc59", "links": [{"href": "http://172.27.201.206:8774/v2.1/servers/2820fcfc-3cd2-4a40-8c01-3c9544cfbc59", "rel": "self"}, {"href": "http://172.27.201.206:8774/servers/2820fcfc-3cd2-4a40-8c01-3c9544cfbc59", "rel": "bookmark"}], "name": "vm1"}]}
    
  • JSON: Human-readable JSON format:

    $ oscurl -p /servers --show-mode RESP -f JSON
    HTTP/1.1 200 OK
    Content-Length: 296
    Content-Type: application/json
    Openstack-Api-Version: compute 2.42
    X-Openstack-Nova-Api-Version: 2.42
    Vary: OpenStack-API-Version, X-OpenStack-Nova-API-Version
    X-Compute-Request-Id: req-3293cc26-c336-454a-b361-0a97aaa8c571
    Date: Fri, 24 Mar 2017 09:09:14 GMT
    Connection: keep-alive
    
    {
      "servers": [
        {
          "id": "2820fcfc-3cd2-4a40-8c01-3c9544cfbc59",
          "links": [
            {
              "href": "http://172.27.201.206:8774/v2.1/servers/2820fcfc-3cd2-4a40-8c01-3c9544cfbc59",
              "rel": "self"
            },
            {
              "href": "http://172.27.201.206:8774/servers/2820fcfc-3cd2-4a40-8c01-3c9544cfbc59",
              "rel": "bookmark"
            }
          ],
          "name": "vm1"
        }
      ]
    }
    
  • YAML: HTTP response body in YAML:

    $ oscurl -p /servers --show-mode RESP -f YAML
    HTTP/1.1 200 OK
    Content-Length: 296
    Content-Type: application/json
    Openstack-Api-Version: compute 2.42
    X-Openstack-Nova-Api-Version: 2.42
    Vary: OpenStack-API-Version, X-OpenStack-Nova-API-Version
    X-Compute-Request-Id: req-69d39243-cd55-4ee8-a6cf-9eb7a7e94fad
    Date: Fri, 24 Mar 2017 09:11:18 GMT
    Connection: keep-alive
    
    servers:
    - id: 2820fcfc-3cd2-4a40-8c01-3c9544cfbc59
      links:
      - {href: 'http://172.27.201.206:8774/v2.1/servers/2820fcfc-3cd2-4a40-8c01-3c9544cfbc59',
        rel: self}
      - {href: 'http://172.27.201.206:8774/servers/2820fcfc-3cd2-4a40-8c01-3c9544cfbc59',
        rel: bookmark}
      name: vm1