Connecting to the API server¶

Basic auth on localhost:8095¶

$ contrail-api-cli --os-auth-plugin http \\
                   --os-username admin \\
                   --os-password paswword \\
                   --port 8095 \\
                   shell

from contrail_api_cli.client import SessionLoader
from contrail_api_cli.resource import Collection
from contrail_api_cli.context import Context
from contrail_api_cli.schema import DummySchema

session = SessionLoader().make(host="localhost",
                               port=8095,
                               os_username="admin",
                               os_password="password",
                               os_cacert=None,
                               os_cert=None,
                               insecure=False,
                               timeout=1)

Context().session = session
Context().schema = DummySchema()

print(len(Collection('virtual-network')))

Keystone auth on API_SERVER:8082¶

$ contrail-api-cli --os-auth-plugin v2password \\
                   --os-username admin \\
                   --os-password paswword \\
                   --os-tenant-name tenant_name \\
                   --os-auth-url https://keystone:5000/v2.0/ \\
                   shell

Note

All parameters can be set in enviroment variables. For example, –os-auth-plugin looks for $OS_AUTH_PLUGIN.

–port and –host correspond to $CONTRAIL_API_(HOST|PORT)

Base commands¶

All commands provides a –help option.

help¶

List all available commands.

man¶

class contrail_api_cli.commands.man.Man(name)[source]¶

Bases: contrail_api_cli.command.Command

Show command documentation.

To improve the output you can install the rst2ansi package.

ls¶

class contrail_api_cli.commands.ls.Ls(name)[source]¶

Bases: contrail_api_cli.command.Command

List resources and collections.

# list API collections
admin@localhost:/> ls
domain
global-vrouter-config
instance-ip
network-policy
virtual-DNS-record
route-target
loadbalancer-listener
floating-ip
floating-ip-pool
physical-router
[...]

# list collection
admin@localhost:/> ls global-system-config
global-system-config/d6820999-c8fe-45ae-acb2-48aebddb3b7d

# long format
admin@localhost:/> ls -l virtual-network
virtual-network/49d00de8-4351-446f-b6ee-d16dec3de413  default-domain:admin:net2
virtual-network/5a9fbd42-a730-42f7-9947-be8a5d808b70  default-domain:admin:net1
virtual-network/e3148147-164e-4194-8507-a58eefe072bd  default-domain:default-project:default-virtual-network
virtual-network/ba2170ce-741c-4361-ad88-f2d97162faf2  default-domain:default-project:ip-fabric
virtual-network/e82ae164-f78a-4766-8ba2-7cb68dacaecb  default-domain:default-project:__link_local__

# parametrized output format
admin@localhost:/> ls -l -c instance_ip_address instance-ip
instance-ip/f9d25887-2765-4ba0-bf45-54b9dbc5874a  192.168.20.1
instance-ip/deb82100-00bb-4b5c-8495-4bbe34b5fab8  192.168.21.1
instance-ip/2f5c047d-0a9c-4709-bcfa-d710ac68cc22  192.168.10.3
instance-ip/04cb356a-fb1f-44fa-bb2f-d0f0dd4eedfd  192.168.20.3

# filter by parent_uuid
admin@localhost:/> ls -l -p d0afbb0b-dd83-4a33-a673-9cb2b244e804 virtual-network
virtual-network/5a9fbd42-a730-42f7-9947-be8a5d808b70  default-domain:admin:net1
virtual-network/49d00de8-4351-446f-b6ee-d16dec3de413  default-domain:admin:net2

# filter by attribute
admin@localhost:/> ls -l -f instance_ip_address=192.168.20.1 instance-ip
instance-ip/f9d25887-2765-4ba0-bf45-54b9dbc5874a  f9d25887-2765-4ba0-bf45-54b9dbc5874a

du¶

class contrail_api_cli.commands.du.Du(name)[source]¶

Bases: contrail_api_cli.command.Command

Count resources of a collection.

admin@localhost:/> du virtual-network
6

cd¶

class contrail_api_cli.commands.shell.Cd(name)[source]¶

Bases: contrail_api_cli.command.Command

Change current context.

admin@localhost:/> cd virtual-network
admin@localhost:/virtual-network> ls
1095e416-b7cd-4c65-b0a3-631e8263a4dd
49d00de8-4351-446f-b6ee-d16dec3de413
[...]
admin@localhost:/virtual-network> ls instance-ip
No resource found
admin@localhost:/virtual-network> ls /instance-ip
/instance-ip/f9d25887-2765-4ba0-bf45-54b9dbc5874a
/instance-ip/deb82100-00bb-4b5c-8495-4bbe34b5fab8
/instance-ip/2f5c047d-0a9c-4709-bcfa-d710ac68cc22
/instance-ip/04cb356a-fb1f-44fa-bb2f-d0f0dd4eedfd

cat¶

class contrail_api_cli.commands.cat.Cat(name)[source]¶

Bases: contrail_api_cli.command.Command

Print resource details in json format.

admin@localhost:/> cat instance-ip/2f5c047d-0a9c-4709-bcfa-d710ac68cc22
{
  "display_name": "2f5c047d-0a9c-4709-bcfa-d710ac68cc22",
  "fq_name": [
    "2f5c047d-0a9c-4709-bcfa-d710ac68cc22"
  ],
  "href": "http://localhost:8082/instance-ip/2f5c047d-0a9c-4709-bcfa-d710ac68cc22",
  "instance_ip_address": "192.168.10.3",
  "instance_ip_family": "v4",
  "name": "2f5c047d-0a9c-4709-bcfa-d710ac68cc22",
  "subnet_uuid": "96b51c74-090b-4c3e-9f73-ecd8efac294d",
  "uuid": "2f5c047d-0a9c-4709-bcfa-d710ac68cc22",
  [...]
}

tree¶

class contrail_api_cli.commands.tree.Tree(name)[source]¶

Bases: contrail_api_cli.command.Command

Show tree of references of a resource.

# tree of references
admin@localhost:/> tree logical-router/dd954810-d614-4892-9ec6-9a9595cc64ff
/logical-router/dd954810-d614-4892-9ec6-9a9595cc64ff                 default-domain:admin:router1
├── /virtual-machine-interface/18b02f01-4300-427f-a646-0a44351034a6  default-domain:admin:18b02f01-4300-427f-a646-0a44351034a6
│   ├── /routing-instance/2f6907e9-20e7-415a-9969-bb5af375574d       default-domain:admin:net2:net2
│   │   ├── /route-target/721618d4-0861-4bda-8a33-bb116584d4bb       target:64512:8000005
│   │   ├── /route-target/d0e33aea-f63d-403b-a3e7-5bcef88e6053       target:64512:8000003
│   │   └── /route-target/ecd725e8-6523-428b-9811-00828926f91b       target:64512:8000002
│   ├── /virtual-network/49d00de8-4351-446f-b6ee-d16dec3de413        default-domain:admin:net2
│   │   └── /network-ipam/0edc36a1-c802-47be-b230-4b462d905b93       default-domain:default-project:default-network-ipam
│   └── /security-group/8282a986-b9fd-4be1-96bd-ab100bd2bb8e         default-domain:admin:default
├── /virtual-machine-interface/6d9637e5-99ae-4d09-950e-50353b29411c  default-domain:admin:6d9637e5-99ae-4d09-950e-50353b29411c
│   ├── /routing-instance/5692de00-533a-4911-965b-dd9f6dbc6f55       default-domain:admin:net1:net1
│   │   ├── /route-target/79b5278c-a846-49f4-82ab-f1b8c05aff67       target:64512:8000001
│   │   └── /route-target/d0e33aea-f63d-403b-a3e7-5bcef88e6053       target:64512:8000003
│   ├── /virtual-network/5a9fbd42-a730-42f7-9947-be8a5d808b70        default-domain:admin:net1
│   │   └── /network-ipam/0edc36a1-c802-47be-b230-4b462d905b93       default-domain:default-project:default-network-ipam
│   └── /security-group/8282a986-b9fd-4be1-96bd-ab100bd2bb8e         default-domain:admin:default
└── /route-target/d0e33aea-f63d-403b-a3e7-5bcef88e6053               target:64512:8000003

# tree of parents
admin@localhost:/> tree -p routing-instance/5692de00-533a-4911-965b-dd9f6dbc6f55
/routing-instance/5692de00-533a-4911-965b-dd9f6dbc6f55     default-domain:admin:net1:net1
└── /virtual-network/5a9fbd42-a730-42f7-9947-be8a5d808b70  default-domain:admin:net1
    └── /project/d0afbb0b-dd83-4a33-a673-9cb2b244e804      default-domain:admin
        └── /domain/cbc6051f-fd47-4a26-82ee-cb3482926e17   default-domain

rm¶

class contrail_api_cli.commands.rm.Rm(name)[source]¶

Bases: contrail_api_cli.command.Command

Delete a resource from the API.

Warning

-r option can be used to delete recursively back_refs of the resource.

edit¶

class contrail_api_cli.commands.edit.Edit(name)[source]¶

Bases: contrail_api_cli.command.Command

Edit a resource.

The resource JSON will be opened in an editor. If modifications have been made and the file is saved the resource will be sent to the API server.

The –template option can be used to create a new resource based on an existing resource.

schema¶

class contrail_api_cli.commands.schema.Schema(name)[source]¶

Bases: contrail_api_cli.command.Command

View resources links using contrail schema definition.

admin@localhost:/> schema -v 2.21 virtual-network
virtual-network
├── parent
│   └── project
├── children
│   ├── access-control-list
│   ├── routing-instance
│   ├── alias-ip-pool
│   └── floating-ip-pool
├── refs
│   ├── route-table
│   ├── network-policy
│   ├── qos-config
│   └── network-ipam
├── back_refs
│   ├── instance-ip
│   ├── physical-router
│   ├── logical-router
│   └── virtual-machine-interface
└── properties
    ├── import-route-target-list
    ├── export-route-target-list
    ├── provider-properties
    ├── multi-policy-service-chains-enabled
    ├── flood-unknown-unicast
    ├── virtual-network-network-id
    ├── router-external
    ├── virtual-network-properties
    ├── route-target-list
    ├── is-shared
    ├── external-ipam
    ├── id-perms
    ├── perms2
    └── display-name

ln¶

class contrail_api_cli.commands.ln.Ln(name)[source]¶

Bases: contrail_api_cli.command.Command

Add or remove a reference link between two resources.

admin@localhost:/> tree -r /virtual-machine/8cfbddcf-6b55-4cdf-abcb-14eed68e4da7
virtual-machine/8cfbddcf-6b55-4cdf-abcb-14eed68e4da7                default-domain__foo__fa3ea892-3591-4611-ba22-cc45164aee3e__2
├── virtual-machine-interface/d739db3d-b89f-46a4-ae02-97ac796261d0  default-domain:foo:default-domain__foo__fa3ea892-3591-4611-ba22-cc45164aee3e__2__right__1
│   ├── floating-ip/958234f5-4fae-4afd-ae7c-d0dc3c608e06            default-domain:admin:public:floating-ip-pool:958234f5-4fae-4afd-ae7c-d0dc3c608e06
│   └── instance-ip/bced2a04-0ef9-4c87-95a6-7cce54182c65            7d401b8c-b9d3-4be2-af0b-a0dfff500860
└── virtual-router/f6f0b262-745b-45f7-a40a-32ffc1f469bc             default-global-system-config:vrouter-1
admin@localhost:/> ln -r virtual-machine/8cfbddcf-6b55-4cdf-abcb-14eed68e4da7 virtual-router/f6f0b262-745b-45f7-a40a-32ffc1f469bc
admin@localhost:/> tree -r /virtual-machine/8cfbddcf-6b55-4cdf-abcb-14eed68e4da7
virtual-machine/8cfbddcf-6b55-4cdf-abcb-14eed68e4da7                default-domain__foo__fa3ea892-3591-4611-ba22-cc45164aee3e__2
└── virtual-machine-interface/d739db3d-b89f-46a4-ae02-97ac796261d0  default-domain:foo:default-domain__foo__fa3ea892-3591-4611-ba22-cc45164aee3e__2__right__1
    ├── floating-ip/958234f5-4fae-4afd-ae7c-d0dc3c608e06            default-domain:admin:public:floating-ip-pool:958234f5-4fae-4afd-ae7c-d0dc3c608e06
    └── instance-ip/bced2a04-0ef9-4c87-95a6-7cce54182c65            7d401b8c-b9d3-4be2-af0b-a0dfff500860
admin@localhost:/> ln virtual-machine/8cfbddcf-6b55-4cdf-abcb-14eed68e4da7 virtual-router/f6f0b262-745b-45f7-a40a-32ffc1f469bc
admin@localhost:/> tree -r /virtual-machine/8cfbddcf-6b55-4cdf-abcb-14eed68e4da7
virtual-machine/8cfbddcf-6b55-4cdf-abcb-14eed68e4da7                default-domain__foo__fa3ea892-3591-4611-ba22-cc45164aee3e__2
├── virtual-machine-interface/d739db3d-b89f-46a4-ae02-97ac796261d0  default-domain:foo:default-domain__foo__fa3ea892-3591-4611-ba22-cc45164aee3e__2__right__1
│   ├── floating-ip/958234f5-4fae-4afd-ae7c-d0dc3c608e06            default-domain:admin:public:floating-ip-pool:958234f5-4fae-4afd-ae7c-d0dc3c608e06
│   └── instance-ip/bced2a04-0ef9-4c87-95a6-7cce54182c65            7d401b8c-b9d3-4be2-af0b-a0dfff500860
└── virtual-router/f6f0b262-745b-45f7-a40a-32ffc1f469bc             default-global-system-config:vrouter-1

relative¶

class contrail_api_cli.commands.relative.Relative(name)[source]¶

Bases: contrail_api_cli.command.Command

Find linked resource using a resource-type path.

admin@localhost:/> relative virtual-machine/8cfbddcf-6b55-4cdf-abcb-14eed68e4da7 virtual-machine-interface/floating-ip
floating-ip/958234f5-4fae-4afd-ae7c-d0dc3c608e06
admin@localhost:/> relative -l virtual-machine/8cfbddcf-6b55-4cdf-abcb-14eed68e4da7 virtual-machine-interface/floating-ip
base      virtual-machine/8cfbddcf-6b55-4cdf-abcb-14eed68e4da7
back_ref  virtual-machine-interface/d739db3d-b89f-46a4-ae02-97ac796261d0
back_ref  floating-ip/958234f5-4fae-4afd-ae7c-d0dc3c608e06

The resource path can contain selectors:

admin@localhost:/> relative logical-router/6f71ab62-d831-4a10-807c-975e23dcc3d8 service-instance/virtual-machine/virtual-machine-interface[virtual_machine_interface_properties.service_interface_type=right]/instance-ip
instance-ip/ea329dca-e30e-42eb-93a3-86325a34a525
admin@localhost:/> cat instance-ip/ea329dca-e30e-42eb-93a3-86325a34a525 | jq .instance_ip_address
"172.24.4.3"

This will get the SNAT public IP of a logical router.

kv¶

class contrail_api_cli.commands.kv.Kv(name)[source]¶

Bases: contrail_api_cli.command.Command

Command to interact with the key-value store.

admin@localhost:/> kv --add my-key my-value
admin@localhost:/> kv --get my-key
[
  {
    "key": "my-key",
    "value": "my-value"
  }
]

admin@localhost:/> kv --delete my-key
admin@localhost:/> kv --get my-key
Unknown User-Agent key my-key (HTTP 404)

Advanced usage¶

pipes¶

Any command can be piped to any program installed on the system inside the cli shell.

admin@localhost:/virtual-network> cat 1095e416-b7cd-4c65-b0a3-631e8263a4dd | grep dns
"dns_nameservers": [],
            "dns_server_address": "192.168.21.2",
admin@localhost:/virtual-network> cat 1095e416-b7cd-4c65-b0a3-631e8263a4dd | jq '.network_ipam_refs[].attr.ipam_subnets[].dns_server_address'
"192.168.21.2"

direct-call¶

You can call command directly from bash and pipe or redirect output as you wish.

$ contrail-api-cli ls /virtual-network
virtual-network/1095e416-b7cd-4c65-b0a3-631e8263a4dd
virtual-network/49d00de8-4351-446f-b6ee-d16dec3de413
virtual-network/5a9fbd42-a730-42f7-9947-be8a5d808b70
virtual-network/e3148147-164e-4194-8507-a58eefe072bd
virtual-network/ba2170ce-741c-4361-ad88-f2d97162faf2
virtual-network/e82ae164-f78a-4766-8ba2-7cb68dacaecb

wildcard resolution¶

The wildcards * and ? can be used in paths. All matching resources will be resolved.

Warning

Note that this does filtering on the cli side and not on the API side.

admin@localhost:/> ls -l virtual-network/default-domain:admin:*
virtual-network/49d00de8-4351-446f-b6ee-d16dec3de413  default-domain:admin:net2
virtual-network/5a9fbd42-a730-42f7-9947-be8a5d808b70  default-domain:admin:net1

loading commands from other namespaces¶

Say you have a collection of commands in the contrail_api_cli.mycommands entrypoint, run:

$ contrail_api_cli --ns contrail_api_cli.mycommands shell

The namespace contrail_api_cli.mycommands commands will be loaded as well as the commands of the default contrail_api_cli.command namespace.

python from the shell¶

You can directly use contrail-api-cli API in a python console that can be run with the python command. If ptpython [1] or IPython [2] are installed they will be used instead of the standard python repl.

admin@localhost:/> python
>>> c = Collection('virtual-network', fetch=True)

>>> for vn in c:
...     print(vn.uuid)
0287b4d1-3aea-4a82-b1be-be524995d1a8
73fc0e08-b542-483e-86e7-f4a5aad2750f
bf91b645-f7aa-4ab3-88cf-dc7a6358c08c
a3694461-c4e0-4f54-a6fa-a11ae0472e04
6afc9f77-607f-424c-8188-996c9513467a

python script execution¶

The exec command can be used to run a python script that is using the contrail_api_cli API. This avoids the need to setup the connection to the API server inside the script since the script will be run in the context of the cli.

$ contrail-api-cli exec my_script.py

[1]	https://github.com/jonathanslenders/ptpython

[2]	https://ipython.org/

Connecting to the API server¶

Basic auth on localhost:8095¶

Keystone auth on API_SERVER:8082¶

Base commands¶

help¶

man¶

ls¶

du¶

cd¶

cat¶

tree¶

rm¶

edit¶

schema¶

ln¶

relative¶

kv¶

Advanced usage¶

pipes¶

direct-call¶

wildcard resolution¶

loading commands from other namespaces¶

python from the shell¶

python script execution¶

Table of Contents

Previous topic

Next topic

This Page