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 back / childs references
localhost:/> tree service-instance/f8e191c5-83fa-47f1-a242-e8ad7cab46c0
service-instance/f8e191c5-83fa-47f1-a242-e8ad7cab46c0                     default-domain:project:a2fb6399-18ce-44ec-839d-d373221a6a8f
├── loadbalancer/a2fb6399-18ce-44ec-839d-d373221a6a8f                     default-domain:project:lbv2
│   └── loadbalancer-listener/434b7b92-b68a-41f6-8321-8e7e2519d483        default-domain:project:lbv2_listener
│       └── loadbalancer-pool/82cce54d-b13a-427c-bac6-fb7e976bcf5f        default-domain:project:lbv2_pool
│           ├── loadbalancer-member/cc6e4c32-92c1-4668-879d-d6802f8ad3de  default-domain:project:lbv2_pool:cc6e4c32-92c1-4668-879d-d6802f8ad3de
│           └── loadbalancer-member/fb30633f-407b-461d-bf20-3ac9f0cbe504  default-domain:project:lbv2_pool:fb30633f-407b-461d-bf20-3ac9f0cbe504
├── virtual-machine/68243a56-298d-4354-a077-b41b6bb55b7c                  default-domain__project__a2fb6399-18ce-44ec-839d-d373221a6a8f__1
│   └── virtual-machine-interface/4a0bf808-19d7-48e9-b076-54064bebaf2e    default-domain:project:default-domain__project__a2fb6399-18ce-44ec-839d-d373221a6a8f__1__right__1
│       └── instance-ip/44a9dc2a-446f-4d34-9148-4a2cc1f9a6f7              default-domain__project__a2fb6399-18ce-44ec-839d-d373221a6a8f-right
└── virtual-machine/114be9ed-ac45-4dc8-9f45-559470037cfd                  default-domain__project__a2fb6399-18ce-44ec-839d-d373221a6a8f__2
    └── virtual-machine-interface/43afc4fe-8a84-47ba-96d9-73a8dd1d6b63    default-domain:project:default-domain__project__a2fb6399-18ce-44ec-839d-d373221a6a8f__2__right__1
        └── instance-ip/44a9dc2a-446f-4d34-9148-4a2cc1f9a6f7              default-domain__project__a2fb6399-18ce-44ec-839d-d373221a6a8f-right

# tree of parents / references
admin@localhost:/> tree -r routing-instance/f792b52d-ff69-487e-b2a5-c13060e3ce77
routing-instance/f792b52d-ff69-487e-b2a5-c13060e3ce77        default-domain:project:test1:test1
├── route-target/7454c39a-b3c7-4d42-b766-bd276710d0b1        target:64518:8000133
└── virtual-network/ce88182e-4e6e-4c61-9df1-7ffb24543578     default-domain:project:test1
    ├── network-ipam/d6bdafea-58d2-4240-8c65-2acf837d6750    default-domain:default-project:default-network-ipam
    │   └── project/acb58362-0272-4d27-97a1-da4ac1e2c5e3     default-domain:default-project
    │       └── domain/ff62f8f7-cccd-4a30-ba32-2ee3764fac79  default-domain
    └── project/0ed483e0-83ef-4f70-8250-1fcfa5d98c0e         default-domain:project
        └── domain/ff62f8f7-cccd-4a30-ba32-2ee3764fac79      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