Aether Operations API

This project defines external APIs to interact with the ROC.

The main goals of this project are:

• expose a stable and expandable API (gRPC, REST, GraphQL)
• support multiple versions of the Aether (and other) models
• provide API documentation

Overview

The external facing API is defined using protobuf which are contained in the ./api folder and a corresponding gRPC server is defined in ./internal/server/grpc/server.go.

The REST and GraphQL implementations are autogenerated using protoc plugins, and their requests are proxied to the gRPC server. The main benefit of this approach is that we are able to expose the same interface over three different transports without increasing the maintenance cost.

The tool that is used to manage the protobuf compilation is called buf, you can read more on the official documentation here

For a more detailed architectural view of the system please refer to this document.

Development

In order to contribute to this project you need to have two external dependencies installed on you system:

• buf
• protoc

Make changes to the protos

Once you have changed the protos you can regenerate everything that is needed via:

make buf graphql

This will generate:

• the go binding for the models
• the gRPC interface
• the REST gateway
• the openapi documentation
• the GraphQL schema
• the GraphQL resolvers and playground

Local setup

It is absolutely possible to run this tool directly from your IDE of choice (or compile it and run it locally) in order to reduce to development cycle.

As of now we only need to access the onos-topo and onos-config APIs, so once you have the aether-roc-umbrella running somewhere you will need to forward those ports on your local machine:

• the onos-config gNMI server on port 5150 (kubectl port-forward svc/onos-config 5150)
• the onos-topo gRPC server on port 5151 (kubectl port-forward svc/onos-topo 5151:5150)

Once those are available you need to provide the correct endpoint via CLI parameters:

./roc-api --onos-config-address localhost:5150 --onos-topo-address localhost:5151

Refer to your IDE documentation to provide those same flags if you want to execute the code from there.

Deployment

An helm-chart is provided to deploy aether-operations-api on your Kubernetes cluster. Since the image is not yet available on DockerHub you need to make it available to your cluster.

You can build and load the image to a Kind cluster with make kind. If you are using a different setup you can build the docker image with make docker-build and load it in you cluster as appropriate.

 helm upgrade --install aether-operations-api ./deployments/aether-operations-api

NOTE the default values for this chart assume that it is deployed in the same namespace as aether-roc-umbrella

If you deploy in a different namespace you can customize the onos-config and onos-topo endpoints with:

helm upgrade --install aether-operations-api ./deployments/aether-operations-api \
  --set aetherOperationsAPI.dataSources.onosConfig=onos-config.<namespace>.svc:5150 \
  --set aetherOperationsAPI.dataSources.onosTopo=onos-topo.<namespace>.svc:5150

For more information on the supported customization refer to the values.yaml file.

TODO

• Bootstrapping of the data