commit | 3d8cd985ae2dca2b308bb53050b206aafd160f34 | [log] [tgz] |
---|---|---|
author | Scott Baker <smbaker@gmail.com> | Fri Jun 28 08:26:01 2019 -0700 |
committer | Scott Baker <smbaker@gmail.com> | Fri Jun 28 08:26:01 2019 -0700 |
tree | afb5fd07a6fa6b4e23a456a301459c5c95c99064 | |
parent | a55e6451fca31a48c0f53563270f483afe78ce29 [diff] |
SEBA-748 Release cordctl Change-Id: I9d59c708732505ae60a4e79cf874fd2b9a382b4b
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.cordctl model setdirty <modelName> <id>
... set a model dirty so it will 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 core also permits models to be filtered based on state, and the --state
argument can be used to filter based on a state. States include all
, dirty
, deleted
, dirtypol
, and deletedpol
. default
is a synonym for all
. For example,
# List deleted ONOSApps cordctl model list ONOSApp --state deleted
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
XOS determines when a model is dirty by comparing timestamps. Each model has an updated
timestamp that indicates the last time the model was updated. If this timestamp is newer than the enacted
or policed
timestamps then sync steps or policies will be run respectively. There is no direct way to modify the updated
timestamp via the API since timestamps are managed by the XOS
core. cordctl
provides the setdirty
command to cause models to be dirtied without altering the other fields of the model. When setdirty
is used, the updated
timestamp will be set to the current time. The setdirty
command may be used with either an ID or a filter or the --all
flag.
# Set model dirty based on ID cordctl model setdirty ONOSApp 17 # Set model dirty based on a field filter cordctl model setdirty ONOSApp --filter name=olt # Set all ONOSApp models dirty cordctl model setdirty ONOSApp --all
If you wish to query which models are dirty (for example, to verify that a previous setdirty
worked as expected) then the --state dirty
argument may be applied to the model list
command. For example,
# Get a list of dirty ONOS Apps cordctl model list ONOSApp --state dirty
Note: Not all models have syncsteps or policies implemented for them. Some models may implicitly cause related models to become dirty. For example, dirtying the head of a service instance chain may cause the whole chain to be dirtied. This behavior is dependent on the model. For models that do not implement syncsteps or policies and do not have the side-effect of dirtying related models, the
setdirty
command has no practical value, and the models may remain in perpetual dirty state.
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