| commit | af7b7ef49fffaac6fe362d80d5c95d963b7e9799 | [log] [tgz] |
|---|---|---|
| author | Scott Baker <smbaker@gmail.com> | Wed May 22 10:41:18 2019 -0700 |
| committer | Scott Baker <smbaker@gmail.com> | Wed May 22 11:58:58 2019 -0700 |
| tree | 8d825494fbc25c45ced93fb7a527439feb1cc3c3 | |
| parent | 8b8a2b56cf8f61807b49af646d5248ce873ca652 [diff] |
SEBA-687 Add release information. Change-Id: I4cdfe99de9d9c8543830121c3c67452280947985
cordctl is a command-line tool for interacting with XOS. XOS is part of the SEBA NEM and part of CORD, so by extension this tool is useful for interacting with SEBA and CORD deployments. cordctl makes use of gRPC to connect to XOS and may by used for administration of a remote pod, assuming the appropriate firewall rules are configured. Typically XOS exposes its gRPC API on port 30011.
Binaries for cordctl are published at https://github.com/opencord/cordctl/releases and may be directly downloaded and used on Linux, MAC, or Windows platforms.
Additionally, the source for cordctl is available at https://github.com/opencord/cordctl and may be downloaded and built. cordctl is written in golang, and go version 1.12 or above must be installed in order to build from source.
If you would like to contribute to cordctl, the preferred process is to submit patches for code review through gerrit at https://gerrit.opencord.org.
Typically a configuration file should be placed at ~/.cord/config as cordctl will automatically look in that location. Alternatively, the -c command-line option may be used to specify a different config file location. Below is a sample config file:
server: 10.201.101.33:30011 username: admin@opencord.org password: letmein grpc: timeout: 10s
The server, username, and password parameters are essential to configure access to the XOS container running on your pod.
To generate a config file on stdout from the currently configured settings, the command cordctl config may be used.
The -h option can be used at multiple levels to get help, for example:
# Show help for global options cordctl -h # Show help for model-related commands cordctl model -h # Show help for the model list command cordctl model list -h
cordctl supports shell completion for the bash shell. To enable shell Completion you can use the following command on most *nix based system.
source <(cordctl completion bash)
If this does not work on your system, as is the case with the standard bash shell on MacOS, then you can try the following command:
source /dev/stdin <<<"$(cordctl completion bash)"
If you which to make bash shell completion automatic when you login to your account you can append the output of cordctl completion bash to your $HOME/.bashrc:
cordctl completion bash >> $HOME/.bashrc
cordctl has several commands for interacting with models in XOS:
cordctl modeltype list ... list the types of models that XOS supports.cordctl model list <modelName> ... list instances of the given model, with optional filtering.cordctl model update <modelName> <id> --set-json <json> ... update models with new fields.cordctl model delete <modelName> <id> ... delete models.cordctl model create <modelName> --set-json <json> ... create a new model.cordctl model sync <modelName> <id> ... wait for a model to be synchronized.XOS supports a dynamic set of models that may be extended by services that are loaded into XOS. As such the set of models that XOS supports is not necessarily fixed at initial deployment time, but may evolve over the life cycle of an XOS deployment as services are added, removed, or upgraded. The modeltype list command allows you to query the set of model types that XOS supports. For example,
# Query available model types cordctl modeltype list
The basic syntax for listing models (cordctl model list <modelName>) will list all objects of a particular model. Filtering options can be added by using the --filter argument and providing a comma-separated list of filters. If the filters contain characters that the shell would interpret, such as spaces or >, < or ! then you'll need to escape your filter specifier. For example,
# List slices that have id > 10 and controller_kind = Deployment cordctl model list Slice --filter "id>10, controller_kind=Deployment"
Supported operators in the filters include =, !=, >, <, >=, <=.
The model update command is a flexible way to update one or more models. The most basic syntax uses one or more model IDs. For example,
# Update Site 1 and set its site_url to http://www.opencord.org/ cordctl model update Site 1 --set-field site_url=http://www.opencord.org/
Alternatively you may specify a JSON-formatted dictionary. Make sure to properly quote your JSON dictionary when using it as a command line argument. For example,
# Update Site 1 and set its site_url to http://www.opencord.org/ cordctl model update Site 1 --set-json '{"site_url": "http://www.opencord.org/"}'
If you don't know the ID of the object you wish to operate, or if you want to update several objects at the same time that have something in common, then you can use a --filter argument instead of an ID. For example,
# Update all sites named "mysite" and set its site_url to http://www.opencord.org/ cordctl model update Site --filter name=mysite --set-field site_url=http://www.opencord.org/
The syntax for deleting models is similar to that for updating models. You may delete by specifying one of more IDs, or you may delete by using a filter. For example,
# Delete Slice 1 cordctl model delete Slice 1 # Delete the Slice named myslice cordctl model delete Slice --filter name=mylice
The model create command allows you to create new instances of a model in XOS. To do this, specify the type of the model that you want to create and the set of fields that populate it. The set of fields can be set using a name=value syntax or by passing a JSON object. The following two examples are equivalent,
# Create a Site by using set-field cordctl model create Site --set-field name=somesite,abbreviated_name=somesite,login_base=somesite # Create a Site by passing a json object cordctl model create Site --set-json '{"name": "somesite", "abbreviated_name": "somesite", "login_base": "somesite"}'
All XOS operations are by nature asynchronous. When a model instance is created or updated, a synchronizer will typically run at a later time, enacting that model by applying its changes to some external component. After this is complete, the synchronizer updates the timestamps and other metadata to convey that the synchronization is complete.
Asynchronous operations are often inconvenient for test infrastructure, automation scripts, and even human operators. cordctl offers some features for synchronous behavior.
The first is the model sync command that can sync models based on ID or based on a filter. For example,
# Sync based on ID cordctl model sync ONOSApp 17 # Sync based on a field filter cordctl model sync ONOSApp --filter name=olt
The second way to sync an object is to use the --sync command when doing a model create or a model update. For example,
cordctl model create ONOSApp --sync --set-field name=myapp,app_id=org.opencord.myapp
To run unit tests, go-junit-report and gocover-obertura tools must be installed. One way to do this is to install them with go get, and then ensure your GOPATH is part of your PATH (editing your ~/.profile as necessary).
go get -u github.com/jstemmer/go-junit-report go get -u github.com/t-yuki/gocover-cobertura